@ultimat3/db 29.4.0 → 30.1.0

package/src/migrate-rollback.ts

@@ -1,10 +1,16 @@
 // Single responsibility: recognise a ledger an OLDER build is being rolled back onto — rows the
-// newer build applied, every one of them newer than anything this build ships — so the migrate
-// role lets a rollback through instead of failing the deploy that is trying to undo a bad one.
+// newer build applied, every one of them newer than anything this build ships — and decide whether
+// the migrate role lets that rollback through: yes over additive rows, no over destructive ones.
 
+import { renderFixShellArg } from '@ultimat3/core';
+import { isDestructiveMigration } from './destructive';
+import { DbError } from './errors';
 import type { LedgerRow, Migration } from './migration-ledger';
 import { pendingMigrations } from './migration-ledger';
 
+/** The operator's written override: the destructive migration ids they checked, comma-separated. */
+export const ROLLBACK_ALLOW_DESTRUCTIVE_ENV = 'ROLLBACK_ALLOW_DESTRUCTIVE';
+
 /** A rollback: the rows this build does not know (all newer), and the ledger it does. */
 export interface LedgerAhead {
   /** The rows a newer build applied, oldest first. Never empty. */
@@ -13,6 +19,15 @@ export interface LedgerAhead {
   readonly known: readonly LedgerRow[];
 }
 
+export interface LedgerAheadOptions {
+  /** `ROLLBACK_ALLOW_DESTRUCTIVE`'s value; read from the environment when not given. */
+  readonly allow?: string | undefined;
+}
+
+/** What the ledger records at apply: whether this migration's `up` destroys data. */
+export const destructiveBit = (migration: Migration): boolean =>
+  isDestructiveMigration(migration.up);
+
 /**
  * The ledger split, when it is exactly a rollback, else `undefined` and the caller's audit refuses
  * the unknown rows as it always has. Three conditions, all required:
@@ -25,13 +40,15 @@ export interface LedgerAhead {
  * - the build ships at least one migration. An image that lost its migrations directory is not
  *   "older than every row", and reading it as one would wave through the image that is broken.
  *
- * Nothing is applied either way: the schema the newer build left is additive over this one when
- * the release followed expand/contract (docs/ops/06-runbooks.md), and when it did not, no
- * migration this build ships could put it back.
+ * Nothing is applied either way. Over ADDITIVE rows the older build runs on the newer schema
+ * (expand/contract, docs/ops/06-runbooks.md). Over a row the newer build recorded as destructive
+ * it may not — a dropped column it still selects is the second outage — so that rollback is
+ * refused (`X_MIGRATION_ROLLBACK_DESTRUCTIVE`) unless the operator named every such row.
  */
 export function ledgerAheadOfBuild(
   ledger: readonly LedgerRow[],
   migrations: readonly Migration[],
+  options: LedgerAheadOptions = {},
 ): LedgerAhead | undefined {
   if (migrations.length === 0) return undefined;
   const shipped = new Set(migrations.map((migration) => migration.id));
@@ -40,5 +57,27 @@ export function ledgerAheadOfBuild(
   if (unknown.length === 0 || unknown.some((row) => row.id <= newest)) return undefined;
   const known = ledger.filter((row) => shipped.has(row.id));
   if (pendingMigrations(known, migrations).length > 0) return undefined;
-  return { ahead: [...unknown].sort((a, b) => (a.id < b.id ? -1 : 1)), known };
+  const ahead = [...unknown].sort((a, b) => (a.id < b.id ? -1 : 1));
+  assertRollbackSafe(ahead, options.allow ?? Bun.env[ROLLBACK_ALLOW_DESTRUCTIVE_ENV]);
+  return { ahead, known };
+}
+
+/** Every destructive row ahead must be named by the override; a null bit is not refused. */
+function assertRollbackSafe(ahead: readonly LedgerRow[], allow: string | undefined): void {
+  const named = new Set(
+    (allow ?? '')
+      .split(',')
+      .map((id) => id.trim())
+      .filter((id) => id !== ''),
+  );
+  const refused = ahead.filter((row) => row.destructive === true && !named.has(row.id));
+  if (refused.length === 0) return;
+  const ids = refused.map((row) => row.id);
+  const all = ahead.filter((row) => row.destructive === true).map((row) => row.id);
+  throw new DbError({
+    code: 'X_MIGRATION_ROLLBACK_DESTRUCTIVE',
+    cause: `the ledger holds ${ids.length} destructive migration(s) a newer build applied (${ids.join(', ')}) and this build predates them — it may read a column or table that no longer exists`,
+    fix: `x deploy --image <the newer image> --json   # roll forward; or, after checking this build runs on the newer schema: ${ROLLBACK_ALLOW_DESTRUCTIVE_ENV}=${renderFixShellArg(all.join(','), '<migration id>')} on the migrate role`,
+    meta: { refused: ids, appVersions: [...new Set(refused.map((row) => row.app_version))] },
+  });
 }

package/src/migrate.ts

@@ -3,10 +3,18 @@
 // 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, logger, renderFixShellArg } from '@ultimat3/core';
+import {
+  appVersion,
+  finiteCount,
+  isProduction,
+  logger,
+  type Random,
+  renderFixShellArg,
+} from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { expectedQueryLoop } from './expected-loop';
-import { ledgerAheadOfBuild } from './migrate-rollback';
+import { MIGRATION_LOCK_RETRIES } from './migrate-lock-retry';
+import { destructiveBit, ledgerAheadOfBuild } from './migrate-rollback';
 import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors';
 import type { Migration } from './migration-ledger';
 import {
@@ -19,6 +27,8 @@ import {
 } from './migration-ledger';
 import { applyMigrationStep } from './migration-step';
 import { poolProfileFor } from './pool-profile';
+import { retireAndContractPending } from './rolling';
+import { retireAndContractTogether } from './rolling-errors';
 import { raw, sql } from './sql';
 
 export type { LedgerRow, Migration } from './migration-ledger';
@@ -81,6 +91,13 @@ export interface MigrateOptions {
   readonly lockWaitMs?: number | undefined;
   /** `SET LOCAL lock_timeout` per migration. Defaults to the `migrate` role's profile. */
   readonly lockTimeoutMs?: number | undefined;
+  /** Attempts past the first when `lock_timeout` fires (`migrate-lock-retry.ts`). Defaults to 5. */
+  readonly lockRetries?: number | undefined;
+  /** Seams for the wait between those attempts; a test reads the schedule. */
+  readonly lockRetrySleep?: ((ms: number) => Promise<void>) | undefined;
+  readonly lockRetryRandom?: Random | undefined;
+  /** Whether a retire and its drop may land in one deploy. Defaults to core's `isProduction()`. */
+  readonly production?: boolean | undefined;
 }
 
 /**
@@ -192,10 +209,15 @@ function migrationLockTimeoutMs(explicit: number | undefined): number {
   );
 }
 
+/** Screened beside `lockTimeoutMs`, before the advisory lock, for the reason given there. */
+const migrationLockRetries = (explicit: number | undefined): number =>
+  finiteCount('migrate', 'lockRetries', explicit ?? MIGRATION_LOCK_RETRIES, 0);
+
 export async function migrate(options: MigrateOptions): Promise<MigrationReport> {
   const client = options.client ?? baseClient();
   const appVersion = runningAppVersion(options.appVersion);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
+  const retries = migrationLockRetries(options.lockRetries);
   const started = performance.now();
 
   return withAdvisoryLock(
@@ -222,6 +244,13 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
       }
 
       const pending = pendingMigrations(ledger, options.migrations);
+      // Before the first BEGIN, so nothing is half done. Only where a previous release can be
+      // running: a non-empty ledger in production. A fresh database, a template or a branch has no
+      // old pods to break and replays both freely.
+      if (ledger.length > 0 && (options.production ?? isProduction())) {
+        const pair = retireAndContractPending(pending);
+        if (pair !== undefined) throw retireAndContractTogether(pair);
+      }
       // A statement per migration and a transaction per migration is the point, not an N+1 to batch:
       // one failed `up` must leave the ledger describing exactly the migrations that did run, and a
       // batch commits or loses all of them together. Declared here so a diagnostic reports the loops
@@ -240,12 +269,20 @@ export async function migrate(options: MigrateOptions): Promise<MigrationReport>
               up: migration.up,
               script: migration.up,
               lockTimeoutMs,
+              lockRetry: {
+                retries,
+                sleep: options.lockRetrySleep,
+                random: options.lockRetryRandom,
+              },
+              // The bit an OLDER build reads on a rollback (`migrate-rollback.ts`): recorded here,
+              // by the build that knows the SQL, because the one rolled back to never sees it.
               record: async (client) => {
                 const durationMs = Math.round(performance.now() - at);
                 await client.execute(sql`
-                insert into ${raw(LEDGER_TABLE)} (id, name, checksum, app_version, duration_ms)
+                insert into ${raw(LEDGER_TABLE)}
+                  (id, name, checksum, app_version, duration_ms, destructive)
                 values (${migration.id}, ${migration.name}, ${migrationChecksum(migration)},
-                        ${appVersion}, ${durationMs})
+                        ${appVersion}, ${durationMs}, ${destructiveBit(migration)})
               `);
               },
             });
@@ -284,6 +321,8 @@ export interface RollbackOptions {
   readonly lockWaitMs?: number | undefined;
   /** `SET LOCAL lock_timeout` per reversal. Defaults to the `migrate` role's profile. */
   readonly lockTimeoutMs?: number | undefined;
+  /** Attempts past the first when `lock_timeout` fires. Defaults to 5, as `migrate`'s does. */
+  readonly lockRetries?: number | undefined;
 }
 
 /** Reverse the newest `steps` applied migrations. `x db rollback`. */
@@ -294,6 +333,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
   // "one fewer", so an unvalidated count reverses migrations nobody asked about.
   if (!Number.isSafeInteger(steps) || steps < 1) throw rollbackStepsInvalid(steps);
   const lockTimeoutMs = migrationLockTimeoutMs(options.lockTimeoutMs);
+  const retries = migrationLockRetries(options.lockRetries);
   const known = new Map(options.migrations.map((migration) => [migration.id, migration]));
 
   // The same lock `migrate` takes, because the race is the same one: a rollback reversing the id a
@@ -333,6 +373,7 @@ export async function rollback(options: RollbackOptions): Promise<readonly strin
               up: migration.up,
               script: migration.down,
               lockTimeoutMs,
+              lockRetry: { retries },
               record: async (client) => {
                 await client.execute(sql`delete from ${raw(LEDGER_TABLE)} where id = ${row.id}`);
               },

package/src/migration-errors.ts

@@ -1,6 +1,6 @@
 // Single responsibility: the refusals a MIGRATION earns — the lock it could not take, a ledger that
 // disagrees with this build, a plan that cannot be reversed, a plan that destroys rows without
-// saying so, a snapshot that was never written, and a view standing in a retype's way. Split out of
+// saying so, a snapshot never written, a view in a retype's way, a concurrent build. Split out of
 // `errors.ts` only because that file reached the 500-line ceiling, exactly as `invariant-errors.ts`
 // was: every code below is still declared, titled and registered there, and `DbError` is still the
 // one class. One direction only — nothing here is imported back.
@@ -176,3 +176,29 @@ export const migrationConcurrentInTransaction = (id: string, statement: string):
     fix: `sed -i '1i -- transaction: false' packages/db/migrations/${renderFixShellArg(id, '<id>')}.sql   # before it is applied — or move the statement into a migration of its own`,
     meta: { id },
   });
