docs(db): Generate the schema, and move its rationale into the schema

[bitbiter-dev]

Why

The hand-written description of the database had drifted, and nothing could tell:

• Invite was missing from the ER diagram entirely — an entire table, in both the wiki's copy and a separate documentation repository's copy
• Columns were named in snake_case throughout; the model has only ever emitted PascalCase. The one explicitly-named column in the whole schema is Invites.xmin
• live_photo_pair_id does not exist — the column is PairedAssetId
• Metadata was documented as carrying a colour space. There is no such column
• ProxyFile was documented as having a blurhash string. There is no such column — BlurHash is a ProxyType value whose content is a file
• The unique index on (StorageConfigId, FilePath) appeared in no document at all

None of that was undocumented. It was duplicated — restated by hand while the authoritative copy sat in AnichronDbContextModelSnapshot.cs, committed and diffed in every PR. The copy rotted because nothing compared it to anything.

What changed

Three layers, none of them hand-written prose about columns:

Layer	Source	Committed?
Facts	dotnet ef dbcontext script → docs/schema.sql	yes, CI-gated
Rationale	.HasComment(...) → COMMENT ON in the DDL	yes, via the model
Navigable view	tbls against a throwaway database	no — CI artefact

scripts/derive-db-docs.sh calls a tool; it renders nothing itself. --check is the CI gate.

Rationale now lives in the schema

COMMENT ON COLUMN "MediaAssets"."ContentHash" IS 'XXHash64 of the file contents.
Dedup is deliberately CONFIG-SCOPED: the same bytes under two storage configs are
two assets, which is what makes multi-user work. A global unique index on this
column alone would break that and must never be added.';

24 such comments. They travel into PostgreSQL, so any schema-doc tool pointed at a live instance picks them up. There is no separate prose file left to drift.

What was deleted, and why it mattered

A first attempt generated Markdown from the EF model in ~200 lines of C# with a test asserting the committed file matched. It worked. It was still wrong: a third copy of the same facts, and a bespoke renderer to own forever, in a space where mature tools exist.

Do not hand-build a layer a maintained tool already covers, and do not restate a fact version control already holds.

Trade-offs, stated plainly

• ⚠️ A one-word comment fix is now a migration, not a text edit. That is the price of putting rationale in the schema. AddSchemaComments is 48 comment alterations and zero structural statements, so it carries no data risk.
• ⚠️ EF exposes no HasComment for an index, so index reasoning stays in code comments and does not reach the database.
• ⚠️ We give up a browsable schema document in the repository. Deliberate: a committed human-readable copy is exactly the thing that drifted.
• ⚠️ database-docs is continue-on-error: true and not a required check — it documents, it does not gate.

Two bugs found and fixed while writing the tests

1. --check overwrote the file it was checking. It regenerated in place then asked git, so a hand-edited schema.sql was silently repaired and reported "current" — it only ever caught a stale commit. Now it derives to a sibling file and diffs, leaving the target untouched, so CI no longer mutates its own checkout either.
2. A test assertion expected CHANGED after repairing an uncommitted edit. The generator reports against HEAD, and the file correctly matched HEAD again.

The comparison file sits beside the target rather than in /tmp or behind <(...): process substitution hands diff a /dev/fd path some sandboxes refuse, and a fixed temp path collides between concurrent runs. All three variants were tried; both alternatives fail as Operation not permitted, which reads like a broken script rather than like drift.

Verification

• dotnet build src/ — 0 warnings, 0 errors (Debug and Release)
• dotnet test src/ — 635/635
• dotnet format --verify-no-changes — clean
• All 5 script suites pass; derive-db-docs.test.sh adds 12 assertions including the failure path
• ⚠️ Not verified locally: the database-docs job needs a live PostgreSQL and Docker. Its first real run is on CI.

See docs/adr/0004-schema-documentation.md.

🤖 Generated with Claude Code