@rvoh/dream 2.11.1 → 2.11.2

package/dist/cjs/src/db/DreamDbConnection.js

@@ -9,6 +9,7 @@
 import { CamelCasePlugin, Kysely } from 'kysely';
 import DreamApp from '../dream-app/index.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
+import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
 let connections = {};
 export default class DreamDbConnection {
     static getConnection(connectionName, connectionType, dialectProvider) {
@@ -19,6 +20,9 @@ export default class DreamDbConnection {
             return connection;
         }
         const connectionConf = dreamApp.dbConnectionConfig(connectionName, connectionType);
+        // Must run before dialectProvider() constructs the pg.Pool. Idempotent and
+        // a no-op unless DREAM_DB_LEAK_DIAGNOSTICS is set.
+        installDbConnectionLeakDiagnosticsIfEnabled();
         const dbConn = new Kysely({
             log(event) {
                 const dreamApp = DreamApp.getOrFail();
@@ -50,11 +54,51 @@ export async function closeAllDbConnections() {
     }
     connections = {};
 }
+/**
+ * Upper bound (ms) on how long {@link closeAllConnectionsForConnectionName}
+ * waits for a single Kysely connection's underlying pool to drain.
+ *
+ * `conn.destroy()` resolves to `pg`'s `pool.end()`, which only settles once
+ * every checked-out client has been released back to the pool. A client that
+ * was leased by a query still in flight when shutdown began — an aborted HTTP
+ * request during a SIGTERM drain, a feature-spec whose page is torn down
+ * mid-request — is never released, so `pool.end()` blocks forever and takes
+ * the whole shutdown with it. Bounding the wait keeps shutdown deterministic;
+ * the leaked socket is reaped by the OS when the process exits.
+ */
+const DB_CONNECTION_CLOSE_TIMEOUT_MS = 10_000;
 export async function closeAllConnectionsForConnectionName(connectionName) {
     const protectedName = protectAgainstPollutingAssignment(connectionName);
     return await Promise.allSettled(Object.keys(connections[protectedName]).map(async (key) => {
         const conn = connections[protectedName][key];
-        await conn.destroy();
+        // Remove from the registry first so a subsequent getConnection() builds a
+        // fresh pool even if this drain times out and the old pool is abandoned.
         delete connections[protectedName][key];
+        await destroyConnectionWithinTimeout(conn, `${connectionName}:${key}`);
     }));
 }
+async function destroyConnectionWithinTimeout(conn, label) {
+    let timer;
+    const timedOut = Symbol('timedOut');
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve(timedOut), DB_CONNECTION_CLOSE_TIMEOUT_MS);
+        // Don't let the timer itself keep the event loop (or `process.exit`) alive.
+        timer.unref?.();
+    });
+    try {
+        const result = await Promise.race([conn.destroy(), timeout]);
+        if (result === timedOut) {
+            DreamApp.logWithLevel('warn', `[dream] timed out after ${DB_CONNECTION_CLOSE_TIMEOUT_MS}ms waiting for db connection "${label}" ` +
+                `to close; abandoning the drain so shutdown can proceed. A pooled client was most likely held ` +
+                `past shutdown by an in-flight or aborted query. ` +
+                `Re-run with NODE_DEBUG=dream to log the acquire stack of the offending query.`);
+            // No-op unless NODE_DEBUG=dream; when set, this prints the acquire
+            // stack(s) of the client(s) that never got released.
+            reportLeakedDbConnections(label);
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/cjs/src/db/dbConnectionLeakDiagnostics.js

@@ -0,0 +1,117 @@
+// after building for esm, importing pg using the following:
+//
+//  import * as pg from 'pg'
+//
+// will crash. This is difficult to discover, since it only happens
+// when being imported from our esm build.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import pg from 'pg';
+import { debuglog } from 'node:util';
+import DreamApp from '../dream-app/index.js';
+/**
+ * Opt-in connection-leak diagnostics.
+ *
+ * `closeAllConnectionsForConnectionName` bounds the shutdown drain, but when it
+ * times out it can only say *that* a pooled client was held past shutdown, not
+ * *where* it was acquired. Finding the offending query then means hand-patching
+ * `pg` — exactly the multi-hour spelunk this is meant to delete.
+ *
+ * Enable with `NODE_DEBUG=dream` (the same `node:util` debug-channel
+ * convention Psychic uses for `NODE_DEBUG=psychic`). Dev/CI only — it patches
+ * `pg.Pool.prototype.connect` process-wide and retains references to
+ * checked-out clients, so it is never installed unless explicitly asked for.
+ * When the close timeout fires, the acquire stack of every still-checked-out
+ * client is logged.
+ *
+ * Like the rest of the ecosystem's `debuglog` usage, the channel is resolved
+ * once by Node on first call and cached for the process lifetime — this is a
+ * process-level switch, not a runtime toggle.
+ */
+// Resolved once at module load (Node caches the channel), mirroring
+// `const debugEnabled = debuglog('psychic').enabled` in Psychic.
+const dreamDebugEnabled = debuglog('dream').enabled;
+// Map (not WeakMap) so entries can be enumerated at report time. Entries are
+// deleted on release, so only genuinely-leaked clients accumulate, and only
+// when diagnostics are explicitly enabled.
+const checkedOutClients = new Map();
+const INSTALLED = Symbol.for('dream:dbLeakDiagnosticsInstalled');
+let enabled = false;
+function track(client, stack) {
+    if (!client)
+        return;
+    checkedOutClients.set(client, { stack: stack ?? '(no stack captured)', since: Date.now() });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const c = client;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (c.__dreamReleasePatched)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const originalRelease = c.release;
+    if (typeof originalRelease !== 'function')
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.__dreamReleasePatched = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.release = function patchedRelease(...args) {
+        checkedOutClients.delete(client);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+        return originalRelease.apply(this, args);
+    };
+}
+/**
+ * Idempotent. Patches `pg.Pool.prototype.connect` to stamp the caller's stack
+ * onto each leased client. No-op unless `DREAM_DB_LEAK_DIAGNOSTICS` is set.
+ */
+export function installDbConnectionLeakDiagnosticsIfEnabled() {
+    if (!dreamDebugEnabled)
+        return;
+    enabled = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    const Pool = pg.Pool;
+    if (!Pool?.prototype)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (Pool.prototype[INSTALLED])
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype[INSTALLED] = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
+    const originalConnect = Pool.prototype.connect;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype.connect = function patchedConnect(cb) {
+        const acquireStack = new Error('db connection acquired here').stack;
+        if (typeof cb === 'function') {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+            return originalConnect.call(this, (err, client, release) => {
+                track(client, acquireStack);
+                // `track()` replaces `client.release` with an untracking wrapper.
+                // Callback-style users call the 3rd `release` arg, which pg captured
+                // *before* that swap — so hand them the wrapped one instead, or a
+                // correctly-released client would be reported as a false leak.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const wrappedRelease = client ? client.release : release;
+                cb(err, client, wrappedRelease);
+            });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        return originalConnect.call(this).then((client) => {
+            track(client, acquireStack);
+            return client;
+        });
+    };
+}
+/**
+ * If diagnostics are enabled, log the acquire stack of every client still
+ * checked out. Called from the shutdown-drain timeout path.
+ */
+export function reportLeakedDbConnections(label) {
+    if (!enabled || checkedOutClients.size === 0)
+        return;
+    const now = Date.now();
+    const report = Array.from(checkedOutClients.values())
+        .map((entry, i) => `  [#${i}] held ${now - entry.since}ms\n${entry.stack}`)
+        .join('\n\n');
+    DreamApp.logWithLevel('warn', `[dream] connection-leak diagnostics: ${checkedOutClients.size} pg client(s) still checked out ` +
+        `when "${label}" hit the close timeout. Acquired at:\n\n${report}`);
+}

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -92,16 +92,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return _db(connectionName || 'default', dbConnectionType, this.dialectProvider(connectionName, dbConnectionType));
     }
     static dialectProvider(connectionName, dbConnectionType) {
-        return (connectionConf) => new PostgresDialect({
-            pool: new pg.Pool({
+        return (connectionConf) => {
+            const pool = new pg.Pool({
+                // Spread pg passthrough first; Dream's resolved fields follow and
+                // always win (per-connection database name, TLS directive).
+                ...(connectionConf.pg ?? {}),
                 user: connectionConf.user || '',
                 password: connectionConf.password || '',
                 database: DreamApp.getOrFail().dbName(connectionName, dbConnectionType),
                 host: connectionConf.host || 'localhost',
                 port: connectionConf.port || 5432,
                 ssl: resolvePostgresSsl(connectionConf),
-            }),
-        });
+            });
+            // node-postgres explicitly warns: a Pool that emits 'error' with no
+            // listener crashes the Node process. Idle pooled clients emit 'error'
+            // on backend restart / failover / a load balancer reaping idle TCP.
+            // Log via Dream's logger instead of taking the process down; the pool
+            // discards the dead client and recovers on the next acquire.
+            pool.on('error', err => {
+                DreamApp.getOrFail().logger.error(`[dream] idle pg client error on connection "${connectionName}:${dbConnectionType}" ` +
+                    `(handled — process kept alive): ${err.stack ?? String(err)}`);
+            });
+            return new PostgresDialect({ pool });
+        };
     }
     static async ensureAllMigrationsHaveBeenRun(connectionName) {
         const migrationsNeedToBeRun = await checkForNeedToBeRunMigrations({

package/dist/esm/src/db/DreamDbConnection.js

@@ -9,6 +9,7 @@
 import { CamelCasePlugin, Kysely } from 'kysely';
 import DreamApp from '../dream-app/index.js';
 import protectAgainstPollutingAssignment from '../helpers/protectAgainstPollutingAssignment.js';
+import { installDbConnectionLeakDiagnosticsIfEnabled, reportLeakedDbConnections, } from './dbConnectionLeakDiagnostics.js';
 let connections = {};
 export default class DreamDbConnection {
     static getConnection(connectionName, connectionType, dialectProvider) {
@@ -19,6 +20,9 @@ export default class DreamDbConnection {
             return connection;
         }
         const connectionConf = dreamApp.dbConnectionConfig(connectionName, connectionType);
+        // Must run before dialectProvider() constructs the pg.Pool. Idempotent and
+        // a no-op unless DREAM_DB_LEAK_DIAGNOSTICS is set.
+        installDbConnectionLeakDiagnosticsIfEnabled();
         const dbConn = new Kysely({
             log(event) {
                 const dreamApp = DreamApp.getOrFail();
@@ -50,11 +54,51 @@ export async function closeAllDbConnections() {
     }
     connections = {};
 }
+/**
+ * Upper bound (ms) on how long {@link closeAllConnectionsForConnectionName}
+ * waits for a single Kysely connection's underlying pool to drain.
+ *
+ * `conn.destroy()` resolves to `pg`'s `pool.end()`, which only settles once
+ * every checked-out client has been released back to the pool. A client that
+ * was leased by a query still in flight when shutdown began — an aborted HTTP
+ * request during a SIGTERM drain, a feature-spec whose page is torn down
+ * mid-request — is never released, so `pool.end()` blocks forever and takes
+ * the whole shutdown with it. Bounding the wait keeps shutdown deterministic;
+ * the leaked socket is reaped by the OS when the process exits.
+ */
+const DB_CONNECTION_CLOSE_TIMEOUT_MS = 10_000;
 export async function closeAllConnectionsForConnectionName(connectionName) {
     const protectedName = protectAgainstPollutingAssignment(connectionName);
     return await Promise.allSettled(Object.keys(connections[protectedName]).map(async (key) => {
         const conn = connections[protectedName][key];
-        await conn.destroy();
+        // Remove from the registry first so a subsequent getConnection() builds a
+        // fresh pool even if this drain times out and the old pool is abandoned.
         delete connections[protectedName][key];
+        await destroyConnectionWithinTimeout(conn, `${connectionName}:${key}`);
     }));
 }
+async function destroyConnectionWithinTimeout(conn, label) {
+    let timer;
+    const timedOut = Symbol('timedOut');
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve(timedOut), DB_CONNECTION_CLOSE_TIMEOUT_MS);
+        // Don't let the timer itself keep the event loop (or `process.exit`) alive.
+        timer.unref?.();
+    });
+    try {
+        const result = await Promise.race([conn.destroy(), timeout]);
+        if (result === timedOut) {
+            DreamApp.logWithLevel('warn', `[dream] timed out after ${DB_CONNECTION_CLOSE_TIMEOUT_MS}ms waiting for db connection "${label}" ` +
+                `to close; abandoning the drain so shutdown can proceed. A pooled client was most likely held ` +
+                `past shutdown by an in-flight or aborted query. ` +
+                `Re-run with NODE_DEBUG=dream to log the acquire stack of the offending query.`);
+            // No-op unless NODE_DEBUG=dream; when set, this prints the acquire
+            // stack(s) of the client(s) that never got released.
+            reportLeakedDbConnections(label);
+        }
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/esm/src/db/dbConnectionLeakDiagnostics.js

@@ -0,0 +1,117 @@
+// after building for esm, importing pg using the following:
+//
+//  import * as pg from 'pg'
+//
+// will crash. This is difficult to discover, since it only happens
+// when being imported from our esm build.
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
+import pg from 'pg';
+import { debuglog } from 'node:util';
+import DreamApp from '../dream-app/index.js';
+/**
+ * Opt-in connection-leak diagnostics.
+ *
+ * `closeAllConnectionsForConnectionName` bounds the shutdown drain, but when it
+ * times out it can only say *that* a pooled client was held past shutdown, not
+ * *where* it was acquired. Finding the offending query then means hand-patching
+ * `pg` — exactly the multi-hour spelunk this is meant to delete.
+ *
+ * Enable with `NODE_DEBUG=dream` (the same `node:util` debug-channel
+ * convention Psychic uses for `NODE_DEBUG=psychic`). Dev/CI only — it patches
+ * `pg.Pool.prototype.connect` process-wide and retains references to
+ * checked-out clients, so it is never installed unless explicitly asked for.
+ * When the close timeout fires, the acquire stack of every still-checked-out
+ * client is logged.
+ *
+ * Like the rest of the ecosystem's `debuglog` usage, the channel is resolved
+ * once by Node on first call and cached for the process lifetime — this is a
+ * process-level switch, not a runtime toggle.
+ */
+// Resolved once at module load (Node caches the channel), mirroring
+// `const debugEnabled = debuglog('psychic').enabled` in Psychic.
+const dreamDebugEnabled = debuglog('dream').enabled;
+// Map (not WeakMap) so entries can be enumerated at report time. Entries are
+// deleted on release, so only genuinely-leaked clients accumulate, and only
+// when diagnostics are explicitly enabled.
+const checkedOutClients = new Map();
+const INSTALLED = Symbol.for('dream:dbLeakDiagnosticsInstalled');
+let enabled = false;
+function track(client, stack) {
+    if (!client)
+        return;
+    checkedOutClients.set(client, { stack: stack ?? '(no stack captured)', since: Date.now() });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const c = client;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (c.__dreamReleasePatched)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const originalRelease = c.release;
+    if (typeof originalRelease !== 'function')
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.__dreamReleasePatched = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    c.release = function patchedRelease(...args) {
+        checkedOutClients.delete(client);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+        return originalRelease.apply(this, args);
+    };
+}
+/**
+ * Idempotent. Patches `pg.Pool.prototype.connect` to stamp the caller's stack
+ * onto each leased client. No-op unless `DREAM_DB_LEAK_DIAGNOSTICS` is set.
+ */
+export function installDbConnectionLeakDiagnosticsIfEnabled() {
+    if (!dreamDebugEnabled)
+        return;
+    enabled = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    const Pool = pg.Pool;
+    if (!Pool?.prototype)
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (Pool.prototype[INSTALLED])
+        return;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype[INSTALLED] = true;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment
+    const originalConnect = Pool.prototype.connect;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    Pool.prototype.connect = function patchedConnect(cb) {
+        const acquireStack = new Error('db connection acquired here').stack;
+        if (typeof cb === 'function') {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+            return originalConnect.call(this, (err, client, release) => {
+                track(client, acquireStack);
+                // `track()` replaces `client.release` with an untracking wrapper.
+                // Callback-style users call the 3rd `release` arg, which pg captured
+                // *before* that swap — so hand them the wrapped one instead, or a
+                // correctly-released client would be reported as a false leak.
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const wrappedRelease = client ? client.release : release;
+                cb(err, client, wrappedRelease);
+            });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+        return originalConnect.call(this).then((client) => {
+            track(client, acquireStack);
+            return client;
+        });
+    };
+}
+/**
+ * If diagnostics are enabled, log the acquire stack of every client still
+ * checked out. Called from the shutdown-drain timeout path.
+ */
+export function reportLeakedDbConnections(label) {
+    if (!enabled || checkedOutClients.size === 0)
+        return;
+    const now = Date.now();
+    const report = Array.from(checkedOutClients.values())
+        .map((entry, i) => `  [#${i}] held ${now - entry.since}ms\n${entry.stack}`)
+        .join('\n\n');
+    DreamApp.logWithLevel('warn', `[dream] connection-leak diagnostics: ${checkedOutClients.size} pg client(s) still checked out ` +
+        `when "${label}" hit the close timeout. Acquired at:\n\n${report}`);
+}

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -92,16 +92,29 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return _db(connectionName || 'default', dbConnectionType, this.dialectProvider(connectionName, dbConnectionType));
     }
     static dialectProvider(connectionName, dbConnectionType) {
-        return (connectionConf) => new PostgresDialect({
-            pool: new pg.Pool({
+        return (connectionConf) => {
+            const pool = new pg.Pool({
+                // Spread pg passthrough first; Dream's resolved fields follow and
+                // always win (per-connection database name, TLS directive).
+                ...(connectionConf.pg ?? {}),
                 user: connectionConf.user || '',
                 password: connectionConf.password || '',
                 database: DreamApp.getOrFail().dbName(connectionName, dbConnectionType),
                 host: connectionConf.host || 'localhost',
                 port: connectionConf.port || 5432,
                 ssl: resolvePostgresSsl(connectionConf),
-            }),
-        });
+            });
+            // node-postgres explicitly warns: a Pool that emits 'error' with no
+            // listener crashes the Node process. Idle pooled clients emit 'error'
+            // on backend restart / failover / a load balancer reaping idle TCP.
+            // Log via Dream's logger instead of taking the process down; the pool
+            // discards the dead client and recovers on the next acquire.
+            pool.on('error', err => {
+                DreamApp.getOrFail().logger.error(`[dream] idle pg client error on connection "${connectionName}:${dbConnectionType}" ` +
+                    `(handled — process kept alive): ${err.stack ?? String(err)}`);
+            });
+            return new PostgresDialect({ pool });
+        };
     }
     static async ensureAllMigrationsHaveBeenRun(connectionName) {
         const migrationsNeedToBeRun = await checkForNeedToBeRunMigrations({

package/dist/types/src/db/dbConnectionLeakDiagnostics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Idempotent. Patches `pg.Pool.prototype.connect` to stamp the caller's stack
+ * onto each leased client. No-op unless `DREAM_DB_LEAK_DIAGNOSTICS` is set.
+ */
+export declare function installDbConnectionLeakDiagnosticsIfEnabled(): void;
+/**
+ * If diagnostics are enabled, log the acquire stack of every client still
+ * checked out. Called from the shutdown-drain timeout path.
+ */
+export declare function reportLeakedDbConnections(label: string): void;

package/dist/types/src/dream-app/index.d.ts

@@ -1,5 +1,6 @@
 import { CompiledQuery } from 'kysely';
 import type { ConnectionOptions as TlsConnectionOptions } from 'node:tls';
+import type { PoolConfig as PgPoolConfig } from 'pg';
 import { Context } from 'node:vm';
 import Dream from '../Dream.js';
 import QueryDriverBase from '../dream/QueryDriver/Base.js';
@@ -242,6 +243,26 @@ export interface SingleDbCredential {
      * decision at the call site rather than a silent default.
      */
     ssl?: TlsConnectionOptions | false;
+    /**
+     * pg pool/client options passed straight through to `new pg.Pool(...)`.
+     * Dream knows nothing about these fields — pg's own types carry the
+     * documentation. Unset ⇒ pg applies its own defaults (backward compatible).
+     *
+     * Omitted from the passthrough:
+     *  - `user / password / database / host / port / ssl`: Dream manages these
+     *    (per-connection name, TLS directive) — hard invariants.
+     *  - `connectionString`: `pg`'s `ConnectionParameters` re-parses the URL
+     *    and lets its fields take precedence, bypassing Dream's per-connection
+     *    database name and TLS directive. Parse `DATABASE_URL` into the discrete
+     *    `host/port/user/password/name/ssl` fields in `conf/dream.ts` instead.
+     *  - `min`: node-pg's `pg-pool` does not honor it (silent no-op).
+     *  - `types / Client / Promise / log / stream`: programmatic, not
+     *    credential config (`types` is already wired via Dream's parsers).
+     *
+     * When another database adapter is added, a parallel `mysql?: ...` key
+     * (or similar) will appear here — this key is intentionally pg-specific.
+     */
+    pg?: Omit<PgPoolConfig, 'user' | 'password' | 'database' | 'host' | 'port' | 'ssl' | 'connectionString' | 'min' | 'types' | 'Client' | 'Promise' | 'log' | 'stream'>;
 }
 export type DreamLogger = {
     info: (...args: any[]) => void;