@everystack/cli 0.4.34 → 0.4.36

package/src/cli/derived-introspect.ts

@@ -218,6 +218,36 @@ WHERE d.classid = 'pg_rewrite'::regclass
   AND rn.nspname NOT LIKE 'pg_%'
   AND NOT EXISTS (
     SELECT 1 FROM pg_depend dep WHERE dep.objid = rp.oid AND dep.deptype = 'e'
+  )
+UNION
+-- A FUNCTION depending on a view/matview's composite ROW TYPE — RETURNS SETOF <view>,
+-- or a view rowtype as an argument.
+--
+-- Both branches above are rooted at pg_rewrite, so their dependent side is always a view or
+-- matview; this edge has a function on the dependent side and is recorded against pg_type, not
+-- pg_class. Nothing found it, so the cascade could not see that dropping the view required
+-- dropping the function first — and PostgreSQL refuses the drop:
+--
+--   cannot drop materialized view post_engagement because other objects depend on it
+--   DETAIL: function analytics.engagement_for_author depends on type analytics_view.post_engagement
+--
+-- Latent until something UPSTREAM of such a view actually changes, which is why an app can carry
+-- this shape for a long time and only meet it the first time the view has to rebuild.
+SELECT DISTINCT
+  dn.nspname, dp.proname, rn.nspname, rc.relname
+FROM pg_depend d
+JOIN pg_proc dp ON dp.oid = d.objid
+JOIN pg_namespace dn ON dn.oid = dp.pronamespace
+JOIN pg_type rt ON rt.oid = d.refobjid
+JOIN pg_class rc ON rc.oid = rt.typrelid
+JOIN pg_namespace rn ON rn.oid = rc.relnamespace
+WHERE d.classid = 'pg_proc'::regclass
+  AND d.refclassid = 'pg_type'::regclass
+  AND rc.relkind IN ('v', 'm')
+  AND rn.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND rn.nspname NOT LIKE 'pg_%'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_depend dep WHERE dep.objid = dp.oid AND dep.deptype = 'e'
   );
 `.trim();
 

package/src/cli/derived-plan.ts

@@ -419,9 +419,19 @@ export function planReconcile(
   };
 
   // Relation roots whose live dependents must be handled: rebuilds and drops.
+  //
+  // FUNCTIONS ARE IN THE CLOSURE, not filtered out. A function whose return type is a view's
+  // composite rowtype (`RETURNS SETOF <view>`) makes PostgreSQL refuse to drop that view while
+  // the function exists. Excluding functions here left the cascade unable to express that, so a
+  // view backing a function's return type could never be rebuilt: the plan plotted the view's
+  // drop, counted the function as up to date, and the apply died on the drop.
+  //
+  // A function pulled in this way must be DROP + CREATE, never CREATE OR REPLACE. Replace does
+  // not drop, so the view's drop still runs with the function present and fails exactly as
+  // before — the `rebuild` map is what puts an identity in BOTH the drop set and the create set.
   const relationRoots = [...rebuild.keys(), ...drop.keys()];
   for (const root of relationRoots) {
-    const closure = closureOf(root).filter((id) => liveById.get(id) && isRelation(liveById.get(id)!.kind));
+    const closure = closureOf(root).filter((id) => liveById.has(id));
     const blockers = closure.filter((id) => !srcById.has(id) && !drop.has(id));
     if (blockers.length > 0) {
       blocked.push({
@@ -434,7 +444,12 @@ export function planReconcile(
     }
     for (const dep of closure) {
       if (!rebuild.has(dep) && !drop.has(dep) && srcById.has(dep)) {
+        const kind = liveById.get(dep)!.kind;
         rebuild.set(dep, `dependency rebuild (depends on ${root})`);
+        // Promoting a function out of the replace lane: a plain replace here would be a no-op
+        // against the problem, and leaving it in both lanes would emit a replace AND a
+        // drop+create for the same object.
+        if (!isRelation(kind)) fnReplace.delete(dep);
       }
     }
   }

package/src/cli/migration-compile.ts

@@ -26,6 +26,7 @@ import { compileTableContract } from './authz-compile.js';
 import { emitReconcileSql } from './authz-reconcile.js';
 import { emitSchemaSql, nextvalSequence, type SchemaChange } from './schema-diff.js';
 import { compileDerived } from './derived-compile.js';
+import { renderEnsureObjectSchemas } from './derived-apply.js';
 
 /** The empty (not-yet-created) authz state for a table — the greenfield baseline. */
 function emptyTable(table: string): TableContract {
@@ -155,7 +156,17 @@ export function compileModuleMigration(modules: Module[], opts: CompileTableOpti
   //    objects — compiled in topological order, after every table. Greenfield = one
   //    complete script: state + compute; from then on the layer deploys via db:reconcile.
   const models = modules.flatMap((m) => m.models);
-  for (const obj of compileDerived(models, modules.flatMap((m) => m.derived))) {
+  const derivedObjects = compileDerived(models, modules.flatMap((m) => m.derived));
+
+  // 4a. A schema that ONLY derived objects live in has no model to create it, so phase 2
+  //     never does — and the first CREATE VIEW in it fails with `schema … does not exist`.
+  //     db:reconcile has always handled this; the greenfield module migration did not, so a
+  //     derived-only schema was buildable by reconcile and not by a from-scratch deploy.
+  //     Same renderer as the reconcile path, deliberately: one implementation, one behaviour.
+  //     Idempotent — a schema phase 2 already created is a no-op here.
+  sql.push(...renderEnsureObjectSchemas(derivedObjects).map((s) => `${s};`));
+
+  for (const obj of derivedObjects) {
     sql.push(`${obj.sql};`);
     for (const a of obj.attachments) sql.push(`${a.sql};`);
   }

package/src/cli/migration-generate.ts

@@ -207,11 +207,40 @@ export function generateMigrationSql(models: ModelDescriptor[], current: SchemaS
         ),
       }
     : opts.liveAuthz;
+  const desiredContracts = models.map((m) => compileTableContract(m, { schema }));
   const authzPhase = liveAuthzRenamed
-    ? emitReconcileSql({ tables: models.map((m) => compileTableContract(m, { schema })), functions: [] }, liveAuthzRenamed)
+    ? emitReconcileSql({ tables: desiredContracts, functions: [] }, liveAuthzRenamed)
     : [];
 
-  return [...schemaPhase, ...dataPhase, ...authzPhase];
+  // 0a-bis (the diff analog of compileMigration's). A role cannot reach a table in a
+  // non-public schema without USAGE on that schema, so every table grant emitted below is
+  // DEAD without this — declared, and denied by the database. Nothing introspects schema
+  // ACLs, so the diff has no live side to compare against; it re-emits USAGE for every
+  // non-public declared schema exactly as the authz phase re-emits every table grant.
+  // GRANT is idempotent, so this stays correct both for a brand-new schema and for a role
+  // added to an existing one.
+  //
+  // The from-scratch path had this from the start; the diff path did not, so a non-public
+  // model reached through db:sync/db:generate was unreachable by every role that did not
+  // pick up USAGE some other way. The example app's analytics schema is what surfaced it.
+  const usagePhase = authzPhase.length
+    ? [...new Set(desiredContracts.map((c) => c.table.split('.')[0]))]
+        .filter((s) => s !== 'public')
+        .sort()
+        .flatMap((s) => {
+          const roles = new Set<string>();
+          for (const c of desiredContracts) {
+            if (!c.table.startsWith(`${s}.`)) continue;
+            for (const r of Object.keys(c.grants)) roles.add(r);
+            for (const r of Object.keys(c.columnGrants ?? {})) roles.add(r);
+          }
+          if (!roles.size) return [];
+          const targets = [...roles].sort().map((r) => (r.toUpperCase() === 'PUBLIC' ? 'PUBLIC' : r)).join(', ');
+          return [`GRANT USAGE ON SCHEMA "${s}" TO ${targets}`];
+        })
+    : [];
+
+  return [...schemaPhase, ...usagePhase, ...dataPhase, ...authzPhase];
 }
 
 /** The marker drizzle migration files put between statements. */

package/src/cli/mutation-lease.ts

@@ -97,6 +97,14 @@ WHERE l.locktype = 'advisory'
   AND l.classid = ${MUTATION_LEASE_KEY.classid}
   AND l.objid   = ${MUTATION_LEASE_KEY.objid}
   AND l.granted
+  -- Scoped to THIS database. An advisory lock's tag includes the database oid, so the lease is
+  -- already per-database and the acquire above contends correctly. pg_locks, though, is
+  -- cluster-wide: without this filter a LIMIT 1 could return a holder from a completely
+  -- different database, and the refusal would name an innocent backend — while telling the
+  -- operator to terminate it. Caught when a swap on a neighbouring database on the same
+  -- cluster was reported as the holder. db:branch mints many databases on one cluster, so
+  -- this is the normal case, not an exotic one.
+  AND l.database = (SELECT oid FROM pg_database WHERE datname = current_database())
 LIMIT 1;
 `.trim();
 

