@ultimat3/db 18.0.0 → 19.0.0

package/CLAUDE.md

@@ -233,6 +233,30 @@ means the nested scope never opened, and a release that failed means its work is
 the outer one. Swallowing either would keep running against a transaction that is not the one the
 caller thinks it is in.
 
+**`close()` is BOUNDED, `As of 2026-08-27`, and by the driver's OWN option rather than a race here**
+(#394). `BunSqlDriver.close` has declared `{ timeout }` since this package's `Bun.SQL` slice was
+written and **nothing ever passed it** — a capability sitting unused in the seam, the same shape as
+`setOfflineMode` on the CDP port. Measured against a real server, three runs per case: `end()` waits
+on an outstanding RESERVED connection and never returns, on Bun 1.3.14 **and** on 1.4.0, with the
+database perfectly healthy; once that connection's backend has been terminated it becomes a race
+1.3.14 loses 3 of 3 and 1.4.0 loses 1 of 3. So the runtime was never the variable — an unbounded
+await was, and `@ultimat3/cli`'s `releaseQueue` awaits this method. A container that will not drain
+is drained by SIGKILL, and the operator's only signal is a pod that took its full grace period.
+
+Three rules ride with it. **The unit is SECONDS** — `close({ timeout: profile.drainTimeoutMs /
+1000 })`, and `timeout: 5000` would be an eighty-three minute budget, which is the same hang with
+extra steps. **`drainTimeoutMs: 0` sends no option at all**, rather than `{ timeout: 0 }`: `migrate`
+and `replicator` mean "wait", for `acquireTimeoutMs`' reason, and a zero handed to the driver is an
+instruction whose reading is the driver's. **The verdict is the elapsed time**, because the driver
+RESOLVES when it gives up rather than rejecting — a drain that abandoned in-flight work looks exactly
+like a clean one, so `X_DB_DRAIN_TIMEOUT` is raised on the clock or nothing is said at all. That
+clock is `performance.now()` and never `Date.now()`, and the reason is this repo rather than NTP:
+the framework preload freezes `Date` for every test in the tree (`installDeterminism`), so a duration
+subtracted from `Date.now()` is 0 in all of them and the branch could not fire — a test asserting it
+would have been one that cannot fail. `pool-drain.test.ts` pins what is ASKED for, against a fake
+pool; `pool-drain.live.test.ts` pins that a real server's driver honours it, because a fake's
+`close()` is whatever the fake decided and the finding is about the real one.
+
 `close()` reads its cached driver into a local, clears the field, **then** awaits the teardown —
 `client.ts` and `pglite.ts` both. A teardown that rejects has still torn the pool down, so clearing
 after the await left the corpse cached for the next `connect()`, and a second `close()` threw in
@@ -1312,7 +1336,7 @@ survives the round trip whole.
   is 0 and not 1.
 
 - **`client.ts` reached the 500-line ceiling on 2026-08-26, and shed the five jobs that were not
-  "open a connection and send a statement".** `pool-profile.ts` owns the five numbers a pool runs
+  "open a connection and send a statement".** `pool-profile.ts` owns the six numbers a pool runs
   on — the per-role table, `DATABASE_POOL_MAX` and the screen every merged profile passes;
   `connection-url.ts` builds the connection string (the libpq `options` merge and the
   `application_name` label); `bun-sql.ts` declares the slice of `Bun.SQL` this package uses and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "18.0.0"
+    "@ultimat3/core": "19.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/bun-sql.ts

@@ -1,13 +1,55 @@
-// Single responsibility: the slice of `Bun.SQL` this package uses, declared structurally, and the
-// lazy lookup of the global that provides it. Reached through a function so importing the client
-// never touches `Bun` at module evaluation — the CLI imports it to print help.
+// Single responsibility: the slice of `Bun.SQL` this package uses, declared structurally, the lazy
+// lookup of the global that provides it, and the one safe way to hand a pinned connection back.
+// Reached through a function so importing the client never touches `Bun` at module evaluation —
+// the CLI imports it to print help.
 
+import { logger, renderThrowable } from '@ultimat3/core';
 import { dbUnavailable } from './errors';
 
 /** One connection pinned out of `Bun.SQL`'s pool, released back by hand. */
 export interface BunSqlReserved {
   unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
-  release(): void;
+  /**
+   * **Answers a PROMISE, and typing it `void` is what made both callers float it.** Measured on
+   * Bun 1.3.14 and 1.4.0 against a real server: `release()` returns a promise on both, and on
+   * 1.3.14 that promise REJECTS with `ERR_POSTGRES_CONNECTION_CLOSED` when the pool has already
+   * been closed. Nothing was attached to it, so it surfaced as an UNHANDLED REJECTION — which Bun
+   * takes the process down for. `unknown` rather than `Promise<void>` because a fake reserved
+   * connection returns nothing at all, and the caller has to handle both anyway.
+   */
+  release(): unknown;
+}
+
+/**
+ * Hand a pin back, totally. The one place that knows `release()` answers a promise, so neither
+ * caller can forget it (axiom 1) — `client.ts`'s `DbConnection.release` and `pool-reserve.ts`'s
+ * late arrival both route here.
+ *
+ * A failed release is **best-effort, exactly where a throw would mask the error that caused it** —
+ * the rule this package already applies to `ROLLBACK`. `[Symbol.dispose]` is `DbConnection.release`
+ * itself, so a throw there replaces whatever error reached the `using` block, or invents one where
+ * the body succeeded. And the news is unactionable: the connection this would hand back is gone
+ * either way.
+ *
+ * Reachable, and reachable BECAUSE `close()` is bounded: an abandoned drain leaves every
+ * still-pinned connection to be released against a pool that no longer exists.
+ */
+export function releaseReserved(reserved: BunSqlReserved): void {
+  const report = (error: unknown): void => {
+    logger.debug('db.release_failed', { error: renderThrowable(error) });
+  };
+  let settled: unknown;
+  try {
+    settled = reserved.release();
+  } catch (error) {
+    report(error);
+    return;
+  }
+  // `then` and not `instanceof Promise`: the value comes from the driver, and a thenable is the
+  // contract every await in this package already relies on.
+  if (typeof (settled as PromiseLike<unknown> | undefined)?.then === 'function') {
+    void (settled as PromiseLike<unknown>).then(undefined, report);
+  }
 }
 
 /** The slice of `Bun.SQL` we use. Declared structurally so this package has no dependency. */

package/src/client.ts

@@ -5,12 +5,12 @@
 // importing this module never opens a socket.
 
 import { type Role, resolveRole } from '@ultimat3/core';
-import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory } from './bun-sql';
+import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory, releaseReserved } from './bun-sql';
 import { connectionUrl } from './connection-url';
 // Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
