@ultimat3/db 20.2.1 → 22.0.0

package/README.md

@@ -440,3 +440,12 @@ x db branch drop feature_x
 half is the `drift` step of `x verify`, which hashes entity source against what `x db gen` recorded
 and opens no database. Two questions, two owners, and no `drift` subcommand under `x db` — the
 `DB_SUBCOMMANDS` set is `gen`, `migrate`, `reset`, `studio`, `branch`, `backfill`.
+
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `DbError` | any `DbErrorCode` — `DB_ERROR_CODES`, including the SQLSTATE codes a driver error maps to (`DB_SQLSTATE_CODES`) | `src/errors.ts` |

package/package.json

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

package/src/array-parameter.ts

@@ -73,19 +73,3 @@ export function pgArrayLiteral(values: readonly unknown[]): string {
   );
   return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`;
 }
-
-/**
- * Every parameter of one statement, arrays rendered and everything else passed through untouched.
- *
- * A NEW ARRAY ONLY WHEN SOMETHING CHANGED. Every statement the framework runs goes through this
- * function, and almost none of them binds an array — so the common path is one `some` over a short
- * list and the caller's own array object, byte for byte, which is what `sendOn` had before this
- * existed (axiom 6).
- *
- * A `Uint8Array` is BYTEA and is deliberately not an array here: `Array.isArray` answers `false`
- * for a typed array, which is the behaviour this relies on rather than a special case it writes.
- */
-export function encodeArrayParameters(values: readonly unknown[]): readonly unknown[] {
-  if (!values.some(Array.isArray)) return values;
-  return values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : value));
-}

package/src/bound-parameters.ts

@@ -0,0 +1,23 @@
+// Single responsibility: every value of one statement, encoded into what `Bun.SQL` sends correctly.
+// Two kinds need it, both measured against Postgres 17: a JS array (`array-parameter.ts`, #384),
+// and a `Date` once the pool runs unnamed statements (`prepare: false`, `bun-sql.ts`) — with no
+// described type to go by the driver sent `Date.prototype.toString()`, a local-zone string
+// Postgres refuses (`22007`), so every entity write carrying a timestamp failed.
+
+import { pgArrayLiteral } from './array-parameter';
+
+const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value instanceof Date;
+
+/**
+ * A NEW ARRAY ONLY WHEN SOMETHING CHANGED — every statement in the process passes through here, so
+ * the common path is one `some` and the caller's own array, byte for byte (axiom 6). A
+ * `Uint8Array` is BYTEA, never an array: `Array.isArray` answers `false` for a typed array.
+ */
+export function encodeBoundParameters(values: readonly unknown[]): readonly unknown[] {
+  if (!values.some(needsEncoding)) return values;
+  return values.map((value) => {
+    if (Array.isArray(value)) return pgArrayLiteral(value);
+    if (value instanceof Date) return value.toISOString();
+    return value;
+  });
+}

package/src/branch.ts

@@ -3,7 +3,7 @@
 // it is unsure about, a data backfill, a DROP — never happens against the shared database.
 // Branches are cheap and forgettable, so `reapBranches()` is part of the design, not an add-on.
 
-import { systemClock } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
 import { baseClient, type DbClient } from './client';
 import { branchExists, branchNameInvalid, DbError } from './errors';
 import { identifier, literal, sql } from './sql';
@@ -168,7 +168,10 @@ export interface ReapOptions extends DropBranchOptions {
  * no migration — the next `createBranch` writes the base down.
  */
 export async function reapBranches(options: ReapOptions): Promise<readonly string[]> {
-  const cutoff = (options.now ?? systemClock.now()).getTime() - options.maxAgeMs;
+  // Screened before anything is read: `now - NaN` is NaN and `createdAtMs > NaN` is false — the
+  // "old enough" answer — so `maxAgeMs: NaN` dropped every branch of this database.
+  const maxAgeMs = finiteCount('reapBranches', 'maxAgeMs', options.maxAgeMs, 0);
+  const cutoff = (options.now ?? systemClock.now()).getTime() - maxAgeMs;
   const client = options.client ?? baseClient();
   const here = await currentDatabase(client);
   const branches = await listBranches({ ...options, client });

package/src/bun-sql.ts

@@ -5,6 +5,7 @@
 
 import { logger, renderThrowable } from '@ultimat3/core';
 import { dbUnavailable } from './errors';
+import type { PoolProfile } from './pool-profile';
 
 /** One connection pinned out of `Bun.SQL`'s pool, released back by hand. */
 export interface BunSqlReserved {
@@ -72,3 +73,23 @@ export function bunSqlFactory(): BunSqlFactory {
   }
   return factory as BunSqlFactory;
 }
+
+/**
+ * What the pool is opened with. `prepare: false` is the load-bearing key: `Bun.SQL` prepares NAMED
+ * statements by default and caches them per connection, so after a migration that adds or drops a
+ * column every warm `select *` / `returning *` — every entity read and write — answered `0A000
+ * cached plan must not change result type` on every running pod until each connection closed.
+ * Reproduced on Postgres 17 (`client-prepared.live.test.ts`); PGlite uses unnamed statements, so
+ * `x dev` never showed it. Unnamed statements are also what PgBouncer's transaction mode needs.
+ *
+ * The cost, measured 2026-09-23 against Postgres 17 on loopback, 20,000 sends a side, `max: 4`:
+ * a primary-key `select *` went from p50 283-330µs to 370-432µs, an `update … returning *` from
+ * 733-744µs to 806-864µs — one extra parse per statement. Paid for correctness across a deploy.
+ */
+export const bunSqlPoolOptions = (
+  profile: Pick<PoolProfile, 'max' | 'idleTimeoutMs'>,
+): Readonly<Record<string, unknown>> => ({
+  max: profile.max,
+  idleTimeout: profile.idleTimeoutMs / 1000,
+  prepare: false,
+});

package/src/client.ts

@@ -5,7 +5,13 @@
 // importing this module never opens a socket.
 
 import { type Role, resolveRole } from '@ultimat3/core';
-import { type BunSqlDriver, type BunSqlReserved, bunSqlFactory, releaseReserved } from './bun-sql';
+import {
+  type BunSqlDriver,
+  type BunSqlReserved,
+  bunSqlFactory,
+  bunSqlPoolOptions,
+  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.
@@ -68,7 +74,7 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
     if (driver !== undefined) return driver;
     const url = connectionUrl(options, profile);
     const Factory = bunSqlFactory();
-    driver = new Factory(url, { max: profile.max, idleTimeout: profile.idleTimeoutMs / 1000 });
+    driver = new Factory(url, bunSqlPoolOptions(profile));
     return driver;
   }
 

package/src/column-alter.ts

@@ -0,0 +1,66 @@
+// Single responsibility: the attributes of an EXISTING column that move in place — its default and
+// its nullability. Split from `generate.ts` because `diffTable` emitted SQL for a type change only:
+// a changed or removed `.default()`, or a nullability change, emitted nothing while the snapshot
+// beside it recorded the move, so `x verify` answered `X_DB_SCHEMA_UNMIGRATED` and its own fix,
+// `x db gen`, produced an empty diff. A gate red forever, with the repair being the thing that failed.
+
+import { defaultExpression, hasUnrenderedDefault } from './column-default';
+import { columnDefaultUnsafe } from './ddl-errors';
+import type { ColumnDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import type { ColumnDescription } from './introspect';
+import { identifier } from './sql';
+import { statementsOf } from './statement-split';
+
+/**
+ * The recorded default comes out of a `.snapshot.json` anything may edit and is SPLICED into
+ * `down`, so it takes the one-expression screen `generatedClause` gives a generated column's.
+ * The wanted side is `defaultExpression`'s own rendering (`literal()` for a value), safe by
+ * construction, and screened anyway because the check costs one scan and the two sides then
+ * cannot drift apart.
+ */
+function screened(column: string, expression: string): string {
+  const commands = statementsOf(expression).length;
+  if (commands > 1) throw columnDefaultUnsafe(column, commands);
+  return expression;
+}
+
+/**
+ * `set default` / `drop default` and `drop not null`, each with its reverse in `down` — the shape
+ * `redefineIndex` (`index-ddl.ts`) gives a moved index. Becoming NOT NULL is deliberately NOT a
+ * bare `set not null`: rows already holding `NULL` make it fail inside `ROLE=migrate`, so it gets
+ * the expand/contract note `diffTable` writes for a NOT NULL column added to a populated table.
+ *
+ * A default this generator cannot render (`hasUnrenderedDefault`) moves nothing: dropping the one
+ * the database holds would lose a rule the entity still states, and `unrenderedOf` already reports
+ * it at the top of `up`.
+ */
+export function alterColumnInPlace(
+  table: string,
+  column: ColumnDescriptionLike,
+  recorded: ColumnDescription,
+  plan: Plan,
+): void {
+  const alter = `alter table ${identifier(table).text} alter column ${identifier(column.column).text}`;
+  const wanted = hasUnrenderedDefault(column) ? recorded.default : defaultExpression(column);
+  const held = recorded.default;
+  if (wanted !== held) {
+    const set = (expression: string | null): string =>
+      expression === null
+        ? `${alter} drop default;`
+        : `${alter} set default ${screened(column.column, expression)};`;
+    plan.up.push(set(wanted));
+    plan.down.push(set(held));
+  }
+  const nullable = !column.notNull;
+  if (nullable === recorded.nullable) return;
+  if (nullable) {
+    plan.up.push(`${alter} drop not null;`);
+    plan.down.push(`${alter} set not null;`);
+    return;
+  }
+  // `drop not null` in `down` is a no-op on a column that never became NOT NULL, so the reverse is
+  // right whether or not the backfill and its `set not null` were ever run.
+  plan.up.push(`-- backfill ${identifier(column.column).text}, then: ${alter} set not null;`);
+  plan.down.push(`${alter} drop not null;`);
+}

package/src/ddl-errors.ts

@@ -57,3 +57,16 @@ export const generatedExpressionUnsafe = (column: string, count: number): DbErro
     fix: `give "${column}" a single expression — .searchable() or generated: 'lower("title")' — then x db gen`,
     meta: { column, count },
   });
+
+/**
+ * A column default holding more than one command, refused before it is spliced into
+ * `alter column … set default …`. The recorded side arrives from a `.snapshot.json`; same lexer and
+ * same argument as `generatedExpressionUnsafe`.
+ */
+export const columnDefaultUnsafe = (column: string, count: number): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `the default of column "${column}" holds ${count} commands; a default is one expression`,
+    fix: `restore the migration's .snapshot.json from version control (git checkout -- migrations/), or give "${column}" a single .default(), then x db gen`,
+    meta: { column, count },
+  });

