@ultimat3/db 16.0.0 → 18.0.0

package/src/drift-findings.ts

@@ -14,6 +14,7 @@
 import { onDeleteRule, rebuildForeignKey } from './foreign-key';
 import type { CheckDescription, ForeignKeyDescription } from './introspect';
 import type { Migration } from './migrate';
+import { shellInertIdentifier } from './sql';
 
 export type DriftKind =
   | 'unexpected-column'
@@ -41,6 +42,15 @@ export interface DriftReport {
   readonly differences: readonly DriftDifference[];
 }
 
+/**
+ * The one `fix:` here whose second layer no quoting closes. `x db gen "add C"` puts the column
+ * inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick substitute before `x` is reached at all
+ * — and the argument is a migration DESCRIPTION, not an identifier, so there is no quoted form
+ * that would make a hostile name safe to pass. A name `shellInertIdentifier` (`sql.ts`) refuses
+ * is therefore left out of the command rather than escaped into it: the command still runs and
+ * still generates the migration, and the name is read off `cause` and `column`, which are prose
+ * nobody pastes.
+ */
 export function unexpectedColumn(table: string, column: string): DriftDifference {
   return {
     kind: 'unexpected-column',
@@ -48,7 +58,12 @@ export function unexpectedColumn(table: string, column: string): DriftDifference
     column,
     // Pinned by the contract. Do not reword without changing docs/errors/X_DB_DRIFT.
     cause: `table "${table}" has column "${column}" not present in any migration`,
-    fix: `x db gen "add ${column}"`,
+    fix:
+      shellInertIdentifier(column) === null
+        ? 'x db gen "add the undeclared column"   # the live column name carries a backtick, a ' +
+          'dollar sign, a quote, a backslash or whitespace, so it is in the cause and not in ' +
+          'this command'
+        : `x db gen "add ${column}"`,
   };
 }
 
