@supabase/pg-delta 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/core/post-diff-normalization.js

@@ -0,0 +1,202 @@
+import { CreateIndex } from "./objects/index/changes/index.create.js";
+import { DropIndex } from "./objects/index/changes/index.drop.js";
+import { AlterTableAddConstraint, AlterTableDropColumn, AlterTableDropConstraint, AlterTableSetReplicaIdentity, AlterTableValidateConstraint, } from "./objects/table/changes/table.alter.js";
+import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (!(change instanceof AlterTableDropColumn) &&
+        !(change instanceof AlterTableDropConstraint)) {
+        return false;
+    }
+    return replacedTableIds.has(change.table.stableId);
+}
+/**
+ * Drop earlier duplicates of `AlterTableAddConstraint` /
+ * `AlterTableValidateConstraint` / `CreateCommentOnConstraint` targeting
+ * replaced tables, keeping only the last occurrence of each
+ * `(changeType, table.stableId, constraint.name)`.
+ *
+ * When `expandReplaceDependencies()` promotes a table to a full
+ * `DropTable + CreateTable` pair, it also emits one
+ * `AlterTableAddConstraint` (plus optional `VALIDATE CONSTRAINT` /
+ * `COMMENT ON CONSTRAINT`) per branch constraint. If `diffTables()` already
+ * emitted the same change for a shape flip or a new constraint on that
+ * table, the plan ends up with two identical `ALTER TABLE ... ADD
+ * CONSTRAINT ...` statements and PostgreSQL fails at apply time with
+ * `constraint "..." for relation "..." already exists`. Because
+ * `expandReplaceDependencies()` appends its additions after the original
+ * `diffTables()` output, the last occurrence is the expansion's emission —
+ * keeping it preserves correctness while removing the duplicate.
+ */
+function dropReplacedTableDuplicateConstraintChanges(changes, replacedTableIds) {
+    if (replacedTableIds.size === 0)
+        return changes;
+    const keyFor = (change) => {
+        if (!(change instanceof AlterTableAddConstraint) &&
+            !(change instanceof AlterTableValidateConstraint) &&
+            !(change instanceof CreateCommentOnConstraint)) {
+            return null;
+        }
+        if (!replacedTableIds.has(change.table.stableId))
+            return null;
+        const tag = change instanceof AlterTableAddConstraint
+            ? "add"
+            : change instanceof AlterTableValidateConstraint
+                ? "validate"
+                : "comment";
+        return `${tag}:${constraintStableId(change.table, change.constraint.name)}`;
+    };
+    const seen = new Set();
+    const reversedKept = [];
+    let mutated = false;
+    // Walk backwards: the first encounter of each key corresponds to its LAST
+    // occurrence in the original order. `expandReplaceDependencies()` appends
+    // additions after the original changes, so "last wins" keeps the
+    // expansion's emission and drops the earlier diffTables duplicate.
+    for (let i = changes.length - 1; i >= 0; i--) {
+        const change = changes[i];
+        const key = keyFor(change);
+        if (key !== null) {
+            if (seen.has(key)) {
+                mutated = true;
+                continue;
+            }
+            seen.add(key);
+        }
+        reversedKept.push(change);
+    }
+    return mutated ? reversedKept.reverse() : changes;
+}
+/**
+ * Re-emit `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ * `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica-identity
+ * index of a branch table.
+ *
+ * Background: PostgreSQL silently flips a table's `relreplident` to `'d'`
+ * (DEFAULT) when the index it points to is dropped. `CREATE INDEX` cannot
+ * restore the marker — only `ALTER TABLE ... REPLICA IDENTITY USING INDEX`
+ * can. When both main and branch carry `replica_identity = 'i'` pointing at
+ * the same index name, `diffTables()` emits no replica-identity change of its
+ * own, so the marker would be lost on apply.
+ *
+ * This is a whole-plan interaction: `diffTables()` cannot detect it without
+ * also looking at index changes. Per the "whole-plan interactions belong in
+ * post-diff normalization" rule in the package CLAUDE.md, the restoration
+ * lives here.
+ *
+ * Insertion is idempotent: if `diffTables()` already emitted the same
+ * `AlterTableSetReplicaIdentity` for this table (e.g. when the user is also
+ * switching the replica-identity index name in the same migration), no
+ * duplicate is added.
+ */
+function restoreReplicaIdentityAfterIndexReplace(changes, branchTables) {
+    // Build the index-stable-id → owning-table map from branch state. Only
+    // tables in 'i' mode contribute, and only those whose configured index name
+    // is non-null (the extractor returns null for any other mode).
+    const replicaIdentityIndexToTable = new Map();
+    for (const table of Object.values(branchTables)) {
+        if (table.replica_identity !== "i" || !table.replica_identity_index) {
+            continue;
+        }
+        const indexId = stableId.index(table.schema, table.name, table.replica_identity_index);
+        replicaIdentityIndexToTable.set(indexId, table);
+    }
+    if (replicaIdentityIndexToTable.size === 0)
+        return changes;
+    // Find the indexes that are both dropped AND created in this plan. A pure
+    // drop or a pure create is handled by `diffTables()` directly (the table's
+    // replica_identity / replica_identity_index fields will have changed). The
+    // hole is specifically the drop+create pair that recreates the same name.
+    const droppedIndexIds = new Set();
+    const createdIndexIds = new Set();
+    for (const change of changes) {
+        if (change instanceof DropIndex) {
+            droppedIndexIds.add(change.index.stableId);
+        }
+        else if (change instanceof CreateIndex) {
+            createdIndexIds.add(change.index.stableId);
+        }
+    }
+    const replacedIndexIds = new Set();
+    for (const id of droppedIndexIds) {
+        if (createdIndexIds.has(id) && replicaIdentityIndexToTable.has(id)) {
+            replacedIndexIds.add(id);
+        }
+    }
+    if (replacedIndexIds.size === 0)
+        return changes;
+    // Skip tables for which `diffTables()` already emitted a replica-identity
+    // setter — re-emitting would produce a redundant ALTER TABLE (harmless on
+    // apply, but noisy in plan output).
+    const tablesWithExistingReplicaIdentitySetter = new Set();
+    for (const change of changes) {
+        if (change instanceof AlterTableSetReplicaIdentity) {
+            tablesWithExistingReplicaIdentitySetter.add(change.table.stableId);
+        }
+    }
+    // Insert one `AlterTableSetReplicaIdentity` per replaced index, immediately
+    // after the matching `CreateIndex`. The change's `requires` already names
+    // both the table and the recreated index, so the topo sort orders it
+    // correctly relative to the surrounding DDL.
+    const result = [];
+    for (const change of changes) {
+        result.push(change);
+        if (!(change instanceof CreateIndex) ||
+            !replacedIndexIds.has(change.index.stableId)) {
+            continue;
+        }
+        const table = replicaIdentityIndexToTable.get(change.index.stableId);
+        if (!table)
+            continue;
+        if (tablesWithExistingReplicaIdentitySetter.has(table.stableId))
+            continue;
+        result.push(new AlterTableSetReplicaIdentity({
+            table,
+            mode: "i",
+            indexName: table.replica_identity_index,
+        }));
+        // Mark as emitted so a second replaced index on the same table — if that
+        // ever arises — doesn't double-emit.
+        tablesWithExistingReplicaIdentitySetter.add(table.stableId);
+    }
+    return result;
+}
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ * - Re-emits `ALTER TABLE ... REPLICA IDENTITY USING INDEX <idx>` after any
+ *   `DropIndex(idx) + CreateIndex(idx)` pair where `idx` is the replica
+ *   identity index of a branch table — Postgres silently clears the marker
+ *   when the underlying index is dropped, and `CREATE INDEX` cannot restore
+ *   it.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffChanges({ changes, replacedTableIds = new Set(), branchTables = {}, }) {
+    const restoredChanges = restoreReplicaIdentityAfterIndexReplace(changes, branchTables);
+    const dedupedChanges = dropReplacedTableDuplicateConstraintChanges(restoredChanges, replacedTableIds);
+    if (replacedTableIds.size === 0)
+        return dedupedChanges;
+    return dedupedChanges.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+}