package/src/generate.ts

@@ -5,6 +5,7 @@
 
 import { systemClock } from '@ultimat3/core';
 import { checkClauses, checkPlan, declaredChecks } from './check-ddl';
+import { alterColumnInPlace } from './column-alter';
 import { defaultExpression } from './column-default';
 import { isDestructive } from './destructive';
 import { dropOrder } from './drop-order';
@@ -194,6 +195,10 @@ function diffTable(
     if (recorded !== undefined) {
       if (retypeColumn(live, column, recorded, plan, moved, retyped) === 'rebuilt') {
         rebuilt.add(column.column);
+      } else {
+        // After any retype, so a new default is set against the column's new type. A rebuilt
+        // column was re-added carrying its whole clause, so it has nothing left to move.
+        alterColumnInPlace(entity.table, column, recorded, plan);
       }
       continue;
     }

package/src/generated-column.ts

@@ -48,13 +48,21 @@ export function generatedClause(column: ColumnDescriptionLike): string {
     `column "${column.column}" is generated by an empty expression`,
     `give "${column.property}" an expression, or drop the generated declaration`,
   );
-  // The expression is SPLICED, so it is screened for a second command first — the rule
-  // `declaredChecks` (`check-ddl.ts`) applies to a CHECK's predicate, on the same seam and with
-  // the same lexer, so a `;` inside a string literal stays data. Measured before it:
-  // `generated always as (upper(title)); drop table users; --) stored`.
+  return ` generated always as (${oneExpression(column.column, expression)}) stored`;
+}
+
+/**
+ * Every expression this file splices passes here — the create clause, `set expression` in both
+ * directions, and the RECORDED one a `.snapshot.json` carries into `down`. The create path alone
+ * had the screen until 2026-09-23, so a CHANGED expression (`'n * 3); drop table users; --'`)
+ * landed in the migration whole. Same lexer as `declaredChecks` (`check-ddl.ts`), so a `;` inside
+ * a string literal stays data. Measured before the first half of it:
+ * `generated always as (upper(title)); drop table users; --) stored`.
+ */
+function oneExpression(column: string, expression: string): string {
   const commands = statementsOf(expression).length;
-  if (commands > 1) throw generatedExpressionUnsafe(column.column, commands);
-  return ` generated always as (${expression}) stored`;
+  if (commands > 1) throw generatedExpressionUnsafe(column, commands);
+  return expression;
 }
 
 export const isGenerated = (column: ColumnDescriptionLike): boolean =>
