refactor(db): type the database settings and inject one engine

The settings for the database were one flat record whose url and pool size
were meaningful only for Postgres, so every reader had to re-check the URL.
They are now a discriminated union per engine (DbEngineSettings): the
Postgres arm carries its URL and a pool size already capped at the ceiling,
and the SQLite arm carries nothing else. The env schema uses the same ceiling
constant, so the boot check and the derivation cannot drift apart.

The engine was resolved from the environment by every caller that needed it
(the lifecycle, the unit of work, the backup adapters), each building its own
instance. The engine is now provided once per container by
DatabaseEngineModule and injected everywhere, so the state an engine keeps
(Postgres's reopen hook) is the same wherever it is used. resolveEngine stays
for the MikroORM CLI config and the DI factory, and nothing else calls it.

The engine's reopen no longer carries a `reopenSwapsConnection` flag. The
engine itself decides what a reopen needs: SQLite closes and reconnects the
ORM's connection before the schema bootstrap (its handle is swapped under
Kysely's cache), and Postgres only migrates, because a restore replaces the
contents of the database the pool already reaches. The Postgres pool is never
closed on a reopen, since ending it waits for connections lent out during the
restore.

The backup ports answer every method the same way. verify() now throws a
DomainError for a refused archive on both engines, and the restore path maps
it back to the same { success: false, error, status } result, so the HTTP
response of a refused restore (status and body) is unchanged. The restore
step that swaps the database and then always reopens it is shared in
nest/backup/database-swap.ts, with the error-description helper in
nest/common, instead of two copies that could drift.
This commit is contained in:
Isaias Tavares
2026-11-05 00:56:39 -03:00
parent 1c3dc93716
commit 98533f3dbe
66 changed files with 639 additions and 351 deletions
+11 -15
View File
@@ -1,9 +1,7 @@
import type { EngineId } from '../../app-config/db-settings';
import type { AnyOrm } from '../orm';
import type { EntityManager, Options } from '@mikro-orm/core';
/** The databases TREK can be pointed at. MySQL/MariaDB are out of scope (server/CLAUDE.md). */
type EngineId = 'sqlite' | 'postgres';
/**
* One database engine: what the ORM needs to reach it, how the connection
* opens, closes and comes back after a restore, and how a database is brought
@@ -22,21 +20,19 @@ export interface DatabaseEngine {
/** What MikroORM needs to reach the database: the driver and its target, the pool, driver options. */
ormOptions(): Partial<Options>;
/**
* Whether a reopen hands the ORM a different connection, so its client has
* to be closed and connected again around it. SQLite swaps the file under
* one handle; a Postgres restore replaces the contents of the same database,
* which the pool's connections keep reaching.
* Called once at boot, before the schema bootstrap. `onReopened` runs after
* each later reopen, once the ORM is pointed at the reopened database: the
* engine does what its own reopen needs first (SQLite hands the ORM a new
* handle, so the ORM's connection is closed and connected again), then calls
* it, and the caller migrates the database and runs whatever follows.
*/
readonly reopenSwapsConnection: boolean;
/**
* Called once at boot, before the schema bootstrap. `onReopened` is what
* has to follow a later reopen (rebinding the ORM, migrating the restored
* database forward).
*/
open(onReopened: () => Promise<void>): void;
open(orm: AnyOrm, onReopened: () => Promise<void>): void;
/** Closes what the engine itself holds; the ORM's own pool is closed with the Nest container. */
close(): void;
/** Comes back after the database was replaced by a restore, then runs `onReopened`. */
/**
* Comes back after the database was replaced by a restore, then runs the
* `onReopened` that `open` registered. Throws when `open` has not run.
*/
reopen(): Promise<void>;
/**
* Brings the database to the current schema, then seeds it. `snapshot:
+15 -2
View File
@@ -1,4 +1,6 @@
import { readEnv } from '../../app-config';
import type { DbEngineSettings } from '../../app-config/db-settings';
import type { DbSettings } from '../../app-config/derive';
import { ALL_ENTITIES } from '../entities';
import type { DatabaseEngine } from './engine';
import { PostgresEngine } from './postgres/postgres-engine';
@@ -15,11 +17,22 @@ export type { DatabaseEngine } from './engine';
* call, like everything `readEnv()` answers, so nothing caches a choice a test
* or a restart changes.
*/
export function resolveEngine(db: ReturnType<typeof readEnv>['db'] = readEnv().db): DatabaseEngine {
if (db.engine === 'postgres' && db.url) return new PostgresEngine({ url: db.url, poolMax: db.poolMax });
export function resolveEngine(db: DbEngineSettings = readEnv().db): DatabaseEngine {
if (db.engine === 'postgres') return new PostgresEngine(db);
return new SqliteEngine();
}
/**
* The Postgres URL and the directory of its client tools, when the settings
* name a Postgres database; null on SQLite. For the code that drives pg_dump
* and pg_restore, which needs both and must not read them from the environment
* again.
*/
export function postgresTarget(db: DbSettings): { url: string; binDir: string | undefined } | null {
if (db.engine !== 'postgres') return null;
return { url: db.url, binDir: db.pgBinDir };
}
/**
* The MikroORM config for `engine`: what every engine shares (entities,
* migrations, seeders) and what the engine adds. `src/mikro-orm.config.ts`
@@ -1,59 +1,15 @@
import type { DbEngineSettings } from '../../../app-config/db-settings';
import { NO_SAFETY_NET } from '../../legacy-baseline';
import { finishSchemaBootstrap, type AnyOrm } from '../../orm';
import type { DatabaseEngine } from '../engine';
import { redactUrl } from '../redact-url';
import { TrekPostgreSqlDriver } from './postgres-driver';
import { bootstrapPostgresSchema, defaultPostgresBootstrapDeps, type PostgresBootstrapDeps } from './schema-bootstrap';
import { sslOptionFor } from './ssl';
import type { EntityManager } from '@mikro-orm/core';
import { readFileSync } from 'node:fs';
/** What `TREK_DB_URL` and `TREK_DB_POOL_MAX` resolve to (`readEnv().db`). */
export interface PostgresSettings {
url: string;
poolMax: number;
}
/** The `ssl` option of a `pg` pool, as `sslOptionFor` builds it. */
export type PgSslOption = false | { rejectUnauthorized: true; ca?: string };
/** The sslmode values that verify the server, read the way the `pg` driver reads them. */
const VERIFYING_MODES = new Set(['require', 'verify-ca', 'verify-full']);
/**
* The `ssl` option for the pool, from the URL's `sslmode` and `sslrootcert`.
*
* MikroORM builds the pool from the URL's host, port, user, password and
* database alone and drops the rest of the query, so an `sslmode` in
* `TREK_DB_URL` would be ignored without this. `require`, `verify-ca` and
* `verify-full` all verify the server's certificate, as the `pg` driver itself
* treats them; `disable` turns SSL off, and no `sslmode` leaves the driver's
* default (no SSL). A mode that would connect without verifying (`prefer`,
* `allow`, `no-verify`) or that is misspelt refuses, rather than quietly
* connecting with less than was asked. `sslrootcert` names the CA file a host
* that signs its own certificates needs (Supabase's, say).
*/
export function sslOptionFor(url: string): PgSslOption | undefined {
const params = new URL(url).searchParams;
const mode = params.get('sslmode');
const rootCert = params.get('sslrootcert');
if (mode === null) {
if (rootCert !== null) throw new Error('TREK_DB_URL names an sslrootcert without sslmode=verify-full.');
return undefined;
}
if (mode === 'disable') return false;
if (!VERIFYING_MODES.has(mode)) {
throw new Error(
`TREK_DB_URL has sslmode "${mode}"; use disable, require, verify-ca or verify-full (all but disable verify the server).`,
);
}
if (rootCert === null) return { rejectUnauthorized: true };
try {
return { rejectUnauthorized: true, ca: readFileSync(rootCert, 'utf8') };
} catch (error) {
throw new Error(`TREK_DB_URL names sslrootcert ${rootCert}, which cannot be read.`, { cause: error });
}
}
/** What `TREK_DB_URL` and `TREK_DB_POOL_MAX` resolve to, when they name a Postgres database. */
type PostgresSettings = Extract<DbEngineSettings, { engine: 'postgres' }>;
/** The advisory lock key every write transaction takes: "TREK" in ASCII. */
const TREK_WRITE_LOCK = 0x5452454b;
@@ -67,12 +23,6 @@ const TREK_WRITE_LOCK = 0x5452454b;
*/
export class PostgresEngine implements DatabaseEngine {
readonly id = 'postgres';
/**
* The pool stays: ending it waits for every connection it has lent out, and
* one lent to a job while the restore ran was never handed back to the
* ending pool, so the restore never returned.
*/
readonly reopenSwapsConnection = false;
constructor(
private readonly settings: PostgresSettings,
@@ -81,8 +31,14 @@ export class PostgresEngine implements DatabaseEngine {
private onReopened: (() => Promise<void>) | null = null;
/** Nothing of its own to open (the ORM connects the pool); keeps what a reopen runs. */
open(onReopened: () => Promise<void>): void {
/**
* Nothing of its own to open: the ORM connects the pool. Keeps what a reopen
* runs. A reopen replaces the database's contents, which the pool's own
* connections keep reaching, so the ORM is not pointed at anything new and
* the pool is never closed (ending a pool waits for every connection it has
* lent out, and one lent to a job during the restore would never come back).
*/
open(_orm: AnyOrm, onReopened: () => Promise<void>): void {
this.onReopened = onReopened;
}
+42
View File
@@ -0,0 +1,42 @@
import { readFileSync } from 'node:fs';
/** The sslmode values that verify the server, read the way the `pg` driver reads them. */
const VERIFYING_MODES = new Set(['require', 'verify-ca', 'verify-full']);
/** The `ssl` option of a `pg` pool, as `sslOptionFor` builds it. */
type PgSslOption = false | { rejectUnauthorized: true; ca?: string };
/**
* The `ssl` option for the pool, from the URL's `sslmode` and `sslrootcert`.
*
* MikroORM builds the pool from the URL's host, port, user, password and
* database alone and drops the rest of the query, so an `sslmode` in
* `TREK_DB_URL` would be ignored without this. `require`, `verify-ca` and
* `verify-full` all verify the server's certificate, as the `pg` driver itself
* treats them; `disable` turns SSL off, and no `sslmode` leaves the driver's
* default (no SSL). A mode that would connect without verifying (`prefer`,
* `allow`, `no-verify`) or that is misspelt refuses, rather than quietly
* connecting with less than was asked. `sslrootcert` names the CA file a host
* that signs its own certificates needs (Supabase's, say).
*/
export function sslOptionFor(url: string): PgSslOption | undefined {
const params = new URL(url).searchParams;
const mode = params.get('sslmode');
const rootCert = params.get('sslrootcert');
if (mode === null) {
if (rootCert !== null) throw new Error('TREK_DB_URL names an sslrootcert without sslmode=verify-full.');
return undefined;
}
if (mode === 'disable') return false;
if (!VERIFYING_MODES.has(mode)) {
throw new Error(
`TREK_DB_URL has sslmode "${mode}"; use disable, require, verify-ca or verify-full (all but disable verify the server).`,
);
}
if (rootCert === null) return { rejectUnauthorized: true };
try {
return { rejectUnauthorized: true, ca: readFileSync(rootCert, 'utf8') };
} catch (error) {
throw new Error(`TREK_DB_URL names sslrootcert ${rootCert}, which cannot be read.`, { cause: error });
}
}
+17 -6
View File
@@ -14,7 +14,6 @@ import type { EntityManager } from '@mikro-orm/core';
*/
export class SqliteEngine implements DatabaseEngine {
readonly id = 'sqlite';
readonly reopenSwapsConnection = true;
describe(): string {
return `SQLite file ${resolveDbPath()}`;
@@ -24,11 +23,23 @@ export class SqliteEngine implements DatabaseEngine {
return { driver: SharedSqliteDriver, dbName: resolveDbPath() };
}
open(onReopened: () => Promise<void>): void {
// Normally a no-op: the ORM's first connect inside NestFactory.create()
// already opened it. Said here so the boot does not depend on that.
/**
* Opens the file (normally a no-op: the ORM's first connect inside
* NestFactory.create() already did, said here so the boot does not depend on
* that), and registers the reopen. A reopen swaps the file under the same
* handle, which Kysely caches, so the ORM's connection is closed and connected
* again first: the driver then reaches the new handle through
* `createKyselyDialect()`. The bound driver's `destroy()` is a no-op
* (`orm-driver.ts`), so the close never reaches the handle `db/database.ts` owns.
*/
open(orm: AnyOrm, onReopened: () => Promise<void>): void {
getRawConnection();
registerReinitializeHook(onReopened);
registerReinitializeHook(async () => {
const connection = orm.em.getConnection();
await connection.close(true);
await connection.connect();
await onReopened();
});
}
close(): void {
@@ -43,8 +54,8 @@ export class SqliteEngine implements DatabaseEngine {
return runSchemaBootstrap(orm, options);
}
/** A no-op: SQLite has one connection and one writer, so its transactions already run one at a time. */
serializeWrites(_em: EntityManager): Promise<void> {
// One connection, one writer: SQLite serializes the transactions already.
return Promise.resolve();
}
}