/** * 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; sql: string[]; logged: string[]; inTransaction: boolean[]; up: ReturnType; /** 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 & { history?: boolean; failingBaseline?: boolean; server?: Partial; 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) => { 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/, ); }); });