@@ -98,13 +106,27 @@ export function regenerate(
   moved: MovedAside,
 ): Regeneration {
   const table = live.name;
-  const wanted = column.generated ?? null;
-  const held = recorded.generated ?? null;
+  const screen = (expression: string | null | undefined): string | null =>
+    expression === null || expression === undefined
+      ? null
+      : oneExpression(column.column, expression);
+  const wanted = screen(column.generated);
+  const held = screen(recorded.generated);
   if (wanted === null && held === null) return 'unchanged';
   // Generated -> plain: the column keeps every value it computed and simply stops being derived.
   if (wanted === null) {
     plan.up.push(`${alterColumn(table, column.column)} drop expression;`);
     plan.down.push(`${alterColumn(table, column.column)} set expression as (${held ?? ''});`);
+    // A plain column at a new type needs the retype a plain column gets, `using` and all — now
+    // legal, since the expression is gone. Without it the snapshot recorded the new type over a
+    // database holding the old one, and every later generation compared new with new.
+    if (recorded.dataType !== wantedType) {
+      const retype = (type: string): string =>
+        `${alterColumn(table, column.column)} type ${type} using ` +
+        `${identifier(column.column).text}::${type};`;
+      plan.up.push(retype(wantedType));
+      plan.down.push(retype(recorded.dataType));
+    }
     return 'altered';
   }
   // Plain -> generated: `set expression` needs a column that already has one, so this is the whole

package/src/migrate.ts

@@ -474,7 +474,8 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
                 // Same reason as `auditLedger`'s: `x db status` does not exist. The `down` SQL only
                 // exists in the build that shipped it, so the fix is the read that names that build.
                 `psql "$DATABASE_URL" -c "select id, app_version from ${LEDGER_TABLE} ` +
-                  `order by id desc limit 5"   # deploy the build that shipped "${row.id}", ` +
+                  `order by id desc limit 5"   # deploy the build that shipped the migration ` +
+                  `whose id is base64 ${Buffer.from(row.id, 'utf8').toString('base64')}, ` +
                   'and roll back there — its down SQL exists nowhere else',
               );
             }

