Study/server/db.ts
Elijah 3e74ecd843 Start Study Desk V2: remove V1 sources, add backend foundation
V1 remains intact on main and in history. This branch replaces it with a new
application: node:sqlite storage with migrations, scrypt auth and sessions,
content/SRS/attempt/stats services, document extraction and chunking, a
provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible,
Ollama), the generation pipeline and the tool-using assistant.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-11 08:16:41 -07:00

140 lines
4.7 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 {
readonly raw: DatabaseSync;
readonly path: string;
private statements = new Map<string, StatementSync>();
private txDepth = 0;
constructor(file: string) {
this.path = file;
this.raw = new DatabaseSync(file);
this.raw.exec('PRAGMA journal_mode = WAL');
this.raw.exec('PRAGMA synchronous = NORMAL');
this.raw.exec('PRAGMA foreign_keys = ON');
this.raw.exec('PRAGMA busy_timeout = 5000');
}
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));
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 };
}