Files
TREK/server/tests/unit/db/engine/postgres/schema-bootstrap.test.ts
T
Maurice 6f4dfc486f fix(db): check the Postgres server and tools before a dump or a restore
- The client tools are looked for newest first, from 18 down: a client
  handles every server up to its own major and refuses a newer one. A dump
  or a restore now refuses a client older than the server up front, naming
  both versions, and the boot refuses a server outside PostgreSQL 14 to 18.
- sslrootcert=system is used only by a client from libpq 16 on; an older
  client is refused with a message that names sslrootcert and the bin dir.
- The restore's CVE-2025-8714 table covers 18.
- A restore refuses a role that is a superuser or may run programs or write
  files on the database host, since the archive's SQL runs as that role;
  the boot warns about such a role.
- pg_restore's script is streamed to its work file and stopped once it
  passes BACKUP_MAX_DECOMPRESSED_MB, so a small dump can no longer expand
  without limit on the data volume.
- A failed tool's error keeps only the summarized stderr; its cause names
  the exit code and signal instead of carrying the process error, whose
  message and stderr quoted row data into the log.
- The migration history is looked for in the current schema, where the
  tables and the backups are, so a role whose search_path is not public
  boots a second time.
2026-11-17 12:23:51 +01:00

325 lines
14 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,
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 };
}
type FakeState = Pick<FakeDb, 'executed' | 'pending' | 'tables'> & {
history?: boolean;
server?: Partial<FakeDb['server']>;
};
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,
ensureTable: vi.fn(async () => {
db.history = true;
}),
sql: [],
logged: [],
inTransaction: [],
up: vi.fn(async () => undefined),
};
const trx = { trx: true };
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('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);
return [];
}),
transactional: vi.fn(async (work: (ctx: unknown) => Promise<void>) => work(trx)),
};
const storage = {
ensureTable: db.ensureTable,
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 },
) {
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,
};
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-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('PGBOOT-021: the oldest and the newest supported servers boot', async () => {
for (const version of ['140019', '180001']) {
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();
});
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('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, empty the database .*pg_restore --no-owner/,
);
});
});