-import { DbError, driverError } from './errors';
+import { DbError, drainTimeout, driverError } from './errors';
 import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
 import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
@@ -120,7 +120,8 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       const release = (): void => {
         if (!held) return;
         held = false;
-        reserved.release();
+        // Total by construction — `releaseReserved` owns the reason (`bun-sql.ts`).
+        releaseReserved(reserved);
       };
       return {
         query: async <T>(fragment: SqlFragment) => rowsOf<T>(await on(fragment)),
@@ -141,7 +142,40 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // rejection still reaches the caller — a shutdown that could not drain wants to know.
       const pool = driver;
       driver = undefined;
-      await pool?.close();
+      if (pool === undefined) return;
+      // BOUNDED, `As of 2026-08-27`, and through the driver's OWN option rather than a race here.
+      // This was a bare `await pool.close()`, and `Bun.SQL`'s `end()` waits on an outstanding
+      // reserved connection without ever giving up — measured three runs per case on Bun 1.3.14
+      // AND 1.4.0, no database outage involved (#394). So a role whose database went away
+      // mid-shutdown never finished shutting down, and the operator's only signal was a container
+      // that burned its whole termination grace period before SIGKILL.
+      //
+      // `BunSqlDriver.close` has declared `{ timeout }` since this port was written and NOTHING
+      // ever passed it — the capability was in the seam, unused, exactly like `setOfflineMode` on
+      // the CDP port. Measured with a reserve outstanding: `close({ timeout: 1 })` returns in
+      // ~1002ms on 1.3.14, 1.4.0 and 1.4.1-canary alike, where a bare `close()` never returns.
+      //
+      // **The unit is SECONDS**, not milliseconds. `timeout: 5000` would be an eighty-three minute
+      // shutdown budget, which is the same hang with extra steps.
+      if (profile.drainTimeoutMs === 0) {
+        // `migrate` and `replicator`, for `acquireTimeoutMs`' reason: a run-once role cutting off
+        // its own session mid-statement is worse than a slow exit.
+        await pool.close();
+        return;
+      }
+      // `performance.now()`, never `Date.now()`, and the reason is this repo rather than NTP: the
+      // framework preload freezes `Date` for every test in the tree (`installDeterminism`), so a
+      // duration subtracted from `Date.now()` is 0 in all of them — the branch below could not
+      // fire, and the test asserting it would have been one that cannot fail.
+      const started = performance.now();
+      await pool.close({ timeout: profile.drainTimeoutMs / 1000 });
+      // The driver RESOLVES when it gives up — it does not reject — so the elapsed time is the only
+      // thing that separates "drained" from "abandoned". Reporting it is the point: a drain that
+      // silently gave up looks exactly like a clean one, and the work still in flight is lost with
+      // no line anywhere saying so. The pool is gone either way, which is why this is terminal.
+      if (performance.now() - started >= profile.drainTimeoutMs) {
+        throw drainTimeout(profile.drainTimeoutMs, role);
+      }
     },
   };
   return client;

