From ff5868bdab73acfbe6dd0dd8dccd6806c2a4ba55 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Wed, 6 May 2026 09:52:10 -0400 Subject: [PATCH] docs(db/m7-coverage-gauge): note CHECK-constraint sync + bucket invariant MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Code-review polish on GetAlbumCoverageRollup's comment block: - Records the invariant that with_art + pending + settled = total (and that pending_no_mbid is a subset of pending, not a fourth bucket). - Notes that the IN ('sidecar','embedded','mbcaa') list must stay in sync with the cover_art_source CHECK constraint in migration 0016 — without this note a future source addition could silently undercount with_art. --- internal/db/dbq/albums.sql.go | 8 ++++++++ internal/db/queries/albums.sql | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/internal/db/dbq/albums.sql.go b/internal/db/dbq/albums.sql.go index 37c4a3a7..e1772aa4 100644 --- a/internal/db/dbq/albums.sql.go +++ b/internal/db/dbq/albums.sql.go @@ -145,6 +145,14 @@ type GetAlbumCoverageRollupRow struct { // of pending; the UI surfaces it separately so operators can see how // many "pending" albums are blocked on missing MBID and won't be // helped by another scan. +// +// Invariant: with_art + pending + settled = total. (pending_no_mbid is +// not part of the sum — it's a subset of pending, surfaced separately.) +// +// The IN list below ('sidecar','embedded','mbcaa') must stay in sync +// with the cover_art_source CHECK constraint in migration +// 0016_album_cover_source.up.sql. If a new source value is added there +// without updating this query, with_art will silently undercount. func (q *Queries) GetAlbumCoverageRollup(ctx context.Context) (GetAlbumCoverageRollupRow, error) { row := q.db.QueryRow(ctx, getAlbumCoverageRollup) var i GetAlbumCoverageRollupRow diff --git a/internal/db/queries/albums.sql b/internal/db/queries/albums.sql index 0716205b..27930f3c 100644 --- a/internal/db/queries/albums.sql +++ b/internal/db/queries/albums.sql @@ -132,6 +132,14 @@ SELECT a.id AS album_id, -- of pending; the UI surfaces it separately so operators can see how -- many "pending" albums are blocked on missing MBID and won't be -- helped by another scan. +-- +-- Invariant: with_art + pending + settled = total. (pending_no_mbid is +-- not part of the sum — it's a subset of pending, surfaced separately.) +-- +-- The IN list below ('sidecar','embedded','mbcaa') must stay in sync +-- with the cover_art_source CHECK constraint in migration +-- 0016_album_cover_source.up.sql. If a new source value is added there +-- without updating this query, with_art will silently undercount. SELECT COUNT(*) AS total, COUNT(*) FILTER (WHERE cover_art_source IN ('sidecar','embedded','mbcaa')) AS with_art,