package/src/cli/schema-rewrite.ts

@@ -19,6 +19,99 @@
 
 const IDENT = '[A-Za-z_][A-Za-z0-9_$]*';
 
+/**
+ * A line split into CODE spans (rewritable) and LITERAL spans (never touched): single-quoted
+ * strings, dollar-quoted strings, and `--` comments.
+ *
+ * This exists because the rewrite is a regex over identifiers and a schema name is also an
+ * ordinary word. `jsonb_build_object('stats', …)` has `stats` as a JSON KEY, and rewriting it
+ * silently renames a key in the output payload:
+ *
+ *   jsonb_build_object('stats', …)  →  jsonb_build_object('stats_incoming', …)
+ *
+ * Found in the field, and it is the nastiest failure this module can produce: every object is
+ * present, non-empty and correctly wired, so the completeness and reachability assertions all
+ * pass while the DATA is wrong. A consumer found 20 renamed keys in one matview.
+ *
+ * Double-quoted spans are deliberately NOT literals — those are quoted IDENTIFIERS (`"stats".x`)
+ * and must still be rewritten.
+ *
+ * `inDollar` carries dollar-quote state across lines, because a dollar-quoted body spans them and
+ * the streaming rewriter is line-oriented.
+ */
+export function splitCodeSpans(
+  line: string,
+  inDollar?: string,
+): { spans: Array<{ text: string; code: boolean }>; inDollar?: string } {
+  const spans: Array<{ text: string; code: boolean }> = [];
+  let i = 0;
+  let start = 0;
+  let dollar = inDollar;
+
+  // Mid-body of a dollar-quoted string that opened on an earlier line: consume to its close.
+  if (dollar) {
+    const end = line.indexOf(dollar);
+    if (end === -1) return { spans: [{ text: line, code: false }], inDollar: dollar };
+    const stop = end + dollar.length;
+    spans.push({ text: line.slice(0, stop), code: false });
+    i = start = stop;
+    dollar = undefined;
+  }
+
+  const push = (to: number, code: boolean): void => {
+    if (to > start) spans.push({ text: line.slice(start, to), code });
+  };
+
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === "'") {
+      push(i, true);
+      let j = i + 1;
+      while (j < line.length) {
+        if (line[j] === "'") {
+          if (line[j + 1] === "'") { j += 2; continue; } // '' is an escaped quote, not the end
+          j++;
+          break;
+        }
+        j++;
+      }
+      spans.push({ text: line.slice(i, j), code: false });
+      i = start = j;
+      continue;
+    }
+    if (ch === '$') {
+      const m = /^\$[A-Za-z0-9_]*\$/.exec(line.slice(i));
+      if (m) {
+        push(i, true);
+        const tag = m[0];
+        const end = line.indexOf(tag, i + tag.length);
+        if (end === -1) {
+          spans.push({ text: line.slice(i), code: false });
+          return { spans, inDollar: tag };
+        }
+        const stop = end + tag.length;
+        spans.push({ text: line.slice(i, stop), code: false });
+        i = start = stop;
+        continue;
+      }
+    }
+    if (ch === '-' && line[i + 1] === '-') {
+      push(i, true);
+      spans.push({ text: line.slice(i), code: false });
+      return { spans, inDollar: undefined };
+    }
+    i++;
+  }
+  push(line.length, true);
+  return { spans, inDollar: dollar };
+}
+
+/** Apply `fn` to the CODE spans of a line only, leaving string/dollar/comment spans verbatim. */
+function overCode(line: string, fn: (code: string) => string, inDollar?: string): { text: string; inDollar?: string } {
+  const { spans, inDollar: next } = splitCodeSpans(line, inDollar);
+  return { text: spans.map((s) => (s.code ? fn(s.text) : s.text)).join(''), inDollar: next };
+}
+
 /** True once this line OPENS a COPY data block (`COPY … FROM stdin;`) — data follows until `\.`. */
 export function opensCopyData(line: string): boolean {
   return /^\s*COPY\s+.*\sFROM\s+stdin;\s*$/i.test(line);
@@ -36,14 +129,49 @@ export function closesCopyData(line: string): boolean {
  * `SET search_path` naming it. The schema token must be a plain identifier at both ends so a
  * substring of another name (`from_archive`) is never touched.
  */
-export function rewriteStatementLine(line: string, from: string, to: string): string {
+export function rewriteStatementLine(line: string, from: string, to: string, inDollar?: string): string {
   const f = from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  // 1. Schema-qualified refs: `from.` or `"from".` → `to.` (normalize to bare; the token is safe).
-  let out = line.replace(new RegExp(`(^|[^A-Za-z0-9_$."])(?:${f}|"${f}")\\.`, 'g'), `$1${to}.`);
-  // 2. Standalone schema in CREATE/ALTER/DROP SCHEMA and search_path — the token as a whole word,
-  //    bare or quoted, not followed by a dot (those were handled above).
-  out = out.replace(new RegExp(`(^|[^A-Za-z0-9_$.])(?:${f}|"${f}")(?![A-Za-z0-9_$."])`, 'g'), `$1${to}`);
-  return out;
+  // CODE spans only — a schema name inside a string literal is DATA (a JSON key, an enum value),
+  // and renaming it corrupts the output while every structural check still passes.
+  return overCode(line, (code) => {
+    // 1. Schema-qualified refs: `from.` or `"from".` → `to.` (normalize to bare; the token is safe).
+    let out = code.replace(new RegExp(`(^|[^A-Za-z0-9_$."])(?:${f}|"${f}")\\.`, 'g'), `$1${to}.`);
+    // 2. Standalone schema in CREATE/ALTER/DROP SCHEMA and search_path — the token as a whole word,
+    //    bare or quoted, not followed by a dot (those were handled above).
+    out = out.replace(new RegExp(`(^|[^A-Za-z0-9_$.])(?:${f}|"${f}")(?![A-Za-z0-9_$."])`, 'g'), `$1${to}`);
+    return out;
+  }, inDollar).text;
+}
+
+/**
+ * The N-schema form of {@link rewriteStatementLine}, applied in ONE pass.
+ *
+ * The paired swap renames several schemas at once (`analytics` + `analytics_view`), and their
+ * names overlap by construction — a derived schema is conventionally the base name plus a
+ * suffix. Rewriting them one after another is not obviously safe to a reader even when it
+ * happens to be (the identifier-boundary rules make `analytics` miss `analytics_view`), and it
+ * gets less safe the moment someone picks different names. One pass with the longest name tried
+ * first removes the ordering question entirely.
+ */
+export function rewriteStatementLineMulti(line: string, map: Record<string, string>, inDollar?: string): string {
+  const froms = Object.keys(map);
+  if (froms.length === 0) return line;
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Longest first: a schema whose name is a PREFIX of another must never win the alternation.
+  const alt = [...froms].sort((a, b) => b.length - a.length).map(esc).join('|');
+  const pick = (bare?: string, quoted?: string) => map[(bare ?? quoted)!];
+  // CODE spans only — see splitCodeSpans. A schema name inside quotes is DATA.
+  return overCode(line, (code) => {
+    let out = code.replace(
+      new RegExp(`(^|[^A-Za-z0-9_$."])(?:(${alt})|"(${alt})")\\.`, 'g'),
+      (_m, pre: string, bare: string, quoted: string) => `${pre}${pick(bare, quoted)}.`,
+    );
+    out = out.replace(
+      new RegExp(`(^|[^A-Za-z0-9_$.])(?:(${alt})|"(${alt})")(?![A-Za-z0-9_$."])`, 'g'),
+      (_m, pre: string, bare: string, quoted: string) => `${pre}${pick(bare, quoted)}`,
+    );
+    return out;
+  }, inDollar).text;
 }
 
 /**
@@ -55,13 +183,18 @@ export function rewriteStatementLine(line: string, from: string, to: string): st
 export function rewriteSchemaDump(sql: string, from: string, to: string): string {
   const lines = sql.split('\n');
   let inCopy = false;
+  let inDollar: string | undefined;
   for (let i = 0; i < lines.length; i++) {
     if (inCopy) {
       if (closesCopyData(lines[i])) inCopy = false;
       continue; // data (or the terminator) — never rewritten
     }
-    lines[i] = rewriteStatementLine(lines[i], from, to);
-    if (opensCopyData(lines[i])) inCopy = true;
+    // Dollar-quote state carries ACROSS lines: a function body spanning them must stay literal
+    // for its whole length, not just the line that opened it.
+    const next = splitCodeSpans(lines[i], inDollar).inDollar;
+    lines[i] = rewriteStatementLine(lines[i], from, to, inDollar);
+    inDollar = next;
+    if (!inDollar && opensCopyData(lines[i])) inCopy = true;
   }
   return lines.join('\n');
 }

package/src/cli/schema-source.ts

@@ -38,6 +38,18 @@ function toCamelCase(name: string): string {
   return name.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 }
 
+/**
+ * The export name for a model's drizzle binding — schema-qualified when the table
+ * does not live in `public`, so `analytics.post_metrics` and a hypothetical
+ * `public.post_metrics` cannot collide on one identifier.
+ *
+ * Same rule the derived relations already use, deliberately: the two halves of this
+ * file name things the same way.
+ */
+function modelCamel(model: { schema: string; table: string }): string {
+  return toCamelCase(model.schema === 'public' ? model.table : `${model.schema}_${model.table}`);
+}
+
 /** A JS/TS string literal — single-quoted, the example's style. */
 function strLiteral(value: string): string {
   return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
@@ -290,7 +302,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
   const derivedRelations = typedRelations(_opts.derived ?? []);
 
   const modelsByDescriptor = new Map<ModelDescriptor, { camel: string }>();
-  for (const model of models) modelsByDescriptor.set(model, { camel: toCamelCase(model.table) });
+  for (const model of models) modelsByDescriptor.set(model, { camel: modelCamel(model) });
 
   // --- Collect enums (deduped by name, sorted) -----------------------------
   const enumsByName = new Map<string, readonly string[]>();
@@ -312,7 +324,9 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
 
   // --- Track which pg-core builders + drizzle-orm symbols are used ----------
   const pgCoreBuilders = new Set<string>();
-  pgCoreBuilders.add('pgTable');
+  // Only when something actually lands in `public` — an all-non-public model set would
+  // otherwise import a builder it never calls.
+  if (models.some((m) => m.schema === 'public')) pgCoreBuilders.add('pgTable');
   if (enumNames.length) pgCoreBuilders.add('pgEnum');
 
   const relationNaming = planRelationNames(models);
@@ -321,7 +335,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
   // --- Emit each table -------------------------------------------------------
   const tableBlocks: string[] = [];
   for (const model of models) {
-    const camel = toCamelCase(model.table);
+    const camel = modelCamel(model);
     const isComposite = model.primaryKey.length > 1;
 
     const colLines: string[] = [];
@@ -361,11 +375,20 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
     }
 
     const cols = `{\n${colLines.join('\n')}\n}`;
+    // A non-public model must emit through `pgSchema(...)`, exactly as the runtime
+    // builder does (`toDrizzleTable`: pgSchema(model.schema).table(...)). A bare
+    // pgTable() resolves against the search_path at query time and silently reads
+    // `public.<table>` — a table that need not even exist. The app's models were all
+    // public until the analytics fixture, so this never surfaced.
+    const target = model.schema === 'public'
+      ? `pgTable(${strLiteral(model.table)}`
+      : `pgSchema(${strLiteral(model.schema)}).table(${strLiteral(model.table)}`;
+    if (model.schema !== 'public') pgCoreBuilders.add('pgSchema');
     let block: string;
     if (extras.length) {
-      block = `export const ${camel} = pgTable(${strLiteral(model.table)}, ${cols}, (t) => [\n${extras.join('\n')}\n]);`;
+      block = `export const ${camel} = ${target}, ${cols}, (t) => [\n${extras.join('\n')}\n]);`;
     } else {
-      block = `export const ${camel} = pgTable(${strLiteral(model.table)}, ${cols});`;
+      block = `export const ${camel} = ${target}, ${cols});`;
     }
     tableBlocks.push(block);
   }
@@ -375,7 +398,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
   for (const model of models) {
     const relEntries = Object.entries(model.relations);
     if (relEntries.length === 0) continue;
-    const camel = toCamelCase(model.table);
+    const camel = modelCamel(model);
 
     const usesOne = relEntries.some(([, r]) => r.kind === 'belongsTo');
     const usesMany = relEntries.some(([, r]) => r.kind === 'hasMany');
@@ -384,7 +407,7 @@ export function compileDrizzleSource(allModels: ModelDescriptor[], _opts: Compil
     const lines: string[] = [];
     for (const [key, rel] of relEntries) {
       const target = rel.target();
-      const targetCamel = toCamelCase(target.table);
+      const targetCamel = modelCamel(target);
       const nameFrag = relationNameFragment(model, rel, relationNaming);
       if (rel.kind === 'belongsTo') {
         // belongsTo(() => Target, column, references?) -> one(...)

package/src/cli/schema-swap.ts

@@ -99,6 +99,14 @@ export interface SwapPlan {
   /** The schema the live data is renamed to before the retiring drop (outside the txn). */
   retiring: string;
   incoming: string;
+  /**
+   * EVERY retiring schema the swap produced — the base schema first, then each paired derived
+   * schema. The caller drops all of them after verify; dropping only `retiring` would strand the
+   * derived twins as permanent clutter that the next swap then collides with.
+   */
+  retiringSchemas: string[];
+  /** The paired derived schemas, in the order they were renamed. Empty for an unpaired swap. */
+  paired: string[];
 }
 
 export interface SwapOptions {
@@ -108,6 +116,27 @@ export interface SwapOptions {
   incoming?: string;
   /** Where the live schema is renamed. Default `<schema>_retiring`; pass a stamped name for uniqueness. */
   retiring?: string;
+  /**
+   * Derived schemas swapping ALONGSIDE the base schema (the paired swap). Each is renamed in the
+   * SAME transaction as the base, so a reader never sees a base schema paired with a derived layer
+   * built over the retiring one. Their incoming twins must already be built — see swap-pair.
+   */
+  paired?: string[];
+  /** Suffix for the paired schemas' incoming twins. Must match the build. Default `_incoming`. */
+  incomingSuffix?: string;
+  /** Suffix for the paired schemas' retiring names. Default `_retiring`. */
+  retiringSuffix?: string;
+  /**
+   * `GRANT USAGE ON SCHEMA` for every schema in the swap set (see renderSwapSchemaUsage), applied
+   * INSIDE the swap transaction after the renames.
+   *
+   * The incoming schemas carry no schema-level ACL — the base one is restored `--no-privileges`,
+   * the derived twins are freshly created — so a swap that re-applies only table authz commits a
+   * set of schemas no application role can enter. Found on real infrastructure: every API endpoint
+   * 500'd, and because PostgreSQL reports missing USAGE as ABSENCE the error read
+   * `relation "..." does not exist`, which points nowhere near the cause.
+   */
+  schemaUsage?: string[];
 }
 
 /**
@@ -135,15 +164,40 @@ export function renderSchemaSwap(models: ModelDescriptor[], opts: SwapOptions):
     .map((m) => compileTableContract(m));
   const authz = emitSwapAuthzSql({ tables: statsContracts, functions: [] });
 
+  // The paired derived schemas rename in the SAME transaction as the base. Order between pairs
+  // does not matter — nothing is resolved by name inside the transaction; the objects already
+  // bind their sources by OID, and a rename does not disturb an OID. What matters is that all of
+  // them commit together, so there is no instant where the new base serves under a derived layer
+  // still welded to the retiring one.
+  const paired = opts.paired ?? [];
+  const incomingSuffix = opts.incomingSuffix ?? '_incoming';
+  const retiringSuffix = opts.retiringSuffix ?? '_retiring';
+  const pairRenames: string[] = [];
+  const retiringSchemas = [retiring];
+  for (const p of paired) {
+    const pRetiring = `${p}${retiringSuffix}`;
+    const pIncoming = `${p}${incomingSuffix}`;
+    assertSafeSchema(p);
+    assertSafeSchema(pRetiring);
+    assertSafeSchema(pIncoming);
+    pairRenames.push(`ALTER SCHEMA "${p}" RENAME TO "${pRetiring}";`);
+    pairRenames.push(`ALTER SCHEMA "${pIncoming}" RENAME TO "${p}";`);
+    retiringSchemas.push(pRetiring);
+  }
+
   const statements = [
     ...fks.map((f) => f.dropSql),
     `ALTER SCHEMA "${schema}" RENAME TO "${retiring}";`,
     `ALTER SCHEMA "${incoming}" RENAME TO "${schema}";`,
+    ...pairRenames,
     ...fks.map((f) => f.addSql),
     ...authz,
+    // Schema-level USAGE last: the table grants above are dead without it, and it must ride the
+    // same transaction so there is no committed instant where the new schemas serve unreachable.
+    ...(opts.schemaUsage ?? []),
   ];
 
-  return { statements, crossSchemaFks: fks, retiring, incoming };
+  return { statements, crossSchemaFks: fks, retiring, incoming, retiringSchemas, paired: [...paired] };
 }
 
 /** The drop of the retiring schema, run AFTER the swap transaction commits and verify passes. */