yonluandClaude Opus 5
e7748f1fd5
Plans 013 and 014, the album page that prompted them, and the smaller fixes they turned up. Changelog, largest first. ## The local library is shaped like files, not like MusicBrainz `audio_files` carries its own tags and points at `albums` and `artists`; `file_genres` is the one real many-to-many. `recordings`, `release_group_recordings`, `artist_credit`, `artist_credit_artist`, `recording_genres`, `release_groups` and `release_to_rg` are gone from the local side, and with them a six-way join in every read, a `MIN(release_group_id)` subquery in eleven queries and a first-credited-artist subquery in nine. Measured on a real 25,966-file library, every many-to-many that model expressed was 1:1 in the data. - Ownership is a file. `GetFilePathsByRecordingMBIDs`, `LibraryMBIDIndex.CheckMBIDs`, `collectLibraryEntities` and `pruneStaleLocalCrossReferences` all join `audio_files`, so the 812 orphaned recordings, 216 release groups and 260 artists that library carried are now structurally impossible. - One projection: every track query selects from the `track_metadata` view, one row type, one mapper. Nine hand-rolled copies had drifted far enough to report different years on different screens. - `library_id = 0` means every library, so each list query exists once instead of scoped and unscoped with a branch at every call site. - No migration chain. `sql/schemas/` is the one description of the shape; `sql/migrations/`, `applyMigrations` and `schema_migrations` are squashed away, along with the drift between them that had sqlc generating against a stale schema. - `database.InsertTestTrack` is the one test seeder; twenty test files had been assembling the old FK chain each in its own order. ## The catalog stores its ids as bytes `explore_index`'s three 36-char MBID columns and its entity-type text are 16 raw bytes and a small integer. The table and its six indexes go 780 MB to 405 MB on a real 2,052,200-row catalog, which is why a fresh install is ~0.6 GB rather than ~1.0 GB. - `backend/explore/mbid.go` is the only place the encoding is known; everything above it speaks dashed strings. - `CHECK(length(mbid) = 16)` makes a stringly write fail at the insert rather than silently returning no rows, since SQLite does not coerce between TEXT and BLOB. - The importer asks the artifact what encoding it carries and converts on the way in, so the artifact already published keeps working and no format bump is needed. - `indexRowColumns`/`scanIndexRow` replace four copies of a 22-column list, and `TestStoredEncodingRoundTrips` sweeps every read path. ## An album page that says how much of the album is yours - One question, asked once: is there a file. `filePaths` is filled by a single batched lookup when the tracklist settles, and the badge, the Play count, the dimmed rows and every menu item read it — replacing four claims of decreasing confidence that could show a green tick on an album whose every action did nothing. - Play, Play 7 of 12, or no play button at all. - `total_tracks` on `explore_index` (~2 bytes over 400,677 release groups) and on `audio_files` from tags that have always carried it: a complete MBID-matched album now makes no catalog call at all, where it used to spend the most expensive request the app makes. - A merged cluster shows the running order the most releases agree on, and the version list marks the release you own rather than standing a synthetic entry in for it. - `AlbumReleasesFailed`: a slow fetch is no longer reported as a failed one by a 12-second timer. - Rows not in the library are dimmed in place (with `aria-disabled`) instead of the owned ones wearing a green tick and a legend. ## Caches and cover art get ceilings - Only the three tiers of a cover are stored; the full-resolution copy nothing rendered was 1,134 MB of a 1.4 GB covers directory. - One artist portrait is downloaded and the rest are remembered as URLs — 4.1 GB of a 5.3 GB cache was candidates no code path reads. - `browsedArtBudget` and `httpCacheBudget` bound what an age cannot: the same install held art for 5,770 artists in a 1,301-artist library. - `OrphanedArtistImagesJob` joined a bare MBID onto a sharded directory, so it deleted the rows that were the only record of the files it left behind. `explore.ArtistImageDir` is that layout's one definition now. ## The autotag queue asks whether there is work `tagging_items` was a row per album folder, not a queue, and no query read the `tag_status` column that held the answer. The four queue queries ask the files, which matters most where it is least visible: `startPrefetch` was scoring every album in a tagged library against MusicBrainz. ## Phantom playlist tracks resolve in place An M3U8 imported before its files leaves phantom rows; they now match by path and fall back to position, keep their place in the playlist when resolved, and pair best-first so two phantoms cannot claim the same file. ## Playing a track plays the list it is in Double-click, and Play on a single row's menu, queue the list as displayed with `startIndex` on that row — the album page and the track list used to queue one track and discard the album around it. A multi-row selection still plays exactly itself. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AfVYUVExXsx1nSWrXN8mAh
3.7 KiB
Changing the database schema
The reasoning — why the local library is shaped like files rather than
like MusicBrainz, and what the metadata tables cost before they went —
is in CLAUDE.md under Backend packages → database. Read it once.
This is the checklist.
There is one description of the schema and no migration chain.
sql/schemas/*.sql declares the current shape; applySchema runs every
file on every open, and CREATE ... IF NOT EXISTS makes that idempotent.
sql/migrations/, applyMigrations and schema_migrations were
squashed away with plan 013. So:
Adding a table or a column is one edit to one file.
make generate # sqlc + templ
go test ./backend/database/ ./backend/datamap/
make test
A new table has a second gate: backend/datamap. Add an entry
stating its Kind and Lifetime, or TestCatalogCoversSchema fails — and
if it is Authored and cascades, TestAuthoredCascadesAreDeliberate
wants an explicit exemption with a note, because authored data is what a
user cannot get back. If a column holds a different Kind from its
table (an authored flag on an owned projection, a fetched value beside a
tag-derived one), say so in the entry's note; audio_files and lyrics
are the worked examples.
Existing databases are not migrated. Nothing upgrades a database
from an older shape — delete your dev YJ_HOME and rescan, and rebuild
any seed you rely on (make sandbox-seed NAME=default). Revisit this
once real user databases exist in the wild.
A stale one fails at the first query, not at open, which is worth
knowing before you read the error. applySchema is
CREATE TABLE IF NOT EXISTS, so an old database keeps its old columns
and gains nothing; the app then starts fine and dies on
no such column: title. Every tier that does not run the app — unit
tests, make ui-test, tsc — is green while this is true, because
they build their database from the current schema. make e2e and
make dev are the two that will tell you, and only after the seed has
been rebuilt.
The four ways this goes wrong
- A query file must be ASCII. sqlc's parameter rewriter works on
byte offsets, so a single non-ASCII character in a query comment
(an em dash, a curly quote) shifts every placeholder and generates
garbage like
SELECid— a parse error a long way from its cause. Schema files are not rewritten and may contain anything. - A slice and a named parameter do not compose.
sqlc.sliceexpands to N placeholders, butsqlc.argis numbered independently, so the two in one query bind the wrong values —GetFilePathsByAlbums([1,2], 0)read album id 2 as the library id. Where a query needs both, return the column and filter in Go. - A write wearing a query's shape still needs the writer.
QueryContext/QueryRowroute to the query-only read pool, so anINSERT ... RETURNINGthrough one fails at runtime with "attempt to write a readonly database (8)". UseExecContext, orQueryRowWriter.TestNoWritesOnTheReadPoolwalks the tree for it. - A view is dropped and recreated.
CREATE VIEW IF NOT EXISTSno-ops against a database holding the old definition, sotrack_metadata.sqlopens withDROP VIEW IF EXISTS.
Where things go
New queries go in backend/database/sql/queries/; generated Go lands in
backend/database/sql/sqlcgen/, which is never edited by hand. Anything
returning a track selects from the track_metadata view rather than
re-joining — that is why there is one row type and one mapper.
Tests use database.NewTestDB(t), built by the same applySchema
production uses, and seed rows with database.InsertTestTrack(t, db, database.TestTrack{...}) rather than assembling inserts by hand.