@ultimat3/db 22.15.0 → 24.0.0

package/src/catalog-fold.ts

@@ -0,0 +1,116 @@
+// Single responsibility: catalog ROWS into one table's description — its columns in ordinal order,
+// its constraints ranked, the sequences its `serial` and identity columns own. Pure; the queries
+// are `catalog-relations.ts`'s and the orchestration is `introspect-catalog.ts`'s.
+
+import type {
+  CatalogColumn,
+  CatalogOwnedSequence,
+  CatalogReplicaIdentity,
+  CatalogSequence,
+  CatalogTable,
+} from './catalog';
+import type { ColumnRow, ConstraintRow, SequenceRow, TableRow } from './catalog-relations';
+
+/**
+ * By UTF-16 code unit, never `localeCompare` and never SQL's `order by`: both follow a locale, and
+ * the same database must produce the same bytes on a laptop and in CI.
+ */
+export const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+export const by =
+  <T>(...keys: readonly ((value: T) => string)[]) =>
+  (a: T, b: T): number => {
+    for (const key of keys) {
+      const order = byCodeUnit(key(a), key(b));
+      if (order !== 0) return order;
+    }
+    return 0;
+  };
+
+export const sequenceOf = (row: SequenceRow): CatalogSequence => ({
+  name: row.name,
+  dataType: row.data_type,
+  start: row.seq_start,
+  increment: row.seq_increment,
+  min: row.seq_min,
+  max: row.seq_max,
+  cache: row.seq_cache,
+  cycle: row.seq_cycle,
+});
+
+function columnOf(row: ColumnRow, sequences: readonly SequenceRow[]): CatalogColumn {
+  const identity = sequences.find(
+    (sequence) =>
+      sequence.ownership === 'i' &&
+      sequence.owner_table === row.table_name &&
+      sequence.owner_column === row.name,
+  );
+  const generated = row.generated !== '' && row.generated !== null;
+  return {
+    name: row.name,
+    type: row.type,
+    notNull: row.not_null,
+    default: generated ? null : row.expression,
+    generated:
+      generated && row.expression !== null
+        ? { expression: row.expression, storage: row.generated === 'v' ? 'virtual' : 'stored' }
+        : null,
+    identity:
+      identity === undefined
+        ? null
+        : { mode: row.identity === 'a' ? 'always' : 'by default', sequence: sequenceOf(identity) },
+    collation: row.collation,
+  };
+}
+
+function replicaIdentityOf(row: TableRow): CatalogReplicaIdentity {
+  if (row.replica_identity === 'f') return { kind: 'full' };
+  if (row.replica_identity === 'n') return { kind: 'nothing' };
+  if (row.replica_identity === 'i' && row.replica_index !== null)
+    return { kind: 'index', index: row.replica_index };
+  return { kind: 'default' };
+}
+
+/** Primary key first, then unique, check, exclusion — each group by name. */
+const CONSTRAINT_RANK: ReadonlyMap<string, string> = new Map([
+  ['p', '0'],
+  ['u', '1'],
+  ['c', '2'],
+  ['x', '3'],
+]);
+
+export function tableOf(
+  row: TableRow,
+  columns: readonly ColumnRow[],
+  constraints: readonly ConstraintRow[],
+  sequences: readonly SequenceRow[],
+): CatalogTable {
+  return {
+    name: row.name,
+    unlogged: row.persistence === 'u',
+    options: row.options,
+    columns: columns
+      .filter((column) => column.table_name === row.name)
+      .sort((a, b) => a.position - b.position)
+      .map((column) => columnOf(column, sequences)),
+    constraints: constraints
+      .filter((constraint) => constraint.table_name === row.name && constraint.type !== 'f')
+      .sort(
+        by(
+          (c) => CONSTRAINT_RANK.get(c.type) ?? '9',
+          (c) => c.name,
+        ),
+      )
+      .map((constraint) => ({ name: constraint.name, definition: constraint.definition })),
+    sequences: sequences
+      .filter((sequence) => sequence.ownership === 'a' && sequence.owner_table === row.name)
+      .sort(by((sequence) => sequence.name))
+      .map(
+        (sequence): CatalogOwnedSequence => ({
+          ...sequenceOf(sequence),
+          column: sequence.owner_column ?? '',
+        }),
+      ),
+    replicaIdentity: replicaIdentityOf(row),
+  };
+}

