@ultimat3/db 23.0.0 → 24.0.0

package/src/introspect.ts

@@ -27,7 +27,11 @@ export interface ColumnDescription {
 
 export interface IndexDescription {
   readonly name: string;
-  /** Physical columns in **index key order** — the order the planner sorts by, never `attnum`. */
+  /**
+   * Key columns in **index key order** — the order the planner sorts by, never `attnum`. An
+   * EXPRESSION key read from the catalog is its definition in parentheses (`(lower(title))`), in
+   * its own position: marked, so it can never be taken for a column, and never dropped.
+   */
   readonly columns: readonly string[];
   readonly unique: boolean;
   readonly primary: boolean;
@@ -188,17 +192,45 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     ...(await nonAppRelations(client, schema)),
   ];
 
+  // The type is `format_type`, as `catalog-relations.ts` reads it: `information_schema.data_type`
+  // answers `numeric` for `numeric(12,2)`, `ARRAY` for `text[]` and `USER-DEFINED` for an enum, and
+  // `ColumnDescription.dataType` has always been documented as the first of each pair. Still FROM
+  // the view, which decides which columns this role may see.
   const columns = await client.query<ColumnRow>(sql`
-    select table_name, column_name, data_type, is_nullable, column_default, ordinal_position
-    from information_schema.columns
-    where table_schema = ${schema}
-    order by table_name, ordinal_position
+    select
+      c.table_name,
+      c.column_name,
+      coalesce(
+        (
+          select format_type(a.atttypid, a.atttypmod)
+          from pg_attribute a
+          join pg_class r on r.oid = a.attrelid
+          join pg_namespace n on n.oid = r.relnamespace
+          where n.nspname = c.table_schema
+            and r.relname = c.table_name
+            and a.attname = c.column_name
+            and a.attnum > 0
+            and not a.attisdropped
+        ),
+        c.data_type
+      ) as data_type,
+      c.is_nullable,
+      c.column_default,
+      c.ordinal_position
+    from information_schema.columns c
+    where c.table_schema = ${schema}
+    order by c.table_name, c.ordinal_position
   `);
 
   // Ordered by the index's own key position, never by `attnum`: `indkey` IS the order the planner
   // sorts by, and a composite index on `(created_at, org_id)` whose columns were declared the
   // other way round came back reversed — a description that reads correct and compares wrong.
   // `indnkeyatts` drops INCLUDE payload columns, which are stored, not keyed.
+  //
+  // A LEFT join on `pg_attribute`: an expression key has `attnum = 0` and no attribute row, so an
+  // inner join dropped it and `(id, lower(title))` read back as `(id)` — an index rebuilt by hand
+  // with an extra expression key compared equal to the declared one. It is kept in its position
+  // and MARKED by its parentheses, which no declared column name carries.
   const indexes = await client.query<IndexRow>(sql`
     select
       t.relname as table_name,
@@ -207,7 +239,10 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
       ix.indisprimary as is_primary,
       pg_get_expr(ix.indpred, ix.indrelid) as predicate,
       am.amname as method,
-      array_agg(a.attname order by k.ord) as columns,
+      array_agg(
+        coalesce(a.attname::text, '(' || pg_get_indexdef(ix.indexrelid, k.ord::int, false) || ')')
+        order by k.ord
+      ) as columns,
       bool_and((ix.indoption[k.ord - 1] & 1) = 1) as descending
     from pg_class t
     join pg_namespace n on n.oid = t.relnamespace
@@ -215,9 +250,11 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     join pg_class i on i.oid = ix.indexrelid
     join pg_am am on am.oid = i.relam
     cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
-    join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum
+    left join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum and k.attnum > 0
     where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
-    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid, am.amname
+    group by
+      t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid,
+      ix.indexrelid, am.amname
     order by t.relname, i.relname
   `);
 

package/src/migrate.ts

@@ -13,7 +13,7 @@ import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
-import { type DbTx, withTransaction } from './transaction';
+import { withTransaction } from './transaction';
 
 export const LEDGER_TABLE = 'x_migrations';
 
@@ -312,7 +312,7 @@ async function withAdvisoryLock<T>(
  * migration loop, and nesting here would replace that reason with a narrower one for no gain. An
  * empty script sends nothing at all, which is how a no-op migration reaches its ledger row.
  */
-async function applyScript(tx: DbTx, script: string): Promise<void> {
+async function applyScript(tx: DbClient, script: string): Promise<void> {
   for (const statement of statementsOf(script)) await tx.execute(raw(statement));
 }
 
@@ -331,7 +331,7 @@ async function applyScript(tx: DbTx, script: string): Promise<void> {
  * it, exactly like `statementTimeoutMs`. The failure it produces is `55P03`, typed as
  * `X_DB_LOCK_TIMEOUT` by `driverError` with the `pg_stat_activity` read as its fix.
  */
-async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
+async function setLockTimeout(tx: DbClient, lockTimeoutMs: number): Promise<void> {
   if (lockTimeoutMs <= 0) return;
   // `SET LOCAL` takes no parameter placeholder, and the value is a validated integer of ours.
   await tx.execute(raw(`SET LOCAL lock_timeout = ${Math.round(lockTimeoutMs)}`));

package/src/object-drift.ts

@@ -4,12 +4,18 @@
 // so everything else is compared here, catalog against catalog, by identity and never by text.
 
 import type { CatalogDescription } from './catalog';
+import { psqlCommand } from './dependent-view';
 import { FRAMEWORK_TABLE_PREFIX } from './drift';
-import type { DriftDifference } from './drift-findings';
-import { shellInertIdentifier } from './sql';
+import { byHand, type DriftDifference } from './drift-findings';
+import { literal, shellInertIdentifier } from './sql';
 
 interface ObjectIdentity {
-  /** The word `drop` takes: `trigger`, `function`, `view`, `materialized view`, `type`, `sequence`. */
+  /** The schema the catalog was read from — a new psql session's search_path need not hold it. */
+  readonly schema: string;
+  /**
+   * The word `drop` takes: `trigger`, `function`, `view`, `materialized view`, `type`, `domain`,
+   * `sequence`. A domain keeps its own word: it is inspected by a different psql command.
+   */
   readonly kind: string;
   readonly name: string;
   /** What tells two objects of one name apart: a function's arguments. */
@@ -27,13 +33,14 @@ interface ObjectIdentity {
  */
 function identities(catalog: CatalogDescription): readonly ObjectIdentity[] {
   const plain = (kind: string, name: string): ObjectIdentity => ({
+    schema: catalog.schema,
     kind,
     name,
     signature: '',
     table: null,
   });
   return [
-    ...catalog.types.map((type) => plain('type', type.name)),
+    ...catalog.types.map((type) => plain(type.kind === 'domain' ? 'domain' : 'type', type.name)),
     ...catalog.sequences.map((sequence) => plain('sequence', sequence.name)),
     ...catalog.views.map((view) =>
       plain(view.materialized ? 'materialized view' : 'view', view.name),
@@ -53,38 +60,88 @@ const SIGNATURE_ACTIVE = /[`$\\\u0000-\u001f\u007f]/;
 const keyOf = (object: ObjectIdentity): string =>
   [object.kind, object.table ?? '', object.name, object.signature].join('\u0000');
 
+/** The psql command that PRINTS a kind's definition — what a migration's create statement is copied from. */
+const SHOW = Object.freeze<Record<string, string>>({
+  view: '\\d+',
+  'materialized view': '\\d+',
+  type: '\\dT+',
+  // `\dT+` LISTS a domain and shows none of it; its base type and CHECKs are `\dD+`'s (measured, 17).
+  domain: '\\dD+',
+  sequence: '\\d',
+  // A trigger has no command of its own: `\d` on its table lists it, definition included.
+  trigger: '\\d',
+});
+
+/**
+ * A function's definition, asked for by the three facts the catalog gave: its schema, its name and
+ * its identity arguments. Not `\\sf name(args)`: that parses a TYPE list, and the identity arguments
+ * carry the parameter NAMES (`a text`), which it answers with a syntax error — measured on 17. By
+ * NAMESPACE and never `pg_function_is_visible`: visibility is the session's search_path, which can
+ * hide this function or answer a same-named one from another schema. All three are data, so all
+ * three go through `literal()`.
+ */
+const showFunction = (object: ObjectIdentity): string =>
+  'select pg_get_functiondef(p.oid) from pg_proc p join pg_namespace n on n.oid = ' +
+  `p.pronamespace where n.nspname = ${literal(object.schema).text} and ` +
+  `p.proname = ${literal(object.name).text} and ` +
+  `pg_get_function_identity_arguments(p.oid) = ${literal(object.signature).text}`;
+
 /**
- * The `drop` comes FIRST in the fix, and that order is the instruction: a migration that creates
- * an object the database already holds fails on `already exists`, so the hand-made copy has to go
- * before the migration that owns it can apply.
+ * The fix is ONE command a shell runs, and it is the harmless one: it prints the object's
+ * definition. The repair is the comment, in the order it has to happen — copy the definition into
+ * a migration, drop the hand-made copy (a migration creating an object the database already holds
+ * fails on `already exists`), then migrate. It used to lead with `run drop …; inside psql`: prose
+ * no shell runs, whose first step destroyed the definition the second step needed.
  */
 function unexpectedObject(object: ObjectIdentity): DriftDifference {
+  const schema = shellInertIdentifier(object.schema);
   const name = shellInertIdentifier(object.name);
   const table = object.table === null ? null : shellInertIdentifier(object.table);
   const where = object.table === null ? '' : ` on table "${object.table}"`;
   const signature = object.signature === '' ? '' : `(${object.signature})`;
-  // A function is dropped by its argument list, empty included: `drop function "add";` is
+  // A function is named by its argument list, empty included: `drop function "add";` is
   // `42725 function name is not unique` while an overload lives beside it. The list is catalog
   // text (`pg_get_function_identity_arguments`), already quoted for SQL, so it is screened for
   // what a shell or a pasted line would read and never escaped.
   const args = object.kind === 'function' ? `(${object.signature})` : '';
   const spellable =
+    schema !== null &&
     name !== null &&
     (object.table === null || table !== null) &&
     !SIGNATURE_ACTIVE.test(object.signature);
-  const drop = `drop ${object.kind} ${name}${args}${table === null ? '' : ` on ${table}`};`;
+  const cause = `${object.kind} "${object.name}"${signature}${where} exists in this database and no migration creates it`;
+  const kind = 'unexpected-object';
+  const base = { kind, table: object.table ?? object.name, column: null, cause } as const;
+  if (!spellable) {
+    return {
+      ...base,
+      fix: byHand(
+        'copy the definition of the object this difference names into a migration as a create ' +
+          'statement, then drop it',
+        'its schema, name or arguments carry a backtick, a dollar sign, a quote, a backslash or ' +
+          'whitespace, so no statement here can spell it',
+      ),
+    };
+  }
+  // Every target is qualified by the catalog's schema: unqualified, `\d "posts"` in a session
+  // whose search_path lacks that schema answers "Did not find any relation" — and exits 0.
+  const drop =
+    table === null
+      ? `drop ${object.kind} ${schema}.${name}${args};`
+      : `drop ${object.kind} ${name} on ${schema}.${table};`;
+  // The comment repeats the statement only when it holds no `'`: a shell that does not read `#`
+  // as a comment would open a quote on one. The command is safe either way (`psqlCommand`).
+  const spoken = drop.includes("'") ? `drop ${object.kind} on it` : drop;
+  const show = psqlCommand(
+    object.kind === 'function'
+      ? showFunction(object)
+      : `${SHOW[object.kind] ?? '\\d'} ${schema}.${table ?? name}`,
+  );
   return {
-    kind: 'unexpected-object',
-    table: object.table ?? object.name,
-    column: null,
-    cause: `${object.kind} "${object.name}"${signature}${where} exists in this database and no migration creates it`,
-    fix: spellable
-      ? `run ${drop} inside psql "$DATABASE_URL", then write its create statement into a ` +
-        'migration and run x db migrate — or leave it dropped if nothing owns it'
-      : 'drop it by hand, then write its create statement into a migration and run x db migrate ' +
-        '— its name or arguments carry a backtick, a dollar sign, a quote, a backslash or ' +
-        'whitespace, so ' +
-        'no statement here can spell it',
+    ...base,
+    fix:
+      `${show}   # no migration creates it: copy its definition into a migration as a create ` +
+      `statement, run ${spoken} here, then x db migrate — or only drop it if nothing owns it`,
   };
 }
 

package/src/pglite-branch.ts

@@ -5,10 +5,10 @@
 
 import { cp, mkdir, rm, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { systemClock } from '@ultimat3/core';
+import { NotImplementedError, systemClock } from '@ultimat3/core';
 import type { BranchInfo } from './branch';
 import { assertBranchName } from './branch';
-import { branchExists, dbNotImplemented, dbUnavailable } from './errors';
+import { branchExists, dbUnavailable } from './errors';
 import { PGLITE_MEMORY, pgliteDataDir } from './pglite';
 
 export interface PgliteBranchOptions {
@@ -56,10 +56,10 @@ export async function branchPglite(
   assertBranchName(branch);
   const from = pgliteDataDir(options.from);
   if (from === PGLITE_MEMORY) {
-    throw dbNotImplemented(
-      'branching an in-memory PGlite',
-      'x dev   # a branch copies .x/pgdata, so the database has to be on disk first',
-    );
+    throw new NotImplementedError({
+      cause: 'branching an in-memory PGlite is not implemented by this driver',
+      fix: 'x dev   # a branch copies .x/pgdata, so the database has to be on disk first',
+    });
   }
   if (!(await isDirectory(from))) {
     throw dbUnavailable(`there is no PGlite data directory at ${from}, so nothing to branch`);

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. */
@@ -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/primary-key.ts

@@ -0,0 +1,180 @@
+// 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 } 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';
+
+/**
+ * `<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`,
+    `psql "$DATABASE_URL" -c "select conname from pg_constraint where contype = 'p' and conrelid = '${table}'::regclass"   # 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 "${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 "${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/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;