package/src/pg-instant.ts

@@ -0,0 +1,54 @@
+// Single responsibility: Postgres' TEXT form of `timestamptz` and `timestamp`, read as an instant.
+// PGlite's own parser — and Bun.SQL's on the text protocol — read year `0099` as 1999, and under a
+// session zone that is not UTC answered Invalid Date for an offset carrying seconds (local mean
+// time before a zone's standard time: `-04:56:02`), which `@ultimat3/entity` then refused as
+// `X_INVARIANT_VIOLATED` on a whole-row read. One reader, every field explicit, no `Date.parse`.
+
+/** The two instants `new Date` can hold at the ends of its range — what `±infinity` reads as. */
+const FAR_FUTURE_MS = 8.64e15;
+
+/**
+ * `YYYY-MM-DD HH:MM:SS[.frac][±HH[:MM[:SS]]][ BC]` — the ISO DateStyle output, the default and the
+ * only one a framework connection runs under. The year is four or more digits, never two.
+ */
+const PG_TIMESTAMP =
+  /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(?:([+-])(\d{2})(?::?(\d{2}))?(?::?(\d{2}))?)?( BC)?$/;
+
+const number = (text: string | undefined): number => (text === undefined ? 0 : Number(text));
+
+function parse(text: string, zoned: boolean): Date {
+  if (text === 'infinity') return new Date(FAR_FUTURE_MS);
+  if (text === '-infinity') return new Date(-FAR_FUTURE_MS);
+  const match = PG_TIMESTAMP.exec(text);
+  // Not a form this reader knows: Invalid Date, exactly what the drivers answered — a caller that
+  // validates (every entity column does) refuses it loudly rather than storing a guess.
+  if (match === null) return new Date(Number.NaN);
+  const [, year, month, day, hour, minute, second, fraction, sign, offH, offM, offS, bc] = match;
+  // Astronomical year: 1 BC is 0, 44 BC is -43.
+  const astronomical = bc === undefined ? number(year) : 1 - number(year);
+  const millis = Math.floor(number((fraction ?? '').padEnd(3, '0').slice(0, 3)));
+  const at = new Date(0);
+  // `setUTCFullYear`, never `Date.UTC(year, …)`: the latter maps 0-99 onto 1900-1999, which is the
+  // defect this file exists for.
+  at.setUTCFullYear(astronomical, number(month) - 1, number(day));
+  at.setUTCHours(number(hour), number(minute), number(second), millis);
+  if (!zoned || sign === undefined) return at;
+  const offsetMs = ((number(offH) * 60 + number(offM)) * 60 + number(offS)) * 1_000;
+  return new Date(at.getTime() - (sign === '-' ? -offsetMs : offsetMs));
+}
+
+/** `timestamptz` text: the offset it carries decides the instant. */
+export const parsePgTimestamptz = (text: string): Date => parse(text, true);
+
+/** `timestamp` text: no zone, so UTC — never the host process's zone, which is what `new Date` uses. */
+export const parsePgTimestamp = (text: string): Date => parse(text, false);
+
+/** Postgres type oids for the two. PGlite takes its parsers keyed by oid. */
+export const TIMESTAMPTZ_OID = 1184;
+export const TIMESTAMP_OID = 1114;
+
+/** What `pglite.ts` hands the embedded driver, so it never reads an instant through its own parser. */
+export const PGLITE_INSTANT_PARSERS = Object.freeze<Record<number, (text: string) => unknown>>({
+  [TIMESTAMPTZ_OID]: parsePgTimestamptz,
+  [TIMESTAMP_OID]: parsePgTimestamp,
+});

