@supabase/pg-delta 0.0.0 → 1.0.0-alpha.0

package/dist/core/sort/sort-changes.js

@@ -0,0 +1,147 @@
+/**
+ * Phased dependency-graph sort for ordered schema changes.
+ *
+ * Changes are split into two execution phases:
+ * - `drop`: Destructive operations (executed first, in reverse dependency order)
+ * - `create_alter_object`: All remaining changes (executed second, in forward dependency order)
+ *
+ * Within each phase, changes are sorted using Constraints derived from:
+ * - Catalog dependencies (from pg_depend)
+ * - Explicit requirements (from Change.requires)
+ * - Custom constraints (change-to-change ordering rules)
+ */
+import debug from "debug";
+import { generateCustomConstraints } from "./custom-constraints.js";
+import { printDebugGraph } from "./debug-visualization.js";
+const debugGraph = debug("pg-delta:graph");
+import { filterEdgesForCycleBreaking, getEdgesInCycle, } from "./dependency-filter.js";
+import { buildGraphData, convertCatalogDependenciesToConstraints, convertConstraintsToEdges, convertExplicitRequirementsToConstraints, edgesToPairs, } from "./graph-builder.js";
+import { dedupeEdges } from "./graph-utils.js";
+import { logicalSort } from "./logical-sort.js";
+import { findCycle, formatCycleError, performStableTopologicalSort, } from "./topological-sort.js";
+import { getExecutionPhase } from "./utils.js";
+/**
+ * Sort changes using dependency information from catalogs and custom constraints.
+ *
+ * First applies logical pre-sorting to group related changes together,
+ * then applies dependency-based topological sorting to ensure correct execution order.
+ *
+ * @param catalogs - Main and branch catalogs containing dependency information
+ * @param changes - List of Change objects to order
+ * @returns Ordered list of Change objects
+ */
+export function sortChanges(catalogs, changes) {
+    // Step 1: Apply logical pre-sorting to group changes by object type, stable ID, and scope
+    const logicallySorted = logicalSort(changes);
+    // Step 2: Apply dependency-based topological sorting
+    return sortChangesByPhasedGraph({
+        mainCatalog: { depends: catalogs.mainCatalog.depends },
+        branchCatalog: { depends: catalogs.branchCatalog.depends },
+    }, logicallySorted);
+}
+/**
+ * Sort changes by phases, using dependency information in each phase.
+ *
+ * @param catalogContext - pg_depend rows from the main and branch catalogs
+ * @param changeList - list of Change objects to order
+ * @returns ordered list of Change objects
+ */
+function sortChangesByPhasedGraph(catalogContext, changeList) {
+    const changesByPhase = {
+        drop: [],
+        create_alter_object: [],
+    };
+    // Partition changes into execution phases
+    for (const changeItem of changeList) {
+        const phase = getExecutionPhase(changeItem);
+        changesByPhase[phase].push(changeItem);
+    }
+    // Sort DROP phase: reverse dependency order using main catalog dependencies
+    const sortedDropPhase = sortPhaseChanges(changesByPhase.drop, catalogContext.mainCatalog.depends, { invert: true });
+    // Sort CREATE/ALTER phase: forward dependency order using branch catalog dependencies
+    const sortedCreateAlterPhase = sortPhaseChanges(changesByPhase.create_alter_object, catalogContext.branchCatalog.depends, {});
+    return [...sortedDropPhase, ...sortedCreateAlterPhase];
+}
+/**
+ * Sort changes within a phase using Constraints derived from all dependency sources.
+ *
+ * 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
+ *
+ * In DROP phase, edges are inverted so drops run in reverse dependency order.
+ */
+function sortPhaseChanges(phaseChanges, dependencyRows, options = {}) {
+    if (phaseChanges.length <= 1)
+        return phaseChanges;
+    // Step 1: Build graph data structures
+    const graphData = buildGraphData(phaseChanges, options);
+    // Step 2: Convert all sources to Constraints
+    const catalogConstraints = convertCatalogDependenciesToConstraints(dependencyRows, graphData);
+    const explicitConstraints = convertExplicitRequirementsToConstraints(phaseChanges, graphData);
+    const customConstraintObjects = generateCustomConstraints(phaseChanges);
+    const allConstraints = [
+        ...catalogConstraints,
+        ...explicitConstraints,
+        ...customConstraintObjects,
+    ];
+    // 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.
+    const seenCycles = new Set();
+    /**
+     * 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) {
+        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;
+        }
+        // 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));
+        }
+        // Track this cycle
+        seenCycles.add(cycleSignature);
+        // Filter only edges involved in the cycle to break it
+        edges = filterEdgesForCycleBreaking(edges, cycleNodeIndexes, phaseChanges, graphData);
+    }
+    const finalEdgePairs = edgesToPairs(edges);
+    // Debug visualization
+    if (debugGraph.enabled) {
+        printDebugGraph(phaseChanges, graphData, finalEdgePairs, dependencyRows, allConstraints);
+    }
+    // Step 5: Perform stable topological sort (no cycles, so this will succeed)
+    const topologicalOrder = performStableTopologicalSort(phaseChanges.length, finalEdgePairs);
+    if (!topologicalOrder || topologicalOrder.length !== phaseChanges.length) {
+        // This should never happen if findCycle returned null, but guard anyway
+        throw new Error("CycleError: dependency graph contains a cycle");
+    }
+    return topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]);
+}

package/dist/core/sort/topological-sort.d.ts

@@ -0,0 +1,20 @@
+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 declare function performStableTopologicalSort(nodeCount: number, edges: Array<[number, number]>): number[] | null;
+/**
+ * Find one cycle (if any) and return its node indices in order.
+ */
+export declare function findCycle(nodeCount: number, edges: Array<[number, number]>): number[] | null;
+/**
+ * Format a cycle error message with details about the changes involved and the edges forming the cycle.
+ */
+export declare function formatCycleError(cycleNodeIndexes: number[], phaseChanges: Change[], cycleEdges?: Array<{
+    sourceIndex: number;
+    targetIndex: number;
+    constraint: Constraint;
+}>): string;

package/dist/core/sort/topological-sort.js

@@ -0,0 +1,138 @@
+/**
+ * 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, edges) {
+    const adjacencyList = Array.from({ length: nodeCount }, () => new Set());
+    const inDegreeCounts = new Array(nodeCount).fill(0);
+    for (const [sourceIndex, targetIndex] of edges) {
+        if (!adjacencyList[sourceIndex].has(targetIndex)) {
+            adjacencyList[sourceIndex].add(targetIndex);
+            inDegreeCounts[targetIndex]++;
+        }
+    }
+    const candidateQueue = [];
+    for (let nodeIndex = 0; nodeIndex < nodeCount; nodeIndex++) {
+        if (inDegreeCounts[nodeIndex] === 0)
+            candidateQueue.push(nodeIndex);
+    }
+    candidateQueue.sort((left, right) => left - right);
+    const orderedNodeIndexes = [];
+    while (candidateQueue.length > 0) {
+        const nodeIndex = candidateQueue.shift();
+        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, edges) {
+    const adjacencyList = Array.from({ length: nodeCount }, () => []);
+    for (const [sourceIndex, targetIndex] of edges) {
+        adjacencyList[sourceIndex].push(targetIndex);
+    }
+    // 0 = unvisited, 1 = visiting, 2 = completed
+    const visitState = new Array(nodeCount).fill(0);
+    const pathStack = [];
+    let cycleNodeIndexes = null;
+    const depthFirstSearch = (nodeIndex) => {
+        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, phaseChanges, cycleEdges) {
+    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/dist/core/sort/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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>>;
+}
+export {};

package/dist/core/sort/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/sort/utils.d.ts

@@ -0,0 +1,23 @@
+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 declare function isMetadataStableId(stableId: string): boolean;
+/**
+ * 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 declare function getExecutionPhase(change: Change): Phase;

package/dist/core/sort/utils.js

@@ -0,0 +1,51 @@
+/**
+ * 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) {
+    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) {
+    // 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) => !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/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./core/index.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./core/index.js";

package/package.json

@@ -1,19 +1,65 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "0.0.0",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "1.0.0-alpha.0",
+  "description": "PostgreSQL migrations made easy",
+  "type": "module",
+  "sideEffects": false,
+  "exports": "./dist/index.js",
+  "bin": {
+    "pgdelta": "./dist/cli/bin/cli.js"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pg",
+    "postgres",
+    "migrations",
+    "diff",
+    "pg-delta",
+    "pgdelta"
+  ],
+  "author": "Supabase",
+  "license": "MIT",
+  "homepage": "https://github.com/supabase/pg-delta",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/supabase/pg-delta.git"
+    "url": "https://github.com/supabase/pg-delta.git"
   },
-  "author": "",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/supabase/pg-delta/issues"
+  "bugs": "https://github.com/supabase/pg-delta/issues",
+  "engines": {
+    "node": ">=20.0.0"
   },
-  "homepage": "https://github.com/supabase/pg-delta#readme",
-  "description": ""
-}
+  "dependencies": {
+    "@stricli/core": "^1.2.4",
+    "chalk": "^5.6.2",
+    "debug": "^4.3.7",
+    "postgres": "^3.4.7",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@changesets/cli": "^2.29.8",
+    "@tsconfig/node-ts": "^23.6.2",
+    "@tsconfig/node24": "^24.0.3",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^24.10.4",
+    "@vitest/coverage-v8": "4.0.16",
+    "dedent": "^1.7.1",
+    "knip": "^5.75.2",
+    "testcontainers": "^11.10.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "format-and-lint": "biome check . --error-on-warnings",
+    "knip": "knip",
+    "pgdelta": "node src/cli/bin/cli.ts",
+    "test": "vitest",
+    "version": "changeset version && pnpm install --no-frozen-lockfile && pnpm format-and-lint --write"
+  }
+}