@supabase/pg-delta 1.0.0-alpha.14 → 1.0.0-alpha.15

package/README.md

@@ -181,7 +181,13 @@ See [Integrations Documentation](./docs/integrations.md) for complete details.
 
 ## Contributing
 
-Contributions welcome! Feel free to submit issues and pull requests.
+Please follow the repository-level guide in [../../CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+In particular:
+
+- Open an issue first.
+- Wait for maintainer triage via one of `✨ Feature`, `🐛 Bug`, `📘 Docs`, or `🛠️ Chore` before opening a pull request.
+- Use [../../ISSUES.md](../../ISSUES.md) when reporting `pg-delta` bugs so maintainers have what they need to reproduce them.
 
 ## License
 

package/dist/core/catalog.diff.js

@@ -1,5 +1,6 @@
 import debug from "debug";
 import { expandReplaceDependencies } from "./expand-replace-dependencies.js";
+import { normalizePostDiffCycles } from "./post-diff-cycle-breaking.js";
 const debugCatalog = debug("pg-delta:catalog");
 import { diffAggregates } from "./objects/aggregate/aggregate.diff.js";
 import { DefaultPrivilegeState } from "./objects/base.default-privileges.js";
@@ -153,11 +154,16 @@ export function diffCatalogs(main, branch, options) {
         }
         return true;
     });
-    filteredChanges = expandReplaceDependencies({
+    const expandedDependencies = expandReplaceDependencies({
         changes: filteredChanges,
         mainCatalog: main,
         branchCatalog: branch,
     });
+    filteredChanges = normalizePostDiffCycles({
+        changes: expandedDependencies.changes,
+        mainCatalog: main,
+        replacedTableIds: expandedDependencies.replacedTableIds,
+    });
     debugCatalog("changes catalog diff: %O", stringifyWithBigInt(filteredChanges, 2));
     return filteredChanges;
 }

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

@@ -5,10 +5,16 @@ import type { Change } from "./change.types.ts";
  * replaced so that destructive drops succeed. Uses dependency edges from pg_depend
  * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
  *
- * New changes are appended; ordering is handled later by the sorter.
+ * New changes are appended; ordering and any multi-statement cycle normalization
+ * are handled later by post-diff helpers and the sorter.
  */
+interface ExpandReplaceDependenciesResult {
+    changes: Change[];
+    replacedTableIds: ReadonlySet<string>;
+}
 export declare function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }: {
     changes: Change[];
     mainCatalog: Catalog;
     branchCatalog: Catalog;
-}): Change[];
+}): ExpandReplaceDependenciesResult;
+export {};

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

@@ -17,13 +17,6 @@ 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";
-/**
- * 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
- * (already captured in Catalog.depends) plus change metadata (creates/drops/requires).
- *
- * New changes are appended; ordering is handled later by the sorter.
- */
 export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog, }) {
     const createdIds = new Set();
     const droppedIds = new Set();
@@ -40,7 +33,10 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         }
     }
     if (replaceRoots.size === 0) {
-        return changes;
+        return {
+            changes,
+            replacedTableIds: new Set(),
+        };
     }
     // Build referenced -> dependents adjacency from main catalog dependencies.
     const dependentsByReferenced = new Map();
@@ -56,6 +52,12 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
     const visitedTargets = new Set();
     const visitedRefs = new Set(replaceRoots);
     const queue = [...replaceRoots];
