@ultimat3/db 22.15.0 → 23.0.0

package/src/pglite.ts

@@ -7,8 +7,24 @@ import { statementAttribution } from './attribution';
 import type { DbClient, DbConnection, ReservableClient } from './client';
 import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
+import {
+  assertListenChannel,
+  type DbSubscription,
+  type ListeningClient,
+  listenUnsupported,
+} from './listen';
 import { statementObserver } from './observe';
 import { PGLITE_INSTANT_PARSERS } from './pg-instant';
+import { linkPgliteExtensions, type PgliteExtensionLoader } from './pglite-extensions';
+import { PGLITE_PACKAGE } from './pglite-package';
+import {
+  discardSnapshot,
+  pgliteVersion,
+  readSnapshot,
+  snapshotFile,
+  snapshotKey,
+  writeSnapshot,
+} from './pglite-snapshot';
 import { createTurnQueue } from './pglite-turns';
 import type { SqlFragment } from './sql';
 import { statementExcerpt } from './statement-excerpt';
@@ -26,6 +42,10 @@ export interface PgliteResult {
 export interface PgliteDriver {
   query(text: string, values?: readonly unknown[]): Promise<PgliteResult>;
   exec?(text: string): Promise<unknown>;
+  /** `LISTEN` on the one session there is. Resolves to the unsubscribe. */
+  listen?(channel: string, callback: (payload: string) => void): Promise<() => Promise<void>>;
+  /** The whole data directory as one tarball — what `pglite-snapshot.ts` caches. */
+  dumpDataDir?(compression: 'none'): Promise<Blob>;
   close(): Promise<void>;
 }
 
@@ -33,7 +53,13 @@ export interface PgliteDriver {
 export interface PgliteModule {
   readonly PGlite: new (
     dataDir?: string,
-    options?: { readonly parsers?: Readonly<Record<number, (text: string) => unknown>> },
+    options?: {
+      readonly parsers?: Readonly<Record<number, (text: string) => unknown>>;
+      /** Keyed by the bundle's own export name; each value is opaque to this package. */
+      readonly extensions?: Readonly<Record<string, unknown>>;
+      /** A `dumpDataDir()` tarball to start from instead of running `initdb`. */
+      readonly loadDataDir?: Blob;
+    },
   ) => PgliteDriver;
 }
 
@@ -47,6 +73,24 @@ export interface PgliteOptions {
   readonly driver?: PgliteDriver | undefined;
   /** Swap the module loader. Tests use it; nothing in the framework does. */
   readonly load?: PgliteLoader | undefined;
+  /**
+   * Extensions to make available to `create extension`, by their Postgres names (`citext`,
+   * `uuid-ossp`). PGlite links an extension only when it is handed over at boot, so a migration
+   * that creates one fails on an instance that was not told. A function, for a caller whose list
+   * is read from disk: a client is constructed synchronously and boots on its first statement.
+   * A name PGlite ships no bundle for is skipped here and refused by the server at
+   * `create extension`, in its own words (`pglite-extensions.ts`).
+   */
+  readonly extensions?: readonly string[] | (() => Promise<readonly string[]>) | undefined;
+  /** Swap the extension bundle loader, by module specifier. Tests use it. */
+  readonly loadExtension?: PgliteExtensionLoader | undefined;
+  /**
+   * A directory to keep the post-`initdb` snapshot in, so an in-memory boot is a restore
+   * (`pglite-snapshot.ts`). Read only for `memory://`: a directory on disk is its own snapshot.
+   */
+  readonly snapshotDir?: string | undefined;
+  /** Swap how the installed PGlite version is read. Tests use it; `undefined` disables caching. */
+  readonly version?: (() => Promise<string | undefined>) | undefined;
 }
 
 export const PGLITE_FIX =
@@ -57,13 +101,9 @@ export const PGLITE_MEMORY = 'memory://';
 
 const PGLITE_URL = 'pglite://';
 
-/**
- * The optional peer's specifier. Exported because `x doctor` asks whether it RESOLVES — a resolve,
- * never an import, since loading it boots the WASM build and takes the single-writer lock — and a
- * diagnostic that spelled the package name a second time is a diagnostic that can name the wrong
- * one after a rename.
- */
-export const PGLITE_PACKAGE = '@electric-sql/pglite';
+// Re-exported: `src/index.ts` and `x doctor` read it from here, and the constant itself lives in
+// a leaf so the extension linker and the snapshot cache can share it without a cycle.
+export { PGLITE_PACKAGE };
 
 /**
  * Why there is no embedded database when that specifier does not resolve. One sentence, shared:
@@ -99,6 +139,38 @@ function pgliteConstructor(loaded: unknown): PgliteModule['PGlite'] {
   return exported as PgliteModule['PGlite'];
 }
 
+type PgliteConstructor = PgliteModule['PGlite'];
+
+/**
+ * A scratch boot from the cache, or `undefined` when there is nothing sound to restore from. The
+ * restored instance is asked one statement before it is believed: a tarball can verify against
+ * its checksum and still be one this build cannot open, and that must cost a rebuild, never a
+ * failed command.
+ */
+async function restore(
+  PGlite: PgliteConstructor,
+  base: { readonly extensions?: Readonly<Record<string, unknown>> },
+  file: string,
+  key: string,
+): Promise<PgliteDriver | undefined> {
+  const snapshot = await readSnapshot(file, key);
+  if (snapshot === undefined) return undefined;
+  let driver: PgliteDriver | undefined;
+  try {
+    driver = new PGlite(PGLITE_MEMORY, {
+      parsers: PGLITE_INSTANT_PARSERS,
+      ...base,
+      loadDataDir: snapshot,
+    });
+    await driver.query('select 1');
+    return driver;
+  } catch {
+    await driver?.close().catch(() => undefined);
+    await discardSnapshot(file, key);
+    return undefined;
+  }
+}
+
 /** Boots one embedded Postgres. Costs seconds — `createPgliteClient` calls it exactly once. */
 export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<PgliteDriver> {
   if (options.driver !== undefined) return options.driver;
@@ -110,13 +182,45 @@ export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<Pgl
     throw missing(PGLITE_MISSING, error);
   }
   const PGlite = pgliteConstructor(loaded);
+  const names =
+    typeof options.extensions === 'function' ? await options.extensions() : options.extensions;
+  const { linked } = await linkPgliteExtensions(names ?? [], options.loadExtension);
+  // Absent, never `{}`: every boot that names no extension hands PGlite exactly what it did.
+  const base = Object.keys(linked).length === 0 ? {} : { extensions: linked };
+  const version =
+    options.snapshotDir === undefined || dataDir !== PGLITE_MEMORY
+      ? undefined
+      : await (options.version ?? pgliteVersion)();
+  const key = version === undefined ? undefined : snapshotKey(version);
+  const file =
+    key === undefined || options.snapshotDir === undefined
+      ? undefined
+      : snapshotFile(options.snapshotDir, key);
+  if (file !== undefined && key !== undefined) {
+    const restored = await restore(PGlite, base, file, key);
+    if (restored !== undefined) return restored;
+  }
+  let driver: PgliteDriver;
   try {
     // `pg-instant.ts` reads every timestamp: PGlite's own parser took year 0099 for 1999 and an
     // offset with seconds for Invalid Date under any session zone that is not UTC.
-    return new PGlite(dataDir, { parsers: PGLITE_INSTANT_PARSERS });
+    driver = new PGlite(dataDir, { parsers: PGLITE_INSTANT_PARSERS, ...base });
   } catch (error) {
     throw missing(`PGlite could not open its data directory (dataDir=${dataDir})`, error);
   }
+  // Taken before the caller's first statement, so what is cached is `initdb`'s output and nothing
+  // of the caller's. A dump that fails leaves no cache and a working database.
+  if (file !== undefined && key !== undefined && driver.dumpDataDir !== undefined) {
+    try {
+      // Uncompressed, by measurement: gzip costs the boot that WRITES the snapshot ~0.3 s of
+      // CPU and saves nothing on the one that reads it. A fresh CI checkout always writes, so
+      // the cache must cost a cold boot nothing; the price is ~40 MB under `.x/cache`.
+      await writeSnapshot(file, key, await driver.dumpDataDir('none'));
+    } catch {
+      // The boot stands; the next one runs `initdb` again.
+    }
+  }
+  return driver;
 }
 
 /**
@@ -124,7 +228,7 @@ export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<Pgl
  * both pin a connection before they `BEGIN`, and a client that cannot be pinned silently gets a
  * shared one — which on a single-session database is every concurrent transaction at once.
  */
-export interface PgliteClient extends ReservableClient {
+export interface PgliteClient extends ReservableClient, ListeningClient {
   /** Pay the boot up front. `x dev` calls it so the first request is not the slow one. */
   ping(): Promise<void>;
   close(): Promise<void>;
@@ -287,6 +391,25 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
       issued.add(connection);
       return connection;
     },
+    async listen(channel, onNotify, onListening): Promise<DbSubscription> {
+      assertListenChannel(channel);
+      const driver = await connect();
+      const subscribe = driver.listen?.bind(driver);
+      if (subscribe === undefined) throw listenUnsupported('this PGlite driver');
+      // A turn of its own: the `LISTEN` is a statement on the one session, and issued beside an
+      // open transaction it would ride inside it — rolled back with it, and nothing delivered.
+      const stop = await turns.run(() => subscribe(channel, onNotify));
+      // One session and no socket to lose: established once, for the life of the client.
+      onListening?.();
+      let ended: Promise<void> | undefined;
+      return {
+        unlisten: () => {
+          // After `close()` the session is gone and so is the subscription: nothing to report.
+          ended ??= turns.run(() => stop()).catch(() => undefined);
+          return ended;
+        },
+      };
+    },
     async ping(): Promise<void> {
       await connect();
     },

package/src/pool-gauge.ts

@@ -0,0 +1,70 @@
+// Single responsibility: how much of its Postgres pools this process is asking for, as three
+// series. `Bun.SQL` publishes no occupancy — no open, idle or queued count — so this counts DEMAND
+// at the one place every statement and every pin passes (`client.ts`) and derives the rest: a
+// statement or a pin beyond `max` is waiting for a connection, by the pool's own rule.
+
+import { gauge } from '@ultimat3/core';
+
+/** One pool's ceiling and the units of work currently asking it for a connection. */
+export interface PoolDemand {
+  /** A statement was sent, or a pin was asked for. */
+  enter(): void;
+  /** That statement settled, or that pin came back. */
+  leave(): void;
+  /** The pool closed: it stops counting toward the totals until it is asked again. */
+  close(): void;
+}
+
+interface Tracked {
+  readonly max: number;
+  demand: number;
+}
+
+const pools = new Set<Tracked>();
+let declared = false;
+
+const total = (pick: (pool: Tracked) => number) => (): number => {
+  let sum = 0;
+  for (const pool of pools) sum += pick(pool);
+  return sum;
+};
+
+/** On the first tracked pool, never at import: a process that opens no pool declares no series. */
+function declare(): void {
+  if (declared) return;
+  declared = true;
+  gauge('db_pool_max', {
+    unit: '{connection}',
+    description: 'Connections this process may open, summed over its pools',
+    observe: total((pool) => pool.max),
+  });
+  gauge('db_pool_in_use', {
+    unit: '{connection}',
+    description: 'Connections running a statement or pinned by a transaction',
+    observe: total((pool) => Math.min(pool.demand, pool.max)),
+  });
+  gauge('db_pool_waiting', {
+    unit: '{statement}',
+    description: 'Statements and pins queued for a connection because the pool is at its ceiling',
+    observe: total((pool) => Math.max(0, pool.demand - pool.max)),
+  });
+}
+
+/** One pool's counter. Registered on its first use, so a client nobody queries counts for nothing. */
+export function trackPool(max: number): PoolDemand {
+  const pool: Tracked = { max, demand: 0 };
+  return {
+    enter(): void {
+      declare();
+      pools.add(pool);
+      pool.demand += 1;
+    },
+    leave(): void {
+      // Floored: a second `leave` for one `enter` must not hide a later statement.
+      pool.demand = Math.max(0, pool.demand - 1);
+    },
+    close(): void {
+      pools.delete(pool);
+    },
+  };
+}

package/src/schema-dump-entry.ts

@@ -0,0 +1,39 @@
+// `@ultimat3/db/schema-dump`: the whole schema as files, and the drift checks over them. Its own
+// entry because only three callers ever run it — `x db gen`, `x db migrate` and the gate's `drift`
+// step — while `@ultimat3/db` is imported by every role of every app: on the barrel these ten
+// modules were evaluated by every web, worker and scheduler pod to serve nothing.
+
+export type {
+  CatalogColumn,
+  CatalogConstraint,
+  CatalogDescription,
+  CatalogDomain,
+  CatalogEnum,
+  CatalogExtension,
+  CatalogForeignKey,
+  CatalogFunction,
+  CatalogIndex,
+  CatalogOwnedSequence,
+  CatalogReplicaIdentity,
+  CatalogSequence,
+  CatalogTable,
+  CatalogTrigger,
+  CatalogType,
+  CatalogUnrendered,
+  CatalogView,
+} from './catalog';
+export { emptyCatalog } from './catalog';
+export type { SchemaDumpDifference, SchemaDumpDifferenceKind } from './dump-drift';
+export {
+  compareSchemaDump,
+  reloadDifferences,
+  schemaDumpDifferenceOf,
+  schemaDumpDrift,
+} from './dump-drift';
+export type { IntrospectCatalogOptions } from './introspect-catalog';
+export { introspectCatalog } from './introspect-catalog';
+export { unexpectedObjects } from './object-drift';
+export type { SchemaDumpFile } from './schema-dump';
+export { renderSchemaDump } from './schema-dump';
+export type { LoadSchemaDumpOptions, SchemaLoadReport } from './schema-load';
+export { loadSchemaDump } from './schema-load';

package/src/schema-dump-table.ts

@@ -0,0 +1,72 @@
+// Single responsibility: one table as the statements that rebuild it — its `serial` sequences, the
+// `create table`, the ownership that ties each sequence back, and its replica identity. Split from
+// `schema-dump.ts`, which decides which file a statement goes to and never how a table is spelled.
+
+import type { CatalogColumn, CatalogConstraint, CatalogSequence, CatalogTable } from './catalog';
+
+/**
+ * Every catalog name, quoted — `identifier()` (`sql.ts`) refuses whitespace and `"`, which are
+ * legal in a name a migration created, and a dump that threw on one could not describe the
+ * database it was pointed at. Doubling the quote is the whole of Postgres' identifier escape.
+ */
+export const quoted = (name: string): string => `"${name.replaceAll('"', '""')}"`;
+
+/** Each option spelled, `no cycle` included, so the statement reads the same on every server. */
+export const sequenceOptions = (sequence: CatalogSequence): string =>
+  [
+    `start with ${sequence.start}`,
+    `increment by ${sequence.increment}`,
+    `minvalue ${sequence.min}`,
+    `maxvalue ${sequence.max}`,
+    `cache ${sequence.cache}`,
+    sequence.cycle ? 'cycle' : 'no cycle',
+  ].join(' ');
+
+export const createSequence = (sequence: CatalogSequence): string =>
+  `create sequence ${quoted(sequence.name)} as ${sequence.dataType} ${sequenceOptions(sequence)};`;
+
+/** `constraint "name" <definition>` — the definition is `pg_get_constraintdef`'s, verbatim. */
+export const constraintClause = (constraint: CatalogConstraint): string =>
+  `constraint ${quoted(constraint.name)} ${constraint.definition}`;
+
+/** Type, collation, then value (default, generation or identity), then nullability — one order. */
+function columnClause(column: CatalogColumn): string {
+  const parts = [quoted(column.name), column.type];
+  if (column.collation !== null) parts.push(`collate ${quoted(column.collation)}`);
+  if (column.default !== null) parts.push(`default ${column.default}`);
+  if (column.generated !== null) parts.push(`generated always as (${column.generated}) stored`);
+  if (column.identity !== null) {
+    const { mode, sequence } = column.identity;
+    parts.push(
+      `generated ${mode} as identity (sequence name ${quoted(sequence.name)} ${sequenceOptions(sequence)})`,
+    );
+  }
+  if (column.notNull) parts.push('not null');
+  return parts.join(' ');
+}
+
+/**
+ * The statements of one table, in the order they must run: a `serial` column's default names its
+ * sequence, so the sequence comes first and is handed to the column only once the table exists.
+ */
+export function tableStatements(table: CatalogTable): readonly string[] {
+  const name = quoted(table.name);
+  const body = [...table.columns.map(columnClause), ...table.constraints.map(constraintClause)].map(
+    (line) => `  ${line}`,
+  );
+  const head = table.unlogged ? 'create unlogged table' : 'create table';
+  const tail = table.options === null ? ');' : `) with (${table.options});`;
+  const statements = [
+    ...table.sequences.map(createSequence),
+    [`${head} ${name} (`, body.join(',\n'), tail].join('\n'),
+    ...table.sequences.map(
+      (sequence) =>
+        `alter sequence ${quoted(sequence.name)} owned by ${name}.${quoted(sequence.column)};`,
+    ),
+  ];
+  // `index` waits for the indexes file: the index it names does not exist yet.
+  if (table.replicaIdentity.kind === 'full' || table.replicaIdentity.kind === 'nothing') {
+    statements.push(`alter table ${name} replica identity ${table.replicaIdentity.kind};`);
+  }
+  return statements;
+}

package/src/schema-dump.ts

@@ -0,0 +1,192 @@
+// Single responsibility: a `CatalogDescription` as files — the schema dump. Pure: the same catalog
+// is the same bytes, so the gate can compare what is committed with what the migrations produce.
+// It decides which file a statement belongs to; `schema-dump-table.ts` spells a table, and every
+// other object is the catalog's own `pg_get_*def` text with a terminator.
+
+import type { CatalogDescription, CatalogType } from './catalog';
+import { FRAMEWORK_TABLE_PREFIX } from './drift';
+import { constraintClause, createSequence, quoted, tableStatements } from './schema-dump-table';
+import { literal } from './sql';
+
+export interface SchemaDumpFile {
+  /** Relative to the dump directory, POSIX: `04_tables/posts.sql`, `framework/04_tables/x_jobs.sql`. */
+  readonly path: string;
+  readonly content: string;
+}
+
+/** One directory per object kind, numbered in the order a database can be built in. */
+export const SCHEMA_DUMP_KINDS = [
+  '01_extensions',
+  '02_types',
+  '03_sequences',
+  '04_tables',
+  '05_indexes',
+  '06_foreign_keys',
+  '07_views',
+  '08_functions',
+  '09_triggers',
+] as const;
+
+export type SchemaDumpKind = (typeof SCHEMA_DUMP_KINDS)[number];
+
+/** The framework's own tables (`x_jobs`, `x_migrations`, …) live under a twin of the same layout. */
+export const FRAMEWORK_DUMP_DIR = 'framework';
+
+/** What the dump could not spell — comments only, so it loads as nothing. */
+export const UNRENDERED_DUMP_FILE = 'unrendered.sql';
+
+/** The ceiling the `filesize` step holds for source. A longer file is split, never exempted. */
+export const SCHEMA_DUMP_MAX_LINES = 500;
+
+export const SCHEMA_DUMP_HEADER =
+  '-- generated by `x db gen` from the migrations; never edited by hand (X_SCHEMA_DUMP_DRIFT)';
+
+/**
+ * A name as a file name: anything outside `[A-Za-z0-9_-]` becomes `%XX` per UTF-8 byte. A `.` is
+ * encoded too, which is what makes the `.<n>.sql` suffix of a split file unambiguous.
+ */
+export function dumpFileName(name: string): string {
+  return [...new TextEncoder().encode(name)]
+    .map((byte) => {
+      const char = String.fromCharCode(byte);
+      return /[A-Za-z0-9_-]/.test(char)
+        ? char
+        : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    })
+    .join('');
+}
+
+/** The `x_` rule `appTables()` already holds: the owner (a table, else the object) decides the twin. */
+const twinOf = (owner: string): string =>
+  owner.startsWith(FRAMEWORK_TABLE_PREFIX) ? `${FRAMEWORK_DUMP_DIR}/` : '';
+
+function typeStatement(type: CatalogType): string {
+  if (type.kind === 'enum') {
+    const labels = type.labels.map((label) => literal(label).text).join(', ');
+    return `create type ${quoted(type.name)} as enum (${labels});`;
+  }
+  const clauses = [`create domain ${quoted(type.name)} as ${type.baseType}`];
+  if (type.default !== null) clauses.push(`default ${type.default}`);
+  if (type.notNull) clauses.push('not null');
+  clauses.push(...type.checks.map(constraintClause));
+  return `${clauses.join(' ')};`;
+}
+
+/** `pg_get_*def` text with exactly one terminator, whether or not the catalog wrote one. */
+const terminated = (definition: string): string => `${definition.trim().replace(/;$/, '')};`;
+
+const TRIGGER_STATE: ReadonlyMap<string, string> = new Map([
+  ['D', 'disable trigger'],
+  ['R', 'enable replica trigger'],
+  ['A', 'enable always trigger'],
+]);
+
+/** Statements per file path, in insertion order within a file. */
+class Buckets {
+  private readonly files = new Map<string, string[]>();
+
+  add(kind: SchemaDumpKind, owner: string, file: string, ...statements: readonly string[]): void {
+    const path = `${twinOf(owner)}${kind}/${dumpFileName(file)}`;
+    const bucket = this.files.get(path) ?? [];
+    bucket.push(...statements);
+    this.files.set(path, bucket);
+  }
+
+  entries(): readonly (readonly [string, readonly string[]])[] {
+    return [...this.files.entries()];
+  }
+}
+
+function collect(catalog: CatalogDescription): Buckets {
+  const out = new Buckets();
+  const materialized = new Set(catalog.views.filter((v) => v.materialized).map((v) => v.name));
+  for (const extension of catalog.extensions) {
+    const statement = `create extension if not exists ${quoted(extension.name)};`;
+    out.add('01_extensions', extension.name, extension.name, statement);
+  }
+  for (const type of catalog.types) out.add('02_types', type.name, type.name, typeStatement(type));
+  for (const sequence of catalog.sequences) {
+    out.add('03_sequences', sequence.name, sequence.name, createSequence(sequence));
+  }
+  for (const table of catalog.tables) {
+    out.add('04_tables', table.name, table.name, ...tableStatements(table));
+  }
+  for (const view of catalog.views) {
+    const head = view.materialized ? 'create materialized view' : 'create view';
+    const options = view.options === null ? '' : ` with (${view.options})`;
+    const statement = `${head} ${quoted(view.name)}${options} as\n${terminated(view.definition)}`;
+    out.add('07_views', view.name, view.name, statement);
+  }
+  for (const index of catalog.indexes) {
+    // A materialized view's index rides in the view's own file: the view is built in a later
+    // directory than `05_indexes`, so an index filed there would name a relation not yet created.
+    const kind = materialized.has(index.table) ? '07_views' : '05_indexes';
+    out.add(kind, index.table, index.table, terminated(index.definition));
+  }
+  for (const table of catalog.tables) {
+    if (table.replicaIdentity.kind !== 'index') continue;
+    const using = `replica identity using index ${quoted(table.replicaIdentity.index)}`;
+    out.add('05_indexes', table.name, table.name, `alter table ${quoted(table.name)} ${using};`);
+  }
+  for (const key of catalog.foreignKeys) {
+    const statement = `alter table ${quoted(key.table)} add ${constraintClause(key)};`;
+    out.add('06_foreign_keys', key.table, key.table, statement);
+  }
+  for (const fn of catalog.functions) {
+    out.add('08_functions', fn.name, fn.name, terminated(fn.definition));
+  }
+  for (const trigger of catalog.triggers) {
+    const state = TRIGGER_STATE.get(trigger.enabled);
+    const on = quoted(trigger.table);
+    out.add('09_triggers', trigger.table, trigger.table, terminated(trigger.definition));
+    if (state !== undefined) {
+      const statement = `alter table ${on} ${state} ${quoted(trigger.name)};`;
+      out.add('09_triggers', trigger.table, trigger.table, statement);
+    }
+  }
+  return out;
+}
+
+/** One file, or `<name>.1.sql`, `<name>.2.sql`, … when it would pass the ceiling. */
+function split(path: string, content: string): readonly SchemaDumpFile[] {
+  // The trailing newline is the file's terminator, not a line of its own.
+  const lines = content.replace(/\n$/, '').split('\n');
+  if (lines.length <= SCHEMA_DUMP_MAX_LINES) return [{ path: `${path}.sql`, content }];
+  const parts: SchemaDumpFile[] = [];
+  for (let at = 0; at < lines.length; at += SCHEMA_DUMP_MAX_LINES) {
+    const chunk = lines.slice(at, at + SCHEMA_DUMP_MAX_LINES).join('\n');
+    parts.push({ path: `${path}.${parts.length + 1}.sql`, content: `${chunk}\n` });
+  }
+  return parts;
+}
+
+function unrenderedFiles(catalog: CatalogDescription): readonly SchemaDumpFile[] {
+  const twins = new Map<string, string[]>();
+  for (const object of catalog.unrendered) {
+    const twin = twinOf(object.table ?? object.name);
+    const on = object.table === null ? '' : ` on ${quoted(object.table)}`;
+    const lines = twins.get(twin) ?? [];
+    lines.push(`-- not rendered: ${object.kind} ${quoted(object.name)}${on}`);
+    twins.set(twin, lines);
+  }
+  return [...twins.entries()].map(([twin, lines]) => ({
+    path: `${twin}${UNRENDERED_DUMP_FILE}`,
+    content: `${SCHEMA_DUMP_HEADER}\n\n${lines.join('\n')}\n`,
+  }));
+}
+
+/**
+ * The whole dump, sorted by path. Deterministic by construction: the catalog arrives sorted
+ * (`introspectCatalog`), nothing here reads a clock, a version or an owner, and every file ends
+ * in exactly one newline.
+ */
+export function renderSchemaDump(catalog: CatalogDescription): readonly SchemaDumpFile[] {
+  const files = collect(catalog)
+    .entries()
+    .flatMap(([path, statements]) =>
+      split(path, `${SCHEMA_DUMP_HEADER}\n\n${statements.join('\n\n')}\n`),
+    );
+  return [...files, ...unrenderedFiles(catalog)].sort((a, b) =>
+    a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+  );
+}