reportSchemaDrift logged 76 differences on every boot, all false positives:
38 indexes each reported twice, once as missing from the database and once
as present but undeclared. The only difference was a single space before the
column list.
The two sides of the comparison are built differently. referenceSnapshot()
applies schema.sql to a local in-memory libsql, which stores the CREATE text
verbatim as "ON t(col)". Production is an embedded replica syncing to Bunny,
whose parser re-emits normalized DDL as "ON t (col)". describeIndexes
collapsed whitespace runs but could not normalize a space that exists on one
side only, and SchemaDrift compares by exact string.
Normalize whitespace adjacent to ( ) and , so both spellings converge. Space
after ) is deliberately left alone, and the space before DESC is untouched,
so column order and direction still have to match.
This mattered because the check exists to catch a migration recorded but not
executed (0004 was, which is why 0009 exists). At 76 phantom findings, real
drift would have been one line among 77, under a hint telling the operator to
write a corrective migration that is not needed. The first boot after this
lands is the first honest reading of that warning.
The existing tests all passed because they run local-only, which is exactly
how this shipped.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PDqoCE1j3njokkZ9b1C5n9
Migrations can be recorded without being executed. That is not hypothetical:
migration 0009 exists to clean up after 0004, which production recorded but
never applied, leaving eleven columns behind that fresh installs never had.
Nothing reported it at the time; it surfaced later as confusing behavior.
InitDB now compares an existing database against schema.sql after migrations run
and logs one warning per difference. Fresh databases skip the check, since they
were just built from schema.sql and agree by construction.
The comparison works by applying schema.sql to a throwaway in-memory database
and introspecting that, rather than parsing the DDL. SQLite's own resolution of
types, defaults and implicit indexes is exactly what we want to compare against,
and a hand-rolled parser would drift from the engine. The introspection is
shared with TestSchemaMatchesMigrations, so the test exercises the same code
that runs at boot.
Warn-only, never fatal. A database merely ahead of or behind schema.sql is
almost always still able to serve traffic, so refusing to boot would turn a diff
that wants a corrective migration into an outage, during a deploy, which is the
worst possible moment to have one.
The README claimed new tables go in schema.sql only. That is wrong in the
direction that hurts: InitDB skips schema.sql entirely once schema_migrations
has rows, so such a table appears on fresh installs, passes every test, and is
silently absent in production. Documented the real rule along with two others
the test cannot enforce: migrations must not return rows (go-libsql rejects them
with "Execute returned rows"), and rebuild migrations must name columns
explicitly, since column order legitimately differs between fresh and upgraded
databases.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
schema.sql and migrations/ are meant to move in lockstep, and nothing checked
that they did. The cost is already on the record: migration 0009 exists only
because 0004 "was supposed to drop these columns but either failed or was only
recorded (not executed) on production", leaving production carrying eleven
columns fresh installs never had.
Build the schema both ways and compare. testdata/base_schema.sql is the shape
immediately before 0009, reconstructed by reversing 0009-0029 out of the current
schema.sql; applying it and then running every migration must land on the same
place as applying schema.sql directly.
Columns compare as a set, ignoring ordinal position. Migrations append with ADD
COLUMN while schema.sql places the same column mid-table, so manifests, users,
devices and repo_pages legitimately differ in order. Reordering them would mean
four rebuild migrations for no functional gain, and nothing in pkg/appview reads
by position (no SELECT *, no column-less INSERT ... VALUES).
Verified non-vacuous three ways: a column only in schema.sql, a column only in a
migration, and a table only in schema.sql are each caught. That last case is the
one with teeth, since InitDB skips schema.sql entirely once schema_migrations has
rows, so a table added only there never reaches an existing database.
The snapshot records versions 1-8 as applied, which is what "before 0009" means.
It also sidesteps a live rake: migration 0001's query is a bare SELECT, and
go-libsql rejects row-returning statements passed to Exec. Every real database
recorded 0001 long ago so it never fires, but a future migration opening with a
SELECT would fail the same way.
This cannot independently verify tables that appear in no migration; those are
copied from schema.sql and compare against themselves. Drift there is the
startup check's job.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Evan JarrettandClaude Opus 5