package/src/errors.ts

@@ -25,6 +25,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_DB_STATEMENT_TIMEOUT',
   'X_DB_LOCK_TIMEOUT',
   'X_DB_POOL_EXHAUSTED',
+  'X_DB_DRAIN_TIMEOUT',
   'X_DB_DRIFT',
   'X_MIGRATION_CONFLICT',
   'X_MIGRATION_IRREVERSIBLE',
@@ -66,6 +67,7 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_STATEMENT_TIMEOUT: 'the statement ran past its statement_timeout',
   X_DB_LOCK_TIMEOUT: 'the statement waited past its lock_timeout',
   X_DB_POOL_EXHAUSTED: 'no connection was available',
+  X_DB_DRAIN_TIMEOUT: 'the pool did not drain inside its shutdown budget',
   X_DB_DRIFT: 'schema differs from migrations',
   X_MIGRATION_CONFLICT: 'the migration ledger disagrees with this build',
   X_MIGRATE_CONCURRENT: 'another migrator holds the migration lock',
@@ -238,6 +240,24 @@ export const driverError = (detail: string, sourceError: unknown): DbError => {
   });
 };
 
+/**
+ * `close()` gave up waiting for the pool. TERMINAL, and deliberately not retryable: the pool is
+ * gone either way — `close()` clears the handle before it awaits — so a caller that retried would
+ * be closing a pool that no longer exists. What this reports is that connections were still held
+ * when the process stopped waiting, which is a fact about the shutdown an operator has to see.
+ *
+ * The alternative was to resolve quietly on the deadline, and that is the version that hides the
+ * bug: a drain that silently gave up looks exactly like a clean one, and the rows still in flight
+ * are lost with no line anywhere saying so.
+ */
+export const drainTimeout = (ms: number, role: string): DbError =>
+  new DbError({
+    code: 'X_DB_DRAIN_TIMEOUT',
+    cause: `the ${role} pool still held connections after ${String(ms)}ms, so close() stopped waiting`,
+    fix: `find the statement that will not finish — psql "$DATABASE_URL" -c "select pid, state, query from pg_stat_activity where state <> 'idle'" — or raise drainTimeoutMs in createPostgresClient({ profile }) for the ${role} role`,
+    meta: { drainTimeoutMs: ms, role },
+  });
+
 /**
  * The pool answered nothing inside `acquireTimeoutMs`. Distinct from the server's own `53300` and
  * deliberately the same code: to a caller both mean "there was no connection for this unit of

package/src/pool-profile.ts

@@ -1,4 +1,4 @@
-// Single responsibility: the five numbers a Postgres pool runs on — the per-role defaults, the one
+// Single responsibility: the six numbers a Postgres pool runs on — the per-role defaults, the one
 // environment override an operator may layer over them, and the screen every resolved profile
 // passes. Split from `client.ts`, which now owns connecting and nothing about sizing.
 
@@ -25,6 +25,24 @@ export interface PoolProfile {
    * kills the pod, and the replacement inherits the same saturated database.
    */
   readonly acquireTimeoutMs: number;