+
+/**
+ * A concurrent index build on a PARTITIONED parent, which Postgres refuses (`0A000`) — reached as
+ * a bare `X_DB_STATEMENT_FAILED` that named the refusal and not the sequence that replaces it.
+ * `sourceError` keeps the server's own error, SQLSTATE included. The sequence is pg_dump's: each
+ * partition built concurrently, the parent's index `on only` (instant, no rows), then attached.
+ */
+export const migrationConcurrentPartitioned = (
+  id: string,
+  statement: string,
+  sourceError: unknown,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_CONCURRENT_PARTITIONED',
+    cause:
+      `migration "${id}" builds an index concurrently on a partitioned table, which Postgres ` +
+      `refuses (0A000): ${statementExcerpt(statement)}`,
+    // Three pieces, each opening with the statement it is: the parent's index is attached to,
+    // never built over, so `on only` is instant and valid once every partition's is attached.
+    fix:
+      'CREATE INDEX CONCURRENTLY <index>_<partition> ON <partition> (<columns>);   # per partition, then ' +
+      'CREATE INDEX <index> ON ONLY <parent> (<columns>);   # then, per partition, ' +
+      'ALTER INDEX <index> ATTACH PARTITION <index>_<partition>;   # in a -- transaction: false migration',
+    meta: { id, sqlState: '0A000' },
+    sourceError,
+  });

