@ultimat3/db 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -14,7 +14,7 @@ Tier 1 — it imports `@ultimat3/core` and nothing else. That placement is load-
 | SQLSTATE | one reader, `sqlState()` (`sqlstate.ts`). Never read `error.code` for a SQLSTATE |
 | Reading a caught value | `renderThrowable()` from core (`checkDb` backs `/readyz`) |
 | Errors | subclass `DbError`; never `throw new Error` in source. A test simulating a database failure throws `dbUnavailable()`; one simulating the caller's body failing throws a bare `Error` on purpose |
-| New code | add to `DB_ERROR_CODES` **and** `DB_ERROR_TITLES` in `errors.ts`, whichever file holds the constructor (`migration-errors.ts`, `invariant-errors.ts`, `drift-errors.ts`); `src/index.ts` re-exports all |
+| New code | `bun run new-error-code <CODE> --package db --title '…' --fix '…'` writes `DB_OWNED_ERROR_CODES`, `DB_ERROR_TITLES` and the wiki row together; then add it to `errors.test.ts`'s pinned list. The constructor lives where its imports allow (`migration-errors.ts`, `invariant-errors.ts`, `drift-errors.ts`, `dump-drift.ts`); `src/index.ts` re-exports all |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from core — never `new AsyncLocalStorage`. Three scopes: `transaction.ts`, `attribution.ts`, `expected-loop.ts` |
 | Exports | explicit in `src/index.ts`; no `export *` |
 | Files | < 200 LOC (the `packages/db/src/**/*.ts` path instruction), one responsibility, `kebab-case.ts`, test beside source |
@@ -58,7 +58,14 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   `drainTimeoutMs: 0` sends no option; the verdict is elapsed time on `performance.now()`
   (`X_DB_DRAIN_TIMEOUT`). `pool-drain.test.ts`, `pool-drain.live.test.ts`. `close()` clears the cached
   driver before awaiting the teardown.
+- **`client.listen` is ONE session beside the pool** (`listen.ts`; `Bun.SQL.listen`, PGlite's
+  `listen` under a turn), never a reserved pin. `onListening` fires on every re-dial; a channel is
+  refused unless it is a plain identifier. `listen.test.ts`, `listen.live.test.ts`.
 - `execute()` trusts the command tag only when `> 0`, in both drivers (`rowsOf`, `affectedBy`).
+- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND** —
+  `Bun.SQL` publishes no occupancy. `client.ts` is the one counter: `run()` from send to settle, a
+  pin from the ask to its (idempotent) release; a statement ON a pin is not counted again. Declared
+  on the first tracked pool, never at import. `pool-gauge.test.ts`.
 - **`client.ts` connects, holds the client and the ambient `db()`**, and opens no socket at import;
   `pool-profile.ts`, `connection-url.ts`, `bun-sql.ts`, `pool-reserve.ts`, `db-health.ts` (`checkDb`)
   and `statement-funnel.ts` (`sendOn`/`runOn`) hold the rest.
@@ -220,6 +227,37 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - `drift-findings.ts` holds every `DriftDifference` constructor and `DriftKind`; `drift.ts` keeps the
   comparisons.
 