package/src/pglite.ts

@@ -4,15 +4,16 @@
 // that only ever talks to a managed Postgres must not carry 26 MB of WASM it will never load.
 
 import { statementAttribution } from './attribution';
-import type { DbConnection, ReservableClient } from './client';
+import type { DbClient, DbConnection, ReservableClient } from './client';
 import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
+import { PGLITE_INSTANT_PARSERS } from './pg-instant';
 import { createTurnQueue } from './pglite-turns';
 import type { SqlFragment } from './sql';
 import { statementExcerpt } from './statement-excerpt';
 import { withStatementSpan } from './statement-span';
-import { inLiveTx } from './transaction';
+import { liveTxConnection } from './transaction';
 
 /** What PGlite answers with. `rows` is empty for a write, which is why the count is separate. */
 export interface PgliteResult {
@@ -30,7 +31,10 @@ export interface PgliteDriver {
 
 /** The one export taken off `@electric-sql/pglite`. */
 export interface PgliteModule {
-  readonly PGlite: new (dataDir?: string) => PgliteDriver;
+  readonly PGlite: new (
+    dataDir?: string,
+    options?: { readonly parsers?: Readonly<Record<number, (text: string) => unknown>> },
+  ) => PgliteDriver;
 }
 
 /** Returns the module namespace. Unknown, not typed, because it is validated before use. */
@@ -107,7 +111,9 @@ export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<Pgl
   }
   const PGlite = pgliteConstructor(loaded);
   try {
-    return new PGlite(dataDir);
+    // `pg-instant.ts` reads every timestamp: PGlite's own parser took year 0099 for 1999 and an
+    // offset with seconds for Invalid Date under any session zone that is not UTC.
+    return new PGlite(dataDir, { parsers: PGLITE_INSTANT_PARSERS });
   } catch (error) {
     throw missing(`PGlite could not open its data directory (dataDir=${dataDir})`, error);
   }
@@ -141,6 +147,9 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
   // would otherwise build two instances over the same data directory and orphan one of them.
   let booting: Promise<PgliteDriver> | undefined;
   const turns = createTurnQueue();
+  // Every reservation this client handed out — the connections a live transaction on THIS
+  // session runs on. Weak, so a released reservation is collected with its scope.
+  const issued = new WeakSet<DbClient>();
 
   function connect(): Promise<PgliteDriver> {
     booting ??= loadPgliteDriver(options).catch((error: unknown) => {
@@ -229,7 +238,11 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     // work held the session next — a stray statement in someone else's transaction, committed or
     // rolled back with it, with no error anywhere. A closed scope falls through and takes its own
     // turn, exactly as `client.ts`'s released pin sends a late statement back to the pool.
-    if (inLiveTx()) return statement(driver, fragment);
+    // And only a transaction on THIS client's session: one open on another client says nothing
+    // about who holds this queue, and skipping it put the statement inside whatever transaction
+    // this session was running — rolled back with it (`pglite-two-clients.test.ts`).
+    const live = liveTxConnection();
+    if (live !== undefined && issued.has(live)) return statement(driver, fragment);
     return turns.run(() => statement(driver, fragment));
   }
 
@@ -263,7 +276,7 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
         held = false;
         turn.release();
       };
-      return {
+      const connection: DbConnection = {
         query: async <T>(fragment: SqlFragment) => (await on(fragment)).rows as readonly T[],
         one: async <T>(fragment: SqlFragment) =>
           ((await on(fragment)).rows[0] as T | undefined) ?? null,
@@ -271,6 +284,8 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
         release,
         [Symbol.dispose]: release,
       };
+      issued.add(connection);
+      return connection;
     },
     async ping(): Promise<void> {
       await connect();

package/src/replica-client.ts

@@ -8,6 +8,7 @@ import { type DbClient, type DbConnection, isReservable, type ReservableClient }
 import { isPlainRead } from './replica-route';
 import { markScopeWrote, replicaScope } from './replica-scope';
 import type { SqlFragment } from './sql';
+import { sqlState } from './sqlstate';
 
 export interface ReplicaStats {
   /** Statements the replica answered. */
@@ -32,6 +33,27 @@ export interface ReplicatedClient extends DbClient {
   readonly stats: ReplicaStats;
 }
 
+/**
+ * Whether a replica failure says the REPLICA could not answer, as opposed to the statement being
+ * refused. No SQLSTATE at all is a failure that never reached a server (a refused socket, a closed
+ * pool) — the `X_DB_UNAVAILABLE` case. Class `08` is a connection failure, `57P0x` an operator or
+ * crash shutdown, `40001` on a standby a conflict with recovery, `25006` a write it refused, and
+ * `53300` a replica out of connections. Everything else — `22P02` a bad cast, `42601` a syntax
+ * error, `57014` the caller's own timeout — would fail identically on the primary, so it is
+ * rethrown: counted, three of them parked a healthy replica, and every one cost two round trips.
+ */
+function replicaUnavailable(error: unknown): boolean {
+  const state = sqlState(error);
+  if (state === undefined) return true;
+  return (
+    state.startsWith('08') ||
+    state.startsWith('57P0') ||
+    state === '40001' ||
+    state === '25006' ||
+    state === '53300'
+  );
+}
+
 /** Three in a row, then a ten-second rest — an outage costs 3 doubled reads, not every read. */
 export const BREAKER_FAILURES = 3;
 export const BREAKER_COOLDOWN_MS = 10_000;
@@ -106,6 +128,12 @@ export function replicatedClient(
       consecutiveFailures = 0;
       return answer;
     } catch (error) {
+      if (!replicaUnavailable(error)) {
+        // The replica answered — with a refusal of the statement — so it is up, and the run of
+        // failures the breaker is counting is over.
+        consecutiveFailures = 0;
+        throw error;
+      }
       // Re-running is exactly-once, not at-least-once: only `isPlainRead` statements reach here,
       // and a statement a standby refused (`25006`) never executed. A replica outage therefore
       // costs latency and never an answer — which is the whole point, since a read replica is a

package/src/statement-funnel.ts

@@ -3,8 +3,8 @@
 // settle paths. Split from `client.ts` at the file-size rule; `pglite.ts` holds the mirror pair
 // (`send`/`statement`) for the embedded driver, and the two must keep answering the same way.
 
-import { encodeArrayParameters } from './array-parameter';
 import { statementAttribution } from './attribution';
+import { encodeBoundParameters } from './bound-parameters';
 import type { BunSqlDriver } from './bun-sql';
 import { driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
@@ -33,11 +33,11 @@ async function sendOn(
   fragment: SqlFragment,
 ): Promise<unknown> {
   try {
-    // `encodeArrayParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
-    // with commas, so every `any($n::T[])` in this framework sent Postgres a malformed literal and
-    // failed — the worker's claim loop among them (#384). One encoder here rather than one import
-    // per call site, because this is the only place this driver's `unsafe` is called.
-    return await driver.unsafe(fragment.text, encodeArrayParameters(fragment.values));
+    // `encodeBoundParameters`, never `fragment.values` raw: `Bun.SQL` joins a JS array's elements
+    // with commas (#384), and on the pool's unnamed statements sends a `Date` as its local-zone
+    // `toString()`. One encoder here rather than one import per call site, because this is the
+    // only place this driver's `unsafe` is called.
+    return await driver.unsafe(fragment.text, encodeBoundParameters(fragment.values));
   } catch (error) {
     // `driverError`, not `dbUnavailable`: the SQLSTATE has always been on this error and nothing
     // read it, so a `23505` from two clicks racing a signup told the operator the database was

package/src/statement-split.ts

@@ -5,6 +5,23 @@
 import { noiseAt } from './sql-scan';
 
 const WHITESPACE = /\s/;
+const WORD_START = /[A-Za-z_]/;
+const WORD = /[A-Za-z0-9_$]/;
+
+/**
+ * The blocks a `;` does not end. A PG14+ SQL-standard function body — `begin atomic … end` — holds
+ * whole statements, so its inner `;` is data; reproduced on PGlite, cutting there sent `create
+ * function … begin atomic select 1` alone (`syntax error at end of input`) and ran the rest of the
+ * body as top-level statements. A `case … end` inside such a body is tracked too, or its `end`
+ * would close the body early. Outside an atomic body nothing is tracked, so `begin; … end;` — a
+ * transaction — splits exactly as it always did.
+ */
+function trackBlocks(stack: string[], word: string, previous: string): void {
+  if (word === 'atomic' && previous === 'begin') stack.push('atomic');
+  else if (stack.length === 0) return;
+  else if (word === 'case') stack.push('case');
+  else if (word === 'end') stack.pop();
+}
 
 const isComment = (kind: string): boolean => kind === 'line-comment' || kind === 'block-comment';
 
@@ -22,6 +39,8 @@ export function statementsOf(script: string): readonly string[] {
   // Set by anything that is not whitespace and not inside a comment: what makes a chunk a
   // statement rather than a note between two of them.
   let content = false;
+  const blocks: string[] = [];
+  let previous = '';
 
   const cut = (end: number): void => {
     const text = content ? script.slice(start, end).trim() : '';
@@ -37,7 +56,18 @@ export function statementsOf(script: string): readonly string[] {
       continue;
     }
     const char = script[index] ?? '';
-    if (char === ';') {
+    // A word starts only after a non-word character, so `x_begin` is not `begin`.
+    if (WORD_START.test(char) && !WORD.test(script[index - 1] ?? ' ')) {
+      let end = index + 1;
+      while (end < script.length && WORD.test(script[end] ?? '')) end += 1;
+      const word = script.slice(index, end).toLowerCase();
+      trackBlocks(blocks, word, previous);
+      previous = word;
+      content = true;
+      index = end;
+      continue;
+    }
+    if (char === ';' && blocks.length === 0) {
       cut(index);
       start = index + 1;
       index += 1;