Repository navigation
doctor: compare stored migration checksums, not just versions #138
Description
Existing issue check
- I searched open and closed issues. None found.
Problem or outcome
doctor reports migrations by version only (crates/consolebook-server/src/doctor.rs:170-179). It never compares the stored _sqlx_migrations checksums with the embedded migrations, and serve refuses to start when they differ. Found while proving #136 (2026-10-15). In a copy of a seeded database with migration 16's stored checksum zeroed:
doctorprintedok migrations 16 applied, up to dateand exited 0;serveexited 1 withrunning database migrations: migration 16 was previously applied but has been modified.
So the read-only diagnostic misses exactly the condition that stops the service. An operator who runs doctor before restarting after an upgrade, as the operations guide suggests, would be told everything is fine.
Outcome
doctor compares each applied migration's stored checksum with the embedded one, and reports any mismatch or unknown applied version as a failure. It names the version and says what it means: the database was migrated by a different build of this migration. It stays read-only (ADR 0016).
Acceptance criteria
- A test with a tampered stored checksum makes
doctorreport a failure and exit non-zero. A positive control on an intact database staysok. - Unchanged: doctor opens nothing for writing, and its read-only test passes.
Related
#136, ADR 0016, tests/upgrade_compat.rs (#136 pins the released checksums).
Activity
TusanHomichi commentedon Oct 15, 2026
Selected (2026-10-15): the maintainer said "lets do 126 and 138 first", ahead of a 0.3.0 release. Work proceeds under the standing PR permission: an issue-linked branch, an independent review, the full local proof, then merge.
TusanHomichi commentedon Oct 15, 2026
Review and decision (2026-10-15). Independent review of
249b2a3: 0 blocking. It confirmed from sqlx-core 0.9 itself that there is no history wheredoctorsays ok whileserverefuses, and that startup's decisions and wording are unchanged.It also found the inverse mismatch, which predates this change.
doctorFAILs onpending: Nand on a database with no_sqlx_migrationstable, yetservestarts on both: it applies the pending migrations, or creates the table. ApendingFAIL is what an operator sees after installing a new binary and runningdoctorbefore restarting.Integrator decision: parity in both directions. Pending migrations and a database with no migration history yet become a
warnthat says what the service will do on start. Only the refusals stayfail. This is backed by a doctor/serve parity test, the operations guide sentence is corrected, and the change is noted in the CHANGELOG. The review's nits are also applied: message wording, the read-only test's claim, an ordering comment, a zombie process in a test, and a README line wrap.The startup ordering problem the implementation surfaced is filed as #142.
fix(doctor): report every migration history serve would refuse
fix(doctor): warn, not fail, on migrations the service applies by itself
fix(doctor): fail a populated database with no migration history; rec…
fix(doctor): report every migration history serve would refuse (#144)
TusanHomichi commentedon Oct 15, 2026
Merged in #144 as
296a81a6439cfc526d461e5f4d0a2348a1d33f53(squash; single parent1dfb945). The tree6a642bc8is identical to the proven head8d403e5.4916711e….fmt-clippy-test,build-x86_64,build-aarch64, and CodeQL all passed.Authority: the maintainer's selection and standing PR permission.