Files
TREK/server/tests/unit/db/engine/postgres/schema-bootstrap.test.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

443 lines
19 KiB
TypeScript

/**
* How a Postgres database reaches the schema (src/db/engine/postgres/schema-bootstrap.ts):
* the three states the plan names (empty, foreign tables, TREK's own) and the
* safety net before pending migrations, over a fake migrator and connection.
*/
import type { AppEnv } from '../../../../../src/app-config';
import {
bootstrapPostgresSchema,
postgresSafetyNet,
sqliteLeftBehindCheck,
type PostgresBootstrapDeps,
} from '../../../../../src/db/engine/postgres/schema-bootstrap';
import type { MigrationSafetyNet } from '../../../../../src/db/legacy-baseline';
import type { AnyOrm } from '../../../../../src/db/orm';
import { answersSchema, failsWith, installFakeTool, writesFile } from '../../../../helpers/fake-pg-tools';
import { Logger } from '@nestjs/common';
import { mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const M1 = 'Migration20200101000000_baseline_schema';
const M2 = 'Migration20200101000100_second';
const M3 = 'Migration20200101000200_after_the_cut';
interface FakeDb {
executed: string[];
pending: string[];
tables: string[];
/** Whether mikro_orm_migrations exists: from the start when anything is recorded. */
history: boolean;
ensureTable: ReturnType<typeof vi.fn>;
sql: string[];
logged: string[];
inTransaction: boolean[];
up: ReturnType<typeof vi.fn>;
/** What the server reports before anything is written: its current schema, version and the role's privilege. */
server: { schema: string | null; version: string; privileged: boolean };
/** The ORM's migrations option, which the bootstrap points at the current schema. */
migrations: { tableName?: string };
/** Whether the users table holds a row: a database in use does. */
accounts: boolean;
/** The transaction the history table was created in, when it was created in one. */
historyCreatedIn: unknown;
/** A baseline statement that fails, as on a server without ICU. */
failingBaseline?: boolean;
}
type FakeState = Pick<FakeDb, 'executed' | 'pending' | 'tables'> & {
history?: boolean;
failingBaseline?: boolean;
server?: Partial<FakeDb['server']>;
accounts?: boolean;
};
function fakeOrm(state: FakeState): {
orm: AnyOrm;
db: FakeDb;
} {
const db: FakeDb = {
...state,
server: { schema: 'public', version: '170004', privileged: false, ...state.server },
migrations: { tableName: 'mikro_orm_migrations' },
history: state.history ?? state.executed.length > 0,
accounts: state.accounts ?? true,
// Like MikroORM's: created on the storage's master transaction, and
// committed on its own when there is none.
ensureTable: vi.fn(async () => {
db.history = true;
db.historyCreatedIn = master;
}),
historyCreatedIn: undefined,
sql: [],
logged: [],
inTransaction: [],
up: vi.fn(async () => undefined),
};
const trx = { trx: true };
let master: unknown;
const connection = {
execute: vi.fn(async (sql: string, _params?: unknown[], _method?: string, ctx?: unknown) => {
if (sql.includes('server_version_num')) return [db.server];
if (sql.includes('from users')) return db.accounts ? [{ present: 1 }] : [];
if (sql.includes('information_schema.tables')) {
return [...db.tables, ...(db.history ? ['mikro_orm_migrations'] : [])].map((table_name) => ({ table_name }));
}
db.sql.push(sql);
db.inTransaction.push(ctx === trx);
if (db.failingBaseline) throw new Error('collation provider "icu" is not supported on this platform');
return [];
}),
// A failed transaction takes back what was created in it.
transactional: vi.fn(async (work: (ctx: unknown) => Promise<void>) => {
try {
await work(trx);
} catch (err) {
if (db.historyCreatedIn === trx) db.history = false;
throw err;
}
}),
};
const storage = {
ensureTable: db.ensureTable,
setMasterMigration: (ctx: unknown) => {
master = ctx;
},
unsetMasterMigration: () => {
master = undefined;
},
logMigration: vi.fn(async ({ name }: { name: string }, ctx?: unknown) => {
db.logged.push(name);
db.inTransaction.push(ctx === trx);
db.executed = [...db.executed, name];
db.pending = db.pending.filter((pending) => pending !== name);
}),
};
const migrator = {
getStorage: () => storage,
getExecuted: vi.fn(async () => db.executed.map((name) => ({ name }))),
getPending: vi.fn(async () => db.pending.map((name) => ({ name }))),
up: db.up,
};
const orm = {
config: { getExtension: () => migrator, get: () => db.migrations },
em: { getConnection: () => connection },
} as unknown as AnyOrm;
return { orm, db };
}
function deps(
safetyNet: MigrationSafetyNet = { beforeMigrate: vi.fn(async () => undefined), restoreHint: async () => null },
sqliteLeftBehind: () => string | null = () => null,
) {
const value: PostgresBootstrapDeps = {
baseline: () => ({
through: M2,
migrations: [M1, M2],
statements: ['create table "a" ("id" bigserial)', 'create index "x" on "a" ("id")'],
}),
known: new Set([M1, M2, M3]),
safetyNet,
sqliteLeftBehind,
};
return value;
}
afterEach(() => vi.restoreAllMocks());
describe('bootstrapPostgresSchema', () => {
beforeEach(() => {
vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
});
it('PGBOOT-001: an empty database gets the baseline and its migrations recorded, all in one transaction', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [] });
const net = deps();
await bootstrapPostgresSchema(orm, net);
expect(db.sql).toEqual(['create table "a" ("id" bigserial);\ncreate index "x" on "a" ("id")']);
expect(db.logged).toEqual([M1, M2]);
expect(db.inTransaction.every(Boolean)).toBe(true);
expect(db.up).not.toHaveBeenCalled();
expect(net.safetyNet.beforeMigrate).not.toHaveBeenCalled();
});
it('PGBOOT-002: a fresh database runs the migrations after the cut without the safety net (nothing to lose)', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2, M3], tables: [] });
const net = deps();
await bootstrapPostgresSchema(orm, net);
expect(db.logged).toEqual([M1, M2]);
expect(db.up).toHaveBeenCalledTimes(1);
expect(net.safetyNet.beforeMigrate).not.toHaveBeenCalled();
});
it('PGBOOT-003: tables without TREK history are refused, named, and nothing is written', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1], tables: ['customers', 'orders'] });
await expect(bootstrapPostgresSchema(orm, deps())).rejects.toThrow(
/Refusing to boot: the database holds 2 table\(s\) \(customers, orders\) but no TREK migration history/,
);
expect(db.sql).toEqual([]);
expect(db.logged).toEqual([]);
expect(db.ensureTable).not.toHaveBeenCalled();
});
it('PGBOOT-009: the history table is created inside the baseline transaction, so a failed first boot leaves no table', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [], failingBaseline: true });
await expect(bootstrapPostgresSchema(orm, deps())).rejects.toThrow('collation provider "icu"');
expect(db.ensureTable).toHaveBeenCalledTimes(1);
expect(db.historyCreatedIn).toEqual({ trx: true });
// Nothing is left that would make RESTORE_FROM_BACKUP take it for a database in use.
expect(db.history).toBe(false);
const fresh = fakeOrm({ executed: [], pending: [M1, M2], tables: [] });
await bootstrapPostgresSchema(fresh.orm, deps());
expect(fresh.db.historyCreatedIn).toEqual({ trx: true });
});
it('PGBOOT-008: an empty history table beside no other table is a fresh database (a first boot cut short)', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [], history: true });
await bootstrapPostgresSchema(orm, deps());
expect(db.logged).toEqual([M1, M2]);
});
it('PGBOOT-004: a database a newer TREK migrated is refused before anything runs', async () => {
const { orm, db } = fakeOrm({ executed: [M1, 'Migration20990101000000_from_the_future'], pending: [], tables: [] });
await expect(bootstrapPostgresSchema(orm, deps())).rejects.toThrow(/migrated by a newer TREK/);
expect(db.up).not.toHaveBeenCalled();
});
it('PGBOOT-005: pending migrations on a database in use run after the safety net, labelled by the last one', async () => {
const { orm, db } = fakeOrm({ executed: [M2, M1], pending: [M3], tables: ['users'] });
const net = deps();
await bootstrapPostgresSchema(orm, net);
expect(net.safetyNet.beforeMigrate).toHaveBeenCalledWith('20200101000100');
expect(db.up).toHaveBeenCalledTimes(1);
expect(db.sql).toEqual([]);
});
it('PGBOOT-006: a refusing safety net stops the migration', async () => {
const { orm, db } = fakeOrm({ executed: [M1, M2], pending: [M3], tables: ['users'] });
const refusing = {
beforeMigrate: vi.fn(async () => Promise.reject(new Error('no copy'))),
restoreHint: async () => null,
};
await expect(bootstrapPostgresSchema(orm, deps(refusing))).rejects.toThrow('no copy');
expect(db.up).not.toHaveBeenCalled();
});
it('PGBOOT-007: a database at head does nothing', async () => {
const { orm, db } = fakeOrm({ executed: [M1, M2, M3], pending: [], tables: ['users'] });
const net = deps();
await bootstrapPostgresSchema(orm, net);
expect(db.sql).toEqual([]);
expect(db.up).not.toHaveBeenCalled();
expect(net.safetyNet.beforeMigrate).not.toHaveBeenCalled();
});
it.each([
{ id: 'PGBOOT-020a', version: '130016', major: 13 },
{ id: 'PGBOOT-020b', version: '190000', major: 19 },
])('$id: a server outside 14 to 18 is refused before anything is read or written', async ({ version, major }) => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [], server: { version } });
await expect(bootstrapPostgresSchema(orm, deps())).rejects.toThrow(
`Refusing to boot: the Postgres server is version ${major}; TREK supports PostgreSQL 14 to 18.`,
);
expect(db.sql).toEqual([]);
expect(db.ensureTable).not.toHaveBeenCalled();
});
it.each(['140019', '180001'])(
'PGBOOT-021: the oldest and the newest supported servers boot (%s)',
async (version) => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [], server: { version } });
await bootstrapPostgresSchema(orm, deps());
expect(db.logged).toEqual([M1, M2]);
},
);
it('PGBOOT-022: the migration history is looked for in the current schema, where the tables are', async () => {
const { orm, db } = fakeOrm({ executed: [M1, M2, M3], pending: [], tables: ['users'], server: { schema: 'trek' } });
await bootstrapPostgresSchema(orm, deps());
expect(db.migrations.tableName).toBe('trek.mikro_orm_migrations');
// A second bootstrap (a restore's reopen) keeps the same name.
await bootstrapPostgresSchema(orm, deps());
expect(db.migrations.tableName).toBe('trek.mikro_orm_migrations');
});
it.each([
{ id: 'PGBOOT-023a', schema: null, message: /has no current schema/ },
{ id: 'PGBOOT-023b', schema: 'a.b', message: /the current schema "a\.b", whose name holds a dot/ },
])('$id: a role without a usable current schema is refused', async ({ schema, message }) => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1], tables: [], server: { schema } });
await expect(bootstrapPostgresSchema(orm, deps())).rejects.toThrow(message);
expect(db.ensureTable).not.toHaveBeenCalled();
});
const LEFT_BEHIND = '/app/data/travel.db';
const noNet = () => ({ beforeMigrate: vi.fn(async () => undefined), restoreHint: async () => null });
it('PGBOOT-030: an empty database beside a SQLite install with accounts is refused before anything is written', async () => {
const { orm, db } = fakeOrm({ executed: [], pending: [M1, M2], tables: [] });
await expect(
bootstrapPostgresSchema(
orm,
deps(noNet(), () => LEFT_BEHIND),
),
).rejects.toThrow(
/Refusing to boot: TREK_DB_URL points at a Postgres database that holds no TREK data, while \/app\/data\/travel\.db .*move-to-postgres.*TREK_DB_IGNORE_SQLITE_FILE=true/s,
);
expect(db.sql).toEqual([]);
expect(db.ensureTable).not.toHaveBeenCalled();
});
it('PGBOOT-031: a schema without a single account (a move cut short) beside such an install is refused too', async () => {
const { orm, db } = fakeOrm({ executed: [M1, M2], pending: [M3], tables: ['users'], accounts: false });
const net = deps(noNet(), () => LEFT_BEHIND);
await expect(bootstrapPostgresSchema(orm, net)).rejects.toThrow(/holds no TREK data/);
expect(db.up).not.toHaveBeenCalled();
expect(net.safetyNet.beforeMigrate).not.toHaveBeenCalled();
});
it('PGBOOT-032: a database in use never looks at the SQLite file', async () => {
const { orm, db } = fakeOrm({ executed: [M1, M2, M3], pending: [], tables: ['users'] });
const leftBehind = vi.fn(() => LEFT_BEHIND);
await bootstrapPostgresSchema(orm, deps(noNet(), leftBehind));
expect(leftBehind).not.toHaveBeenCalled();
expect(db.up).not.toHaveBeenCalled();
});
it('PGBOOT-033: a database with foreign tables keeps its own refusal; without a SQLite install an empty one boots', async () => {
const foreign = fakeOrm({ executed: [], pending: [M1], tables: ['customers'] });
await expect(
bootstrapPostgresSchema(
foreign.orm,
deps(noNet(), () => LEFT_BEHIND),
),
).rejects.toThrow(/no TREK migration history/);
const empty = fakeOrm({ executed: [], pending: [M1, M2], tables: [] });
await bootstrapPostgresSchema(
empty.orm,
deps(noNet(), () => null),
);
expect(empty.db.logged).toEqual([M1, M2]);
});
it('PGBOOT-024: a role that could reach the database host boots with a warning', async () => {
const warn = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
const { orm } = fakeOrm({ executed: [M1, M2, M3], pending: [], tables: ['users'], server: { privileged: true } });
await bootstrapPostgresSchema(orm, deps());
expect(warn).toHaveBeenCalledWith(expect.stringMatching(/Restores are refused for such a role/));
});
});
describe('sqliteLeftBehindCheck', () => {
const envWith = (isTest: boolean, ignoreSqliteFile: boolean) => () =>
({ db: { trekDbFile: '/data/travel.db', ignoreSqliteFile }, app: { isTest } }) as unknown as AppEnv;
it('PGBOOT-034: names the SQLite file when it holds accounts, and nothing when it holds none', () => {
expect(sqliteLeftBehindCheck(envWith(false, false), () => true)()).toBe('/data/travel.db');
expect(sqliteLeftBehindCheck(envWith(false, false), () => false)()).toBeNull();
});
it('PGBOOT-035: TREK_DB_IGNORE_SQLITE_FILE lets the boot through with a warning', () => {
const warn = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
expect(sqliteLeftBehindCheck(envWith(false, true), () => true)()).toBeNull();
expect(warn).toHaveBeenCalledWith(expect.stringContaining('TREK_DB_IGNORE_SQLITE_FILE is set'));
});
it('PGBOOT-036: stays out of the way under test, without opening the file', () => {
const holds = vi.fn(() => true);
expect(sqliteLeftBehindCheck(envWith(true, false), holds)()).toBeNull();
expect(holds).not.toHaveBeenCalled();
});
});
describe('postgresSafetyNet', () => {
const URL = 'postgresql://trek:pw@db/trek';
const NOW = new Date('2026-11-02T13:05:09Z');
let dir: string;
let bin: string;
beforeEach(() => {
dir = mkdtempSync(path.join(tmpdir(), 'trek-pg-net-'));
bin = mkdtempSync(path.join(tmpdir(), 'trek-pg-net-bin-'));
vi.spyOn(Logger.prototype, 'log').mockImplementation(() => undefined);
});
afterEach(() => {
rmSync(dir, { recursive: true, force: true });
rmSync(bin, { recursive: true, force: true });
});
/**
* A stand-in pg_dump that writes its --file, or fails like one that cannot
* connect, beside the psql that names the schema the dump is limited to.
*/
const fakePgDump = (ok: boolean) => {
installFakeTool(bin, 'pg_dump', { snippets: [ok ? writesFile('dump') : failsWith('could not connect')] });
installFakeTool(bin, 'psql', { snippets: [answersSchema()] });
};
const envWith =
(preMigrateSnapshot: boolean | undefined, isTest: boolean, keep = 3) =>
() =>
({
db: { preMigrateSnapshot, preMigrateSnapshotKeep: keep, pgBinDir: bin },
app: { isTest },
}) as unknown as AppEnv;
const net = (env: () => AppEnv) =>
postgresSafetyNet(
URL,
env,
() => NOW,
() => dir,
);
it.each([undefined, true])(
'PGBOOT-010: dumps the database before migrating it (setting %s), keeping the newest copies and no half-written one',
async (setting) => {
fakePgDump(true);
for (const old of ['20200101000001', '20200101000002']) {
writeFileSync(path.join(dir, `pre-migrate-${old}-20250101T000000Z.pgdump`), 'old');
utimesSync(path.join(dir, `pre-migrate-${old}-20250101T000000Z.pgdump`), 1, 1);
}
writeFileSync(path.join(dir, 'pre-migrate-20200101000003-20250101T000000Z.pgdump.partial'), 'killed');
await net(envWith(setting, false, 2)).beforeMigrate('20200101000100');
const kept = readdirSync(dir).sort();
expect(kept).toHaveLength(2);
expect(kept).toContain('pre-migrate-20200101000100-20261102T130509Z.pgdump');
expect(kept.some((file) => file.endsWith('.partial'))).toBe(false);
},
);
it('PGBOOT-011: migrates without a copy when the operator turned it off, and says so', async () => {
const warn = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
await expect(net(envWith(false, false)).beforeMigrate('1')).resolves.toBeUndefined();
expect(warn).toHaveBeenCalledWith(expect.stringContaining('without a copy'));
expect(readdirSync(dir)).toEqual([]);
});
it('PGBOOT-012: stays out of the way under test unless a suite asks for it', async () => {
await expect(net(envWith(undefined, true)).beforeMigrate('1')).resolves.toBeUndefined();
expect(readdirSync(dir)).toEqual([]);
});
it('PGBOOT-013: a copy that cannot be written refuses the boot, names the switch, and leaves no partial file', async () => {
fakePgDump(false);
await expect(net(envWith(true, false)).beforeMigrate('1')).rejects.toThrow(
/Refusing to boot: could not write a copy.*pg_dump failed: could not connect.*TREK_DB_PRE_MIGRATE_SNAPSHOT=false/s,
);
expect(readdirSync(dir)).toEqual([]);
});
it('PGBOOT-014: the newer-database refusal points at the copy taken from this release, or at the others', async () => {
const hint = net(envWith(true, false));
await expect(hint.restoreHint('20200101000100')).resolves.toBeNull();
writeFileSync(path.join(dir, 'pre-migrate-20200101000050-20250101T000000Z.pgdump'), 'old');
await expect(hint.restoreHint('20200101000100')).resolves.toMatch(/none of them from this release/);
writeFileSync(path.join(dir, 'pre-migrate-20200101000100-20250102T000000Z.pgdump'), 'mine');
await expect(hint.restoreHint('20200101000100')).resolves.toMatch(
/pre-migrate-20200101000100-20250102T000000Z\.pgdump: stop TREK and load it as the wiki page Updating .*pg_restore --no-owner/,
);
});
});