@rvoh/dream 2.11.1 → 2.11.3

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/cjs/src/errors/dream-app/MissingDbSslDirective.js

@@ -9,7 +9,7 @@ export default class MissingDbSslDirective extends Error {
     get message() {
         return `
 DreamApp refused to register a db credential without an explicit TLS
-directive. Every \`SingleDbCredential\` passed to \`app.set('db', ...)\`
+directive. Every \`DreamDbConfig\` passed to \`app.set('db', ...)\`
 must set one of:
 
   ssl: { rejectUnauthorized: true }              // verified TLS (system CA)

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/esm/src/errors/dream-app/MissingDbSslDirective.js

@@ -9,7 +9,7 @@ export default class MissingDbSslDirective extends Error {
     get message() {
         return `
 DreamApp refused to register a db credential without an explicit TLS
-directive. Every \`SingleDbCredential\` passed to \`app.set('db', ...)\`
+directive. Every \`DreamDbConfig\` passed to \`app.set('db', ...)\`
 must set one of:
 
   ssl: { rejectUnauthorized: true }              // verified TLS (system CA)

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

@@ -1,5 +1,5 @@
 import { Kysely } from 'kysely';
-import { SingleDbCredential } from '../dream-app/index.js';
+import { DreamDbConfig } from '../dream-app/index.js';
 import { DbConnectionType } from '../types/db.js';
 export default class DreamDbConnection {
     static getConnection<DB>(connectionName: string, connectionType: DbConnectionType, dialectProvider: DialectProviderCb): Kysely<DB>;
@@ -12,4 +12,4 @@ export declare function dreamDbConnections(): {
 };
 export declare function closeAllDbConnections(): Promise<void>;
 export declare function closeAllConnectionsForConnectionName(connectionName: string): Promise<PromiseSettledResult<void>[]>;
-export type DialectProviderCb = (connectionConf: SingleDbCredential) => any;
+export type DialectProviderCb = (connectionConf: DreamDbConfig) => any;

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/db/index.d.ts

@@ -1,5 +1,5 @@
 import { Kysely } from 'kysely';
-import { SingleDbCredential } from '../dream-app/index.js';
+import { DreamDbConfig } from '../dream-app/index.js';
 import Dream from '../Dream.js';
 import { DbConnectionType } from '../types/db.js';
-export default function db<T extends Dream, DB extends T['DB'] = T['DB']>(connectionName?: string, connectionType?: DbConnectionType, dialectProvider?: (connectionConf: SingleDbCredential) => any): Kysely<DB>;
+export default function db<T extends Dream, DB extends T['DB'] = T['DB']>(connectionName?: string, connectionType?: DbConnectionType, dialectProvider?: (connectionConf: DreamDbConfig) => any): Kysely<DB>;

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -1,7 +1,7 @@
 import type { ConnectionOptions as TlsConnectionOptions } from 'node:tls';
 import { DeleteQueryBuilder, Kysely, Transaction as KyselyTransaction, OrderByItemBuilder, SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import { DialectProviderCb } from '../../db/DreamDbConnection.js';
-import { SingleDbCredential } from '../../dream-app/index.js';
+import { DreamDbConfig } from '../../dream-app/index.js';
 import Dream from '../../Dream.js';
 import { SchemaBuilderInformationSchemaRow } from '../../helpers/cli/ASTBuilder.js';
 import { AssociationStatement } from '../../types/associations/shared.js';
@@ -482,4 +482,4 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
  * `app.set('db', ...)` time when both `ssl` and `useSsl` are unset, so this
  * resolver never sees the "neither directive" state.
  */
-export declare function resolvePostgresSsl(connectionConf: SingleDbCredential): TlsConnectionOptions | false;
+export declare function resolvePostgresSsl(connectionConf: DreamDbConfig): TlsConnectionOptions | false;

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';
@@ -148,7 +149,7 @@ export default class DreamApp {
     get models(): Record<string, typeof Dream>;
     get serializers(): Record<string, DreamModelSerializerType | SimpleObjectSerializerType>;
     dbName(connectionName: string, connection: DbConnectionType): string;
-    dbConnectionConfig(connectionName: string, connection: DbConnectionType): SingleDbCredential;
+    dbConnectionConfig(connectionName: string, connection: DbConnectionType): DreamDbConfig;
     dbConnectionQueryDriverClass<T extends Dream = Dream>(connectionName: string): typeof QueryDriverBase<T>;
     dbConnectionKeys(): string[];
     hasReplicaConfig(connectionName: string): boolean;
@@ -179,8 +180,8 @@ export interface DreamDirectoryPaths {
     types?: string;
 }
 export interface DreamDbCredentialOptions {
-    primary: SingleDbCredential;
-    replica?: SingleDbCredential | undefined;
+    primary: DreamDbConfig;
+    replica?: DreamDbConfig | undefined;
     queryDriverClass?: typeof QueryDriverBase;
     /**
      * a string which informs the kysely-codegen tool,
@@ -204,7 +205,7 @@ export interface DreamDbCredentialOptions {
     tableExcludePattern?: string;
 }
 type UnicodeNormalizationForm = 'NFC' | 'NFD' | 'none';
-export interface SingleDbCredential {
+export interface DreamDbConfig {
     user: string;
     password: string;
     host: string;
@@ -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;

package/dist/types/src/package-exports/types.d.ts

@@ -14,5 +14,5 @@ export { type DurationObject, type DurationUnit, type WeekdayName } from '../typ
 export { type DreamAssociationMetadata, type DreamAttributes, type DreamClassAssociationAndStatement, type DreamClassColumn, type DreamColumn, type DreamColumnNames, type DreamOrViewModelClassSerializerKey, type DreamOrViewModelSerializerKey, type DreamParamSafeAttributes, type DreamParamSafeColumnNames, type DreamSerializable, type DreamSerializableArray, type DreamSerializerKey, type DreamSerializers, type DreamVirtualColumns, type UpdateableAssociationProperties, type UpdateableProperties, type ViewModel, type ViewModelClass, } from '../types/dream.js';
 export { type DreamModelSerializerType, type InternalAnyTypedSerializerRendersMany, type InternalAnyTypedSerializerRendersOne, type SerializerCasing, type SimpleObjectSerializerType, } from '../types/serializer.js';
 export { type ValidationType } from '../types/validation.js';
-export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, } from '../dream-app/index.js';
+export { type DreamAppInitOptions, type DreamAppOpts, type DreamLogger, type DreamLogLevel, type DreamDbConfig, } from '../dream-app/index.js';
 export { type WhereStatementForDream, type WhereStatementForDreamClass, } from '../types/associations/shared.js';

package/docs/assets/navigation.js

@@ -1 +1 @@
-window.navigationData = "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"
+window.navigationData = "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"