src/backup.ts

Functions

Imports

It imports src/dump.ts, src/runs.ts, src/schema.ts, src/types.ts. Imported by src/index.ts.

Source

1import { dumpDatabase, writeCompleteMarker, type DumpOptions, type DumpResult } from "./dump.js";
2import { pruneDumps, type PruneResult, type RetentionPolicy } from "./runs.js";
3import { quoteIdent } from "./schema.js";
4import type { D1Like, R2Like } from "./types.js";
5
6export interface BackupOptions extends Omit<DumpOptions, "markComplete"> {
7  // Tables that must be in the dump: the ones that hold what exists nowhere else.
8  required?: string[];
9  // Tables counted live straight after the dump. Each must be dumped with exactly its live row
10  // count, and the run is refused if every one dumped empty: an emptied database matches its own
11  // counts. Name tables only the operator writes, since a reader's write between the dump and the
12  // count would fail the night.
13  counted?: string[];
14  // The site's own checks, run after the standard ones. Each string is one failed check.
15  check?: (dump: DumpResult) => string[] | Promise<string[]>;
16  // Passed to pruneDumps. The default is its graduated retention.
17  retention?: { policy?: RetentionPolicy; retentionDays?: number; minKept?: number };
18}
19
20export interface BackupResult {
21  dump: DumpResult;
22  pruned: PruneResult;
23}
24
25// A run that failed its checks. Its objects stay as evidence, without the marker, so it is
26// never the newest dump and the health age keeps growing until a good run lands.
27export class BackupIncomplete extends Error {
28  constructor(
29    readonly dump: DumpResult,
30    readonly problems: string[]
31  ) {
32    super(`dump ${dump.run_id} was left incomplete: ${problems.join("; ")}`);
33    this.name = "BackupIncomplete";
34  }
35}
36
37// The checks every site makes: something was dumped, no excluded table is in it, and every
38// required table is. One message per failed check; empty means the dump may be marked complete.
39export function standardProblems(dump: DumpResult, options: { exclude?: string[]; required?: string[] } = {}): string[] {
40  const problems: string[] = [];
41  const names = new Set(dump.tables.map((t) => t.name));
42  const rows = dump.tables.reduce((sum, t) => sum + t.rows, 0);
43  if (dump.tables.length === 0 || rows === 0) problems.push(`the dump holds ${dump.tables.length} tables and ${rows} rows`);
44  for (const name of options.exclude ?? []) if (names.has(name)) problems.push(`${name} is in the dump but must be excluded`);
45  for (const name of options.required ?? []) if (!names.has(name)) problems.push(`${name} is missing from the dump`);
46  return problems;
47}
48
49// Each counted table that was dumped is counted again live; a missing one is named by the required check.
50async function countProblems(db: D1Like, dump: DumpResult, counted: string[]): Promise<string[]> {
51  if (counted.length === 0) return [];
52  const dumped = new Map(dump.tables.map((t) => [t.name, t.rows]));
53  const present = counted.filter((name) => dumped.has(name));
54  const count = (name: string) => db.prepare(`SELECT COUNT(*) AS n FROM ${quoteIdent(name)}`);
55  const live = present.length > 0 ? await db.batch<{ n: number }>(present.map(count)) : [];
56  const problems = present.flatMap((name, i) => {
57    const n = live[i]?.results[0]?.n;
58    return n === dumped.get(name) ? [] : [`${name} dumped ${dumped.get(name)} rows but has ${n}`];
59  });
60  if (counted.every((name) => (dumped.get(name) ?? 0) === 0)) problems.push("every counted table dumped empty");
61  return problems;
62}
63
64// The nightly backup: dump without the marker, run the standard and the site's checks, then
65// write the marker and prune. Prune runs only after a marker, so a failing night deletes nothing.
66export async function runCheckedBackup(db: D1Like, bucket: R2Like, options: BackupOptions = {}): Promise<BackupResult> {
67  const { required, counted = [], check, retention, ...dumpOptions } = options;
68  const dump = await dumpDatabase(db, bucket, { ...dumpOptions, markComplete: false });
69  const problems = [
70    ...standardProblems(dump, { exclude: dumpOptions.exclude, required: [...new Set([...(required ?? []), ...counted])] }),
71    ...(await countProblems(db, dump, counted)),
72    ...((await check?.(dump)) ?? []),
73  ];
74  if (problems.length > 0) throw new BackupIncomplete(dump, problems);
75  await writeCompleteMarker(bucket, dump);
76  const pruned = await pruneDumps(bucket, { prefix: dumpOptions.prefix, now: dumpOptions.now, ...retention });
77  return { dump, pruned };
78}