urban/WCX
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update reference database contract for project split

Browse Source
This commit is contained in:
Urban
2026-07-19 18:25:57 +02:00
parent 19af3c8cc2
commit 717750a36b
1 changed files with 24 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/reference-database-read-contract.md
View File

@ -1,17 +1,17 @@
# Read contract for the WCX reference database # Producer contract for read access to the WCX reference database
## Purpose and ownership ## Purpose and ownership
This document defines the current SQLite read contract used by This document defines the SQLite read contract that this reference-data
`scripts/match_filenames.py` when matching local video filenames against the project provides to the external file-management repository
WCX reference database. The contract identifies the database objects that the `/storage/disk1/WCX-collection`. The contract identifies the database objects
file-management code depends on and the compatibility boundary that the that WCX-collection depends on and the compatibility boundary that this
reference-data project must preserve. producer must preserve.
The reference-data project owns the database schema, canonical metadata, This reference-data project owns the database schema and all reference data,
history, and aliases. It is the sole writer to the reference database. including canonical metadata, history, and aliases. It is the sole writer to
File-management code is a consumer only and must open the database through a the reference database. WCX-collection is an external read-only consumer and
SQLite URI with `mode=ro` and `uri=True`. must open the database through a SQLite URI with `mode=ro` and `uri=True`.
Local file paths, local processing state, matching decisions, and collection Local file paths, local processing state, matching decisions, and collection
state are outside this contract and must not be written to the reference state are outside this contract and must not be written to the reference
@ -19,8 +19,9 @@ database.
## Connection contract ## Connection contract
`scripts/match_filenames.py` resolves the configured database path, converts The consumer in `/storage/disk1/WCX-collection` resolves the configured
it to a file URI, appends `?mode=ro`, and opens it as follows: database path, converts it to a file URI, appends `?mode=ro`, and opens it as
follows:
```python ```python
database_uri = f"{database_file.resolve().as_uri()}?mode=ro" database_uri = f"{database_file.resolve().as_uri()}?mode=ro"
@ -42,7 +43,7 @@ The current contract contains exactly three tables and ten selected columns:
| `movie_name_alias` | `movie_id`, `alias`, `normalized_alias`, `source` | | `movie_name_alias` | `movie_id`, `alias`, `normalized_alias`, `source` |
| `movie_history` | `movie_id`, `duration_seconds`, `archived_at` | | `movie_history` | `movie_id`, `duration_seconds`, `archived_at` |
No other table or column is read by `load_movies()`. No other table or column is read by WCX-collection's current database loader.
### Column meanings for matching ### Column meanings for matching
@ -66,7 +67,8 @@ must therefore refer to `movie.id`, never to a name as an identifier.
## SQL queries ## SQL queries
The current implementation executes exactly these three queries. The current WCX-collection implementation executes exactly these three
queries.
### Current movies ### Current movies
@ -138,12 +140,14 @@ historical durations are also compatible with the current query contract.
## Process for contract changes ## Process for contract changes
Before the reference-data project makes an incompatible change: As producer and schema owner, the reference-data project is responsible for
preserving this contract. Before it makes an incompatible change:
1. Identify the affected table, column, value semantics, or relationship and 1. Identify the affected table, column, value semantics, or relationship and
document the proposed replacement. document the proposed replacement.
2. Update the file-management consumer to support the new contract, preferably 2. Coordinate with WCX-collection and update the consumer to support the new
with a transition period in which it can read both forms. contract, preferably with a transition period in which it can read both
forms.
3. Create a disposable database containing representative current names, 3. Create a disposable database containing representative current names,
aliases, current durations, and historical durations under the proposed aliases, current durations, and historical durations under the proposed
schema. schema.
@ -155,5 +159,6 @@ Before the reference-data project makes an incompatible change:
7. Remove the old contract only after both projects explicitly agree that no 7. Remove the old contract only after both projects explicitly agree that no
active consumer depends on it. active consumer depends on it.
The projects must coordinate any incompatible change; the reference-data The reference-data project must not deploy an incompatible schema or semantic
project must not silently break or reinterpret the documented read contract. change until a compatible WCX-collection version is available. It must not
silently break or reinterpret the documented read contract.