@ultimat3/db 22.15.0 → 24.0.0

package/src/drift.ts

@@ -9,6 +9,7 @@ import {
   changedColumn,
   changedForeignKey,
   changedIndex,
+  changedPrimaryKey,
   missingCheck,
   missingColumn,
   missingForeignKey,
@@ -23,6 +24,7 @@ import { foreignKeyTarget, onDeleteRule } from './foreign-key';
 import { indexMethodOf } from './index-method';
 import { findTable, introspect, type SchemaDescription, type TableDescription } from './introspect';
 import { type LedgerRow, type Migration, readLedger } from './migrate';
+import { sameColumns } from './primary-key';
 
 // Re-exported explicitly, never `export *`: `src/index.ts` publishes both from `'./drift'`, so the
 // split is invisible to `@ultimat3/db`'s public surface and no consumer moves with it.
@@ -145,7 +147,7 @@ function compareForeignKeys(live: TableDescription, expected: TableDescription):
       continue;
     }
     if (onDeleteRule(counterpart.onDelete) !== onDeleteRule(key.onDelete)) {
-      differences.push(changedForeignKey(live.name, key, counterpart));
+      differences.push(changedForeignKey(live.schema, live.name, key, counterpart));
     }
   }
   return differences;
@@ -175,26 +177,29 @@ function compareChecks(live: TableDescription, expected: TableDescription): Drif
   const present = new Set(held);
   return declared
     .filter((check) => !present.has(check.name))
-    .map((check) => missingCheck(live.name, check));
+    .map((check) => missingCheck(live.schema, live.name, check));
 }
 
 /**
- * A primary key column is `NOT NULL` in the catalog whether or not anything declared it — Postgres
- * adds the constraint with the key. Both sides are therefore read through the union of the two
- * primary keys, or a table whose snapshot spells its key column nullable reports a difference
- * against a database that is exactly right and cannot be anything else. The union, not one side:
- * a key present on only one of them is a difference the *key* comparison owns, and reporting it
- * again as a nullability change would be one fault with two findings.
+ * The two key lists, compared in ORDER. The comment that used to stand here said a key on one side
+ * only "is a difference the key comparison owns" — and no key comparison existed, so a table
+ * re-keyed by hand, or one whose key no migration ever produced, read `ok: true`.
  */
