@everystack/cli 0.4.35 → 0.4.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.35",
+  "version": "0.4.36",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/commands/db-swap.ts

@@ -26,6 +26,9 @@ import { fingerprintModels } from '../schema-fingerprint.js';
 import { resolveModelsPath } from '../models-path.js';
 import { loadModels } from './db-generate.js';
 import { loadDeclaredDerived } from '../declared-derived.js';
+import type { SourceObject } from '../derived-source.js';
+import { pairedDerivedSchemas, renderPairedDerivedBuild, renderSwapSchemaUsage, swapSchemaRoles, expectedIncomingObjects, renderPairedProvenance } from '../swap-pair.js';
+import { introspectDerived } from '../derived-introspect.js';
 import { createUrlRunner } from '../db-source.js';
 import type { QueryRunner } from '../authz-contract.js';
 import { executeSwap, type SwapVerdict } from '../swap-execute.js';
@@ -413,17 +416,40 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
   if (!from) { fail('db:swap needs --from <artifact.dump | artifact-id> (the schema-scoped -Fc archive to land).'); process.exit(1); }
 
   // Resolve the venue.
-  //  - --database-url (or DATABASE_URL): a local/direct operator connection.
+  //  - --database-url: a local/direct operator connection. EXPLICIT FLAG ONLY.
   //  - --stage --direct: resolve the stage's OPERATOR connection from its ops Lambda and execute
   //    CLI-side with an unbounded clock (a multi-GB restore blows the 900s Lambda ceiling). The
   //    operator never holds a URL; the swap snapshots the stage via db:backup before it lands.
   //  - --stage alone: refuse, naming --direct — the ops-Lambda venue can't hold the restore clock.
-  let url = flags['database-url'] || process.env.DATABASE_URL;
+  //
+  // `process.env.DATABASE_URL` is NOT a venue here, and used to be.
+  //
+  // It was read first, and the stage branch was guarded by `if (!url && stage)` — so an exported
+  // DATABASE_URL SILENTLY OVERRODE `--stage`. An operator asking for dev got whatever the
+  // environment named, the stage's snapshot was skipped (the branch that sets snapshotViaStage
+  // never ran, hence the "direct v1" warning), and the swap reported success against a database
+  // nobody had asked for. A consumer hit exactly this: two runs differing only by an unrelated
+  // diagnostic flag went to different databases, because one shell had the variable exported and
+  // the other did not. Their dev derived layer was untouched because dev was never the target.
+  //
+  // On a DESTRUCTIVE verb an ambient variable must never choose the target, and db:export already
+  // states the rule: --database-url is explicit-flag-only, never the env — the venue must be
+  // deliberate. This is that rule, applied where it mattered most and was missing.
+  const urlFlag = flags['database-url'];
+  if (urlFlag && stage) {
+    fail(`db:swap got BOTH --database-url and --stage ${stage} — that is two different targets and the wrong one is destructive. Pass exactly one.`);
+    process.exit(1);
+  }
+  if (!urlFlag && !stage && process.env.DATABASE_URL) {
+    fail('db:swap will not take its target from the DATABASE_URL environment variable — a destructive swap must name its target explicitly. Pass --database-url <url> (local/direct) or --stage <name> --direct.');
+    process.exit(1);
+  }
+  let url = urlFlag;
   let snapshotViaStage = false;
   let region: string | undefined;
   let opsFn: string | undefined;
 
