fix(migrate): --allow adopt-view no longer emits illegal CREATE OR REPLACE VIEW (#239)

The adopt-view branch (a Postgres DB view with no MetaObjects fingerprint — created
before view stamping, or hand-written) pushed `replace-view` unconditionally, so a
view that was BOTH being adopted AND structurally changed (column rename / reorder /
mid-insert) in the same migration emitted `CREATE OR REPLACE VIEW`. Postgres rejects
that at apply time (`cannot change name of view column …`), aborting the migration on
any DB that already holds the prior view. Invisible until apply: offline migrate and a
fresh DB (where CREATE OR REPLACE behaves as CREATE) never hit it.

The adopt branch now routes through the same `viewReplaceIsLegal` decision the managed
path makes (`pushViewUpdate(v, a, changes, /* unmanaged */ true)`): a legal append stays
a non-destructive `replace-view`; a structural change is emitted as `drop-view` +
`create-view` (the recreated view is re-stamped, so the next migrate converges).
Adopting an unmanaged view still requires `allow.adoptView` in BOTH cases — the drop+
create carries the adopt-view gate (`unmanagedActual` on the drop-view), checked in
status.ts BEFORE the recreate-pair auto-allow so it can't silently clobber hand-written
SQL. SQLite/D1 unaffected (they always drop+create); the emit `orReplace` invariant
(OR REPLACE only for a legal `replace-view`) is restored.

TS-only (schema migrations are TS-owned, ADR-0015). Gated by unit + emit tests and a
real-Postgres round-trip (hold prior unmanaged view → diff → emit → APPLY → re-diff==[]).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014xy8powhHYJ6gfFt9Ut8dL

Author: dmealing

CHANGELOG.md

@@ -5,6 +5,30 @@ here. The format follows [Keep a Changelog](https://keepachangelog.com/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 (pre-1.0; MINOR bumps may introduce breaking changes with notice).
 
+## [Unreleased]
+
+### Fixed — `--allow adopt-view` no longer emits an illegal `CREATE OR REPLACE VIEW` (#239)
+
+**npm-only** (`migrate-ts` + `cli`; schema migrations are TS-owned, ADR-0015 — NuGet / PyPI /
+Maven have no migrate engine). `meta migrate --allow adopt-view` emitted `CREATE OR REPLACE
+VIEW` when adopting an **unmanaged** Postgres view (one with no MetaObjects fingerprint —
+created before view stamping, or hand-written) that was **also** structurally changed in the
+same migration (column rename / reorder / mid-list insert). Postgres rejects that DDL at apply
+time (`cannot change name of view column …`), aborting the migration on any DB that already
+holds the prior view. It was invisible until apply: offline `meta migrate` and a freshly
+provisioned DB (where `CREATE OR REPLACE` behaves as a plain `CREATE`) never hit it — it bites
+exactly once per project, on the first migration authored after upgrading into view
+fingerprinting.
+
+The adopt-view branch now runs the **same** legal/illegal `CREATE OR REPLACE` decision the
+managed path already made (`viewReplaceIsLegal`): a legal append stays a non-destructive
+`replace-view`; a structural change is emitted as `drop-view` + `create-view` (the recreated
+view is re-stamped, so the next migrate converges). Adopting an unmanaged view still requires
+`allow.adoptView` in both cases — the drop+create path carries the adopt-view gate so the
+recreate-pair auto-allow can't silently clobber hand-written SQL. Gated by unit + emit tests
+and a real-Postgres round-trip (`hold prior unmanaged view → diff → emit → APPLY → re-diff ==
+[]`). Generated-output change — regenerate to pick it up; three-way merge preserves hand edits.
+
 ## [0.20.3] — 2026-07-25
 
 **Coordinated release** — npm `0.20.3` · PyPI `0.19.6` · Maven Central `7.11.4` · NuGet

server/typescript/packages/migrate-ts/src/diff/index.ts

@@ -558,12 +558,14 @@ function diffViews(
       // existed, OR somebody's hand-written SQL sitting at a projection's name — and on
       // Postgres those are indistinguishable, because the deparser destroyed the text
       // evidence. Overwriting the second destroys work nothing can restore, so fail
-      // closed: propose the replace but BLOCK it pending `allow.adoptView`.
+      // closed: propose the adoption but BLOCK it pending `allow.adoptView`.
+      //
+      // #239: route through the SAME legal/illegal OR-REPLACE decision the managed
+      // path makes — a structural change (rename/reorder/mid-insert) is not a legal
+      // CREATE OR REPLACE and must be drop+create. `unmanaged: true` carries the
+      // adopt-view gate onto whichever change kind we emit.
       if (a.fingerprint === undefined) {
-        changes.push({
-          kind: "replace-view", view: v, ...schemaSpread(v.schema),
-          restore: a, unmanagedActual: true, status: ALLOWED,
-        });
+        pushViewUpdate(v, a, changes, /* unmanaged */ true);
         continue;
       }
 
@@ -602,16 +604,23 @@ function diffViews(
  * view's columns come out in projection DECLARATION order, so a field APPENDED to a
  * projection lands last, which is exactly what Postgres's prefix rule permits.
  */
-function pushViewUpdate(expected: ViewDescriptor, actual: ViewDescriptor, changes: Change[]): void {
+function pushViewUpdate(
+  expected: ViewDescriptor, actual: ViewDescriptor, changes: Change[],
+  // #239: when the ACTUAL view is unmanaged (no fingerprint), this is an ADOPTION —
+  // stamp the adopt-view gate (`unmanagedActual`) onto whichever change we emit so
+  // status.ts fails closed on `allow.adoptView`, legal-replace and drop+create alike.
+  unmanaged = false,
+): void {
   const sx = schemaSpread(expected.schema);
+  const adopt = unmanaged ? { unmanagedActual: true as const } : {};
   if (viewReplaceIsLegal(expected.columns, actual.columns)) {
-    changes.push({ kind: "replace-view", view: expected, ...sx, restore: actual, status: ALLOWED });
+    changes.push({ kind: "replace-view", view: expected, ...sx, restore: actual, ...adopt, status: ALLOWED });
     return;
   }
   // The column list changed shape (removed / renamed / reordered / retyped), so
   // Postgres refuses OR REPLACE. The view must be dropped and rebuilt — which is
   // destructive to anything depending on it (annotateViewDropDependents makes that loud).
-  changes.push({ kind: "drop-view", view: expected.name, ...sx, restore: actual, status: ALLOWED });
+  changes.push({ kind: "drop-view", view: expected.name, ...sx, restore: actual, ...adopt, status: ALLOWED });
   changes.push({ kind: "create-view", view: expected, ...sx, status: ALLOWED });
 }
 

server/typescript/packages/migrate-ts/src/diff/status.ts

@@ -70,6 +70,16 @@ function blockedReasonFor(
           + `(${external.map((d) => `${d.schema}.${d.name}`).join(", ")}) `
           + `— pass allow.dropViewCascade to destroy them, or migrate them off this view first`;
       }
+      // #239: the drop half of ADOPTING an unmanaged view (no fingerprint) whose shape
+      // changed too much for a legal CREATE OR REPLACE. It is paired with a create-view,
+      // so the recreate-pair rule below would auto-allow it — but clobbering (possibly
+      // hand-written) SQL needs explicit consent, exactly like the replace-view adopt
+      // path. Gate on allow.adoptView BEFORE the recreate-pair auto-allow.
+      if (c.unmanagedActual && !allow.adoptView) {
+        return `existing view "${c.view}" carries no MetaObjects fingerprint — it is hand-written, `
+          + `or was created before view fingerprinting. Its shape changed, so adopting it means `
+          + `DROP + rebuild, which takes ownership and cannot be undone. Pass allow.adoptView to adopt it`;
+      }
       // Identity, not bare name — see viewIdentity().
       if (recreatedViews.has(viewIdentity(c.view, c.schema))) return null; // recreate pair — view survives
       return allow.dropView ? null : "destructive: drop-view not allowed (pass allow.dropView)";

server/typescript/packages/migrate-ts/src/types.ts

@@ -243,6 +243,15 @@ export type Change =
        * do not manage — so this is blocked pending `allow.dropViewCascade`.
        */
       dependents?: readonly DependentRelation[];
+      /**
+       * This drop is the drop half of adopting an UNMANAGED view (no fingerprint)
+       * whose shape changed too much for a legal `CREATE OR REPLACE` (#239). It is
+       * paired with a `create-view`, so the recreate-pair rule would normally
+       * auto-allow it — but clobbering (possibly hand-written) SQL still needs
+       * explicit consent, so status.ts gates it on `allow.adoptView`, exactly like
+       * the `replace-view` adopt path.
+       */
+      unmanagedActual?: boolean;
     }
   | {
       kind: "replace-view";

server/typescript/packages/migrate-ts/test/integration/pg-adopt-view-239.test.ts

@@ -0,0 +1,93 @@
+/**
+ * PG round-trip — #239: adopting an UNMANAGED view (no fingerprint) whose shape
+ * changed too much for a legal `CREATE OR REPLACE` must be emitted as DROP+CREATE,
+ * and it must APPLY cleanly against a DB that already holds the prior view.
+ *
+ * The bug: the adopt-view branch pushed `replace-view` unconditionally, so a renamed
+ * output column emitted `CREATE OR REPLACE VIEW` — which Postgres rejects at apply
+ * ("cannot change name of view column"). Invisible until apply (offline migrate /
+ * a fresh DB where CREATE OR REPLACE behaves as CREATE never hit it).
+ *
+ * Acceptance gate (per the migrate round-trip discipline):
+ *   hold the prior unmanaged view → diff (adoptView) → emit → APPLY → re-diff == [].
+ *
+ * Skips gracefully when MIGRATE_TS_PG_URL is not set.
+ */
+
+import { test, expect, beforeAll, afterAll, describe } from "bun:test";
+import { Pool } from "pg";
+import { Kysely, PostgresDialect, sql } from "kysely";
+import { introspectPostgres } from "../../src/introspect/postgres.js";
+import { diff } from "../../src/diff/index.js";
+import { emit } from "../../src/emit/index.js";
+import { viewFingerprint } from "../../src/view-fingerprint.js";
+import type { SchemaSnapshot } from "../../src/types.js";
+
+const PG_URL = process.env["MIGRATE_TS_PG_URL"];
+
+async function applyRaw(k: Kysely<Record<string, unknown>>, sqlText: string): Promise<void> {
+  for (const stmt of sqlText.split(";").map((s) => s.trim()).filter((s) => s.length > 0)) {
+    await sql.raw(stmt).execute(k);
+  }
+}
+
+describe("PG adopt-view structural change round-trip (#239)", () => {
+  if (!PG_URL) {
+    test.skip("skipped — MIGRATE_TS_PG_URL not set", () => {});
+    return;
+  }
+
+  let kysely: Kysely<Record<string, unknown>>;
+  let pool: Pool;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: PG_URL });
+    kysely = new Kysely<Record<string, unknown>>({ dialect: new PostgresDialect({ pool }) });
+    await sql.raw(`DROP VIEW IF EXISTS v_foo CASCADE`).execute(kysely);
+    await sql.raw(`DROP TABLE IF EXISTS t_239 CASCADE`).execute(kysely);
+    await sql.raw(`CREATE TABLE t_239 (a text, b text)`).execute(kysely);
+    // An UNMANAGED view: NO metaobjects fingerprint COMMENT (pre-fingerprint / hand-written).
+    await sql.raw(`CREATE VIEW v_foo AS SELECT t_239.a AS a, t_239.b AS b FROM t_239`).execute(kysely);
+  });
+
+  afterAll(async () => {
+    await sql.raw(`DROP VIEW IF EXISTS v_foo CASCADE`).execute(kysely);
+    await sql.raw(`DROP TABLE IF EXISTS t_239 CASCADE`).execute(kysely);
+    await pool.end();
+  });
+
+  test("renamed output column: adopt via DROP+CREATE, applies clean, re-diff empty", async () => {
+    const actual = await introspectPostgres(kysely);
+    // Metadata renames the second output column b → c (a structural change).
+    const body = `SELECT t_239.a AS a, t_239.b AS c FROM t_239`;
+    const expectedView = {
+      name: "v_foo",
+      sql: body,
+      fingerprint: viewFingerprint(body),
+      columns: [
+        { name: "a", sqlType: { kind: "text" as const } },
+        { name: "c", sqlType: { kind: "text" as const } },
+      ],
+      dependsOn: ["t_239"],
+    };
+    const expected: SchemaSnapshot = { tables: actual.tables, views: [expectedView] };
+
+    const r = await diff(expected, actual, { dialect: "postgres", allow: { adoptView: true } });
+    // The fix: a structural adoption is DROP+CREATE, never an illegal OR-REPLACE.
+    expect(r.changes.find((c) => c.kind === "replace-view")).toBeUndefined();
+    expect(r.changes.find((c) => c.kind === "drop-view")).toBeDefined();
+    expect(r.blocked).toEqual([]);
+
+    const up = emit(r.changes, { dialect: "postgres" }).up;
+    expect(up).not.toMatch(/CREATE OR REPLACE VIEW/i);
+
+    // Apply against the DB that ALREADY HOLDS the prior view — the bug threw HERE
+    // with "cannot change name of view column b to c".
+    await applyRaw(kysely, up);
+
+    // Converged: the view is now fingerprint-stamped, so a re-diff is empty.
+    const actual2 = await introspectPostgres(kysely);
+    const r2 = await diff({ tables: actual2.tables, views: [expectedView] }, actual2, { dialect: "postgres" });
+    expect(r2.changes.filter((c) => c.kind.endsWith("-view"))).toEqual([]);
+  });
+});

server/typescript/packages/migrate-ts/test/unit/diff.test.ts

@@ -1,5 +1,6 @@
 import { test, expect, describe } from "bun:test";
 import { diff } from "../../src/diff/index.js";
+import { emit } from "../../src/emit/index.js";
 import type { SchemaSnapshot, ColumnDescriptor } from "../../src/types.js";
 
 const empty: SchemaSnapshot = { tables: [], views: [] };
@@ -137,3 +138,93 @@ describe("diff — view-body drift", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// #239 — the Postgres adopt-view branch (DB view carries no fingerprint) must
+// make the SAME legal/illegal OR-REPLACE decision the managed path makes.
+// A structural change (rename / reorder / mid-insert) is NOT a legal
+// CREATE OR REPLACE, so it must be emitted as drop-view + create-view — and the
+// adoption of an unmanaged view still requires allow.adoptView (the recreate-pair
+// auto-allow must not wave through clobbering hand-written SQL).
+// ---------------------------------------------------------------------------
+describe("diff — Postgres adopt-view legality (#239)", () => {
+  const T = { kind: "text" as const };
+  // A view metadata (expected) side always carries a fingerprint.
+  const expView = (cols: string[]) => ({
+    name: "v_foo",
+    sql: `SELECT ${cols.map((c) => `t.${c} AS ${c}`).join(", ")} FROM t`,
+    fingerprint: "a".repeat(64), // raw sha256-hex; renderFingerprintMarker adds the prefix
+    columns: cols.map((name) => ({ name, sqlType: T })),
+  });
+  // The DB (actual) side has NO fingerprint — pre-fingerprint or hand-written.
+  const dbView = (cols: string[]) => ({
+    name: "v_foo",
+    sql: `SELECT ${cols.map((c) => `t.${c} AS ${c}`).join(", ")} FROM t`,
+    columns: cols.map((name) => ({ name, sqlType: T })),
+  });
+  const opts = (adoptView = false) => ({ dialect: "postgres" as const, allow: { adoptView } });
+
+  test("STRUCTURAL change (renamed output column) → drop-view + create-view, NOT replace-view", async () => {
+    // DB view outputs (a, b); metadata renames b→c → columns (a, c). Postgres cannot
+    // OR-REPLACE a column rename ("cannot change name of view column").
+    const r = await diff(
+      { tables: [], views: [expView(["a", "c"])] },
+      { tables: [], views: [dbView(["a", "b"])] },
+      opts(true),
+    );
+    expect(r.changes.find((c) => c.kind === "replace-view")).toBeUndefined();
+    expect(r.changes.find((c) => c.kind === "drop-view")).toMatchObject({ kind: "drop-view", view: "v_foo" });
+    expect(r.changes.find((c) => c.kind === "create-view")).toMatchObject({
+      kind: "create-view", view: { name: "v_foo" },
+    });
+  });
+
+  test("adopting an unmanaged view via drop+create STILL requires allow.adoptView", async () => {
+    // Without allow.adoptView the drop must be BLOCKED — the recreate-pair auto-allow
+    // must not silently clobber the (possibly hand-written) unmanaged view.
+    const r = await diff(
+      { tables: [], views: [expView(["a", "c"])] },
+      { tables: [], views: [dbView(["a", "b"])] },
+      opts(false),
+    );
+    const dropv = r.changes.find((c) => c.kind === "drop-view");
+    expect(dropv?.status.state).toBe("blocked");
+    // With allow.adoptView → allowed.
+    const r2 = await diff(
+      { tables: [], views: [expView(["a", "c"])] },
+      { tables: [], views: [dbView(["a", "b"])] },
+      opts(true),
+    );
+    expect(r2.changes.find((c) => c.kind === "drop-view")?.status.state).toBe("allowed");
+  });
+
+  test("PURE APPEND (columns are a prefix) is still a legal replace-view (unmanagedActual)", async () => {
+    // DB (a, b); metadata (a, b, c) — c appended. Legal OR-REPLACE → replace-view,
+    // still gated on adoptView.
+    const r = await diff(
+      { tables: [], views: [expView(["a", "b", "c"])] },
+      { tables: [], views: [dbView(["a", "b"])] },
+      opts(true),
+    );
+    expect(r.changes.find((c) => c.kind === "replace-view")).toMatchObject({
+      kind: "replace-view", view: { name: "v_foo" }, unmanagedActual: true,
+    });
+    expect(r.changes.find((c) => c.kind === "drop-view")).toBeUndefined();
+  });
+
+  test("emitted up.sql for a structural adoption is DROP+CREATE (no illegal CREATE OR REPLACE)", async () => {
+    // The bug's symptom: `CREATE OR REPLACE VIEW` for a rename fails at apply on a DB
+    // that already holds the prior view. The fix emits DROP VIEW + CREATE VIEW + a
+    // fingerprint COMMENT (so the next migrate converges).
+    const r = await diff(
+      { tables: [], views: [expView(["a", "c"])] },
+      { tables: [], views: [dbView(["a", "b"])] },
+      opts(true),
+    );
+    const up = emit(r.changes, { dialect: "postgres" }).up;
+    expect(up).not.toMatch(/CREATE OR REPLACE VIEW/i);
+    expect(up).toMatch(/DROP VIEW/i);
+    expect(up).toMatch(/CREATE VIEW/i);
+    expect(up).toMatch(/COMMENT ON VIEW .* IS 'metaobjects:/i);
+  });
+});