package/src/migration-ledger.ts

@@ -3,15 +3,18 @@
 // 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 { isFixShellSafe } from '@ultimat3/core';
 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';
 
+/** Where `x new` puts an app's migrations: this package reads rows, the CLI reads the directory. */
+const APP_MIGRATIONS_DIR = 'packages/db/migrations';
+
 export interface Migration {
   /** Sort key and primary key. `20260726120000_add_publish_at`. */
   readonly id: string;
@@ -31,6 +34,13 @@ export interface LedgerRow {
   readonly applied_at: string;
   readonly app_version: string;
   readonly duration_ms: number;
+  /**
+   * Whether this migration's `up` destroys data, recorded at apply (`destructiveBit`). `null` on a
+   * row applied before the ledger kept the bit: the framework cannot know, and says so
+   * (`migrate-rollback.ts` warns rather than refuses over it). Optional so a row a caller builds
+   * by hand still types; `readLedger` always answers it.
+   */
+  readonly destructive?: boolean | null | undefined;
 }
 
 /**
@@ -58,6 +68,11 @@ export async function ensureLedger(client: DbClient): Promise<void> {
       duration_ms integer not null
     )
   `);
+  // Added, never part of the create: a ledger every earlier release made has no such column, and
+  // its rows keep `null` — "applied before the bit was recorded", never a guessed `false`.
+  await client.execute(sql`
+    alter table ${raw(LEDGER_TABLE)} add column if not exists destructive boolean
+  `);
 }
 
 /**
@@ -76,10 +91,16 @@ export function isLedgerMissing(error: unknown): boolean {
   return sqlState(error) === SQLSTATE.undefinedTable;
 }
 
+/**
+ * The bit is read through the row's JSON, not by name: `x db status`, the drift step and the MCP
+ * dry run read a ledger `ensureLedger` has not touched, and naming a column an older release's
+ * ledger lacks would turn every one of those reads into `42703`. Absent reads `null`.
+ */
 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)}
