@ultimat3/db 10.0.0 → 11.1.0

package/CLAUDE.md

@@ -137,6 +137,16 @@ that would start attempt two answers `25P01 ROLLBACK TO SAVEPOINT can only be us
 blocks`. There is nothing to retry into, and an author who believes they hold a budget they do not
 is worse off than one who is told.
 
+**`BEGIN` re-derives its isolation level from the closed set, `As of 2026-08-23`.** `BEGIN` takes
+no parameters, so `beginStatement` is one of the two statements here built as TEXT — and the level
+was `options.isolation.toUpperCase()` spliced into it. The TYPE is not the guard: the value reaches
+`withTransaction` from an app's config, a JSON body or a CLI flag, and
+`{ isolation: 'read committed; drop table x; --' }` became exactly that statement while a
+non-string became an uncoded `TypeError` inside a template literal. `isolationMode` is a `switch`
+over `IsolationLevel` whose `default` arm is `never` — a fourth level with no SQL beside it is a
+type error, and anything else at runtime is `X_SQL_UNSAFE` (`isolationLevelInvalid`), the code
+`branchNameInvalid` already uses for a value spliced into a statement.
+
 **The migration lock is polled, never waited on.** `pg_advisory_lock` blocks with no timeout, so a
 predecessor OOM-killed on a network partition kept its backend — and the lock — for hours while the
 new `ROLE=migrate` pod sat inside one statement printing nothing: `helm upgrade --wait` blocked on a
