@ultimat3/db 29.3.2 → 30.0.0

package/src/catalog-policies.ts

@@ -0,0 +1,81 @@
+// Single responsibility: row security as the catalog holds it — which tables enable or force it,
+// and every policy on them, clause by clause — read and folded for the schema dump. A dump without
+// them loads a test database that refuses nothing, so a policy would be untested and prod-only.
+
+import type { CatalogPolicy, CatalogRowSecurity } from './catalog';
+import { by } from './catalog-fold';
+import { notExtensionOwned } from './catalog-relations';
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+export interface RowSecurityRow {
+  readonly table_name: string;
+  readonly enabled: boolean;
+  readonly forced: boolean;
+}
+
+export interface PolicyRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly permissive: boolean;
+  readonly command: string;
+  readonly roles: readonly string[];
+  readonly using: string | null;
+  readonly with_check: string | null;
+}
+
+export const rowSecurityRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly RowSecurityRow[]> =>
+  client.query<RowSecurityRow>(sql`
+    select c.relname as table_name, c.relrowsecurity as enabled, c.relforcerowsecurity as forced
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and (c.relrowsecurity or c.relforcerowsecurity)
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** `polroles` holds `0` for `public`, which no `pg_roles` row answers; each name is resolved here. */
+export const policyRows = (client: DbClient, schema: string): Promise<readonly PolicyRow[]> =>
+  client.query<PolicyRow>(sql`
+    select
+      c.relname as table_name,
+      p.polname as name,
+      p.polpermissive as permissive,
+      case p.polcmd when 'r' then 'select' when 'a' then 'insert' when 'w' then 'update'
+        when 'd' then 'delete' else 'all' end as command,
+      array(
+        select case when r.oid = 0 then 'public' else (select rolname from pg_roles where oid = r.oid) end
+        from unnest(p.polroles) as r(oid)
+      ) as roles,
+      pg_get_expr(p.polqual, p.polrelid) as using,
+      pg_get_expr(p.polwithcheck, p.polrelid) as with_check
+    from pg_policy p
+    join pg_class c on c.oid = p.polrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+export const rowSecurityOf = (rows: readonly RowSecurityRow[]): readonly CatalogRowSecurity[] =>
+  rows
+    .map((row) => ({ table: row.table_name, enabled: row.enabled, forced: row.forced }))
+    .sort(by((entry) => entry.table));
+
+export const policiesOf = (rows: readonly PolicyRow[]): readonly CatalogPolicy[] =>
+  rows
+    .map((row) => ({
+      table: row.table_name,
+      name: row.name,
+      permissive: row.permissive,
+      command: row.command,
+      roles: [...row.roles].sort(by((role) => role)),
+      using: row.using,
+      withCheck: row.with_check,
+    }))
+    .sort(
+      by(
+        (policy) => policy.table,
+        (policy) => policy.name,
+      ),
+    );

package/src/catalog-relations.ts

@@ -26,6 +26,11 @@ export interface TableRow {
   readonly replica_identity: string;
   readonly replica_index: string | null;
   readonly options: string | null;
+  /** `pg_get_partkeydef` — `RANGE (at)` — on a partitioned table; `null` on any other. */
+  readonly partition_key: string | null;
+  /** The table this one is a partition of, and its bound (`FOR VALUES …`, `DEFAULT`); else `null`. */
+  readonly partition_of: string | null;
+  readonly partition_bound: string | null;
 }
 
 export interface ColumnRow {
@@ -69,9 +74,10 @@ export interface IndexRow {
 }
 
 /**
- * Plain tables only. A partition, an inheritance child and a partitioned parent are `relkind`
- * `r`/`p` rows a `create table (…)` cannot rebuild, so they are named by `unrenderedRows`
- * (`catalog-objects.ts`) instead of rendered wrong here.
+ * Plain tables, partitioned tables and their partitions. An inheritance child that is not a
+ * partition is a row a `create table (…)` cannot rebuild, so it is named by `unrenderedRows`
+ * (`catalog-objects.ts`) instead of rendered wrong here. A partition's bound is the server's own
+ * `pg_get_expr` text: a `timestamptz` bound is spelled in the session's `TimeZone`.
  */
 export const tableRows = (client: DbClient, schema: string): Promise<readonly TableRow[]> =>
   client.query<TableRow>(sql`
@@ -85,13 +91,20 @@ export const tableRows = (client: DbClient, schema: string): Promise<readonly Ta
         join pg_class i on i.oid = x.indexrelid
         where x.indrelid = c.oid and x.indisreplident
       ) as replica_index,
-      array_to_string(c.reloptions, ', ') as options
+      array_to_string(c.reloptions, ', ') as options,
+      pg_get_partkeydef(c.oid) as partition_key,
+      (
+        select p.relname
+        from pg_inherits h
+        join pg_class p on p.oid = h.inhparent
+        where h.inhrelid = c.oid and c.relispartition
+      ) as partition_of,
+      case when c.relispartition then pg_get_expr(c.relpartbound, c.oid) end as partition_bound
     from pg_class c
     join pg_namespace n on n.oid = c.relnamespace
     where n.nspname = ${schema}
-      and c.relkind = 'r'
-      and not c.relispartition
-      and not exists (select 1 from pg_inherits h where h.inhrelid = c.oid)
+      and c.relkind in ('r', 'p')
+      and (c.relispartition or not exists (select 1 from pg_inherits h where h.inhrelid = c.oid))
       and ${notExtensionOwned('pg_class', 'c.oid')}
   `);
 
@@ -114,13 +127,15 @@ export const columnRows = (client: DbClient, schema: string): Promise<readonly C
     join pg_type t on t.oid = a.atttypid
     left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
     left join pg_collation co on co.oid = a.attcollation
-    where n.nspname = ${schema} and c.relkind = 'r' and a.attnum > 0 and not a.attisdropped
+    where n.nspname = ${schema} and c.relkind in ('r', 'p') and a.attnum > 0 and not a.attisdropped
   `);
 
 /**
  * Every constraint a table carries, foreign keys included — the fold routes those to their own
  * directory. `contype = 'n'` (a NOT NULL recorded as a constraint, Postgres 18) is left out: the
  * column's own `not null` already says it, and reading it would make the dump differ by server.
+ * A constraint a partition holds from its parent — a key's clone (`conparentid`), an inherited
+ * check (`not conislocal`) — is left out too: the parent's own statement recreates it.
  */
 export const constraintRows = (
   client: DbClient,
@@ -136,6 +151,7 @@ export const constraintRows = (
     join pg_class c on c.oid = k.conrelid
     join pg_namespace n on n.oid = c.relnamespace
     where n.nspname = ${schema} and k.contype in ('p', 'u', 'c', 'x', 'f')
+      and k.conparentid = 0 and k.conislocal
   `);
 
 /** `::text` on every bound: a `bigint` is a string on one driver and a number on the other. */
@@ -164,7 +180,11 @@ export const sequenceRows = (client: DbClient, schema: string): Promise<readonly
     where n.nspname = ${schema} and ${notExtensionOwned('pg_class', 'c.oid')}
   `);
 
-/** Indexes no constraint backs, on a table or a materialized view. */
+/**
+ * Indexes no constraint backs, on a table, a partitioned table or a materialized view. A
+ * partition's index ATTACHED to its parent's (a `pg_inherits` row of its own) is left out: the
+ * parent's index, built on load, builds it.
+ */
 export const indexRows = (client: DbClient, schema: string): Promise<readonly IndexRow[]> =>
   client.query<IndexRow>(sql`
     select
@@ -176,9 +196,10 @@ export const indexRows = (client: DbClient, schema: string): Promise<readonly In
     join pg_class t on t.oid = x.indrelid
     join pg_namespace n on n.oid = t.relnamespace
     where n.nspname = ${schema}
-      and t.relkind in ('r', 'm')
+      and t.relkind in ('r', 'm', 'p')
       and not exists (
         select 1 from pg_constraint k
         where k.conindid = x.indexrelid and k.contype in ('p', 'u', 'x')
       )
+      and not exists (select 1 from pg_inherits h where h.inhrelid = x.indexrelid)
   `);

package/src/catalog.ts

@@ -90,6 +90,14 @@ export interface CatalogTable {
   readonly constraints: readonly CatalogConstraint[];
   readonly sequences: readonly CatalogOwnedSequence[];
   readonly replicaIdentity: CatalogReplicaIdentity;
+  /** `pg_get_partkeydef` — `RANGE (at)` — on a partitioned table. Absent on any other. */
+  readonly partitionBy?: string | undefined;
+  /**
+   * On a partition: the table it is a partition of and its bound as the server spells it
+   * (`FOR VALUES FROM (…) TO (…)`, `DEFAULT`). Absent on any other. A partition's columns and the
+   * constraints it holds from its parent are the parent's, so the dump spells neither.
+   */
+  readonly partitionOf?: { readonly table: string; readonly bound: string } | undefined;
 }
 
 /** An index no constraint backs; a constraint's own index is created by the constraint. */
@@ -111,6 +119,11 @@ export interface CatalogView {
   readonly options: string | null;
   /** `pg_get_viewdef` verbatim, trailing `;` and all. */
   readonly definition: string;
+  /**
+   * The output columns, in order. Never rendered — the definition already says them — and read by
+   * the `drift` step against a view entity's declared `columns`. Absent on a hand-built catalog.
+   */
+  readonly columns?: readonly string[] | undefined;
 }
 
 export interface CatalogFunction {
@@ -130,9 +143,31 @@ export interface CatalogTrigger {
   readonly enabled: string;
 }
 
+/** A table whose row security is enabled or forced — two flags, each its own `alter table`. */
+export interface CatalogRowSecurity {
+  readonly table: string;
+  readonly enabled: boolean;
+  /** `force`: the table's owner is bound too. Without it an owner sees every row. */
+  readonly forced: boolean;
+}
+
+/** A row-security policy, every clause spelled: a clause left out is a default two servers may differ on. */
+export interface CatalogPolicy {
+  readonly table: string;
+  readonly name: string;
+  readonly permissive: boolean;
+  /** `all`, `select`, `insert`, `update` or `delete`. */
+  readonly command: string;
+  /** Role names, `public` for the `0` grantee; sorted. */
+  readonly roles: readonly string[];
+  /** `pg_get_expr` verbatim, or `null` when the clause is absent. */
+  readonly using: string | null;
+  readonly withCheck: string | null;
+}
+
 /**
  * An object in the schema that the dump has no statement for. Named rather than dropped: a dump
- * that silently omitted a row-security policy would load into a database that is not the one the
+ * that silently omitted an object would load into a database that is not the one the
  * migrations build, and the load-equals-replay check could not see it, because both sides of that
  * comparison would be blind in the same place.
  */
@@ -155,6 +190,8 @@ export interface CatalogDescription {
   readonly views: readonly CatalogView[];
   readonly functions: readonly CatalogFunction[];
   readonly triggers: readonly CatalogTrigger[];
+  readonly rowSecurity: readonly CatalogRowSecurity[];
+  readonly policies: readonly CatalogPolicy[];
   readonly unrendered: readonly CatalogUnrendered[];
 }
 
@@ -170,5 +207,7 @@ export const emptyCatalog = (schema = 'public'): CatalogDescription => ({
   views: [],
   functions: [],
   triggers: [],
+  rowSecurity: [],
+  policies: [],
   unrendered: [],
 });

package/src/check-ddl.ts

@@ -11,6 +11,7 @@
 // is `42710` on the very next generation — a migration nobody can apply.
 
 import { assert } from '@ultimat3/core';
+import { type ConcurrentPlan, deferValidate } from './concurrent-plan';
 import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 import type { CheckDescription, TableDescription } from './introspect';
 import { invariantChecks, isIdentifier, MAX_IDENTIFIER_BYTES } from './invariant-ddl';
@@ -32,6 +33,9 @@ import { statementsOf } from './statement-split';
  */
 const spellColumnCheckName = (table: string, column: string): string => `${table}_${column}_check`;
 
+/** The spelling, for a reader asking about a recorded column (`retired.ts`). Validates nothing. */
+export const columnCheckNameOf = spellColumnCheckName;
+
 /**
  * Whether a RECORDED constraint is one of THIS entity's columns' own CHECKs. Validates nothing and
  * never throws, exactly as `namesConstraint` does not, because its caller is a REPORTER
@@ -131,6 +135,10 @@ export const addCheck = (table: string, check: CheckDescription): string =>
   `alter table ${identifier(table).text} add constraint ${identifier(check.name).text} ` +
   `check (${check.expression});`;
 
+/** `not valid`: new writes are held to it at once, and the scan runs later (`deferValidate`). */
+const addCheckNotValid = (table: string, check: CheckDescription): string =>
+  `${addCheck(table, check).slice(0, -1)} not valid;`;
+
 export const dropCheck = (table: string, name: string): string =>
   `alter table ${identifier(table).text} drop constraint ${identifier(name).text};`;
 
@@ -144,9 +152,13 @@ export const dropCheck = (table: string, name: string): string =>
  * `add constraint` is `42710` on the first, inside `ROLE=migrate`, with the server's words and none
  * of the entity's. `drop constraint if exists` costs a notice on the second and repairs the first.
  */
-const rebuildCheck = (table: string, check: CheckDescription): readonly string[] => [
+const rebuildCheck = (
+  table: string,
+  check: CheckDescription,
+  add: typeof addCheck,
+): readonly string[] => [
   `alter table ${identifier(table).text} drop constraint if exists ${identifier(check.name).text};`,
-  addCheck(table, check),
+  add(table, check),
 ];
 
 /**
@@ -171,6 +183,14 @@ const rebuildCheck = (table: string, check: CheckDescription): readonly string[]
  * `drop constraint` on it a second time is `42704`, and its `down` belongs to the retype that
  * moved it. Keyed by name and not by column because an INVARIANT's check reads a column without
  * being derived from one, which is exactly the constraint `examples/dummy` retypes under.
+ *
+ * `concurrent` is what makes this safe on a live table: a CHECK needs no index, so it can always be
+ * added `not valid` in the transaction, scanning nothing, with its `validate constraint` in the
+ * deferred step. A name that was rebuilt or moved aside stays plain: that column's rewrite already
+ * holds ACCESS EXCLUSIVE, and a window with an unvalidated constraint would buy nothing. Omitted,
+ * every constraint takes the plain form, which is what a caller outside `generateMigration` gets.
+ *
+ * A column `retired` keeps its own check recorded and untouched until the drop takes both.
  */
 export function checkPlan(
   entity: EntityDescriptionLike,
@@ -178,6 +198,7 @@ export function checkPlan(
   plan: { up: string[]; down: string[] },
   rebuilt: ReadonlySet<string> = new Set(),
   predropped: ReadonlySet<string> = new Set(),
+  concurrent?: ConcurrentPlan,
 ): void {
   const recorded = new Map((live.checks ?? []).map((check) => [check.name, check]));
   const present = new Set(live.columns.map((column) => column.name));
@@ -202,22 +223,28 @@ export function checkPlan(
   for (const check of wanted) {
     const gone = dropped.has(check.name) || predropped.has(check.name);
     const held = gone ? undefined : recorded.get(check.name);
+    if (held !== undefined && held.expression === check.expression) continue;
+    const online = concurrent !== undefined && !gone;
+    const add = online ? addCheckNotValid : addCheck;
+    if (online) deferValidate(entity.table, check.name, concurrent);
     if (held === undefined) {
       plan.up.push(
         ...(exposed.has(check.name) && !predropped.has(check.name)
-          ? rebuildCheck(entity.table, check)
-          : [addCheck(entity.table, check)]),
+          ? rebuildCheck(entity.table, check, add)
+          : [add(entity.table, check)]),
       );
       plan.down.push(dropCheck(entity.table, check.name));
       continue;
     }
-    if (held.expression === check.expression) continue;
-    plan.up.push(dropCheck(entity.table, check.name), addCheck(entity.table, check));
+    plan.up.push(dropCheck(entity.table, check.name), add(entity.table, check));
     plan.down.push(addCheck(entity.table, held), dropCheck(entity.table, check.name));
   }
   const declared = new Set(wanted.map((check) => check.name));
+  const retired = new Set(
+    (entity.retired ?? []).map((column) => spellColumnCheckName(entity.table, column)),
+  );
   for (const check of live.checks ?? []) {
-    if (declared.has(check.name) || predropped.has(check.name)) continue;
+    if (declared.has(check.name) || predropped.has(check.name) || retired.has(check.name)) continue;
     plan.up.push(dropCheck(entity.table, check.name));
     plan.down.push(addCheck(entity.table, check));
   }

package/src/client.ts

@@ -4,7 +4,7 @@
 // `Bun.SQL` slice in `bun-sql.ts` and the observed statement funnel in `statement-funnel.ts`, so
 // importing this module never opens a socket.
 
-import { logger, type Role, renderThrowable, resolveRole } from '@ultimat3/core';
+import { logger, type Role, resolveRole, type Scheduler } from '@ultimat3/core';
 import {
   type BunSqlDriver,
   type BunSqlReserved,
@@ -16,16 +16,17 @@ 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, drainTimeout, driverError } from './errors';
-import {
-  assertListenChannel,
-  type DbSubscription,
-  type ListeningClient,
-  listenUnsupported,
-} from './listen';
-import { type PoolDemand, trackPool } from './pool-gauge';
+import { DbError, dbUnavailable, drainTimeout, driverError } from './errors';
+import type { DbSubscription, ListeningClient } from './listen';
+import { freeSlot, type GatedPool, poolGate, takeSlot } from './pool-gate';
+import { trackPool } from './pool-gauge';
+import { poolListeners } from './pool-listeners';
+import { noteAnswered, pinBound, pinDeadlineMs } from './pool-pins';
 import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
 import { reserveWithin } from './pool-reserve';
+import { closeRetiredPool } from './pool-retire';
+import { poolSweep, UNANSWERED_GRACE_MS } from './pool-sweep';
+import { type PoolerMode, poolerFromEnv, poolerSessionRequired, poolerWaitFor } from './pooler';
 import { type SqlFragment, sql } from './sql';
 import { affectedBy, rowsOf, runOn } from './statement-funnel';
 import { currentTx } from './transaction';
@@ -60,17 +61,44 @@ export interface PostgresClientOptions {
   readonly role?: Role | undefined;
   readonly profile?: Partial<PoolProfile> | undefined;
   readonly applicationName?: string | undefined;
+  /**
+   * The environment this pool is configured from: `DATABASE_POOLER`, `ROLE` and, with no `url`,
+   * `DATABASE_URL`. `process.env` when absent. One source per client, so a caller handed an
+   * environment cannot get its URL from it and its pooler from the process; `client.pooler` is
+   * then the one answer to "is a pooler in the path", for everything that asks afterwards.
+   */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  /**
+   * How long a statement may queue in the pooler for a backend before it counts as unanswered,
+   * added to the deadline only when a pooler is named. Default `POOLER_WAIT_MS`, PgBouncer's
+   * `query_wait_timeout`; match it to the pooler's own if that one is set.
+   */
+  readonly poolerWaitMs?: number | undefined;
+  /** Injection seam for the pool's deadlines; production passes none. */
+  readonly schedule?: Scheduler | undefined;
 }
 
 export interface PostgresClient extends ReservableClient, ListeningClient {
   readonly profile: PoolProfile;
+  readonly pooler: PoolerMode | undefined;
   ping(): Promise<void>;
   close(): Promise<void>;
 }
 
+const PIN_RETIRED =
+  'the connection this transaction holds stopped answering and was retired; nothing more is sent on it';
+
 /** Lazily connects: the pool opens on the first statement, never at import. */
 export function postgresClient(options: PostgresClientOptions = {}): PostgresClient {
-  const role = options.role ?? resolveRole();
+  const env = options.env ?? process.env;
+  const role = options.role ?? resolveRole({ env });
+  const pooler = poolerFromEnv(env);
+  const poolerWaitMs = poolerWaitFor(pooler, options.poolerWaitMs);
+  // Here, before a socket: through a transaction pooler `pg_try_advisory_lock` answers true to two
+  // migrators on one backend, and a statement could not tell either of them so.
+  if (pooler === 'transaction' && (role === 'migrate' || role === 'replicator')) {
+    throw poolerSessionRequired(`ROLE=${role}`);
+  }
   const profile: PoolProfile = assertPoolProfile({
     ...poolProfileFor(role),
     ...(options.profile ?? {}),
@@ -79,28 +107,64 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
   // as ONE value: a pool still draining after `close()` settles its own work against its own
   // counter, never against the pool that replaced it. Built only once the driver exists, so a
   // connection string that cannot be built registers no pool in `db_pool_max`.
-  let driver: { readonly pool: BunSqlDriver; readonly demand: PoolDemand } | undefined;
+  // The gate rides on it for the same reason: a pin held on a retired pool is no slot of the new one.
+  type LivePool = GatedPool & { readonly pool: BunSqlDriver };
+  let driver: LivePool | undefined;
+  const listeners = poolListeners(() => connect().pool, options.schedule);
+  // Every statement past it is rejected and its pool retired: pooled, or on a pin against the bound
+  // in force on that connection (`pool-pins.ts`). `0` (`migrate`, `replicator`): none.
+  // Behind a pooler the server's bound starts only once a backend is assigned.
+  const beyondBoundMs = UNANSWERED_GRACE_MS + poolerWaitMs;
+  const sweep =
+    profile.statementTimeoutMs === 0
+      ? undefined
+      : poolSweep<LivePool>({
+          deadlineMs: profile.statementTimeoutMs + beyondBoundMs,
+          onMiss: retire,
+          schedule: options.schedule,
+        });
 
-  function connect(): { readonly pool: BunSqlDriver; readonly demand: PoolDemand } {
+  function connect(): LivePool {
     if (driver !== undefined) return driver;
-    const url = connectionUrl(options, profile);
+    const url = connectionUrl(
+      { ...options, url: options.url ?? env['DATABASE_URL'], pooler },
+      profile,
+    );
     const Factory = bunSqlFactory();
-    driver = { pool: new Factory(url, bunSqlPoolOptions(profile)), demand: trackPool(profile.max) };
+    driver = {
+      pool: new Factory(url, bunSqlPoolOptions(profile)),
+      demand: trackPool(profile.max),
+      gate: poolGate(profile.max, options.schedule),
+    };
     return driver;
   }
 
+  /** A statement went unanswered on `missed`. Its stragglers miss too, and retire nothing newer. */
+  function retire(missed: LivePool, excerpt: string, waitedMs: number): void {
+    if (driver !== missed) return;
+    // Read-then-clear, as `close()` does: the next `connect()` opens a fresh pool, never this one.
+    driver = undefined;
+    missed.demand.close();
+    logger.error('db.pool.retired', { statement: excerpt, waitedMs, role });
+    closeRetiredPool(missed.pool);
+    missed.gate.handOverWaiting();
+    listeners.redial();
+  }
+
   async function run(fragment: SqlFragment): Promise<unknown> {
-    const { pool, demand } = connect();
-    demand.enter();
+    const slot = takeSlot(connect, profile.acquireTimeoutMs);
+    const live = slot instanceof Promise ? await slot : slot;
     try {
-      return await runOn(pool, fragment);
+      const sending = runOn(live.pool, fragment);
+      return await (sweep === undefined ? sending : sweep.track(live, fragment.text, sending));
     } finally {
-      demand.leave();
+      freeSlot(live);
     }
   }
 
   const client: PostgresClient = {
     profile,
+    pooler,
     async query<T>(fragment: SqlFragment): Promise<readonly T[]> {
       return rowsOf<T>(await run(fragment));
     },
@@ -116,14 +180,20 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
       // (`ERR_POSTGRES_UNSAFE_TRANSACTION`), and a BEGIN that landed on a different connection
       // than the statement after it would not be a transaction at all — which is exactly what
       // `withTransaction` and `readOnlyQuery` depend on being true.
-      const { pool, demand } = connect();
+      // One gate slot for the life of the pin, so one number counts statements and pins alike.
+      const budget = profile.acquireTimeoutMs;
+      const started = performance.now();
+      const live = await takeSlot(connect, budget);
       let reserved: BunSqlReserved;
-      // Counted from the ASK: a pin queued behind a full pool is exactly what `waiting` reports.
-      demand.enter();
       try {
-        reserved = await reserveWithin(pool, profile);
+        // `reserveWithin` keeps its own timer for `Bun.SQL`'s queue, on what the gate left of ONE
+        // budget: two full timers made `web` wait 10 s for a pin promised in 5. At least 1 ms, since
+        // a budget of 0 means "wait forever" there.
+        const left =
+          budget === 0 ? 0 : Math.max(1, Math.round(budget - (performance.now() - started)));
+        reserved = await reserveWithin(live.pool, profile, left);
       } catch (error) {
-        demand.leave();
+        freeSlot(live);
         // Acquiring the pin is the one step that runs outside `runOn`, so an exhausted or
         // unreachable pool would escape as an untyped driver error — and `readOnlyQuery` reaches
         // this line before its first statement, which is how MCP ends up returning something
@@ -133,20 +203,38 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
         throw driverError('could not reserve a connection from the pool', error);
       }
       let held = true;
+      const pin = pinBound(profile.statementTimeoutMs);
       // Direct only while the pin is held. `release()` hands this physical connection back, and
       // the pool may already have given it to another unit of work mid-transaction — a statement
       // issued on the stale handle would land inside theirs, committed or rolled back with it and
       // no error anywhere to explain the row. So a late statement takes its own connection out of
       // the pool, exactly like any other caller. Same rule as `pglite.ts`, one driver down.
       const on = (fragment: SqlFragment): Promise<unknown> =>
-        held ? runOn(reserved, fragment) : run(fragment);
+        held ? onPinned(fragment) : run(fragment);
+      // A miss retired the pool; this connection is never written to again, so the transaction's
+      // ROLLBACK is refused here rather than waiting out a second bound on the same dead path.
+      const onPinned = async (fragment: SqlFragment): Promise<unknown> => {
+        if (pin.dead) throw dbUnavailable(PIN_RETIRED);
+        const sending = runOn(reserved, fragment);
+        const deadlineMs = pinDeadlineMs(pin, beyondBoundMs);
+        try {
+          const answer = await (sweep === undefined
+            ? sending
+            : sweep.track(live, fragment.text, sending, deadlineMs));
+          noteAnswered(pin, fragment, profile.statementTimeoutMs);
+          return answer;
+        } catch (error) {
+          if (error instanceof DbError && error.code === 'X_DB_UNAVAILABLE') pin.dead = true;
+          throw error;
+        }
+      };
       // Idempotent because two owners already exist on one exit path: `withTransaction` releases
       // in a `finally` and `[Symbol.dispose]` fires on the same scope. A second `release()` on a
       // handle already back in the pool frees whoever holds that connection now.
       const release = (): void => {
         if (!held) return;
         held = false;
-        demand.leave();
+        freeSlot(live);
         // Total by construction — `releaseReserved` owns the reason (`bun-sql.ts`).
         releaseReserved(reserved);
       };
@@ -158,29 +246,8 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
         [Symbol.dispose]: release,
       };
     },
-    async listen(channel, onNotify, onListening): Promise<DbSubscription> {
-      assertListenChannel(channel);
-      const { pool } = connect();
-      if (pool.listen === undefined) throw listenUnsupported('this Bun.SQL');
-      let held: { unlisten(): Promise<void> };
-      try {
-        // The driver's own session, never a pin out of the pool: a reserved connection holds the
-        // LISTEN and surfaces no notification, and it would cost the pool a slot for good.
-        held = await pool.listen(channel, onNotify, onListening);
-      } catch (error) {
-        throw driverError(`LISTEN ${channel}`, error);
-      }
-      let ended: Promise<void> | undefined;
-      return {
-        unlisten: () => {
-          // Best-effort, the rule `releaseReserved` states: the session this would end may be
-          // gone with the pool already, and that is the outcome asked for.
-          ended ??= held.unlisten().catch((error: unknown) => {
-            logger.debug('db.unlisten_failed', { error: renderThrowable(error) });
-          });
-          return ended;
-        },
-      };
+    listen(channel, onNotify, onListening): Promise<DbSubscription> {
+      return listeners.listen(channel, onNotify, onListening);
     },
     async ping(): Promise<void> {
       await client.query(sql`select 1`);
@@ -193,7 +260,12 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
       // rejection still reaches the caller — a shutdown that could not drain wants to know.
       const closing = driver;
       driver = undefined;
+      listeners.drop();
       if (closing === undefined) return;
+      // A queued statement must not outlive this and open a pool in a process shutting down.
+      closing.gate.refuseWaiting(
+        dbUnavailable('the pool closed while this statement waited for a slot'),
+      );
       // Only THIS pool's counter leaves the totals; its in-flight work settles against it.
       closing.demand.close();
       const { pool } = closing;
@@ -236,10 +308,22 @@ export function postgresClient(options: PostgresClientOptions = {}): PostgresCli
 }
 
 let ambient: DbClient | undefined;
+// Separate from `ambient`, which the lazy default also fills: a unit test that sent one statement
+// through `db()` must not flip `@ultimat3/entity`'s `testDriver()` onto a pool nobody asked for.
+let installed = false;
 
 /** Test/dev seam. `setDbClient(undefined)` restores lazy construction from `DATABASE_URL`. */
 export function setDbClient(client: DbClient | undefined): void {
   ambient = client;
+  installed = client !== undefined;
+}
+
+/**
+ * Whether `setDbClient` installed a client that is still in place. Asking never builds the lazy
+ * default — `testDriver()` asks on every repository call of every unit test.
+ */
+export function dbClientInstalled(): boolean {
+  return installed;
 }
 
 /**