+    select id, name, checksum, applied_at, app_version, duration_ms,
+           (to_jsonb(ledger) ->> 'destructive')::boolean as destructive
+    from ${raw(LEDGER_TABLE)} as ledger
     order by id
   `);
 }
@@ -122,11 +143,24 @@ export function auditLedger(
     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`,
+      editedMigrationFix(row.id, row.checksum),
     );
   }
 }
 
+/**
+ * Restore first. `x db gen` was this line, and it exits 0 and writes the edited SQL into the schema
+ * dump, with `drift` green over it. `git checkout -- <file>` was the next, and a COMMITTED edit
+ * restores the same wrong blob, so the line lists the file's revisions and the ledger's checksum
+ * names the one applied. The id is a file name and the checksum a ledger value: either one the
+ * shell would read is left out (the directory, then the cause) rather than spliced.
+ */
+const editedMigrationFix = (id: string, checksum: string): string => {
+  const path = isFixShellSafe(id) ? `${APP_MIGRATIONS_DIR}/${id}.sql` : APP_MIGRATIONS_DIR;
+  const applied = isFixShellSafe(checksum) ? `checksum ${checksum}` : 'the checksum in the cause';
+  return `git log --format='%h %ad %s' --date=short -- ${path}   # restore the revision applied with ${applied}: git checkout <rev> -- ${path} and never edit an applied migration; then x db gen "<change>"`;
+};
+
 /**
  * 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

package/src/migration-step.ts

@@ -10,9 +10,14 @@ import {
   firstConcurrentStatement,
   isConcurrentIndexStatement,
   isNonTransactional,
+  isPartitionedBuildRefusal,
 } from './concurrent-index';
 import { refuseDependentViews } from './dependent-view';
-import { migrationConcurrentInTransaction } from './migration-errors';
+import { type LockRetryPolicy, withLockRetry } from './migrate-lock-retry';
+import {
+  migrationConcurrentInTransaction,
+  migrationConcurrentPartitioned,
+} from './migration-errors';
 import { raw, sql } from './sql';
 import { statementsOf } from './statement-split';
 import { withTransaction } from './transaction';
@@ -25,6 +30,8 @@ export interface MigrationStep {
   readonly script: string;
   /** `SET LOCAL lock_timeout` — every transaction, and no concurrent statement. `0` sets none. */
   readonly lockTimeoutMs: number;
