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

package/src/core/sort/cycle-breakers.ts

@@ -0,0 +1,311 @@
+import type { Change } from "../change.types.ts";
+import { AlterPublicationDropTables } from "../objects/publication/changes/publication.alter.ts";
+import {
+  AlterTableDropColumn,
+  AlterTableDropConstraint,
+} from "../objects/table/changes/table.alter.ts";
+import { DropTable } from "../objects/table/changes/table.drop.ts";
+import type { TableConstraintProps } from "../objects/table/table.model.ts";
+import { stableId } from "../objects/utils.ts";
+
+/**
+ * Try to break an unbreakable cycle by INJECTING NEW CHANGES or REWRITING
+ * existing ones (rather than removing graph edges).
+ *
+ * Called by `sortPhaseChanges` when its edge-removal cycle handler has seen
+ * the same cycle twice — i.e. weak-edge filtering exhausted itself but the
+ * cycle is still there. At that point we know the cycle is composed of
+ * "hard" edges (explicit `requires` or pg_depend rows) that can only be
+ * broken by changing the change list itself.
+ *
+ * Returns a rewritten `phaseChanges` array, or `null` if no breaker matches
+ * (in which case the caller throws the existing CycleError).
+ */
+export function tryBreakCycleByChangeInjection(
+  cycleNodeIndexes: readonly number[],
+  phaseChanges: readonly Change[],
+): Change[] | null {
+  // ─── Branch A: FK cycle among DropTable changes ──────────────────────
+  // Triggered when N≥2 dropped tables reference each other via foreign
+  // keys. With no surviving table on either side, every FK constraint
+  // stable-id ends up tied back to a DropTable node, and every
+  // pg_depend row produces a hard explicit edge between two DropTables.
+  // Edge filtering can't break it — the edges are not weak.
+  //
+  // Example (3-cycle):
+  //   DROP TABLE a; DROP TABLE b; DROP TABLE c;
+  //   where  a.b_id REFERENCES b,  b.c_id REFERENCES c,  c.a_id REFERENCES a
+  //
+  // Fix: inject a dedicated `ALTER TABLE ... DROP CONSTRAINT fk` ahead of
+  // each DropTable in the cycle, and mark the constraint name on
+  // `DropTable.externallyDroppedConstraints` so the table drop won't try
+  // to re-claim the same constraint stable-id. The injected drops have
+  // their own stable-id ownership and run before any DropTable, breaking
+  // the cycle.
+  //
+  // This naturally handles any N (2-cycle, 3-cycle, …) because
+  // `findCycle` already gave us the full member list — no separate SCC
+  // enumeration needed.
+  const fkBroken = tryBreakFkCycle(cycleNodeIndexes, phaseChanges);
+  if (fkBroken) return fkBroken;
+
+  // ─── Branch B: Publication ↔ Column on a surviving table ─────────────
+  // Triggered when a publication has an explicit column list and one of
+  // those columns is dropped on a table that itself is NOT being dropped
+  // (the table just loses one column).
+  //
+  // Example:
+  //   CREATE PUBLICATION p FOR TABLE lab_results (id, flash_summary);
+  //   ALTER TABLE lab_results DROP COLUMN flash_summary;
+  //
+  // Diff emits two drop-phase changes:
+  //   AlterPublicationDropTables(p, [lab_results])
+  //   AlterTableDropColumn(lab_results.flash_summary)
+  //
+  // The cycle:
+  //   pub:p → col:lab_results.flash_summary  (catalog, pg_depend)
+  //   col:lab_results.flash_summary → table:lab_results
+  //                                         (explicit, AlterTableDropColumn.requires)
+  //
+  // Fix: rebuild the AlterTableDropColumn with `omitTableRequirement=true`
+  // so it no longer requires `table:lab_results`. Safe because
+  // `lab_results` survives the migration; its lifetime trivially covers
+  // the column drop. The catalog edge `pub → col` correctly orders the
+  // publication drop before the column drop.
+  const pubColBroken = tryBreakPublicationColumnCycle(
+    cycleNodeIndexes,
+    phaseChanges,
+  );
+  if (pubColBroken) return pubColBroken;
+
+  // No known pattern. Returning null lets sortPhaseChanges throw the
+  // formatted CycleError with full diagnostic — better a clear bug
+  // report than silently shipping a broken plan.
+  return null;
+}
+
+/**
+ * Branch A worker — inject `AlterTableDropConstraint` for every FK linking
+ * two DropTables in the cycle.
+ *
+ * Returns the rewritten changes array, or `null` if the cycle does not
+ * match (e.g. mixed types, or no cross-cycle FK exists).
+ */
+function tryBreakFkCycle(
+  cycleNodeIndexes: readonly number[],
+  phaseChanges: readonly Change[],
+): Change[] | null {
+  // Guard: every member of the cycle must be a DropTable. Mixed cycles
+  // (e.g. DropTable + DropView, or DropTable + DropMaterializedView) are
+  // out of scope — they need a different breaker.
+  const cycleDropTables: DropTable[] = [];
+  for (const nodeIndex of cycleNodeIndexes) {
+    const change = phaseChanges[nodeIndex];
+    if (!(change instanceof DropTable)) return null;
+    cycleDropTables.push(change);
+  }
+
+  const cycleTableIds = new Set(
+    cycleDropTables.map((change) => change.table.stableId),
+  );
+
+  // For each DropTable in the cycle, find every FK whose referenced table
+  // is also in the cycle. Each such FK becomes one injected
+  // `AlterTableDropConstraint` and one entry on the source table's
+  // `externallyDroppedConstraints`.
+  //
+  // 2-cycle example: { A→B, B→A } — two FKs, two injected drops.
+  // 3-cycle example: { A→B, B→C, C→A } — three FKs, three injected drops.
+  const injectedDropsByTableId = new Map<string, AlterTableDropConstraint[]>();
+  const updatedExternalsByTableId = new Map<string, Set<string>>();
+  let didMutate = false;
+
+  for (const dropTable of cycleDropTables) {
+    const tableId = dropTable.table.stableId;
+    const existingExternals = new Set(dropTable.externallyDroppedConstraints);
+    let tableMutated = false;
+
+    for (const fk of iterCrossCycleFkConstraints(
+      dropTable.table.constraints,
+      tableId,
+      cycleTableIds,
+    )) {
+      // Skip if a same-table `AlterTableDropConstraint` is already in the
+      // change list — could happen if a previous breaker iteration
+      // injected one, or the diff layer emitted one explicitly.
+      if (existingExternals.has(fk.name)) continue;
+      if (alreadyHasExplicitDrop(phaseChanges, tableId, fk.name)) continue;
+
+      const injected = new AlterTableDropConstraint({
+        table: dropTable.table,
+        constraint: fk,
+      });
+      const list = injectedDropsByTableId.get(tableId) ?? [];
+      list.push(injected);
+      injectedDropsByTableId.set(tableId, list);
+      existingExternals.add(fk.name);
+      tableMutated = true;
+      didMutate = true;
+    }
+
+    if (tableMutated) {
+      updatedExternalsByTableId.set(tableId, existingExternals);
+    }
+  }
+
+  if (!didMutate) return null;
+
+  // Rebuild phaseChanges: keep all non-DropTable changes in place. For
+  // each DropTable in the cycle that gained injected drops, emit the
+  // injected drops first, then a fresh DropTable carrying the updated
+  // `externallyDroppedConstraints` so it stops claiming the FK
+  // stable-ids.
+  const rewritten: Change[] = [];
+  for (const change of phaseChanges) {
+    if (!(change instanceof DropTable)) {
+      rewritten.push(change);
+      continue;
+    }
+    const tableId = change.table.stableId;
+    const injected = injectedDropsByTableId.get(tableId);
+    if (injected) {
+      rewritten.push(...injected);
+    }
+    const updatedExternals = updatedExternalsByTableId.get(tableId);
+    if (updatedExternals) {
+      rewritten.push(
+        new DropTable({
+          table: change.table,
+          externallyDroppedConstraints: updatedExternals,
+        }),
+      );
+    } else {
+      rewritten.push(change);
+    }
+  }
+  return rewritten;
+}
+
+/**
+ * Yield FK constraints on `constraints` whose referenced table is also a
+ * member of the cycle (i.e. an FK strictly between two cycle DropTables).
+ *
+ * Self-referencing FKs are skipped — they create a self-loop in the
+ * dependency graph which the existing sort-phase handler resolves on its
+ * own; injecting an `AlterTableDropConstraint` for a self-FK would just
+ * add noise.
+ */
+function* iterCrossCycleFkConstraints(
+  constraints: readonly TableConstraintProps[],
+  ownTableId: string,
+  cycleTableIds: ReadonlySet<string>,
+): Iterable<TableConstraintProps> {
+  for (const constraint of 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 === ownTableId) continue;
+    if (!cycleTableIds.has(referencedId)) continue;
+    yield constraint;
+  }
+}
+
+/**
+ * True iff `phaseChanges` already contains an explicit
+ * `AlterTableDropConstraint(table, constraint)` for the given pair —
+ * either emitted by the diff layer or by a previous breaker iteration.
+ * Avoids duplicate constraint drops.
+ */
+function alreadyHasExplicitDrop(
+  phaseChanges: readonly Change[],
+  tableId: string,
+  constraintName: string,
+): boolean {
+  for (const change of phaseChanges) {
+    if (!(change instanceof AlterTableDropConstraint)) continue;
+    if (change.table.stableId !== tableId) continue;
+    if (change.constraint.name === constraintName) return true;
+  }
+  return false;
+}
+
+/**
+ * Branch B worker — break the publication↔column cycle by rebuilding the
+ * `AlterTableDropColumn` change with `omitTableRequirement=true`.
+ *
+ * Returns the rewritten changes array, or `null` if the cycle does not
+ * match (e.g. table is also being dropped, or no `AlterPublicationDropTables`
+ * references the table).
+ */
+function tryBreakPublicationColumnCycle(
+  cycleNodeIndexes: readonly number[],
+  phaseChanges: readonly Change[],
+): Change[] | null {
+  // Find an `AlterTableDropColumn` and an `AlterPublicationDropTables` in
+  // the cycle that reference the same table. Both must be present —
+  // otherwise this is a different cycle shape.
+  let dropColumnIndex = -1;
+  let dropColumnChange: AlterTableDropColumn | null = null;
+  let pubMatchesTable = false;
+  let pubChange: AlterPublicationDropTables | null = null;
+
+  for (const nodeIndex of cycleNodeIndexes) {
+    const change = phaseChanges[nodeIndex];
+    if (
+      change instanceof AlterTableDropColumn &&
+      !change.omitTableRequirement
+    ) {
+      dropColumnIndex = nodeIndex;
+      dropColumnChange = change;
+    } else if (change instanceof AlterPublicationDropTables) {
+      pubChange = change;
+    }
+  }
+  if (dropColumnChange === null || pubChange === null) return null;
+
+  // Verify the publication is actually dropping membership for the same
+  // table whose column is being dropped. Without this check we'd risk
+  // rewriting an unrelated AlterTableDropColumn that happens to share a
+  // cycle with some other publication change.
+  const targetTableId = dropColumnChange.table.stableId;
+  for (const t of pubChange.tables) {
+    if (stableId.table(t.schema, t.name) === targetTableId) {
+      pubMatchesTable = true;
+      break;
+    }
+  }
+  if (!pubMatchesTable) 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)
+  // 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
+  // drop reorder against the table drop, which is unsafe.
+  for (const change of phaseChanges) {
+    if (
+      change instanceof DropTable &&
+      change.table.stableId === targetTableId
+    ) {
+      return null;
+    }
+  }
+
+  // Replace the AlterTableDropColumn with a fresh instance carrying
+  // `omitTableRequirement=true`. All other changes pass through
+  // unchanged.
+  const rewritten: Change[] = phaseChanges.slice();
+  rewritten[dropColumnIndex] = new AlterTableDropColumn({
+    table: dropColumnChange.table,
+    column: dropColumnChange.column,
+    omitTableRequirement: true,
+  });
+  return rewritten;
+}