package/dist/core/sort/cycle-breakers.js

@@ -245,7 +245,7 @@ function tryBreakPublicationColumnCycle(cycleNodeIndexes, phaseChanges) {
         return null;
     // Verify the table is NOT itself being dropped. If `DropTable(T)` is in
     // the same phase, the existing structural rewrites in
-    // `post-diff-cycle-breaking.ts` (replace-expansion superseded filter)
+    // `post-diff-normalization.ts` (replace-expansion superseded filter)
     // already prune the redundant `AlterTableDropColumn`, so we should not
     // see this combination here. Be defensive and bail anyway — flipping
     // `omitTableRequirement` when T is being dropped would let the column

package/dist/core/sort/utils.d.ts

@@ -19,5 +19,15 @@ export declare function isMetadataStableId(stableId: string): boolean;
  * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
  * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
  * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ *
+ * Dependency-breaking ALTERs that remove a `pg_depend` edge to another
+ * object that may be dropped in the same plan (for example
+ * `ALTER COLUMN ... DROP DEFAULT` releasing a sequence reference, or
+ * `ALTER COLUMN ... TYPE <built-in>` releasing a user-defined type
+ * reference) are routed to the drop phase. The drop phase sorts in reverse
+ * dependency order using the main catalog, so the catalog edges already
+ * in `pg_depend` order the ALTER before any dependent `DROP TYPE` /
+ * `DROP SEQUENCE` / `DROP FUNCTION` and PostgreSQL no longer rejects the
+ * drop with error 2BP01.
  */
 export declare function getExecutionPhase(change: Change): Phase;

package/dist/core/sort/utils.js

@@ -1,3 +1,4 @@
+import { AlterTableAlterColumnDropDefault, AlterTableAlterColumnDropIdentity, AlterTableAlterColumnType, } from "../objects/table/changes/table.alter.js";
 /**
  * Check if a stable ID represents metadata (ACL, default privileges, comments, etc.)
  * rather than an actual database object.
@@ -20,6 +21,16 @@ export function isMetadataStableId(stableId) {
  * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
  * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
  * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ *
+ * Dependency-breaking ALTERs that remove a `pg_depend` edge to another
+ * object that may be dropped in the same plan (for example
+ * `ALTER COLUMN ... DROP DEFAULT` releasing a sequence reference, or
+ * `ALTER COLUMN ... TYPE <built-in>` releasing a user-defined type
+ * reference) are routed to the drop phase. The drop phase sorts in reverse
+ * dependency order using the main catalog, so the catalog edges already
+ * in `pg_depend` order the ALTER before any dependent `DROP TYPE` /
+ * `DROP SEQUENCE` / `DROP FUNCTION` and PostgreSQL no longer rejects the
+ * drop with error 2BP01.
  */
 export function getExecutionPhase(change) {
     // DROP operations always go to drop phase
@@ -43,6 +54,23 @@ export function getExecutionPhase(change) {
             // Destructive ALTER (DROP COLUMN, DROP CONSTRAINT, etc.) → drop phase
             return "drop";
         }
+        // Dependency-breaking column ALTERs that release a pg_depend edge.
+        // Routing these to the drop phase lets the existing catalog dependency
+        // edges (column → sequence, column → identity sequence) order them
+        // before the matching DROP statement.
+        if (change instanceof AlterTableAlterColumnDropDefault ||
+            change instanceof AlterTableAlterColumnDropIdentity) {
+            return "drop";
+        }
+        // ALTER COLUMN ... TYPE only safely runs in the drop phase when the
+        // target type is built-in. For user-defined target types we cannot tell
+        // here whether the type is created in the same plan, and the create
+        // happens in create_alter phase, so we keep the alter in that phase to
+        // preserve the create-then-alter ordering.
+        if (change instanceof AlterTableAlterColumnType &&
+            !change.column.is_custom_type) {
+            return "drop";
+        }
         // Non-destructive ALTER (ADD COLUMN, GRANT, etc.) → create_alter phase
         return "create_alter_object";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.23",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,

package/src/core/catalog.diff.ts

@@ -1,7 +1,7 @@
 import debug from "debug";
 import type { Catalog } from "./catalog.model.ts";
 import { expandReplaceDependencies } from "./expand-replace-dependencies.ts";
-import { normalizePostDiffCycles } from "./post-diff-cycle-breaking.ts";
+import { normalizePostDiffChanges } from "./post-diff-normalization.ts";
 
 const debugCatalog = debug("pg-delta:catalog");
 
@@ -190,6 +190,7 @@ export function diffCatalogs(
       main.sequences,
       branch.sequences,
       branch.tables,
+      main.tables,
     ),
   );
   changes.push(...diffTables(diffContext, main.tables, branch.tables));
@@ -238,9 +239,10 @@ export function diffCatalogs(
     mainCatalog: main,
     branchCatalog: branch,
   });
