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

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

@@ -0,0 +1,184 @@
+import type { Change } from "../change.types.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Stable topological sort. If multiple zero-indegree nodes exist, picks the
+ * smallest original index first to preserve input order among unconstrained items.
+ * Returns null on cycles.
+ */
+export function performStableTopologicalSort(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<Set<number>> = Array.from(
+    { length: nodeCount },
+    () => new Set<number>(),
+  );
+  const inDegreeCounts = new Array<number>(nodeCount).fill(0);
+
+  for (const [sourceIndex, targetIndex] of edges) {
+    if (!adjacencyList[sourceIndex].has(targetIndex)) {
+      adjacencyList[sourceIndex].add(targetIndex);
+      inDegreeCounts[targetIndex]++;
+    }
+  }
+
+  const candidateQueue: number[] = [];
+  for (let nodeIndex = 0; nodeIndex < nodeCount; nodeIndex++) {
+    if (inDegreeCounts[nodeIndex] === 0) candidateQueue.push(nodeIndex);
+  }
+  candidateQueue.sort((left, right) => left - right);
+
+  const orderedNodeIndexes: number[] = [];
+  while (candidateQueue.length > 0) {
+    const nodeIndex = candidateQueue.shift() as number;
+    orderedNodeIndexes.push(nodeIndex);
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      inDegreeCounts[neighborIndex]--;
+      if (inDegreeCounts[neighborIndex] === 0) {
+        let inserted = false;
+        for (
+          let queuePosition = 0;
+          queuePosition < candidateQueue.length;
+          queuePosition++
+        ) {
+          if (neighborIndex < candidateQueue[queuePosition]) {
+            candidateQueue.splice(queuePosition, 0, neighborIndex);
+            inserted = true;
+            break;
+          }
+        }
+        if (!inserted) candidateQueue.push(neighborIndex);
+      }
+    }
+  }
+
+  if (orderedNodeIndexes.length !== nodeCount) return null; // cycle detected
+  return orderedNodeIndexes;
+}
+
+/**
+ * Find one cycle (if any) and return its node indices in order.
+ */
+export function findCycle(
+  nodeCount: number,
+  edges: Array<[number, number]>,
+): number[] | null {
+  const adjacencyList: Array<number[]> = Array.from(
+    { length: nodeCount },
+    () => [],
+  );
+  for (const [sourceIndex, targetIndex] of edges) {
+    adjacencyList[sourceIndex].push(targetIndex);
+  }
+
+  // 0 = unvisited, 1 = visiting, 2 = completed
+  const visitState = new Array<number>(nodeCount).fill(0);
+  const pathStack: number[] = [];
+  let cycleNodeIndexes: number[] | null = null;
+
+  const depthFirstSearch = (nodeIndex: number) => {
+    if (cycleNodeIndexes) return;
+    visitState[nodeIndex] = 1;
+    pathStack.push(nodeIndex);
+
+    for (const neighborIndex of adjacencyList[nodeIndex]) {
+      if (visitState[neighborIndex] === 0) {
+        depthFirstSearch(neighborIndex);
+      } else if (visitState[neighborIndex] === 1) {
+        const cycleStartIndex = pathStack.lastIndexOf(neighborIndex);
+        if (cycleStartIndex !== -1) {
+          cycleNodeIndexes = pathStack.slice(cycleStartIndex);
+        }
+        return;
+      }
+      if (cycleNodeIndexes) return;
+    }
+
+    pathStack.pop();
+    visitState[nodeIndex] = 2;
+  };
+
+  for (
+    let nodeIndex = 0;
+    nodeIndex < nodeCount && !cycleNodeIndexes;
+    nodeIndex++
+  ) {
+    if (visitState[nodeIndex] === 0) depthFirstSearch(nodeIndex);
+  }
+
+  return cycleNodeIndexes;
+}
+
+/**
+ * Format a cycle error message with details about the changes involved and the edges forming the cycle.
+ */
+export function formatCycleError(
+  cycleNodeIndexes: number[],
+  phaseChanges: Change[],
+  cycleEdges?: Array<{
+    sourceIndex: number;
+    targetIndex: number;
+    constraint: Constraint;
+  }>,
+): string {
+  const cycleChanges = cycleNodeIndexes.map((idx) => phaseChanges[idx]);
+  const changeDescriptions = cycleChanges.map((change, i) => {
+    const className = change?.constructor?.name ?? "Change";
+    const creates = change.creates.slice(0, 2).join(", ");
+    return `  ${i + 1}. [${cycleNodeIndexes[i]}] ${className}${creates ? ` (creates: ${creates}${change.creates.length > 2 ? "..." : ""})` : ""}`;
+  });
+
+  let message = `CycleError: dependency graph contains a cycle involving ${cycleNodeIndexes.length} changes:\n${changeDescriptions.join("\n")}`;
+
+  // Add cycle path information if edges are provided
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\n\nCycle path (edges forming the cycle):`;
+    for (let i = 0; i < cycleNodeIndexes.length; i++) {
+      const sourceIndex = cycleNodeIndexes[i];
+      const targetIndex = cycleNodeIndexes[(i + 1) % cycleNodeIndexes.length];
+      const edge = cycleEdges.find(
+        (e) => e.sourceIndex === sourceIndex && e.targetIndex === targetIndex,
+      );
+
+      if (edge) {
+        const constraint = edge.constraint;
+        let edgeInfo = `\n  [${sourceIndex}] → [${targetIndex}] (source: ${constraint.source})`;
+
+        if (
+          constraint.source === "catalog" ||
+          constraint.source === "explicit"
+        ) {
+          if (constraint.reason.dependentStableId) {
+            edgeInfo += `\n    Dependency: ${constraint.reason.dependentStableId} → ${constraint.reason.referencedStableId}`;
+          } else {
+            edgeInfo += `\n    Requires: ${constraint.reason.referencedStableId}`;
+          }
+        }
+
+        // Add why it wasn't filtered
+        if (constraint.source === "custom") {
+          edgeInfo += `\n    Reason: Custom constraint (never filtered)`;
+        } else if (
+          constraint.source === "explicit" &&
+          !constraint.reason.dependentStableId
+        ) {
+          edgeInfo += `\n    Reason: Explicit requirement without created IDs (not filtered)`;
+        } else {
+          edgeInfo += `\n    Reason: Cycle-breaking filter did not match (edge preserved)`;
+        }
+
+        message += edgeInfo;
+      } else {
+        message += `\n  [${sourceIndex}] → [${targetIndex}] (edge not found)`;
+      }
+    }
+  }
+
+  message += `\n\nThis usually indicates a circular dependency in the schema changes that cannot be resolved.`;
+  if (cycleEdges && cycleEdges.length > 0) {
+    message += `\nThe cycle-breaking filters were unable to break this cycle.`;
+  }
+
+  return message;
+}

package/src/core/sort/types.ts

@@ -0,0 +1,112 @@
+/**
+ * pg_depend rows that matter for ordering.
+ *
+ * These represent dependency relationships extracted from PostgreSQL's pg_depend catalog.
+ */
+export type PgDependRow = {
+  /** Object that depends on `referenced_stable_id`. */
+  dependent_stable_id: string;
+  /** Object being depended upon. */
+  referenced_stable_id: string;
+  /**
+   * Dependency type as defined in PostgreSQL's pg_depend.deptype.
+   *
+   * - "n" (normal): Ordinary dependency — if the referenced object is dropped, the dependent object is also dropped automatically.
+   * - "a" (auto): Automatically created dependency — the dependent object was created as a result of creating the referenced object,
+   *   and should be dropped automatically when the referenced object is dropped, but not otherwise treated as a strong link.
+   * - "i" (internal): Internal dependency — the dependent object is a low-level part of the referenced object.
+   */
+  deptype: "n" | "a" | "i";
+};
+
+/**
+ * Constraint representing that one change must come before another.
+ *
+ * Unified abstraction for all ordering requirements:
+ * - Catalog dependencies (from pg_depend) → Constraints
+ * - Explicit requirements (from Change.requires) → Constraints
+ * - Custom constraints (change-to-change rules) → Constraints
+ */
+export type Constraint =
+  | CatalogConstraint
+  | ExplicitConstraint
+  | CustomConstraint;
+
+/**
+ * Base constraint properties shared by all constraint types.
+ */
+interface BaseConstraint {
+  /** Index of the change that must come first */
+  sourceChangeIndex: number;
+  /** Index of the change that must come after */
+  targetChangeIndex: number;
+}
+
+/**
+ * Constraint from catalog dependencies (pg_depend).
+ * Always has both dependent and referenced stable IDs.
+ */
+interface CatalogConstraint extends BaseConstraint {
+  source: "catalog";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId */
+    dependentStableId: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from explicit requirements (Change.requires).
+ * Always has referencedStableId, but dependentStableId is optional
+ * if the change doesn't create anything.
+ */
+interface ExplicitConstraint extends BaseConstraint {
+  source: "explicit";
+  /** The stable ID dependency that led to this constraint */
+  reason: {
+    /** The stable ID that depends on referencedStableId (undefined if change doesn't create anything) */
+    dependentStableId?: string;
+    /** The stable ID being depended upon */
+    referencedStableId: string;
+  };
+}
+
+/**
+ * Constraint from custom constraint functions.
+ * No reason field since these are direct change-to-change ordering rules.
+ */
+interface CustomConstraint extends BaseConstraint {
+  source: "custom";
+  /** Optional description for debugging */
+  description?: string;
+}
+
+export interface PhaseSortOptions {
+  /** If true, invert edges so drops run in reverse dependency order. */
+  invert?: boolean;
+}
+
+/**
+ * Edge with its originating constraint for filtering purposes.
+ */
+export interface Edge {
+  sourceIndex: number;
+  targetIndex: number;
+  constraint: Constraint;
+}
+
+/**
+ * Graph data structures for converting dependencies to Constraints.
+ */
+export interface GraphData {
+  /** Maps each change index to the set of stable IDs it creates. */
+  createdStableIdSets: Array<Set<string>>;
+  /** Maps each change index to the set of stable IDs it explicitly requires. */
+  explicitRequirementSets: Array<Set<string>>;
+  /** Maps a stable ID to the set of change indices that create it. */
+  changeIndexesByCreatedId: Map<string, Set<number>>;
+  /** Maps a stable ID to the set of change indices that explicitly require it. */
+  changeIndexesByExplicitRequirementId: Map<string, Set<number>>;
+}

package/src/core/sort/utils.ts

@@ -0,0 +1,69 @@
+import type { Change } from "../change.types.ts";
+
+/**
+ * Execution phases for changes.
+ */
+export type Phase = "drop" | "create_alter_object";
+
+/**
+ * Check if a stable ID represents metadata (ACL, default privileges, comments, etc.)
+ * rather than an actual database object.
+ *
+ * Unified check used by both logical sorting and dependency sorting.
+ */
+export function isMetadataStableId(stableId: string): boolean {
+  return (
+    stableId.startsWith("acl:") ||
+    stableId.startsWith("defacl:") ||
+    stableId.startsWith("aclcol:") ||
+    stableId.startsWith("membership:") ||
+    stableId.startsWith("comment:")
+  );
+}
+
+/**
+ * Determine the execution phase for a change based on its properties.
+ *
+ * Rules:
+ * - DROP operations → drop phase
+ * - CREATE operations → create_alter_object phase
+ * - ALTER operations with scope="privilege" → create_alter_object phase (metadata changes)
+ * - ALTER operations that drop actual objects → drop phase (destructive ALTER)
+ * - ALTER operations that don't drop objects → create_alter_object phase (non-destructive ALTER)
+ */
+export function getExecutionPhase(change: Change): Phase {
+  // DROP operations always go to drop phase
+  if (change.operation === "drop") {
+    return "drop";
+  }
+
+  // CREATE operations always go to create_alter phase
+  if (change.operation === "create") {
+    return "create_alter_object";
+  }
+
+  // For ALTER operations, determine based on what they do
+  if (change.operation === "alter") {
+    // Privilege changes (metadata) always go to create_alter phase
+    if (change.scope === "privilege") {
+      return "create_alter_object";
+    }
+
+    // Check if this ALTER drops actual objects (not metadata)
+    const droppedIds = change.drops ?? [];
+    const dropsObjects = droppedIds.some(
+      (id: string) => !isMetadataStableId(id),
+    );
+
+    if (dropsObjects) {
+      // Destructive ALTER (DROP COLUMN, DROP CONSTRAINT, etc.) → drop phase
+      return "drop";
+    }
+
+    // Non-destructive ALTER (ADD COLUMN, GRANT, etc.) → create_alter phase
+    return "create_alter_object";
+  }
+
+  // Safe default
+  return "create_alter_object";
+}

package/src/core/test-utils/assert-valid-sql.ts

@@ -0,0 +1,20 @@
+import { validateSqlSyntax } from "@supabase/pg-topo";
+
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export async function assertValidSql(sql: string): Promise<void> {
+  try {
+    await validateSqlSyntax(sql);
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : "Unknown parser error";
+    throw new Error(`Invalid SQL syntax: ${message}\nSQL: ${sql}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+
+// Catalog model and extraction
+export {
+  Catalog,
+  createEmptyCatalog,
+  extractCatalog,
+} from "./core/catalog.model.ts";
+export type { CatalogSnapshot } from "./core/catalog.snapshot.ts";
+export {
+  deserializeCatalog,
+  serializeCatalog,
+  stringifyCatalogSnapshot,
+} from "./core/catalog.snapshot.ts";
+
+// Declarative schema export
+export { exportDeclarativeSchema } from "./core/export/index.ts";
+export type {
+  DeclarativeSchemaOutput,
+  FileCategory,
+  FileEntry,
+  FileMetadata,
+} from "./core/export/types.ts";
+
+// Integrations
+export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+
+// Plan operations
+export { applyPlan } from "./core/plan/apply.ts";
+export type { CatalogInput } from "./core/plan/create.ts";
+export { createPlan } from "./core/plan/create.ts";
+export type { SqlFormatOptions } from "./core/plan/sql-format.ts";
+export { formatSqlStatements } from "./core/plan/sql-format.ts";
+export type { CreatePlanOptions, Plan } from "./core/plan/types.ts";
+
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.ts";