package/src/core/sort/sort-changes.ts

@@ -15,6 +15,7 @@ import debug from "debug";
 import type { Catalog } from "../catalog.model.ts";
 import type { Change } from "../change.types.ts";
 import { generateCustomConstraints } from "./custom-constraints.ts";
+import { tryBreakCycleByChangeInjection } from "./cycle-breakers.ts";
 import { printDebugGraph } from "./debug-visualization.ts";
 
 const debugGraph = debug("pg-delta:graph");
@@ -40,6 +41,14 @@ import {
 import type { PgDependRow, PhaseSortOptions } from "./types.ts";
 import { getExecutionPhase, type Phase } from "./utils.ts";
 
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
+
 /**
  * Sort changes using dependency information from catalogs and custom constraints.
  *
@@ -110,24 +119,50 @@ function sortChangesByPhasedGraph(
 }
 
 /**
- * Sort changes within a phase using Constraints derived from all dependency sources.
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+function normalizeCycle(cycleNodeIndexes: number[]): string {
+  if (cycleNodeIndexes.length === 0) return "";
+  const minIndex = Math.min(...cycleNodeIndexes);
+  const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
+  const rotated = [
+    ...cycleNodeIndexes.slice(minIndexPos),
+    ...cycleNodeIndexes.slice(0, minIndexPos),
+  ];
+  return rotated.join(",");
+}
+
+type SortRoundResult =
+  | { kind: "sorted"; sorted: Change[] }
+  | {
+      kind: "unbreakable";
+      cycleNodeIndexes: number[];
+      cycleEdges: ReturnType<typeof getEdgesInCycle>;
+    };
+
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
  *
  * Algorithm:
- * 1. Build graph data (change sets and reverse indexes)
- * 2. Convert all sources to Constraints (catalog, explicit, custom constraints)
- * 3. Convert Constraints to edges
- * 4. Iteratively detect and break cycles (deduplicate edges, detect cycles, filter problematic edges)
- * 5. Perform stable topological sort on the acyclic graph
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
  *
- * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
  */
-function sortPhaseChanges(
+function attemptSortRound(
   phaseChanges: Change[],
   dependencyRows: PgDependRow[],
-  options: PhaseSortOptions = {},
-): Change[] {
-  if (phaseChanges.length <= 1) return phaseChanges;
-
+  options: PhaseSortOptions,
+): SortRoundResult {
   // Step 1: Build graph data structures
   const graphData = buildGraphData(phaseChanges, options);
 
@@ -150,54 +185,31 @@ function sortPhaseChanges(
   // Step 3: Convert constraints to edges and deduplicate immediately
   let edges = dedupeEdges(convertConstraintsToEdges(allConstraints, options));
 
-  // Step 4: Iteratively detect and break cycles
-  // Track cycles we've seen to detect when filtering fails to break a cycle.
-  // The only way we loop indefinitely is if we encounter a cycle we've already seen,
-  // which means filtering didn't break it. Otherwise, we continue until all cycles are broken.
+  // Step 4: Iteratively detect and break cycles by edge filtering.
+  // We loop until no cycles remain OR we see the same cycle twice — the
+  // latter signals that edge filtering exhausted itself. At that point
+  // the caller may dispatch a change-injection breaker; if no breaker
+  // matches, the original throw path runs.
   const seenCycles = new Set<string>();
 
-  /**
-   * Normalize a cycle by rotating it to start with the smallest node index.
-   * This allows us to compare cycles regardless of where they start.
-   */
-  function normalizeCycle(cycleNodeIndexes: number[]): string {
-    if (cycleNodeIndexes.length === 0) return "";
-    const minIndex = Math.min(...cycleNodeIndexes);
-    const minIndexPos = cycleNodeIndexes.indexOf(minIndex);
-    const rotated = [
-      ...cycleNodeIndexes.slice(minIndexPos),
-      ...cycleNodeIndexes.slice(0, minIndexPos),
-    ];
-    return rotated.join(",");
-  }
-
   while (true) {
-    // Edge deduplication moved outside loop
     const edgePairs = edgesToPairs(edges);
-
-    // Detect cycles
     const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
 
-    if (!cycleNodeIndexes) {
-      // No cycles found, we're done
-      break;
-    }
+    if (!cycleNodeIndexes) break;
 
-    // Normalize cycle to check if we've seen it before
     const cycleSignature = normalizeCycle(cycleNodeIndexes);
     if (seenCycles.has(cycleSignature)) {
-      // We've seen this cycle before - filtering didn't break it
-      // Get edges involved in the cycle for detailed error message
-      const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
-      throw new Error(
-        formatCycleError(cycleNodeIndexes, phaseChanges, cycleEdges),
-      );
+      // Edge filtering can't break this cycle. Report it back to the
+      // caller so it can try change-injection before throwing.
+      return {
+        kind: "unbreakable",
+        cycleNodeIndexes,
+        cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+      };
     }
-
-    // Track this cycle
     seenCycles.add(cycleSignature);
 
-    // Filter only edges involved in the cycle to break it
     edges = filterEdgesForCycleBreaking(
       edges,
       cycleNodeIndexes,
@@ -208,7 +220,6 @@ function sortPhaseChanges(
 
   const finalEdgePairs = edgesToPairs(edges);
 
-  // Debug visualization
   if (debugGraph.enabled) {
     printDebugGraph(
       phaseChanges,
@@ -230,5 +241,79 @@ function sortPhaseChanges(
     throw new Error("CycleError: dependency graph contains a cycle");
   }
 
-  return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+  return {
+    kind: "sorted",
+    sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+  };
+}
+
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(
+  initialPhaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions = {},
+): Change[] {
+  if (initialPhaseChanges.length <= 1) return initialPhaseChanges;
+
+  let phaseChanges = initialPhaseChanges;
+  const breakerRoundSignatures = new Set<string>();
+
+  // `attemptSortRound` returns at most one unbreakable cycle per call,
+  // so a phase with K independent unbreakable cycles needs K+1 rounds.
+  // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+  // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+  // using `initialPhaseChanges.length` itself is therefore a real upper
+  // bound with one round of slack (and matches the early-return guard
+  // above, which already excluded length-0 and length-1 phases).
+  const maxRounds = initialPhaseChanges.length;
+
+  for (let round = 0; round <= maxRounds; round++) {
+    const result = attemptSortRound(phaseChanges, dependencyRows, options);
+    if (result.kind === "sorted") return result.sorted;
+
+    // Edge filtering hit an unbreakable cycle. Try the change-injection
+    // breakers (FK pattern, publication↔column pattern). If none matches,
+    // throw with the same diagnostic the original code emitted.
+    const broken = tryBreakCycleByChangeInjection(
+      result.cycleNodeIndexes,
+      phaseChanges,
+    );
+    if (broken === null) {
+      throw new Error(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+      );
+    }
+
+    // Loop guard: if the same cycle node-set re-appears after a break,
+    // the breaker isn't making progress. Throw with full context.
+    const signature = normalizeCycle(result.cycleNodeIndexes);
+    if (breakerRoundSignatures.has(signature)) {
+      throw new Error(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+      );
+    }
+    breakerRoundSignatures.add(signature);
+
+    phaseChanges = broken;
+  }
+
+  throw new Error(
+    `CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`,
+  );
 }