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

package/dist/core/objects/table/table.diff.js

@@ -152,13 +152,11 @@ export function diffTables(ctx, main, branch) {
         }
         // REPLICA IDENTITY: If non-default, emit ALTER TABLE ... REPLICA IDENTITY
         if (branchTable.replica_identity !== "d") {
-            // Skip 'i' (USING INDEX) — handled by index changes
-            if (branchTable.replica_identity !== "i") {
-                changes.push(new AlterTableSetReplicaIdentity({
-                    table: branchTable,
-                    mode: branchTable.replica_identity,
-                }));
-            }
+            changes.push(new AlterTableSetReplicaIdentity({
+                table: branchTable,
+                mode: branchTable.replica_identity,
+                indexName: branchTable.replica_identity_index,
+            }));
         }
         changes.push(...createAlterConstraintChange(
         // Create a dummy table with no constraints do diff constraints against
@@ -261,14 +259,20 @@ export function diffTables(ctx, main, branch) {
             }
         }
         // REPLICA IDENTITY
-        if (mainTable.replica_identity !== branchTable.replica_identity) {
-            // Skip when target is 'i' (USING INDEX) — handled by index changes
-            if (branchTable.replica_identity !== "i") {
-                changes.push(new AlterTableSetReplicaIdentity({
-                    table: mainTable,
-                    mode: branchTable.replica_identity,
-                }));
-            }
+        // Re-emit when the mode changes, or when staying in 'i' mode but pointing
+        // at a different index. The index named on the branch must already exist
+        // before this ALTER runs; AlterTableSetReplicaIdentity declares that
+        // dependency in its `requires`.
+        const replicaIdentityChanged = mainTable.replica_identity !== branchTable.replica_identity ||
+            (branchTable.replica_identity === "i" &&
+                mainTable.replica_identity_index !==
+                    branchTable.replica_identity_index);
+        if (replicaIdentityChanged) {
+            changes.push(new AlterTableSetReplicaIdentity({
+                table: mainTable,
+                mode: branchTable.replica_identity,
+                indexName: branchTable.replica_identity_index,
+            }));
         }
         // OWNER
         if (mainTable.owner !== branchTable.owner) {

package/dist/core/objects/table/table.model.d.ts

@@ -2,6 +2,7 @@ import type { Pool } from "pg";
 import z from "zod";
 import { BasePgModel, type TableLikeObject } from "../base.model.ts";
 import { type PrivilegeProps } from "../base.privilege-diff.ts";
+import { type ExtractRetryOptions } from "../extract-with-retry.ts";
 export declare const ReplicaIdentitySchema: z.ZodEnum<{
     n: "n";
     i: "i";
@@ -85,6 +86,7 @@ declare const tablePropsSchema: z.ZodObject<{
         d: "d";
         f: "f";
     }>;
+    replica_identity_index: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     is_partition: z.ZodBoolean;
     options: z.ZodNullable<z.ZodArray<z.ZodString>>;
     partition_bound: z.ZodNullable<z.ZodString>;
@@ -187,6 +189,7 @@ export declare class Table extends BasePgModel implements TableLikeObject {
     readonly has_subclasses: TableProps["has_subclasses"];
     readonly is_populated: TableProps["is_populated"];
     readonly replica_identity: TableProps["replica_identity"];
+    readonly replica_identity_index: TableProps["replica_identity_index"];
     readonly is_partition: TableProps["is_partition"];
     readonly options: TableProps["options"];
     readonly partition_bound: TableProps["partition_bound"];
@@ -209,6 +212,7 @@ export declare class Table extends BasePgModel implements TableLikeObject {
         row_security: boolean;
         force_row_security: boolean;
         replica_identity: "n" | "i" | "d" | "f";
+        replica_identity_index: string | null | undefined;
         options: string[] | null;
         parent_schema: string | null;
         parent_name: string | null;
@@ -336,6 +340,7 @@ export declare class Table extends BasePgModel implements TableLikeObject {
             row_security: boolean;
             force_row_security: boolean;
             replica_identity: "n" | "i" | "d" | "f";
+            replica_identity_index: string | null | undefined;
             parent_schema: string | null;
             parent_name: string | null;
             partition_bound: string | null;
@@ -344,5 +349,5 @@ export declare class Table extends BasePgModel implements TableLikeObject {
         };
     };
 }
-export declare function extractTables(pool: Pool): Promise<Table[]>;
+export declare function extractTables(pool: Pool, options?: ExtractRetryOptions): Promise<Table[]>;
 export {};

package/dist/core/objects/table/table.model.js

@@ -3,6 +3,7 @@ import z from "zod";
 import { BasePgModel, columnPropsSchema, normalizeColumns, } from "../base.model.js";
 import { normalizePrivileges } from "../base.privilege.js";
 import { privilegePropsSchema, } from "../base.privilege-diff.js";
+import { extractWithDefinitionRetry, } from "../extract-with-retry.js";
 const RelationPersistenceSchema = z.enum([
     "p", // permanent
     "u", // unlogged
@@ -65,6 +66,14 @@ const tableConstraintPropsSchema = z.object({
     definition: z.string(),
     comment: z.string().nullable().optional(),
 });
+// pg_get_constraintdef(oid, pretty) can return NULL under the same conditions
+// as pg_get_indexdef: races with concurrent DDL, transient catalog
+// inconsistencies, recovery edges. An unreadable constraint cannot be diffed,
+// so we accept NULL here and filter the constraint out at extraction time
+// rather than crashing the whole catalog parse with a ZodError.
+const tableConstraintRowSchema = tableConstraintPropsSchema.extend({
+    definition: z.string().nullable(),
+});
 const tablePropsSchema = z.object({
     schema: z.string(),
     name: z.string(),
@@ -77,6 +86,7 @@ const tablePropsSchema = z.object({
     has_subclasses: z.boolean(),
     is_populated: z.boolean(),
     replica_identity: ReplicaIdentitySchema,
+    replica_identity_index: z.string().nullable().optional(),
     is_partition: z.boolean(),
     options: z.array(z.string()).nullable(),
     partition_bound: z.string().nullable(),
@@ -89,6 +99,9 @@ const tablePropsSchema = z.object({
     constraints: z.array(tableConstraintPropsSchema).optional(),
     privileges: z.array(privilegePropsSchema),
 });
+const tableRowSchema = tablePropsSchema.extend({
+    constraints: z.array(tableConstraintRowSchema).optional(),
+});
 export class Table extends BasePgModel {
     schema;
     name;
@@ -101,6 +114,7 @@ export class Table extends BasePgModel {
     has_subclasses;
     is_populated;
     replica_identity;
+    replica_identity_index;
     is_partition;
     options;
     partition_bound;
@@ -127,6 +141,7 @@ export class Table extends BasePgModel {
         this.has_subclasses = props.has_subclasses;
         this.is_populated = props.is_populated;
         this.replica_identity = props.replica_identity;
+        this.replica_identity_index = props.replica_identity_index ?? null;
         this.is_partition = props.is_partition;
         this.options = props.options;
         this.partition_bound = props.partition_bound;
@@ -155,6 +170,7 @@ export class Table extends BasePgModel {
             row_security: this.row_security,
             force_row_security: this.force_row_security,
             replica_identity: this.replica_identity,
+            replica_identity_index: this.replica_identity_index,
             options: this.options,
             // Partition membership can be altered via ATTACH/DETACH
             parent_schema: this.parent_schema,
@@ -185,8 +201,13 @@ export class Table extends BasePgModel {
         };
     }
 }
-export async function extractTables(pool) {
-    const { rows: tableRows } = await pool.query(sql `
+export async function extractTables(pool, options) {
+    const tableRows = await extractWithDefinitionRetry({
+        label: "table constraints",
+        options,
+        hasNullDefinition: (row) => row.constraints?.some((c) => c.definition === null) ?? false,
+        query: async () => {
+            const result = await pool.query(sql `
 with extension_oids as (
   select objid
   from pg_depend d
@@ -205,6 +226,14 @@ with extension_oids as (
     c.relhassubclass as has_subclasses,
     c.relispopulated as is_populated,
     c.relreplident as replica_identity,
+    (
+      select quote_ident(ri_class.relname)
+      from pg_index ri
+      join pg_class ri_class on ri_class.oid = ri.indexrelid
+      where ri.indrelid = c.oid
+        and ri.indisreplident is true
+      limit 1
+    ) as replica_identity_index,
     c.relispartition as is_partition,
     c.reloptions as options,
     pg_get_expr(c.relpartbound, c.oid) as partition_bound,
@@ -235,6 +264,7 @@ select
   t.has_subclasses,
   t.is_populated,
   t.replica_identity,
+  t.replica_identity_index,
   t.is_partition,
   t.options,
   t.partition_bound,
@@ -422,11 +452,16 @@ from
   left join pg_attrdef ad on a.attrelid = ad.adrelid and a.attnum = ad.adnum
   left join pg_type ty on ty.oid = a.atttypid
 group by
-  t.oid, t.schema, t.name, t.persistence, t.row_security, t.force_row_security, t.has_indexes, t.has_rules, t.has_triggers, t.has_subclasses, t.is_populated, t.replica_identity, t.is_partition, t.options, t.partition_bound, t.partition_by, t.owner, t.parent_schema, t.parent_name
+  t.oid, t.schema, t.name, t.persistence, t.row_security, t.force_row_security, t.has_indexes, t.has_rules, t.has_triggers, t.has_subclasses, t.is_populated, t.replica_identity, t.replica_identity_index, t.is_partition, t.options, t.partition_bound, t.partition_by, t.owner, t.parent_schema, t.parent_name
 order by
   t.schema, t.name
   `);
-    // Validate and parse each row using the Zod schema
-    const validatedRows = tableRows.map((row) => tablePropsSchema.parse(row));
+            return result.rows.map((row) => tableRowSchema.parse(row));
+        },
+    });
+    const validatedRows = tableRows.map((row) => {
+        const filteredConstraints = row.constraints?.filter((c) => c.definition !== null);
+        return { ...row, constraints: filteredConstraints };
+    });
     return validatedRows.map((row) => new Table(row));
 }

package/dist/core/objects/trigger/trigger.model.d.ts

@@ -1,6 +1,7 @@
 import type { Pool } from "pg";
 import z from "zod";
 import { BasePgModel } from "../base.model.ts";
+import { type ExtractRetryOptions } from "../extract-with-retry.ts";
 declare const triggerPropsSchema: z.ZodObject<{
     schema: z.ZodString;
     name: z.ZodString;
@@ -97,5 +98,5 @@ export declare class Trigger extends BasePgModel {
         comment: string | null;
     };
 }
-export declare function extractTriggers(pool: Pool): Promise<Trigger[]>;
+export declare function extractTriggers(pool: Pool, options?: ExtractRetryOptions): Promise<Trigger[]>;
 export {};

package/dist/core/objects/trigger/trigger.model.js

@@ -1,6 +1,7 @@
 import { sql } from "@ts-safeql/sql-tag";
 import z from "zod";
 import { BasePgModel } from "../base.model.js";
+import { extractWithDefinitionRetry, } from "../extract-with-retry.js";
 const TriggerEnabledSchema = z.enum([
     "O", // ORIGIN - trigger fires in "origin" and "local" replica modes
     "D", // DISABLED - trigger is disabled
@@ -41,6 +42,14 @@ const triggerPropsSchema = z.object({
     definition: z.string(),
     comment: z.string().nullable(),
 });
+// pg_get_triggerdef(oid, pretty) can return NULL when the trigger (its
+// pg_trigger row) is dropped between catalog scan and resolution, or under
+// transient catalog state. An unreadable trigger cannot be diffed, so we
+// accept NULL here and filter the row out at extraction time rather than
+// crashing the whole catalog parse with a ZodError.
+const triggerRowSchema = triggerPropsSchema.extend({
+    definition: z.string().nullable(),
+});
 export class Trigger extends BasePgModel {
     schema;
     name;
@@ -139,8 +148,13 @@ export class Trigger extends BasePgModel {
         };
     }
 }
-export async function extractTriggers(pool) {
-    const { rows: triggerRows } = await pool.query(sql `
+export async function extractTriggers(pool, options) {
+    const triggerRows = await extractWithDefinitionRetry({
+        label: "triggers",
+        options,
+        hasNullDefinition: (row) => row.definition === null,
+        query: async () => {
+            const result = await pool.query(sql `
       with extension_trigger_oids as (
         select objid
         from pg_depend d
@@ -245,7 +259,9 @@ export async function extractTriggers(pool) {
 
       order by 1, 2
   `);
-    // Validate and parse each row using the Zod schema
-    const validatedRows = triggerRows.map((row) => triggerPropsSchema.parse(row));
+            return result.rows.map((row) => triggerRowSchema.parse(row));
+        },
+    });
+    const validatedRows = triggerRows.filter((row) => row.definition !== null);
     return validatedRows.map((row) => new Trigger(row));
 }

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

@@ -20,6 +20,7 @@ export declare const stableId: {
     defacl(grantor: string, objtype: string, schema: string | null, grantee: string): `defacl:${string}:${string}:${string}:grantee:${string}`;
     column(schema: string, table: string, column: string): `column:${string}.${string}.${string}`;
     constraint(schema: string, table: string, constraint: string): `constraint:${string}.${string}.${string}`;
+    index(schema: string, table: string, indexName: string): `index:${string}.${string}.${string}`;
     comment(objectStableId: string): `comment:${string}`;
     role(role: string): `role:${string}`;
     type(schema: string, name: string): `type:${string}.${string}`;

package/dist/core/objects/utils.js

@@ -49,6 +49,9 @@ export const stableId = {
     constraint(schema, table, constraint) {
         return `constraint:${schema}.${table}.${constraint}`;
     },
+    index(schema, table, indexName) {
+        return `index:${schema}.${table}.${indexName}`;
+    },
     comment(objectStableId) {
         return `comment:${objectStableId}`;
     },

package/dist/core/objects/view/view.model.d.ts

@@ -2,6 +2,7 @@ import type { Pool } from "pg";
 import z from "zod";
 import { BasePgModel, type TableLikeObject } from "../base.model.ts";
 import { type PrivilegeProps } from "../base.privilege-diff.ts";
+import { type ExtractRetryOptions } from "../extract-with-retry.ts";
 declare const viewPropsSchema: z.ZodObject<{
     schema: z.ZodString;
     name: z.ZodString;
@@ -162,5 +163,5 @@ export declare class View extends BasePgModel implements TableLikeObject {
         };
     };
 }
-export declare function extractViews(pool: Pool): Promise<View[]>;
+export declare function extractViews(pool: Pool, options?: ExtractRetryOptions): Promise<View[]>;
 export {};

package/dist/core/objects/view/view.model.js

@@ -2,6 +2,7 @@ import { sql } from "@ts-safeql/sql-tag";
 import z from "zod";
 import { BasePgModel, columnPropsSchema, normalizeColumns, } from "../base.model.js";
 import { privilegePropsSchema, } from "../base.privilege-diff.js";
+import { extractWithDefinitionRetry, } from "../extract-with-retry.js";
 import { ReplicaIdentitySchema } from "../table/table.model.js";
 const viewPropsSchema = z.object({
     schema: z.string(),
@@ -23,6 +24,14 @@ const viewPropsSchema = z.object({
     columns: z.array(columnPropsSchema),
     privileges: z.array(privilegePropsSchema),
 });
+// pg_get_viewdef(oid) can return NULL when the underlying view (or its
+// pg_rewrite row) is dropped between catalog scan and resolution, or under
+// transient catalog state during recovery. An unreadable view cannot be
+// diffed, so we accept NULL here and filter the row out at extraction time
+// rather than crashing the whole catalog parse with a ZodError.
+const viewRowSchema = viewPropsSchema.extend({
+    definition: z.string().nullable(),
+});
 export class View extends BasePgModel {
     schema;
     name;
@@ -104,8 +113,13 @@ export class View extends BasePgModel {
         };
     }
 }
-export async function extractViews(pool) {
-    const { rows: viewRows } = await pool.query(sql `
+export async function extractViews(pool, options) {
+    const viewRows = await extractWithDefinitionRetry({
+        label: "views",
+        options,
+        hasNullDefinition: (row) => row.definition === null,
+        query: async () => {
+            const result = await pool.query(sql `
 with extension_oids as (
   select
     objid
@@ -232,7 +246,9 @@ group by
 order by
   v.schema, v.name
   `);
-    // Validate and parse each row using the Zod schema
-    const validatedRows = viewRows.map((row) => viewPropsSchema.parse(row));
+            return result.rows.map((row) => viewRowSchema.parse(row));
+        },
+    });
+    const validatedRows = viewRows.filter((row) => row.definition !== null);
     return validatedRows.map((row) => new View(row));
 }

package/dist/core/plan/create.js

@@ -62,7 +62,9 @@ export async function createPlan(source, target, options = {}) {
         }
         const resolved = await resolvePool(input, label);
         pools.push(resolved);
-        return extractCatalog(resolved.pool);
+        return extractCatalog(resolved.pool, {
+            extractRetries: options.extractRetries,
+        });
     };
     const pools = [];
     try {

package/dist/core/plan/types.d.ts

@@ -141,5 +141,13 @@ export interface CreatePlanOptions {
      * the output must be self-contained and not rely on statement execution order.
      */
     skipDefaultPrivilegeSubtraction?: boolean;
+    /**
+     * Number of retry attempts for catalog extractors when `pg_get_*def()`
+     * returns NULL for at least one row (a transient race with concurrent DDL).
+     * Total attempts is `extractRetries + 1`. When undefined, the value is read
+     * from the `PGDELTA_EXTRACT_RETRIES` environment variable, falling back to
+     * a default of 1 (i.e. the first attempt plus one retry, 2 attempts total).
+     */
+    extractRetries?: number;
 }
 export {};

package/dist/core/{post-diff-cycle-breaking.d.ts → post-diff-normalization.d.ts}

@@ -1,4 +1,5 @@
 import type { Change } from "./change.types.ts";
+import type { Table } from "./objects/table/table.model.ts";
 /**
  * Apply structural rewrites to the change list that are only obvious once
  * every object diff has been collected. This pass does NOT prevent dependency
@@ -19,11 +20,17 @@ import type { Change } from "./change.types.ts";
  *   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 declare function normalizePostDiffCycles({ changes, replacedTableIds, }: {
+export declare function normalizePostDiffChanges({ changes, replacedTableIds, branchTables, }: {
     changes: Change[];
     replacedTableIds?: ReadonlySet<string>;
+    branchTables?: Record<string, Table>;
 }): Change[];

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;