+## The schema dump
+
+- **Its own entry: `@ultimat3/db/schema-dump`** (`schema-dump-entry.ts`). The barrel is in every
+  role's boot graph and must evaluate none of this family — `schema-dump-entry.test.ts`.
+- **Two readings of one catalog, never mixed.** `introspect()` → `SchemaDescription`, the entity
+  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries in `catalog-relations.ts` and
+  `catalog-objects.ts`; the pure fold in `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
+  itself. A catalog spelling on a `SchemaDescription` field is the `checks`/`checkNames` mistake.
+- **Sorted in JS** (`byCodeUnit`), never `order by` and never `localeCompare`: collations differ.
+- **`renderSchemaDump()` is pure**; `schema-dump-table.ts` spells one table. `quoted()` escapes any
+  catalog name — `identifier()` refuses whitespace and `"`, which a migration may have created.
+- **`x_` owner → `framework/` twin** (`FRAMEWORK_TABLE_PREFIX`). No list is handed in.
+- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`). A kind
+  rendered later leaves that list in the same diff. Never render a partition as a plain table.
+- **`loadSchemaDump()`**: one transaction, `check_function_bodies` off, a savepoint per file, and
+  only `42P01`/`42883`/`42704` are retried. Its refusal is `X_SCHEMA_DUMP_DRIFT` (`dump-drift.ts`).
+- **`object-drift.ts`**: `unexpectedObjects(live, expected)` compares IDENTITY (kind, table, name,
+  arguments). The live side is the operator's Postgres, the expected side a PGlite replay.
+- **No app path here.** Where the dump lives, which engine replays, and when it is written are
+  `@ultimat3/cli`'s (`db-schema-dump.ts`). `schema-load.contract.test.ts` reads the reference app's
+  migrations as text and runs on Postgres when `TEST_DATABASE_URL` is set.
+- **`pglite-extensions.ts` is the one linker** (`linkPgliteExtensions` → `{ linked, missing }`):
+  `contrib/<name>` then the package root; the name is data (read from migration text), screened
+  by `pgliteExtensionExport` before it reaches a specifier; `plpgsql` is built in, never missing.
+  Only a not-found import is `missing`; a bundle that throws is `X_DB_UNAVAILABLE`.
+- **`pglite-snapshot.ts`**: `snapshotDir` makes a `memory://` boot a restore. Key = PGlite version
+  (read off its `package.json`; unreadable = no cache), never the extension set. One file, checksum in its
+  header; unsound or unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed by
+  measurement: gzip taxes the boot that writes, and a CI checkout always writes.
+- **One embedded boot** serves every database-backed dump test: `schema-dump.test.ts`.
+
 ## Branches, replicas, read-only
 
 - **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`

package/README.md

@@ -51,6 +51,13 @@ await withTransaction(async (tx) => {
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
 | `introspect()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
