Public: anyone can read this; the crew can change it.
Repair a database whose schema lags its recorded version #221
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/214-repair-a-database-whose-schema-lags-its → main 2 commits fork 2 threads · 2 unresolved
4 files
changed +149
−0
docs/TECHNICAL.md +6
| @@ -298,6 +298,12 @@ decide nothing themselves. `AGENTS.md` says how to add to it. | ||
| 298 | 298 | bound of 1000; `LIMIT`ed, no writes). If one throws it answers 503 with `ok:false` and `failed` naming |
| 299 | 299 | the check (`profile`, `deals`, `dates`, `waiting`), never the SQL or the |
| 300 | 300 | error, so a database a broken upgrade left behind never looks healthy. |
| 301 | At boot a failing check is logged to stderr first (the check and SQLite's | |
| 302 | message); then `src/repair.ts` re-adds any column the recorded schema | |
| 303 | version promises and a table lacks, by running the migration's own | |
| 304 | `ADD COLUMN` (so its CHECK is kept), and says `added table.column` on | |
| 305 | stdout. It never drops or rewrites (only the `ADD COLUMN`, never a migration's backfill), and a repair that throws is logged to stderr while the boot goes on; a rebuilt table that drifted is not | |
| 306 | repaired and stays 503. | |
| 301 | 307 | - **The look.** `design/tokens.json` holds every colour, space and size, |
| 302 | 308 | light and dark; nothing else spells out a colour (`bun run lint:design`), |
| 303 | 309 | and every pair a person reads meets 4.5:1 in both themes. |
src/repair.test.ts added +92
| @@ -0,0 +1,92 @@ | ||
| 1 | import { expect, spyOn, test } from "bun:test"; | |
| 2 | import { Database } from "bun:sqlite"; | |
| 3 | import { mkdtempSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { migrate, openDb } from "./db.ts"; | |
| 7 | import { failedCheck } from "./health.ts"; | |
| 8 | import { repairAtBoot, repairDrift } from "./repair.ts"; | |
| 9 | import { serve } from "./server.ts"; | |
| 10 | ||
| 11 | const sqlOf = (db: Database, table: string) => | |
| 12 | db.query<{ sql: string }, [string]>("SELECT sql FROM sqlite_master WHERE name = ?1").get(table)!.sql; | |
| 13 | ||
| 14 | // A database that records the newest schema version and lacks columns it promises. | |
| 15 | function drifted(): Database { | |
| 16 | const db = new Database(":memory:"); | |
| 17 | migrate(db); | |
| 18 | for (const [t, c] of [["deadline", "place"], ["deadline", "time"], ["profile", "zone"], ["deal", "closing_place"]]) { | |
| 19 | db.exec(`ALTER TABLE ${t} DROP COLUMN ${c}`); | |
| 20 | } | |
| 21 | return db; | |
| 22 | } | |
| 23 | ||
| 24 | test("a drifted database fails the first paint, is repaired, and then serves it", () => { | |
| 25 | const db = drifted(); | |
| 26 | expect(failedCheck(db)).not.toBeNull(); | |
| 27 | expect(repairDrift(db).sort()).toEqual(["deadline.place", "deadline.time", "deal.closing_place", "profile.zone"]); | |
| 28 | expect(failedCheck(db)).toBeNull(); | |
| 29 | expect(repairDrift(db)).toEqual([]); | |
| 30 | }); | |
| 31 | ||
| 32 | test("a repaired column keeps the CHECK a fresh database enforces", () => { | |
| 33 | const db = drifted(); | |
| 34 | repairDrift(db); | |
| 35 | const fresh = new Database(":memory:"); | |
| 36 | migrate(fresh); | |
| 37 | for (const t of ["deadline", "profile", "deal"]) { | |
| 38 | for (const col of ["place", "time", "zone", "closing_place"]) { | |
| 39 | const re = new RegExp(`${col} [^,]*CHECK[^,]*\\)`); | |
| 40 | expect(re.test(sqlOf(db, t))).toBe(re.test(sqlOf(fresh, t))); | |
| 41 | } | |
| 42 | } | |
| 43 | expect(() => db.exec("INSERT INTO profile (id, name, brokerage, phone, email, zone) VALUES (1, 'A', 'B', '5', '[email protected]', '')")).toThrow(/CHECK/); | |
| 44 | }); | |
| 45 | ||
| 46 | test("a boot repairs the file, still reports the failure on stderr, and says what it added", () => { | |
| 47 | const dir = mkdtempSync(join(tmpdir(), "app-repair-")); | |
| 48 | const seeded = openDb(dir); | |
| 49 | seeded.exec("ALTER TABLE deadline DROP COLUMN place"); | |
| 50 | seeded.close(); | |
| 51 | const err = spyOn(console, "error").mockImplementation(() => {}); | |
| 52 | const out = spyOn(console, "log").mockImplementation(() => {}); | |
| 53 | try { | |
| 54 | serve({ port: 0, dataDir: dir, identityKey: "k" }).stop(true); | |
| 55 | expect(err.mock.calls.map((a) => a.join(" "))).toHaveLength(1); | |
| 56 | expect(err.mock.calls[0]!.join(" ")).toMatch(/health check "dates" fails at boot: .*no such column: place/); | |
| 57 | expect(out.mock.calls.map((a) => a.join(" ")).join("\n")).toMatch(/added deadline\.place/); | |
| 58 | } finally { | |
| 59 | err.mockRestore(); | |
| 60 | out.mockRestore(); | |
| 61 | } | |
| 62 | const after = new Database(join(dir, "app.db")); | |
| 63 | expect(failedCheck(after)).toBeNull(); | |
| 64 | }); | |
| 65 | ||
| 66 | test("a repair adds only the column: a migration's backfill UPDATE does not run", () => { | |
| 67 | const db = new Database(":memory:"); | |
| 68 | migrate(db); | |
| 69 | db.exec("INSERT INTO deal (address, contract_date, author_id, author_name) VALUES ('1 A St', '2026-01-01', 'sample', 'S')"); | |
| 70 | db.exec( | |
| 71 | "INSERT INTO reminder (deal_id, deadline_id, party_id, label, party_name, moment, due, by_name) SELECT id, 1, 1, 'L', 'P', 'before', '2026-02-01', 'Sample data' FROM deal", | |
| 72 | ); | |
| 73 | db.exec("ALTER TABLE reminder DROP COLUMN sample"); | |
| 74 | expect(repairDrift(db)).toEqual(["reminder.sample"]); | |
| 75 | // Had the backfill run, this row would be marked sample = 1. | |
| 76 | expect(db.query("SELECT sample FROM reminder").get()).toEqual({ sample: 0 }); | |
| 77 | }); | |
| 78 | ||
| 79 | test("a repair that cannot run is logged to stderr and the boot goes on, so healthz stays 503", () => { | |
| 80 | const dir = mkdtempSync(join(tmpdir(), "app-repair-ro-")); | |
| 81 | const seeded = openDb(dir); | |
| 82 | seeded.exec("ALTER TABLE deadline DROP COLUMN place"); | |
| 83 | seeded.close(); | |
| 84 | const db = new Database(join(dir, "app.db"), { readonly: true }); | |
| 85 | const lines: string[] = []; | |
| 86 | const said: string[] = []; | |
| 87 | expect(() => repairAtBoot(db, "deal-clock", (l) => said.push(l), (l) => lines.push(l))).not.toThrow(); | |
| 88 | expect(said).toEqual([]); | |
| 89 | expect(lines).toHaveLength(1); | |
| 90 | expect(lines[0]).toMatch(/^deal-clock: repair of the schema failed at boot: .*readonly/); | |
| 91 | expect(failedCheck(db)).toBe("dates"); | |
| 92 | }); |
src/repair.ts added +49
| @@ -0,0 +1,49 @@ | ||
| 1 | import type { Database } from "bun:sqlite"; | |
| 2 | import { migrations } from "./db.ts"; | |
| 3 | ||
| 4 | const ADD_COLUMN = /^ALTER TABLE (\w+) ADD COLUMN (\w+) /; | |
| 5 | ||
| 6 | /** | |
| 7 | * Put back the columns a database's recorded schema version promises and its | |
| 8 | * tables lack. Each is re-added by running the migration's own `ADD COLUMN` | |
| 9 | * statement, so the column keeps its type, default and CHECK constraint | |
| 10 | * exactly as a fresh database has them. A table that is absent is left alone | |
| 11 | * (a rebuild migration owns it), and nothing is dropped or rewritten. | |
| 12 | * Returns `table.column` for each column added; empty when nothing drifted. | |
| 13 | */ | |
| 14 | export function repairDrift(db: Database): string[] { | |
| 15 | const added: string[] = []; | |
| 16 | db.transaction(() => { | |
| 17 | for (const sql of migrations) { | |
| 18 | const match = ADD_COLUMN.exec(sql); | |
| 19 | if (match === null) continue; | |
| 20 | const [, table, column] = match as unknown as [string, string, string]; | |
| 21 | const columns = db.query<{ name: string }, []>(`PRAGMA table_info(${table})`).all(); | |
| 22 | if (columns.length === 0 || columns.some((c) => c.name === column)) continue; | |
| 23 | // Only the ADD COLUMN: a migration's trailing backfill UPDATE would rewrite rows. | |
| 24 | db.exec(sql.split(";")[0]!); | |
| 25 | added.push(`${table}.${column}`); | |
| 26 | } | |
| 27 | })(); | |
| 28 | return added; | |
| 29 | } | |
| 30 | ||
| 31 | /** | |
| 32 | * Repair at boot, after the failure has been reported: the boot line names the | |
| 33 | * failing check first, then this says what was put back. Stdout, so stderr | |
| 34 | * stays the failures alone. | |
| 35 | */ | |
| 36 | export function repairAtBoot( | |
| 37 | db: Database, | |
| 38 | title: string, | |
| 39 | log: (line: string) => void = console.log, | |
outdated
Wrap repairDrift in try/catch: on failure, log to stderr and return so serve() still starts and /healthz reports 503. As written, a failed repair crashes boot. |
||
| 40 | fail: (line: string) => void = console.error, | |
| 41 | ): void { | |
| 42 | try { | |
| 43 | const added = repairDrift(db); | |
| 44 | if (added.length > 0) log(`${title}: schema lagged its recorded version; added ${added.join(", ")}`); | |
| 45 | } catch (error) { | |
| 46 | // The transaction rolled back; the boot goes on and /healthz stays the honest 503. | |
| 47 | fail(`${title}: repair of the schema failed at boot: ${error instanceof Error ? error.message : String(error)}`); | |
| 48 | } | |
| 49 | } |
src/server.ts +2
| @@ -10,6 +10,7 @@ | ||
| 10 | 10 | import { openDb } from "./db.ts"; |
| 11 | 11 | import { dataDir, identityKey, title, where } from "./env.ts"; |
| 12 | 12 | import { reportHealthAtBoot } from "./health.ts"; |
| 13 | import { repairAtBoot } from "./repair.ts"; | |
| 13 | 14 | import { html, sourceBytes, text } from "./http.ts"; |
| 14 | 15 | import { follow } from "./live.ts"; |
| 15 | 16 | import { match, notFound } from "./routes.ts"; |
| @@ -26,6 +27,7 @@ export interface ServeOptions { | ||
| 26 | 27 | export function serve(options: ServeOptions) { |
| 27 | 28 | const db = openDb(options.dataDir); |
| 28 | 29 | reportHealthAtBoot(db, title); |
| 30 | repairAtBoot(db, title); | |
| 29 | 31 | // The terminal writes from its own process: when the file changes under |
| 30 | 32 | // us, every open page hears it, as if the change were made here. |
| 31 | 33 | const unfollow = follow( |
new above
offline
db.exec(sql) runs the whole migration string. For party_role and sample that includes the UPDATE backfill. Execute only the ADD COLUMN statement (split at the first semicolon) so the claim that nothing is rewritten holds. An exception here is also uncaught at boot (see repairAtBoot).