+  /**
+   * How long `close()` may wait for the pool to drain before `X_DB_DRAIN_TIMEOUT`. 0 waits forever.
+   *
+   * **A drain that cannot finish is the failure this bounds, and it is not hypothetical.** Measured
+   * against a real Postgres, three runs per case: `Bun.SQL`'s `end()` waits on an outstanding
+   * RESERVED connection and never stops waiting — 3 of 3 on Bun 1.3.14 *and* 3 of 3 on 1.4.0, with
+   * no database outage involved at all. Once that connection's backend has been terminated it
+   * becomes a race, which 1.3.14 loses 3 of 3 and 1.4.0 loses 1 of 3. So the runtime is not the
+   * variable; an unbounded await is (#394).
+   *
+   * What that cost, before this: `releaseQueue` awaits `db.close()`, so a role whose database went
+   * away mid-shutdown never finished shutting down. A container that will not drain is drained by
+   * SIGKILL, and the operator's only signal is a pod that took its full termination grace period.
+   *
+   * `migrate` and `replicator` wait forever, deliberately, for `acquireTimeoutMs`' reason: a
+   * run-once role cutting off its own session mid-statement is worse than a slow exit.
+   */
+  readonly drainTimeoutMs: number;
 }
 
 /** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
@@ -35,6 +53,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 30_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
+    drainTimeoutMs: 5_000,
   },
   sync: {
     max: 10,
@@ -42,6 +61,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 5_000,
+    drainTimeoutMs: 5_000,
   },
   worker: {
     max: 8,
@@ -49,6 +69,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 30_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
+    drainTimeoutMs: 15_000,
   },
   scheduler: {
     max: 2,
@@ -56,6 +77,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 10_000,
+    drainTimeoutMs: 5_000,
   },
   // `migrate` waits: its pool is `max: 1` and the advisory-lock pin holds it for the whole run, so
   // a deadline here would refuse the migration's own session. The wait that needed bounding is the
@@ -66,6 +88,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 10_000,
     lockTimeoutMs: 3_000,
     acquireTimeoutMs: 0,
+    drainTimeoutMs: 0,
   },
   replicator: {
     max: 4,
@@ -73,6 +96,7 @@ export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
     idleTimeoutMs: 60_000,
     lockTimeoutMs: 0,
     acquireTimeoutMs: 0,
+    drainTimeoutMs: 0,
   },
 });
 
@@ -99,13 +123,13 @@ export function poolMaxFromEnv(): Partial<PoolProfile> {
 }
 
 /**
- * The five numbers a pool runs on, screened on the MERGED profile — an override is spread over a
+ * The six numbers a pool runs on, screened on the MERGED profile — an override is spread over a
  * role default the caller never restated, so the resolved object is the only one that can be
  * judged. Every one of them is a plausible `Number(process.env.…)`, which is `NaN` for an unset
- * variable and not nullish, so `??` and the spread both keep it. None of the five then fails
+ * variable and not nullish, so `??` and the spread both keep it. None of the six then fails
  * loudly: `idleTimeout: NaN` goes to `Bun.SQL`, `statement_timeout=NaN` goes into the libpq
  * options string for the SERVER to reject on connect, and a timer given `NaN` fires at 1ms in this
- * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the three
+ * Bun — so a pool with free connections reports itself exhausted. `0` stays legal for the five
  * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
  */
 export function assertPoolProfile(profile: PoolProfile): PoolProfile {
@@ -121,5 +145,6 @@ export function assertPoolProfile(profile: PoolProfile): PoolProfile {
   whole('idleTimeoutMs', profile.idleTimeoutMs, 0);
   whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
   whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
+  whole('drainTimeoutMs', profile.drainTimeoutMs, 0);
   return profile;
 }

package/src/pool-reserve.ts

@@ -2,7 +2,7 @@
 // and giving back a reservation that arrives after the deadline has passed. Split from `client.ts`,
 // which now asks for a pin rather than owning what "waited too long" means.
 
-import type { BunSqlDriver, BunSqlReserved } from './bun-sql';
+import { type BunSqlDriver, type BunSqlReserved, releaseReserved } from './bun-sql';
 import { poolAcquireTimeout } from './errors';
 import type { PoolProfile } from './pool-profile';
 
@@ -42,7 +42,7 @@ export async function reserveWithin(
     // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
     void pending.then(
       (late) => {
-        if (expired) late.release();
+        if (expired) releaseReserved(late);
       },
       () => undefined,
     );