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

package/src/core/sort/dependency-filter.ts

@@ -0,0 +1,224 @@
+import type { Change } from "../change.types.ts";
+import { CreateSequence } from "../objects/sequence/changes/sequence.create.ts";
+import { stableId } from "../objects/utils.ts";
+import { findConsumerIndexes } from "./graph-utils.ts";
+import type { Edge, GraphData } from "./types.ts";
+
+/**
+ * Check if a sequence is owned by a given column.
+ *
+ * @param sequence - The sequence object with ownership information
+ * @param referencedStableId - The column stable ID to check against
+ * @returns true if the sequence is owned by the referenced column
+ */
+function isSequenceOwnedBy(
+  sequence: {
+    owned_by_schema: string | null;
+    owned_by_table: string | null;
+    owned_by_column: string | null;
+  },
+  referencedStableId: string,
+): boolean {
+  if (
+    !sequence.owned_by_schema ||
+    !sequence.owned_by_table ||
+    !sequence.owned_by_column
+  ) {
+    return false;
+  }
+
+  const ownedByColumnId = stableId.column(
+    sequence.owned_by_schema,
+    sequence.owned_by_table,
+    sequence.owned_by_column,
+  );
+
+  return referencedStableId === ownedByColumnId;
+}
+
+/**
+ * Check if a sequence ownership dependency should be filtered to prevent cycles.
+ *
+ * CYCLE SCENARIO:
+ * When a sequence is owned by a table column that also uses the sequence (via DEFAULT),
+ * PostgreSQL's pg_depend creates a bidirectional dependency cycle:
+ *   1. column → sequence (column default depends on sequence)
+ *   2. sequence → column (sequence ownership depends on column)
+ *
+ * This creates: sequence → column → sequence (cycle!)
+ *
+ * HOW WE BREAK THE CYCLE:
+ * We filter out the ownership dependency edge (sequence → column) because:
+ *   - CREATE phase: Sequences should be created before tables. Ownership is set later
+ *     via ALTER SEQUENCE OWNED BY after both the sequence and table exist.
+ *   - DROP phase: Prevents cycles when dropping sequences owned by tables that
+ *     aren't being dropped.
+ *
+ * PARAMETERS:
+ * @param dependentStableId - The sequence stable ID (e.g., "sequence:schema.seq_name")
+ * @param referencedStableId - The column stable ID (e.g., "column:schema.table.col")
+ *   Note: PostgreSQL's pg_depend creates sequence ownership dependencies on columns (not tables)
+ *   when refobjsubid > 0, so we only check for column dependencies
+ * @param phaseChanges - All changes in the current phase
+ * @param graphData - Graph data structures for looking up changes
+ * @returns true if this ownership dependency should be filtered (removed) to break the cycle
+ */
+function shouldFilterSequenceOwnershipDependency(
+  dependentStableId: string,
+  referencedStableId: string,
+  phaseChanges: Change[],
+  graphData: GraphData,
+): boolean {
+  // Early exit: only filter edges FROM sequences TO columns
+  // Note: PostgreSQL's pg_depend creates sequence ownership dependencies on columns (not tables)
+  // when refobjsubid > 0, so we only need to check for column dependencies
+  if (
+    !dependentStableId.startsWith("sequence:") ||
+    !referencedStableId.startsWith("column:")
+  ) {
+    return false;
+  }
+
+  // Find all changes that create or consume this sequence
+  // (includes the CreateSequence change that creates it)
+  const changesInvolvingSequence = findConsumerIndexes(
+    dependentStableId,
+    graphData.changeIndexesByCreatedId,
+    graphData.changeIndexesByExplicitRequirementId,
+  );
+
+  // Check if any CreateSequence change creates a sequence that is owned by
+  // the referenced table/column. If so, filter this ownership dependency edge.
+  for (const changeIndex of changesInvolvingSequence) {
+    const change = phaseChanges[changeIndex];
+
+    // Only filter edges from CreateSequence changes, not AlterSequenceSetOwnedBy.
+    // AlterSequenceSetOwnedBy is a separate change that sets ownership after
+    // both the sequence and table exist, so it doesn't create the cycle.
+    if (!(change instanceof CreateSequence)) {
+      continue;
+    }
+
+    // Check if this CreateSequence creates a sequence owned by the referenced table/column
+    if (isSequenceOwnedBy(change.sequence, referencedStableId)) {
+      return true; // Filter this edge to break the cycle
+    }
+  }
+
+  return false; // Don't filter - this is not a cycle-causing ownership dependency
+}
+
+/**
+ * Cycle-breaking filters for stable ID dependencies.
+ *
+ * Prevents cycles that would occur due to special PostgreSQL behaviors.
+ * Delegates to specific filter functions for each type of cycle.
+ *
+ * @param dependentStableId - The dependent object's stable ID
+ * @param referencedStableId - The referenced object's stable ID
+ * @param phaseChanges - All changes in the current phase
+ * @param graphData - Graph data structures for looking up changes
+ * @returns true if this dependency edge should be filtered (removed) to break a cycle
+ */
+function shouldFilterStableIdDependencyForCycleBreaking(
+  dependentStableId: string,
+  referencedStableId: string,
+  phaseChanges: Change[],
+  graphData: GraphData,
+): boolean {
+  // Filter sequence ownership dependencies that create cycles with column defaults
+  if (
+    shouldFilterSequenceOwnershipDependency(
+      dependentStableId,
+      referencedStableId,
+      phaseChanges,
+      graphData,
+    )
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Identify edges that are part of a cycle.
+ *
+ * Given cycle node indices, returns edges where both source and target are in the cycle
+ * and form consecutive nodes in the cycle path.
+ */
+export function getEdgesInCycle(
+  cycleNodeIndexes: number[],
+  edges: Edge[],
+): Edge[] {
+  const cycleEdges: Edge[] = [];
+
+  // Create a map of edges for quick lookup
+  const edgeMap = new Map<string, Edge>();
+  for (const edge of edges) {
+    const key = `${edge.sourceIndex}->${edge.targetIndex}`;
+    edgeMap.set(key, edge);
+  }
+
+  // Find edges that connect consecutive nodes in the cycle
+  for (let i = 0; i < cycleNodeIndexes.length; i++) {
+    const sourceIndex = cycleNodeIndexes[i];
+    const targetIndex = cycleNodeIndexes[(i + 1) % cycleNodeIndexes.length];
+    const key = `${sourceIndex}->${targetIndex}`;
+    const edge = edgeMap.get(key);
+    if (edge) {
+      cycleEdges.push(edge);
+    }
+  }
+
+  return cycleEdges;
+}
+
+/**
+ * Filter edges involved in cycles based on their constraint's cycle-breaking rules.
+ *
+ * This is applied when cycles are detected to break them by removing problematic edges.
+ * Only filters edges that:
+ * 1. Are part of the detected cycle(s)
+ * 2. Have a reason (stable ID dependency) - custom constraints are never filtered
+ * 3. Match the cycle-breaking filter criteria
+ */
+export function filterEdgesForCycleBreaking(
+  edges: Edge[],
+  cycleNodeIndexes: number[],
+  phaseChanges: Change[],
+  graphData: GraphData,
+): Edge[] {
+  // Get edges that are part of the cycle
+  const cycleEdges = getEdgesInCycle(cycleNodeIndexes, edges);
+  // Use string keys for comparison since Set.has() uses reference equality
+  const cycleEdgeKeys = new Set(
+    cycleEdges.map((e) => `${e.sourceIndex}->${e.targetIndex}`),
+  );
+
+  return edges.filter((edge) => {
+    const edgeKey = `${edge.sourceIndex}->${edge.targetIndex}`;
+    // If edge is not in the cycle, keep it
+    if (!cycleEdgeKeys.has(edgeKey)) {
+      return true;
+    }
+
+    // Edge is in cycle - check if it should be filtered
+    const constraint = edge.constraint;
+
+    // Custom constraints are never filtered
+    if (constraint.source === "custom") return true;
+
+    const { dependentStableId, referencedStableId } = constraint.reason;
+    // Skip if dependentStableId is undefined (explicit requirement without created IDs)
+    if (!dependentStableId) return true;
+
+    // Apply cycle-breaking filters - return false to filter out this edge
+    return !shouldFilterStableIdDependencyForCycleBreaking(
+      dependentStableId,
+      referencedStableId,
+      phaseChanges,
+      graphData,
+    );
+  });
+}

package/src/core/sort/graph-builder.ts

@@ -0,0 +1,235 @@
+import type { Change } from "../change.types.ts";
+import { findConsumerIndexes } from "./graph-utils.ts";
+import type {
+  Constraint,
+  Edge,
+  GraphData,
+  PgDependRow,
+  PhaseSortOptions,
+} from "./types.ts";
+
+/**
+ * Convert catalog dependencies to Constraints.
+ *
+ * For each catalog dependency (stable ID → stable ID), finds the changes that
+ * create/require those stable IDs and creates Constraints between them.
+ *
+ * Filters out unknown stable IDs (basic validation).
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export function convertCatalogDependenciesToConstraints(
+  dependencyRows: PgDependRow[],
+  graphData: GraphData,
+): Constraint[] {
+  const constraints: Constraint[] = [];
+
+  for (const row of dependencyRows) {
+    // Filter out unknown stable IDs (basic validation)
+    if (
+      row.referenced_stable_id.startsWith("unknown:") ||
+      row.dependent_stable_id.startsWith("unknown:")
+    ) {
+      continue;
+    }
+    const producerIndexes = graphData.changeIndexesByCreatedId.get(
+      row.referenced_stable_id,
+    );
+    if (!producerIndexes || producerIndexes.size === 0) continue;
+
+    const consumerIndexes = findConsumerIndexes(
+      row.dependent_stable_id,
+      graphData.changeIndexesByCreatedId,
+      graphData.changeIndexesByExplicitRequirementId,
+    );
+    if (consumerIndexes.size === 0) continue;
+
+    for (const producerIndex of producerIndexes) {
+      for (const consumerIndex of consumerIndexes) {
+        if (producerIndex === consumerIndex) continue;
+        constraints.push({
+          sourceChangeIndex: producerIndex,
+          targetChangeIndex: consumerIndex,
+          source: "catalog",
+          reason: {
+            dependentStableId: row.dependent_stable_id,
+            referencedStableId: row.referenced_stable_id,
+          },
+        });
+      }
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * Convert explicit requirements to Constraints.
+ *
+ * For each change that explicitly requires something:
+ * - If the change creates stable IDs, creates Constraints from producers of required IDs to this change
+ * - If the change doesn't create anything but requires something, creates Constraints from producers to this change
+ *
+ * Cycle-breaking filters are applied later when detecting cycles.
+ */
+export function convertExplicitRequirementsToConstraints(
+  phaseChanges: Change[],
+  graphData: GraphData,
+): Constraint[] {
+  const constraints: Constraint[] = [];
+
+  for (
+    let consumerIndex = 0;
+    consumerIndex < phaseChanges.length;
+    consumerIndex++
+  ) {
+    const createdIds = graphData.createdStableIdSets[consumerIndex];
+    const requiredIds = graphData.explicitRequirementSets[consumerIndex];
+
+    if (requiredIds.size === 0) continue;
+
+    // Collect dropped IDs for this change so we can skip requirements
+    // for stableIds that this change also drops.  A change that drops a
+    // stableId should not depend on another change that creates the same
+    // stableId, because the entity already exists in the source database.
+    // This prevents false ordering constraints such as Grant → Revoke
+    // when both operate on the same ACL stableId.
+    const droppedIds = new Set<string>(phaseChanges[consumerIndex].drops);
+
+    for (const requiredId of requiredIds) {
+      if (droppedIds.has(requiredId)) {
+        continue;
+      }
+
+      const producerIndexes =
+        graphData.changeIndexesByCreatedId.get(requiredId);
+      if (!producerIndexes || producerIndexes.size === 0) continue;
+
+      if (createdIds.size > 0) {
+        for (const createdId of createdIds) {
+          for (const producerIndex of producerIndexes) {
+            if (producerIndex === consumerIndex) continue;
+            constraints.push({
+              sourceChangeIndex: producerIndex,
+              targetChangeIndex: consumerIndex,
+              source: "explicit",
+              reason: {
+                dependentStableId: createdId,
+                referencedStableId: requiredId,
+              },
+            });
+          }
+        }
+      } else {
+        // Change doesn't create anything but requires something
+        for (const producerIndex of producerIndexes) {
+          if (producerIndex === consumerIndex) continue;
+          constraints.push({
+            sourceChangeIndex: producerIndex,
+            targetChangeIndex: consumerIndex,
+            source: "explicit",
+            reason: {
+              referencedStableId: requiredId,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * Build graph data structures from phase changes.
+ *
+ * Creates change sets and reverse indexes needed for converting dependencies to Constraints.
+ * In DROP phase (invert=true), dropped IDs are included in createdStableIdSets.
+ */
+export function buildGraphData(
+  phaseChanges: Change[],
+  options: PhaseSortOptions,
+): GraphData {
+  const createdStableIdSets: Array<Set<string>> = phaseChanges.map(
+    (changeItem) => {
+      const createdIds = new Set<string>(changeItem.creates);
+      if (options.invert) {
+        for (const droppedId of changeItem.drops ?? []) {
+          createdIds.add(droppedId);
+        }
+      }
+      return createdIds;
+    },
+  );
+
+  const explicitRequirementSets: Array<Set<string>> = phaseChanges.map(
+    (changeItem) => new Set<string>(changeItem.requires ?? []),
+  );
+
+  const changeIndexesByCreatedId = new Map<string, Set<number>>();
+  for (let changeIndex = 0; changeIndex < phaseChanges.length; changeIndex++) {
+    for (const createdId of createdStableIdSets[changeIndex]) {
+      let producerIndexes = changeIndexesByCreatedId.get(createdId);
+      if (!producerIndexes) {
+        producerIndexes = new Set<number>();
+        changeIndexesByCreatedId.set(createdId, producerIndexes);
+      }
+      producerIndexes.add(changeIndex);
+    }
+  }
+
+  const changeIndexesByExplicitRequirementId = new Map<string, Set<number>>();
+  for (
+    let changeIndex = 0;
+    changeIndex < explicitRequirementSets.length;
+    changeIndex++
+  ) {
+    for (const requiredId of explicitRequirementSets[changeIndex]) {
+      let consumerIndexes =
+        changeIndexesByExplicitRequirementId.get(requiredId);
+      if (!consumerIndexes) {
+        consumerIndexes = new Set<number>();
+        changeIndexesByExplicitRequirementId.set(requiredId, consumerIndexes);
+      }
+      consumerIndexes.add(changeIndex);
+    }
+  }
+
+  return {
+    createdStableIdSets,
+    explicitRequirementSets,
+    changeIndexesByCreatedId,
+    changeIndexesByExplicitRequirementId,
+  };
+}
+
+/**
+ * Convert Constraints to edges.
+ */
+export function convertConstraintsToEdges(
+  constraints: Constraint[],
+  options: PhaseSortOptions,
+): Edge[] {
+  const edges: Edge[] = [];
+  for (const constraint of constraints) {
+    if (constraint.sourceChangeIndex === constraint.targetChangeIndex) continue;
+    const sourceIndex = options.invert
+      ? constraint.targetChangeIndex
+      : constraint.sourceChangeIndex;
+    const targetIndex = options.invert
+      ? constraint.sourceChangeIndex
+      : constraint.targetChangeIndex;
+    edges.push({
+      sourceIndex,
+      targetIndex,
+      constraint,
+    });
+  }
+  return edges;
+}
+
+/**
+ * Convert edges to simple edge pairs for cycle detection and sorting.
+ */
+export function edgesToPairs(edges: Edge[]): Array<[number, number]> {
+  return edges.map((edge) => [edge.sourceIndex, edge.targetIndex]);
+}

package/src/core/sort/graph-utils.ts

@@ -0,0 +1,51 @@
+import type { Edge } from "./types.ts";
+
+/**
+ * Find all change indices that could be consumers for a given dependent stable ID.
+ *
+ * A consumer is either:
+ * 1. A change that explicitly requires the dependent ID, OR
+ * 2. A change that creates the dependent ID (since creating something implies
+ *    it depends on its own dependencies)
+ */
+export function findConsumerIndexes(
+  dependentStableId: string,
+  changeIndexesByCreatedId: Map<string, Set<number>>,
+  changeIndexesByExplicitRequirementId: Map<string, Set<number>>,
+): Set<number> {
+  const consumerIndexes = new Set<number>();
+
+  // Add changes that explicitly require this ID
+  const explicitConsumerIndexes =
+    changeIndexesByExplicitRequirementId.get(dependentStableId);
+  if (explicitConsumerIndexes) {
+    for (const consumerIndex of explicitConsumerIndexes) {
+      consumerIndexes.add(consumerIndex);
+    }
+  }
+
+  // Add changes that create this ID (they are consumers of dependencies)
+  const dependentProducers = changeIndexesByCreatedId.get(dependentStableId);
+  if (dependentProducers) {
+    for (const producerIndex of dependentProducers) {
+      consumerIndexes.add(producerIndex);
+    }
+  }
+
+  return consumerIndexes;
+}
+
+/**
+ * Deduplicate edges, keeping the first occurrence.
+ */
+export function dedupeEdges(edges: Edge[]): Edge[] {
+  const seenEdges = new Set<string>();
+  const uniqueEdges: Edge[] = [];
+  for (const edge of edges) {
+    const edgeKey = `${edge.sourceIndex}->${edge.targetIndex}`;
+    if (seenEdges.has(edgeKey)) continue;
+    seenEdges.add(edgeKey);
+    uniqueEdges.push(edge);
+  }
+  return uniqueEdges;
+}