Files
TREK/server/src/nest/backup/boot-restore.ts
T
Maurice e6f4f7a5f3 fix(db): leave nothing behind when a first Postgres boot fails, so RESTORE_FROM_BACKUP still runs
createFromBaseline created the migration history's table through MikroORM's
storage before, and outside, the transaction that runs the baseline. Without a
master transaction MikroORM commits that table on its own, so a first boot that
failed in the baseline (a server without ICU, a timeout, a dropped connection)
left an empty mikro_orm_migrations behind. The next start with
RESTORE_FROM_BACKUP took that for a database in use, skipped the restore with a
warning and brought up an empty instance, after which the restore never ran.

The table is now created on the baseline's own transaction, so a failed first
boot leaves the database empty. The boot restore also treats a lone migration
history that records nothing as no database, which a restore clears anyway; any
other answer keeps it, so the check fails closed. Database-Postgres says both.
2026-11-17 23:04:11 +01:00

142 lines
6.8 KiB
TypeScript

import { pgRestore, pgTablesInUse } from '../../db/engine/postgres/pg-tools';
import { stageExtractedPluginTrees } from '../plugins/plugin-backup';
import {
checkBackupDatabase,
extractBackupArchive,
markReclaimResetPending,
MAX_BACKUP_DECOMPRESSED_SIZE,
} from './backup-archive';
import { checkPostgresDump, PG_ARCHIVE_ENTRY } from './postgres-database-backup';
import fs from 'fs';
import path from 'path';
/**
* Restoring a backup on the very first start (#1089).
*
* Moving an instance used to mean setting up a new one first: fetch the admin
* password from the logs, sign in, click through the welcome, then restore in
* the admin panel and throw the fresh admin away again. With
* RESTORE_FROM_BACKUP pointing at an archive, the first start restores it
* instead, and the instance comes up as the one the backup was taken from.
*
* ── When it runs ─────────────────────────────────────────────────────────
*
* Only while there is no database yet. The variable is typically left in the
* compose file after the move, and a restart must not roll the instance back to
* the day it moved; with a database present it is ignored with a warning.
*
* It runs before the database is opened, not after: the archive's database is
* migrated on the normal open, the admin seed finds its users and adds none, and
* the at-rest key the archive carries is in place before anything reads it. A
* restore after startup would need a restart for that key, which is the setup
* step this exists to remove.
*
* ── Why not an upload on the setup screen ────────────────────────────────
*
* A restore that anyone may run on an empty instance is a takeover: whoever
* reaches it first installs their own admins. The environment belongs to
* whoever runs the container, so that is where the switch lives.
*
* ── When it fails ────────────────────────────────────────────────────────
*
* Loudly, and without starting. An empty instance coming up instead would be
* worse than no instance: its new database would then stop the restore from
* ever running on the next start.
*/
export interface BootRestorePlan {
/** The archive to restore, or null when the variable is not set. */
archive: string | null;
/** Where the database lives: TREK_DB_FILE, or data/travel.db. */
dbFile: string;
/** The data directory, for the scratch space and the at-rest key. */
dataDir: string;
/** `data/.trek-reclaim-reset` (data-paths.ts), left before the database is put in place. */
reclaimResetFile: string;
/**
* Set when TREK runs on Postgres (TREK_DB_URL): the archive's dump is loaded
* into the database, which must hold no table yet, instead of `dbFile`.
*/
postgres?: { url: string; binDir: string | undefined };
}
export type BootRestoreOutcome =
| { restored: false; reason: 'unset' | 'database-exists' }
/** `uploads` is the unpacked uploads tree, to hand to storage once it is up. Null when the archive had none. */
| { restored: true; uploads: string | null; staging: string };
export class BootRestoreError extends Error {}
/**
* A database is there already: on a file, the file; on Postgres, any table in
* its schema but a lone migration history that records nothing, which a first
* boot cut short leaves (pgTablesInUse).
*/
async function existingDatabase(plan: BootRestorePlan): Promise<string | null> {
if (!plan.postgres) return fs.existsSync(plan.dbFile) ? plan.dbFile : null;
const tables = await pgTablesInUse(plan.postgres.url, plan.postgres.binDir);
return tables.length > 0 ? `the Postgres database (${tables.length} table(s))` : null;
}
/** Why the unpacked archive's database cannot be restored here, or null. */
async function checkArchiveDatabase(plan: BootRestorePlan, staging: string): Promise<string | null> {
if (plan.postgres) return checkPostgresDump(staging, plan.postgres.binDir);
return checkBackupDatabase(staging)?.error ?? null;
}
/** Puts the archive's database in place: renamed in beside the file, or loaded into Postgres in one transaction. */
async function putDatabaseInPlace(plan: BootRestorePlan, staging: string): Promise<void> {
if (plan.postgres) {
const dump = path.join(staging, PG_ARCHIVE_ENTRY);
await pgRestore(plan.postgres.url, dump, plan.postgres.binDir, MAX_BACKUP_DECOMPRESSED_SIZE);
return;
}
fs.mkdirSync(path.dirname(plan.dbFile), { recursive: true });
// Copied in beside the target and renamed, so a crash leaves either nothing or a whole file.
const tmp = `${plan.dbFile}.restore-tmp`;
fs.copyFileSync(path.join(staging, 'travel.db'), tmp);
fs.renameSync(tmp, plan.dbFile);
}
export async function restoreOnFirstBoot(plan: BootRestorePlan): Promise<BootRestoreOutcome> {
if (!plan.archive) return { restored: false, reason: 'unset' };
const existing = await existingDatabase(plan);
if (existing) {
console.warn(
`[restore] RESTORE_FROM_BACKUP is set, but ${existing} already exists. The backup is only restored on a first start; remove the variable to silence this.`,
);
return { restored: false, reason: 'database-exists' };
}
if (!fs.existsSync(plan.archive) || !fs.statSync(plan.archive).isFile()) {
throw new BootRestoreError(`RESTORE_FROM_BACKUP: no backup archive at ${plan.archive}`);
}
console.log(`[restore] Restoring ${plan.archive} before the first start`);
const staging = path.join(plan.dataDir, `restore-boot-${Date.now()}`);
const refused = await extractBackupArchive(plan.archive, staging);
if (refused) throw new BootRestoreError(`RESTORE_FROM_BACKUP: ${refused.error}`);
const unreadable = await checkArchiveDatabase(plan, staging);
if (unreadable) {
fs.rmSync(staging, { recursive: true, force: true });
throw new BootRestoreError(`RESTORE_FROM_BACKUP: ${unreadable}`);
}
// Storage reclaim drops what the restored database knew about its storage on
// the start that follows, even when the backup is this installation's own.
markReclaimResetPending(plan.reclaimResetFile);
await putDatabaseInPlace(plan, staging);
// The key the archive's secrets were encrypted with. An ENCRYPTION_KEY in the
// environment still wins over the file, exactly as on any other start.
const key = path.join(staging, '.encryption_key');
if (fs.existsSync(key)) fs.copyFileSync(key, path.join(plan.dataDir, '.encryption_key'));
// Plugin trees are swapped in by the runtime's own boot reconcile.
stageExtractedPluginTrees(staging);
const uploads = path.join(staging, 'uploads');
return { restored: true, uploads: fs.existsSync(uploads) ? uploads : null, staging };
}