All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 30s
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>
185 lines
6.2 KiB
TypeScript
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 };
|
|
}
|