mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 11:36:05 +00:00
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:
@@ -0,0 +1,14 @@
|
||||
/** The databases TREK can run on. MySQL and MariaDB are out of scope (server/CLAUDE.md). */
|
||||
export type EngineId = 'sqlite' | 'postgres';
|
||||
|
||||
/**
|
||||
* Which database this process runs on, as `deriveDb` reads it from
|
||||
* `TREK_DB_URL`. The Postgres arm carries what its pool needs, so nothing
|
||||
* downstream has to check the URL again.
|
||||
*/
|
||||
export type DbEngineSettings = { engine: 'sqlite' } | { engine: 'postgres'; url: string; poolMax: number };
|
||||
|
||||
/** The most connections the Postgres pool opens (`TREK_DB_POOL_MAX` is refused above it). */
|
||||
export const DB_POOL_MAX_CEILING = 100;
|
||||
/** The pool size when `TREK_DB_POOL_MAX` is unset. */
|
||||
export const DB_POOL_MAX_DEFAULT = 10;
|
||||
@@ -14,6 +14,7 @@
|
||||
* call, which is what keeps the runtime env-mutation semantics the test suite
|
||||
* depends on. Zod validation runs once at boot (env.schema.ts), never here.
|
||||
*/
|
||||
import { DB_POOL_MAX_CEILING, DB_POOL_MAX_DEFAULT, type DbEngineSettings } from './db-settings';
|
||||
import { imageVersion } from './image-version';
|
||||
import {
|
||||
csvList,
|
||||
@@ -336,16 +337,23 @@ export function deriveBackup(raw: RawEnv) {
|
||||
};
|
||||
}
|
||||
|
||||
/** The database settings `readEnv().db` answers with. */
|
||||
export type DbSettings = ReturnType<typeof deriveDb>;
|
||||
|
||||
export function deriveDb(raw: RawEnv) {
|
||||
const durability = resolveDurability(raw.TREK_DB_JOURNAL_MODE, raw.TREK_DB_SYNCHRONOUS);
|
||||
const url = raw.TREK_DB_URL?.trim() || undefined;
|
||||
const engine: DbEngineSettings = url
|
||||
? {
|
||||
engine: 'postgres',
|
||||
// The connection URL carries the password, so it is never logged (db/engine/redact-url.ts).
|
||||
url,
|
||||
poolMax: Math.min(positiveIntOr(raw.TREK_DB_POOL_MAX, DB_POOL_MAX_DEFAULT), DB_POOL_MAX_CEILING),
|
||||
}
|
||||
: { engine: 'sqlite' };
|
||||
return {
|
||||
/** Which database this process runs on: Postgres when TREK_DB_URL names one, the SQLite file otherwise. */
|
||||
engine: (url ? 'postgres' : 'sqlite') as 'sqlite' | 'postgres',
|
||||
/** The Postgres connection URL; it carries the password, so never log it (db/engine/redact-url.ts). */
|
||||
url,
|
||||
/** The largest number of connections the Postgres pool opens. */
|
||||
poolMax: Math.min(positiveIntOr(raw.TREK_DB_POOL_MAX, 10), 100),
|
||||
...engine,
|
||||
/** Where pg_dump and pg_restore are; unset, the usual install directories are tried (never PATH). */
|
||||
pgBinDir: raw.TREK_DB_PG_BIN_DIR?.trim() || undefined,
|
||||
trekDbFile: raw.TREK_DB_FILE,
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
* listed here pass through untouched (Zod strips unknown keys, it does not
|
||||
* reject them).
|
||||
*/
|
||||
import { DB_POOL_MAX_CEILING } from './db-settings';
|
||||
import {
|
||||
isP256PrivateKey,
|
||||
isServiceKeyShape,
|
||||
@@ -167,7 +168,7 @@ export const envSchema = z.object({
|
||||
// A Postgres database instead of the SQLite file. Its value is a secret (it
|
||||
// carries the password), so it is masked in the boot report.
|
||||
TREK_DB_URL: postgresUrl,
|
||||
TREK_DB_POOL_MAX: integer(1, 100),
|
||||
TREK_DB_POOL_MAX: integer(1, DB_POOL_MAX_CEILING),
|
||||
TREK_DB_PG_BIN_DIR: anyString,
|
||||
TREK_DB_FILE: anyString,
|
||||
// The two SQLite pragmas are deliberately unvalidated: a typo here must fall
|
||||
|
||||
@@ -2,6 +2,7 @@ export { readEnv, validateEnvAtBoot } from './env';
|
||||
export { getAppUrl, getMcpSafeUrl } from './app-url';
|
||||
export { runningVersion } from './running-version';
|
||||
export type { AppEnv, RawEnv } from './env';
|
||||
export type { DbSettings } from './derive';
|
||||
export {
|
||||
deriveAll,
|
||||
deriveApp,
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
|
||||
@@ -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 });
|
||||
}
|
||||
}
|
||||
@@ -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();
|
||||
}
|
||||
}
|
||||
|
||||
+2
-1
@@ -14,6 +14,7 @@ import { resolveDataPaths } from './app-config/data-paths';
|
||||
// keeping the require after the restore keeps that true by construction.
|
||||
import type * as Bootstrap from './bootstrap';
|
||||
import { resolveDbPath } from './db/db-path';
|
||||
import { postgresTarget } from './db/engine';
|
||||
import { flushLogFileSync, logError } from './nest/audit/audit-log.logger';
|
||||
import type { DatabaseLifecycle } from './nest/database/database-lifecycle.service';
|
||||
import { ReadinessService } from './nest/health/readiness.service';
|
||||
@@ -150,7 +151,7 @@ async function restoreBeforeTheDatabaseOpens() {
|
||||
dbFile: resolveDbPath(),
|
||||
dataDir: paths.dataDir,
|
||||
reclaimResetFile: paths.reclaimResetFile,
|
||||
postgres: env.db.url ? { url: env.db.url, binDir: env.db.pgBinDir } : undefined,
|
||||
postgres: postgresTarget(env.db) ?? undefined,
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
import { buildOrmConfig, resolveEngine } from './db/engine';
|
||||
|
||||
/**
|
||||
* The one MikroORM config, for the CLI and the Nest container alike: the
|
||||
* engine `TREK_DB_URL` names (the SQLite file by default) and what every
|
||||
* engine shares (`db/engine/index.ts`).
|
||||
* The MikroORM config for the CLI and the Nest container alike: the engine
|
||||
* `TREK_DB_URL` names (the SQLite file by default) and what every engine shares
|
||||
* (`db/engine/index.ts`).
|
||||
*
|
||||
* Built at module level, not from `DATABASE_ENGINE`, because the MikroORM CLI
|
||||
* loads this file without Nest. Only the engine's options come from it, and
|
||||
* those are plain values with no state, so it and the container's engine agree
|
||||
* on the database. The state an engine keeps (Postgres's reopen hook) exists
|
||||
* only on the container's instance.
|
||||
*/
|
||||
export default buildOrmConfig(resolveEngine());
|
||||
|
||||
@@ -4,7 +4,9 @@ import { UserSessions } from '../../db/entities/UserSessions.entity';
|
||||
import type { CarriedUserSessionRow } from '../../db/repositories/UserSessions.repository';
|
||||
import { dbNow } from '../../db/types';
|
||||
import { logError, logWarn } from '../audit/audit-log.logger';
|
||||
import type { DatabaseBackupStrategy } from '../database/database-backup.interface';
|
||||
import { describeError } from '../common/describe-error';
|
||||
import { DomainError } from '../common/domain-error';
|
||||
import type { DatabaseBackupRefusal, DatabaseBackupStrategy } from '../database/database-backup.interface';
|
||||
import { invalidatePermissionsCache } from '../permissions/permissions-cache';
|
||||
import { snapshotAllPluginDataDbs } from '../plugins/host/plugin-data.service';
|
||||
import { pluginsCodeRoot, pluginsDataRoot } from '../plugins/paths';
|
||||
@@ -36,8 +38,6 @@ export interface BackupDeps {
|
||||
database: DatabaseBackupStrategy;
|
||||
}
|
||||
|
||||
const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
|
||||
|
||||
// The scratch and key directory. The database itself may live elsewhere
|
||||
// (TREK_DB_FILE); the database port knows where.
|
||||
const { dataDir, encryptionKeyFile, reclaimResetFile } = resolveDataPaths();
|
||||
@@ -467,6 +467,12 @@ async function restoreCarriedSessions(rows: readonly CarriedUserSessionRow[]): P
|
||||
}
|
||||
}
|
||||
|
||||
/** The restore route's refusal for a `verify` that threw one. Any other failure is not a refusal, and keeps propagating. */
|
||||
function refusalOf(err: unknown): DatabaseBackupRefusal {
|
||||
if (err instanceof DomainError) return { error: err.publicMessage, status: err.getStatus() };
|
||||
throw err;
|
||||
}
|
||||
|
||||
export async function restoreFromZip({ storage, database }: BackupDeps, zipPath: string): Promise<RestoreResult> {
|
||||
const extractDir = path.join(dataDir, `restore-${Date.now()}`);
|
||||
let reinitFailed: unknown;
|
||||
@@ -474,7 +480,7 @@ export async function restoreFromZip({ storage, database }: BackupDeps, zipPath:
|
||||
const refused = await extractBackupArchive(zipPath, extractDir);
|
||||
if (refused) return { success: false, ...refused };
|
||||
|
||||
const unreadable = await database.verify(extractDir);
|
||||
const unreadable = await database.verify(extractDir).then(() => null, refusalOf);
|
||||
if (unreadable) {
|
||||
fs.rmSync(extractDir, { recursive: true, force: true });
|
||||
return { success: false, ...unreadable };
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { resolveEngine } from '../../db/engine';
|
||||
import type { DatabaseEngine } from '../../db/engine';
|
||||
import { DATABASE_BACKUP, type DatabaseBackupStrategy } from '../database/database-backup.interface';
|
||||
import { DatabaseEngineModule, DATABASE_ENGINE } from '../database/database-engine.module';
|
||||
import { DatabaseLifecycleModule } from '../database/database-lifecycle.module';
|
||||
import { MaintenanceModule } from '../database/maintenance.module';
|
||||
import { PostgresDatabaseBackup } from './postgres-database-backup';
|
||||
@@ -8,7 +9,7 @@ import { Global, Module } from '@nestjs/common';
|
||||
|
||||
/**
|
||||
* Binds the database backup port (`DATABASE_BACKUP`) to the engine in use
|
||||
* (`TREK_DB_URL`, read at boot through `resolveEngine()`).
|
||||
* (`TREK_DB_URL`, the one `DATABASE_ENGINE` provides).
|
||||
*
|
||||
* Global because its consumers sit in two domains: the backup domain itself
|
||||
* and the admin domain (the demo reset job and the baseline route). Admin
|
||||
@@ -22,15 +23,18 @@ import { Global, Module } from '@nestjs/common';
|
||||
*/
|
||||
@Global()
|
||||
@Module({
|
||||
imports: [DatabaseLifecycleModule, MaintenanceModule],
|
||||
imports: [DatabaseEngineModule, DatabaseLifecycleModule, MaintenanceModule],
|
||||
providers: [
|
||||
SqliteDatabaseBackup,
|
||||
PostgresDatabaseBackup,
|
||||
{
|
||||
provide: DATABASE_BACKUP,
|
||||
useFactory: (sqlite: SqliteDatabaseBackup, postgres: PostgresDatabaseBackup): DatabaseBackupStrategy =>
|
||||
({ sqlite, postgres })[resolveEngine().id],
|
||||
inject: [SqliteDatabaseBackup, PostgresDatabaseBackup],
|
||||
useFactory: (
|
||||
engine: DatabaseEngine,
|
||||
sqlite: SqliteDatabaseBackup,
|
||||
postgres: PostgresDatabaseBackup,
|
||||
): DatabaseBackupStrategy => ({ sqlite, postgres })[engine.id],
|
||||
inject: [DATABASE_ENGINE, SqliteDatabaseBackup, PostgresDatabaseBackup],
|
||||
},
|
||||
],
|
||||
exports: [DATABASE_BACKUP],
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
import { logInfo, logWarn } from '../audit/audit-log.logger';
|
||||
import { describeError } from '../common/describe-error';
|
||||
import { DatabaseConnectionLostError } from '../database/database-backup.interface';
|
||||
|
||||
/** Whether a step ran to the end, and what it threw when it did not. */
|
||||
interface Outcome {
|
||||
failed: boolean;
|
||||
error: unknown;
|
||||
}
|
||||
|
||||
/** Runs `step` and records that it threw even when what it threw is undefined. */
|
||||
async function settle(step: () => void | Promise<void>): Promise<Outcome> {
|
||||
try {
|
||||
await step();
|
||||
return { failed: false, error: null };
|
||||
} catch (error) {
|
||||
return { failed: true, error };
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The restore step both backup ports share. `swap` puts the new database in
|
||||
* place; `reopen` always runs after it, so the process is never left without a
|
||||
* connection. A failed swap rethrows its error, or a DatabaseConnectionLostError
|
||||
* carrying both when the reopen failed too. A swap that landed resolves with the
|
||||
* reopen's error, which the caller reports as "restart required".
|
||||
*/
|
||||
export async function replaceThenReopen(
|
||||
swap: () => void | Promise<void>,
|
||||
reopen: () => Promise<void>,
|
||||
): Promise<{ reopenError: unknown }> {
|
||||
const swapped = await settle(swap);
|
||||
const reopened = await settle(reopen);
|
||||
if (swapped.failed) {
|
||||
if (reopened.failed) throw new DatabaseConnectionLostError(swapped.error, reopened.error);
|
||||
throw swapped.error;
|
||||
}
|
||||
return { reopenError: reopened.failed ? reopened.error : null };
|
||||
}
|
||||
|
||||
/**
|
||||
* Keeps a copy of the database a restore is about to replace, at `target`. Best
|
||||
* effort: a database broken enough to need the restore may not copy, and that
|
||||
* must not block the recovery. Resolves with where the copy went, or null.
|
||||
*/
|
||||
export async function keepRestoreCopy(
|
||||
target: string,
|
||||
snapshot: (target: string) => Promise<void>,
|
||||
): Promise<string | null> {
|
||||
try {
|
||||
await snapshot(target);
|
||||
logInfo(`Restore: the replaced database was kept as ${target}`);
|
||||
return target;
|
||||
} catch (err) {
|
||||
logWarn(`Restore: could not keep a copy of the current database (${describeError(err)})`);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
@@ -1,23 +1,20 @@
|
||||
import { readEnv } from '../../app-config';
|
||||
import { resolveEngine } from '../../db/engine';
|
||||
import type { DbSettings } from '../../app-config';
|
||||
import { postgresTarget, type DatabaseEngine } from '../../db/engine';
|
||||
import { pgDump, pgDumpMigrations, pgRestore } from '../../db/engine/postgres/pg-tools';
|
||||
import { unknownMigrations } from '../../db/known-migrations';
|
||||
import { DataPathsService } from '../app-config/data-paths.service';
|
||||
import { logInfo, logWarn } from '../audit/audit-log.logger';
|
||||
import { logWarn } from '../audit/audit-log.logger';
|
||||
import { describeError } from '../common/describe-error';
|
||||
import { DomainError } from '../common/domain-error';
|
||||
import {
|
||||
DatabaseConnectionLostError,
|
||||
type DatabaseBackupRefusal,
|
||||
type DatabaseBackupStrategy,
|
||||
} from '../database/database-backup.interface';
|
||||
import type { DatabaseBackupStrategy } from '../database/database-backup.interface';
|
||||
import { DATABASE_ENGINE, DATABASE_SETTINGS } from '../database/database-engine.module';
|
||||
import { DatabaseLifecycle } from '../database/database-lifecycle.service';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { keepRestoreCopy, replaceThenReopen } from './database-swap';
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
|
||||
|
||||
/** The name a Postgres database takes inside a backup archive: a pg_dump custom-format file. */
|
||||
export const PG_ARCHIVE_ENTRY = 'travel.pgdump';
|
||||
|
||||
@@ -67,21 +64,25 @@ export async function checkPostgresDump(extractDir: string, binDir: string | und
|
||||
@Injectable()
|
||||
export class PostgresDatabaseBackup implements DatabaseBackupStrategy {
|
||||
readonly archiveEntry = PG_ARCHIVE_ENTRY;
|
||||
/** The URL and the tools' directory; null on SQLite, where this provider is built but never called. */
|
||||
private readonly target: ReturnType<typeof postgresTarget>;
|
||||
|
||||
constructor(
|
||||
private readonly lifecycle: DatabaseLifecycle,
|
||||
private readonly paths: DataPathsService,
|
||||
) {}
|
||||
@Inject(DATABASE_ENGINE) private readonly engine: DatabaseEngine,
|
||||
@Inject(DATABASE_SETTINGS) settings: DbSettings,
|
||||
) {
|
||||
this.target = postgresTarget(settings);
|
||||
}
|
||||
|
||||
/** The URL and the tools' directory, read when used: on SQLite this provider is built but never called. */
|
||||
private get settings(): { url: string; binDir: string | undefined } {
|
||||
const { url, pgBinDir } = readEnv().db;
|
||||
if (!url) throw new Error('The Postgres backup was used without TREK_DB_URL.');
|
||||
return { url, binDir: pgBinDir };
|
||||
private get connection(): { url: string; binDir: string | undefined } {
|
||||
if (!this.target) throw new Error('The Postgres backup was used without TREK_DB_URL.');
|
||||
return this.target;
|
||||
}
|
||||
|
||||
location(): string {
|
||||
return resolveEngine().describe();
|
||||
return this.engine.describe();
|
||||
}
|
||||
|
||||
/** A Postgres database is always there to copy; a missing pg_dump fails the snapshot, loudly. */
|
||||
@@ -95,51 +96,32 @@ export class PostgresDatabaseBackup implements DatabaseBackupStrategy {
|
||||
|
||||
/** pg_dump writes beside `target` and renames into place: a failed dump leaves nothing there. */
|
||||
async snapshot(target: string): Promise<void> {
|
||||
const { url, binDir } = this.settings;
|
||||
const { url, binDir } = this.connection;
|
||||
await pgDump(url, target, binDir);
|
||||
}
|
||||
|
||||
/** Refuses (a DomainError, 400) an archive this database cannot take, before anything is replaced. */
|
||||
async verify(extractDir: string): Promise<DatabaseBackupRefusal | null> {
|
||||
const refusal = await checkPostgresDump(extractDir, this.settings.binDir);
|
||||
/** Throws a DomainError (400) with the refusal when the archive cannot be restored here, before anything is replaced. */
|
||||
async verify(extractDir: string): Promise<void> {
|
||||
const refusal = await checkPostgresDump(extractDir, this.connection.binDir);
|
||||
if (refusal) throw new DomainError(400, refusal);
|
||||
return null;
|
||||
}
|
||||
|
||||
/** A dump of the database a restore is about to replace, in the data directory. */
|
||||
async keepCopyBeforeRestore(): Promise<string | null> {
|
||||
keepCopyBeforeRestore(): Promise<string | null> {
|
||||
const target = path.join(this.paths.dataDir, `pre-restore-${Date.now()}.pgdump`);
|
||||
try {
|
||||
await this.snapshot(target);
|
||||
logInfo(`Restore: the replaced database was kept as ${target}`);
|
||||
return target;
|
||||
} catch (err) {
|
||||
logWarn(`Restore: could not keep a copy of the current database (${describeError(err)})`);
|
||||
return null;
|
||||
}
|
||||
return keepRestoreCopy(target, (copy) => this.snapshot(copy));
|
||||
}
|
||||
|
||||
async replace(source: string): Promise<{ reopenError: unknown }> {
|
||||
let swapError: unknown = null;
|
||||
try {
|
||||
const { url, binDir } = this.settings;
|
||||
await pgRestore(url, source, binDir);
|
||||
} catch (err) {
|
||||
swapError = err ?? new Error('pg_restore failed');
|
||||
}
|
||||
|
||||
// As on SQLite: the reopen always runs, so the ORM never keeps a stale pool,
|
||||
// and both errors go up together when the restore failed as well.
|
||||
let reopenError: unknown = null;
|
||||
try {
|
||||
await this.lifecycle.reopen();
|
||||
} catch (err) {
|
||||
reopenError = err;
|
||||
}
|
||||
if (swapError) {
|
||||
if (reopenError) throw new DatabaseConnectionLostError(swapError, reopenError);
|
||||
throw swapError;
|
||||
}
|
||||
return { reopenError };
|
||||
replace(source: string): Promise<{ reopenError: unknown }> {
|
||||
return replaceThenReopen(
|
||||
async () => {
|
||||
const { url, binDir } = this.connection;
|
||||
// A rejection with no reason still has to fail the swap, so it is never swallowed.
|
||||
await pgRestore(url, source, binDir).catch((err: unknown) => {
|
||||
throw err ?? new Error('pg_restore failed');
|
||||
});
|
||||
},
|
||||
() => this.lifecycle.reopen(),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,29 +1,22 @@
|
||||
import { SqliteMaintenance } from '../../db/engine/sqlite/sqlite-maintenance';
|
||||
import { logInfo, logWarn } from '../audit/audit-log.logger';
|
||||
import {
|
||||
DatabaseConnectionLostError,
|
||||
type DatabaseBackupRefusal,
|
||||
type DatabaseBackupStrategy,
|
||||
} from '../database/database-backup.interface';
|
||||
import { DomainError } from '../common/domain-error';
|
||||
import type { DatabaseBackupStrategy } from '../database/database-backup.interface';
|
||||
import { DatabaseLifecycle } from '../database/database-lifecycle.service';
|
||||
import { checkBackupDatabase } from './backup-archive';
|
||||
import { keepRestoreCopy, replaceThenReopen } from './database-swap';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
|
||||
import fs from 'fs';
|
||||
import path from 'path';
|
||||
|
||||
const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
|
||||
|
||||
/**
|
||||
* The backup port for the one engine TREK runs on: a SQLite file.
|
||||
* The backup port on a SQLite file, the engine TREK runs on by default.
|
||||
*
|
||||
* Every step is what `backup.impl.ts` and `demo/demo-reset.ts` did inline
|
||||
* before the port existed. A snapshot is `VACUUM INTO`, which takes a
|
||||
* consistent copy even under concurrent writers. A restore closes the
|
||||
* connection, swaps the file by copy and rename (a crash mid-swap leaves the
|
||||
* old or the new file, never neither), drops the old `-wal`/`-shm` sidecars,
|
||||
* and reopens through `DatabaseLifecycle`, which migrates the restored file
|
||||
* forward.
|
||||
* A snapshot is `VACUUM INTO`, which takes a consistent copy even under
|
||||
* concurrent writers. A restore closes the connection, swaps the file by copy
|
||||
* and rename (a crash mid-swap leaves the old or the new file, never neither),
|
||||
* drops the old `-wal`/`-shm` sidecars, and reopens through `DatabaseLifecycle`,
|
||||
* which migrates the restored file forward.
|
||||
*
|
||||
* The file is always `DatabaseLifecycle.file`, the path the connection was
|
||||
* opened on, so `TREK_DB_FILE` moves the backup, the restore and the demo reset
|
||||
@@ -62,66 +55,42 @@ export class SqliteDatabaseBackup implements DatabaseBackupStrategy {
|
||||
}
|
||||
}
|
||||
|
||||
async verify(extractDir: string): Promise<DatabaseBackupRefusal | null> {
|
||||
return checkBackupDatabase(extractDir);
|
||||
/** Throws a DomainError carrying the refusal when the archive's database cannot be restored here. */
|
||||
async verify(extractDir: string): Promise<void> {
|
||||
const refusal = checkBackupDatabase(extractDir);
|
||||
if (refusal) throw new DomainError(refusal.status, refusal.error);
|
||||
}
|
||||
|
||||
/**
|
||||
* A copy of the database a restore is about to replace, next to it. The swap
|
||||
* deletes the current file, and a restore of the wrong archive used to leave
|
||||
* nothing to go back to.
|
||||
*/
|
||||
async keepCopyBeforeRestore(): Promise<string | null> {
|
||||
/** A copy of the database a restore is about to replace, next to it: the swap deletes the current file. */
|
||||
keepCopyBeforeRestore(): Promise<string | null> {
|
||||
const target = path.join(path.dirname(this.lifecycle.file), `pre-restore-${Date.now()}.db`);
|
||||
try {
|
||||
await this.snapshot(target);
|
||||
logInfo(`Restore: the replaced database was kept as ${target}`);
|
||||
return target;
|
||||
} catch (err) {
|
||||
logWarn(`Restore: could not keep a copy of the current database (${describeError(err)})`);
|
||||
return null;
|
||||
}
|
||||
return keepRestoreCopy(target, (copy) => this.snapshot(copy));
|
||||
}
|
||||
|
||||
async replace(source: string): Promise<{ reopenError: unknown }> {
|
||||
const dest = this.lifecycle.file;
|
||||
this.lifecycle.close();
|
||||
let swapFailed = false;
|
||||
let swapError: unknown = null;
|
||||
try {
|
||||
// Copy to a temp file on the SAME filesystem, drop the old sidecars (they
|
||||
// belong to the database being replaced and would corrupt the new one),
|
||||
// then rename into place. The rename is atomic.
|
||||
const tmp = dest + '.restore-tmp';
|
||||
fs.copyFileSync(source, tmp);
|
||||
for (const ext of ['-wal', '-shm']) {
|
||||
try {
|
||||
fs.unlinkSync(dest + ext);
|
||||
} catch {
|
||||
/* no sidecar to drop */
|
||||
}
|
||||
}
|
||||
fs.renameSync(tmp, dest);
|
||||
} catch (err) {
|
||||
swapFailed = true;
|
||||
swapError = err;
|
||||
}
|
||||
|
||||
// Reopening must always run, even when the swap threw, so the process is
|
||||
// never left without a connection. After a swap that landed, a reopen
|
||||
// failure is reported, not thrown: the files are in place and the caller
|
||||
// has to say "restart". After a swap that failed, both errors go up
|
||||
// together, because the swap's alone would hide that the connection is gone.
|
||||
let reopenError: unknown = null;
|
||||
try {
|
||||
await this.lifecycle.reopen();
|
||||
} catch (err) {
|
||||
reopenError = err;
|
||||
}
|
||||
if (swapFailed) {
|
||||
if (reopenError) throw new DatabaseConnectionLostError(swapError, reopenError);
|
||||
throw swapError;
|
||||
}
|
||||
return { reopenError };
|
||||
return replaceThenReopen(
|
||||
() => swapFile(source, dest),
|
||||
() => this.lifecycle.reopen(),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Puts `source` at `dest` by copying it to a temp file on the same filesystem
|
||||
* and renaming it into place. The old sidecars go first: they belong to the
|
||||
* database being replaced and would corrupt the new one.
|
||||
*/
|
||||
function swapFile(source: string, dest: string): void {
|
||||
const tmp = dest + '.restore-tmp';
|
||||
fs.copyFileSync(source, tmp);
|
||||
for (const ext of ['-wal', '-shm']) {
|
||||
try {
|
||||
fs.unlinkSync(dest + ext);
|
||||
} catch {
|
||||
/* no sidecar to drop */
|
||||
}
|
||||
}
|
||||
fs.renameSync(tmp, dest);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
/** The message of an error, or the value itself as text when it is not an Error (a thrown string, say). */
|
||||
export const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
|
||||
@@ -1,14 +1,15 @@
|
||||
import { describeError } from '../common/describe-error';
|
||||
|
||||
/**
|
||||
* How a backup, a restore and the demo reset get at the core database, without
|
||||
* knowing which engine holds it.
|
||||
*
|
||||
* The admin backup (`nest/backup/backup.impl.ts`), its restore, and the demo
|
||||
* baseline save and hourly reset (`demo/demo-reset.ts`) all go through this
|
||||
* port. The only implementation today is `SqliteDatabaseBackup`
|
||||
* (`nest/backup/`), which does what those paths always did: `VACUUM INTO` for a
|
||||
* consistent copy of the file, a file swap under a closed connection for a
|
||||
* restore. An engine that is not one local file would plug in here with a
|
||||
* logical dump and load instead.
|
||||
* port. Each engine has an adapter in `nest/backup/`, chosen by the engine in
|
||||
* use: SQLite copies the file (`VACUUM INTO`) and swaps it under a closed
|
||||
* connection; Postgres dumps and restores it with pg_dump and pg_restore. The
|
||||
* two adapters answer every method the same way, so the callers do not branch.
|
||||
*
|
||||
* Lives in the shared database kernel, not in the backup domain, so the admin
|
||||
* domain (the demo reset job, the baseline route) can inject it without
|
||||
@@ -43,10 +44,10 @@ export interface DatabaseBackupStrategy {
|
||||
|
||||
/**
|
||||
* Checks an unpacked archive's database before anything is replaced. Resolves
|
||||
* with null when it can be restored, or the refusal in the restore route's
|
||||
* words (an engine may throw a DomainError with it instead).
|
||||
* when it can be restored; otherwise throws a DomainError (status 400) that
|
||||
* carries the refusal in the restore route's words.
|
||||
*/
|
||||
verify(extractDir: string): Promise<DatabaseBackupRefusal | null>;
|
||||
verify(extractDir: string): Promise<void>;
|
||||
|
||||
/**
|
||||
* Keeps a copy of the database a restore is about to replace. Best effort: a
|
||||
@@ -68,7 +69,7 @@ export interface DatabaseBackupStrategy {
|
||||
replace(source: string): Promise<{ reopenError: unknown }>;
|
||||
}
|
||||
|
||||
/** A refusal in the restore route's own words and status. */
|
||||
/** A refusal in the restore route's own words and status, as `verify` reports it. */
|
||||
export interface DatabaseBackupRefusal {
|
||||
error: string;
|
||||
status: number;
|
||||
@@ -77,8 +78,6 @@ export interface DatabaseBackupRefusal {
|
||||
/** Injection token for the active `DatabaseBackupStrategy`. */
|
||||
export const DATABASE_BACKUP = Symbol('DATABASE_BACKUP');
|
||||
|
||||
const describeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
|
||||
|
||||
/**
|
||||
* Thrown by `replace` when the swap failed and the reopen that always follows
|
||||
* failed too. The process is left without a database connection until a
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
import { readEnv, type DbSettings } from '../../app-config';
|
||||
import { resolveEngine, type DatabaseEngine } from '../../db/engine';
|
||||
import { Module } from '@nestjs/common';
|
||||
|
||||
/** `readEnv().db`, read once per container: what decides which engine runs and its settings. */
|
||||
export const DATABASE_SETTINGS = Symbol('DATABASE_SETTINGS');
|
||||
|
||||
/**
|
||||
* The one `DatabaseEngine` of this process. Every injector (the lifecycle, the
|
||||
* unit of work, the backup port and its adapters) gets this instance, so the
|
||||
* state an engine keeps (Postgres's reopen hook) is the same wherever it is used.
|
||||
*/
|
||||
export const DATABASE_ENGINE = Symbol('DATABASE_ENGINE');
|
||||
|
||||
/**
|
||||
* Provides the engine and its settings. Not global: each module that needs
|
||||
* the engine imports it, and Nest keeps one instance per container.
|
||||
*/
|
||||
@Module({
|
||||
providers: [
|
||||
{ provide: DATABASE_SETTINGS, useFactory: (): DbSettings => readEnv().db },
|
||||
{
|
||||
provide: DATABASE_ENGINE,
|
||||
useFactory: (db: DbSettings): DatabaseEngine => resolveEngine(db),
|
||||
inject: [DATABASE_SETTINGS],
|
||||
},
|
||||
],
|
||||
exports: [DATABASE_SETTINGS, DATABASE_ENGINE],
|
||||
})
|
||||
export class DatabaseEngineModule {}
|
||||
@@ -1,3 +1,4 @@
|
||||
import { DatabaseEngineModule } from './database-engine.module';
|
||||
import { DatabaseLifecycle } from './database-lifecycle.service';
|
||||
import { Module } from '@nestjs/common';
|
||||
|
||||
@@ -6,5 +7,5 @@ import { Module } from '@nestjs/common';
|
||||
* import it by name, so a partial test harness that never touches the
|
||||
* connection lifecycle does not have to supply the `MikroORM` it injects.
|
||||
*/
|
||||
@Module({ providers: [DatabaseLifecycle], exports: [DatabaseLifecycle] })
|
||||
@Module({ imports: [DatabaseEngineModule], providers: [DatabaseLifecycle], exports: [DatabaseLifecycle] })
|
||||
export class DatabaseLifecycleModule {}
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
import { resolveDbPath } from '../../db/db-path';
|
||||
import { resolveEngine } from '../../db/engine';
|
||||
import type { DatabaseEngine } from '../../db/engine';
|
||||
import { DATABASE_ENGINE } from './database-engine.module';
|
||||
import { MikroORM } from '@mikro-orm/core';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
|
||||
/**
|
||||
* The one owner of the core database connection's lifecycle: open, close and
|
||||
@@ -12,19 +13,21 @@ import { Injectable } from '@nestjs/common';
|
||||
* replace that module wholesale with `vi.mock`. What moved here is every
|
||||
* decision about WHEN it opens and closes: `buildApp()` opens through this,
|
||||
* a restore and the demo reset close and reopen through this (via the backup
|
||||
* port), and the shutdown closes through this. Nothing opens the database at
|
||||
* import any more; the first connect does, and this provider makes it explicit.
|
||||
* port), and the shutdown closes through this. The ORM's first connect is what
|
||||
* actually opens the file; this provider makes that step explicit.
|
||||
*
|
||||
* What differs by engine (a file to open or not, how a database reaches the
|
||||
* schema) is the engine's (`db/engine/`), chosen from `TREK_DB_URL`: this
|
||||
* What differs by engine (a file to open or not, how a reopen reaches the ORM)
|
||||
* is the engine's (`db/engine/`), the one `DATABASE_ENGINE` provides: this
|
||||
* provider decides when, the engine decides how.
|
||||
*/
|
||||
@Injectable()
|
||||
export class DatabaseLifecycle {
|
||||
private readonly reopenListeners: Array<() => Promise<void>> = [];
|
||||
private readonly engine = resolveEngine();
|
||||
|
||||
constructor(private readonly orm: MikroORM) {}
|
||||
constructor(
|
||||
private readonly orm: MikroORM,
|
||||
@Inject(DATABASE_ENGINE) private readonly engine: DatabaseEngine,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* The database file this process runs on, resolved the one way every caller
|
||||
@@ -36,14 +39,14 @@ export class DatabaseLifecycle {
|
||||
}
|
||||
|
||||
/**
|
||||
* Opens the connection, binds the ORM to its later swaps and brings the schema
|
||||
* to head (on SQLite: legacy baseline, migrations, the deferred index,
|
||||
* Opens the connection, points the engine's reopen at the ORM and brings the
|
||||
* schema to head (on SQLite: legacy baseline, migrations, the deferred index,
|
||||
* seeders, demo seed, in that order, see `db/orm.ts`; on Postgres: the
|
||||
* baseline or the migrations after it, then the same seeding). Called once
|
||||
* by `buildApp()`, before anything reads the database.
|
||||
*/
|
||||
async open(): Promise<void> {
|
||||
this.engine.open(() => this.rebindOrm());
|
||||
this.engine.open(this.orm, () => this.afterReopen());
|
||||
await this.engine.schemaBootstrap(this.orm, { snapshot: true });
|
||||
}
|
||||
|
||||
@@ -53,9 +56,9 @@ export class DatabaseLifecycle {
|
||||
}
|
||||
|
||||
/**
|
||||
* Reopens the connection after its file was replaced, rebuilds the ORM's
|
||||
* cached client around the new handle and migrates the new file forward (a
|
||||
* restored backup may predate this release).
|
||||
* Reopens the connection after the database was replaced. The engine points
|
||||
* the ORM at the new database first; then `afterReopen` migrates it forward
|
||||
* and runs the listeners.
|
||||
*/
|
||||
async reopen(): Promise<void> {
|
||||
await this.engine.reopen();
|
||||
@@ -76,22 +79,11 @@ export class DatabaseLifecycle {
|
||||
}
|
||||
|
||||
/**
|
||||
* Kysely caches whatever handle it was given, so without this the ORM would
|
||||
* keep talking to the closed one. Closing and reconnecting sends the driver
|
||||
* back through `createKyselyDialect()`, which picks up the new handle. An
|
||||
* engine whose reopen keeps the connection (Postgres) skips that and only
|
||||
* migrates.
|
||||
* What follows a reopen once the engine has pointed the ORM at the reopened
|
||||
* database. No pre-migrate snapshot: the file was just unpacked from an
|
||||
* archive that is still there to go back to.
|
||||
*/
|
||||
private async rebindOrm(): Promise<void> {
|
||||
if (this.engine.reopenSwapsConnection) {
|
||||
const connection = this.orm.em.getConnection();
|
||||
// The handle is owned and closed by `db/database.ts`; the bound driver's
|
||||
// `destroy()` is a no-op (see `orm-driver.ts`), so this close never reaches it.
|
||||
await connection.close(true);
|
||||
await connection.connect();
|
||||
}
|
||||
// No pre-migrate snapshot: the file was just unpacked from an archive that
|
||||
// is still there to go back to.
|
||||
private async afterReopen(): Promise<void> {
|
||||
await this.engine.schemaBootstrap(this.orm, { snapshot: false });
|
||||
for (const listener of this.reopenListeners) await listener();
|
||||
}
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { DatabaseEngineModule } from './database-engine.module';
|
||||
import { UnitOfWork } from './unit-of-work';
|
||||
import { Global, Module } from '@nestjs/common';
|
||||
|
||||
@@ -10,10 +11,11 @@ import { Global, Module } from '@nestjs/common';
|
||||
* (`Test.createTestingModule({ imports: [DatabaseModule, ...] })`)
|
||||
* with no ORM in the container: a provider there that injects the core
|
||||
* `EntityManager` fails every one of them at `compile()`, because Nest
|
||||
* instantiates providers eagerly. Nothing is imported here — the
|
||||
* `EntityManager` token comes from `MikroOrmModule.forRoot`, whose
|
||||
* `MikroOrmCoreModule` is itself `@Global()`.
|
||||
* instantiates providers eagerly. The `EntityManager` token comes from
|
||||
* `MikroOrmModule.forRoot`, whose
|
||||
* `MikroOrmCoreModule` is itself `@Global()`. It imports `DatabaseEngineModule`,
|
||||
* the engine the unit of work serializes its writes through.
|
||||
*/
|
||||
@Global()
|
||||
@Module({ providers: [UnitOfWork], exports: [UnitOfWork] })
|
||||
@Module({ imports: [DatabaseEngineModule], providers: [UnitOfWork], exports: [UnitOfWork] })
|
||||
export class OrmModule {}
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
import { resolveEngine } from '../../db/engine';
|
||||
import type { DatabaseEngine } from '../../db/engine';
|
||||
import { DATABASE_ENGINE } from './database-engine.module';
|
||||
import { EntityManager } from '@mikro-orm/core';
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { Inject, Injectable } from '@nestjs/common';
|
||||
|
||||
/**
|
||||
* The one way a service opens a transaction.
|
||||
@@ -26,9 +27,10 @@ import { Injectable } from '@nestjs/common';
|
||||
*/
|
||||
@Injectable()
|
||||
export class UnitOfWork {
|
||||
private readonly engine = resolveEngine();
|
||||
|
||||
constructor(private readonly em: EntityManager) {}
|
||||
constructor(
|
||||
private readonly em: EntityManager,
|
||||
@Inject(DATABASE_ENGINE) private readonly engine: DatabaseEngine,
|
||||
) {}
|
||||
|
||||
transactional<T>(fn: () => Promise<T>): Promise<T> {
|
||||
return this.em.transactional(async (em) => {
|
||||
|
||||
Reference in New Issue
Block a user