+| `introspectCatalog()` / `CatalogDescription` / `emptyCatalog()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the WHOLE schema in the catalog's own spelling — extensions, enum and domain types, sequences, tables, indexes, foreign keys, views, functions, triggers — sorted in code-unit order, plus `unrendered`: what exists and the dump cannot spell. Comparable only to another reading of itself; `introspect()` stays the entity-vocabulary reading a snapshot is diffed in |
+| `renderSchemaDump()` / `SchemaDumpFile` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: a catalog → the schema dump's files. Pure and byte-deterministic. [The schema dump](#the-schema-dump) |
+| `loadSchemaDump()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: build a schema from those files, in one transaction, retrying a file that names something not created yet |
+| `compareSchemaDump()` / `reloadDifferences()` / `schemaDumpDrift()` / `schemaDumpDifferenceOf()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: `X_SCHEMA_DUMP_DRIFT` — committed files against rendered ones in both directions, and load-equals-replay as a comparison |
+| `unexpectedObjects()` | **`@ultimat3/db/schema-dump`.** `As of 2026-10`: the triggers, functions, views, types and sequences a live catalog holds and an expected one does not, as `unexpected-object` drift. Identity, never definition text |
+| `PgliteOptions.extensions` / `linkPgliteExtensions()` | `As of 2026-10`: Postgres extensions to link at boot, by name — a list, or a function for a caller whose list is read from disk. `linkPgliteExtensions(names)` answers `{ linked, missing }` without booting anything: `missing` is what the installed PGlite ships no bundle for, which is how `@ultimat3/cli` decides a replay needs a real Postgres. A missing name is skipped at boot and refused by `create extension` itself |
+| `PgliteOptions.snapshotDir` | `As of 2026-10`: a directory for the post-`initdb` snapshot, so an in-memory boot is a restore (~0.4 s against ~2.7 s). Keyed on the PGlite version alone — `initdb` never sees a linked extension, so one snapshot serves every set; checksummed, never trusted, written by temp-name-then-rename. Ignored for a data directory on disk |
 | `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases. `As of 2026-08-19` the marker comment records the **base** as well as the instant (`ultimate:branch:<base>:<iso>`, on `BranchInfo.base`), and `reapBranches()` sweeps only branches of the database it is connected to — one Postgres hosting two Ultimate apps used to mean one app's nightly reap dropped the other's branches. A pre-3.x marker records no base and is skipped, never dropped |
 | `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
@@ -231,6 +238,52 @@ the exit code — and a deploy that rolled on past a schema nobody can reconstru
 drift exists to catch. There is no `x db drift`, and `x verify`'s `drift` step is the *source*
 detector (`checkSourceDrift`), which needs no database and never calls this.
 
+## The schema dump
+
+**Imported from `@ultimat3/db/schema-dump`, never from the barrel** (23.0.0): `introspectCatalog`,
+`emptyCatalog`, the `Catalog*` types, `renderSchemaDump`, `loadSchemaDump`, `compareSchemaDump`,
+`reloadDifferences`, `schemaDumpDrift`, `schemaDumpDifferenceOf` and `unexpectedObjects`. Three
+callers run them — `x db gen`, `x db migrate`, the gate's `drift` step — and `@ultimat3/db` is in
+every role's boot graph, where these ten modules served nothing. `schema-dump-entry.test.ts` holds
+both halves: the barrel evaluates none of them, and no name has two homes.
+
+`renderSchemaDump(await introspectCatalog({ client }))` is the schema as files: one directory per
+object kind, numbered in the order a database is built in, one file per named object.
+
+| Directory | Holds |
+|---|---|
+| `01_extensions/` | `create extension if not exists` — never `plpgsql` |
+| `02_types/` | enums, domains |
+| `03_sequences/` | sequences no column owns |
+| `04_tables/` | the table; a `serial` column's sequence before it and its ownership after; `replica identity full` |
+| `05_indexes/` | per table, indexes no constraint backs; `replica identity using index` |
+| `06_foreign_keys/` | per table, `alter table … add constraint` |
+| `07_views/` | views; a materialized view with its indexes |
+| `08_functions/` | per name, overloads together |
+| `09_triggers/` | per table |
+
+- An object whose owner — its table, else itself — starts with `x_` goes to a `framework/` twin of
+  the same layout. The rule is `FRAMEWORK_TABLE_PREFIX`, the one `appTables()` already holds.
+- Postgres' own spellings (`format_type`, `pg_get_expr`, `pg_get_*def`), so a loaded dump renders
+  the same bytes. Sorted in JS, never by `order by`: a name's order follows the server's collation.
+- No timestamp, version, owner or grant. Every sequence option is written, defaults included.
+- A name becomes a file name with everything outside `[A-Za-z0-9_-]` percent-encoded.
+- A file over 500 lines (`SCHEMA_DUMP_MAX_LINES`, the `filesize` ceiling) is split `<name>.1.sql`, `<name>.2.sql`;
+  `loadSchemaDump()` joins the parts in numeric order.
+- What cannot be spelled — partitions, inheritance, foreign tables, composite and range types,
+  aggregates, row-security policies, rules — is named in `unrendered.sql` as comments.
+
+`loadSchemaDump()` runs kind by kind, the framework twin first, each file in a savepoint. A file
+refused with `42P01`, `42883` or `42704` — "not created yet" — is retried after the rest; a pass
+that loads nothing ends with `X_SCHEMA_DUMP_DRIFT` naming the file.
+
+**Not the snapshot.** `<id>.snapshot.json` is `x db gen`'s diff base, in the entity's vocabulary:
+both sides of that diff are generator spellings. The dump is what the database holds, in SQL:
+both sides of ITS comparison are catalog spellings. Neither can be compared with the other.
+
+Which engine, where the files live, when they are written and what holds them is `@ultimat3/cli`'s
+(`x db gen`, `x db migrate`, the `drift` step). This package renders, loads and compares.
+
 ## The embedded database
 
 No `DATABASE_URL` means no Docker: `createPgliteClient()` runs Postgres as WASM inside this
@@ -312,6 +365,33 @@ so nothing else would ever end that wait. `migrate()` emits it as `SET LOCAL loc
 each migration's own transaction — it reverts at COMMIT, so a DDL value never leaks onto the session
 the ledger insert runs on.
 
