@toist/aja 0.5.0

package/src/migrate.ts

@@ -0,0 +1,204 @@
+// 2121
+// Linear SQL-file migration runner for runtime.db.
+//
+// Migrations live in <migrationsDir> (default: sibling 'migrations/' of the
+// runner code). Files named NNN_description.sql are applied in lexicographic
+// order, each in its own SQL transaction.
+//
+// Tracking: the _migrations table records every applied filename + sha256
+// checksum of its contents. Re-applying is a no-op. Editing an applied file
+// is a loud error — checksum mismatch refuses to start, forcing the author to
+// add a new migration instead.
+//
+// Bootstrap: _migrations is created (CREATE TABLE IF NOT EXISTS) before
+// reading it, so the very first run on a fresh DB works without special-casing.
+//
+// Auto-migrate vs explicit: by default the runner applies pending migrations
+// at startup. RUNTIME_AUTO_MIGRATE=false flips this to fail-loud — startup
+// aborts if anything is pending.
+
+import { Database } from "bun:sqlite"
+import { readdirSync, readFileSync, existsSync, copyFileSync, statSync, unlinkSync } from "node:fs"
+import { join, dirname, basename } from "node:path"
+import { fileURLToPath } from "node:url"
+import { createHash } from "node:crypto"
+
+const __dir = dirname(fileURLToPath(import.meta.url))
+export const DEFAULT_MIGRATIONS_DIR = join(__dir, "..", "migrations")
+const BACKUP_RETAIN = 5
+
+export interface MigrateOptions {
+  migrationsDir?: string
+}
+
+export interface MigrationResult {
+  applied: string[]
+  alreadyApplied: string[]
+  backup?: string
+}
+
+function checksum(contents: string): string {
+  return createHash("sha256").update(contents).digest("hex")
+}
+
+interface MigrationFile {
+  filename: string
+  contents: string
+  checksum: string
+}
+
+function readMigrationFiles(migrationsDir: string): MigrationFile[] {
+  if (!existsSync(migrationsDir)) {
+    throw new Error(`[migrate] migrations directory not found: ${migrationsDir}`)
+  }
+  return readdirSync(migrationsDir)
+    .filter((f) => f.endsWith(".sql"))
+    .sort()
+    .map((filename) => {
+      const contents = readFileSync(join(migrationsDir, filename), "utf8")
+      return { filename, contents, checksum: checksum(contents) }
+    })
+}
+
+function ensureMigrationsTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _migrations (
+      filename   TEXT PRIMARY KEY,
+      checksum   TEXT NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `)
+}
+
+function readApplied(db: Database): Map<string, string> {
+  const rows = db.prepare("SELECT filename, checksum FROM _migrations").all() as
+    { filename: string; checksum: string }[]
+  return new Map(rows.map((r) => [r.filename, r.checksum]))
+}
+
+function verifyChecksum(file: MigrationFile, knownChecksum: string): void {
+  if (file.checksum !== knownChecksum) {
+    throw new Error(
+      `[migrate] checksum mismatch for already-applied "${file.filename}". ` +
+      `Applied migrations are immutable — add a new migration instead of editing this one.`,
+    )
+  }
+}
+
+/**
+ * Snapshot the runtime DB before any pending migration is applied. Keeps the
+ * last BACKUP_RETAIN snapshots, prunes older ones. Returns the backup path,
+ * or null if there is nothing to back up (first-ever run).
+ *
+ * Filename: <db>.bak-<ISO-timestamp> with colons replaced (Windows-safe).
+ * Backups live next to the DB. They are not an audit log — durable history
+ * lives in the runs table itself.
+ */
+function backupAndPrune(dbPath: string): string | null {
+  if (!existsSync(dbPath)) return null
+
+  const dir = dirname(dbPath)
+  const base = basename(dbPath)
+  const ts = new Date().toISOString().replace(/[:.]/g, "-")
+  const backupPath = join(dir, `${base}.bak-${ts}`)
+
+  copyFileSync(dbPath, backupPath)
+  console.log(`[migrate] backup ${backupPath}`)
+
+  const prefix = `${base}.bak-`
+  const all = readdirSync(dir)
+    .filter((f) => f.startsWith(prefix))
+    .map((f) => ({ name: f, mtime: statSync(join(dir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)
+
+  for (const stale of all.slice(BACKUP_RETAIN)) {
+    unlinkSync(join(dir, stale.name))
+    console.log(`[migrate] pruned old backup ${stale.name}`)
+  }
+
+  return backupPath
+}
+
+/**
+ * Returns the list of migrations that exist on disk but are not yet applied
+ * to the given database. Verifies checksums of already-applied migrations as
+ * a side-effect (throws on mismatch). Does not mutate the database.
+ */
+export function pendingMigrations(dbPath: string, opts: MigrateOptions = {}): string[] {
+  const files = readMigrationFiles(opts.migrationsDir ?? DEFAULT_MIGRATIONS_DIR)
+  const db = new Database(dbPath, { create: true })
+  try {
+    ensureMigrationsTable(db)
+    const applied = readApplied(db)
+    const pending: string[] = []
+    for (const file of files) {
+      const known = applied.get(file.filename)
+      if (known === undefined) pending.push(file.filename)
+      else verifyChecksum(file, known)
+    }
+    return pending
+  } finally {
+    db.close()
+  }
+}
+
+/**
+ * Applies pending migrations in lexicographic order. Idempotent: returns
+ * with empty `applied` if nothing is pending. Each migration runs in its own
+ * SQL transaction; a failure rolls back that migration and aborts the run.
+ *
+ * Before applying anything, snapshots the DB to <db>.bak-<timestamp> and
+ * prunes old backups beyond BACKUP_RETAIN. No backup is taken when nothing
+ * is pending (no-op runs leave the filesystem alone).
+ */
+export function runMigrations(dbPath: string, opts: MigrateOptions = {}): MigrationResult {
+  const files = readMigrationFiles(opts.migrationsDir ?? DEFAULT_MIGRATIONS_DIR)
+  const result: MigrationResult = { applied: [], alreadyApplied: [] }
+
+  // Phase 1: open, verify checksums of already-applied, collect pending. Close.
+  const checkDb = new Database(dbPath, { create: true })
+  const pending: MigrationFile[] = []
+  try {
+    ensureMigrationsTable(checkDb)
+    const applied = readApplied(checkDb)
+    for (const file of files) {
+      const known = applied.get(file.filename)
+      if (known === undefined) {
+        pending.push(file)
+      } else {
+        verifyChecksum(file, known)
+        result.alreadyApplied.push(file.filename)
+      }
+    }
+  } finally {
+    checkDb.close()
+  }
+
+  if (pending.length === 0) return result
+
+  // Phase 2: backup with no DB connection open, then apply pending sequentially.
+  result.backup = backupAndPrune(dbPath) ?? undefined
+
+  const db = new Database(dbPath, { create: true })
+  try {
+    for (const file of pending) {
+      const apply = db.transaction(() => {
+        db.exec(file.contents)
+        db.prepare(
+          "INSERT INTO _migrations (filename, checksum) VALUES (?, ?)",
+        ).run(file.filename, file.checksum)
+      })
+      try {
+        apply()
+        result.applied.push(file.filename)
+        console.log(`[migrate] applied ${file.filename}`)
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        throw new Error(`[migrate] failed applying "${file.filename}": ${msg}`)
+      }
+    }
+    return result
+  } finally {
+    db.close()
+  }
+}