@ultimat3/db 18.0.0 → 19.1.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.1.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.1.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

@@ -19,12 +19,15 @@ import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
  */
 export const DB_OWNED_ERROR_CODES = [
   'X_DB_UNAVAILABLE',
+  'X_DB_SCHEMA_STALE',
+  'X_DB_STATEMENT_FAILED',
   'X_DB_UNIQUE_VIOLATION',
   'X_DB_FOREIGN_KEY_VIOLATION',
   'X_DB_SERIALIZATION_FAILURE',
   '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',
@@ -60,12 +63,15 @@ export type DbErrorCode = (typeof DB_ERROR_CODES)[number];
 
 export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_UNAVAILABLE: 'cannot reach the database',
+  X_DB_SCHEMA_STALE: 'the statement names a table or column the database does not have',
+  X_DB_STATEMENT_FAILED: 'the database refused the statement',
   X_DB_UNIQUE_VIOLATION: 'a unique constraint rejected the row',
   X_DB_FOREIGN_KEY_VIOLATION: 'a foreign key constraint rejected the row',
   X_DB_SERIALIZATION_FAILURE: 'the transaction lost a serialization race',
   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',
@@ -125,7 +131,9 @@ export const DB_ERROR_RETRY = {
 // a typo or a renamed code is a build error rather than a classification for a code nothing throws.
 //
 // Left to the fail-closed default, deliberately, each for its own reason:
-//   X_DB_UNAVAILABLE            two failures in one code — see the note above
+//   X_DB_UNAVAILABLE            a connection failure — see the note above
+//   X_DB_SCHEMA_STALE           `42P01`/`42703`: the migration is the fix, and no attempt runs it
+//   X_DB_STATEMENT_FAILED       the server's verdict on the SQL; the same SQL gets the same verdict
 //   X_DB_STATEMENT_TIMEOUT      `57014`, and this package's fix for it is "add the index": an edit.
 //                               The queued-behind-a-lock case has its own code, above
 //   X_DB_UNIQUE_VIOLATION       the same row, the same constraint, the same refusal
@@ -169,7 +177,9 @@ export class DbError extends UltimateError {
 export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
   new DbError({
     code: 'X_DB_UNAVAILABLE',
-    cause: detail,
+    // The driver's own words ride along when there are any: `ECONNREFUSED 127.0.0.1:5432` is the
+    // half of "cannot reach the database" an operator acts on, and it was dropped on the floor.
+    cause: sourceError === undefined ? detail : `${detail}: ${renderThrowable(sourceError)}`,
     fix: 'set DATABASE_URL to a reachable Postgres url, or run `x dev` to use the embedded PGlite',
     sourceError,
   });
@@ -184,6 +194,9 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
  * of one; `driverError` substitutes the placeholder when the driver reported none.
  */
 const SQLSTATE_FIXES = Object.freeze<Record<DbSqlStateCode, string>>({
+  X_DB_SCHEMA_STALE:
+    'x db gen "<what changed>" && x db migrate   # the entity is ahead of the schema; ' +
+    'if the migration already exists, only the migrate half is due',
   X_DB_UNIQUE_VIOLATION:
     'upsertAll(rows, { onConflict: [...] }) over the columns {constraint} covers — ' +
     'or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is',
@@ -217,19 +230,31 @@ const UNNAMED_CONSTRAINT = 'the constraint named in cause';
  * given where it is true, and a new SQLSTATE arrives as a new row here rather than as a new
  * `catch` at a call site.
  */
-export const driverError = (detail: string, sourceError: unknown): DbError => {
-  const code = sqlStateCode(sourceError);
-  if (code === undefined) return dbUnavailable(detail, sourceError);
+export const driverError = (statement: string, sourceError: unknown): DbError => {
   const state = sqlState(sourceError);
+  // No SQLSTATE means the failure never reached a server — a refused socket, a closed pool, a
+  // driver that would not load. THAT is unavailability, and it is the only thing that is.
+  if (state === undefined) return dbUnavailable(`statement failed: ${statement}`, sourceError);
+  // A state the table does not classify still proves the server answered: it read the statement
+  // and refused it. `X_DB_STATEMENT_FAILED` says so and carries the server's own words, where
+  // `X_DB_UNAVAILABLE` said "set DATABASE_URL" to a developer whose database was fine.
+  const code = sqlStateCode(sourceError) ?? 'X_DB_STATEMENT_FAILED';
   const constraint = stringField(sourceError, 'constraint');
   return new DbError({
     code,
-    cause: `${detail}: ${renderThrowable(sourceError)} [SQLSTATE ${state ?? '?????'}]`,
+    // The server's SQLSTATE and message FIRST, the statement after: a cause is rendered on one
+    // line and cut when long, and a column list of any width put the one thing an author needs —
+    // `column "host_id" does not exist` — past the cut. The statement is `statementExcerpt`'d by
+    // the caller, so the whole line has a known ceiling.
+    cause: `[SQLSTATE ${state}] ${renderThrowable(sourceError)} — statement: ${statement}`,
     // A FUNCTION as the replacement, never the string: `String.replace` expands `$&`, `` $` ``,
     // `$'` and `$$` inside a replacement literal, and a constraint name is the server's, not
     // ours — `$` is legal in a Postgres identifier, so `posts_$&_key` would splice the matched
     // `{constraint}` back into the fix line an author is meant to paste.
-    fix: SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
+    fix:
+      code === 'X_DB_STATEMENT_FAILED'
+        ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
+        : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
     meta: {
       sqlState: state,
       ...(constraint === undefined ? {} : { constraint }),
@@ -238,6 +263,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/pglite.ts

@@ -5,11 +5,12 @@
 
 import { statementAttribution } from './attribution';
 import type { DbConnection, ReservableClient } from './client';
-import { DbError, dbUnavailable } from './errors';
+import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
 import { createTurnQueue } from './pglite-turns';
 import type { SqlFragment } from './sql';
+import { statementExcerpt } from './statement-excerpt';
 import { withStatementSpan } from './statement-span';
 import { inLiveTx } from './transaction';
 
@@ -142,7 +143,12 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     try {
       return await driver.query(fragment.text, fragment.values);
     } catch (error) {
-      throw dbUnavailable(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+      // `driverError`, as `statement-funnel.ts` already does for Bun's driver: this site passed
+      // every failure to `dbUnavailable`, so under `x dev` — which IS this driver when no
+      // `DATABASE_URL` is set — a `select` naming a column whose migration had not run answered
+      // "cannot reach the database" with the fix "set DATABASE_URL", against a database that was
+      // answering fine (measured 2026-09-05). PGlite carries the SQLSTATE on `code`.
+      throw driverError(statementExcerpt(fragment.text), error);
     }
   }
 

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,
     );

package/src/sqlstate.ts

@@ -14,6 +14,8 @@ import { stringField } from '@ultimat3/core';
 export const SQLSTATE = Object.freeze({
   /** `undefined_table` — the ledger's absence is a class, not a message to match on. */
   undefinedTable: '42P01',
+  /** `undefined_column` — an entity edited before the migration that adds the column ran. */
+  undefinedColumn: '42703',
   uniqueViolation: '23505',
   foreignKeyViolation: '23503',
   serializationFailure: '40001',
@@ -70,6 +72,7 @@ export function sqlState(error: unknown): string | undefined {
 
 /** The codes a SQLSTATE can classify into. `errors.ts` owns their titles and their fixes. */
 export type DbSqlStateCode =
+  | 'X_DB_SCHEMA_STALE'
   | 'X_DB_UNIQUE_VIOLATION'
   | 'X_DB_FOREIGN_KEY_VIOLATION'
   | 'X_DB_SERIALIZATION_FAILURE'
@@ -84,6 +87,11 @@ export type DbSqlStateCode =
  * class 53, insufficient resources, and both are answered by asking for fewer connections.
  */
 export const DB_SQLSTATE_CODES: Readonly<Record<string, DbSqlStateCode>> = Object.freeze({
+  // Both class 42 "the schema does not have what this statement names": a table or a column
+  // declared in code whose migration has not run. One code, because the instruction is one
+  // instruction — generate the migration and apply it — and the cause names which it was.
+  [SQLSTATE.undefinedTable]: 'X_DB_SCHEMA_STALE',
+  [SQLSTATE.undefinedColumn]: 'X_DB_SCHEMA_STALE',
   [SQLSTATE.uniqueViolation]: 'X_DB_UNIQUE_VIOLATION',
   [SQLSTATE.foreignKeyViolation]: 'X_DB_FOREIGN_KEY_VIOLATION',
   [SQLSTATE.serializationFailure]: 'X_DB_SERIALIZATION_FAILURE',
@@ -94,7 +102,11 @@ export const DB_SQLSTATE_CODES: Readonly<Record<string, DbSqlStateCode>> = Objec
   [SQLSTATE.outOfMemory]: 'X_DB_POOL_EXHAUSTED',
 } as const);
 
-/** `undefined` when the state is unknown or absent — the caller then reports unavailability. */
+/**
+ * `undefined` when the state is absent or not in the table. What the caller does with that is
+ * `driverError`'s decision, not this file's: a state the table does not name still proves the
+ * statement REACHED a server, which is the opposite of unavailable.
+ */
 export function sqlStateCode(error: unknown): DbSqlStateCode | undefined {
   const state = sqlState(error);
   return state === undefined ? undefined : DB_SQLSTATE_CODES[state];

package/src/statement-funnel.ts

@@ -10,6 +10,7 @@ import { driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
 import type { SqlFragment } from './sql';
+import { statementExcerpt } from './statement-excerpt';
 import { withStatementSpan } from './statement-span';
 
 export function rowsOf<T>(result: unknown): readonly T[] {
@@ -42,7 +43,7 @@ async function sendOn(
     // read it, so a `23505` from two clicks racing a signup told the operator the database was
     // unreachable and paged on-call for an outage that never happened. Everything the table does
     // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
-    throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+    throw driverError(statementExcerpt(fragment.text), error);
   }
 }