@ultimat3/db 22.15.0 → 24.0.0

package/src/pglite.ts

@@ -4,11 +4,29 @@
 // that only ever talks to a managed Postgres must not carry 26 MB of WASM it will never load.
 
 import { statementAttribution } from './attribution';
+import { refuseUnsendable } from './bound-parameters';
 import type { DbClient, DbConnection, ReservableClient } from './client';
+import { refuseRolledBackCommit } from './commit-tag';
 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';
@@ -20,12 +38,18 @@ export interface PgliteResult {
   readonly rows: readonly unknown[];
   /** Postgres' command-tag count — the only truthful answer for INSERT/UPDATE/DELETE. */
   readonly affectedRows?: number | undefined;
+  /** The command tag's verb. `ROLLBACK` in answer to a `COMMIT` is how an aborted one reads. */
+  readonly command?: string | undefined;
 }
 
 /** The slice of PGlite we need. Declared structurally — this package has no dependencies. */
 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 +57,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 +77,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 +105,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 +143,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 +186,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 +232,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>;
@@ -162,8 +270,12 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
 
   /** The send itself: one statement on the session, every driver failure typed on the way out. */
   async function send(driver: PgliteDriver, fragment: SqlFragment): Promise<PgliteResult> {
+    // Above the `try`, as `sendOn` encodes above its own: a value this package refuses to send is
+    // not a driver failure.
+    refuseUnsendable(fragment.values);
+    let result: PgliteResult;
     try {
-      return await driver.query(fragment.text, fragment.values);
+      result = await driver.query(fragment.text, fragment.values);
     } catch (error) {
       // `driverError`, as `statement-funnel.ts` already does for Bun's driver: this site passed
       // every failure to `dbUnavailable`, so under `x dev` — which IS this driver when no
@@ -172,6 +284,10 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
       // answering fine (measured 2026-09-05). PGlite carries the SQLSTATE on `code`.
       throw driverError(statementExcerpt(fragment.text), error);
     }
+    // Outside the `try`, as `sendOn` does it: a COMMIT the server answered with ROLLBACK is a
+    // refusal of its own, and `driverError` would re-wrap it as unavailability.
+    refuseRolledBackCommit(fragment.text, result);
+    return result;
   }
 
   /**
@@ -287,6 +403,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/primary-key.ts

@@ -0,0 +1,180 @@
+// Single responsibility: a table's PRIMARY KEY as DDL — the two statements that move one, the
+// generator's arm that decides when they are due, and the refusal for a key another table still
+// points at. `diffTable` had no arm for it, so a changed `primaryKey` wrote no statement while the
+// snapshot beside it recorded the new key, and drift had no comparison to notice with.
+
+import { assert } from '@ultimat3/core';
+import { defaultExpression } from './column-default';
+import type { EntityDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import { isGenerated } from './generated-column';
+import type { SchemaDescription, TableDescription } from './introspect';
+import { MAX_IDENTIFIER_BYTES } from './invariant-ddl';
+import { migrationIrreversible } from './migration-errors';
+import { identifier } from './sql';
+
+/**
+ * `<table>_pkey` — what Postgres names the constraint an inline `primary key (…)` creates, which is
+ * how `createTable` has always written one. Written out by name on every `add` here, so the name a
+ * later migration drops is one a migration chose.
+ *
+ * Bounded in bytes: past 63 the server truncates the TABLE part to make room for `_pkey`, so the
+ * name it holds is no longer this string and a `drop constraint` built from it would miss.
+ */
+export function primaryKeyName(table: string): string {
+  const name = `${table}_pkey`;
+  const bytes = new TextEncoder().encode(name).length;
+  assert(
+    bytes <= MAX_IDENTIFIER_BYTES,
+    `primary key constraint "${name}" is ${bytes} bytes; Postgres truncates at ${MAX_IDENTIFIER_BYTES}, so the name the database holds is not this one`,
+    `psql "$DATABASE_URL" -c "select conname from pg_constraint where contype = 'p' and conrelid = '${table}'::regclass"   # then write the drop constraint / add primary key pair by hand in a new migration`,
+  );
+  return name;
+}
+
+export function addPrimaryKey(table: string, columns: readonly string[]): string {
+  const key = columns.map((column) => identifier(column).text).join(', ');
+  return (
+    `alter table ${identifier(table).text} add constraint ` +
+    `${identifier(primaryKeyName(table)).text} primary key (${key});`
+  );
+}
+
+/**
+ * `if exists` for the generator, and for a reason the server supplies: dropping a COLUMN drops
+ * every constraint written over it, so a key whose column this same migration removes — in either
+ * direction — may already be gone by the time this statement runs.
+ */
+export function dropPrimaryKey(table: string, constraint: string, ifExists: boolean): string {
+  return (
+    `alter table ${identifier(table).text} drop constraint ` +
+    `${ifExists ? 'if exists ' : ''}${identifier(constraint).text};`
+  );
+}
+
+/**
+ * Postgres marks every key column NOT NULL and dropping the key does not undo it (measured on 17),
+ * so a column the declaration allows NULL in needs the constraint taken off by name.
+ */
+const dropNotNull = (table: string, column: string): string =>
+  `alter table ${identifier(table).text} alter column ${identifier(column).text} drop not null;`;
+
+/**
+ * No default, or the default `null` — `.default(null)` renders that expression, and it fills an
+ * added column with exactly what no default does.
+ */
+const fillsNothing = (expression: string | null): boolean =>
+  expression === null || expression === 'null';
+
+/** Two column lists, equal in ORDER — the one copy; `drift.ts` compares the live key through it. */
+export const sameColumns = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((column, index) => column === b[index]);
+
+/** ORDER is part of a key: `(org_id, id)` and `(id, org_id)` are two different indexes. */
+export function keyChanged(entity: EntityDescriptionLike, live: TableDescription): boolean {
+  return !sameColumns(entity.primaryKey, live.primaryKey);
+}
+
+/**
+ * The recorded foreign keys written against the key being replaced. Postgres refuses to drop a
+ * constraint another one depends on (`2BP01`), and re-pointing someone else's key is not a diff
+ * this generator can derive: the referencing table's own columns would have to change with it.
+ */
+function inboundKeys(current: SchemaDescription, live: TableDescription): readonly string[] {
+  const key = new Set(live.primaryKey);
+  return current.tables.flatMap((table) =>
+    table.foreignKeys
+      .filter(
+        (foreign) =>
+          foreign.referencedTable === live.name &&
+          foreign.referencedColumns.length === key.size &&
+          foreign.referencedColumns.every((column) => key.has(column)),
+      )
+      .map((foreign) => foreign.name),
+  );
+}
+
+/**
+ * The first half, ahead of every column statement of the table: the old key goes. `down` is
+ * reversed at assembly, so the statement pushed here runs LAST on the way back — the old key is
+ * restored only once every column it names is back.
+ */
+export function dropChangedKey(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  current: SchemaDescription,
+  plan: Plan,
+  migration: string,
+): void {
+  if (!keyChanged(entity, live) || live.primaryKey.length === 0) return;
+  const inbound = inboundKeys(current, live);
+  if (inbound.length > 0) {
+    throw migrationIrreversible(
+      `changing the primary key of "${entity.table}" drops the constraint ${inbound.map((name) => `"${name}"`).join(', ')} ${inbound.length === 1 ? 'is' : 'are'} written against, and re-pointing another table's foreign key is not a change this generator can derive`,
+      `x db gen "${migration}"   # after removing the references() to "${entity.table}" behind ${inbound.join(', ')} — drop the keys in one migration, change the primary key in the next, restore them in a third`,
+    );
+  }
+  plan.up.push(dropPrimaryKey(entity.table, primaryKeyName(entity.table), true));
+  const declared = new Map(entity.columns.map((column) => [column.column, column]));
+  const kept = new Set(entity.primaryKey);
+  for (const name of live.primaryKey) {
+    // Leaving the key, still on the table, and declared nullable: the key's NOT NULL goes with it.
+    if (!kept.has(name) && declared.get(name)?.notNull === false) {
+      plan.up.push(dropNotNull(entity.table, name));
+    }
+  }
+  // A key column this migration DROPS comes back empty on the way down (`-- data is not
+  // restored`), and a primary key over NULLs cannot be added to a table holding a row. The
+  // statement is named as the follow-up rather than emitted as one that cannot apply — the form
+  // `diffTable` already uses for a NOT NULL add.
+  const restored = live.primaryKey.filter((name) => !declared.has(name));
+  const restore = addPrimaryKey(entity.table, live.primaryKey);
+  plan.down.push(
+    restored.length === 0
+      ? restore
+      : `-- backfill ${restored.map((name) => identifier(name).text).join(', ')}, then: ${restore}`,
+  );
+}
+
+/**
+ * The second half, after the table's last column statement — the `drop column`s included: every
+ * column the new key names exists by now, and none it no longer names is still in the way.
+ *
+ * Refused when the key names a column this same migration ADDS with nothing to fill it (no
+ * default, or the default `null`): `add
+ * column` lands NULL in every existing row and a primary key refuses a NULL, so the generated `up`
+ * could not apply to any table holding a row. A default or a generation expression fills it.
+ */
+export function addChangedKey(
+  entity: EntityDescriptionLike,
+  live: TableDescription,
+  plan: Plan,
+  migration: string,
+): void {
+  if (!keyChanged(entity, live) || entity.primaryKey.length === 0) return;
+  const recorded = new Map(live.columns.map((column) => [column.name, column]));
+  const empty = entity.columns.filter(
+    (column) =>
+      entity.primaryKey.includes(column.column) &&
+      !recorded.has(column.column) &&
+      !isGenerated(column) &&
+      fillsNothing(defaultExpression(column)),
+  );
+  if (empty.length > 0) {
+    const names = empty.map((column) => `"${column.column}"`).join(', ');
+    throw migrationIrreversible(
+      `the new primary key of "${entity.table}" names ${names}, which this same migration adds with no default that fills it: every existing row would hold NULL there, and a primary key cannot be added over a NULL`,
+      `x db gen "${migration}"   # with ${names} declared but left OUT of primaryKey — apply it, backfill the column, then put it in the key and run x db gen again`,
+    );
+  }
+  plan.up.push(addPrimaryKey(entity.table, entity.primaryKey));
+  const old = new Set(live.primaryKey);
+  for (const name of entity.primaryKey) {
+    // Pushed BEFORE the drop so it runs AFTER it on the way down: a column that was nullable
+    // before this migration keyed it is nullable again once the key is gone.
+    if (!old.has(name) && recorded.get(name)?.nullable === true) {
+      plan.down.push(dropNotNull(entity.table, name));
+    }
+  }
+  plan.down.push(dropPrimaryKey(entity.table, primaryKeyName(entity.table), true));
+}

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,75 @@
+// 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) {
+    const { expression, storage } = column.generated;
+    parts.push(`generated always as (${expression}) ${storage}`);
+  }
+  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;
+}