@ultimat3/db 23.0.0 → 25.0.0

package/src/pglite.ts

@@ -4,7 +4,9 @@
 // that only ever talks to a managed Postgres must not carry 26 MB of WASM it will never load.
 
 import { statementAttribution } from './attribution';
+import { refuseUnsendable } from './bound-parameters';
 import type { DbClient, DbConnection, ReservableClient } from './client';
+import { refuseRolledBackCommit } from './commit-tag';
 import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import {
@@ -36,6 +38,8 @@ export interface PgliteResult {
   readonly rows: readonly unknown[];
   /** Postgres' command-tag count — the only truthful answer for INSERT/UPDATE/DELETE. */
   readonly affectedRows?: number | undefined;
+  /** The command tag's verb. `ROLLBACK` in answer to a `COMMIT` is how an aborted one reads. */
+  readonly command?: string | undefined;
 }
 
 /** The slice of PGlite we need. Declared structurally — this package has no dependencies. */
@@ -171,7 +175,7 @@ async function restore(
   }
 }
 
-/** Boots one embedded Postgres. Costs seconds — `createPgliteClient` calls it exactly once. */
+/** Boots one embedded Postgres. Costs seconds — `pgliteClient` calls it exactly once. */
 export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<PgliteDriver> {
   if (options.driver !== undefined) return options.driver;
   const dataDir = options.dataDir ?? PGLITE_MEMORY;
@@ -245,8 +249,8 @@ function rowsOf(result: PgliteResult): number {
     : result.rows.length;
 }
 
-/** Lazily boots: constructing a client opens nothing, exactly like `createPostgresClient`. */
-export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
+/** Lazily boots: constructing a client opens nothing, exactly like `postgresClient`. */
+export function pgliteClient(options: PgliteOptions = {}): PgliteClient {
   // One in-flight boot, shared. PGlite takes seconds to start, so two concurrent first queries
   // would otherwise build two instances over the same data directory and orphan one of them.
   let booting: Promise<PgliteDriver> | undefined;
@@ -266,8 +270,12 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
 
   /** The send itself: one statement on the session, every driver failure typed on the way out. */
   async function send(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
+    // Above the `try`, as `sendOn` encodes above its own: a value this package refuses to send is
+    // not a driver failure.
+    refuseUnsendable(fragment.values);
+    let result: PgliteResult;
     try {
-      return await driver.query(fragment.text, fragment.values);
+      result = await driver.query(fragment.text, fragment.values);
     } catch (error) {
       // `driverError`, as `statement-funnel.ts` already does for Bun's driver: this site passed
       // every failure to `dbUnavailable`, so under `x dev` — which IS this driver when no
@@ -276,6 +284,10 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
       // answering fine (measured 2026-09-05). PGlite carries the SQLSTATE on `code`.
       throw driverError(statementExcerpt(fragment.text), error);
     }
+    // Outside the `try`, as `sendOn` does it: a COMMIT the server answered with ROLLBACK is a
+    // refusal of its own, and `driverError` would re-wrap it as unavailability.
+    refuseRolledBackCommit(fragment.text, result);
+    return result;
   }
 
   /**

package/src/pool-profile.ts

@@ -137,7 +137,7 @@ export function assertPoolProfile(profile: PoolProfile): PoolProfile {
     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`,
+      `pass a whole number for ${option} in postgresClient({ 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);

package/src/primary-key.ts

@@ -0,0 +1,210 @@
+// Single responsibility: a table's PRIMARY KEY as DDL — the two statements that move one, the
+// generator's arm that decides when they are due, and the refusal for a key another table still
+// points at. `diffTable` had no arm for it, so a changed `primaryKey` wrote no statement while the
+// snapshot beside it recorded the new key, and drift had no comparison to notice with.
+
+import { assert, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
+import { defaultExpression } from './column-default';
+import type { EntityDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { isGenerated } from './generated-column';
+import type { SchemaDescription, TableDescription } from './introspect';
+import { MAX_IDENTIFIER_BYTES } from './invariant-ddl';
+import { migrationIrreversible } from './migration-errors';
+import { identifier } from './sql';
+
+/**
+ * Inside shell double quotes a `$`, a backtick and a `!` still run; everything else — a quote, a
+ * `;`, a space — is inert once `JSON.stringify` has escaped `"` and `\\`.
+ */
+const DOUBLE_QUOTE_LIVE = /[$`!]/;
+
+/**
+ * A control character — C0, DEL, C1. `JSON.stringify` writes one as an escape (`\\n`), and inside
+ * shell double quotes that escape is passed on LITERALLY, so the pasted line would name a different
+ * migration than the one refused. The placeholder is honest; an escape is not.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/**
+ * A migration NAME as the one argument of `x db gen "…"`, for a `fix:` a reader pastes. It is a
+ * description (`add posts`), never an identifier, so it keeps its spaces; a name carrying shell
+ * syntax becomes the placeholder rather than a second command (plan 101 row S12). Lives here, the
+ * lowest of the three files echoing one, so `generate.ts` and `migrate.ts` share one rule.
+ */
+export const migrationNameArg = (name: string): string =>
+  renderFixLiteral(
+    // A leading `-` reads as a flag to `x db gen` however it is quoted (sweep 1c audit, L3).
+    DOUBLE_QUOTE_LIVE.test(name) || CONTROL.test(name) || name.startsWith('-') ? undefined : name,
+    '"<a migration name>"',
+  );
+
+/**
+ * `<table>_pkey` — what Postgres names the constraint an inline `primary key (…)` creates, which is
+ * how `createTable` has always written one. Written out by name on every `add` here, so the name a
+ * later migration drops is one a migration chose.
+ *
+ * Bounded in bytes: past 63 the server truncates the TABLE part to make room for `_pkey`, so the
+ * name it holds is no longer this string and a `drop constraint` built from it would miss.
+ */
+export function primaryKeyName(table: string): string {
+  const name = `${table}_pkey`;
+  const bytes = new TextEncoder().encode(name).length;
+  assert(
+    bytes <= MAX_IDENTIFIER_BYTES,
+    `primary key constraint "${name}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES}, so the name the database holds is not this one`,
+    // By `relname`, not `'<table>'::regclass`: a regclass literal re-parses the name as SQL, so a
+    // mixed-case table needs inner double quotes — which end the shell string. A name that is not
+    // one plain shell word is also not a safe SQL literal, so it is the placeholder (plan 101 S12).
+    `psql "$DATABASE_URL" -c "select con.conname from pg_constraint con join pg_class rel on rel.oid = con.conrelid where con.contype = 'p' and rel.relname = '${renderFixShellArg(table, '<table>')}'"   # then write the drop constraint / add primary key pair by hand in a new migration`,
+  );
+  return name;
+}
+
+export function addPrimaryKey(table: string, columns: readonly string[]): string {
+  const key = columns.map((column) => identifier(column).text).join(', ');
+  return (
+    `alter table ${identifier(table).text} add constraint ` +
+    `${identifier(primaryKeyName(table)).text} primary key (${key});`
+  );
+}
+
+/**
+ * `if exists` for the generator, and for a reason the server supplies: dropping a COLUMN drops
+ * every constraint written over it, so a key whose column this same migration removes — in either
+ * direction — may already be gone by the time this statement runs.
+ */
+export function dropPrimaryKey(table: string, constraint: string, ifExists: boolean): string {
+  return (
+    `alter table ${identifier(table).text} drop constraint ` +
+    `${ifExists ? 'if exists ' : ''}${identifier(constraint).text};`
+  );
+}
+
+/**
+ * Postgres marks every key column NOT NULL and dropping the key does not undo it (measured on 17),
+ * so a column the declaration allows NULL in needs the constraint taken off by name.
+ */
+const dropNotNull = (table: string, column: string): string =>
+  `alter table ${identifier(table).text} alter column ${identifier(column).text} drop not null;`;
+
+/**
+ * No default, or the default `null` — `.default(null)` renders that expression, and it fills an
+ * added column with exactly what no default does.
+ */
+const fillsNothing = (expression: string | null): boolean =>
+  expression === null || expression === 'null';
+
+/** Two column lists, equal in ORDER — the one copy; `drift.ts` compares the live key through it. */
+export const sameColumns = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((column, index) => column === b[index]);
+
+/** ORDER is part of a key: `(org_id, id)` and `(id, org_id)` are two different indexes. */
+export function keyChanged(entity: EntityDescriptionLike, live: TableDescription): boolean {
+  return !sameColumns(entity.primaryKey, live.primaryKey);
+}
+
+/**
+ * The recorded foreign keys written against the key being replaced. Postgres refuses to drop a
+ * constraint another one depends on (`2BP01`), and re-pointing someone else's key is not a diff
+ * this generator can derive: the referencing table's own columns would have to change with it.
+ */
+function inboundKeys(current: SchemaDescription, live: TableDescription): readonly string[] {
+  const key = new Set(live.primaryKey);
+  return current.tables.flatMap((table) =>
+    table.foreignKeys
+      .filter(
+        (foreign) =>
+          foreign.referencedTable === live.name &&
+          foreign.referencedColumns.length === key.size &&
+          foreign.referencedColumns.every((column) => key.has(column)),
+      )
+      .map((foreign) => foreign.name),
+  );
+}
+
+/**
+ * The first half, ahead of every column statement of the table: the old key goes. `down` is
+ * reversed at assembly, so the statement pushed here runs LAST on the way back — the old key is
+ * restored only once every column it names is back.
+ */
+export function dropChangedKey(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  current: SchemaDescription,
+  plan: Plan,
+  migration: string,
+): void {
+  if (!keyChanged(entity, live) || live.primaryKey.length === 0) return;
+  const inbound = inboundKeys(current, live);
+  if (inbound.length > 0) {
+    throw migrationIrreversible(
+      `changing the primary key of "${entity.table}" drops the constraint ${inbound.map((name) => `"${name}"`).join(', ')} ${inbound.length === 1 ? 'is' : 'are'} written against, and re-pointing another table's foreign key is not a change this generator can derive`,
+      `x db gen ${migrationNameArg(migration)}   # after removing the references() to "${entity.table}" behind ${inbound.join(', ')} — drop the keys in one migration, change the primary key in the next, restore them in a third`,
+    );
+  }
+  plan.up.push(dropPrimaryKey(entity.table, primaryKeyName(entity.table), true));
+  const declared = new Map(entity.columns.map((column) => [column.column, column]));
+  const kept = new Set(entity.primaryKey);
+  for (const name of live.primaryKey) {
+    // Leaving the key, still on the table, and declared nullable: the key's NOT NULL goes with it.
+    if (!kept.has(name) && declared.get(name)?.notNull === false) {
+      plan.up.push(dropNotNull(entity.table, name));
+    }
+  }
+  // A key column this migration DROPS comes back empty on the way down (`-- data is not
+  // restored`), and a primary key over NULLs cannot be added to a table holding a row. The
+  // statement is named as the follow-up rather than emitted as one that cannot apply — the form
+  // `diffTable` already uses for a NOT NULL add.
+  const restored = live.primaryKey.filter((name) => !declared.has(name));
+  const restore = addPrimaryKey(entity.table, live.primaryKey);
+  plan.down.push(
+    restored.length === 0
+      ? restore
+      : `-- backfill ${restored.map((name) => identifier(name).text).join(', ')}, then: ${restore}`,
+  );
+}
+
+/**
+ * The second half, after the table's last column statement — the `drop column`s included: every
+ * column the new key names exists by now, and none it no longer names is still in the way.
+ *
+ * Refused when the key names a column this same migration ADDS with nothing to fill it (no
+ * default, or the default `null`): `add
+ * column` lands NULL in every existing row and a primary key refuses a NULL, so the generated `up`
+ * could not apply to any table holding a row. A default or a generation expression fills it.
+ */
+export function addChangedKey(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  migration: string,
+): void {
+  if (!keyChanged(entity, live) || entity.primaryKey.length === 0) return;
+  const recorded = new Map(live.columns.map((column) => [column.name, column]));
+  const empty = entity.columns.filter(
+    (column) =>
+      entity.primaryKey.includes(column.column) &&
+      !recorded.has(column.column) &&
+      !isGenerated(column) &&
+      fillsNothing(defaultExpression(column)),
+  );
+  if (empty.length > 0) {
+    const names = empty.map((column) => `"${column.column}"`).join(', ');
+    throw migrationIrreversible(
+      `the new primary key of "${entity.table}" names ${names}, which this same migration adds with no default that fills it: every existing row would hold NULL there, and a primary key cannot be added over a NULL`,
+      `x db gen ${migrationNameArg(migration)}   # with ${names} declared but left OUT of primaryKey — apply it, backfill the column, then put it in the key and run x db gen again`,
+    );
+  }
+  plan.up.push(addPrimaryKey(entity.table, entity.primaryKey));
+  const old = new Set(live.primaryKey);
+  for (const name of entity.primaryKey) {
+    // Pushed BEFORE the drop so it runs AFTER it on the way down: a column that was nullable
+    // before this migration keyed it is nullable again once the key is gone.
+    if (!old.has(name) && recorded.get(name)?.nullable === true) {
+      plan.down.push(dropNotNull(entity.table, name));
+    }
+  }
+  plan.down.push(dropPrimaryKey(entity.table, primaryKeyName(entity.table), true));
+}

package/src/schema-dump-table.ts

@@ -34,7 +34,10 @@ function columnClause(column: CatalogColumn): string {
   const parts = [quoted(column.name), column.type];
   if (column.collation !== null) parts.push(`collate ${quoted(column.collation)}`);
   if (column.default !== null) parts.push(`default ${column.default}`);
-  if (column.generated !== null) parts.push(`generated always as (${column.generated}) stored`);
+  if (column.generated !== null) {
+    const { expression, storage } = column.generated;
+    parts.push(`generated always as (${expression}) ${storage}`);
+  }
   if (column.identity !== null) {
     const { mode, sequence } = column.identity;
     parts.push(

package/src/sibling-turn.ts

@@ -0,0 +1,49 @@
+// Single responsibility: a nested scope's wait for its turn among its siblings, under a deadline.
+// Sibling scopes run one after the other (savepoints are a stack), so a body that awaits a sibling
+// queued BEHIND it is a cycle nothing can break from inside — and an unbounded wait made it a
+// silent, permanent hang. Same shape as `pool-reserve.ts`: a late turn is given back, never dropped.
+
+import type { DbError } from './errors';
+import type { Turn, TurnQueue } from './pglite-turns';
+
+/**
+ * The default wait, in milliseconds. Above the serving roles' `statement_timeout` (10–15 s,
+ * `pool-profile.ts`), so a sibling that is merely inside one slow statement finishes or fails
+ * first; `{ siblingWaitMs }` moves it and `0` removes it.
+ */
+export const SIBLING_SCOPE_WAIT_MS = 30_000;
+
+/**
+ * `queue.take()` under a deadline. The place in the queue is claimed the moment `take()` is called
+ * and cannot be withdrawn, so a wait that gives up must still hand the turn straight on when it
+ * arrives — otherwise every later sibling waits behind a scope that no longer exists.
+ */
+export async function siblingTurn(
+  queue: TurnQueue,
+  waitMs: number,
+  refusal: () => DbError,
+): Promise<Turn> {
+  const pending = queue.take();
+  if (waitMs === 0) return pending;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let expired = false;
+  try {
+    return await Promise.race([
+      pending,
+      new Promise<never>((_resolve, reject) => {
+        timer = setTimeout(() => {
+          expired = true;
+          // Built at expiry, so it names the scope holding the turn NOW.
+          reject(refusal());
+        }, waitMs);
+        // The deadline must not be what keeps a finished process alive.
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    void pending.then((late) => {
+      if (expired) late.release();
+    });
+  }
+}

package/src/snapshot-parse.ts

@@ -118,14 +118,20 @@ function tableOf(value: unknown): TableDescription | undefined {
   // wrong. Any other value is garbage and takes the file with it, like every field above.
   const identity = value['replicaIdentityFull'];
   if (!(identity === undefined || bool(identity))) return undefined;
-  const replica = identity === true ? { replicaIdentityFull: true as const } : {};
+  // `appendOnly` by the same rule: `true` or nothing, `false` normalised away.
+  const appendOnly = value['appendOnly'];
+  if (!(appendOnly === undefined || bool(appendOnly))) return undefined;
+  const flags = {
+    ...(identity === true ? { replicaIdentityFull: true as const } : {}),
+    ...(appendOnly === true ? { appendOnly: true as const } : {}),
+  };
   const raw = value['checks'];
   if (raw === undefined) {
-    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...replica };
+    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...flags };
   }
   const checks = all(raw, check);
   if (checks === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...replica };
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...flags };
 }
 
 /**

package/src/sqlstate.ts

@@ -31,12 +31,6 @@ export const SQLSTATE = Object.freeze({
   outOfMemory: '53200',
 } as const);
 
-/** Five characters, digits and uppercase letters — `42P01`, never `ERR_POSTGRES_SERVER_ERROR`. */
-const SQLSTATE_SHAPE = /^[0-9A-Z]{5}$/;
-
-/** How deep a wrap may nest before we stop looking. `DbError` adds exactly one level. */
-const MAX_WRAPS = 4;
-
 /** A field off a value that may fight being read — `stringField`'s shape, for a non-string. */
 function unknownField(value: unknown, key: string): unknown {
   if (typeof value !== 'object' || value === null) return undefined;
@@ -47,6 +41,32 @@ function unknownField(value: unknown, key: string): unknown {
   }
 }
 
+/** Five characters, digits and uppercase letters — `42P01`, never `ERR_POSTGRES_SERVER_ERROR`. */
+const SQLSTATE_SHAPE = /^[0-9A-Z]{5}$/;
+
+/**
+ * Whether five characters of that shape are a SQLSTATE, decided by where the object CAME FROM —
+ * the shape alone cannot say. `EPIPE` and `E2BIG` are errno names of exactly that shape, and
+ * `raise exception … using errcode = 'ABCDE'` is a legal state with no digit in it, so a rule
+ * about letters and digits is wrong in both directions.
+ *
+ * Measured on Bun.SQL against Postgres 17 and on PGlite: a server ErrorResponse carries
+ * `severity` on both drivers, and nothing the socket layer throws does. A syscall error carries
+ * `syscall` and a NUMERIC `errno`. An object marked as neither — a fake, a wrapper, a driver this
+ * package has not measured — keeps the old reading only for a state that carries a digit, which
+ * is every state Postgres itself defines and no bare errno name this package has been handed.
+ */
+function isState(holder: unknown, candidate: string): boolean {
+  if (!SQLSTATE_SHAPE.test(candidate)) return false;
+  if (stringField(holder, 'severity') !== undefined) return true;
+  if (stringField(holder, 'syscall') !== undefined) return false;
+  if (typeof unknownField(holder, 'errno') === 'number') return false;
+  return /[0-9]/.test(candidate);
+}
+
+/** How deep a wrap may nest before we stop looking. `DbError` adds exactly one level. */
+const MAX_WRAPS = 4;
+
 /**
  * The SQLSTATE a driver error carries, unwrapping `DbError.sourceError` on the way, or `undefined`
  * when the failure never reached the server — a refused socket, a closed pool, a DNS miss.
@@ -57,17 +77,17 @@ function unknownField(value: unknown, key: string): unknown {
  * has no `errno` at all. Reading `code` alone is correct on the embedded driver and wrong on every
  * production one, which is exactly the split `isLedgerMissing` was living on.
  *
- * The shape test is what keeps the two apart: `ERR_POSTGRES_SERVER_ERROR` and `X_DB_UNAVAILABLE`
- * are not five characters of `[0-9A-Z]`, and no SQLSTATE contains an underscore.
+ * The shape test keeps `ERR_POSTGRES_SERVER_ERROR` and `X_DB_UNAVAILABLE` out — neither is five
+ * characters of `[0-9A-Z]` — and `isState` keeps an errno NAME out, which the shape cannot.
  */
 export function sqlState(error: unknown): string | undefined {
   let value = error;
   for (let depth = 0; depth < MAX_WRAPS; depth += 1) {
     if (value === undefined || value === null) return undefined;
     const errno = stringField(value, 'errno');
-    if (errno !== undefined && SQLSTATE_SHAPE.test(errno)) return errno;
+    if (errno !== undefined && isState(value, errno)) return errno;
     const code = stringField(value, 'code');
-    if (code !== undefined && SQLSTATE_SHAPE.test(code)) return code;
+    if (code !== undefined && isState(value, code)) return code;
     value = unknownField(value, 'sourceError');
   }
   return undefined;

package/src/statement-funnel.ts

@@ -6,6 +6,7 @@
 import { statementAttribution } from './attribution';
 import { encodeBoundParameters } from './bound-parameters';
 import type { BunSqlDriver } from './bun-sql';
+import { refuseRolledBackCommit } from './commit-tag';
 import { driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
@@ -32,12 +33,18 @@ async function sendOn(
   driver: Pick<BunSqlDriver, 'unsafe'>,
   fragment: SqlFragment,
 ): Promise<unknown> {
+  // `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.
+  //
+  // ABOVE the `try`: its refusals are this package's own and already coded. Inside it, a ragged
+  // array or an Invalid Date came back as `X_DB_UNAVAILABLE` — "set DATABASE_URL" — from a driver
+  // that was never called.
+  const values = encodeBoundParameters(fragment.values);
+  let result: unknown;
   try {
-    // `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));
+    result = await driver.unsafe(fragment.text, 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
@@ -45,6 +52,10 @@ async function sendOn(
     // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
     throw driverError(statementExcerpt(fragment.text), error);
   }
+  // Outside the `try`: this refusal is already typed, and `driverError` would re-wrap it as a
+  // database nobody could reach.
+  refuseRolledBackCommit(fragment.text, result);
+  return result;
 }
 
 /**

package/src/transaction-errors.ts

@@ -0,0 +1,66 @@
+// Single responsibility: the two refusals a transaction's END can raise — the server rolled it back
+// while the body carried on, and the answer to COMMIT never arrived. Split from `errors.ts` at the
+// file-size rule; both are thrown by `transaction.ts`, the first by the two statement funnels too.
+
+import { renderThrowable } from '@ultimat3/core';
+import { DbError } from './errors';
+import { sqlState } from './sqlstate';
+
+const ABORTED_FIX =
+  'await withTransaction(() => fallible()).catch(fallback)   # a nested scope is a SAVEPOINT, so ' +
+  'only it rolls back — or rethrow the statement error instead of catching it';
+
+/**
+ * Postgres aborts the WHOLE transaction on any statement error and answers the `COMMIT` that
+ * follows with the tag `ROLLBACK` and no error, so a body that caught the failure and returned was
+ * reported committed with nothing stored. `first` is the statement the body threw away — rendered
+ * into the cause, deliberately NOT chained as `sourceError`: `sqlState()` unwraps that chain, and a
+ * caller asking "was this a unique violation" would be answered yes by an error that means the
+ * whole unit of work is gone.
+ */
+export const transactionAborted = (first?: unknown): DbError => {
+  const state = sqlState(first);
+  return new DbError({
+    code: 'X_DB_TRANSACTION_ABORTED',
+    cause:
+      first === undefined
+        ? 'COMMIT was answered with ROLLBACK: a statement failed earlier in this transaction, its error was caught, and the server had already rolled the whole unit of work back'
+        : `a statement failed inside the transaction and the error was caught rather than rethrown, so the server rolled the whole unit of work back: ${renderThrowable(first)}`,
+    fix: ABORTED_FIX,
+    ...(state === undefined ? {} : { meta: { sqlState: state } }),
+  });
+};
+
+/**
+ * A nested scope gave up waiting for the sibling holding the turn. Names both: the scope that
+ * waited is identified by its parent (it never opened, so it has no savepoint of its own), and the
+ * holder by the savepoint it is inside. Terminal: the usual cause is a body awaiting a sibling
+ * queued behind it, and the same call made again waits for the same cycle.
+ */
+export const siblingScopeTimeout = (
+  parent: string,
+  holder: string | undefined,
+  waitedMs: number,
+): DbError =>
+  new DbError({
+    code: 'X_DB_SIBLING_SCOPE_TIMEOUT',
+    cause: `a nested scope under ${parent} waited ${waitedMs}ms for its sibling ${holder ?? 'scope'} to finish and never got a turn — sibling scopes run one after the other, so a body that awaits a sibling started after it waits for itself`,
+    fix: 'await withTransaction(first); await withTransaction(second)   # one after the other, never a nested body awaiting a sibling — or raise the wait: withTransaction(fn, { siblingWaitMs: 120000 })',
+    meta: { parent, waitedMs, ...(holder === undefined ? {} : { holder }) },
+  });
+
+/**
+ * `COMMIT` was sent and rejected with no SQLSTATE — the socket went before the answer did. The
+ * transaction is durable or it is not, and nothing on this side can say which, so neither list
+ * runs: an `onRollback` undo would revert state the database may have kept, and an `onCommit`
+ * effect would announce rows it may not have.
+ */
+export const commitUnknown = (sourceError: unknown): DbError =>
+  new DbError({
+    code: 'X_DB_COMMIT_UNKNOWN',
+    cause: `the connection failed while COMMIT was in flight, so the transaction is either durable or rolled back and this process cannot tell which; neither onCommit effects nor onRollback undos ran. Only the data can say which — a row the transaction wrote is present if it committed and absent if it did not: ${renderThrowable(sourceError)}`,
+    // A session, never a `-c "<placeholder>"`: which row proves it is the caller's knowledge, and
+    // a placeholder inside a command is a command that does not run.
+    fix: 'psql "$DATABASE_URL"   # a session on that database: select a row the transaction wrote, and re-run the unit of work only when it is absent',
+    sourceError,
+  });