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

package/dist/core/objects/table/changes/table.alter.d.ts

@@ -216,16 +216,27 @@ export declare class AlterTableValidateConstraint extends AlterTableChange {
 }
 /**
  * ALTER TABLE ... REPLICA IDENTITY ...
+ *
+ * When `mode === "i"` (USING INDEX), `indexName` is the name of the index to
+ * use. The extractor populates `Table.replica_identity_index` from
+ * `pg_index.indisreplident` whenever `Table.replica_identity` is `'i'`, so
+ * callers that source their props from a `Table` instance can rely on the
+ * pair being consistent. The non-null assertions in `requires` / `serialize`
+ * below are justified by that data invariant — the same pattern the FK
+ * branch of `AlterTableAddConstraint` uses for `foreign_key_columns!` /
+ * `foreign_key_table!` / `foreign_key_schema!`.
  */
 export declare class AlterTableSetReplicaIdentity extends AlterTableChange {
     readonly table: Table;
     readonly mode: "d" | "n" | "f" | "i";
+    readonly indexName: string | null;
     readonly scope: "object";
     constructor(props: {
         table: Table;
         mode: "d" | "n" | "f" | "i";
+        indexName?: string | null;
     });
-    get requires(): `table:${string}`[];
+    get requires(): string[];
     serialize(_options?: SerializeOptions): string;
 }
 /**
@@ -250,9 +261,11 @@ export declare class AlterTableDropColumn extends AlterTableChange {
     readonly table: Table;
     readonly column: ColumnProps;
     readonly scope: "object";
+    readonly omitTableRequirement: boolean;
     constructor(props: {
         table: Table;
         column: ColumnProps;
+        omitTableRequirement?: boolean;
     });
     get drops(): `column:${string}.${string}.${string}`[];
     get requires(): (`column:${string}.${string}.${string}` | `table:${string}`)[];
@@ -264,10 +277,12 @@ export declare class AlterTableDropColumn extends AlterTableChange {
 export declare class AlterTableAlterColumnType extends AlterTableChange {
     readonly table: Table;
     readonly column: ColumnProps;
+    readonly previousColumn?: ColumnProps;
     readonly scope: "object";
     constructor(props: {
         table: Table;
         column: ColumnProps;
+        previousColumn?: ColumnProps;
     });
     get requires(): `column:${string}.${string}.${string}`[];
     serialize(_options?: SerializeOptions): string;

package/dist/core/objects/table/changes/table.alter.js

@@ -302,18 +302,35 @@ export class AlterTableValidateConstraint extends AlterTableChange {
 }
 /**
  * ALTER TABLE ... REPLICA IDENTITY ...
+ *
+ * When `mode === "i"` (USING INDEX), `indexName` is the name of the index to
+ * use. The extractor populates `Table.replica_identity_index` from
+ * `pg_index.indisreplident` whenever `Table.replica_identity` is `'i'`, so
+ * callers that source their props from a `Table` instance can rely on the
+ * pair being consistent. The non-null assertions in `requires` / `serialize`
+ * below are justified by that data invariant — the same pattern the FK
+ * branch of `AlterTableAddConstraint` uses for `foreign_key_columns!` /
+ * `foreign_key_table!` / `foreign_key_schema!`.
  */
 export class AlterTableSetReplicaIdentity extends AlterTableChange {
     table;
     mode;
+    indexName;
     scope = "object";
     constructor(props) {
         super();
         this.table = props.table;
         this.mode = props.mode;
+        this.indexName = props.indexName ?? null;
     }
     get requires() {
-        return [this.table.stableId];
+        const reqs = [this.table.stableId];
+        if (this.mode === "i") {
+            reqs.push(stableId.index(this.table.schema, this.table.name, 
+            // biome-ignore lint/style/noNonNullAssertion: mode 'i' implies the extractor populated replica_identity_index
+            this.indexName));
+        }
+        return reqs;
     }
     serialize(_options) {
         const clause = this.mode === "d"
@@ -322,7 +339,8 @@ export class AlterTableSetReplicaIdentity extends AlterTableChange {
                 ? "NOTHING"
                 : this.mode === "f"
                     ? "FULL"
-                    : "DEFAULT"; // 'i' (USING INDEX) is handled via index changes; fallback to DEFAULT
+                    : // biome-ignore lint/style/noNonNullAssertion: mode 'i' implies the extractor populated replica_identity_index
+                        `USING INDEX ${this.indexName}`;
         return [
             "ALTER TABLE",
             `${this.table.schema}.${this.table.name}`,
@@ -386,10 +404,16 @@ export class AlterTableDropColumn extends AlterTableChange {
     table;
     column;
     scope = "object";
+    // Drop the implicit `requires(table)` edge. Only set by the lazy
+    // cycle-breaker for the publication↔column case, where the table survives
+    // the migration and the edge is therefore artificial. See
+    // `sort/cycle-breakers.ts` for the full justification.
+    omitTableRequirement;
     constructor(props) {
         super();
         this.table = props.table;
         this.column = props.column;
+        this.omitTableRequirement = props.omitTableRequirement ?? false;
     }
     get drops() {
         return [
@@ -397,10 +421,8 @@ export class AlterTableDropColumn extends AlterTableChange {
         ];
     }
     get requires() {
-        return [
-            this.table.stableId,
-            stableId.column(this.table.schema, this.table.name, this.column.name),
-        ];
+        const colId = stableId.column(this.table.schema, this.table.name, this.column.name);
+        return this.omitTableRequirement ? [colId] : [this.table.stableId, colId];
     }
     serialize(_options) {
         return [
@@ -417,11 +439,13 @@ export class AlterTableDropColumn extends AlterTableChange {
 export class AlterTableAlterColumnType extends AlterTableChange {
     table;
     column;
+    previousColumn;
     scope = "object";
     constructor(props) {
         super();
         this.table = props.table;
         this.column = props.column;
+        this.previousColumn = props.previousColumn;
     }
     get requires() {
         return [
@@ -429,6 +453,12 @@ export class AlterTableAlterColumnType extends AlterTableChange {
         ];
     }
     serialize(_options) {
+        // previousColumn is optional so direct serializer tests/fixtures can keep
+        // emitting canonical ALTER TYPE SQL without forcing a USING expression.
+        // When provided, we can detect true type changes and add USING for casts
+        // PostgreSQL cannot perform automatically.
+        const hasTypeChangedWithPreviousDefinition = this.previousColumn?.data_type_str !== undefined &&
+            this.previousColumn.data_type_str !== this.column.data_type_str;
         const parts = [
             "ALTER TABLE",
             `${this.table.schema}.${this.table.name}`,
@@ -440,6 +470,9 @@ export class AlterTableAlterColumnType extends AlterTableChange {
         if (this.column.collation) {
             parts.push("COLLATE", this.column.collation);
         }
+        if (hasTypeChangedWithPreviousDefinition) {
+            parts.push("USING", `${this.column.name}::${this.column.data_type_str}`);
+        }
         return parts.join(" ");
     }
 }

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) {
@@ -451,15 +455,30 @@ export function diffTables(ctx, main, branch) {
             const branchCol = branchCols.get(name);
             if (!branchCol)
                 continue;
+            const columnTypeChanged = mainCol.data_type_str !== branchCol.data_type_str;
+            const columnCollationChanged = mainCol.collation !== branchCol.collation;
+            const needsDefaultSafeFlow = columnTypeChanged && mainCol.default !== null;
             // TYPE or COLLATION change
-            if (mainCol.data_type_str !== branchCol.data_type_str ||
-                mainCol.collation !== branchCol.collation) {
+            if (columnTypeChanged || columnCollationChanged) {
                 // Skip if parent has the same type/collation change
                 if (!parentHasSameColumnPropertyChange(name, "type")) {
+                    if (needsDefaultSafeFlow) {
+                        changes.push(new AlterTableAlterColumnDropDefault({
+                            table: branchTable,
+                            column: branchCol,
+                        }));
+                    }
                     changes.push(new AlterTableAlterColumnType({
                         table: branchTable,
                         column: branchCol,
+                        previousColumn: mainCol,
                     }));
+                    if (needsDefaultSafeFlow && branchCol.default !== null) {
+                        changes.push(new AlterTableAlterColumnSetDefault({
+                            table: branchTable,
+                            column: branchCol,
+                        }));
+                    }
                 }
             }
             // PostgreSQL rejects SET DEFAULT while the column still has identity metadata,
@@ -476,6 +495,10 @@ export function diffTables(ctx, main, branch) {
             if (mainCol.default !== branchCol.default) {
                 // Skip if parent has the same default change
                 if (!parentHasSameColumnPropertyChange(name, "default")) {
+                    if (needsDefaultSafeFlow) {
+                        // Defaults were already dropped/re-set in the type-change flow above.
+                        continue;
+                    }
                     if (branchCol.default === null) {
                         // Drop default value
                         changes.push(new AlterTableAlterColumnDropDefault({

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,
@@ -265,13 +295,16 @@ select
 
           'key_columns',
             case
-              when c.conkey is not null then (
-                select json_agg(quote_ident(att.attname) order by pk.ordinality)
-                from unnest(c.conkey) with ordinality as pk(attnum, ordinality)
-                join pg_attribute att
-                  on att.attrelid = c.conrelid
-                and att.attnum = pk.attnum
-                and att.attisdropped = false
+              when c.conkey is not null then coalesce(
+                (
+                  select json_agg(quote_ident(att.attname) order by pk.ordinality)
+                  from unnest(c.conkey) with ordinality as pk(attnum, ordinality)
+                  join pg_attribute att
+                    on att.attrelid = c.conrelid
+                  and att.attnum = pk.attnum
+                  and att.attisdropped = false
+                ),
+                '[]'::json
               )
               else '[]'::json
             end,
@@ -419,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-normalization.d.ts

@@ -0,0 +1,36 @@
+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
+ * 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 declare function normalizePostDiffChanges({ changes, replacedTableIds, branchTables, }: {
+    changes: Change[];
+    replacedTableIds?: ReadonlySet<string>;
+    branchTables?: Record<string, Table>;
+}): Change[];