+  /** What a `lock_timeout` firing is worth (`migrate-lock-retry.ts`). Absent is no second attempt. */
+  readonly lockRetry?: Omit<LockRetryPolicy, 'lockTimeoutMs'> | undefined;
   /** The ledger write, on the client the statements ran on — after the last of them succeeded. */
   readonly record: (client: DbClient) => Promise<void>;
 }
@@ -52,7 +59,7 @@ async function applyScript(tx: DbClient, script: string): Promise<void> {
  *
  * `SET LOCAL`, inside the migration's own transaction: it reverts at COMMIT, so a value chosen for
  * DDL never leaks onto the session the next migration runs on. The failure it produces is `55P03`,
- * typed as `X_DB_LOCK_TIMEOUT` by `driverError` with the `pg_stat_activity` read as its fix.
+ * typed as `X_DB_LOCK_TIMEOUT` by `driverError`, whose fix is `x db diagnostics --json`.
  */
 async function setLockTimeout(tx: DbClient, lockTimeoutMs: number): Promise<void> {
   if (lockTimeoutMs <= 0) return;
@@ -113,12 +120,26 @@ const BARE_CLUSTER = /^\s*cluster(?:\s+verbose)?\s*;?\s*$/i;
 const withoutLeadingComments = (statement: string): string =>
   statement.replace(/^(?:\s*--[^\n]*(?:\n|$))+/, '');
 
+/** The one retry wrap, whichever unit the step's kind makes safe to send again. */
+const retrying = (step: MigrationStep, attempt: () => Promise<void>): Promise<void> =>
+  withLockRetry(
+    step.id,
+    { ...(step.lockRetry ?? { retries: 0 }), lockTimeoutMs: step.lockTimeoutMs },
+    attempt,
+  );
+
 async function applyOutsideTransaction(session: DbClient, step: MigrationStep): Promise<void> {
   await refuseDependentViews(session, step.script);
   for (const statement of statementsOf(step.script)) {
     if (isConcurrentIndexStatement(statement)) {
       await dropInvalidLeftover(session, statement);
-      await session.execute(raw(statement));
+      await session.execute(raw(statement)).catch((error: unknown) => {
+        // `0A000` on a partitioned parent: the instruction is the sequence that replaces it.
+        if (isPartitionedBuildRefusal(statement, error)) {
+          throw migrationConcurrentPartitioned(step.id, statement, error);
+        }
+        throw error;
+      });
       continue;
     }
     // Postgres refuses these inside a transaction (25001): autocommitted, as the marker promises.
@@ -127,12 +148,16 @@ async function applyOutsideTransaction(session: DbClient, step: MigrationStep):
       await session.execute(raw(statement));
       continue;
     }
-    await withTransaction(
-      async (tx) => {
-        await setLockTimeout(tx, step.lockTimeoutMs);
-        await tx.execute(raw(statement));
-      },
-      { client: session },
+    // This statement and no earlier one: what already ran stays run. From the top would re-swap
+    // every validated key to `not valid` and scan it again, and repeat a hand-written first line.
+    await retrying(step, () =>
+      withTransaction(
+        async (tx) => {
+          await setLockTimeout(tx, step.lockTimeoutMs);
+          await tx.execute(raw(statement));
+        },
+        { client: session },
+      ),
     );
   }
   await step.record(session);
@@ -147,18 +172,21 @@ export async function applyMigrationStep(session: DbClient, step: MigrationStep)
   if (refused !== undefined) {
     throw migrationConcurrentInTransaction(step.id, refused);
   }
-  await withTransaction(
-    async (tx) => {
-      await setLockTimeout(tx, step.lockTimeoutMs);
-      // Before the first statement, never after the failure: a view compiled against a column
-      // this script retypes is `0A000` from the server with the view named only in a DETAIL field
-      // nothing prints (`dependent-view.ts`).
-      await refuseDependentViews(tx, step.script);
-      await applyScript(tx, step.script);
-      await step.record(tx);
-    },
-    // The lock's own session: a migration applied on another connection is not covered by the
-    // lock at all, and on `ROLE=migrate` there is no other connection to apply it on.
-    { client: session },
+  // Whole: the failed attempt rolled back, so nothing it did is left to repeat.
+  await retrying(step, () =>
+    withTransaction(
+      async (tx) => {
+        await setLockTimeout(tx, step.lockTimeoutMs);
+        // Before the first statement, never after the failure: a view compiled against a column
+        // this script retypes is `0A000` from the server with the view named only in a DETAIL field
+        // nothing prints (`dependent-view.ts`).
+        await refuseDependentViews(tx, step.script);
+        await applyScript(tx, step.script);
+        await step.record(tx);
+      },
+      // The lock's own session: a migration applied on another connection is not covered by the
+      // lock at all, and on `ROLE=migrate` there is no other connection to apply it on.
+      { client: session },
+    ),
   );
 }

package/src/partition-order.ts

@@ -0,0 +1,56 @@
+// Single responsibility: the two facts a partitioned table changes about the schema dump — the
+// order its tables load in (parent before partition, every one in the ROOT's file) and the index
+// definition its parent's index can be rebuilt from. Pure; `schema-dump.ts` places the statements.
+
+import type { CatalogTable } from './catalog';
+
+/** A table and the file it is written to: its own, or its partition root's. */
+export interface PlacedTable {
+  readonly table: CatalogTable;
+  readonly file: string;
+}
+
+/**
+ * Every table once, each partition after the table it is a partition of, and filed under its root
+ * — so `04_tables/events.sql` creates `events` and then each month, whatever the months are
+ * called. Name order would create `a_2026_11` before `events`. A partition whose parent is not in
+ * the list (another schema's) is filed under itself, after every family.
+ */
+export function inLoadOrder(tables: readonly CatalogTable[]): readonly PlacedTable[] {
+  const byName = new Map(tables.map((table) => [table.name, table]));
+  const children = new Map<string, CatalogTable[]>();
+  for (const table of tables) {
+    const parent = table.partitionOf?.table;
+    if (parent === undefined || !byName.has(parent)) continue;
+    const siblings = children.get(parent) ?? [];
+    siblings.push(table);
+    children.set(parent, siblings);
+  }
+  const placed: PlacedTable[] = [];
+  const seen = new Set<string>();
+  const family = (root: CatalogTable): void => {
+    // Breadth first: a sub-partition comes after every partition of the level above it.
+    const queue = [root];
+    for (let at = 0; at < queue.length; at += 1) {
+      const table = queue[at];
+      if (table === undefined || seen.has(table.name)) continue;
+      seen.add(table.name);
+      placed.push({ table, file: root.name });
+      queue.push(...(children.get(table.name) ?? []));
+    }
+  };
+  for (const table of tables) {
+    const parent = table.partitionOf?.table;
+    if (parent === undefined || !byName.has(parent)) family(table);
+  }
+  return placed;
+}
+
+/**
+ * `pg_get_indexdef` spells a partitioned table's index `ON ONLY` — the form that builds the
+ * parent's index alone, INVALID until every partition's is attached. The dump renders no
+ * partition's attached index, so it loads the parent's without `ONLY`, which builds them all.
+ */
+const ON_ONLY = /^(CREATE (?:UNIQUE )?INDEX (?:"(?:[^"]|"")*"|\S+) ON )ONLY /;
+
+export const indexDefinitionOf = (definition: string): string => definition.replace(ON_ONLY, '$1');

package/src/partitioned-tables.ts

@@ -0,0 +1,24 @@
+// Single responsibility: name the PARTITIONED parents in a schema (`relkind = 'p'`), so a table
+// description can say it is one. The partitions themselves are not app schema and never reach
+// here: `nonAppRelations()` excludes every `relispartition` row, a sub-partition's parent included.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+interface PartitionedRow {
+  readonly name: string;
+}
+
+/** The partitioned tables of `schema` that are not themselves a partition — the ones migrations declare. */
+export async function partitionedTables(
+  client: DbClient,
+  schema: string,
+): Promise<readonly string[]> {
+  const rows = await client.query<PartitionedRow>(sql`
+    select c.relname as name
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and c.relkind = 'p' and not c.relispartition
+  `);
+  return rows.map((row) => row.name);
+}

package/src/pool-gate.ts

@@ -0,0 +1,120 @@
+// Single responsibility: how many units of work may be out on the pool at once, and how long the
+// next one waits. `Bun.SQL` queues past `max` with no bound and publishes no occupancy, so this counts
+// in front of it: a statement and a pin each hold one slot, and a full pool refuses on one deadline.
+
+import type { Scheduler } from '@ultimat3/core';
+import { type DbError, poolAcquireTimeout } from './errors';
+import type { PoolDemand } from './pool-gauge';
+import { unrefSchedule } from './pool-timer';
+
+export interface PoolGate {
+  /**
+   * Take a slot. `undefined` when one was free, so the path that never waits pays no promise and
+   * sends in the caller's own turn. Otherwise resolves `true` when the slot arrives, `false` when
+   * this pool retired first, and rejects past `acquireTimeoutMs` (`X_DB_POOL_EXHAUSTED`). `0` waits
+   * forever.
+   */
+  enter(acquireTimeoutMs: number): Promise<boolean> | undefined;
+  /** Give a slot back. The oldest waiter inherits it, so a newcomer never overtakes the queue. */
+  leave(): void;
+  /** This pool is gone but the database may not be: everyone queued asks the next pool. */
+  handOverWaiting(): void;
+  /** Reject everyone still queued. Slots already held are untouched. */
+  refuseWaiting(reason: DbError): void;
+}
+
+/** What `takeSlot` needs of a pool: the gate that admits to it and the counter that reports it. */
+export interface GatedPool {
+  readonly gate: PoolGate;
+  readonly demand: PoolDemand;
+}
+
+/**
+ * A slot on the current pool, counted from the ask: a statement queued behind a full pool is exactly
+ * what `db_pool_waiting` reports. Answers the pool itself when a slot was free, so a caller checking
+ * `instanceof Promise` sends in its own turn. A retirement during the wait re-asks the pool that
+ * replaced it, with a fresh deadline: the work was never sent, so it can only be late, never doubled.
+ */
+export function takeSlot<P extends GatedPool>(
+  connect: () => P,
+  acquireTimeoutMs: number,
+): P | Promise<P> {
+  const asked = connect();
+  asked.demand.enter();
+  const wait = asked.gate.enter(acquireTimeoutMs);
+  if (wait === undefined) return asked;
+  return (async () => {
+    let admitted: boolean;
+    try {
+      admitted = await wait;
+    } catch (error) {
+      asked.demand.leave();
+      throw error;
+    }
+    if (admitted) return asked;
+    asked.demand.leave();
+    return takeSlot(connect, acquireTimeoutMs);
+  })();
+}
+
+/** The other half of `takeSlot`. */
+export function freeSlot(pool: GatedPool): void {
+  pool.gate.leave();
+  pool.demand.leave();
+}
+
+interface Waiter {
+  readonly settle: (admitted: boolean) => void;
+  readonly refuse: (reason: DbError) => void;
+  disarm: () => void;
+}
+
+export function poolGate(max: number, schedule: Scheduler = unrefSchedule): PoolGate {
+  let out = 0;
+  // A Set: FIFO by insertion, and a waiter past its deadline leaves from the middle in O(1).
+  const waiting = new Set<Waiter>();
+
+  return {
+    enter(acquireTimeoutMs) {
+      // `leave` hands a slot over rather than freeing it, so a free slot means nobody is queued.
+      if (out < max) {
+        out += 1;
+        return undefined;
+      }
+      return new Promise<boolean>((settle, refuse) => {
+        const waiter: Waiter = { settle, refuse, disarm: () => undefined };
+        waiting.add(waiter);
+        if (acquireTimeoutMs <= 0) return;
+        waiter.disarm = schedule(() => {
+          waiting.delete(waiter);
+          refuse(poolAcquireTimeout(acquireTimeoutMs, max));
+        }, acquireTimeoutMs);
+      });
+    },
+    leave() {
+      const next = waiting.values().next();
+      if (next.done === true) {
+        out = Math.max(0, out - 1);
+        return;
+      }
+      // Handed over: `out` does not move, the slot changes hands.
+      waiting.delete(next.value);
+      next.value.disarm();
+      next.value.settle(true);
+    },
+    handOverWaiting() {
+      for (const waiter of waiting) {
+        waiter.disarm();
+        waiter.settle(false);
+      }
+      waiting.clear();
+    },
+    refuseWaiting(reason) {
+      for (const waiter of waiting) {
+        waiter.disarm();
+        waiter.refuse(reason);
+      }
+      waiting.clear();
+    },
+  };
+}