package/src/catalog-objects.ts

@@ -0,0 +1,229 @@
+// Single responsibility: the catalog queries for every object that is NOT a table — extensions,
+// enum and domain types, views, functions, triggers — plus the list of objects the schema dump has
+// no statement for. Flat rows; `introspect-catalog.ts` folds and sorts them.
+
+import { notExtensionOwned } from './catalog-relations';
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+export interface NameRow {
+  readonly name: string;
+}
+
+export interface EnumRow {
+  readonly name: string;
+  readonly label: string;
+  readonly position: number;
+}
+
+export interface DomainRow {
+  readonly name: string;
+  readonly base_type: string;
+  readonly not_null: boolean;
+  readonly expression: string | null;
+}
+
+export interface DomainCheckRow {
+  readonly domain_name: string;
+  readonly name: string;
+  readonly definition: string;
+}
+
+export interface ViewRow {
+  readonly name: string;
+  readonly kind: string;
+  readonly options: string | null;
+  readonly definition: string;
+}
+
+export interface FunctionRow {
+  readonly name: string;
+  readonly arguments: string;
+  readonly definition: string;
+}
+
+export interface TriggerRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly definition: string;
+  readonly enabled: string;
+}
+
+export interface UnrenderedRow {
+  readonly kind: string;
+  readonly name: string;
+  readonly table_name: string | null;
+}
+
+/**
+ * Database-wide, so no schema filter. `plpgsql` is left out: every database has it, `create
+ * extension` on it is a no-op, and a dump line that can never differ is noise in every app.
+ */
+export const extensionRows = (client: DbClient): Promise<readonly NameRow[]> =>
+  client.query<NameRow>(sql`select extname as name from pg_extension where extname <> 'plpgsql'`);
+
+export const enumRows = (client: DbClient, schema: string): Promise<readonly EnumRow[]> =>
+  client.query<EnumRow>(sql`
+    select t.typname as name, e.enumlabel as label, e.enumsortorder::float8 as position
+    from pg_enum e
+    join pg_type t on t.oid = e.enumtypid
+    join pg_namespace n on n.oid = t.typnamespace
+    where n.nspname = ${schema} and ${notExtensionOwned('pg_type', 't.oid')}
+  `);
+
+export const domainRows = (client: DbClient, schema: string): Promise<readonly DomainRow[]> =>
+  client.query<DomainRow>(sql`
+    select
+      t.typname as name,
+      format_type(t.typbasetype, t.typtypmod) as base_type,
+      t.typnotnull as not_null,
+      t.typdefault as expression
+    from pg_type t
+    join pg_namespace n on n.oid = t.typnamespace
+    where n.nspname = ${schema} and t.typtype = 'd' and ${notExtensionOwned('pg_type', 't.oid')}
+  `);
+
+export const domainCheckRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly DomainCheckRow[]> =>
+  client.query<DomainCheckRow>(sql`
+    select t.typname as domain_name, k.conname as name, pg_get_constraintdef(k.oid) as definition
+    from pg_constraint k
+    join pg_type t on t.oid = k.contypid
+    join pg_namespace n on n.oid = t.typnamespace
+    where n.nspname = ${schema} and k.contype = 'c'
+  `);
+
+/** The non-pretty `pg_get_viewdef`: the pretty form's line breaks follow a width, not the query. */
+export const viewRows = (client: DbClient, schema: string): Promise<readonly ViewRow[]> =>
+  client.query<ViewRow>(sql`
+    select
+      c.relname as name,
+      c.relkind as kind,
+      array_to_string(c.reloptions, ', ') as options,
+      pg_get_viewdef(c.oid) as definition
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and c.relkind in ('v', 'm')
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** Functions, procedures and window functions. An aggregate is refused by `pg_get_functiondef`. */
+export const functionRows = (client: DbClient, schema: string): Promise<readonly FunctionRow[]> =>
+  client.query<FunctionRow>(sql`
+    select
+      p.proname as name,
+      pg_get_function_identity_arguments(p.oid) as arguments,
+      pg_get_functiondef(p.oid) as definition
+    from pg_proc p
+    join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = ${schema}
+      and p.prokind in ('f', 'p', 'w')
+      and ${notExtensionOwned('pg_proc', 'p.oid')}
+  `);
+
+/**
+ * `not tgisinternal`: a foreign key's own enforcement triggers are the constraint's, not the app's.
+ * A trigger on an extension-owned table is skipped with its table: the dump creates no such table,
+ * so its `09_triggers/` file could never load.
+ */
+export const triggerRows = (client: DbClient, schema: string): Promise<readonly TriggerRow[]> =>
+  client.query<TriggerRow>(sql`
+    select
+      c.relname as table_name,
+      t.tgname as name,
+      pg_get_triggerdef(t.oid) as definition,
+      t.tgenabled as enabled
+    from pg_trigger t
+    join pg_class c on c.oid = t.tgrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and not t.tgisinternal
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/**
+ * 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,
+  schema: string,
+): Promise<readonly UnrenderedRow[]> =>
+  client.query<UnrenderedRow>(sql`
+    select kind, name, table_name from (
+      select
+        case
+          when c.relkind = 'p' then 'partitioned table'
+          when c.relkind = 'f' then 'foreign table'
+          when c.relkind = 'c' then 'composite type'
+          else 'partition or inheritance child'
+        end as kind,
+        c.relname as name,
+        null::text as table_name,
+        c.relnamespace as namespace
+      from pg_class c
+      where (
+          c.relkind in ('p', 'f', 'c')
+          or (c.relkind = 'r' and (
+            c.relispartition or exists (select 1 from pg_inherits h where h.inhrelid = c.oid)
+          ))
+        )
+        and ${notExtensionOwned('pg_class', 'c.oid')}
+      union all
+      select 'range type', t.typname, null::text, t.typnamespace
+      from pg_type t
+      where t.typtype = 'r' and ${notExtensionOwned('pg_type', 't.oid')}
+      union all
+      select 'aggregate', p.proname, null::text, p.pronamespace
+      from pg_proc p
+      where p.prokind = 'a' and ${notExtensionOwned('pg_proc', 'p.oid')}
+      union all
+      select 'row security policy', pol.polname, c.relname, c.relnamespace
+      from pg_policy pol
+      join pg_class c on c.oid = pol.polrelid
+      union all
+      select 'row security', c.relname, c.relname, c.relnamespace
+      from pg_class c
+      where c.relrowsecurity
+      union all
+      select 'rule', r.rulename, c.relname, c.relnamespace
+      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-relations.ts

@@ -0,0 +1,184 @@
+// Single responsibility: the catalog queries for what a TABLE is — the relation, its columns, its
+// constraints, its sequences and its indexes — as flat rows. Nothing here folds or sorts:
+// `introspect-catalog.ts` does, in JS, because `order by` on a name follows the server's collation
+// and two servers do not share one.
+
+import type { DbClient } from './client';
+import { raw, type SqlFragment, sql } from './sql';
+
+/**
+ * "No extension owns this object" — `pg_depend`'s `deptype = 'e'` row, the rule `app-relation.ts`
+ * already holds for relations, asked of whichever catalog the object lives in. Both arguments are
+ * literals at every call site, never data.
+ */
+export const notExtensionOwned = (
+  catalog: 'pg_class' | 'pg_type' | 'pg_proc',
+  oid: string,
+): SqlFragment =>
+  raw(
+    `not exists (select 1 from pg_depend e where e.classid = '${catalog}'::regclass ` +
+      `and e.objid = ${oid} and e.refclassid = 'pg_extension'::regclass and e.deptype = 'e')`,
+  );
+
+export interface TableRow {
+  readonly name: string;
+  readonly persistence: string;
+  readonly replica_identity: string;
+  readonly replica_index: string | null;
+  readonly options: string | null;
+}
+
+export interface ColumnRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly position: number;
+  readonly type: string;
+  readonly not_null: boolean;
+  readonly identity: string;
+  readonly generated: string;
+  readonly expression: string | null;
+  readonly collation: string | null;
+}
+
+export interface ConstraintRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly type: string;
+  readonly definition: string;
+}
+
+export interface SequenceRow {
+  readonly name: string;
+  readonly data_type: string;
+  readonly seq_start: string;
+  readonly seq_increment: string;
+  readonly seq_min: string;
+  readonly seq_max: string;
+  readonly seq_cache: string;
+  readonly seq_cycle: boolean;
+  /** `a` — a `serial` column owns it; `i` — an identity column does; `null` — nothing does. */
+  readonly ownership: string | null;
+  readonly owner_table: string | null;
+  readonly owner_column: string | null;
+}
+
+export interface IndexRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly definition: string;
+}
+
+/**
+ * Plain tables only. A partition, an inheritance child and a partitioned parent are `relkind`
+ * `r`/`p` rows a `create table (…)` cannot rebuild, so they are named by `unrenderedRows`
+ * (`catalog-objects.ts`) instead of rendered wrong here.
+ */
+export const tableRows = (client: DbClient, schema: string): Promise<readonly TableRow[]> =>
+  client.query<TableRow>(sql`
+    select
+      c.relname as name,
+      c.relpersistence as persistence,
+      c.relreplident as replica_identity,
+      (
+        select i.relname
+        from pg_index x
+        join pg_class i on i.oid = x.indexrelid
+        where x.indrelid = c.oid and x.indisreplident
+      ) as replica_index,
+      array_to_string(c.reloptions, ', ') as options
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and c.relkind = 'r'
+      and not c.relispartition
+      and not exists (select 1 from pg_inherits h where h.inhrelid = c.oid)
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** `format_type` and `pg_get_expr`, never `information_schema`: that view answers `ARRAY` and `USER-DEFINED`. */
+export const columnRows = (client: DbClient, schema: string): Promise<readonly ColumnRow[]> =>
+  client.query<ColumnRow>(sql`
+    select
+      c.relname as table_name,
+      a.attname as name,
+      a.attnum as position,
+      format_type(a.atttypid, a.atttypmod) as type,
+      a.attnotnull as not_null,
+      a.attidentity as identity,
+      a.attgenerated as generated,
+      pg_get_expr(d.adbin, d.adrelid) as expression,
+      case when a.attcollation <> t.typcollation then co.collname end as collation
+    from pg_attribute a
+    join pg_class c on c.oid = a.attrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    join pg_type t on t.oid = a.atttypid
+    left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
+    left join pg_collation co on co.oid = a.attcollation
+    where n.nspname = ${schema} and c.relkind = 'r' and a.attnum > 0 and not a.attisdropped
+  `);
+
+/**
+ * Every constraint a table carries, foreign keys included — the fold routes those to their own
+ * directory. `contype = 'n'` (a NOT NULL recorded as a constraint, Postgres 18) is left out: the
+ * column's own `not null` already says it, and reading it would make the dump differ by server.
+ */
+export const constraintRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly ConstraintRow[]> =>
+  client.query<ConstraintRow>(sql`
+    select
+      c.relname as table_name,
+      k.conname as name,
+      k.contype as type,
+      pg_get_constraintdef(k.oid) as definition
+    from pg_constraint k
+    join pg_class c on c.oid = k.conrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and k.contype in ('p', 'u', 'c', 'x', 'f')
+  `);
+
+/** `::text` on every bound: a `bigint` is a string on one driver and a number on the other. */
+export const sequenceRows = (client: DbClient, schema: string): Promise<readonly SequenceRow[]> =>
+  client.query<SequenceRow>(sql`
+    select
+      c.relname as name,
+      format_type(s.seqtypid, null) as data_type,
+      s.seqstart::text as seq_start,
+      s.seqincrement::text as seq_increment,
+      s.seqmin::text as seq_min,
+      s.seqmax::text as seq_max,
+      s.seqcache::text as seq_cache,
+      s.seqcycle as seq_cycle,
+      d.deptype as ownership,
+      t.relname as owner_table,
+      a.attname as owner_column
+    from pg_sequence s
+    join pg_class c on c.oid = s.seqrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    left join pg_depend d
+      on d.classid = 'pg_class'::regclass and d.objid = c.oid
+      and d.refclassid = 'pg_class'::regclass and d.deptype in ('a', 'i')
+    left join pg_class t on t.oid = d.refobjid
+    left join pg_attribute a on a.attrelid = d.refobjid and a.attnum = d.refobjsubid
+    where n.nspname = ${schema} and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** Indexes no constraint backs, on a table or a materialized view. */
+export const indexRows = (client: DbClient, schema: string): Promise<readonly IndexRow[]> =>
+  client.query<IndexRow>(sql`
+    select
+      t.relname as table_name,
+      i.relname as name,
+      pg_get_indexdef(x.indexrelid) as definition
+    from pg_index x
+    join pg_class i on i.oid = x.indexrelid
+    join pg_class t on t.oid = x.indrelid
+    join pg_namespace n on n.oid = t.relnamespace
+    where n.nspname = ${schema}
+      and t.relkind in ('r', 'm')
+      and not exists (
+        select 1 from pg_constraint k
+        where k.conindid = x.indexrelid and k.contype in ('p', 'u', 'x')
+      )
+  `);

package/src/catalog.ts

@@ -0,0 +1,174 @@
+// Single responsibility: the SHAPE of a whole schema as the catalog holds it — every object kind
+// the schema dump renders, in Postgres' own spelling. Distinct from `SchemaDescription`
+// (`introspect.ts`) on purpose: that one is the entity vocabulary a snapshot is diffed in, and a
+// catalog spelling can never compare equal to a generated one. This one is only ever compared to
+// itself, which is why it may carry `pg_get_*def` text verbatim.
+
+export interface CatalogExtension {
+  readonly name: string;
+}
+
+export interface CatalogEnum {
+  readonly kind: 'enum';
+  readonly name: string;
+  /** In `enumsortorder` — the order `create type … as enum` must repeat. */
+  readonly labels: readonly string[];
+}
+
+export interface CatalogConstraint {
+  readonly name: string;
+  /** `pg_get_constraintdef` verbatim: `CHECK ((x > 0))`, `PRIMARY KEY (id)`, `FOREIGN KEY …`. */
+  readonly definition: string;
+}
+
+export interface CatalogDomain {
+  readonly kind: 'domain';
+  readonly name: string;
+  readonly baseType: string;
+  readonly notNull: boolean;
+  readonly default: string | null;
+  readonly checks: readonly CatalogConstraint[];
+}
+
+export type CatalogType = CatalogEnum | CatalogDomain;
+
+/** Every option spelled, defaults included: a clause left out is a clause two servers may default apart. */
+export interface CatalogSequence {
+  readonly name: string;
+  readonly dataType: string;
+  readonly start: string;
+  readonly increment: string;
+  readonly min: string;
+  readonly max: string;
+  readonly cache: string;
+  readonly cycle: boolean;
+}
+
+/** A sequence a `serial` column owns: created before its table, tied to the column after. */
+export interface CatalogOwnedSequence extends CatalogSequence {
+  readonly column: string;
+}
+
+export interface CatalogColumn {
+  readonly name: string;
+  /** `format_type` — `character varying(120)`, `numeric(12,2)`, `timestamp with time zone`. */
+  readonly type: string;
+  readonly notNull: boolean;
+  /** `pg_get_expr` of the default; `null` when there is none or the column is generated. */
+  readonly default: 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';
+    readonly sequence: CatalogSequence;
+  } | null;
+  /** Only when it differs from the type's own collation. */
+  readonly collation: string | null;
+}
+
+export type CatalogReplicaIdentity =
+  | { readonly kind: 'default' | 'full' | 'nothing' }
+  | { readonly kind: 'index'; readonly index: string };
+
+export interface CatalogTable {
+  readonly name: string;
+  readonly unlogged: boolean;
+  /** `reloptions` joined — `fillfactor=70` — or `null`. */
+  readonly options: string | null;
+  /** In `attnum` order. */
+  readonly columns: readonly CatalogColumn[];
+  /** Primary key, unique, check and exclusion constraints — never a foreign key. */
+  readonly constraints: readonly CatalogConstraint[];
+  readonly sequences: readonly CatalogOwnedSequence[];
+  readonly replicaIdentity: CatalogReplicaIdentity;
+}
+
+/** An index no constraint backs; a constraint's own index is created by the constraint. */
+export interface CatalogIndex {
+  /** The relation it is on — a table, or a materialized view. */
+  readonly table: string;
+  readonly name: string;
+  /** `pg_get_indexdef` verbatim. */
+  readonly definition: string;
+}
+
+export interface CatalogForeignKey extends CatalogConstraint {
+  readonly table: string;
+}
+
+export interface CatalogView {
+  readonly name: string;
+  readonly materialized: boolean;
+  readonly options: string | null;
+  /** `pg_get_viewdef` verbatim, trailing `;` and all. */
+  readonly definition: string;
+}
+
+export interface CatalogFunction {
+  readonly name: string;
+  /** `pg_get_function_identity_arguments` — what tells two overloads apart. */
+  readonly arguments: string;
+  /** `pg_get_functiondef` verbatim. */
+  readonly definition: string;
+}
+
+export interface CatalogTrigger {
+  readonly table: string;
+  readonly name: string;
+  /** `pg_get_triggerdef` verbatim. */
+  readonly definition: string;
+  /** `tgenabled`: `O` origin (the default), `D` disabled, `R` replica, `A` always. */
+  readonly enabled: string;
+}
+
+/**
+ * An object in the schema that the dump has no statement for. Named rather than dropped: a dump
+ * that silently omitted a row-security policy would load into a database that is not the one the
+ * migrations build, and the load-equals-replay check could not see it, because both sides of that
+ * comparison would be blind in the same place.
+ */
+export interface CatalogUnrendered {
+  readonly kind: string;
+  readonly name: string;
+  /** The table it hangs off, when it has one. */
+  readonly table: string | null;
+}
+
+export interface CatalogDescription {
+  readonly schema: string;
+  readonly extensions: readonly CatalogExtension[];
+  readonly types: readonly CatalogType[];
+  /** Sequences no column owns. */
+  readonly sequences: readonly CatalogSequence[];
+  readonly tables: readonly CatalogTable[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly foreignKeys: readonly CatalogForeignKey[];
+  readonly views: readonly CatalogView[];
+  readonly functions: readonly CatalogFunction[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly unrendered: readonly CatalogUnrendered[];
+}
+
+/** Every list empty — the base a test or a caller spreads its one interesting object over. */
+export const emptyCatalog = (schema = 'public'): CatalogDescription => ({
+  schema,
+  extensions: [],
+  types: [],
+  sequences: [],
+  tables: [],
+  indexes: [],
+  foreignKeys: [],
+  views: [],
+  functions: [],
+  triggers: [],
+  unrendered: [],
+});