-  if (!url && stage) {
+  if (stage) {
     if (!direct) {
       fail('db:swap --stage needs --direct: a schema restore can exceed the ops-Lambda 900-second clock, so the swap runs CLI-side with an unbounded clock (credential-free — the operator never holds a URL). Re-run with --stage ' + stage + ' --direct.');
       process.exit(1);
@@ -451,15 +477,18 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
 
   // --rebuild-derived carries a real outage window: the derived layer does not exist between the
   // swap committing and db:reconcile --apply finishing. State it BEFORE the work starts — saying it
-  // only afterward tells the operator about an outage they are already in.
+  // only afterward tells the operator about an outage they are already in. It is now the OPT-OUT:
+  // the paired swap below is the default and has no window at all.
   if (flags['rebuild-derived'] === 'true') {
     warn('--rebuild-derived drops the dependent derived objects as part of the swap. They do NOT exist until db:reconcile --apply finishes — an outage window proportional to the size of the derived layer.');
+    warn('  the paired swap (the default, without this flag) rebuilds the layer over the incoming data and renames it in the same transaction — no window. Drop the flag unless you specifically want the old behaviour.');
   }
 
   const modelsPath = resolveModelsPath(flags.models);
   let models: ModelDescriptor[];
   let declaredFingerprint: string;
-  let declaredDerivedObjects: Array<{ identity: string }> = [];
+  let declaredDerivedObjects: SourceObject[] = [];
+  let paired: string[] = [];
   try {
     step(`Loading models from ${modelsPath}...`);
     models = await loadModels(modelsPath);
@@ -467,8 +496,19 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
     declaredFingerprint = fingerprintModels(models, { schemas: [schema], sequences: declaredDb?.sequences }).hash;
     // The identities db:reconcile can regenerate — what makes a dependent safe to drop.
     declaredDerivedObjects = declaredDb?.objects ?? [];
+    // The PAIRED swap is the default whenever a declared derived schema hangs off this one: the
+    // layer is rebuilt over the incoming tables and renamed in the same transaction, so it is
+    // never absent. --rebuild-derived is the explicit opt-out (drop, swap, reconcile after), kept
+    // for the case where rebuilding twice is not worth the zero-downtime guarantee.
+    if (flags['rebuild-derived'] !== 'true' && declaredDb) {
+      paired = pairedDerivedSchemas(models, declaredDb.derived, schema);
+    }
   } catch (err: any) { fail(err.message); process.exit(1); }
 
+  if (paired.length > 0) {
+    info(`paired swap: ${paired.join(', ')} will be rebuilt over the incoming data and renamed in the SAME transaction — the derived layer is never absent.`);
+  }
+
   // Resolve --from to a local plain -Fc dump (a local file, or an S3 export id fetched down).
   let artifact: ResolvedArtifact;
   try {
@@ -496,6 +536,68 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
         // What db:reconcile can regenerate — the set a dependent must be in to be safe to drop.
         declaredIdentities: declaredDerivedObjects.map((o) => o.identity),
         rebuildDerived: flags['rebuild-derived'] === 'true',
+        paired,
+        // Schema-level USAGE, re-applied in the swap transaction and asserted after it commits.
+        // The incoming schemas arrive with no schema ACL, so without this the swap lands correct
+        // data behind schemas the app cannot enter — every endpoint 500s with "does not exist".
+        schemaUsage: renderSwapSchemaUsage(models, declaredDerivedObjects, schema, paired),
+        schemaUsageRoles: [...swapSchemaRoles(models, declaredDerivedObjects, [schema, ...paired])]
+          .flatMap(([s, roles]) => roles.map((role) => ({ schema: s, role }))),
+        // Every declared object the paired build must produce. Checked before the rename, so a
+        // partial layer refuses with live untouched rather than committing a silent shortfall.
+        expectedDerived: paired.length
+          ? expectedIncomingObjects(declaredDerivedObjects, schema, paired)
+          : undefined,
+        // Tell the reconciler what the build made. Without this the next db:reconcile — days
+        // later, for an unrelated edit — sees the whole layer as drift and rebuilds it under
+        // ACCESS EXCLUSIVE. The objects are correct; only the bookkeeping was missing.
+        recordProvenance: paired.length
+          ? async (r) => {
+              const live = await introspectDerived(r);
+              const prov = renderPairedProvenance(declaredDerivedObjects, live.objects, schema, paired);
+              for (const st of prov.statements) await r(st);
+              if (prov.recorded.length === 0) {
+                warn(`provenance recorded NOTHING — no declared object in ${[schema, ...paired].join(', ')} matched a live catalog entry. `
+                  + `The swap itself succeeded, but the next db:reconcile will treat this layer as drift. Run db:reconcile --check to see what it thinks.`);
+              } else {
+                info(`provenance recorded for ${prov.recorded.length} object(s) — a post-swap db:reconcile is NOT required.`);
+                if (prov.unmatched.length) {
+                  warn(`  ${prov.unmatched.length} declared object(s) had no live catalog entry and were NOT recorded: ${prov.unmatched.slice(0, 10).join(', ')}${prov.unmatched.length > 10 ? ', …' : ''}`);
+                }
+              }
+            }
+          : undefined,
+        // Build the incoming derived layer over <schema>_incoming, before the rename. Skipped
+        // entirely when nothing pairs — an all-public app's swap is byte-identical to before.
+        buildPairedDerived: paired.length
+          ? async (r) => {
+              step(`Building the incoming derived layer (${paired.join(', ')})...`);
+              const built = renderPairedDerivedBuild(declaredDerivedObjects, schema, paired);
+              for (const s of built.statements) await r(s);
+              // --dump-build: diagnostic only, no behaviour change. Writes what the build EMITTED
+              // and what the catalog HOLDS immediately afterwards, before the rename. Those two
+              // together separate "the build rendered the wrong SQL" from "the build was fine and
+              // the rename lost it" — a distinction that is otherwise only reachable by racing a
+              // second connection against the build window.
+              if (flags['dump-build']) {
+                const twins = paired.map((p) => `${p}_incoming`);
+                const rows = await r(
+                  `SELECT n.nspname || '.' || c.relname AS identity, pg_get_viewdef(c.oid) AS definition
+                     FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+                    WHERE n.nspname = ANY (ARRAY[${twins.map((t) => `'${t.replace(/'/g, "''")}'`).join(',')}])
+                      AND c.relkind IN ('v','m') ORDER BY 1`,
+                );
+                fs.writeFileSync(flags['dump-build'], JSON.stringify({
+                  schema, paired,
+                  searchPath: built.statements[0],
+                  statementCount: built.statements.length,
+                  statements: built.statements,
+                  liveInIncomingAfterBuild: rows,
+                }, null, 2));
+                info(`--dump-build: wrote ${built.statements.length} rendered statement(s) and ${rows.length} live definition(s) to ${flags['dump-build']}`);
+              }
+            }
+          : undefined,
         log: (m) => info(m),
         // The runner is handed in and USED: it is idle for the whole restore, so the Phase B
         // heartbeat reads the loading backend's state over it (swap-heartbeat.ts).
@@ -526,6 +628,13 @@ export async function dbSwapCommand(flags: Record<string, string>): Promise<void
       if (flags['rebuild-derived'] === 'true') {
         warn(`the derived objects depending on ${schema} were dropped — they do NOT exist until you regenerate them.`);
         warn(`  run now: everystack db:reconcile --apply --stage ${stage ?? '<stage>'} --direct`);
+      } else if (paired.length > 0) {
+        // Say it in the OUTPUT, not just the docs. The two-step "swap then reconcile" was correct
+        // advice for the unpaired swap and is baked into deploy scripts written against it. Run
+        // now, that reconcile drops and recreates the layer the swap just built correctly, holding
+        // ACCESS EXCLUSIVE — turning a zero-downtime swap into an outage. Seen in the field.
+        info(`the derived layer (${paired.join(', ')}) is live and complete — a post-swap db:reconcile is NOT required.`);
+        info(`  if your deploy script still runs one, remove it: it would drop and rebuild these objects under ACCESS EXCLUSIVE and cause the outage this swap exists to avoid.`);
       }
     } else {
       fail(`db:swap ${res.status}: ${res.reason}`);

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(...)