Files
yellowjacket/backend/database/sql/sqlcgen/models.go
T
yonluandClaude Opus 5 e7748f1fd5
CI / check (push) Successful in 3m7s
CI / e2e (push) Canceled after 1m45s
feat(database): shape the library like files, and shrink the catalog
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
2026-08-16 13:58:15 -04:00

399 lines
7.9 KiB
Go

// Code generated by sqlc. DO NOT EDIT.
// versions:
// sqlc v1.30.0
package sqlcgen
import (
"database/sql"
"time"
)
type Album struct {
ID int64
Name string
ArtistCredit string
ArtistID sql.NullInt64
Mbid sql.NullString
Year sql.NullInt64
OriginalYear sql.NullInt64
CoverArtID sql.NullInt64
PendingReleaseMbid sql.NullString
}
type Artist struct {
ID int64
Name string
Mbid sql.NullString
}
type ArtistEnrichment struct {
ArtistMbid string
BrowsedAt sql.NullTime
SimilarAt sql.NullTime
}
type ArtistImage struct {
ID int64
ArtistMbid string
Source string
SourceUrl string
FilePath string
IsPrimary int64
SortOrder int64
Width sql.NullInt64
Height sql.NullInt64
FileSize sql.NullInt64
CreatedAt time.Time
}
type ArtistMetadatum struct {
Mbid string
Source string
Data []byte
FetchedAt time.Time
}
type AudioFile struct {
ID int64
FilePath string
LibraryID int64
FileTypeID int64
LengthMilliseconds int64
SampleRate int64
BitDepth int64
Channels int64
Bitrate int64
FileSize int64
Title string
ArtistCredit string
ArtistID sql.NullInt64
AlbumID sql.NullInt64
TrackNumber sql.NullInt64
DiscNumber sql.NullInt64
TotalTracks sql.NullInt64
Year sql.NullInt64
Composer string
Comment string
RecordingMbid sql.NullString
Basename string
GroupKey string
ModifiedAt int64
PlayCount int64
LastPlayed sql.NullTime
TagStatus string
}
type CoverArt struct {
ID int64
IsEmbedded bool
FilePath string
MimeType string
}
type DownloadDownload struct {
ID string
LibraryID int64
Source string
RequestID sql.NullInt64
ReleaseMbid sql.NullString
ReleaseGroupMbid sql.NullString
RecordingMbid sql.NullString
Artist string
Album string
Query string
Expected string
State string
Error string
CreatedAt time.Time
UpdatedAt time.Time
}
type DownloadItem struct {
ID string
DownloadID string
ProviderID int64
TransportID sql.NullInt64
ExternalID string
Candidate string
State string
StagingDir string
BytesDone int64
BytesTotal int64
ImportedPaths string
Error string
CreatedAt time.Time
UpdatedAt time.Time
}
type DownloadProvider struct {
ID int64
Kind string
Name string
Enabled int64
Priority int64
Settings string
CreatedAt time.Time
}
type DownloadRequest struct {
ID int64
Mbid string
Entity string
LibraryID int64
Artist string
Title string
Scope string
Secondary int64
State string
ParentID sql.NullInt64
Attempts int64
LastError string
LastTriedAt sql.NullTime
NextTryAt sql.NullTime
ExternalIds string
CreatedAt time.Time
UpdatedAt time.Time
}
type ExcludedPath struct {
ID int64
LibraryID int64
FilePath string
ExcludedAt time.Time
}
type ExploreChampionFt struct {
Title string
ArtistName string
Aliases string
}
type ExploreIndex struct {
ID int64
EntityType int64
Mbid []byte
Title string
ArtistName string
ArtistMbid []byte
Aliases string
Popularity int64
ListenerCount int64
Duration int64
CaaReleaseMbid []byte
ReleaseName string
PrimaryType string
SecondaryTypes string
ReleaseDate string
TotalTracks int64
ArtistType string
Country string
Disambiguation string
SortName string
InLibrary int64
IsSimilar int64
LocalArtistID sql.NullInt64
LocalReleaseGroupID sql.NullInt64
LocalRecordingID sql.NullInt64
DiscogFetched int64
}
type ExploreIndexFt struct {
Title string
ArtistName string
Aliases string
}
type ExploreIndexMetum struct {
Key string
Value string
}
type FileGenre struct {
AudioFileID int64
GenreID int64
}
type FileType struct {
ID int64
Extension string
}
type Genre struct {
ID int64
Name string
}
type HttpCache struct {
UrlKey string
Response []byte
ExpiresAt time.Time
EntityMbid string
EntityType string
}
type JobState struct {
ID string
Kind string
Title string
Subtitle string
PausedAt string
}
type Library struct {
ID int64
Name string
Path string
CreatedAt time.Time
AutotagWarningAcked int64
}
type Lyric struct {
AudioFileID int64
Text string
Source string
RecordingMbid sql.NullString
FetchedAt time.Time
}
type LyricsIndex struct {
Lyrics string
}
type PlayHistory struct {
ID int64
AudioFileID int64
PlayedAt time.Time
}
type PlayerState struct {
ID int64
Volume int64
Muted bool
LastTrackPath string
LastPositionSeconds int64
}
type Playlist struct {
ID int64
Name string
IsSmart int64
SmartRules sql.NullString
SmartSnapshotAt sql.NullTime
CreatedAt time.Time
UpdatedAt time.Time
}
type PlaylistTrack struct {
ID int64
PlaylistID int64
AudioFileID sql.NullInt64
Position int64
PhantomTitle sql.NullString
PhantomArtist sql.NullString
PhantomAlbum sql.NullString
PhantomDurationMs sql.NullInt64
PhantomGenre sql.NullString
PhantomCoverArtPath sql.NullString
PhantomFilePath sql.NullString
}
type Queue struct {
ID int64
SourcePlaylistID sql.NullInt64
CurrentPosition int64
ShuffleMode bool
RepeatMode string
ShuffleOrder sql.NullString
SourceType string
SourceID int64
SourceLabel string
}
type QueueTrack struct {
ID int64
AudioFileID int64
Position int64
}
type ReleaseToRg struct {
ReleaseMbid string
RgMbid string
}
type SearchClick struct {
Query string
EntityMbid string
EntityType string
ClickCount int64
LastClicked time.Time
}
type SearchIndex struct {
FilePath string
Title string
Artist string
Album string
}
type SimilarArtistMap struct {
SourceArtistMbid string
SimilarArtistMbid string
SimilarArtistName string
Score int64
}
type TaggingCandidate struct {
GroupKey string
Candidates string
ComputedAt time.Time
}
type TaggingItem struct {
GroupKey string
LibraryID int64
TrackCount int64
AlbumName string
AlbumArtist string
DiscNumber int64
BestMatchReleaseMbid sql.NullString
Score sql.NullFloat64
LastCheckedAt sql.NullTime
Status string
ClearedAt sql.NullTime
CreatedAt time.Time
Synthetic int64
ParentGroupKey string
AlbumArtistConflict int64
}
type TrackMetadatum struct {
ID int64
FilePath string
LengthMilliseconds int64
Title string
ArtistName string
TrackNumber sql.NullInt64
DiscNumber sql.NullInt64
Album string
Genre string
Year int64
ReleaseYear int64
Composer string
FileType string
SampleRate int64
BitDepth int64
Channels int64
Bitrate int64
FileSize int64
LibraryID int64
PlayCount int64
LastPlayed sql.NullTime
CoverArtPath string
ArtistMbid string
ReleaseGroupMbid string
RecordingMbid string
AlbumID sql.NullInt64
ArtistID sql.NullInt64
}