@@ -82,6 +97,8 @@ export function changedColumn(
   liveNullable: boolean,
 ): DriftDifference {
   const clause = liveNullable ? 'set not null' : 'drop not null';
+  const relation = shellInertIdentifier(table);
+  const attribute = shellInertIdentifier(column);
   return {
     kind: 'changed-column',
     table,
@@ -89,19 +106,47 @@ export function changedColumn(
     cause: liveNullable
       ? `table "${table}" allows NULL in column "${column}" that migrations declare not null`
       : `table "${table}" forbids NULL in column "${column}" that migrations declare nullable`,
+    // Both identifiers are the catalog's, so both go through the one screen. A refusal names the
+    // column as the thing it could not spell, which is what tells this line apart from
+    // `missingCheck`'s refusal in a report that carries both.
     fix:
-      `alter table "${table}" alter column "${column}" ${clause};   # in a new migration` +
-      (liveNullable ? ' — backfill the existing NULLs first' : ''),
+      relation === null || attribute === null
+        ? `${clause} on the column named in this difference, in a new migration, then ` +
+          'x db migrate — its table or column name carries a backtick, a dollar sign, a quote, ' +
+          'a backslash or whitespace, so no statement here can spell it'
+        : `alter table ${relation} alter column ${attribute} ${clause};   # in a new migration` +
+          (liveNullable ? ' — backfill the existing NULLs first' : ''),
   };
 }
 
+/**
+ * The `fix:` names the two edits that actually resolve this, and neither is `x db gen` (issue
+ * #345). That command diffs the ENTITY REGISTRY against the newest snapshot, and a table nothing
+ * declares is absent from both sides of that diff — so it wrote an EMPTY migration, and the
+ * generator's own empty-diff branch writes no file at all, leaving the reader with nothing to run
+ * and the same finding on the next deploy.
+ *
+ * What is left once `@ultimat3/cli`'s `acceptCreatedTables` has run is a table no migration's SQL
+ * creates and no entity declares — so either a migration should claim it (`if not exists`, because
+ * the relation is already there, and `x db migrate` then accepts a table its own SQL creates), or
+ * nothing owns it and it should not be in this schema. No migration PATH is named: where an app
+ * keeps its migrations is the CLI's fact, not this package's.
+ */
 export function unexpectedTable(table: string): DriftDifference {
+  const name = shellInertIdentifier(table);
   return {
     kind: 'unexpected-table',
     table,
     column: null,
     cause: `table "${table}" is not present in any migration`,
-    fix: `x db gen "add ${table}"`,
+    fix:
+      name === null
+        ? 'claim it in a migration with create table if not exists, or drop it by hand — its ' +
+          'table name carries a backtick, a dollar sign, a quote, a backslash or whitespace, so ' +
+          'no statement here can spell it'
+        : `put a create table if not exists ${name} (…) statement in a migration — x db migrate ` +
+          'then accepts a table its own SQL creates — or, if nothing owns it, run ' +
+          `drop table ${name}; inside psql "$DATABASE_URL"`,
   };
 }
 
@@ -174,6 +219,8 @@ export function changedIndex(table: string, index: string, detail: string): Drif
  * the predicate, which is what makes an executable fix possible at all.
  */
 export function missingCheck(table: string, check: CheckDescription): DriftDifference {
+  const relation = shellInertIdentifier(table);
+  const constraint = shellInertIdentifier(check.name);
   return {
     kind: 'missing-check',
     table,
@@ -183,9 +230,19 @@ export function missingCheck(table: string, check: CheckDescription): DriftDiffe
     // banned advice word the `errors` gate demands a command beside: writing the migration is half
     // the repair and applying it is the other half, and `changedColumn`'s bare `# in a new
     // migration` leaves the second half to be guessed.
+    //
+    // Both NAMES go through the one screen; the EXPRESSION deliberately does not, and cannot. It
+    // is a predicate, so no screen could accept `status in ('draft', 'published')` and reject a
+    // second statement — and it is the DECLARED side's own text, out of the author's migration,
+    // where both names are the catalog's and a sidecar's. Narrower than "this line is safe", and
+    // it is the honest claim.
     fix:
-      `alter table "${table}" add constraint "${check.name}" ` +
-      `check (${check.expression});   # in a new migration, then x db migrate`,
+      relation === null || constraint === null
+        ? 'add the constraint named in this difference back in a new migration, then ' +
+          'x db migrate — its table or constraint name carries a backtick, a dollar sign, a ' +
+          'quote, a backslash or whitespace, so no statement here can spell it'
+        : `alter table ${relation} add constraint ${constraint} ` +
+          `check (${check.expression});   # in a new migration, then x db migrate`,
   };
 }
 

package/src/drift-fixtures.ts

@@ -0,0 +1,23 @@
+// TEST-ONLY. The two builders every drift suite compares with — a `TableDescription` of text
+// columns and the `SchemaDescription` around it. One copy, because three suites arguing about
+// schemas built differently would each be judging a different fixture. Never exported from
+// `index.ts`.
+
+import type { SchemaDescription, TableDescription } from './introspect';
+
+export const table = (name: string, columns: readonly string[]): TableDescription => ({
+  schema: 'public',
+  name,
+  columns: columns.map((column, index) => ({
+    name: column,
+    dataType: 'text',
+    nullable: true,
+    default: null,
+    position: index + 1,
+  })),
+  primaryKey: ['id'],
+  indexes: [],
+  foreignKeys: [],
+});
+
+export const schema = (...tables: readonly TableDescription[]): SchemaDescription => ({ tables });

package/src/errors.ts

@@ -285,15 +285,6 @@ export const serializationExhausted = (attempts: number, sourceError: unknown):
     sourceError,
   });
 
