@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.30

package/src/core/sort/sort-changes.test.ts

@@ -0,0 +1,390 @@
+import { describe, expect, test } from "bun:test";
+import { Catalog, createEmptyCatalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import type { PgDepend } from "../depend.ts";
+import { AlterPublicationDropTables } from "../objects/publication/changes/publication.alter.ts";
+import { Publication } from "../objects/publication/publication.model.ts";
+import {
+  AlterTableAlterColumnType,
+  AlterTableDropConstraint,
+} from "../objects/table/changes/table.alter.ts";
+import { DropTable } from "../objects/table/changes/table.drop.ts";
+import { Table } from "../objects/table/table.model.ts";
+import { CreateView } from "../objects/view/changes/view.create.ts";
+import { DropView } from "../objects/view/changes/view.drop.ts";
+import { View } from "../objects/view/view.model.ts";
+import { sortChanges } from "./sort-changes.ts";
+
+const baseTableProps = {
+  schema: "public",
+  persistence: "p" as const,
+  row_security: false,
+  force_row_security: false,
+  has_indexes: false,
+  has_rules: false,
+  has_triggers: false,
+  has_subclasses: false,
+  is_populated: true,
+  replica_identity: "d" as const,
+  is_partition: false,
+  options: null,
+  partition_bound: null,
+  partition_by: null,
+  owner: "postgres",
+  comment: null,
+  parent_schema: null,
+  parent_name: null,
+  privileges: [],
+};
+
+function integerColumn(name: string, position: number) {
+  return {
+    name,
+    position,
+    data_type: "integer",
+    data_type_str: "integer",
+    is_custom_type: false,
+    custom_type_type: null,
+    custom_type_category: null,
+    custom_type_schema: null,
+    custom_type_name: null,
+    not_null: false,
+    is_identity: false,
+    is_identity_always: false,
+    is_generated: false,
+    collation: null,
+    default: null,
+    comment: null,
+  };
+}
+
+function fkConstraint(props: {
+  name: string;
+  fkColumn: string;
+  targetTable: string;
+  targetColumn?: string;
+}) {
+  const targetColumn = props.targetColumn ?? "id";
+  return {
+    name: props.name,
+    constraint_type: "f" as const,
+    deferrable: false,
+    initially_deferred: false,
+    validated: true,
+    is_local: true,
+    no_inherit: false,
+    is_temporal: false,
+    is_partition_clone: false,
+    parent_constraint_schema: null,
+    parent_constraint_name: null,
+    parent_table_schema: null,
+    parent_table_name: null,
+    key_columns: [props.fkColumn],
+    foreign_key_columns: [targetColumn],
+    foreign_key_table: props.targetTable,
+    foreign_key_schema: "public",
+    foreign_key_table_is_partition: false,
+    foreign_key_parent_schema: null,
+    foreign_key_parent_table: null,
+    foreign_key_effective_schema: "public",
+    foreign_key_effective_table: props.targetTable,
+    on_update: "a" as const,
+    on_delete: "a" as const,
+    match_type: "s" as const,
+    check_expression: null,
+    owner: "postgres",
+    definition: `FOREIGN KEY (${props.fkColumn}) REFERENCES public.${props.targetTable}(${targetColumn})`,
+    comment: null,
+  };
+}
+
+function uniqueConstraint(name: string, column: string) {
+  return {
+    name,
+    constraint_type: "u" as const,
+    deferrable: false,
+    initially_deferred: false,
+    validated: true,
+    is_local: true,
+    no_inherit: false,
+    is_temporal: false,
+    is_partition_clone: false,
+    parent_constraint_schema: null,
+    parent_constraint_name: null,
+    parent_table_schema: null,
+    parent_table_name: null,
+    key_columns: [column],
+    foreign_key_columns: null,
+    foreign_key_table: null,
+    foreign_key_schema: null,
+    foreign_key_table_is_partition: null,
+    foreign_key_parent_schema: null,
+    foreign_key_parent_table: null,
+    foreign_key_effective_schema: null,
+    foreign_key_effective_table: null,
+    on_update: null,
+    on_delete: null,
+    match_type: null,
+    check_expression: null,
+    owner: "postgres",
+    definition: `UNIQUE (${column})`,
+    comment: null,
+  };
+}
+
+function table(
+  name: string,
+  constraints: ConstructorParameters<typeof Table>[0]["constraints"] = [],
+) {
+  return new Table({
+    ...baseTableProps,
+    name,
+    columns: [
+      { ...integerColumn("id", 1), not_null: true },
+      integerColumn("post_id", 2),
+      integerColumn("lab_id", 3),
+    ],
+    constraints,
+  });
+}
+
+function view(name: string, columns = [integerColumn("id", 1)]) {
+  return new View({
+    schema: "public",
+    name,
+    definition: "SELECT id FROM users",
+    row_security: false,
+    force_row_security: false,
+    has_indexes: false,
+    has_rules: true,
+    has_triggers: false,
+    has_subclasses: false,
+    is_populated: true,
+    replica_identity: "d",
+    is_partition: false,
+    options: null,
+    partition_bound: null,
+    owner: "postgres",
+    comment: null,
+    columns,
+    privileges: [],
+  });
+}
+
+async function catalogWithDepends(depends: PgDepend[]) {
+  const base = await createEmptyCatalog(170000, "postgres");
+  // oxlint-disable-next-line typescript/no-misused-spread
+  return new Catalog({ ...base, depends });
+}
+
+function changeLabel(change: Change) {
+  if (change instanceof AlterTableDropConstraint) {
+    return `${change.constructor.name}:${change.table.name}.${change.constraint.name}`;
+  }
+  if (change instanceof DropTable) {
+    return `${change.constructor.name}:${change.table.name}`;
+  }
+  return change.constructor.name;
+}
+
+describe("sortChanges", () => {
+  test("orders dependent view drop before drop-phase column type rewrite", async () => {
+    const branchTable = table("users");
+    const mainColumn = {
+      ...integerColumn("age", 4),
+      data_type: "numeric",
+      data_type_str: "numeric",
+    };
+    const branchColumn = integerColumn("age", 4);
+    const dependentView = view("user_ages", [
+      integerColumn("id", 1),
+      mainColumn,
+    ]);
+    const recreatedView = view("user_ages", [
+      integerColumn("id", 1),
+      branchColumn,
+    ]);
+    const changes: Change[] = [
+      new AlterTableAlterColumnType({
+        table: branchTable,
+        column: branchColumn,
+        previousColumn: mainColumn,
+      }),
+      new DropView({ view: dependentView }),
+      new CreateView({ view: recreatedView }),
+    ];
+    const mainCatalog = await catalogWithDepends([
+      {
+        dependent_stable_id: dependentView.stableId,
+        referenced_stable_id: "column:public.users.age",
+        deptype: "n",
+      },
+    ]);
+    const branchCatalog = await catalogWithDepends([]);
+
+    const sorted = sortChanges({ mainCatalog, branchCatalog }, changes);
+
+    expect(sorted.map(changeLabel)).toEqual([
+      "DropView",
+      "AlterTableAlterColumnType",
+      "CreateView",
+    ]);
+  });
+
+  test("breaks publication FK-chain constraint-drop cycle with one dropped table", async () => {
+    const labs = table("labs", [uniqueConstraint("unique_lab_id", "id")]);
+    const posts = table("posts", [
+      fkConstraint({
+        name: "posts_lab_id_fkey",
+        fkColumn: "lab_id",
+        targetTable: "labs",
+      }),
+    ]);
+    const publication = new Publication({
+      name: "supabase_realtime",
+      owner: "postgres",
+      comment: null,
+      all_tables: false,
+      publish_insert: true,
+      publish_update: true,
+      publish_delete: true,
+      publish_truncate: true,
+      publish_via_partition_root: false,
+      tables: [
+        {
+          schema: "public",
+          name: "labs",
+          columns: null,
+          row_filter: null,
+        },
+        {
+          schema: "public",
+          name: "posts",
+          columns: null,
+          row_filter: null,
+        },
+      ],
+      schemas: [],
+    });
+    const changes: Change[] = [
+      new AlterPublicationDropTables({
+        publication,
+        tables: publication.tables,
+      }),
+      new DropTable({ table: posts }),
+      new AlterTableDropConstraint({
+        table: labs,
+        constraint: labs.constraints[0],
+      }),
+    ];
+    const mainCatalog = await catalogWithDepends([
+      {
+        dependent_stable_id: "publication:supabase_realtime",
+        referenced_stable_id: "table:public.posts",
+        deptype: "n",
+      },
+      {
+        dependent_stable_id: "constraint:public.posts.posts_lab_id_fkey",
+        referenced_stable_id: "constraint:public.labs.unique_lab_id",
+        deptype: "n",
+      },
+    ]);
+    const branchCatalog = await catalogWithDepends([]);
+
+    const sorted = sortChanges({ mainCatalog, branchCatalog }, changes);
+
+    expect(sorted.map(changeLabel)).toContain(
+      "AlterTableDropConstraint:posts.posts_lab_id_fkey",
+    );
+  });
+
+  test("breaks publication FK-chain constraint-drop cycle in the drop phase", async () => {
+    const labs = table("labs", [uniqueConstraint("unique_lab_id", "id")]);
+    const posts = table("posts", [
+      fkConstraint({
+        name: "posts_lab_id_fkey",
+        fkColumn: "lab_id",
+        targetTable: "labs",
+      }),
+    ]);
+    const postAttachments = table("post_attachments", [
+      fkConstraint({
+        name: "post_attachments_post_id_fkey",
+        fkColumn: "post_id",
+        targetTable: "posts",
+      }),
+    ]);
+    const publication = new Publication({
+      name: "supabase_realtime",
+      owner: "postgres",
+      comment: null,
+      all_tables: false,
+      publish_insert: true,
+      publish_update: true,
+      publish_delete: true,
+      publish_truncate: true,
+      publish_via_partition_root: false,
+      tables: [
+        {
+          schema: "public",
+          name: "labs",
+          columns: null,
+          row_filter: null,
+        },
+        {
+          schema: "public",
+          name: "post_attachments",
+          columns: null,
+          row_filter: null,
+        },
+        {
+          schema: "public",
+          name: "posts",
+          columns: null,
+          row_filter: null,
+        },
+      ],
+      schemas: [],
+    });
+    const changes: Change[] = [
+      new AlterPublicationDropTables({
+        publication,
+        tables: publication.tables,
+      }),
+      new DropTable({ table: postAttachments }),
+      new DropTable({ table: posts }),
+      new AlterTableDropConstraint({
+        table: labs,
+        constraint: labs.constraints[0],
+      }),
+    ];
+    const mainCatalog = await catalogWithDepends([
+      {
+        dependent_stable_id: "publication:supabase_realtime",
+        referenced_stable_id: "table:public.post_attachments",
+        deptype: "n",
+      },
+      {
+        dependent_stable_id:
+          "constraint:public.post_attachments.post_attachments_post_id_fkey",
+        referenced_stable_id: "column:public.posts.id",
+        deptype: "n",
+      },
+      {
+        dependent_stable_id: "constraint:public.posts.posts_lab_id_fkey",
+        referenced_stable_id: "constraint:public.labs.unique_lab_id",
+        deptype: "n",
+      },
+    ]);
+    const branchCatalog = await catalogWithDepends([]);
+
+    const sorted = sortChanges({ mainCatalog, branchCatalog }, changes);
+
+    expect(sorted.map(changeLabel)).toContain(
+      "AlterTableDropConstraint:post_attachments.post_attachments_post_id_fkey",
+    );
+    expect(sorted.map(changeLabel)).toContain(
+      "AlterTableDropConstraint:posts.posts_lab_id_fkey",
+    );
+  });
+});

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

@@ -0,0 +1,324 @@
+/**
+ * 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 type { Catalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import { generateCustomConstraints } from "./custom-constraints.ts";
+import { tryBreakCycleByChangeInjection } from "./cycle-breakers.ts";
+import { printDebugGraph } from "./debug-visualization.ts";
+
+const debugGraph = debug("pg-delta:graph");
+
+import {
+  filterEdgesForCycleBreaking,
+  getEdgesInCycle,
+} from "./dependency-filter.ts";
+import {
+  buildGraphData,
+  convertCatalogDependenciesToConstraints,
+  convertConstraintsToEdges,
+  convertExplicitRequirementsToConstraints,
+  edgesToPairs,
+} from "./graph-builder.ts";
+import { dedupeEdges } from "./graph-utils.ts";
+import { logicalSort } from "./logical-sort.ts";
+import {
+  findCycle,
+  formatCycleError,
+  performStableTopologicalSort,
+} from "./topological-sort.ts";
+import type { PgDependRow, PhaseSortOptions } from "./types.ts";
+import { UnorderableCycleError } from "./unorderable-cycle-error.ts";
+import { getExecutionPhase, type Phase } from "./utils.ts";
+
+// `sortPhaseChanges` caps the change-injection breaker at one round per
+// node in the initial phase: there can never be more disjoint unbreakable
+// cycles than there are change nodes (each cycle has ≥ 2 distinct nodes).
+// The cap exists only to surface a buggy breaker as `CycleError` instead
+// of an infinite loop — the actual loop-protection guarantee comes from
+// `breakerRoundSignatures`, which throws the moment the same cycle
+// reappears after a break.
+
+/**
+ * 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: { mainCatalog: Catalog; branchCatalog: Catalog },
+  changes: Change[],
+): Change[] {
+  // 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: {
+    mainCatalog: { depends: PgDependRow[] };
+    branchCatalog: { depends: PgDependRow[] };
+  },
+  changeList: Change[],
+): Change[] {
+  const changesByPhase: Record<Phase, Change[]> = {
+    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];
+}
+
+/**
+ * Normalize a cycle by rotating it to start with the smallest node index, so
+ * cycles that loop through the same nodes in the same direction compare equal
+ * regardless of where DFS happened to enter them.
+ */
+function normalizeCycle(cycleNodeIndexes: number[]): string {
+  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(",");
+}
+
+type SortRoundResult =
+  | { kind: "sorted"; sorted: Change[] }
+  | {
+      kind: "unbreakable";
+      cycleNodeIndexes: number[];
+      cycleEdges: ReturnType<typeof getEdgesInCycle>;
+    };
+
+/**
+ * One attempt at sorting `phaseChanges`. Builds the graph from scratch,
+ * runs the iterative edge-removal cycle handler, and either returns a
+ * topologically sorted list or reports an unbreakable cycle so the caller
+ * can decide whether to dispatch a change-injection breaker.
+ *
+ * Algorithm:
+ * 1. Build graph data (change sets and reverse indexes).
+ * 2. Convert all sources to Constraints (catalog, explicit, custom).
+ * 3. Convert Constraints to edges.
+ * 4. Iteratively detect and break cycles by removing weak edges.
+ * 5. Perform stable topological sort on the acyclic graph.
+ *
+ * In DROP phase, edges are inverted so drops run in reverse dependency
+ * order.
+ */
+function attemptSortRound(
+  phaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions,
+): SortRoundResult {
+  // 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 by edge filtering.
+  // We loop until no cycles remain OR we see the same cycle twice — the
+  // latter signals that edge filtering exhausted itself. At that point
+  // the caller may dispatch a change-injection breaker; if no breaker
+  // matches, the original throw path runs.
+  const seenCycles = new Set<string>();
+
+  while (true) {
+    const edgePairs = edgesToPairs(edges);
+    const cycleNodeIndexes = findCycle(phaseChanges.length, edgePairs);
+
+    if (!cycleNodeIndexes) break;
+
+    const cycleSignature = normalizeCycle(cycleNodeIndexes);
+    if (seenCycles.has(cycleSignature)) {
+      // Edge filtering can't break this cycle. Report it back to the
+      // caller so it can try change-injection before throwing.
+      return {
+        kind: "unbreakable",
+        cycleNodeIndexes,
+        cycleEdges: getEdgesInCycle(cycleNodeIndexes, edges),
+      };
+    }
+    seenCycles.add(cycleSignature);
+
+    edges = filterEdgesForCycleBreaking(
+      edges,
+      cycleNodeIndexes,
+      phaseChanges,
+      graphData,
+    );
+  }
+
+  const finalEdgePairs = edgesToPairs(edges);
+
+  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 UnorderableCycleError(
+      "CycleError: dependency graph contains a cycle",
+    );
+  }
+
+  return {
+    kind: "sorted",
+    sorted: topologicalOrder.map((changeIndex) => phaseChanges[changeIndex]),
+  };
+}
+
+/**
+ * Sort changes within a phase. Tries `attemptSortRound`; on an unbreakable
+ * cycle, dispatches to `tryBreakCycleByChangeInjection`, retries with the
+ * rewritten changes, and bails after `MAX_CYCLE_BREAKER_ROUNDS` to surface
+ * a buggy breaker as `CycleError` instead of an infinite loop.
+ *
+ * Best case (no cycles, the vast majority of plans): one round, no
+ * change-injection breaker code runs at all.
+ */
+function sortPhaseChanges(
+  initialPhaseChanges: Change[],
+  dependencyRows: PgDependRow[],
+  options: PhaseSortOptions = {},
+): Change[] {
+  if (initialPhaseChanges.length <= 1) return initialPhaseChanges;
+
+  let phaseChanges = initialPhaseChanges;
+  const breakerRoundSignatures = new Set<string>();
+
+  // `attemptSortRound` returns at most one unbreakable cycle per call,
+  // so a phase with K independent unbreakable cycles needs K+1 rounds.
+  // Every cycle contains ≥ 2 distinct change nodes, so the maximum
+  // possible value of K is `floor(initialPhaseChanges.length / 2)` —
+  // using `initialPhaseChanges.length` itself is therefore a real upper
+  // bound with one round of slack (and matches the early-return guard
+  // above, which already excluded length-0 and length-1 phases).
+  const maxRounds = initialPhaseChanges.length;
+
+  for (let round = 0; round <= maxRounds; round++) {
+    const result = attemptSortRound(phaseChanges, dependencyRows, options);
+    if (result.kind === "sorted") return result.sorted;
+
+    // Edge filtering hit an unbreakable cycle. Try the change-injection
+    // breakers (FK pattern, publication↔column pattern). If none matches,
+    // throw with the same diagnostic the original code emitted.
+    const broken = tryBreakCycleByChangeInjection(
+      result.cycleNodeIndexes,
+      phaseChanges,
+    );
+    if (broken === null) {
+      throw new UnorderableCycleError(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+        result.cycleNodeIndexes.map((index) => phaseChanges[index]),
+      );
+    }
+
+    // Loop guard: if the same cycle node-set re-appears after a break,
+    // the breaker isn't making progress. Throw with full context.
+    const signature = normalizeCycle(result.cycleNodeIndexes);
+    if (breakerRoundSignatures.has(signature)) {
+      throw new UnorderableCycleError(
+        formatCycleError(
+          result.cycleNodeIndexes,
+          phaseChanges,
+          result.cycleEdges,
+        ),
+        result.cycleNodeIndexes.map((index) => phaseChanges[index]),
+      );
+    }
+    breakerRoundSignatures.add(signature);
+
+    phaseChanges = broken;
+  }
+
+  throw new UnorderableCycleError(
+    `CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`,
+  );
+}