Study/server/db.ts
Elijah 7125dec3e0
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
Restore a full backup from Settings
Settings → Data → Import gets "Restore a full backup" in place of the V1
import row. The zip from "Download backup" is uploaded and replaces the
database, every setting and the uploaded files on the running server:

- the staged database is upgraded to this schema (newer backups are refused),
  saved keys are re-encrypted for this server's key, interrupted jobs are
  marked, and the restoring session is carried over;
- a pre-restore snapshot is written, running generations stop, and the file
  is swapped under the open DB handle (DB.replaceWith); uploads and media are
  copied into place and background work restarts.

The /api/import/v1 endpoint stays for the V1 cutover (docs/MIGRATION.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:33:42 -07:00

185 lines
6.2 KiB
TypeScript

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<string, StatementSync>();
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<T = Record<string, unknown>>(sql: string, ...params: Param[]): T[] {
return this.stmt(sql).all(...bind(params)) as T[];
}
get<T = Record<string, unknown>>(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<T>(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 };
}