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

package/src/core/sort/custom-constraints.ts

@@ -0,0 +1,161 @@
+import type { Change } from "../change.types.ts";
+import { getSchema } from "../integrations/filter/extractors.ts";
+import {
+  GrantRoleDefaultPrivileges,
+  RevokeRoleDefaultPrivileges,
+} from "../objects/role/changes/role.privilege.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Maps object type names to PostgreSQL default privilege objtype codes.
+ * This mirrors the mapping in base.default-privileges.ts.
+ */
+function objectTypeToObjtype(objectType: string): string | null {
+  switch (objectType) {
+    case "table":
+    case "view":
+    case "materialized_view":
+      return "r"; // Relations
+    case "sequence":
+      return "S"; // Sequences
+    case "procedure":
+    case "function":
+    case "aggregate":
+      return "f"; // Functions/routines
+    case "type":
+    case "domain":
+    case "enum":
+    case "range":
+    case "composite_type":
+      return "T"; // Types
+    case "schema":
+      return "n"; // Schemas
+    default:
+      return null;
+  }
+}
+
+/**
+ * A function that generates constraints for a list of changes.
+ * Should be optimized to avoid O(N²) complexity by using lookups/indexing.
+ */
+type ConstraintGenerator = (changes: Change[]) => Constraint[];
+
+/**
+ * Generate constraints to ensure ALTER DEFAULT PRIVILEGES comes before CREATE statements.
+ *
+ * Rules:
+ * - Only applies when the default privilege's schema matches the CREATE statement's schema
+ *   (or if the default privilege is global, applies to all schemas)
+ * - Only applies when the default privilege's objtype matches the CREATE statement's object type
+ * - Excludes CREATE ROLE and CREATE SCHEMA since they are dependencies
+ *   of ALTER DEFAULT PRIVILEGES and must come before it
+ *
+ * implementation: O(N) using schema/objtype indexing.
+ */
+function generateDefaultPrivilegeConstraints(changes: Change[]): Constraint[] {
+  const constraints: Constraint[] = [];
+  const defaultPrivilegeIndices: number[] = [];
+  // Map<objtype_code, Map<schema_name, index[]>>
+  const createsByObjTypeAndSchema = new Map<string, Map<string, number[]>>();
+
+  // Pass 1: Index changes
+  for (let i = 0; i < changes.length; i++) {
+    const change = changes[i];
+
+    // Identify default privilege changes
+    if (
+      change instanceof GrantRoleDefaultPrivileges ||
+      change instanceof RevokeRoleDefaultPrivileges
+    ) {
+      defaultPrivilegeIndices.push(i);
+      continue;
+    }
+
+    // Identify CREATE object changes (excluding role/schema)
+    if (
+      change.operation === "create" &&
+      change.scope === "object" &&
+      change.objectType !== "role" &&
+      change.objectType !== "schema"
+    ) {
+      const objTypeCode = objectTypeToObjtype(change.objectType);
+      if (!objTypeCode) continue;
+
+      const schema = getSchema(change);
+      // Default privileges only apply to schema-contained objects.
+      if (schema) {
+        let schemaMap = createsByObjTypeAndSchema.get(objTypeCode);
+        if (!schemaMap) {
+          schemaMap = new Map();
+          createsByObjTypeAndSchema.set(objTypeCode, schemaMap);
+        }
+
+        let indices = schemaMap.get(schema);
+        if (!indices) {
+          indices = [];
+          schemaMap.set(schema, indices);
+        }
+        indices.push(i);
+      }
+    }
+  }
+
+  // Pass 2: Generate constraints
+  for (const privIndex of defaultPrivilegeIndices) {
+    const privChange = changes[privIndex] as {
+      inSchema: string | null;
+      objtype: string;
+    };
+    const privSchema = privChange.inSchema;
+    const privObjType = privChange.objtype;
+
+    const schemaMap = createsByObjTypeAndSchema.get(privObjType);
+    if (!schemaMap) continue;
+
+    if (privSchema === null) {
+      // Global default privilege: applies to ALL schemas
+      for (const indices of schemaMap.values()) {
+        for (const createIndex of indices) {
+          // (No self-check needed as types differ)
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    } else {
+      // Specific schema: applies only to that schema
+      const indices = schemaMap.get(privSchema);
+      if (indices) {
+        for (const createIndex of indices) {
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * All custom constraint generators.
+ */
+const customConstraintGenerators: ConstraintGenerator[] = [
+  generateDefaultPrivilegeConstraints,
+];
+
+/**
+ * Generate Constraints from custom constraint generators.
+ *
+ * Iterates through registered generators to produce constraints.
+ * Generators should be optimized (e.g. using indexing) to avoid O(N²) complexity.
+ */
+export function generateCustomConstraints(changes: Change[]): Constraint[] {
+  return customConstraintGenerators.flatMap((generate) => generate(changes));
+}

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