-/** The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync. */
-export const dbDrift = (tableName: string, columnName: string): DbError =>
-  new DbError({
-    code: 'X_DB_DRIFT',
-    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
-    fix: `x db gen "add ${columnName}"`,
-    meta: { table: tableName, column: columnName },
-  });
-
 export const sqlUnsafe = (received: string, position: number): DbError =>
   new DbError({
     code: 'X_SQL_UNSAFE',

package/src/generate.ts

@@ -22,6 +22,8 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
+import type { ReplicaIdentityInput } from './replica-identity';
+import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
 import type { MovedAside } from './retype-dependents';
 import { moveDependentsAside } from './retype-dependents';
 import { moveKeysAside, retypedColumns, retypedIn } from './retype-keys';
@@ -54,7 +56,13 @@ function columnClause(column: ColumnDescriptionLike): string {
   return parts.join(' ');
 }
 
-export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDescription {
+/** No table subscribed to, which is what every caller outside `generateMigration` describes. */
+const NONE: ReadonlySet<string> = new Set();
+
+export function snapshotOf(
+  entities: readonly EntityDescriptionLike[],
+  replicaIdentityFull: ReadonlySet<string> = NONE,
+): SchemaDescription {
   const tables = [...entities]
     .sort((a, b) => (a.table < b.table ? -1 : 1))
     .map((entity): TableDescription => {
@@ -99,6 +107,9 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
         // read as "nothing recorded" so the next generation adds the constraints the database is
         // genuinely missing — the rule `using` and `generated` already state one field up.
         ...(checks.length === 0 ? {} : { checks }),
+        // The same rule once more: `true` or absent, never `false`. This is what makes the ALTER
+        // beside it a one-time statement rather than a line every `x db gen` writes again.
+        ...(replicaIdentityFull.has(entity.table) ? { replicaIdentityFull: true as const } : {}),
       };
     });
   return { tables };
@@ -227,6 +238,17 @@ export interface GenerateOptions {
   readonly now?: Date | undefined;
   /** Allow a DROP COLUMN whose down cannot restore the data. `x db gen --allow-destructive`. */
   readonly allowDestructive?: boolean | undefined;
+  /**
+   * Tables a live query subscribes to, so logical replication carries the old row —
+   * `@ultimat3/realtime` refuses a subscription without it. Absent or empty emits nothing.
+   *
+   * A parameter and never an `EntityDescriptionLike` field: which tables need it is DECLARED by
+   * each `live: true` query's `subscribes:`, never derived — the relation is a literal inside the
+   * query's `sql:` callback, which nothing can invoke without valid input. This package is tier 1
+   * and can see neither the manifest nor `@ultimat3/query`, so `@ultimat3/cli`'s `db-generate.ts`
+   * is the one caller that can answer it.
+   */
+  readonly replicaIdentityFull?: readonly string[] | undefined;
 }
 
 export interface GeneratedMigration {
@@ -275,6 +297,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   // of one key can move in two different entities' diffs (`retype-keys.ts`).
   const preAlters: Plan = { up: [], down: [] };
   const wanted = new Set(options.entities.map((entity) => entity.table));
+  // The tables this run brings into being, read by the replica-identity arm below: their `down` is
+  // already `drop table`, so reverting the identity ahead of it performs nothing.
+  const created = new Set<string>();
 
   const doomed = new Set(
     current.tables.filter((table) => !wanted.has(table.name)).map((table) => table.name),
@@ -291,6 +316,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     if (live === undefined) {
       plan.up.push(...createTable(entity));
       plan.down.push(`drop table ${identifier(entity.table).text};`);
+      created.add(entity.table);
       continue;
     }
     diffTable(entity, live, plan, retypedIn(retyped, entity.table));
@@ -337,6 +363,18 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
   plan.up.push(...constraints.up);
   plan.down.push(...constraints.down);
 
+  // Dead last in `up`, and it is the only placement that is right for every arm: the table has to
+  // exist, and a `create table` in this same migration is the reason it might not. It is ordered
+  // against nothing else — replica identity constrains no column, no index and no constraint — so
+  // the end is where it can never be read as depending on a statement above it.
+  const replicaIdentity: ReplicaIdentityInput = {
+    wanted: options.replicaIdentityFull,
+    declared: wanted,
+    created,
+    current,
+  };
+  replicaIdentityPlan(plan, replicaIdentity);
+
   const id = `${migrationStamp(options.now ?? systemClock.now())}_${slugify(options.name)}`;
   // At the TOP of `up`, so what is MISSING is the first thing read — and a line comment, so it is
   // noise to every reader that matters: `statementsOf` drops a chunk of comments alone,
@@ -362,7 +400,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
     // FRONT here precisely so reversal puts it last — a key is added back only once both of its
     // ends have been retyped back, which is every other statement in the script.
     down: [...preAlters.down, ...plan.down].reverse().join('\n'),
-    snapshot: snapshotOf(options.entities),
+    snapshot: snapshotOf(options.entities, replicaIdentityFullAfter(replicaIdentity)),
     destructive: isDestructive(up),
     unrendered,
   };

package/src/index.ts

@@ -23,25 +23,15 @@ export {
 export type {
   DbClient,
   DbConnection,
-  DbHealthReport,
-  PoolProfile,
   PostgresClient,
   PostgresClientOptions,
   ReservableClient,
 } from './client';
-export {
-  baseClient,
-  checkDb,
-  createPostgresClient,
-  db,
-  isReservable,
-  POOL_MAX_ENV,
-  POOL_PROFILES,
-  poolProfileFor,
-  setDbClient,
-} from './client';
+export { baseClient, createPostgresClient, db, isReservable, setDbClient } from './client';
 export type { ColumnDefaultLike } from './column-default';
 export { defaultExpression } from './column-default';
+export type { DbHealthReport } from './db-health';
+export { checkDb } from './db-health';
 export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {
@@ -62,6 +52,7 @@ export {
   expectedSchema,
   FRAMEWORK_TABLE_PREFIX,
 } from './drift';
+export { dbDrift } from './drift-errors';
 export type {
   ColumnDescriptionLike,
   EntityDescriptionLike,
@@ -76,7 +67,6 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbDrift,
   dbNotImplemented,
   dbUnavailable,
   driverError,
@@ -169,6 +159,8 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { PoolProfile } from './pool-profile';
+export { POOL_MAX_ENV, POOL_PROFILES, poolProfileFor } from './pool-profile';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
@@ -185,7 +177,15 @@ export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope'
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
-export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export {
+  identifier,
+  isSqlFragment,
+  join,
+  literal,
+  raw,
+  shellInertIdentifier,
+  sql,
+} from './sql';
 export { stripSqlNoise } from './sql-noise';
 export type { DbSqlStateCode } from './sqlstate';
 export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';

package/src/introspect.ts

@@ -105,6 +105,22 @@ export interface TableDescription {
    * read one instead of reporting every declared constraint as missing.
    */
   readonly checkNames?: readonly string[] | undefined;
+  /**
+   * That a migration set `replica identity full` on this table — what `@ultimat3/realtime` requires
+   * of every table a live query subscribes to, and the only reason this generator emits it.
+   *
+   * `true` or absent, never `false`, and the literal type is what enforces it. Absent means
+   * *nothing recorded*: a sidecar written before this field existed, exactly as `checks` absent
+   * means "no constraint was recorded" rather than "none is declared". Writing `false` onto every
+   * table an app has would rewrite every sidecar in the tree on the next `x db gen` for a fact that
+   * was already true — the argument `IndexDescription.using` makes about `btree`.
+   *
+   * `introspect()` never answers it. The catalog's half is `pg_class.relreplident`, which
+   * `@ultimat3/realtime`'s preflight already reads at the only moment it matters; a second reader
+   * here would let a `diffSchema` compare a declaration against a catalog value, which is the
+   * mistake `checks` and `checkNames` exist as two fields to prevent.
+   */
+  readonly replicaIdentityFull?: true | undefined;
 }
 
 export interface SchemaDescription {

package/src/migrate.ts

@@ -3,18 +3,13 @@
 // app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
 // another build already owns, because the alternative is two schemas racing during a rollout.
 
-import { appVersion } from '@ultimat3/core';
-import {
-  baseClient,
-  type DbClient,
-  type DbConnection,
-  isReservable,
-  poolProfileFor,
-} from './client';
+import { appVersion, finiteCount } from '@ultimat3/core';
+import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
 import type { SchemaDescription } from './introspect';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
+import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
@@ -237,6 +232,9 @@ async function acquireLock(session: DbClient, waitMs: number): Promise<void> {
           sql`select pg_try_advisory_lock(${MIGRATION_LOCK_KEY}) as locked`,
         );
         if (row?.locked === true) return;
+        // `waitMs` is screened at both call sites: `NaN - elapsed` is `NaN`, `NaN <= 0` is false
+        // and `Bun.sleep(Math.min(POLL, NaN))` does not sleep — so an unbounded wait is not what a
+        // non-finite one produced, a tight spin re-taking `pg_try_advisory_lock` was.
         const remaining = waitMs - (performance.now() - started);
         if (remaining <= 0) {
           throw migrateConcurrent(MIGRATION_LOCK_KEY, Math.round(performance.now() - started));
@@ -317,7 +315,17 @@ async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
  * same `ACCESS EXCLUSIVE` locks against the same tables.
  */
 function migrationLockTimeoutMs(explicit: number | undefined): number {
-  return explicit ?? poolProfileFor('migrate').lockTimeoutMs;
+  // Screened here, where BOTH `migrate()` and `rollback()` resolve it, and before either takes the
+  // advisory lock. `lockWaitMs` beside it was screened from the start and this one was not, so
+  // `Number(process.env.…)` on an unset variable travelled all the way to `SET LOCAL lock_timeout
+  // = NaN`, which the server rejects inside the migration's own transaction — the option that was
+  // wrong appears nowhere in what the deploy prints. `finiteCount`, never a second bound checker.
+  return finiteCount(
+    'migrate',
+    'lockTimeoutMs',
+    explicit ?? poolProfileFor('migrate').lockTimeoutMs,
+    0,
+  );
 }
 
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
@@ -329,7 +337,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       await ensureLedger(session);
       const ledger = await readLedger(session);
@@ -419,7 +427,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
   return withAdvisoryLock(
     client,
     options.lock !== false,
-    options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS,
+    finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       const ledger = await readLedger(session);
       const targets = [...ledger].reverse().slice(0, steps);

package/src/pool-profile.ts

@@ -0,0 +1,125 @@
+// Single responsibility: the five 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.
+
+import { assert, type Role, resolveRole } from '@ultimat3/core';
+import { poolMaxInvalid } from './errors';
+
+export interface PoolProfile {
+  readonly max: number;
+  /** 0 disables the timeout — only `migrate`, which is allowed to take as long as it takes. */
+  readonly statementTimeoutMs: number;
+  readonly idleTimeoutMs: number;
+  /**
+   * How long a statement may **wait for a lock** before `55P03`, distinct from how long it may run.
+   * 0 everywhere but `migrate`, which is the only role that takes `ACCESS EXCLUSIVE`: an `alter
+   * table` queued behind a long `SELECT` puts every later query on that table behind it too,
+   * because Postgres' lock queue is FIFO — and `migrate` runs `statement_timeout = 0`, so nothing
+   * else would ever end the wait. Read by `migrate()` as a `SET LOCAL`, never by the pool.
+   */
+  readonly lockTimeoutMs: number;
+  /**
+   * How long `reserve()` may wait for a free connection before `X_DB_POOL_EXHAUSTED`. 0 waits
+   * forever, which is what a run-once role wants and what a request-serving one must never do:
+   * queueing turns exhaustion into a hang, `/readyz`'s `select 1` joins the same queue, the kubelet
+   * kills the pod, and the replacement inherits the same saturated database.
+   */
+  readonly acquireTimeoutMs: number;
+}
+
+/** Sized per role because the failure modes differ: RPS bursts vs. queue depth vs. run-once. */
+export const POOL_PROFILES = Object.freeze<Record<Role, PoolProfile>>({
+  web: {
+    max: 20,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  sync: {
+    max: 10,
+    statementTimeoutMs: 10_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 5_000,
+  },
+  worker: {
+    max: 8,
+    statementTimeoutMs: 120_000,
+    idleTimeoutMs: 30_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_000,
+  },
+  scheduler: {
+    max: 2,
+    statementTimeoutMs: 15_000,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 10_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
+  // advisory lock's, and `MIGRATION_LOCK_WAIT_MS` bounds it.
+  migrate: {
+    max: 1,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 10_000,
+    lockTimeoutMs: 3_000,
+    acquireTimeoutMs: 0,
+  },
+  replicator: {
+    max: 4,
+    statementTimeoutMs: 0,
+    idleTimeoutMs: 60_000,
+    lockTimeoutMs: 0,
+    acquireTimeoutMs: 0,
+  },
+});
+
+export function poolProfileFor(role: Role = resolveRole()): PoolProfile {
+  return POOL_PROFILES[role];
+}
+
+/** The one pool knob an operator can turn without a rebuild. Layered over the role default. */
+export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
+
+/**
+ * `DATABASE_POOL_MAX`, or nothing. `POOL_PROFILES` is frozen into the build, so before this the
+ * only way to change a fleet's connection count was to ship a new image — and 400 `web` pods at
+ * `max: 20` is 8,000 backends against a `max_connections` of 450. An unparseable value **refuses**
+ * rather than falling back: a fleet that ignored the number it was given is the failure the
+ * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
+ */
+export function poolMaxFromEnv(): Partial<PoolProfile> {
+  const raw = process.env[POOL_MAX_ENV];
+  if (raw === undefined || raw.trim() === '') return {};
+  const max = Number(raw);
+  if (!Number.isSafeInteger(max) || max < 1) throw poolMaxInvalid(raw);
+  return { max };
+}
+
+/**
+ * The five 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
+ * 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
+ * budgets that document it as "no bound"; `max` is at least one connection, or nothing can run.
+ */
+export function assertPoolProfile(profile: PoolProfile): PoolProfile {
+  const whole = (option: string, value: number, min: 0 | 1): void => {
+    assert(
+      Number.isSafeInteger(value) && value >= min,
+      `pool profile ${option} is ${String(value)}; it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more, where 0 is the documented "no bound"'}`,
+      `pass a whole number for ${option} in createPostgresClient({ profile }), and parse an environment value first — Number(process.env.DATABASE_${option.toUpperCase()} ?? '') is NaN when the variable is unset`,
+    );
+  };
+  whole('max', profile.max, 1);
+  whole('statementTimeoutMs', profile.statementTimeoutMs, 0);
+  whole('idleTimeoutMs', profile.idleTimeoutMs, 0);
+  whole('lockTimeoutMs', profile.lockTimeoutMs, 0);
+  whole('acquireTimeoutMs', profile.acquireTimeoutMs, 0);
+  return profile;
+}

package/src/pool-reserve.ts

@@ -0,0 +1,50 @@
+// Single responsibility: pinning a connection out of the pool under the profile's acquire deadline,
+// 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 { poolAcquireTimeout } from './errors';
+import type { PoolProfile } from './pool-profile';
+
+/**
+ * `pool.reserve()` under a deadline. Without one an exhausted pool does not fail, it **queues** —
+ * so a slow endpoint filling all 20 slots turns every later request, `/readyz`'s `select 1`
+ * included, into a wait with no end and no error, and the pod is killed for being unready rather
+ * than answering 503 for the requests it cannot serve.
+ *
+ * The losing reservation is released, never dropped: the pool hands out a connection whenever one
+ * frees, deadline or no deadline, and a pin nobody holds is a connection nobody gets back. That is
+ * the whole reason this is not a bare `Promise.race`.
+ */
+export async function reserveWithin(
+  pool: Pick<BunSqlDriver, 'reserve'>,
+  profile: PoolProfile,
+): Promise<BunSqlReserved> {
+  const budget = profile.acquireTimeoutMs;
+  if (budget <= 0) return pool.reserve();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let expired = false;
+  const pending = pool.reserve();
+  try {
+    return await Promise.race([
+      pending,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          expired = true;
+          reject(poolAcquireTimeout(budget, profile.max));
+        }, budget);
+        // The deadline must not be what keeps a finished process alive.
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    // Attached unconditionally so a rejection arriving after we gave up is handled, not unhandled.
+    void pending.then(
+      (late) => {
+        if (expired) late.release();
+      },
+      () => undefined,
+    );
+  }
+}

package/src/readonly-query.ts

@@ -3,6 +3,7 @@
 // enforcing read-only beats a regex, and the timeout bounds a runaway scan the agent never
 // meant to ask for.
 
+import { finiteCount } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { multipleStatements } from './errors';
 import { identifier, raw, sql } from './sql';
@@ -89,6 +90,26 @@ export async function readOnlyQuery<T>(
   const statements = statementsOf(statement);
   if (statements.length > 1) throw multipleStatements(statement, statements.length);
 
+  // Decided before anything is opened, for the reason `rollback({ steps })` screens before it
+  // takes the advisory lock: a value this build cannot honour is not a fact about the pool. It
+  // was computed after `reserve()` and after `BEGIN READ ONLY`, so an unbounded `timeoutMs`
+  // against an exhausted pool answered with the pool's error — or waited for a connection it was
+  // never going to use — in place of the `X_INVARIANT` naming the option that was wrong.
+  //
+  // Clamped and truncated to an integer: the result is a JS number the caller never touches
+  // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
+  // parameters, which is why this can't go through `sql` the normal, parameterised way.
+  // REFUSED rather than normalised: `NaN` used to take the default silently, so a config typo
+  // ran under a timeout nobody wrote. Only an explicit 0 disables the layer, which is why the
+  // floor is 0 and not 1; the hour ceiling is a clamp on a number that IS one.
+  const asked = finiteCount(
+    'readonlyQuery',
+    'timeoutMs',
+    options.timeoutMs ?? READONLY_TIMEOUT_MS,
+    0,
+  );
+  const ms = Math.min(3_600_000, asked);
+
   const client = options.client ?? baseClient();
   // A pooled BEGIN that lands on a different physical connection than the query that follows is
   // not a transaction at all, so a reservable client must pin one connection for the sequence.
@@ -104,14 +125,6 @@ export async function readOnlyQuery<T>(
     await connection.execute(raw('BEGIN READ ONLY'));
     guards.push('txn:read-only');
 
-    // Clamped and truncated to an integer: the result is a JS number the caller never touches
-    // as text, so there is nothing here for `raw()` to inject — `SET LOCAL` can't bind `$n`
-    // parameters, which is why this can't go through `sql` the normal, parameterised way.
-    // NaN normalises to the default first: only an explicit 0 disables the timeout, and
-    // `Math.min(3_600_000, NaN)` is NaN, which would fail `ms > 0` and silently skip the layer.
-    const asked = options.timeoutMs ?? READONLY_TIMEOUT_MS;
-    const requested = Number.isNaN(asked) ? READONLY_TIMEOUT_MS : asked;
-    const ms = Math.max(0, Math.min(3_600_000, Math.trunc(requested)));
     if (ms > 0) {
       // `LOCAL`, so the setting dies with the transaction — one agent read must not re-time
       // every request the pool serves afterwards. Caveat: embedded PGlite applies the setting