+## `LISTEN` on a session of its own
+
+A pooled statement cannot hold a subscription: the next one runs on another connection. Both
+clients hold ONE session beside the pool for it.
+
+```ts
+import { createPostgresClient } from '@ultimat3/db';
+
+const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const subscription = await client.listen(
+  'x_jobs_wake',
+  (payload) => console.log('notified', payload),
+  () => console.log('listening'), // again after every re-dial
+);
+await subscription.unlisten();
+```
+
+| Fact | Detail |
+|---|---|
+| the session | `Bun.SQL.listen` on the pooled client — outside `max`, untouched by `idleTimeout`, ended by `unlisten()` or `close()`; PGlite's own `listen` on the embedded one. Every channel a client listens on shares it |
+| `onListening` | fires each time the subscription is (re-)established. The driver re-dials a session that died, and what was notified in between is LOST — re-read the source of truth there |
+| the channel | a lower-case identifier of at most 63 characters, refused otherwise before a driver sees it |
+| a transaction-pooling proxy | `listen()` resolves and nothing is ever delivered. Only a notification that arrives proves the path |
+| `canListen(client)` | `true` for both shipped clients. `false` for a replicated pair — listen on the primary it was built from, as the boot does |
+
+`@ultimat3/jobs`' `startQueueWake` is the framework's one caller.
+
 ## Migrations
 
 `migrate()` takes the advisory lock by **polling** `pg_try_advisory_lock(4919202607)` every 500ms
@@ -424,6 +504,7 @@ job the moment Postgres fails over.
 | `X_MIGRATION_IRREVERSIBLE` | generated `down` would lose data |
 | `X_SQL_UNSAFE` | non-bindable interpolation, or an unsafe identifier/branch name |
 | `X_BRANCH_EXISTS` | branch database already exists (or is the connected one) |
+| `X_SCHEMA_DUMP_DRIFT` | the committed schema dump is not what the migrations produce, or does not load back |
 | `X_NOT_IMPLEMENTED` | branching an in-memory PGlite — a copy needs a directory |
 | `X_ENV_MISSING` | core's — `DATABASE_POOL_MAX` is set to something that is not a positive integer |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -14,11 +14,13 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./schema-dump": "./src/schema-dump-entry.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,7 +33,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.14.0"
+    "@ultimat3/core": "23.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/bun-sql.ts

@@ -58,6 +58,18 @@ export interface BunSqlDriver {
   unsafe(text: string, values?: readonly unknown[]): Promise<unknown>;
   reserve(): Promise<BunSqlReserved>;
   close(options?: { readonly timeout?: number }): Promise<void>;
+  /**
+   * `LISTEN` on a connection the driver opens for it, OUTSIDE the pool. Measured on Bun 1.4.0
+   * against Postgres 17: a `max: 1` pool still answers statements while it is held;
+   * `idleTimeout` does not close it; a backend killed under it is re-dialled by the driver, with
+   * its own growing gap between attempts, and `onlisten` fires again once it is back; `close()`
+   * and `unlisten()` both end the session. Optional because a fake driver has none.
+   */
+  listen?(
+    channel: string,
+    onnotify: (payload: string) => void,
+    onlisten?: () => void,
+  ): Promise<{ unlisten(): Promise<void> }>;
 }
 
 export type BunSqlFactory = new (

package/src/catalog-fold.ts

@@ -0,0 +1,113 @@
+// 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,
+    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,200 @@
+// 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.
+ */
+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'
+    ) objects
+    join pg_namespace n on n.oid = objects.namespace
+    where n.nspname = ${schema}
+  `);