@@ -669,7 +679,13 @@ statement_timeout` set moments earlier, so `select 1; set statement_timeout = 0`
 while `guards` went on reporting `timeout:5000ms`. `BEGIN READ ONLY` still held, so this was a
 defeated layer reported as an engaged one rather than a write — and a guard list that lies is worse
 than a guard list that is short. `statementsOf` is the package's one splitter, so a `;` inside a
-literal, a comment or a dollar-quoted body stays data.
+literal, a comment or a dollar-quoted body stays data. **And the splice takes the splitter's
+answer, `As of 2026-08-23`** — `statements[0]`, never the caller's text with a trailing `;` chopped
+off it by a regex. That second answer only saw a `;` at the very END: `select 1; -- note` is one
+statement to the splitter and does not end in `;`, so it reached the `DECLARE` whole and Postgres
+answered `cannot insert multiple commands into a prepared statement`, uncoded, out of the path
+whose whole job is bounding the read. The uncursored path still sends the caller's text
+byte-for-byte, because it splices nothing.
 
 `readonly-role.ts` and `readonly-query.ts` are layers 1–2 of that tool's defence-in-depth: a
 `NOLOGIN` Postgres role (`ensureReadOnlyRole`) and a per-statement `BEGIN READ ONLY` + statement

package/package.json

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

package/src/errors.ts

@@ -2,7 +2,13 @@
 // fixes the situation — `X_DB_DRIFT` is the flagship and its rendering is byte-for-byte
 // pinned by the framework contract, so change its strings only with the contract.
 
-import { registerErrorCodes, renderThrowable, stringField, UltimateError } from '@ultimat3/core';
+import {
+  describeValue,
+  registerErrorCodes,
+  renderThrowable,
+  stringField,
+  UltimateError,
+} from '@ultimat3/core';
 import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
 
@@ -384,6 +390,23 @@ export const branchNameInvalid = (branch: string): DbError =>
     meta: { branch },
   });
 
+/**
+ * An isolation level that is not one of the three. `X_SQL_UNSAFE` for the reason
+ * `branchNameInvalid` uses it: `BEGIN` takes no parameters, so the level is SPLICED into the
+ * statement text — `withTransaction(fn, { isolation: fromConfig })` with an operand TypeScript
+ * never saw is an injection, not a typo.
+ *
+ * `describeValue`, never the value: this cause is folded into a problem document and a log line,
+ * and an operand that arrived from a request body has no key left to redact once it is baked into
+ * a message. The three legal spellings are in the `fix:`, which is what the caller needs.
+ */
+export const isolationLevelInvalid = (received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an isolation level must be one of 'read committed', 'repeatable read' or 'serializable'; got ${describeValue(received)}`,
+    fix: "withTransaction(fn, { isolation: 'serializable' })   # or 'repeatable read', or 'read committed'",
+  });
+
 export const dbNotImplemented = (feature: string, fix: string): DbError =>
   new DbError({
     code: 'X_NOT_IMPLEMENTED',

package/src/readonly-query.ts

@@ -128,7 +128,15 @@ export async function readOnlyQuery<T>(
       guards.push(`role:${options.role}`);
     }
 
-    const rows = await readRows<T>(connection, statement, fetchCount(options.maxRows), guards);
+    // Two texts, deliberately: the caller's own, sent verbatim when nothing is spliced, and the
+    // one COMMAND `statementsOf` cut out of it, which is the only text a `DECLARE` may carry.
+    const rows = await readRows<T>(
+      connection,
+      statement,
+      statements[0] ?? statement,
+      fetchCount(options.maxRows),
+      guards,
+    );
     await connection.execute(raw('ROLLBACK'));
     return { rows, guards };
   } catch (error) {
@@ -151,16 +159,25 @@ export async function readOnlyQuery<T>(
  */
 async function readRows<T>(
   connection: DbClient,
+  /** What the caller wrote. Sent byte-for-byte on the uncursored path, which splices nothing. */
   statement: string,
+  /**
+   * The one command `statementsOf` cut out of it — what may be spliced.
+   *
+   * This was `statement.trim().replace(/;\s*$/, '')`, a second answer to "where does the command
+   * end" that only saw a `;` at the very END of the text: `select 1; -- note` is ONE statement to
+   * the splitter (a chunk of pure noise is not a statement), so it passed the one-statement gate
+   * and reached the splice whole, as `DECLARE … CURSOR FOR select 1; -- note` — two commands, and
+   * `cannot insert multiple commands into a prepared statement` out of the driver with no code
+   * and no `fix:`. The splitter is the package's one answer, and this is now its only reader.
+   */
+  command: string,
   fetch: number | undefined,
   guards: string[],
 ): Promise<readonly T[]> {
-  if (fetch === undefined || !cursorable(statement)) return connection.query<T>(raw(statement));
+  if (fetch === undefined || !cursorable(command)) return connection.query<T>(raw(statement));
 
-  // A trailing `;` would close `DECLARE` before its query and turn one statement into two. An
-  // EMBEDDED one is refused up in `readOnlyQuery`, before the transaction opens.
-  const query = statement.trim().replace(/;\s*$/, '');
-  await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${query}`));
+  await connection.execute(raw(`DECLARE ${CURSOR_NAME} NO SCROLL CURSOR FOR ${command}`));
   const rows = await connection.query<T>(raw(`FETCH FORWARD ${fetch} FROM ${CURSOR_NAME}`));
   guards.push(`fetch:${fetch} rows`);
   return rows;

package/src/transaction.ts

@@ -5,7 +5,7 @@
 
 import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
-import { serializationExhausted } from './errors';
+import { isolationLevelInvalid, serializationExhausted } from './errors';
 import { raw, type SqlFragment } from './sql';
 import { isRetryableState } from './sqlstate';
 
@@ -102,11 +102,36 @@ export function inLiveTx(): boolean {
   return storage.get()?.live.value === true;
 }
 
+/**
+ * The SQL for one isolation level, RE-DERIVED from the closed set rather than built out of the
+ * value — the same rule `pg-sql.ts` follows for `asc|desc`, and for the same reason: `BEGIN` takes
+ * no parameters, so this is one of the two statements here built as text, and a level spliced into
+ * it is whatever the caller passed. `isolation` is typed, and a type is not a runtime guard: the
+ * value reaches `withTransaction` from an app's config, a JSON body or a CLI flag —
+ * `{ isolation: 'read committed; drop table x; --' }` became exactly that statement, and a
+ * non-string became an uncoded `TypeError` inside a template literal.
+ *
+ * The `default` arm is `never`, so a fourth member added to `IsolationLevel` with no SQL beside it
+ * is a type error here rather than a refusal at runtime.
+ */
+const isolationMode = (declared: IsolationLevel): string => {
+  switch (declared) {
+    case 'read committed':
+      return 'ISOLATION LEVEL READ COMMITTED';
+    case 'repeatable read':
+      return 'ISOLATION LEVEL REPEATABLE READ';
+    case 'serializable':
+      return 'ISOLATION LEVEL SERIALIZABLE';
+    default: {
+      const unhandled: never = declared;
+      throw isolationLevelInvalid(unhandled);
+    }
+  }
+};
+
 export function beginStatement(options: TransactionOptions): string {
   const modes: string[] = [];
-  if (options.isolation !== undefined) {
-    modes.push(`ISOLATION LEVEL ${options.isolation.toUpperCase()}`);
-  }
+  if (options.isolation !== undefined) modes.push(isolationMode(options.isolation));
   if (options.readOnly === true) modes.push('READ ONLY');
   if (options.deferrable === true) modes.push('DEFERRABLE');
   return modes.length === 0 ? 'BEGIN' : `BEGIN ${modes.join(' ')}`;