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

package/src/core/plan/render.ts

@@ -0,0 +1,153 @@
+/**
+ * Plan rendering - turn migration units into executable SQL scripts.
+ */
+
+import { normalizePlan } from "./normalize.ts";
+import type { SqlFormatOptions } from "./sql-format.ts";
+import { formatSqlStatements } from "./sql-format.ts";
+import type {
+  ExecutionBoundaryReason,
+  MigrationUnit,
+  Plan,
+  SerializedPlan,
+} from "./types.ts";
+
+const STATEMENT_DELIMITER = ";\n\n";
+
+export interface RenderPlanSqlOptions {
+  sqlFormatOptions?: SqlFormatOptions;
+  includeTransactions?: boolean;
+}
+
+export interface RenderedPlanFile {
+  path: string;
+  sql: string;
+  unit: MigrationUnit;
+}
+
+/**
+ * Render the whole plan as a single SQL script. Each migration unit is
+ * delimited with header comments and, for transactional units, wrapped in
+ * explicit BEGIN/COMMIT.
+ */
+export function renderPlanSql(
+  plan: SerializedPlan,
+  options: RenderPlanSqlOptions = {},
+): string {
+  const normalized = normalizePlan(plan);
+  return normalized.units
+    .map((unit, index) => renderUnitSql(normalized, unit, index, options))
+    .join("\n\n");
+}
+
+/**
+ * Render the plan as one numbered SQL file per migration unit. Session
+ * statements are repeated in every file because each file may be executed
+ * in its own session.
+ */
+export function renderPlanFiles(
+  plan: SerializedPlan,
+  options: RenderPlanSqlOptions = {},
+): RenderedPlanFile[] {
+  const normalized = normalizePlan(plan);
+  return normalized.units.map((unit, index) => ({
+    path: `${String(index + 1).padStart(3, "0")}_${unitName(unit.reason)}.sql`,
+    sql: renderUnitSql(normalized, unit, index, options),
+    unit,
+  }));
+}
+
+/**
+ * Flatten a plan back into the ordered statement list, session statements
+ * included. Execution context (transaction boundaries) is lost — use
+ * `renderPlanSql`/`renderPlanFiles` or `plan.units` when it matters.
+ */
+export function flattenPlanStatements(plan: SerializedPlan): string[] {
+  const normalized = normalizePlan(plan);
+  return [
+    ...normalized.sessionStatements,
+    ...normalized.units.flatMap((unit) => unit.statements),
+  ];
+}
+
+/** Display name for a migration unit, derived from its boundary reason. */
+function unitName(reason: ExecutionBoundaryReason): string {
+  switch (reason) {
+    case "default":
+      return "schema_changes";
+    case "enum_value_visibility":
+      return "after_enum_values";
+    case "non_transactional":
+      return "non_transactional";
+  }
+}
+
+function renderUnitSql(
+  plan: Plan,
+  unit: MigrationUnit,
+  index: number,
+  options: RenderPlanSqlOptions,
+): string {
+  const includeTransactions = options.includeTransactions !== false;
+  const body =
+    options.sqlFormatOptions != null
+      ? formatSqlStatements(unit.statements, options.sqlFormatOptions)
+      : unit.statements;
+
+  const lines: string[] = [
+    `-- Migration unit ${index + 1}: ${unitName(unit.reason)}`,
+    `-- Transaction mode: ${unit.transactionMode}`,
+    `-- Boundary reason: ${unit.reason}`,
+  ];
+
+  if (unit.transactionMode === "none") {
+    // PostgreSQL runs every statement of a multi-command simple-query string
+    // in an implicit transaction block, so this unit can never execute as
+    // part of a single query string — no SET/COMMIT shuffling changes that.
+    lines.push(
+      "-- Run statement-by-statement (psql does this; do not use psql -1 or",
+      "-- send this script as a single multi-statement query string).",
+    );
+  }
+
+  lines.push("");
+
+  if (plan.sessionStatements.length > 0) {
+    lines.push(renderStatements(plan.sessionStatements));
+    lines.push("");
+  }
+
+  if (includeTransactions && unit.transactionMode === "transactional") {
+    lines.push("BEGIN;");
+    lines.push("");
+  }
+
+  lines.push(renderStatements(body));
+
+  if (includeTransactions && unit.transactionMode === "transactional") {
+    lines.push("");
+    lines.push("COMMIT;");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+function renderStatements(statements: string[]): string {
+  if (statements.length === 0) return "";
+  return `${statements.map(trimTerminator).join(STATEMENT_DELIMITER)};`;
+}
+
+/**
+ * Strip trailing semicolons so every rendered statement ends with exactly
+ * one. pg-delta's own serializers emit no terminator, but plan JSON is a
+ * persisted artifact — legacy v1 files, hand-built units, or user-edited
+ * plans may already carry one, and joining those blindly would render ";;".
+ */
+function trimTerminator(statement: string): string {
+  const trimmed = statement.trim();
+  let end = trimmed.length;
+  while (end > 0 && trimmed.charCodeAt(end - 1) === 59) {
+    end--;
+  }
+  return trimmed.slice(0, end);
+}

package/src/core/plan/sql-format/format-off.test.ts

@@ -659,7 +659,7 @@ describe("sql formatting snapshots", () => {
       ALTER DEFAULT PRIVILEGES FOR ROLE app_user IN SCHEMA public REVOKE SELECT ON TABLES FROM app_reader;
 
       -- subscription.create
-      CREATE SUBSCRIPTION sub_replica CONNECTION 'host=primary.db port=5432 dbname=mydb' PUBLICATION pub_custom WITH (slot_name = 'sub_replica_slot', binary = true, streaming = 'parallel', synchronous_commit = 'remote_apply', disable_on_error = true, failover = true);
+      CREATE SUBSCRIPTION sub_replica CONNECTION 'host=primary.db port=5432 dbname=mydb' PUBLICATION pub_custom WITH (slot_name = 'sub_replica_slot', binary = true, streaming = 'parallel', synchronous_commit = 'remote_apply', disable_on_error = true, failover = true, create_slot = false);
 
       -- subscription.drop
       DROP SUBSCRIPTION sub_replica;

package/src/core/plan/sql-format/format-pretty-lower-leading.test.ts

@@ -869,6 +869,7 @@ describe("sql formatting snapshots", () => {
               , synchronous_commit = 'remote_apply'
               , disable_on_error   = true
               , failover           = true
+              , create_slot        = false
           );
 
       -- subscription.drop

package/src/core/plan/sql-format/format-pretty-narrow.test.ts

@@ -1047,7 +1047,8 @@ describe("sql formatting snapshots", () => {
           streaming          = 'parallel',
           synchronous_commit = 'remote_apply',
           disable_on_error   = true,
-          failover           = true
+          failover           = true,
+          create_slot        = false
         );
 
       -- subscription.drop

package/src/core/plan/sql-format/format-pretty-preserve.test.ts

@@ -864,7 +864,8 @@ describe("sql formatting snapshots", () => {
             streaming = 'parallel',
             synchronous_commit = 'remote_apply',
             disable_on_error = true,
-            failover = true
+            failover = true,
+            create_slot = false
          );
 
       -- subscription.drop

package/src/core/plan/sql-format/format-pretty-upper.test.ts

@@ -855,7 +855,8 @@ describe("sql formatting snapshots", () => {
           streaming          = 'parallel',
           synchronous_commit = 'remote_apply',
           disable_on_error   = true,
-          failover           = true
+          failover           = true,
+          create_slot        = false
         );
 
       -- subscription.drop

package/src/core/plan/types.ts

@@ -5,6 +5,7 @@
 import z from "zod";
 import type { Change } from "../change.types.ts";
 import type { Integration } from "../integrations/integration.types.ts";
+import type { CommitBoundaryReason } from "../objects/base.change.ts";
 
 // ============================================================================
 // Core Types
@@ -14,6 +15,34 @@ export type PlanRisk =
   | { level: "safe" }
   | { level: "data_loss"; statements: string[] };
 
+export type TransactionMode = "transactional" | "none";
+
+/**
+ * Why a migration unit starts a new execution boundary.
+ *
+ * - `"default"` — the first (or only) unit of the plan.
+ * - `"non_transactional"` — the unit's statement cannot run inside a
+ *   transaction block (see `BaseChange.nonTransactional`).
+ * - commit-visibility kinds (see `BaseChange.commitBoundary`) — the previous
+ *   unit produced effects that are only usable after COMMIT.
+ */
+export type ExecutionBoundaryReason =
+  | "default"
+  | "non_transactional"
+  | CommitBoundaryReason;
+
+/**
+ * An ordered group of SQL statements that share one execution context.
+ *
+ * Transactional units are applied inside an explicit BEGIN/COMMIT;
+ * non-transactional units run their single statement without a wrapper.
+ */
+export interface MigrationUnit {
+  transactionMode: TransactionMode;
+  reason: ExecutionBoundaryReason;
+  statements: string[];
+}
+
 /**
  * All supported object types in the system.
  * Derived from the Change union type's objectType discriminant.
@@ -127,7 +156,26 @@ export const PlanSchema = z.object({
   target: z.object({
     fingerprint: z.string(),
   }),
-  statements: z.array(z.string()),
+  units: z
+    .array(
+      z.object({
+        transactionMode: z.enum(["transactional", "none"]),
+        reason: z.enum([
+          "default",
+          "non_transactional",
+          "enum_value_visibility",
+        ]),
+        statements: z.array(z.string()),
+      }),
+    )
+    .optional(),
+  /** Session-level statements (SET ROLE, ...) applied once before the units. */
+  sessionStatements: z.array(z.string()).optional(),
+  /**
+   * Legacy v1 plans only: the flat statement list. Converted to units by
+   * `normalizePlan`; never emitted by `createPlan`/`serializePlan`.
+   */
+  statements: z.array(z.string()).optional(),
   role: z.string().optional(),
   filter: z.any().optional(), // FilterDSL - complex recursive type, validated at compile time
   serialize: z.any().optional(), // SerializeDSL - complex recursive type, validated at compile time
@@ -144,10 +192,22 @@ export const PlanSchema = z.object({
     .optional(),
 });
 
+export type SerializedPlan = z.infer<typeof PlanSchema>;
+
 /**
- * A migration plan containing all changes to transform one database schema into another.
+ * A migration plan containing all changes to transform one database schema
+ * into another, as an ordered list of execution-aware migration units.
+ *
+ * `units` and `sessionStatements` are the single source of truth: render via
+ * `renderPlanSql`/`renderPlanFiles`, or flatten via `flattenPlanStatements`.
  */
-export type Plan = z.infer<typeof PlanSchema>;
+export type Plan = Omit<
+  SerializedPlan,
+  "units" | "statements" | "sessionStatements"
+> & {
+  units: MigrationUnit[];
+  sessionStatements: string[];
+};
 
 /**
  * Options for creating a plan.

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

@@ -39,6 +39,7 @@ import {
   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
@@ -238,7 +239,9 @@ function attemptSortRound(
 
   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");
+    throw new UnorderableCycleError(
+      "CycleError: dependency graph contains a cycle",
+    );
   }
 
   return {
@@ -287,12 +290,13 @@ function sortPhaseChanges(
       phaseChanges,
     );
     if (broken === null) {
-      throw new Error(
+      throw new UnorderableCycleError(
         formatCycleError(
           result.cycleNodeIndexes,
           phaseChanges,
           result.cycleEdges,
         ),
+        result.cycleNodeIndexes.map((index) => phaseChanges[index]),
       );
     }
 
@@ -300,12 +304,13 @@ function sortPhaseChanges(
     // the breaker isn't making progress. Throw with full context.
     const signature = normalizeCycle(result.cycleNodeIndexes);
     if (breakerRoundSignatures.has(signature)) {
-      throw new Error(
+      throw new UnorderableCycleError(
         formatCycleError(
           result.cycleNodeIndexes,
           phaseChanges,
           result.cycleEdges,
         ),
+        result.cycleNodeIndexes.map((index) => phaseChanges[index]),
       );
     }
     breakerRoundSignatures.add(signature);
@@ -313,7 +318,7 @@ function sortPhaseChanges(
     phaseChanges = broken;
   }
 
-  throw new Error(
+  throw new UnorderableCycleError(
     `CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`,
   );
 }

package/src/core/sort/unorderable-cycle-error.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { createEmptyCatalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import { BaseChange } from "../objects/base.change.ts";
+import { sortChanges } from "./sort-changes.ts";
+import { UnorderableCycleError } from "./unorderable-cycle-error.ts";
+
+class MutualCreateChange extends BaseChange {
+  readonly operation = "create";
+  readonly objectType = "table";
+  readonly scope = "object";
+  readonly table: { schema: string; name: string };
+  private readonly dependsOn: string;
+
+  constructor(name: string, dependsOn: string) {
+    super();
+    this.table = { schema: "public", name };
+    this.dependsOn = dependsOn;
+  }
+
+  override get creates() {
+    return [`table:public.${this.table.name}`];
+  }
+
+  override get requires() {
+    return [`table:public.${this.dependsOn}`];
+  }
+
+  serialize(): string {
+    return `CREATE TABLE public.${this.table.name} ()`;
+  }
+}
+
+describe("UnorderableCycleError", () => {
+  test("sortChanges throws a typed error carrying the offending cycle", async () => {
+    const a = new MutualCreateChange("a", "b");
+    const b = new MutualCreateChange("b", "a");
+    const catalog = await createEmptyCatalog(170000, "postgres");
+
+    let thrown: unknown;
+    try {
+      sortChanges({ mainCatalog: catalog, branchCatalog: catalog }, [
+        a,
+        b,
+      ] as unknown as Change[]);
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(UnorderableCycleError);
+    if (!(thrown instanceof UnorderableCycleError)) {
+      throw new Error("expected UnorderableCycleError");
+    }
+    expect(thrown.name).toBe("UnorderableCycleError");
+    expect(thrown.message).toContain("CycleError");
+    expect(new Set(thrown.cycle)).toEqual(
+      new Set<Change>([a, b] as unknown as Change[]),
+    );
+  });
+});

package/src/core/sort/unorderable-cycle-error.ts

@@ -0,0 +1,23 @@
+import type { Change } from "../change.types.ts";
+
+/**
+ * Thrown by `sortChanges` when the dependency graph contains a cycle that
+ * neither weak-edge filtering nor the change-injection cycle breakers could
+ * resolve.
+ *
+ * `message` is the human-readable `formatCycleError` output (it starts with
+ * "CycleError:" for backward compatibility with log greps).
+ */
+export class UnorderableCycleError extends Error {
+  override readonly name = "UnorderableCycleError";
+  /**
+   * Changes participating in the cycle, in cycle order. Empty when the
+   * failure came from an internal guard rather than a concrete cycle.
+   */
+  readonly cycle: readonly Change[];
+
+  constructor(message: string, cycle: readonly Change[] = []) {
+    super(message);
+    this.cycle = cycle;
+  }
+}

package/src/index.ts

@@ -30,12 +30,29 @@ export type {
 export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
 
 // Plan operations
+export type { Change } from "./core/change.types.ts";
 export { applyPlan } from "./core/plan/apply.ts";
 export type { CatalogInput } from "./core/plan/create.ts";
 export { createPlan } from "./core/plan/create.ts";
+export type {
+  RenderedPlanFile,
+  RenderPlanSqlOptions,
+} from "./core/plan/render.ts";
+export {
+  flattenPlanStatements,
+  renderPlanFiles,
+  renderPlanSql,
+} from "./core/plan/render.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";
+export type {
+  CreatePlanOptions,
+  ExecutionBoundaryReason,
+  MigrationUnit,
+  Plan,
+  TransactionMode,
+} from "./core/plan/types.ts";
+export { UnorderableCycleError } from "./core/sort/unorderable-cycle-error.ts";
 
 // Postgres config
 export { createManagedPool } from "./core/postgres-config.ts";