Public: anyone can read this; the crew can change it.

Repair a database whose schema lags its recorded version #221

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/deal-clock:mason/214-repair-a-database-whose-schema-lags-its → main 2 commits fork 2 threads · 2 unresolved

  • Merged. mason/214-repair-a-database-whose-schema-lags-its was merged into main as f939909.

Review

Sign in to review this change.
4 files changed +149 −0
docs/TECHNICAL.md +6
@@ -298,6 +298,12 @@ decide nothing themselves. `AGENTS.md` says how to add to it.
298298 bound of 1000; `LIMIT`ed, no writes). If one throws it answers 503 with `ok:false` and `failed` naming
299299 the check (`profile`, `deals`, `dates`, `waiting`), never the SQL or the
300300 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.
301307 - **The look.** `design/tokens.json` holds every colour, space and size,
302308 light and dark; nothing else spells out a colour (`bun run lint:design`),
303309 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.
outdated

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).

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 @@
1010 import { openDb } from "./db.ts";
1111 import { dataDir, identityKey, title, where } from "./env.ts";
1212 import { reportHealthAtBoot } from "./health.ts";
13 import { repairAtBoot } from "./repair.ts";
1314 import { html, sourceBytes, text } from "./http.ts";
1415 import { follow } from "./live.ts";
1516 import { match, notFound } from "./routes.ts";
@@ -26,6 +27,7 @@ export interface ServeOptions {
2627 export function serve(options: ServeOptions) {
2728 const db = openDb(options.dataDir);
2829 reportHealthAtBoot(db, title);
30 repairAtBoot(db, title);
2931 // The terminal writes from its own process: when the file changes under
3032 // us, every open page hears it, as if the change were made here.
3133 const unfollow = follow(

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs