@supabase/pg-delta 1.0.0-alpha.26 → 1.0.0-alpha.28

package/dist/cli/commands/catalog-export.js

@@ -3,6 +3,7 @@
  */
 import { writeFile } from "node:fs/promises";
 import { buildCommand } from "@stricli/core";
+import { filterCatalog } from "../../core/catalog.filter.js";
 import { extractCatalog } from "../../core/catalog.model.js";
 import { serializeCatalog, stringifyCatalogSnapshot, } from "../../core/catalog.snapshot.js";
 import { createManagedPool } from "../../core/postgres-config.js";
@@ -25,6 +26,19 @@ export const catalogExportCommand = buildCommand({
                 parse: String,
                 optional: true,
             },
+            filter: {
+                kind: "parsed",
+                brief: 'Filter DSL as inline JSON to filter changes (e.g., \'{"*/schema": "app"}\').',
+                parse: (value) => {
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch (error) {
+                        throw new Error(`Invalid filter JSON: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                },
+                optional: true,
+            },
         },
         aliases: {
             t: "target",
@@ -43,6 +57,10 @@ Use cases:
   - Snapshot template1 for use as an empty-database baseline
   - Snapshot a production database to generate revert migrations
   - Snapshot any state for reproducible offline diffs
+
+Pass --filter to scope the snapshot to a subset of the catalog (same
+Filter DSL accepted by plan/sync). Useful when committing a baseline
+snapshot to a repo and only one schema's drift is interesting.
     `.trim(),
     },
     async func(flags) {
@@ -52,7 +70,10 @@ Use cases:
         });
         try {
             const catalog = await extractCatalog(pool);
-            const snapshot = serializeCatalog(catalog);
+            const scoped = flags.filter
+                ? await filterCatalog(catalog, flags.filter)
+                : catalog;
+            const snapshot = serializeCatalog(scoped);
             const json = stringifyCatalogSnapshot(snapshot);
             await writeFile(flags.output, json, "utf-8");
             this.process.stdout.write(`Catalog snapshot written to ${flags.output}\n`);

package/dist/core/catalog.diff.js

@@ -138,19 +138,37 @@ export function diffCatalogs(main, branch, options) {
     changes.push(...diffServers(diffContext, main.servers, branch.servers));
     changes.push(...diffUserMappings(main.userMappings, branch.userMappings));
     changes.push(...diffForeignTables(diffContext, main.foreignTables, branch.foreignTables));
-    // Filter privilege REVOKEs for objects that are being dropped
-    // Avoid emitting redundant REVOKE statements for targets that will no longer exist.
+    // Filter privilege changes for objects that are only being dropped.
+    // Avoid emitting redundant ACL statements for targets that will no longer exist.
     const droppedObjectStableIds = new Set();
+    const createdStableIds = new Set();
     for (const change of changes) {
         if (change.operation === "drop" && change.scope === "object") {
             for (const dep of change.requires) {
                 droppedObjectStableIds.add(dep);
             }
         }
+        if (change.operation === "create" && change.scope === "object") {
+            for (const dep of change.creates) {
+                createdStableIds.add(dep);
+            }
+        }
     }
+    // A pure DROP does not need ACL cleanup: the target object is going away.
+    // A replacement is different: it has both DROP and CREATE for the same stable
+    // id, and its privilege ALTERs describe the ACL state of the newly created
+    // object. Keep all of them, including REVOKE/REVOKE GRANT OPTION generated to
+    // subtract privileges inherited from ALTER DEFAULT PRIVILEGES at create time.
+    const replacementStableIds = new Set([...droppedObjectStableIds].filter((id) => createdStableIds.has(id)));
     let filteredChanges = changes.filter((change) => {
         if (change.operation === "alter" && change.scope === "privilege") {
-            return !droppedObjectStableIds.has(getPrivilegeTargetStableId(change));
+            const targetStableId = getPrivilegeTargetStableId(change);
+            // Checking only privilege creates would keep replacement GRANTs but drop
+            // replacement REVOKEs, so preserve by replacement target stable id instead.
+            if (replacementStableIds.has(targetStableId)) {
+                return true;
+            }
+            return !droppedObjectStableIds.has(targetStableId);
         }
         return true;
     });
@@ -158,6 +176,7 @@ export function diffCatalogs(main, branch, options) {
         changes: filteredChanges,
         mainCatalog: main,
         branchCatalog: branch,
+        diffContext,
     });
     filteredChanges = normalizePostDiffChanges({
         changes: expandedDependencies.changes,

package/dist/core/catalog.filter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Prune a catalog to the objects that match a Filter DSL expression.
+ *
+ * The Filter DSL is defined over Change objects, so the catalog is
+ * diffed against an empty baseline first to materialize one CREATE
+ * change per object. The filter then evaluates against the same shape
+ * it would at plan time, and the surviving stableIds drive the prune.
+ *
+ * Dependency cascade is not applied. A scoped snapshot is partial by
+ * design: out-of-scope owners, roles, and types must exist on the
+ * target DB at apply time. Cascading would expand the filter beyond
+ * what the caller asked for and, in practice, collapse schema-scoped
+ * exports whose kept objects reference cluster-scoped owners.
+ */
+import { Catalog } from "./catalog.model.ts";
+import { type FilterDSL } from "./integrations/filter/dsl.ts";
+export declare function filterCatalog(catalog: Catalog, filter: FilterDSL): Promise<Catalog>;

package/dist/core/catalog.filter.js

@@ -0,0 +1,75 @@
+/**
+ * Prune a catalog to the objects that match a Filter DSL expression.
+ *
+ * The Filter DSL is defined over Change objects, so the catalog is
+ * diffed against an empty baseline first to materialize one CREATE
+ * change per object. The filter then evaluates against the same shape
+ * it would at plan time, and the surviving stableIds drive the prune.
+ *
+ * Dependency cascade is not applied. A scoped snapshot is partial by
+ * design: out-of-scope owners, roles, and types must exist on the
+ * target DB at apply time. Cascading would expand the filter beyond
+ * what the caller asked for and, in practice, collapse schema-scoped
+ * exports whose kept objects reference cluster-scoped owners.
+ */
+import { diffCatalogs } from "./catalog.diff.js";
+import { Catalog, createEmptyCatalog } from "./catalog.model.js";
+import { compileFilterDSL } from "./integrations/filter/dsl.js";
+export async function filterCatalog(catalog, filter) {
+    if (typeof filter === "object" &&
+        filter !== null &&
+        filter.cascade === true) {
+        throw new Error("Filter DSL `cascade: true` is not supported by catalog-export: " +
+            "scoped snapshots are intentionally partial. Out-of-scope owners, " +
+            "roles, and types must exist on the target DB at apply time.");
+    }
+    const empty = await createEmptyCatalog(catalog.version, catalog.currentUser);
+    const changes = diffCatalogs(empty, catalog);
+    const filterFn = compileFilterDSL(filter);
+    const keep = new Set();
+    for (const change of changes) {
+        if (!filterFn(change))
+            continue;
+        for (const id of change.creates ?? [])
+            keep.add(id);
+    }
+    return pruneCatalog(catalog, keep);
+}
+function filterRecord(record, keep) {
+    return Object.fromEntries(Object.entries(record).filter(([id]) => keep.has(id)));
+}
+function pruneCatalog(catalog, keep) {
+    const tables = filterRecord(catalog.tables, keep);
+    const materializedViews = filterRecord(catalog.materializedViews, keep);
+    return new Catalog({
+        aggregates: filterRecord(catalog.aggregates, keep),
+        collations: filterRecord(catalog.collations, keep),
+        compositeTypes: filterRecord(catalog.compositeTypes, keep),
+        domains: filterRecord(catalog.domains, keep),
+        enums: filterRecord(catalog.enums, keep),
+        extensions: filterRecord(catalog.extensions, keep),
+        procedures: filterRecord(catalog.procedures, keep),
+        indexes: filterRecord(catalog.indexes, keep),
+        materializedViews,
+        subscriptions: filterRecord(catalog.subscriptions, keep),
+        publications: filterRecord(catalog.publications, keep),
+        rlsPolicies: filterRecord(catalog.rlsPolicies, keep),
+        roles: filterRecord(catalog.roles, keep),
+        schemas: filterRecord(catalog.schemas, keep),
+        sequences: filterRecord(catalog.sequences, keep),
+        tables,
+        triggers: filterRecord(catalog.triggers, keep),
+        eventTriggers: filterRecord(catalog.eventTriggers, keep),
+        rules: filterRecord(catalog.rules, keep),
+        ranges: filterRecord(catalog.ranges, keep),
+        views: filterRecord(catalog.views, keep),
+        foreignDataWrappers: filterRecord(catalog.foreignDataWrappers, keep),
+        servers: filterRecord(catalog.servers, keep),
+        userMappings: filterRecord(catalog.userMappings, keep),
+        foreignTables: filterRecord(catalog.foreignTables, keep),
+        depends: catalog.depends.filter((d) => keep.has(d.dependent_stable_id) && keep.has(d.referenced_stable_id)),
+        indexableObjects: { ...tables, ...materializedViews },
+        version: catalog.version,
+        currentUser: catalog.currentUser,
+    });
+}

package/dist/core/catalog.model.js

@@ -93,7 +93,7 @@ export class Catalog {
 let _pg1516Baseline = null;
 let _pg17Baseline = null;
 async function loadBaselineJson() {
-    const mod = await import("./fixtures/empty-catalogs/postgres-15-16-baseline.json");
+    const mod = await import("./fixtures/empty-catalogs/postgres-15-16-baseline.json", { with: { type: "json" } });
     return mod.default;
 }
 async function getPg1516Baseline() {
@@ -286,6 +286,8 @@ function normalizeCatalog(catalog) {
             options: redactSensitiveOptionPairs(server.options),
             comment: server.comment,
             privileges: server.privileges,
+            wrapper_handler: server.wrapper_handler,
+            wrapper_validator: server.wrapper_validator,
         });
     });
     const userMappings = mapRecord(catalog.userMappings, (mapping) => {
@@ -293,6 +295,8 @@ function normalizeCatalog(catalog) {
             user: mapping.user,
             server: mapping.server,
             options: redactSensitiveOptionPairs(mapping.options),
+            wrapper_handler: mapping.wrapper_handler,
+            wrapper_validator: mapping.wrapper_validator,
         });
     });
     const foreignTables = mapRecord(catalog.foreignTables, (foreignTable) => new ForeignTable({
@@ -304,6 +308,8 @@ function normalizeCatalog(catalog) {
         options: redactSensitiveOptionPairs(foreignTable.options),
         comment: foreignTable.comment,
         privileges: foreignTable.privileges,
+        wrapper_handler: foreignTable.wrapper_handler,
+        wrapper_validator: foreignTable.wrapper_validator,
     }));
     const subscriptions = mapRecord(catalog.subscriptions, (subscription) => {
         return new Subscription({

package/dist/core/expand-replace-dependencies.d.ts

@@ -1,5 +1,6 @@
 import type { Catalog } from "./catalog.model.ts";
 import type { Change } from "./change.types.ts";
+import type { ObjectDiffContext } from "./objects/diff-context.ts";
 /**
  * For objects we are replacing (drop + create), ensure that any dependents are also
  * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
@@ -12,9 +13,10 @@ interface ExpandReplaceDependenciesResult {
     changes: Change[];
     replacedTableIds: ReadonlySet<string>;
 }
-export declare function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }: {
+export declare function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, diffContext, }: {
     changes: Change[];
     mainCatalog: Catalog;
     branchCatalog: Catalog;
+    diffContext?: Pick<ObjectDiffContext, "version" | "currentUser" | "defaultPrivilegeState">;
 }): ExpandReplaceDependenciesResult;
 export {};

package/dist/core/expand-replace-dependencies.js

@@ -4,8 +4,12 @@ import { CreateIndex } from "./objects/index/changes/index.create.js";
 import { DropIndex } from "./objects/index/changes/index.drop.js";
 import { CreateMaterializedView } from "./objects/materialized-view/changes/materialized-view.create.js";
 import { DropMaterializedView } from "./objects/materialized-view/changes/materialized-view.drop.js";
+import { buildCreateMaterializedViewChanges } from "./objects/materialized-view/materialized-view.diff.js";
 import { CreateProcedure } from "./objects/procedure/changes/procedure.create.js";
 import { DropProcedure } from "./objects/procedure/changes/procedure.drop.js";
+import { CreateCommentOnRlsPolicy } from "./objects/rls-policy/changes/rls-policy.comment.js";
+import { CreateRlsPolicy } from "./objects/rls-policy/changes/rls-policy.create.js";
+import { DropRlsPolicy } from "./objects/rls-policy/changes/rls-policy.drop.js";
 import { AlterTableAddConstraint } from "./objects/table/changes/table.alter.js";
 import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
 import { CreateTable } from "./objects/table/changes/table.create.js";
@@ -19,7 +23,8 @@ import { DropRange } from "./objects/type/range/changes/range.drop.js";
 import { stableId } from "./objects/utils.js";
 import { CreateView } from "./objects/view/changes/view.create.js";
 import { DropView } from "./objects/view/changes/view.drop.js";
-export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }) {
+import { buildCreateViewChanges } from "./objects/view/view.diff.js";
+export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, diffContext, }) {
     const createdIds = new Set();
     const droppedIds = new Set();
     for (const change of changes) {
@@ -34,6 +39,15 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
             replaceRoots.add(id);
         }
     }
+    const promotedRlsPolicyIds = new Set();
+    const additions = collectInvalidatedRlsPolicyReplacements({
+        changes,
+        mainCatalog,
+        branchCatalog,
+        createdIds,
+        droppedIds,
+        promotedRlsPolicyIds,
+    });
     // Procedure stableIds are signature-qualified
     // (`procedure:schema.name(argtypes)`), so a function whose parameter types
     // change has different ids in `createdIds` and `droppedIds` and would not
@@ -76,7 +90,7 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
             replaceRoots.add(id);
         }
     }
-    if (replaceRoots.size === 0) {
+    if (replaceRoots.size === 0 && additions.length === 0) {
         return {
             changes,
             replacedTableIds: new Set(),
@@ -92,7 +106,6 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         }
         list.add(dep.dependent_stable_id);
     }
-    const additions = [];
     const visitedTargets = new Set();
     const visitedRefs = new Set(replaceRoots);
     const queue = [...replaceRoots];
@@ -144,10 +157,14 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
             const replacementChanges = buildReplaceChanges(resolved, {
                 addDrop,
                 addCreate,
+                diffContext,
             });
             if (!replacementChanges)
                 continue;
             additions.push(...replacementChanges);
+            if (resolved.kind === "rls_policy") {
+                promotedRlsPolicyIds.add(targetId);
+            }
             // If we added a DropTable(T) for an existing table, mark T so any
             // pre-existing object-scope AlterTable*(T) changes get dropped below —
             // the DropTable+CreateTable pair supersedes all structural alterations.
@@ -170,10 +187,70 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         };
     }
     return {
-        changes: [...changes, ...additions],
+        changes: [
+            ...removeSupersededRlsPolicyAlters(changes, promotedRlsPolicyIds),
+            ...additions,
+        ],
         replacedTableIds: tablesReplacedByExpansion,
     };
 }
+function collectInvalidatedRlsPolicyReplacements({ changes, mainCatalog, branchCatalog, createdIds, droppedIds, promotedRlsPolicyIds, }) {
+    // In-place rewrites report stable ids through `invalidates`: the referenced
+    // object keeps its identity, but dependents bound to the old definition must
+    // be torn down first. RLS policy expressions are tracked in pg_depend, so use
+    // those catalog edges to promote only policies that depend on an invalidated
+    // id, without coupling this expansion pass to a concrete table-change class.
+    const invalidatedIds = new Set();
+    for (const change of changes) {
+        for (const invalidatedId of change.invalidates) {
+            invalidatedIds.add(invalidatedId);
+        }
+    }
+    if (invalidatedIds.size === 0)
+        return [];
+    const replacements = [];
+    for (const dep of mainCatalog.depends) {
+        if (!invalidatedIds.has(dep.referenced_stable_id))
+            continue;
+        const targetId = normalizeDependentId(dep.dependent_stable_id);
+        if (!targetId?.startsWith("rlsPolicy:"))
+            continue;
+        if (promotedRlsPolicyIds.has(targetId))
+            continue;
+        if (createdIds.has(targetId) && droppedIds.has(targetId))
+            continue;
+        const resolved = resolveObjectForStableId(targetId, mainCatalog, branchCatalog);
+        if (!resolved || resolved.kind !== "rls_policy")
+            continue;
+        const addDrop = !droppedIds.has(targetId);
+        const addCreate = !createdIds.has(targetId);
+        const replacementChanges = buildReplaceChanges(resolved, {
+            addDrop,
+            addCreate,
+        });
+        if (!replacementChanges)
+            continue;
+        replacements.push(...replacementChanges);
+        promotedRlsPolicyIds.add(targetId);
+        for (const change of replacementChanges) {
+            for (const id of change.creates ?? [])
+                createdIds.add(id);
+            for (const id of change.drops ?? [])
+                droppedIds.add(id);
+        }
+    }
+    return replacements;
+}
+function removeSupersededRlsPolicyAlters(changes, promotedRlsPolicyIds) {
+    if (promotedRlsPolicyIds.size === 0)
+        return changes;
+    return changes.filter((change) => {
+        if (change.objectType !== "rls_policy" || change.operation !== "alter") {
+            return true;
+        }
+        return !promotedRlsPolicyIds.has(change.policy.stableId);
+    });
+}
 function isOwnedSequenceColumnDependency(referencedId, dependentId, mainCatalog, branchCatalog) {
     // When a sequence replace root is still OWNED BY the same column, the
     // sequence->column pg_depend edge is bookkeeping for ownership, not a signal
@@ -264,6 +341,11 @@ function resolveObjectForStableId(stableId, mainCatalog, branchCatalog) {
         const branch = branchCatalog.procedures[stableId];
         return main && branch ? { kind: "procedure", main, branch } : null;
     }
+    if (stableId.startsWith("rlsPolicy:")) {
+        const main = mainCatalog.rlsPolicies[stableId];
+        const branch = branchCatalog.rlsPolicies[stableId];
+        return main && branch ? { kind: "rls_policy", main, branch } : null;
+    }
     if (stableId.startsWith("domain:")) {
         const main = mainCatalog.domains[stableId];
         const branch = branchCatalog.domains[stableId];
@@ -293,7 +375,7 @@ function resolveObjectForStableId(stableId, mainCatalog, branchCatalog) {
     return null;
 }
 function buildReplaceChanges(resolved, options) {
-    const { addDrop, addCreate } = options;
+    const { addDrop, addCreate, diffContext } = options;
     if (!addDrop && !addCreate)
         return null;
     switch (resolved.kind) {
@@ -327,7 +409,9 @@ function buildReplaceChanges(resolved, options) {
         case "view":
             return [
                 ...(addDrop ? [new DropView({ view: resolved.main })] : []),
-                ...(addCreate ? [new CreateView({ view: resolved.branch })] : []),
+                ...(addCreate
+                    ? buildCreateViewReplacementChanges(resolved.branch, diffContext)
+                    : []),
             ];
         case "materialized_view":
             return [
@@ -335,7 +419,13 @@ function buildReplaceChanges(resolved, options) {
                     ? [new DropMaterializedView({ materializedView: resolved.main })]
                     : []),
                 ...(addCreate
-                    ? [new CreateMaterializedView({ materializedView: resolved.branch })]
+                    ? diffContext
+                        ? buildCreateMaterializedViewChanges(diffContext, resolved.branch)
+                        : [
+                            new CreateMaterializedView({
+                                materializedView: resolved.branch,
+                            }),
+                        ]
                     : []),
             ];
         case "index":
@@ -373,6 +463,18 @@ function buildReplaceChanges(resolved, options) {
                     ? [new CreateProcedure({ procedure: resolved.branch })]
                     : []),
             ];
+        case "rls_policy":
+            return [
+                ...(addDrop ? [new DropRlsPolicy({ policy: resolved.main })] : []),
+                ...(addCreate
+                    ? [
+                        new CreateRlsPolicy({ policy: resolved.branch }),
+                        ...(resolved.branch.comment !== null
+                            ? [new CreateCommentOnRlsPolicy({ policy: resolved.branch })]
+                            : []),
+                    ]
+                    : []),
+            ];
         case "enum":
             return [
                 ...(addDrop ? [new DropEnum({ enum: resolved.main })] : []),
@@ -401,3 +503,11 @@ function buildReplaceChanges(resolved, options) {
             return null;
     }
 }
+function buildCreateViewReplacementChanges(view, diffContext) {
+    // Dependency-closure replacements synthesize a create without going through
+    // `diffViews`, so replay the same owner/comment/security-label/ACL metadata
+    // that a normal non-alterable view replacement would emit.
+    return diffContext
+        ? buildCreateViewChanges(diffContext, view)
+        : [new CreateView({ view })];
+}

package/dist/core/integrations/supabase.js

@@ -120,6 +120,30 @@ export const supabase = {
                             "trigger/function_schema": [...SUPABASE_SYSTEM_SCHEMAS],
                         },
                     },
+                    // Defensive fallback for dynamically-created pgmq queue /
+                    // archive tables. `pgmq.q_<name>` and `pgmq.a_<name>` are
+                    // materialized by `select pgmq.create('<name>')`, NOT by
+                    // `CREATE EXTENSION pgmq`, so emitting a user trigger against
+                    // them fails locally with
+                    // `relation "pgmq.q_<name>" does not exist`. On a healthy
+                    // install the trigger extractor's `extension_table_oids` join
+                    // (packages/pg-delta/src/core/objects/trigger/trigger.model.ts)
+                    // already drops these via the `pg_depend deptype='e'` row pgmq
+                    // records during `pgmq.create()`; this rule covers projects
+                    // where that row is missing (older pgmq, manual table
+                    // rewrites, `pg_dump`/restore that loses extension deps, ...).
+                    // pgmq 1.4.4 — the version Supabase Cloud currently ships —
+                    // does not record the dependency at all.
+                    {
+                        not: {
+                            and: [
+                                { "trigger/schema": "pgmq" },
+                                {
+                                    "trigger/table_name": { op: "regex", value: "^[qa]_" },
+                                },
+                            ],
+                        },
+                    },
                 ],
             },
             // Exclude system objects
@@ -180,15 +204,25 @@ export const supabase = {
                             ],
                         },
                         // Platform-managed foreign data wrappers — Wasm-based FDWs
-                        // (e.g. `clerk`, `clerk_oauth`) whose handler/validator live in
-                        // the `extensions` schema. `CREATE FOREIGN DATA WRAPPER`
-                        // requires superuser, and Supabase Cloud provisions these via
-                        // `supabase_admin` at project creation; replaying the DDL
-                        // against a local image fails because the local environment
-                        // has no equivalent pre-step. We can't rely on the FDW owner
-                        // alone — after a dump/restore the owner is often rewritten
-                        // away from `supabase_admin` — so match on the function
-                        // reference instead.
+                        // (e.g. `clerk`, `clerk_oauth`) provisioned via the `wrappers`
+                        // extension. Supabase Cloud creates these as
+                        // `CREATE FOREIGN DATA WRAPPER clerk_oauth HANDLER
+                        // extensions.wasm_fdw_handler VALIDATOR
+                        // extensions.wasm_fdw_validator` at project creation; replaying
+                        // the DDL against a local image fails because the local
+                        // environment has no equivalent pre-step. We can't rely on the
+                        // FDW owner alone — after a dump/restore the owner is often
+                        // rewritten away from `supabase_admin` — so match on the shared
+                        // Wasm handler/validator (`extensions.wasm_fdw_handler` /
+                        // `extensions.wasm_fdw_validator`) instead.
+                        //
+                        // Matching the bare `extensions.*` namespace would be too broad:
+                        // contrib FDWs like `postgres_fdw` also install their
+                        // handler/validator into `extensions` on Supabase, and those ARE
+                        // available in the local image, so a user-created `postgres_fdw`
+                        // wrapper (and its servers/foreign tables/user mappings) must
+                        // still roundtrip. Keying on the `wasm_fdw_*` function names
+                        // targets only the platform Wasm wrappers.
                         {
                             and: [
                                 { objectType: "foreign_data_wrapper" },
@@ -197,13 +231,70 @@ export const supabase = {
                                         {
                                             "foreign_data_wrapper/handler": {
                                                 op: "regex",
-                                                value: "^extensions\\.",
+                                                value: "^extensions\\.wasm_fdw_handler$",
                                             },
                                         },
                                         {
                                             "foreign_data_wrapper/validator": {
                                                 op: "regex",
-                                                value: "^extensions\\.",
+                                                value: "^extensions\\.wasm_fdw_validator$",
+                                            },
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                        // Platform-managed Wasm FDW dependents (CLI-1470 follow-up).
+                        // Suppressing the wrapper DDL alone leaves `CREATE SERVER` /
+                        // `CREATE FOREIGN TABLE` / `CREATE USER MAPPING` that reference
+                        // a wrapper local Docker never provisions (`clerk_oauth`, etc.).
+                        // Match on the parent wrapper's Wasm handler/validator
+                        // (`extensions.wasm_fdw_handler` / `extensions.wasm_fdw_validator`,
+                        // joined at extract time) — the same discriminator used for the
+                        // wrapper itself above. A bare `extensions.*` match would also
+                        // drop user-created `postgres_fdw` servers/foreign tables/user
+                        // mappings (whose handler installs into `extensions` but which
+                        // the local image CAN provision), so keep it scoped to the Wasm
+                        // function names. Server _privilege_ scope is excluded here —
+                        // `GRANT/REVOKE ON SERVER` does not require superuser and remains
+                        // user-declarative state (see CLI-1469 companion test).
+                        {
+                            and: [
+                                { objectType: "server" },
+                                { not: { scope: "privilege" } },
+                                {
+                                    or: [
+                                        {
+                                            "{server,foreign_table,user_mapping}/wrapper_handler": {
+                                                op: "regex",
+                                                value: "^extensions\\.wasm_fdw_handler$",
+                                            },
+                                        },
+                                        {
+                                            "{server,foreign_table,user_mapping}/wrapper_validator": {
+                                                op: "regex",
+                                                value: "^extensions\\.wasm_fdw_validator$",
+                                            },
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                        {
+                            and: [
+                                { objectType: ["foreign_table", "user_mapping"] },
+                                {
+                                    or: [
+                                        {
+                                            "{server,foreign_table,user_mapping}/wrapper_handler": {
+                                                op: "regex",
+                                                value: "^extensions\\.wasm_fdw_handler$",
+                                            },
+                                        },
+                                        {
+                                            "{server,foreign_table,user_mapping}/wrapper_validator": {
+                                                op: "regex",
+                                                value: "^extensions\\.wasm_fdw_validator$",
                                             },
                                         },
                                     ],

package/dist/core/objects/base.change.d.ts

@@ -39,6 +39,18 @@ export declare abstract class BaseChange {
      * Defaults to an empty array. Override in subclasses that remove objects.
      */
     get drops(): string[];
+    /**
+     * Stable identifiers this change invalidates in place.
+     *
+     * Unlike `drops`, the object keeps its identity. This is an ordering-only
+     * signal for mutations that rewrite an existing object in a way that requires
+     * dependents bound to the old definition to be dropped before the mutation
+     * and rebuilt afterward.
+     *
+     * Defaults to an empty array. Override in subclasses that invalidate
+     * dependents without dropping the object.
+     */
+    get invalidates(): string[];
     /**
      * Stable identifiers this change requires to exist beforehand.
      *

package/dist/core/objects/base.change.js

@@ -31,6 +31,20 @@ export class BaseChange {
     get drops() {
         return [];
     }
+    /**
+     * Stable identifiers this change invalidates in place.
+     *
+     * Unlike `drops`, the object keeps its identity. This is an ordering-only
+     * signal for mutations that rewrite an existing object in a way that requires
+     * dependents bound to the old definition to be dropped before the mutation
+     * and rebuilt afterward.
+     *
+     * Defaults to an empty array. Override in subclasses that invalidate
+     * dependents without dropping the object.
+     */
+    get invalidates() {
+        return [];
+    }
     /**
      * Stable identifiers this change requires to exist beforehand.
      *