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

package/src/core/sort/debug-visualization.ts

@@ -0,0 +1,239 @@
+import debug from "debug";
+import type { Change } from "../change.types.ts";
+import { findCycle } from "./topological-sort.ts";
+import type { Constraint, GraphData, PgDependRow } from "./types.ts";
+
+const debugGraph = debug("pg-delta:graph");
+
+/**
+ * Generate a Mermaid diagram representation of the dependency graph for debugging.
+ */
+function generateMermaidDiagram(
+  phaseChanges: Change[],
+  graphData: GraphData,
+  edges: Array<[number, number]>,
+  requirementSets: Array<Set<string>>,
+  dependenciesByReferencedId: Map<string, Set<string>>,
+): string {
+  const cycleNodeIndexes = findCycle(phaseChanges.length, edges) ?? [];
+  const mermaidLines: string[] = [];
+  mermaidLines.push("flowchart TD");
+
+  // Add nodes
+  for (let changeIndex = 0; changeIndex < phaseChanges.length; changeIndex++) {
+    const changeInstance = phaseChanges[changeIndex];
+    const changeClassName = changeInstance?.constructor?.name ?? "Change";
+    const truncatedCreates = Array.isArray(changeInstance.creates)
+      ? changeInstance.creates.slice(0, 3)
+      : [];
+    const nodeLabel = `${changeIndex}: ${changeClassName} ${
+      truncatedCreates.length > 0 ? `[${truncatedCreates.join(",")}]` : ""
+    }`.replaceAll('"', "'");
+    mermaidLines.push(`  n${changeIndex}["${nodeLabel}"]`);
+  }
+
+  // Add edges with descriptions
+  for (const [sourceIndex, targetIndex] of edges) {
+    const edgeDescription = describeEdge(
+      sourceIndex,
+      targetIndex,
+      graphData,
+      requirementSets,
+      dependenciesByReferencedId,
+    ).replaceAll('"', "'");
+    if (edgeDescription.length > 0) {
+      mermaidLines.push(
+        `  n${sourceIndex} -- "${edgeDescription}" --> n${targetIndex}`,
+      );
+    } else {
+      mermaidLines.push(`  n${sourceIndex} --> n${targetIndex}`);
+    }
+  }
+
+  // Highlight cycles if any
+  if (cycleNodeIndexes.length > 0) {
+    mermaidLines.push(
+      "  classDef cycleNode fill:#ffe6e6,stroke:#ff4d4f,stroke-width:2px;",
+    );
+    for (const nodeIndex of cycleNodeIndexes) {
+      mermaidLines.push(`  class n${nodeIndex} cycleNode;`);
+    }
+
+    const cycleEdges: Array<[number, number]> = [];
+    for (
+      let cycleIndex = 0;
+      cycleIndex < cycleNodeIndexes.length;
+      cycleIndex++
+    ) {
+      const sourceIndex = cycleNodeIndexes[cycleIndex];
+      const targetIndex =
+        cycleNodeIndexes[(cycleIndex + 1) % cycleNodeIndexes.length];
+      cycleEdges.push([sourceIndex, targetIndex]);
+    }
+
+    let edgeIndex = 0;
+    for (const [sourceIndex, targetIndex] of edges) {
+      const edgeBelongsToCycle = cycleEdges.some(
+        ([cycleSourceIndex, cycleTargetIndex]) =>
+          cycleSourceIndex === sourceIndex && cycleTargetIndex === targetIndex,
+      );
+      if (edgeBelongsToCycle) {
+        mermaidLines.push(
+          `  linkStyle ${edgeIndex} stroke:#ff4d4f,stroke-width:2px;`,
+        );
+      }
+      edgeIndex++;
+    }
+  }
+
+  return mermaidLines.join("\n");
+}
+
+/**
+ * Build requirementSets from explicit requirements and constraints (for debug visualization).
+ *
+ * This reconstructs what requirements were inferred from constraints by looking at
+ * the constraints that were processed. Only processes catalog/explicit constraints,
+ * as custom constraints don't affect requirement sets.
+ */
+function buildRequirementSets(
+  explicitRequirementSets: Array<Set<string>>,
+  constraints: Constraint[],
+  changeIndexesByCreatedId: Map<string, Set<number>>,
+  _changeIndexesByExplicitRequirementId: Map<string, Set<number>>,
+): Array<Set<string>> {
+  // Start with explicit requirements
+  const requirementSets: Array<Set<string>> = explicitRequirementSets.map(
+    (explicitRequirements) => new Set<string>(explicitRequirements),
+  );
+
+  // Add requirements inferred from catalog/explicit constraints
+  // For each constraint with a reason, if the referenced ID is created by some change,
+  // then the target change requires the referenced ID
+  for (const constraint of constraints) {
+    // Only process catalog/explicit constraints (custom constraints don't affect requirements)
+    if (constraint.source === "custom" || !constraint.reason) continue;
+
+    const referencedProducers = changeIndexesByCreatedId.get(
+      constraint.reason.referencedStableId,
+    );
+    if (!referencedProducers || referencedProducers.size === 0) continue;
+
+    // The target change requires the referenced stable ID
+    requirementSets[constraint.targetChangeIndex].add(
+      constraint.reason.referencedStableId,
+    );
+  }
+
+  return requirementSets;
+}
+
+/**
+ * Build dependenciesByReferencedId from dependency rows (for debug visualization).
+ */
+function buildDependenciesByReferencedId(
+  dependencyRows: PgDependRow[],
+): Map<string, Set<string>> {
+  const dependenciesByReferencedId = new Map<string, Set<string>>();
+  for (const dependencyRow of dependencyRows) {
+    // Filter out unknown dependencies
+    if (
+      dependencyRow.referenced_stable_id.startsWith("unknown:") ||
+      dependencyRow.dependent_stable_id.startsWith("unknown:")
+    ) {
+      continue;
+    }
+
+    let dependentIds = dependenciesByReferencedId.get(
+      dependencyRow.referenced_stable_id,
+    );
+    if (!dependentIds) {
+      dependentIds = new Set<string>();
+      dependenciesByReferencedId.set(
+        dependencyRow.referenced_stable_id,
+        dependentIds,
+      );
+    }
+    dependentIds.add(dependencyRow.dependent_stable_id);
+  }
+  return dependenciesByReferencedId;
+}
+
+/**
+ * Describe an edge in the dependency graph for visualization.
+ */
+function describeEdge(
+  sourceIndex: number,
+  targetIndex: number,
+  graphData: GraphData,
+  requirementSets: Array<Set<string>>,
+  dependenciesByReferencedId: Map<string, Set<string>>,
+): string {
+  // Check if target explicitly requires something created by source
+  for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+    if (requirementSets[targetIndex].has(createdId)) {
+      return `${createdId} -> (requires)`;
+    }
+  }
+
+  // Check pg_depend relationships
+  for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+    const outgoingDependencies = dependenciesByReferencedId.get(createdId);
+    if (!outgoingDependencies) continue;
+
+    // Check if target requires this ID
+    for (const requiredId of requirementSets[targetIndex]) {
+      if (outgoingDependencies.has(requiredId)) {
+        return `${createdId} -> ${requiredId}`;
+      }
+    }
+
+    // Check if target creates something that depends on this ID
+    for (const targetCreatedId of graphData.createdStableIdSets[targetIndex]) {
+      if (outgoingDependencies.has(targetCreatedId)) {
+        return `${createdId} -> ${targetCreatedId}`;
+      }
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Print debug information about the dependency graph.
+ *
+ * Builds debug-only data structures (requirementSets, dependenciesByReferencedId) just-in-time.
+ */
+export function printDebugGraph(
+  phaseChanges: Change[],
+  graphData: GraphData,
+  edges: Array<[number, number]>,
+  dependencyRows: PgDependRow[],
+  constraints: Constraint[],
+): void {
+  try {
+    // Build debug-only data structures just-in-time
+    const requirementSets = buildRequirementSets(
+      graphData.explicitRequirementSets,
+      constraints,
+      graphData.changeIndexesByCreatedId,
+      graphData.changeIndexesByExplicitRequirementId,
+    );
+    const dependenciesByReferencedId =
+      buildDependenciesByReferencedId(dependencyRows);
+
+    const mermaidDiagram = generateMermaidDiagram(
+      phaseChanges,
+      graphData,
+      edges,
+      requirementSets,
+      dependenciesByReferencedId,
+    );
+    debugGraph(
+      "\n==== Mermaid (cycle detected) ====\n%s\n==== end ====",
+      mermaidDiagram,
+    );
+  } catch (_error) {
+    // ignore debug printing errors
+  }
+}

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]);
+}