refactor(db): split the Postgres client-tool module by concern

pg-tools.ts held six concerns in 366 lines: tool resolution and process
running, the libpq connection environment, the CVE-2025-8714 version policy,
the CLEAR-SCHEMA SQL and the operations themselves. Each now has its own
module, and pg-tools.ts keeps only the operations the backup and the boot
restore call, so their import paths do not change.

- pg-process.ts: PgTool, resolvePgTool, pgConnectionEnv, PgToolMissingError
  and run (stderr is summarized there, as before).
- restore-safety.ts: hasRestrictFix and the refusal. The minimum versions in
  the error are built from the RESTRICT_SINCE table, so the message cannot
  drift from the policy.
- clear-schema.ts: the SQL that empties the schema before a load, unchanged.

The version floor also no longer keeps its own OLDEST_MAJOR and
LAST_MAJOR_WITHOUT_IT constants: both are read from the table. Behaviour is
unchanged. The literal /dev/null is os.devNull, and the COPY parsing of a
dump's migration history is its own function.
This commit is contained in:
Isaias Tavares
2026-11-05 00:20:22 -03:00
parent ae005fc582
commit 1c73ac4c35
5 changed files with 242 additions and 216 deletions
@@ -0,0 +1,41 @@
/**
* Drops every table, view, sequence, routine, collation and standalone type in
* the current schema, except an extension's, before a dump is loaded: a dump
* only recreates what it holds, so whatever a later migration added would
* otherwise survive the restore and break the migrations the reopen runs. It
* runs in the same transaction as the load (`pgRestore`), so a restore that
* fails leaves the database as it was.
*/
export const CLEAR_SCHEMA_SQL = `DO $clear$
DECLARE r record;
BEGIN
FOR r IN SELECT c.oid::regclass AS name, c.relkind FROM pg_class c
WHERE c.relnamespace = current_schema()::regnamespace AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype IN ('e', 'a', 'i'))
LOOP
EXECUTE format('DROP %s IF EXISTS %s CASCADE',
CASE r.relkind WHEN 'v' THEN 'VIEW' WHEN 'm' THEN 'MATERIALIZED VIEW' WHEN 'S' THEN 'SEQUENCE'
WHEN 'f' THEN 'FOREIGN TABLE' ELSE 'TABLE' END, r.name);
END LOOP;
FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p
WHERE p.pronamespace = current_schema()::regnamespace
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.deptype = 'e')
LOOP
EXECUTE format('DROP ROUTINE IF EXISTS %s CASCADE', r.sig);
END LOOP;
FOR r IN SELECT format('%I.%I', n.nspname, c.collname) AS name FROM pg_collation c
JOIN pg_namespace n ON n.oid = c.collnamespace
WHERE n.nspname = current_schema()
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype = 'e')
LOOP
EXECUTE format('DROP COLLATION IF EXISTS %s CASCADE', r.name);
END LOOP;
FOR r IN SELECT t.oid::regtype AS name FROM pg_type t
WHERE t.typnamespace = current_schema()::regnamespace AND t.typtype IN ('e', 'd', 'r')
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = t.oid AND d.deptype IN ('e', 'i'))
LOOP
EXECUTE format('DROP TYPE IF EXISTS %s CASCADE', r.name);
END LOOP;
END
$clear$;
`;
+119
View File
@@ -0,0 +1,119 @@
import { execFile } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
/** The Postgres client tools a backup runs. */
export type PgTool = 'pg_dump' | 'pg_restore' | 'psql';
/**
* Where the client tools are looked for when `TREK_DB_PG_BIN_DIR` is unset:
* Debian's versioned directories newest first (the Docker image installs 17),
* then the usual prefixes. Never PATH: a binary is run by its absolute path.
*/
const DEFAULT_BIN_DIRS = [
'/usr/lib/postgresql/17/bin',
'/usr/lib/postgresql/16/bin',
'/usr/lib/postgresql/15/bin',
'/usr/lib/postgresql/14/bin',
'/usr/local/bin',
'/usr/bin',
];
/** A dump or a restore of a large database takes minutes, not hours. */
const TOOL_TIMEOUT_MS = 30 * 60 * 1000;
const TOOL_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
/** An unreachable host fails the tool in seconds instead of holding a boot or a restore. */
const CONNECT_TIMEOUT_SECONDS = '10';
/** How much of a tool's stderr an error keeps. */
const STDERR_LIMIT = 2000;
/** stderr lines that quote SQL or row data: they stay out of errors and logs. */
const DATA_LINE = /^\s*(Command was:|CONTEXT:|DETAIL:|LINE \d+:|QUERY:)/;
/** The absolute path of `tool`, or null when it is not installed where TREK looks. */
export function resolvePgTool(tool: PgTool, binDir: string | undefined): string | null {
const dirs = binDir ? [binDir] : DEFAULT_BIN_DIRS;
const executable = (candidate: string): boolean => {
try {
fs.accessSync(candidate, fs.constants.X_OK);
return true;
} catch {
return false; // missing or not executable: the next directory may have it
}
};
return dirs.map((dir) => path.join(dir, tool)).find(executable) ?? null;
}
/**
* The libpq environment for `url`: the tools read the password from
* PGPASSWORD, so it never appears in an argument list another process can
* read. An sslmode that asks for SSL verifies the server's certificate, as the
* app's own pool does (`postgres-engine.ts`): against the URL's sslrootcert,
* else the system's trusted CAs.
*/
export function pgConnectionEnv(url: string): Record<string, string> {
const parsed = new URL(url);
const env: Record<string, string> = {
PGHOST: parsed.hostname.replace(/^\[(.*)\]$/, '$1'),
PGPORT: parsed.port || '5432',
PGDATABASE: decodeURIComponent(parsed.pathname.replace(/^\//, '')),
PGCONNECT_TIMEOUT: CONNECT_TIMEOUT_SECONDS,
};
if (parsed.username) env.PGUSER = decodeURIComponent(parsed.username);
if (parsed.password) env.PGPASSWORD = decodeURIComponent(parsed.password);
const sslmode = parsed.searchParams.get('sslmode');
if (sslmode === 'disable') env.PGSSLMODE = 'disable';
else if (sslmode) {
env.PGSSLMODE = 'verify-full';
env.PGSSLROOTCERT = parsed.searchParams.get('sslrootcert') ?? 'system';
}
return env;
}
/** A client tool, refused with a clear message when it is not installed. */
export class PgToolMissingError extends Error {
constructor(tool: PgTool) {
super(
`${tool} was not found, so a Postgres database cannot be backed up or restored. ` +
'Install the PostgreSQL client tools (the Docker image has them) or point TREK_DB_PG_BIN_DIR at them.',
);
this.name = 'PgToolMissingError';
}
}
/** The tool's own message, without the lines that quote SQL or rows, and bounded. */
function summarizeStderr(stderr: string | undefined): string {
const kept = (stderr ?? '')
.split('\n')
.filter((line) => line.trim() !== '' && !DATA_LINE.test(line))
.join('\n');
return kept.length > STDERR_LIMIT ? `${kept.slice(0, STDERR_LIMIT)}…` : kept;
}
/**
* Runs `tool` by its absolute path and resolves with its stdout. A failure
* throws `<tool> failed: <its stderr, summarized>`, with the original error as
* the cause.
*/
export async function run(
tool: PgTool,
binDir: string | undefined,
args: string[],
env: Record<string, string>,
): Promise<string> {
const binary = resolvePgTool(tool, binDir);
if (!binary) throw new PgToolMissingError(tool);
try {
const { stdout } = await execFileAsync(binary, args, {
env,
timeout: TOOL_TIMEOUT_MS,
maxBuffer: TOOL_MAX_OUTPUT_BYTES,
});
return stdout;
} catch (err) {
const message = summarizeStderr((err as { stderr?: string }).stderr);
throw new Error(`${tool} failed${message ? `: ${message}` : ''}`, { cause: err });
}
}
+29 -207
View File
@@ -1,166 +1,18 @@
import { execFile } from 'node:child_process';
import { CLEAR_SCHEMA_SQL } from './clear-schema';
import { pgConnectionEnv, run } from './pg-process';
import { refuseToolsWithoutRestrict } from './restore-safety';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import readline from 'node:readline';
import { promisify } from 'node:util';
const execFileAsync = promisify(execFile);
/** The Postgres client tools a backup runs. */
type PgTool = 'pg_dump' | 'pg_restore' | 'psql';
/**
* Where the client tools are looked for when `TREK_DB_PG_BIN_DIR` is unset:
* Debian's versioned directories newest first (the Docker image installs 17),
* then the usual prefixes. Never PATH: a binary is run by its absolute path.
*/
const DEFAULT_BIN_DIRS = [
'/usr/lib/postgresql/17/bin',
'/usr/lib/postgresql/16/bin',
'/usr/lib/postgresql/15/bin',
'/usr/lib/postgresql/14/bin',
'/usr/local/bin',
'/usr/bin',
];
/** A dump or a restore of a large database takes minutes, not hours. */
const TOOL_TIMEOUT_MS = 30 * 60 * 1000;
const TOOL_MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
/** An unreachable host fails the tool in seconds instead of holding a boot or a restore. */
const CONNECT_TIMEOUT_SECONDS = '10';
/**
* A restore waiting on a lock another session holds gives up, and rolls back,
* instead of hanging; the NOTICEs every CASCADE prints stay out of its stderr.
* Restore's session settings: a restore waiting on a lock another session
* holds gives up, and rolls back, instead of hanging; the NOTICEs every
* CASCADE prints stay out of its stderr.
*/
const RESTORE_SESSION_OPTIONS = '-c lock_timeout=60s -c client_min_messages=warning';
/** How much of a tool's stderr an error keeps. */
const STDERR_LIMIT = 2000;
/** stderr lines that quote SQL or row data: they stay out of errors and logs. */
const DATA_LINE = /^\s*(Command was:|CONTEXT:|DETAIL:|LINE \d+:|QUERY:)/;
/**
* Drops every table, view, sequence, routine, collation and standalone type in
* the current schema, except an extension's, before a dump is loaded: a dump only recreates what it
* holds, so whatever a later migration added would otherwise survive the
* restore and break the migrations the reopen runs. It runs in the same
* transaction as the load, so a restore that fails leaves the database as it
* was.
*/
const CLEAR_SCHEMA_SQL = `DO $clear$
DECLARE r record;
BEGIN
FOR r IN SELECT c.oid::regclass AS name, c.relkind FROM pg_class c
WHERE c.relnamespace = current_schema()::regnamespace AND c.relkind IN ('r', 'p', 'v', 'm', 'S', 'f')
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype IN ('e', 'a', 'i'))
LOOP
EXECUTE format('DROP %s IF EXISTS %s CASCADE',
CASE r.relkind WHEN 'v' THEN 'VIEW' WHEN 'm' THEN 'MATERIALIZED VIEW' WHEN 'S' THEN 'SEQUENCE'
WHEN 'f' THEN 'FOREIGN TABLE' ELSE 'TABLE' END, r.name);
END LOOP;
FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p
WHERE p.pronamespace = current_schema()::regnamespace
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = p.oid AND d.deptype = 'e')
LOOP
EXECUTE format('DROP ROUTINE IF EXISTS %s CASCADE', r.sig);
END LOOP;
FOR r IN SELECT format('%I.%I', n.nspname, c.collname) AS name FROM pg_collation c
JOIN pg_namespace n ON n.oid = c.collnamespace
WHERE n.nspname = current_schema()
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = c.oid AND d.deptype = 'e')
LOOP
EXECUTE format('DROP COLLATION IF EXISTS %s CASCADE', r.name);
END LOOP;
FOR r IN SELECT t.oid::regtype AS name FROM pg_type t
WHERE t.typnamespace = current_schema()::regnamespace AND t.typtype IN ('e', 'd', 'r')
AND NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.objid = t.oid AND d.deptype IN ('e', 'i'))
LOOP
EXECUTE format('DROP TYPE IF EXISTS %s CASCADE', r.name);
END LOOP;
END
$clear$;
`;
/** The absolute path of `tool`, or null when it is not installed where TREK looks. */
export function resolvePgTool(tool: PgTool, binDir: string | undefined): string | null {
const dirs = binDir ? [binDir] : DEFAULT_BIN_DIRS;
const executable = (candidate: string): boolean => {
try {
fs.accessSync(candidate, fs.constants.X_OK);
return true;
} catch {
return false; // missing or not executable: the next directory may have it
}
};
return dirs.map((dir) => path.join(dir, tool)).find(executable) ?? null;
}
/**
* The libpq environment for `url`: the tools read the password from
* PGPASSWORD, so it never appears in an argument list another process can
* read. An sslmode that asks for SSL verifies the server's certificate, as the
* app's own pool does (`postgres-engine.ts`): against the URL's sslrootcert,
* else the system's trusted CAs.
*/
export function pgConnectionEnv(url: string): Record<string, string> {
const parsed = new URL(url);
const env: Record<string, string> = {
PGHOST: parsed.hostname.replace(/^\[(.*)\]$/, '$1'),
PGPORT: parsed.port || '5432',
PGDATABASE: decodeURIComponent(parsed.pathname.replace(/^\//, '')),
PGCONNECT_TIMEOUT: CONNECT_TIMEOUT_SECONDS,
};
if (parsed.username) env.PGUSER = decodeURIComponent(parsed.username);
if (parsed.password) env.PGPASSWORD = decodeURIComponent(parsed.password);
const sslmode = parsed.searchParams.get('sslmode');
if (sslmode === 'disable') env.PGSSLMODE = 'disable';
else if (sslmode) {
env.PGSSLMODE = 'verify-full';
env.PGSSLROOTCERT = parsed.searchParams.get('sslrootcert') ?? 'system';
}
return env;
}
/** A client tool, refused with a clear message when it is not installed. */
export class PgToolMissingError extends Error {
constructor(tool: PgTool) {
super(
`${tool} was not found, so a Postgres database cannot be backed up or restored. ` +
'Install the PostgreSQL client tools (the Docker image has them) or point TREK_DB_PG_BIN_DIR at them.',
);
this.name = 'PgToolMissingError';
}
}
/** The tool's own message, without the lines that quote SQL or rows, and bounded. */
function summarizeStderr(stderr: string | undefined): string {
const kept = (stderr ?? '')
.split('\n')
.filter((line) => line.trim() !== '' && !DATA_LINE.test(line))
.join('\n');
return kept.length > STDERR_LIMIT ? `${kept.slice(0, STDERR_LIMIT)}…` : kept;
}
async function run(
tool: PgTool,
binDir: string | undefined,
args: string[],
env: Record<string, string>,
): Promise<string> {
const binary = resolvePgTool(tool, binDir);
if (!binary) throw new PgToolMissingError(tool);
try {
const { stdout } = await execFileAsync(binary, args, {
env,
timeout: TOOL_TIMEOUT_MS,
maxBuffer: TOOL_MAX_OUTPUT_BYTES,
});
return stdout;
} catch (err) {
// stderr is the tool's own message; the password is in env, never in it.
const message = summarizeStderr((err as { stderr?: string }).stderr);
throw new Error(`${tool} failed${message ? `: ${message}` : ''}`, { cause: err });
}
}
/** An empty file only its owner can read: the tool writing into it keeps the mode. */
function createPrivateFile(file: string): void {
@@ -217,7 +69,6 @@ export async function pgDump(url: string, target: string, binDir: string | undef
'--no-owner',
'--no-privileges',
`--file=${partial}`,
// A pattern in double quotes matches that one name, as written.
`--schema="${schema.name.replaceAll('"', '""')}"`,
],
pgConnectionEnv(url),
@@ -229,44 +80,6 @@ export async function pgDump(url: string, target: string, binDir: string | undef
}
}
/**
* The first minor of each major whose pg_restore and psql carry the fix for
* CVE-2025-8714; every major after 17 has it from its first release.
*/
const RESTRICT_SINCE: Readonly<Record<number, number>> = { 14: 19, 15: 14, 16: 10, 17: 6 };
const LAST_MAJOR_WITHOUT_IT = 17;
const OLDEST_MAJOR = 14;
/** Whether `version` (`pg_restore (PostgreSQL) 17.11 (Debian …)`) carries the fix. */
export function hasRestrictFix(version: string): boolean {
const match = /\(PostgreSQL\) (\d+)\.(\d+)/.exec(version);
if (!match) return false;
const major = Number(match[1]);
const minor = Number(match[2]);
if (major > LAST_MAJOR_WITHOUT_IT) return true;
return major >= OLDEST_MAJOR && minor >= RESTRICT_SINCE[major];
}
/**
* A script from a dump an admin uploaded is run by psql, which would also run
* a psql meta-command (`\!` runs a shell command) smuggled into an object
* name. A fixed pg_restore opens the script with `\restrict <random key>`, and
* a fixed psql then refuses every meta-command until the matching
* `\unrestrict` (CVE-2025-8714). The tools' own versions are checked, not the
* script, whose text the dump controls.
*/
async function refuseToolsWithoutRestrict(binDir: string | undefined): Promise<void> {
const tools = ['pg_restore', 'psql'] as const;
const versions = await Promise.all(tools.map((tool) => run(tool, binDir, ['--version'], {})));
const stale = tools.findIndex((_, i) => !hasRestrictFix(versions[i]));
if (stale >= 0) {
throw new Error(
`${tools[stale]} is too old to restore safely (${versions[stale].trim()}): it must be at least 17.6, 16.10, ` +
'15.14 or 14.19 (the Docker image has 17). Upgrade the PostgreSQL client tools or point TREK_DB_PG_BIN_DIR at newer ones.',
);
}
}
/** Escapes every character a RegExp would read as syntax. */
function escapeRegExp(text: string): string {
return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -328,7 +141,7 @@ export async function pgRestore(url: string, source: string, binDir: string | un
'--quiet',
'--single-transaction',
'--set=ON_ERROR_STOP=1',
'--output=/dev/null',
`--output=${os.devNull}`,
`--file=${clear}`,
`--file=${script}`,
],
@@ -356,18 +169,11 @@ export async function pgTableNames(url: string, binDir: string | undefined): Pro
}
/**
* The migrations a dump records as executed, read from the dump itself (its
* `mikro_orm_migrations` rows as COPY text), so a restore can refuse a newer
* TREK's backup before anything is replaced. Throws on a file that is not a
* dump; an empty list means the dump holds no TREK history.
* The migration names in a restore script's COPY block for
* `mikro_orm_migrations`, read from its `name` column; none when the script
* has no such block.
*/
export async function pgDumpMigrations(source: string, binDir: string | undefined): Promise<string[]> {
const script = await run(
'pg_restore',
binDir,
['--data-only', '--table=mikro_orm_migrations', '--file=-', '--', source],
{},
);
function migrationNamesFromCopy(script: string): string[] {
const lines = script.split('\n');
const copy = lines.findIndex((line) => /^COPY \S*mikro_orm_migrations \(/.test(line));
if (copy < 0) return [];
@@ -386,3 +192,19 @@ export async function pgDumpMigrations(source: string, binDir: string | undefine
}
return names;
}
/**
* The migrations a dump records as executed, read from the dump itself (its
* `mikro_orm_migrations` rows as COPY text), so a restore can refuse a newer
* TREK's backup before anything is replaced. Throws on a file that is not a
* dump; an empty list means the dump holds no TREK history.
*/
export async function pgDumpMigrations(source: string, binDir: string | undefined): Promise<string[]> {
const script = await run(
'pg_restore',
binDir,
['--data-only', '--table=mikro_orm_migrations', '--file=-', '--', source],
{},
);
return migrationNamesFromCopy(script);
}
@@ -0,0 +1,50 @@
import { run } from './pg-process';
/**
* The client-tool versions a restore accepts (CVE-2025-8714). A script from a
* dump an admin uploaded is run by psql, which would also run a psql
* meta-command (`\!` runs a shell command) smuggled into an object name. A
* fixed pg_restore opens the script with `\restrict <random key>`, and a fixed
* psql then refuses every meta-command until the matching `\unrestrict`.
*
* RESTRICT_SINCE holds, per major, the first minor that carries the fix. Every
* major after the last one listed has it from its first release.
*/
const RESTRICT_SINCE: Readonly<Partial<Record<number, number>>> = { 14: 19, 15: 14, 16: 10, 17: 6 };
const LAST_MAJOR_WITHOUT_IT = Math.max(...Object.keys(RESTRICT_SINCE).map(Number));
/** Whether `version` (`pg_restore (PostgreSQL) 17.11 (Debian …)`) carries the fix. */
export function hasRestrictFix(version: string): boolean {
const match = /\(PostgreSQL\) (\d+)\.(\d+)/.exec(version);
if (!match) return false;
const major = Number(match[1]);
const minor = Number(match[2]);
if (major > LAST_MAJOR_WITHOUT_IT) return true;
const firstFixedMinor = RESTRICT_SINCE[major];
return firstFixedMinor !== undefined && minor >= firstFixedMinor;
}
/** The minimum versions as the error names them, newest major first: "17.6, 16.10, 15.14 or 14.19". */
function minimumVersionsText(): string {
const floors = Object.keys(RESTRICT_SINCE)
.map(Number)
.sort((a, b) => b - a)
.map((major) => `${major}.${RESTRICT_SINCE[major]}`);
const last = floors.pop() ?? '';
return floors.length > 0 ? `${floors.join(', ')} or ${last}` : last;
}
/**
* Refuses the restore when pg_restore or psql predates the fix. The tools'
* own versions are checked, not the script, whose text the dump controls.
*/
export async function refuseToolsWithoutRestrict(binDir: string | undefined): Promise<void> {
const tools = ['pg_restore', 'psql'] as const;
const versions = await Promise.all(tools.map((tool) => run(tool, binDir, ['--version'], {})));
const stale = tools.findIndex((_, i) => !hasRestrictFix(versions[i]));
if (stale < 0) return;
throw new Error(
`${tools[stale]} is too old to restore safely (${versions[stale].trim()}): it must be at least ${minimumVersionsText()} ` +
'(the Docker image has 17). Upgrade the PostgreSQL client tools or point TREK_DB_PG_BIN_DIR at newer ones.',
);
}