+    // Tables being replaced by an expansion-added DropTable+CreateTable pair.
+    // Any pre-existing targeted AlterTable*(T) object-scope change is superseded
+    // by the replacement and must be removed to avoid contradictions (e.g. an
+    // AlterTableDropColumn on a table that is about to be dropped) and the
+    // associated drop-phase cycle with the catalog constraint→column edge.
+    const tablesReplacedByExpansion = new Set();
     while (queue.length > 0) {
         const refId = queue.shift();
         const dependents = dependentsByReferenced.get(refId);
@@ -102,6 +104,12 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
             if (!replacementChanges)
                 continue;
             additions.push(...replacementChanges);
+            // 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.
+            if (resolved.kind === "table" && addDrop) {
+                tablesReplacedByExpansion.add(targetId);
+            }
             // Track new creates/drops so we don't duplicate work for downstream dependents.
             for (const change of replacementChanges) {
                 for (const id of change.creates ?? [])
@@ -112,9 +120,15 @@ export function expandReplaceDependencies({ changes, mainCatalog, branchCatalog,
         }
     }
     if (additions.length === 0) {
-        return changes;
+        return {
+            changes,
+            replacedTableIds: tablesReplacedByExpansion,
+        };
     }
-    return [...changes, ...additions];
+    return {
+        changes: [...changes, ...additions],
+        replacedTableIds: tablesReplacedByExpansion,
+    };
 }
 function isOwnedSequenceColumnDependency(referencedId, dependentId, mainCatalog, branchCatalog) {
     // When a sequence replace root is still OWNED BY the same column, the

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

@@ -59,16 +59,24 @@ export function diffSequences(ctx, main, branch, branchTables = {}) {
     }
     for (const sequenceId of dropped) {
         const sequence = main[sequenceId];
-        // Skip generating DROP SEQUENCE if the sequence is owned by a table that's being dropped.
-        // PostgreSQL automatically drops sequences owned by tables when the table is dropped,
-        // so generating DROP SEQUENCE would cause an error (sequence doesn't exist).
+        // Skip generating DROP SEQUENCE if the sequence is owned by a table/column that's being dropped.
+        // PostgreSQL automatically cascades owned sequences when the owning table OR the owning
+        // column is dropped (via OWNED BY). Emitting DROP SEQUENCE in those cases would either
+        // fail at apply time (sequence already gone) or — in the column-drop case — create an
+        // unbreakable DropSequence ↔ AlterTableDropColumn cycle in the drop-phase sort graph.
         if (sequence.owned_by_schema &&
             sequence.owned_by_table &&
             sequence.owned_by_column) {
             const ownedByTableId = `table:${sequence.owned_by_schema}.${sequence.owned_by_table}`;
-            // If the owning table doesn't exist in branch catalog, it's being dropped
-            // and will auto-drop this sequence, so skip generating DROP SEQUENCE
-            if (!(ownedByTableId in branchTables)) {
+            const ownedByTable = branchTables[ownedByTableId];
+            // Owning table is dropped → PG auto-drops the owned sequence.
+            if (!ownedByTable) {
+                continue;
+            }
+            // Owning column is dropped (table survives) → PG still auto-drops the owned
+            // sequence as part of the column drop, so we must not emit DROP SEQUENCE.
+            const ownedByColumnExists = ownedByTable.columns?.some((col) => col.name === sequence.owned_by_column);
+            if (!ownedByColumnExists) {
                 continue;
             }
         }

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

@@ -14,9 +14,21 @@ import { DropTableChange } from "./table.base.ts";
 export declare class DropTable extends DropTableChange {
     readonly table: Table;
     readonly scope: "object";
+    /**
+     * Names of constraints on this table that are dropped explicitly by a
+     * separate `AlterTableDropConstraint` change. Those constraints must not be
+     * claimed by `DropTable.drops` / `.requires`, otherwise catalog edges tied
+     * to the constraint stableId will attach to this DropTable node instead of
+     * the dedicated AlterTableDropConstraint node. When two tables with mutual
+     * FK references are dropped in the same phase, that misattribution
+     * produces an unbreakable cycle between the two DropTable changes.
+     */
+    readonly externallyDroppedConstraints: ReadonlySet<string>;
     constructor(props: {
         table: Table;
+        externallyDroppedConstraints?: ReadonlySet<string>;
     });
+    private get claimedConstraints();
     get drops(): (`column:${string}.${string}.${string}` | `constraint:${string}.${string}.${string}` | `table:${string}`)[];
     get requires(): (`column:${string}.${string}.${string}` | `constraint:${string}.${string}.${string}` | `table:${string}`)[];
     serialize(_options?: SerializeOptions): string;

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

@@ -13,17 +13,34 @@ import { DropTableChange } from "./table.base.js";
 export class DropTable extends DropTableChange {
     table;
     scope = "object";
+    /**
+     * Names of constraints on this table that are dropped explicitly by a
+     * separate `AlterTableDropConstraint` change. Those constraints must not be
+     * claimed by `DropTable.drops` / `.requires`, otherwise catalog edges tied
+     * to the constraint stableId will attach to this DropTable node instead of
+     * the dedicated AlterTableDropConstraint node. When two tables with mutual
+     * FK references are dropped in the same phase, that misattribution
+     * produces an unbreakable cycle between the two DropTable changes.
+     */
+    externallyDroppedConstraints;
     constructor(props) {
         super();
         this.table = props.table;
+        this.externallyDroppedConstraints =
+            props.externallyDroppedConstraints ?? new Set();
+    }
+    get claimedConstraints() {
+        return this.table.constraints.filter((constraint) => !this.externallyDroppedConstraints.has(constraint.name));
     }
     get drops() {
         return [
             this.table.stableId,
             ...this.table.columns.map((column) => stableId.column(this.table.schema, this.table.name, column.name)),
             // Include constraint stableIds so FK relationships that only exist at the
-            // constraint level still affect whole-table drop ordering.
-            ...this.table.constraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
+            // constraint level still affect whole-table drop ordering. Skip any
+            // constraint that the diff layer is dropping via a dedicated
+            // AlterTableDropConstraint change — that node owns the stableId.
+            ...this.claimedConstraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
         ];
     }
     get requires() {
@@ -32,7 +49,7 @@ export class DropTable extends DropTableChange {
             ...this.table.columns.map((col) => stableId.column(this.table.schema, this.table.name, col.name)),
             // Mirror the dropped constraint ids in requires so drop-phase graph
             // consumers can connect catalog FK edges back to this table drop.
-            ...this.table.constraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
+            ...this.claimedConstraints.map((constraint) => stableId.constraint(this.table.schema, this.table.name, constraint.name)),
         ];
     }
     serialize(_options) {

package/dist/core/post-diff-cycle-breaking.d.ts

@@ -0,0 +1,22 @@
+import type { Catalog } from "./catalog.model.ts";
+import type { Change } from "./change.types.ts";
+/**
+ * Normalize change-list cycles that only become apparent after all object
+ * diffs have been collected.
+ *
+ * This pass intentionally handles whole-plan interactions only:
+ * - If replace expansion added `DropTable(T)+CreateTable(T)`, targeted
+ *   `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)` changes are
+ *   redundant and create an unbreakable drop-phase cycle, so we elide them.
+ * - If two dropped tables reference each other via FK, we insert dedicated
+ *   `AlterTableDropConstraint` changes and teach the paired `DropTable`
+ *   changes not to claim those FK stable IDs.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades) stay
+ * in the corresponding `diff*` function instead of this pass.
+ */
+export declare function normalizePostDiffCycles({ changes, mainCatalog, replacedTableIds, }: {
+    changes: Change[];
+    mainCatalog: Catalog;
+    replacedTableIds?: ReadonlySet<string>;
+}): Change[];

package/dist/core/post-diff-cycle-breaking.js

@@ -0,0 +1,143 @@
+import { AlterTableDropColumn, AlterTableDropConstraint, } from "./objects/table/changes/table.alter.js";
+import { DropTable } from "./objects/table/changes/table.drop.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+/**
+ * Yield FK constraints on `table` whose referenced table is also dropped in the
+ * final plan. Self-references are left alone because the sort phase already
+ * handles the resulting self-loop correctly.
+ */
+function* iterCrossDropFkConstraints(table, droppedSet) {
+    for (const constraint of table.constraints) {
+        if (constraint.constraint_type !== "f")
+            continue;
+        if (constraint.is_partition_clone)
+            continue;
+        if (!constraint.foreign_key_schema || !constraint.foreign_key_table) {
+            continue;
+        }
+        const referencedId = stableId.table(constraint.foreign_key_schema, constraint.foreign_key_table);
+        if (referencedId === table.stableId)
+            continue;
+        if (!droppedSet.has(referencedId))
+            continue;
+        yield { constraint, referencedId };
+    }
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (!(change instanceof AlterTableDropColumn) &&
+        !(change instanceof AlterTableDropConstraint)) {
+        return false;
+    }
+    return replacedTableIds.has(change.table.stableId);
+}
+function collectExplicitConstraintDropIds(changes) {
+    const explicitConstraintDropIds = new Set();
+    for (const change of changes) {
+        if (!(change instanceof AlterTableDropConstraint))
+            continue;
+        explicitConstraintDropIds.add(constraintStableId(change.table, change.constraint.name));
+    }
+    return explicitConstraintDropIds;
+}
+function hasSameEntries(left, right) {
+    if (left.size !== right.size)
+        return false;
+    for (const value of left) {
+        if (!right.has(value))
+            return false;
+    }
+    return true;
+}
+/**
+ * Normalize change-list cycles that only become apparent after all object
+ * diffs have been collected.
+ *
+ * This pass intentionally handles whole-plan interactions only:
+ * - If replace expansion added `DropTable(T)+CreateTable(T)`, targeted
+ *   `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)` changes are
+ *   redundant and create an unbreakable drop-phase cycle, so we elide them.
+ * - If two dropped tables reference each other via FK, we insert dedicated
+ *   `AlterTableDropConstraint` changes and teach the paired `DropTable`
+ *   changes not to claim those FK stable IDs.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades) stay
+ * in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffCycles({ changes, mainCatalog, replacedTableIds = new Set(), }) {
+    const structurallyNormalizedChanges = replacedTableIds.size === 0
+        ? changes
+        : changes.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+    const dropTableChanges = structurallyNormalizedChanges.filter((change) => change instanceof DropTable);
+    if (dropTableChanges.length < 2) {
+        return structurallyNormalizedChanges;
+    }
+    const droppedSet = new Set(dropTableChanges.map((change) => change.table.stableId));
+    const droppedFkTargets = new Map();
+    for (const dropTableChange of dropTableChanges) {
+        const mainTable = mainCatalog.tables[dropTableChange.table.stableId] ??
+            dropTableChange.table;
+        const targets = new Set();
+        for (const { referencedId } of iterCrossDropFkConstraints(mainTable, droppedSet)) {
+            targets.add(referencedId);
+        }
+        droppedFkTargets.set(mainTable.stableId, targets);
+    }
+    const explicitConstraintDropIds = collectExplicitConstraintDropIds(structurallyNormalizedChanges);
+    const injectedConstraintDropsByTableId = new Map();
+    const externallyDroppedConstraintsByTableId = new Map();
+    let didMutate = structurallyNormalizedChanges !== changes;
+    for (const dropTableChange of dropTableChanges) {
+        const mainTable = mainCatalog.tables[dropTableChange.table.stableId] ??
+            dropTableChange.table;
+        const externallyDroppedConstraints = new Set(dropTableChange.externallyDroppedConstraints);
+        for (const { constraint, referencedId } of iterCrossDropFkConstraints(mainTable, droppedSet)) {
+            const isMutual = droppedFkTargets.get(referencedId)?.has(mainTable.stableId) === true;
+            if (!isMutual)
+                continue;
+            const droppedConstraintStableId = constraintStableId(mainTable, constraint.name);
+            externallyDroppedConstraints.add(constraint.name);
+            if (!explicitConstraintDropIds.has(droppedConstraintStableId)) {
+                const injectedDrop = new AlterTableDropConstraint({
+                    table: mainTable,
+                    constraint,
+                });
+                const existingDrops = injectedConstraintDropsByTableId.get(mainTable.stableId) ?? [];
+                existingDrops.push(injectedDrop);
+                injectedConstraintDropsByTableId.set(mainTable.stableId, existingDrops);
+                explicitConstraintDropIds.add(droppedConstraintStableId);
+                didMutate = true;
+            }
+        }
+        if (!hasSameEntries(dropTableChange.externallyDroppedConstraints, externallyDroppedConstraints)) {
+            externallyDroppedConstraintsByTableId.set(mainTable.stableId, externallyDroppedConstraints);
+            didMutate = true;
+        }
+    }
+    if (!didMutate) {
+        return changes;
+    }
+    const normalizedChanges = [];
+    for (const change of structurallyNormalizedChanges) {
+        if (!(change instanceof DropTable)) {
+            normalizedChanges.push(change);
+            continue;
+        }
+        const injectedConstraintDrops = injectedConstraintDropsByTableId.get(change.table.stableId) ?? [];
+        if (injectedConstraintDrops.length > 0) {
+            normalizedChanges.push(...injectedConstraintDrops);
+        }
+        const externallyDroppedConstraints = externallyDroppedConstraintsByTableId.get(change.table.stableId);
+        if (!externallyDroppedConstraints) {
+            normalizedChanges.push(change);
+            continue;
+        }
+        normalizedChanges.push(new DropTable({
+            table: change.table,
+            externallyDroppedConstraints,
+        }));
+    }
+    return normalizedChanges;
+}

package/package.json

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

package/src/core/catalog.diff.ts

@@ -1,6 +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";
 
 const debugCatalog = debug("pg-delta:catalog");
 
@@ -232,11 +233,16 @@ export function diffCatalogs(
     return true;
   });
 
-  filteredChanges = expandReplaceDependencies({
+  const expandedDependencies = expandReplaceDependencies({
     changes: filteredChanges,
     mainCatalog: main,
     branchCatalog: branch,
   });
+  filteredChanges = normalizePostDiffCycles({
+    changes: expandedDependencies.changes,
+    mainCatalog: main,
+    replacedTableIds: expandedDependencies.replacedTableIds,
+  });
 
   debugCatalog(
     "changes catalog diff: %O",