-  filteredChanges = normalizePostDiffCycles({
+  filteredChanges = normalizePostDiffChanges({
     changes: expandedDependencies.changes,
     replacedTableIds: expandedDependencies.replacedTableIds,
+    branchTables: branch.tables,
   });
 
   debugCatalog(

package/src/core/catalog.model.ts

@@ -267,6 +267,7 @@ export async function createEmptyCatalog(
     owner: currentUser,
     comment: "standard public schema",
     privileges: [],
+    security_labels: [],
   });
 
   return new Catalog({
@@ -302,7 +303,19 @@ export async function createEmptyCatalog(
   });
 }
 
-export async function extractCatalog(pool: Pool) {
+interface ExtractCatalogOptions {
+  /**
+   * Number of retry attempts for catalog extractors when `pg_get_*def()`
+   * returns NULL for at least one row. See `ExtractRetryOptions.retries`.
+   */
+  extractRetries?: number;
+}
+
+export async function extractCatalog(
+  pool: Pool,
+  options: ExtractCatalogOptions = {},
+) {
+  const retryOptions = { retries: options.extractRetries };
   const [
     aggregates,
     collations,
@@ -339,21 +352,21 @@ export async function extractCatalog(pool: Pool) {
     extractDomains(pool).then(listToRecord),
     extractEnums(pool).then(listToRecord),
     extractExtensions(pool).then(listToRecord),
-    extractIndexes(pool).then(listToRecord),
-    extractMaterializedViews(pool).then(listToRecord),
+    extractIndexes(pool, retryOptions).then(listToRecord),
+    extractMaterializedViews(pool, retryOptions).then(listToRecord),
     extractSubscriptions(pool).then(listToRecord),
     extractPublications(pool).then(listToRecord),
-    extractProcedures(pool).then(listToRecord),
+    extractProcedures(pool, retryOptions).then(listToRecord),
     extractRlsPolicies(pool).then(listToRecord),
     extractRoles(pool).then(listToRecord),
     extractSchemas(pool).then(listToRecord),
     extractSequences(pool).then(listToRecord),
-    extractTables(pool).then(listToRecord),
-    extractTriggers(pool).then(listToRecord),
+    extractTables(pool, retryOptions).then(listToRecord),
+    extractTriggers(pool, retryOptions).then(listToRecord),
     extractEventTriggers(pool).then(listToRecord),
-    extractRules(pool).then(listToRecord),
+    extractRules(pool, retryOptions).then(listToRecord),
     extractRanges(pool).then(listToRecord),
-    extractViews(pool).then(listToRecord),
+    extractViews(pool, retryOptions).then(listToRecord),
     extractForeignDataWrappers(pool).then(listToRecord),
     extractServers(pool).then(listToRecord),
     extractUserMappings(pool).then(listToRecord),

package/src/core/expand-replace-dependencies.test.ts

@@ -97,6 +97,137 @@ describe("expandReplaceDependencies", () => {
     expect(result.replacedTableIds.size).toBe(0);
   });
 
+  test("promotes surviving dependent view when its referenced table is dropped without a same-name create", async () => {
+    // Reproduces issue #228 case 3: ALTER TABLE users RENAME TO members.
+    // pg-delta sees `users` as drop-only and `members` as create-only — the
+    // stableIds differ, so neither is in the createdIds∩droppedIds replace
+    // root set. The dependent view `user_count` exists in both catalogs
+    // (its definition was rewritten to FROM members in branch). Without
+    // expansion, DROP TABLE users would fail because user_count still
+    // references it. The expander must seed the drop-only table as a root
+    // so the surviving dependent gets promoted to DROP+CREATE.
+    const baseline = await createEmptyCatalog(170000, "postgres");
+    const usersTable = new Table({
+      schema: "public",
+      name: "users",
+      persistence: "p",
+      row_security: false,
+      force_row_security: false,
+      has_indexes: false,
+      has_rules: false,
+      has_triggers: false,
+      has_subclasses: false,
+      is_populated: true,
+      replica_identity: "d",
+      is_partition: false,
+      options: null,
+      partition_bound: null,
+      partition_by: null,
+      owner: "postgres",
+      comment: null,
+      parent_schema: null,
+      parent_name: null,
+      columns: [
+        {
+          name: "id",
+          position: 1,
+          data_type: "integer",
+          data_type_str: "integer",
+          is_custom_type: false,
+          custom_type_type: null,
+          custom_type_category: null,
+          custom_type_schema: null,
+          custom_type_name: null,
+          not_null: true,
+          is_identity: false,
+          is_identity_always: false,
+          is_generated: false,
+          collation: null,
+          default: null,
+          comment: null,
+        },
+      ],
+      privileges: [],
+    });
+    const mainView = new View({
+      schema: "public",
+      name: "user_count",
+      owner: "postgres",
+      definition: " SELECT count(*) AS n FROM public.users;",
+      row_security: false,
+      force_row_security: false,
+      has_indexes: false,
+      has_rules: false,
+      has_triggers: false,
+      has_subclasses: false,
+      is_populated: true,
+      replica_identity: "d",
+      is_partition: false,
+      partition_bound: null,
+      comment: null,
+      columns: [
+        {
+          name: "n",
+          position: 1,
+          data_type: "bigint",
+          data_type_str: "bigint",
+          is_custom_type: false,
+          custom_type_type: null,
+          custom_type_category: null,
+          custom_type_schema: null,
+          custom_type_name: null,
+          not_null: false,
+          is_identity: false,
+          is_identity_always: false,
+          is_generated: false,
+          collation: null,
+          default: null,
+          comment: null,
+        },
+      ],
+      options: null,
+      privileges: [],
+    });
+    const branchView = new View({
+      ...mainView,
+      definition: " SELECT count(*) AS n FROM public.members;",
+    });
+
+    const mainCatalog = new Catalog({
+      ...baseline,
+      tables: { [usersTable.stableId]: usersTable },
+      views: { [mainView.stableId]: mainView },
+      depends: [
+        {
+          dependent_stable_id: mainView.stableId,
+          referenced_stable_id: usersTable.stableId,
+          deptype: "n",
+        },
+      ],
+    });
+    const branchCatalog = new Catalog({
+      ...baseline,
+      views: { [branchView.stableId]: branchView },
+    });
+
+    // Simulated planner output: DropTable(users) + CreateView orReplace(user_count).
+    // The surviving view appears only as a "create" (CREATE OR REPLACE VIEW),
+    // never as a drop, so DROP TABLE users would fail without expansion.
+    const changes: Change[] = [
+      new DropTable({ table: usersTable }),
+      new CreateView({ view: branchView, orReplace: true }),
+    ];
+    const result = expandReplaceDependencies({
+      changes,
+      mainCatalog,
+      branchCatalog,
+    });
+
+    // The view's surviving CREATE OR REPLACE remains, AND a DropView is
+    // injected so the drop phase removes the view before the table.
+    expect(result.changes.some((c) => c instanceof DropView)).toBe(true);
+  });
+
   test("does not replace the owning table for an owned sequence recreation", async () => {
     const baseline = await createEmptyCatalog(170000, "postgres");
     // Use `persistence` (UNLOGGED → LOGGED) to trigger the

package/src/core/expand-replace-dependencies.ts

@@ -129,6 +129,30 @@ export function expandReplaceDependencies({
     }
   }
 
+  // Drop-only objects (no matching create — typically a renamed-away table or
+  // type) are also expansion roots: anything in main that depends on them via
+  // pg_depend must drop before the parent does. Without this seed, a renamed
+  // table whose dependent view stays in the branch catalog (with an updated
+  // definition that no longer references the old name) would still try to
+  // run DROP TABLE old_name while old_name is referenced by the view, which
+  // PostgreSQL refuses without CASCADE. The walk below promotes the surviving
+  // dependent to DROP+CREATE so its drop is sequenced before the parent drop.
+  for (const id of droppedIds) {
+    if (createdIds.has(id)) continue;
+    if (replaceRoots.has(id)) continue;
+    // Only seed for object kinds that can have catalog dependents we know
+    // how to recreate via buildReplaceChanges.
+    if (
+      id.startsWith("table:") ||
+      id.startsWith("view:") ||
+      id.startsWith("materializedView:") ||
+      id.startsWith("type:") ||
+      id.startsWith("domain:")
+    ) {
+      replaceRoots.add(id);
+    }
+  }
+
   if (replaceRoots.size === 0) {
     return {
       changes,

package/src/core/integrations/filter/dsl.test.ts

@@ -41,6 +41,16 @@ const membershipChange = {
   requires: [],
 } as unknown as Change;
 
+const securityLabelChange = {
+  objectType: "schema",
+  operation: "create",
+  scope: "security_label",
+  schema: { name: "labeled" },
+  securityLabel: { provider: "dummy", label: "classified" },
+  requires: ["schema:labeled"],
+  creates: ["security_label:schema:labeled:dummy"],
+} as unknown as Change;
+
 describe("evaluatePattern", () => {
   describe("bare key matching (top-level properties)", () => {
     test("objectType match", () => {
@@ -242,6 +252,23 @@ describe("evaluatePattern", () => {
     });
   });
 
+  describe("security label matching", () => {
+    test("provider matches security label changes", () => {
+      expect(
+        evaluatePattern(
+          { scope: "security_label", provider: "dummy" },
+          securityLabelChange,
+        ),
+      ).toBe(true);
+      expect(
+        evaluatePattern(
+          { scope: "security_label", provider: "other" },
+          securityLabelChange,
+        ),
+      ).toBe(false);
+    });
+  });
+
   describe("composition patterns", () => {
     test("not negates a pattern", () => {
       expect(

package/src/core/integrations/filter/flatten.ts

@@ -105,6 +105,22 @@ export function flattenChange(change: Change): Record<string, FlatValue> {
           flat[`${prefix}/${subKey}`] = flatVal;
         }
       }
+    } else if (
+      key === "securityLabel" &&
+      value &&
+      typeof value === "object" &&
+      !Array.isArray(value)
+    ) {
+      // Security labels are change-level metadata, so expose provider/label as
+      // bare keys for filters like { scope: "security_label", provider: "..." }.
+      for (const [subKey, subValue] of Object.entries(
+        value as Record<string, unknown>,
+      )) {
+        const flatVal = toFlatValue(subValue);
+        if (flatVal !== undefined) {
+          flat[subKey] = flatVal;
+        }
+      }
     } else {
       const flatVal = toFlatValue(value);
       if (flatVal !== undefined) {

package/src/core/objects/aggregate/aggregate.diff.ts

@@ -5,6 +5,7 @@ import {
   filterPublicBuiltInDefaults,
 } from "../base.privilege-diff.ts";
 import type { ObjectDiffContext } from "../diff-context.ts";
+import { diffSecurityLabels } from "../security-label.types.ts";
 import { deepEqual, hasNonAlterableChanges } from "../utils.ts";
 import type { Aggregate } from "./aggregate.model.ts";
 import { AlterAggregateChangeOwner } from "./changes/aggregate.alter.ts";
@@ -19,6 +20,10 @@ import {
   RevokeAggregatePrivileges,
   RevokeGrantOptionAggregatePrivileges,
 } from "./changes/aggregate.privilege.ts";
+import {
+  CreateSecurityLabelOnAggregate,
+  DropSecurityLabelOnAggregate,
+} from "./changes/aggregate.security-label.ts";
 import type { AggregateChange } from "./changes/aggregate.types.ts";
 
 export function diffAggregates(
@@ -51,6 +56,14 @@ export function diffAggregates(
     if (aggregate.comment !== null) {
       changes.push(new CreateCommentOnAggregate({ aggregate }));
     }
+    for (const label of aggregate.security_labels) {
+      changes.push(
+        new CreateSecurityLabelOnAggregate({
+          aggregate,
+          securityLabel: label,
+        }),
+      );
+    }
 
     // PRIVILEGES: For created objects, compare against default privileges state
     // The migration script will run ALTER DEFAULT PRIVILEGES before CREATE (via constraint spec),
@@ -182,6 +195,26 @@ export function diffAggregates(
       }
     }
 
+    // SECURITY LABELS
+    changes.push(
+      ...diffSecurityLabels<
+        CreateSecurityLabelOnAggregate | DropSecurityLabelOnAggregate
+      >(
+        mainAggregate.security_labels,
+        branchAggregate.security_labels,
+        (securityLabel) =>
+          new CreateSecurityLabelOnAggregate({
+            aggregate: branchAggregate,
+            securityLabel,
+          }),
+        (securityLabel) =>
+          new DropSecurityLabelOnAggregate({
+            aggregate: mainAggregate,
+            securityLabel,
+          }),
+      ),
+    );
+
     // PRIVILEGES
     // Filter out PUBLIC's built-in default EXECUTE privilege from main catalog
     // (PostgreSQL grants it automatically, so we shouldn't compare it)