-function keyColumnsOf(live: TableDescription, expected: TableDescription): ReadonlySet<string> {
-  return new Set([...live.primaryKey, ...expected.primaryKey]);
+function comparePrimaryKey(live: TableDescription, expected: TableDescription): DriftDifference[] {
+  if (sameColumns(live.primaryKey, expected.primaryKey)) return [];
+  const held = live.indexes.find((index) => index.primary)?.name;
+  return [changedPrimaryKey(live.schema, live.name, live.primaryKey, held, expected.primaryKey)];
 }
 
 function compareTable(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
   const expectedColumns = new Map(expected.columns.map((column) => [column.name, column]));
   const liveColumns = new Map(live.columns.map((column) => [column.name, column]));
-  const keyColumns = keyColumnsOf(live, expected);
+  // A primary key column is `NOT NULL` in the catalog whether or not anything declared it —
+  // Postgres adds the constraint with the key — so a snapshot spelling its key column nullable is
+  // not drift. The DECLARED key only: a column the database alone keys stays NOT NULL after the
+  // stray constraint is dropped, which is a second fault and reported as one.
+  const keyColumns = new Set(expected.primaryKey);
   for (const column of live.columns) {
     if (expectedColumns.has(column.name)) continue;
     differences.push(unexpectedColumn(live.name, column.name));
@@ -210,9 +215,10 @@ function compareTable(live: TableDescription, expected: TableDescription): Drift
     // `retypeColumn` already owns that question where both sides are generated.
     if (keyColumns.has(column.name)) continue;
     if (column.nullable !== counterpart.nullable) {
-      differences.push(changedColumn(live.name, column.name, counterpart.nullable));
+      differences.push(changedColumn(live.schema, live.name, column.name, counterpart.nullable));
     }
   }
+  differences.push(...comparePrimaryKey(live, expected));
   differences.push(...compareIndexes(live, expected));
   differences.push(...compareChecks(live, expected));
   differences.push(...compareForeignKeys(live, expected));
@@ -224,7 +230,7 @@ export function diffSchema(live: SchemaDescription, expected: SchemaDescription)
   const differences: DriftDifference[] = [];
   for (const table of live.tables) {
     const counterpart = findTable(expected, table.name);
-    if (counterpart === undefined) differences.push(unexpectedTable(table.name));
+    if (counterpart === undefined) differences.push(unexpectedTable(table.schema, table.name));
     else differences.push(...compareTable(table, counterpart));
   }
   for (const table of expected.tables) {

package/src/dump-drift.ts

@@ -0,0 +1,142 @@
+// Single responsibility: `X_SCHEMA_DUMP_DRIFT` — what it means for a committed schema dump to
+// disagree with the one the migrations produce, and how each disagreement reads. Pure: files in,
+// differences out. Which directory the dump lives in is the caller's fact; paths here are relative.
+
+import { DbError } from './errors';
+import type { SchemaDumpFile } from './schema-dump';
+
+export type SchemaDumpDifferenceKind =
+  | 'missing-file'
+  | 'changed-file'
+  | 'unexpected-file'
+  | 'unloadable'
+  | 'reload-differs';
+
+export interface SchemaDumpDifference {
+  readonly kind: SchemaDumpDifferenceKind;
+  /** Relative to the dump directory. */
+  readonly path: string;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/** Regenerating is the whole repair for a dump that is merely behind. */
+export const SCHEMA_DUMP_FIX = 'x db gen';
+
+/**
+ * For a dump that regenerating cannot repair. It still starts with the command, because the first
+ * thing to rule out is a dump that is merely stale — and it says what the second failure means,
+ * since nothing the app's author can run fixes a statement the dump renders wrong.
+ */
+const roundTripFix = (path: string): string =>
+  `x db gen   # and when the regenerated dump is refused the same way, ${path} holds an object the dump cannot round-trip: report it with that file and the migration that creates it`;
+
+const byPath = (a: SchemaDumpDifference, b: SchemaDumpDifference): number =>
+  a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+
+/**
+ * The committed files against the rendered ones, byte for byte, in both directions: a file the
+ * migrations produce and nobody committed, one whose bytes differ, and one on disk that nothing
+ * renders. The last matters as much as the first — a stray `04_tables/old.sql` is a table an
+ * agent reading the directory believes exists.
+ */
+export function compareSchemaDump(
+  committed: readonly SchemaDumpFile[],
+  rendered: readonly SchemaDumpFile[],
+): readonly SchemaDumpDifference[] {
+  const onDisk = new Map(committed.map((file) => [file.path, file.content]));
+  const produced = new Set(rendered.map((file) => file.path));
+  const differences: SchemaDumpDifference[] = [];
+  for (const file of rendered) {
+    const held = onDisk.get(file.path);
+    if (held === file.content) continue;
+    differences.push(
+      held === undefined
+        ? {
+            kind: 'missing-file',
+            path: file.path,
+            cause: `schema dump file ${file.path} is what the migrations produce and is not committed`,
+            fix: SCHEMA_DUMP_FIX,
+          }
+        : {
+            kind: 'changed-file',
+            path: file.path,
+            cause: `schema dump file ${file.path} differs from what the migrations produce`,
+            fix: SCHEMA_DUMP_FIX,
+          },
+    );
+  }
+  for (const file of committed) {
+    if (produced.has(file.path)) continue;
+    differences.push({
+      kind: 'unexpected-file',
+      path: file.path,
+      cause: `schema dump file ${file.path} describes nothing the migrations produce`,
+      fix: SCHEMA_DUMP_FIX,
+    });
+  }
+  return differences.sort(byPath);
+}
+
+/**
+ * Load equals replay, as a comparison: the dump of the migrated database against the dump of a
+ * database built by loading that dump. Any difference means the files are not a cache of the
+ * migrations but a second, lossy source. One finding, naming the first file that came back
+ * different — the rest follow from it.
+ *
+ * Asked only of a dump that claims to be whole. One that names objects in `unrendered.sql` has
+ * already said it is not, and its caller does not ask.
+ */
+export function reloadDifferences(
+  replayed: readonly SchemaDumpFile[],
+  reloaded: readonly SchemaDumpFile[],
+): readonly SchemaDumpDifference[] {
+  const first = compareSchemaDump(reloaded, replayed)[0];
+  if (first === undefined) return [];
+  return [
+    {
+      kind: 'reload-differs',
+      path: first.path,
+      cause: `a database loaded from the schema dump is not the one the migrations build: ${first.path} comes back different`,
+      fix: roundTripFix(first.path),
+    },
+  ];
+}
+
+/** A dump file the database refused, with what the database said about it. */
+export const unloadableDump = (path: string, detail: string): SchemaDumpDifference => ({
+  kind: 'unloadable',
+  path,
+  cause: `schema dump file ${path} does not load: ${detail}`,
+  fix: roundTripFix(path),
+});
+
+export const schemaDumpDrift = (difference: SchemaDumpDifference): DbError =>
+  new DbError({
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: difference.cause,
+    fix: difference.fix,
+    meta: { kind: difference.kind, path: difference.path },
+  });
+
+const DIFFERENCE_KINDS: readonly string[] = [
+  'missing-file',
+  'changed-file',
+  'unexpected-file',
+  'unloadable',
+  'reload-differs',
+] satisfies readonly SchemaDumpDifferenceKind[];
+
+/**
+ * The difference a thrown `X_SCHEMA_DUMP_DRIFT` was built from, or `undefined` for anything else.
+ * `loadSchemaDump` throws; a caller that reports findings wants the value back, and reading it
+ * off the error here keeps `meta`'s shape a fact of this file alone.
+ */
+export function schemaDumpDifferenceOf(error: unknown): SchemaDumpDifference | undefined {
+  if (!(error instanceof DbError) || error.code !== 'X_SCHEMA_DUMP_DRIFT') return undefined;
+  const kind = error.meta?.['kind'];
+  const path = error.meta?.['path'];
+  if (typeof kind !== 'string' || typeof path !== 'string') return undefined;
+  if (!DIFFERENCE_KINDS.includes(kind)) return undefined;
+  return { kind: kind as SchemaDumpDifferenceKind, path, cause: error.cause, fix: error.fix };
+}

package/src/errors.ts

@@ -37,6 +37,10 @@ export const DB_OWNED_ERROR_CODES = [
   'X_MIGRATE_CONCURRENT',
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
+  'X_SCHEMA_DUMP_DRIFT',
+  'X_DB_TRANSACTION_ABORTED',
+  'X_DB_COMMIT_UNKNOWN',
+  'X_DB_SIBLING_SCOPE_TIMEOUT',
 ] as const;
 
 /**
@@ -81,6 +85,10 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_MIGRATION_VIEW_DEPENDS: 'a view is compiled against a column this migration retypes',
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
+  X_SCHEMA_DUMP_DRIFT: 'the committed schema dump is not what the migrations produce',
+  X_DB_TRANSACTION_ABORTED: 'the server rolled the transaction back',
+  X_DB_COMMIT_UNKNOWN: 'the connection was lost while COMMIT was in flight',
+  X_DB_SIBLING_SCOPE_TIMEOUT: 'a nested transaction scope waited too long for its sibling',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails
@@ -414,10 +422,3 @@ export const isolationLevelInvalid = (received: unknown): DbError =>
     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',
-    cause: `${feature} is not implemented by this driver`,
-    fix,
-  });

package/src/foreign-key.ts

@@ -130,37 +130,3 @@ export function unrestorableNote(table: string, constraint: string, gone: string
     `cannot be restored; ${identifier(gone).text} is gone`
   );
 }
-
-/**
- * The drop/add pair that moves a key's `on delete` rule — a rebuild, because Postgres has no
- * `alter constraint` for it — for a `fix:` line an author pastes into a new migration.
- *
- * It lives here, beside the two writers, because it is the one caller reading values neither of
- * them may assume: `held` is the **live catalog's** and `declared` is a `.snapshot.json`'s. Both
- * writers refuse rather than guess — `identifier()` on a name holding a quote, a space or a
- * backslash (all three legal inside a quoted Postgres name), and `addForeignKey` on an `on delete`
- * rule Postgres does not have. That is exactly right for DDL this package SENDS and wrong for a
- * `fix:` line: `diffSchema` is documented pure and total, so a pair it cannot write is a sentence,
- * never a throw — a drift check that raises in place of its report hands the caller an exception
- * where a verdict was asked for. The constraint is still named, because it is the only thing
- * identifying which one, quoted by `JSON.stringify`, which escapes rather than refuses; nothing
- * runs this string either way.
- */
-export function rebuildForeignKey(
-  table: string,
-  declared: ForeignKeyDescription,
-  held: ForeignKeyDescription,
-): string {
-  // The writers are ASKED whether they can write the pair — never a second copy of their rules
-  // beside them, which is the copy that drifts. A refusal is the answer, and nothing here reads
-  // the thrown value.
-  try {
-    return `${dropForeignKey(table, held.name)} ${addForeignKey(table, declared)}`;
-  } catch {
-    return (
-      `drop constraint ${JSON.stringify(held.name)} on table ${JSON.stringify(table)} and add ` +
-      'it back with the on delete rule the migrations declare — by hand: x db gen cannot ' +
-      'write this pair'
-    );
-  }
-}

package/src/generate.ts

@@ -23,6 +23,7 @@ import {
 } from './introspect';
 import { declaredIndexes } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
+import { addChangedKey, dropChangedKey } from './primary-key';
 import type { ReplicaIdentityInput } from './replica-identity';
 import { replicaIdentityFullAfter, replicaIdentityPlan } from './replica-identity';
 import type { MovedAside } from './retype-dependents';
@@ -324,6 +325,9 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
       created.add(entity.table);
       continue;
     }
+    // The key first and last, around every column statement of the table (`primary-key.ts`): the
+    // snapshot below records `entity.primaryKey`, and until this arm existed nothing produced it.
+    dropChangedKey(entity, live, current, plan, options.name);
     diffTable(entity, live, plan, retypedIn(retyped, entity.table));
     const kept = new Set(entity.columns.map((column) => column.column));
     for (const column of live.columns) {
@@ -343,6 +347,7 @@ export function generateMigration(options: GenerateOptions): GeneratedMigration
           ' -- data is not restored',
       );
     }
+    addChangedKey(entity, live, plan, options.name);
   }
 
   const order = dropOrder(current.tables.filter((table) => !wanted.has(table.name)));

package/src/index.ts

@@ -72,7 +72,6 @@ export {
   DB_ERROR_RETRY,
   DB_ERROR_TITLES,
   DbError,
-  dbNotImplemented,
   dbUnavailable,
   driverError,
   identifierUnsafe,
@@ -112,6 +111,8 @@ export {
   uniqueColumns,
 } from './invariant-ddl';
 export { constraintExpressionUnsafe, constraintNameUnsafe } from './invariant-errors';
+export type { DbSubscription, ListeningClient } from './listen';
+export { canListen } from './listen';
 export type {
   AppliedMigration,
   LedgerRow,
@@ -166,6 +167,8 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { LinkedExtensions, PgliteExtensionLoader } from './pglite-extensions';
+export { linkPgliteExtensions } from './pglite-extensions';
 export type { PoolProfile } from './pool-profile';
 export { POOL_MAX_ENV, POOL_PROFILES, poolProfileFor } from './pool-profile';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
@@ -181,6 +184,7 @@ export { BREAKER_COOLDOWN_MS, BREAKER_FAILURES, replicatedClient } from './repli
 export { type DbNode, isPlainRead } from './replica-route';
 export type { ReplicaScope } from './replica-scope';
 export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope';
+export { SIBLING_SCOPE_WAIT_MS } from './sibling-turn';
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
@@ -199,8 +203,10 @@ export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode }
 export { statementFingerprint, statementKind, statementVerb } from './statement-shape';
 export { STATEMENT_ATTRIBUTE } from './statement-span';
 export { statementsOf } from './statement-split';
-export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
-export { beginStatement, currentTx, withTransaction } from './transaction';
+export { currentTx, liveTxConnection, withTransaction } from './transaction';
+export { commitUnknown, siblingScopeTimeout, transactionAborted } from './transaction-errors';
+export type { DbTx, IsolationLevel, TransactionOptions } from './transaction-options';
+export { beginStatement } from './transaction-options';
 export type { GeneratableForm } from './ungeneratable';
 export { GENERATABLE_FORMS, ungeneratableStatements } from './ungeneratable';
 export type { UnrenderedDeclaration } from './unrendered';

package/src/introspect-catalog.ts

@@ -0,0 +1,171 @@
+// Single responsibility: read the WHOLE schema out of `pg_catalog` — tables and everything that is
+// not a table — into one `CatalogDescription`, sorted in JS. `introspect()` beside it stays the
+// entity-vocabulary reading drift compares to a snapshot; this is the catalog's own spelling, the
+// input of the schema dump, and comparable only to another reading of itself.
+
+import type { CatalogDescription, CatalogType } from './catalog';
+import { by, sequenceOf, tableOf } from './catalog-fold';
+import {
+  domainCheckRows,
+  domainRows,
+  enumRows,
+  extensionRows,
+  functionRows,
+  triggerRows,
+  unrenderedRows,
+  viewRows,
+} from './catalog-objects';
+import {
+  columnRows,
+  constraintRows,
+  indexRows,
+  sequenceRows,
+  tableRows,
+} from './catalog-relations';
+import { type DbClient, db } from './client';
+
+export interface IntrospectCatalogOptions {
+  readonly client?: DbClient | undefined;
+  readonly schema?: string | undefined;
+}
+
+async function typesOf(client: DbClient, schema: string): Promise<readonly CatalogType[]> {
+  const labels = await enumRows(client, schema);
+  const domains = await domainRows(client, schema);
+  const checks = await domainCheckRows(client, schema);
+  const enums = [...new Set(labels.map((row) => row.name))].map(
+    (name): CatalogType => ({
+      kind: 'enum',
+      name,
+      labels: labels
+        .filter((row) => row.name === name)
+        .sort((a, b) => a.position - b.position)
+        .map((row) => row.label),
+    }),
+  );
+  const described = domains.map(
+    (row): CatalogType => ({
+      kind: 'domain',
+      name: row.name,
+      baseType: row.base_type,
+      notNull: row.not_null,
+      default: row.expression,
+      checks: checks
+        .filter((check) => check.domain_name === row.name)
+        .sort(by((check) => check.name))
+        .map((check) => ({ name: check.name, definition: check.definition })),
+    }),
+  );
+  return [...enums, ...described].sort(by((type) => type.name));
+}
+
+/**
+ * Eleven round trips, sequential: a pinned transaction connection answers one statement at a
+ * time, and this runs once per `x db gen`, never per request.
+ */
+export async function introspectCatalog(
+  options: IntrospectCatalogOptions = {},
+): Promise<CatalogDescription> {
+  const client = options.client ?? db();
+  const schema = options.schema ?? 'public';
+  const tables = await tableRows(client, schema);
+  const columns = await columnRows(client, schema);
+  const constraints = await constraintRows(client, schema);
+  const sequences = await sequenceRows(client, schema);
+  const indexes = await indexRows(client, schema);
+  const views = await viewRows(client, schema);
+  const functions = await functionRows(client, schema);
+  const triggers = await triggerRows(client, schema);
+  const unrendered = await unrenderedRows(client, schema);
+  const known = new Set(tables.map((table) => table.name));
+  const materialized = new Set(views.filter((view) => view.kind === 'm').map((view) => view.name));
+  // A trigger loads only onto a relation the dump creates: a plain table, or a view (`instead
+  // of`). One on a partitioned table or a partition was filed under `09_triggers/` for a table no
+  // file creates, and the load refused the whole dump with `X_SCHEMA_DUMP_DRIFT`.
+  const viewNames = new Set(views.map((view) => view.name));
+  const loadable = (trigger: { readonly table_name: string }): boolean =>
+    known.has(trigger.table_name) || viewNames.has(trigger.table_name);
+
+  return {
+    schema,
+    extensions: (await extensionRows(client))
+      .map((row) => ({ name: row.name }))
+      .sort(by((extension) => extension.name)),
+    types: await typesOf(client, schema),
+    sequences: sequences
+      .filter((sequence) => sequence.ownership === null)
+      .map(sequenceOf)
+      .sort(by((sequence) => sequence.name)),
+    tables: tables
+      .map((table) => tableOf(table, columns, constraints, sequences))
+      .sort(by((table) => table.name)),
+    // An index on a relation this reading does not render (a partition) has nowhere to load.
+    indexes: indexes
+      .filter((index) => known.has(index.table_name) || materialized.has(index.table_name))
+      .map((row) => ({ table: row.table_name, name: row.name, definition: row.definition }))
+      .sort(
+        by(
+          (index) => index.table,
+          (index) => index.name,
+        ),
+      ),
+    foreignKeys: constraints
+      .filter((constraint) => constraint.type === 'f' && known.has(constraint.table_name))
+      .map((row) => ({ table: row.table_name, name: row.name, definition: row.definition }))
+      .sort(
+        by(
+          (key) => key.table,
+          (key) => key.name,
+        ),
+      ),
+    views: views
+      .map((row) => ({
+        name: row.name,
+        materialized: row.kind === 'm',
+        options: row.options,
+        definition: row.definition,
+      }))
+      .sort(by((view) => view.name)),
+    functions: functions
+      .map((row) => ({ name: row.name, arguments: row.arguments, definition: row.definition }))
+      .sort(
+        by(
+          (fn) => fn.name,
+          (fn) => fn.arguments,
+        ),
+      ),
+    triggers: triggers
+      .filter(loadable)
+      .map((row) => ({
+        table: row.table_name,
+        name: row.name,
+        definition: row.definition,
+        enabled: row.enabled,
+      }))
+      .sort(
+        by(
+          (trigger) => trigger.table,
+          (trigger) => trigger.name,
+        ),
+      ),
+    unrendered: [
+      ...unrendered,
+      // Named rather than dropped, the rule `CatalogUnrendered` states.
+      ...triggers
+        .filter((trigger) => !loadable(trigger))
+        .map((trigger) => ({
+          kind: 'trigger',
+          name: trigger.name,
+          table_name: trigger.table_name,
+        })),
+    ]
+      .map((row) => ({ kind: row.kind, name: row.name, table: row.table_name }))
+      .sort(
+        by(
+          (object) => object.kind,
+          (object) => object.table ?? '',
+          (object) => object.name,
+        ),
+      ),
+  };
+}

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
   `);