@ultimat3/db 23.0.0 → 25.0.0

package/src/array-parameter.ts

@@ -28,18 +28,45 @@ import { assert } from '@ultimat3/core';
  * backslash, or leading/trailing whitespace the parser would strip — plus the empty string, which
  * unquoted is not an element at all.
  */
+const hexOf = (bytes: Uint8Array): string =>
+  Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/**
+ * A `Date` as the instant Postgres reads, or `X_INVARIANT` for one that holds no instant.
+ * `toISOString()` on an Invalid Date is a bare `RangeError`, and inside the funnel that became
+ * "cannot reach the database". `position` names the parameter when the caller knows it.
+ */
+export function instantText(value: Date, position?: number): string {
+  assert(
+    !Number.isNaN(value.getTime()),
+    `${position === undefined ? 'an array element' : `parameter $${position}`} is an Invalid Date, which names no instant Postgres could store`,
+    'new Date(input) answers Invalid Date for text it cannot parse — parse it with t.date first, or bind null: Number.isNaN(value.getTime()) ? null : value',
+  );
+  return value.toISOString();
+}
+
 function element(value: unknown): string {
   if (value === null || value === undefined) return 'NULL';
   // A Date is ALWAYS quoted, even though an ISO-8601 instant carries no character the grammar
   // reads as structure. A timestamp element is conventionally quoted, and the alternative is a
   // rule that holds only while nothing ever renders a timestamp with a space in it.
-  if (value instanceof Date) return `"${value.toISOString()}"`;
+  if (value instanceof Date) return `"${instantText(value)}"`;
+  // BYTEA's hex form, never `String(bytes)` — that is `1,2,3`, three elements where one was bound,
+  // and no error anywhere. The backslash is doubled because a quoted element reads `\\` as one.
+  if (value instanceof Uint8Array) return `"\\\\x${hexOf(value)}"`;
   const text = String(value);
   const structural = /[{},"\\\s]/.test(text) || text.length === 0 || text.toUpperCase() === 'NULL';
   if (!structural) return text;
   return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
 
+/** The extents along a value's FIRST path, `2x3` for two rows of three — `''` for a scalar. */
+function extentsOf(value: unknown): string {
+  if (!Array.isArray(value)) return '';
+  const inner = extentsOf(value[0]);
+  return inner === '' ? String(value.length) : `${value.length}x${inner}`;
+}
+
 /**
  * The array literal for one parameter: `{a,b,c}`, elements escaped.
  *
@@ -71,5 +98,15 @@ export function pgArrayLiteral(values: readonly unknown[]): string {
     `a nested array parameter is ragged — its rows are ${nested.map((row) => row.length).join(', ')} long, and Postgres has no jagged array`,
     'give every row the same length, or bind one array per row',
   );
+  // Every extent, not only this level's: `[[['a']], [['b', 'c']]]` is two rows of one element each,
+  // each rectangular on its own, and `{{{a}},{{b,c}}}` is the same 22P02 — measured on 17. Each
+  // row is checked against itself by the recursion below, so comparing one path's extents per row
+  // is comparing all of them.
+  const depth = extentsOf(nested[0]);
+  assert(
+    nested.every((row) => extentsOf(row) === depth),
+    `a nested array parameter is ragged below its first level — its rows have the extents ${nested.map((row) => extentsOf(row)).join(' | ')}, and Postgres has no jagged array`,
+    'give every branch the same length at every depth, or bind one array per row',
+  );
   return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`;
 }

package/src/bound-parameters.ts

@@ -4,7 +4,7 @@
 // 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';
+import { instantText, pgArrayLiteral } from './array-parameter';
 
 const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value instanceof Date;
 
@@ -12,12 +12,31 @@ const needsEncoding = (value: unknown): boolean => Array.isArray(value) || value
  * 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.
+ *
+ * It REFUSES what cannot be sent — a ragged array, an Invalid Date — with `X_INVARIANT`, so the
+ * funnel calls it BEFORE the driver's `try`: inside it, a refusal was re-wrapped as a driver
+ * failure and read "cannot reach the database".
  */
+/**
+ * The refusals alone, for a driver that does its own encoding. PGlite renders an array and a
+ * `Date` correctly, so `pglite.ts` sends the caller's values untouched — but what cannot be sent
+ * must be refused alike on both funnels: an Invalid Date (its serializer answers a bare
+ * `RangeError`) and a ragged or mixed-depth array, which the pooled path refuses in
+ * `pgArrayLiteral`. That function IS the shape rule, so it is asked and its literal discarded
+ * rather than restated here; only a statement that binds an array pays for it.
+ */
+export function refuseUnsendable(values: readonly unknown[]): void {
+  for (const [index, value] of values.entries()) {
+    if (value instanceof Date) instantText(value, index + 1);
+    else if (Array.isArray(value)) pgArrayLiteral(value);
+  }
+}
+
 export function encodeBoundParameters(values: readonly unknown[]): readonly unknown[] {
   if (!values.some(needsEncoding)) return values;
-  return values.map((value) => {
+  return values.map((value, index) => {
     if (Array.isArray(value)) return pgArrayLiteral(value);
-    if (value instanceof Date) return value.toISOString();
+    if (value instanceof Date) return instantText(value, index + 1);
     return value;
   });
 }

package/src/catalog-fold.ts

@@ -51,7 +51,10 @@ function columnOf(row: ColumnRow, sequences: readonly SequenceRow[]): CatalogCol
     type: row.type,
     notNull: row.not_null,
     default: generated ? null : row.expression,
-    generated: generated ? row.expression : null,
+    generated:
+      generated && row.expression !== null
+        ? { expression: row.expression, storage: row.generated === 'v' ? 'virtual' : 'stored' }
+        : null,
     identity:
       identity === undefined
         ? null

package/src/catalog-objects.ts

@@ -148,6 +148,15 @@ export const triggerRows = (client: DbClient, schema: string): Promise<readonly
  * What exists in the schema and the dump cannot spell. One query, one closed list — a kind added
  * here is a kind the dump admits it does not carry, and a kind rendered later leaves this list in
  * the same diff.
+ *
+ * The last four are facts ABOUT an object the dump does render, and each was absent from both the
+ * dump and this list: `create statistics`, `force row level security` (a second flag beside
+ * `relrowsecurity`), a column whose `set storage` departs from its type's own, and a materialized
+ * view created `with no data` — which the dump's `create materialized view` would populate. A
+ * load-equals-replay check cannot see any of them, because both sides are this same reading.
+ *
+ * A trigger on a relation the dump does not create is the one kind NOT read here: which relations
+ * are rendered is the fold's answer, so `introspectCatalog` names those itself.
  */
 export const unrenderedRows = (
   client: DbClient,
@@ -194,6 +203,26 @@ export const unrenderedRows = (
       from pg_rewrite r
       join pg_class c on c.oid = r.ev_class
       where r.rulename <> '_RETURN'
+      union all
+      select 'extended statistics', s.stxname, c.relname, s.stxnamespace
+      from pg_statistic_ext s
+      join pg_class c on c.oid = s.stxrelid
+      union all
+      select 'forced row security', c.relname, c.relname, c.relnamespace
+      from pg_class c
+      where c.relforcerowsecurity
+      union all
+      select 'column storage', a.attname, c.relname, c.relnamespace
+      from pg_attribute a
+      join pg_class c on c.oid = a.attrelid
+      join pg_type t on t.oid = a.atttypid
+      where c.relkind = 'r' and a.attnum > 0 and not a.attisdropped
+        and a.attstorage <> t.typstorage
+        and ${notExtensionOwned('pg_class', 'c.oid')}
+      union all
+      select 'unpopulated materialized view', c.relname, null::text, c.relnamespace
+      from pg_class c
+      where c.relkind = 'm' and not c.relispopulated
     ) objects
     join pg_namespace n on n.oid = objects.namespace
     where n.nspname = ${schema}

package/src/catalog.ts

@@ -56,8 +56,16 @@ export interface CatalogColumn {
   readonly notNull: boolean;
   /** `pg_get_expr` of the default; `null` when there is none or the column is generated. */
   readonly default: string | null;
-  /** The stored generation expression, when `attgenerated` says the column has one. */
-  readonly generated: string | null;
+  /**
+   * The generation expression and HOW it is kept, when `attgenerated` says the column has one:
+   * `s` is `stored`, `v` (Postgres 18) is `virtual` — computed on read, nothing on disk. Both
+   * halves, because a dump that spelled every one `stored` loaded a virtual column as a stored
+   * one and round-tripped "equal": both sides of that comparison were this reading.
+   */
+  readonly generated: {
+    readonly expression: string;
+    readonly storage: 'stored' | 'virtual';
+  } | null;
   /** `always` / `by default`, with the identity sequence's own options. */
   readonly identity: {
     readonly mode: 'always' | 'by default';

package/src/client.ts

@@ -69,7 +69,7 @@ export interface PostgresClient extends ReservableClient, ListeningClient {
 }
 
 /** Lazily connects: the pool opens on the first statement, never at import. */
-export function createPostgresClient(options: PostgresClientOptions = {}): PostgresClient {
+export function postgresClient(options: PostgresClientOptions = {}): PostgresClient {
   const role = options.role ?? resolveRole();
   const profile: PoolProfile = assertPoolProfile({
     ...poolProfileFor(role),
@@ -247,7 +247,7 @@ export function setDbClient(client: DbClient | undefined): void {
  *
  * The role default is layered under `DATABASE_POOL_MAX`, because this is the one place the process
  * builds its own client and therefore the only place an operator's value can reach one:
- * `createPostgresClient` has always taken a `profile` override and nothing in a running app passed
+ * `postgresClient` has always taken a `profile` override and nothing in a running app passed
  * it, so `POOL_PROFILES` was the last word in a deployed image. `default-client.ts` owns what gets
  * built — one pool, or a primary and a replica when `DATABASE_REPLICA_URL` names one.
  */

package/src/column-alter.ts

@@ -6,8 +6,9 @@
 
 import { defaultExpression, hasUnrenderedDefault } from './column-default';
 import { columnDefaultUnsafe } from './ddl-errors';
-import type { ColumnDescriptionLike } from './entity-shape';
+import type { ColumnDescriptionLike, EntityDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
+import { appendOnlyBackfillRefused } from './generate-append-only';
 import type { ColumnDescription } from './introspect';
 import { identifier } from './sql';
 import { statementsOf } from './statement-split';
@@ -29,18 +30,20 @@ function screened(column: string, expression: string): string {
  * `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.
+ * the expand/contract note `diffTable` writes for a NOT NULL column added to a populated table —
+ * refused on an append-only table, whose backfill the trigger would refuse.
  *
  * 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,
+  entity: EntityDescriptionLike,
   column: ColumnDescriptionLike,
   recorded: ColumnDescription,
   plan: Plan,
 ): void {
+  const { table } = entity;
   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;
@@ -59,6 +62,9 @@ export function alterColumnInPlace(
     plan.down.push(`${alter} set not null;`);
     return;
   }
+  // That backfill is an UPDATE, and an append-only table's trigger refuses every one. Refused even
+  // with a default now declared: `set default` fills no row that already holds NULL.
+  if (entity.appendOnly === true) throw appendOnlyBackfillRefused(entity, column, 'made-not-null');
   // `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;`);

package/src/commit-tag.ts

@@ -0,0 +1,21 @@
+// Single responsibility: the server's answer to `COMMIT`, read. Postgres answers a COMMIT on an
+// aborted transaction with the command tag `ROLLBACK` and NO error, so a driver that reports only
+// rejections calls a rolled-back unit of work committed. Both funnels (`statement-funnel.ts`,
+// `pglite.ts`) ask here, so every COMMIT in the process is covered and not only `withTransaction`'s.
+
+import { stringField } from '@ultimat3/core';
+import { transactionAborted } from './transaction-errors';
+
+/** `COMMIT` and its alias `END`, as the first word. Only consulted once the tag already disagrees. */
+const COMMIT_STATEMENT = /^\s*(?:commit|end)\b/i;
+
+/**
+ * Throws `X_DB_TRANSACTION_ABORTED` when `text` asked for a commit and the tag says `ROLLBACK`.
+ * The tag is read first: one property read per statement on the path every statement takes, and
+ * the regular expression runs only for a statement that really was answered `ROLLBACK`. Both
+ * drivers carry the tag on `command` — measured on Bun.SQL against Postgres 17 and on PGlite.
+ */
+export function refuseRolledBackCommit(text: string, result: unknown): void {
+  if (stringField(result, 'command') !== 'ROLLBACK') return;
+  if (COMMIT_STATEMENT.test(text)) throw transactionAborted();
+}

package/src/default-client.ts

@@ -3,7 +3,7 @@
 // framework decides a process's database topology from the environment, and `client.ts` is at the
 // line ceiling.
 
-import { createPostgresClient, type DbClient } from './client';
+import { type DbClient, postgresClient } from './client';
 import { poolMaxFromEnv } from './pool-profile';
 import { replicatedClient } from './replica-client';
 
@@ -18,7 +18,7 @@ import { replicatedClient } from './replica-client';
 export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
 
 /**
- * Composed rather than folded into `createPostgresClient`, on purpose: `migrate`, `x db branch` and
+ * Composed rather than folded into `postgresClient`, on purpose: `migrate`, `x db branch` and
  * every test build a client that must be exactly one pool, and a second pool reachable through the
  * same factory would be a second thing `reserve()`, `close()` and `ping()` each have to mean two
  * ways.
@@ -29,8 +29,8 @@ export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
  */
 export function defaultClient(): DbClient {
   const profile = poolMaxFromEnv();
-  const primary = createPostgresClient({ profile });
+  const primary = postgresClient({ profile });
   const replicaUrl = process.env[REPLICA_URL_ENV];
   if (replicaUrl === undefined || replicaUrl.trim() === '') return primary;
-  return replicatedClient(primary, createPostgresClient({ url: replicaUrl, profile }));
+  return replicatedClient(primary, postgresClient({ url: replicaUrl, profile }));
 }

package/src/dependent-view.ts

@@ -2,7 +2,7 @@
 // before the statement is sent — and name the view, the column and the statement that recreates it.
 //
 // **This is the honest ceiling for views, and the reason it is not in the generator.** `x db gen`
-// runs with no database open; `SchemaDescription` has no field for a view; `introspect()` reads
+// runs with no database open; `SchemaDescription` has no field for a view; `introspectSchema()` reads
 // none by construction (`app-relation.ts` excludes every non-table relation); and no `entity()` can
 // declare one. So nothing the generator reads knows a view exists, and a `GenerateOptions.views`
 // with no caller to fill it is the declared-and-never-wired defect this release exists to
@@ -139,6 +139,7 @@ async function dependentViews(
       join pg_attribute a on a.attrelid = c.oid and a.attnum = d.refobjsubid
      where v.relkind in ('v', 'm') and v.oid <> c.oid
        and c.relname in (${tables}) and a.attname in (${columns})
+       and pg_table_is_visible(c.oid)
      order by v.relname
   `);
 }
@@ -155,7 +156,8 @@ async function dependentViews(
 const shellArg = (statement: string): string => `'${statement.replaceAll("'", `'\\''`)}'`;
 
 /** The invocation `migrationConflict` already writes, with the statement as its own argv word. */
-const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
+export const psqlCommand = (statement: string): string =>
+  `psql "$DATABASE_URL" -c ${shellArg(statement)}`;
 
 /**
  * The two statements that unblock the deploy, as one line an operator pastes.
@@ -166,7 +168,7 @@ const psql = (statement: string): string => `psql "$DATABASE_URL" -c ${shellArg(
  * a shell read `drop` as a program that does not exist. Neither reader could run it (axiom 4).
  *
  * `identifier()` REFUSES a name holding a quote, a space or a backslash — all three legal inside a
- * quoted Postgres name — and a `fix:` may not throw: the rule `rebuildForeignKey` already states,
+ * quoted Postgres name — and a `fix:` may not throw: the rule `changedForeignKey` (`drift-findings.ts`) states,
  * with the same shape. A refusal that raised `X_SQL_UNSAFE` in place of the finding would hand the
  * operator an exception where a verdict was asked for, over a view name that is perfectly legal.
  * The fallback still leads with a command that runs — a psql session — because quoting that name
@@ -192,8 +194,8 @@ function restoreView(view: string, definition: string, relkind: string): string
   try {
     const name = identifier(view).text;
     return (
-      `${psql(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
-      `${psql(`create ${kind} ${name} as ${body}`)}${note}`
+      `${psqlCommand(`drop ${kind} ${name}`)}   # then x db migrate, then: ` +
+      `${psqlCommand(`create ${kind} ${name} as ${body}`)}${note}`
     );
   } catch {
     return (

package/src/destructive.ts

@@ -112,4 +112,4 @@ export function destructiveStatements(up: string): readonly DestructiveStatement
 }
 
 /** Whether `up` destroys data at all — what `x db gen` writes the marker from. */
-export const isDestructive = (up: string): boolean => destructiveStatements(up).length > 0;
+export const isDestructiveMigration = (up: string): boolean => destructiveStatements(up).length > 0;

package/src/drift-append-only.ts

@@ -0,0 +1,53 @@
+// Single responsibility: whether an `appendOnly` table still carries the trigger that refuses UPDATE
+// and DELETE, and what to say when it does not. The repository refuses above the driver whatever
+// the database holds, so a dropped trigger is invisible to every test — only the catalog can say.
+
+import { byHand, type DriftDifference, pathTo, repair } from './drift-findings';
+import {
+  APPEND_ONLY_FUNCTION_SQL,
+  APPEND_ONLY_TRIGGER,
+  installAppendOnlyTriggerSql,
+} from './generate-append-only';
+import type { TableDescription } from './introspect';
+import { shellInertIdentifier } from './sql';
+
+/** The code `driftError` raises for this kind, exported so the tests assert the one literal. */
+export const APPEND_ONLY_DRIFT_CODE = 'X_APPEND_ONLY_TRIGGER_MISSING';
+
+/**
+ * The constructor. The fix is the two statements `x db gen` wrote, run against THIS database:
+ * the migration that added the trigger is already in the ledger, so `x db migrate` applies nothing
+ * (`repair`'s argument). Drop-if-exists before create, because a DISABLED trigger counts as missing
+ * here yet still exists, and a bare `create trigger` would fail on it. The function is redefined too — `create or replace` — because a hand that
+ * dropped the trigger may have dropped the function with it.
+ */
+export function missingAppendOnlyTrigger(schema: string, table: string): DriftDifference {
+  const path = pathTo(schema);
+  const spellable = shellInertIdentifier(table) !== null;
+  return {
+    kind: 'missing-append-only-trigger',
+    table,
+    column: null,
+    cause:
+      `table "${table}" is declared appendOnly, and its trigger ${APPEND_ONLY_TRIGGER} is missing ` +
+      'or disabled — raw SQL can UPDATE and DELETE its rows; only the repository still refuses',
+    fix:
+      path === null || !spellable
+        ? byHand('re-create the append-only function and trigger this difference names')
+        : repair(path, [APPEND_ONLY_FUNCTION_SQL, ...installAppendOnlyTriggerSql(table)].join(' ')),
+  };
+}
+
+/**
+ * Judged only where both halves were asked: the snapshot declares the table append-only AND the
+ * catalog was read (`triggerNames` present). Either absent says nothing — a sidecar that predates
+ * the field, or a description nobody introspected — exactly as `compareChecks` reads its pair.
+ */
+export function compareAppendOnly(
+  live: TableDescription,
+  expected: TableDescription,
+): DriftDifference[] {
+  if (expected.appendOnly !== true || live.triggerNames === undefined) return [];
+  if (live.triggerNames.includes(APPEND_ONLY_TRIGGER)) return [];
+  return [missingAppendOnlyTrigger(live.schema, live.name)];
+}

package/src/drift-errors.ts

@@ -10,9 +10,9 @@ import { DbError } from './errors';
 import { shellInertIdentifier } from './sql';
 
 /**
- * The contract's pinned wording. Mirror of `@ultimat3/entity`'s `dbDrift()` — keep in sync; that
- * one screens the column through the same `@ultimat3/db` export, so the two lines are the same
- * text on both sides of the tier seam.
+ * The contract's pinned wording, and the ONE definition of it: `@ultimat3/entity` carried a second
+ * `dbDrift()` held in step by a comment and a test, deleted `As of 2026-10-02`. Drift is this
+ * package's to raise.
  *
  * The column name is the CATALOG's, so it is data: whoever can add a column picks the text that
  * lands here, and `x db gen "add C"` puts it inside SHELL DOUBLE QUOTES, where `$(…)` and a