import fs from 'node:fs'; import path from 'node:path'; import { DatabaseSync, type StatementSync } from 'node:sqlite'; import { MIGRATIONS } from './migrations.ts'; type Param = string | number | bigint | boolean | null | undefined | Uint8Array; function bind(params: Param[]): (string | number | bigint | null | Uint8Array)[] { return params.map((p) => (p === undefined ? null : typeof p === 'boolean' ? (p ? 1 : 0) : p)); } /** * Thin synchronous wrapper around node:sqlite. Single process, single writer: * exactly what a one-user app in one container needs, with no native add-on to build. */ export class DB { private handle: DatabaseSync; readonly path: string; private statements = new Map(); private txDepth = 0; /** Called after each write that changed rows (used to tell open tabs what changed). */ onWrite: ((sql: string) => void) | null = null; constructor(file: string) { this.path = file; this.handle = DB.open(file); } private static open(file: string): DatabaseSync { const raw = new DatabaseSync(file); raw.exec('PRAGMA journal_mode = WAL'); raw.exec('PRAGMA synchronous = NORMAL'); raw.exec('PRAGMA foreign_keys = ON'); raw.exec('PRAGMA busy_timeout = 5000'); return raw; } /** The node:sqlite handle. Changes when a full backup is restored (`replaceWith`). */ get raw(): DatabaseSync { return this.handle; } /** * Swaps the database file for `file` (a complete, closed SQLite file in the same folder) under * this same object, so every part of the app keeps working with the restored data. If the * swap fails, the current database is reopened untouched. */ replaceWith(file: string): void { if (this.txDepth > 0) throw new Error('A database transaction is still open.'); if (this.path === ':memory:') throw new Error('An in-memory database cannot be replaced.'); this.statements.clear(); try { this.handle.exec('PRAGMA wal_checkpoint(TRUNCATE)'); } catch { /* closing writes it anyway */ } this.handle.close(); try { const aside = `${this.path}.replaced`; fs.rmSync(aside, { force: true }); fs.renameSync(this.path, aside); try { fs.renameSync(file, this.path); } catch (e) { fs.renameSync(aside, this.path); throw e; } for (const ext of ['-wal', '-shm']) fs.rmSync(`${this.path}${ext}`, { force: true }); fs.rmSync(aside, { force: true }); } finally { this.handle = DB.open(this.path); } } private stmt(sql: string): StatementSync { let s = this.statements.get(sql); if (!s) { s = this.raw.prepare(sql); if (this.statements.size > 500) this.statements.clear(); this.statements.set(sql, s); } return s; } all>(sql: string, ...params: Param[]): T[] { return this.stmt(sql).all(...bind(params)) as T[]; } get>(sql: string, ...params: Param[]): T | undefined { return this.stmt(sql).get(...bind(params)) as T | undefined; } run(sql: string, ...params: Param[]): { changes: number; lastId: number } { const r = this.stmt(sql).run(...bind(params)); if (this.onWrite && r.changes) this.onWrite(sql); return { changes: Number(r.changes), lastId: Number(r.lastInsertRowid) }; } exec(sql: string): void { this.raw.exec(sql); } /** Runs fn atomically. Nested calls become savepoints. */ tx(fn: () => T): T { const depth = this.txDepth; const name = `sp_${depth}`; this.raw.exec(depth === 0 ? 'BEGIN IMMEDIATE' : `SAVEPOINT ${name}`); this.txDepth += 1; try { const out = fn(); this.txDepth -= 1; this.raw.exec(depth === 0 ? 'COMMIT' : `RELEASE ${name}`); return out; } catch (e) { this.txDepth -= 1; try { this.raw.exec(depth === 0 ? 'ROLLBACK' : `ROLLBACK TO ${name}; RELEASE ${name}`); } catch { /* the original error matters more */ } throw e; } } /** Writes a consistent, compacted copy of the database (safe while the app is running). */ snapshot(target: string): void { if (fs.existsSync(target)) fs.rmSync(target); this.raw.exec(`VACUUM INTO '${target.replace(/'/g, "''")}'`); } close(): void { this.statements.clear(); try { this.raw.exec('PRAGMA wal_checkpoint(TRUNCATE)'); } catch { /* ignore */ } this.raw.close(); } } export interface MigrationReport { applied: string[]; backup: string | null; } /** * Applies pending migrations in order, each in its own transaction. When an existing * database is about to change, a snapshot is written to the backups folder first. */ export function migrate(db: DB, backupsDir?: string): MigrationReport { db.exec('CREATE TABLE IF NOT EXISTS schema_migrations (id INTEGER PRIMARY KEY, name TEXT NOT NULL, applied_at INTEGER NOT NULL)'); const done = new Set(db.all<{ id: number }>('SELECT id FROM schema_migrations').map((r) => r.id)); const known = new Set(MIGRATIONS.map((m) => m.id)); const unknown = [...done].filter((id) => !known.has(id)); if (unknown.length > 0) { throw new Error( `This database was created by a newer version of Study Desk (unknown migration ${unknown.join(', ')}). Upgrade the app instead of downgrading it.`, ); } const pending = MIGRATIONS.filter((m) => !done.has(m.id)).sort((a, b) => a.id - b.id); const report: MigrationReport = { applied: [], backup: null }; if (pending.length === 0) return report; if (done.size > 0 && backupsDir && db.path !== ':memory:') { fs.mkdirSync(backupsDir, { recursive: true }); const stamp = new Date().toISOString().replace(/[:.]/g, '-'); report.backup = path.join(backupsDir, `pre-migration-${stamp}.db`); db.snapshot(report.backup); } for (const m of pending) { db.tx(() => { db.exec(m.sql); db.run('INSERT INTO schema_migrations (id, name, applied_at) VALUES (?, ?, ?)', m.id, m.name, Date.now()); }); report.applied.push(`${m.id}_${m.name}`); } return report; } export function openDatabase(file: string, backupsDir?: string): { db: DB; report: MigrationReport } { const db = new DB(file); const report = migrate(db, backupsDir); return { db, report }; }