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

package/src/core/plan/execution.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../change.types.ts";
+import { BaseChange } from "../objects/base.change.ts";
+import type { ColumnProps } from "../objects/base.model.ts";
+import { AlterTableAlterColumnSetDefault } from "../objects/table/changes/table.alter.ts";
+import type { Table } from "../objects/table/table.model.ts";
+import { AlterEnumAddValue } from "../objects/type/enum/changes/enum.alter.ts";
+import { Enum } from "../objects/type/enum/enum.model.ts";
+import { buildExecutionPlan } from "./execution.ts";
+
+describe("buildExecutionPlan", () => {
+  test("splits after enum values before subsequent statements", () => {
+    const userRole = createEnum(["admin", "user", "store"]);
+    const column = createEnumColumn("'store'::public.user_role");
+
+    const execution = buildExecutionPlan([
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "store",
+        position: { after: "user" },
+      }),
+      new AlterTableAlterColumnSetDefault({
+        table: createTable(column),
+        column,
+      }),
+    ]);
+
+    expect(execution.units).toHaveLength(2);
+    expect(execution.units[0].statements).toHaveLength(1);
+    expect(execution.units[1].reason).toBe("enum_value_visibility");
+    expect(execution.units[1].transactionMode).toBe("transactional");
+  });
+
+  test("keeps newly added enum values in one unit when nothing uses them", () => {
+    const userRole = createEnum(["admin", "user", "store"]);
+
+    const execution = buildExecutionPlan([
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "store",
+        position: { after: "user" },
+      }),
+    ]);
+
+    expect(execution.units).toHaveLength(1);
+    expect(execution.units[0].reason).toBe("default");
+  });
+
+  test("groups multiple enum additions before a dependent consumer", () => {
+    const userRole = createEnum(["admin", "user", "store", "auditor"]);
+    const column = createEnumColumn("'auditor'::public.user_role");
+
+    const execution = buildExecutionPlan([
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "store",
+        position: { after: "user" },
+      }),
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "auditor",
+        position: { after: "store" },
+      }),
+      new AlterTableAlterColumnSetDefault({
+        table: createTable(column),
+        column,
+      }),
+    ]);
+
+    expect(execution.units).toHaveLength(2);
+    expect(execution.units[0].statements).toMatchInlineSnapshot(`
+      [
+        "ALTER TYPE public.user_role ADD VALUE 'store' AFTER 'user'",
+        "ALTER TYPE public.user_role ADD VALUE 'auditor' AFTER 'store'",
+      ]
+    `);
+  });
+
+  test("splits after enum values before opaque later statements", () => {
+    const userRole = createEnum(["admin", "user", "store"]);
+
+    const execution = buildExecutionPlan([
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "store",
+        position: { after: "user" },
+      }),
+      new OpaqueEnumConsumerChange() as unknown as Change,
+    ]);
+
+    expect(execution.units).toHaveLength(2);
+    expect(execution.units[1].reason).toBe("enum_value_visibility");
+    expect(execution.units[1].statements[0]).toBe(
+      "CREATE VIEW public.store_profiles AS SELECT 'store'::public.user_role AS role",
+    );
+  });
+
+  test("puts non-transactional statements in their own unit", () => {
+    const userRole = createEnum(["admin", "user", "store"]);
+
+    const execution = buildExecutionPlan([
+      new AlterEnumAddValue({
+        enum: userRole,
+        newValue: "store",
+        position: { after: "user" },
+      }),
+      new NonTransactionalChange() as unknown as Change,
+      new OpaqueEnumConsumerChange() as unknown as Change,
+    ]);
+
+    expect(execution.units).toMatchInlineSnapshot(`
+      [
+        {
+          "reason": "default",
+          "statements": [
+            "ALTER TYPE public.user_role ADD VALUE 'store' AFTER 'user'",
+          ],
+          "transactionMode": "transactional",
+        },
+        {
+          "reason": "non_transactional",
+          "statements": [
+            "CREATE INDEX CONCURRENTLY users_email_idx ON public.users (email)",
+          ],
+          "transactionMode": "none",
+        },
+        {
+          "reason": "default",
+          "statements": [
+            "CREATE VIEW public.store_profiles AS SELECT 'store'::public.user_role AS role",
+          ],
+          "transactionMode": "transactional",
+        },
+      ]
+    `);
+  });
+
+  test("routes SET ROLE and check_function_bodies into session statements, not units", () => {
+    const execution = buildExecutionPlan(
+      [new ProcedureChange() as unknown as Change],
+      { role: "app_owner" },
+    );
+
+    expect(execution.sessionStatements).toEqual([
+      'SET ROLE "app_owner"',
+      "SET check_function_bodies = false",
+    ]);
+    expect(execution.units).toHaveLength(1);
+    expect(execution.units[0].statements).toEqual([
+      "CREATE PROCEDURE public.noop() LANGUAGE sql AS $$ SELECT 1 $$",
+    ]);
+  });
+});
+
+class NonTransactionalChange extends BaseChange {
+  readonly operation = "create";
+  readonly objectType = "index";
+  readonly scope = "object";
+
+  override get nonTransactional() {
+    return true;
+  }
+
+  serialize(): string {
+    return "CREATE INDEX CONCURRENTLY users_email_idx ON public.users (email)";
+  }
+}
+
+class OpaqueEnumConsumerChange extends BaseChange {
+  readonly operation = "create";
+  readonly objectType = "view";
+  readonly scope = "object";
+
+  serialize(): string {
+    return "CREATE VIEW public.store_profiles AS SELECT 'store'::public.user_role AS role";
+  }
+}
+
+class ProcedureChange extends BaseChange {
+  readonly operation = "create";
+  readonly objectType = "procedure";
+  readonly scope = "object";
+
+  serialize(): string {
+    return "CREATE PROCEDURE public.noop() LANGUAGE sql AS $$ SELECT 1 $$";
+  }
+}
+
+function createEnum(labels: string[]): Enum {
+  return new Enum({
+    schema: "public",
+    name: "user_role",
+    owner: "postgres",
+    labels: labels.map((label, index) => ({
+      label,
+      sort_order: index + 1,
+    })),
+    comment: null,
+    privileges: [],
+  });
+}
+
+function createEnumColumn(defaultValue: string): ColumnProps {
+  return {
+    name: "role",
+    position: 1,
+    data_type: "USER-DEFINED",
+    data_type_str: "public.user_role",
+    is_custom_type: true,
+    custom_type_type: "e",
+    custom_type_category: "E",
+    custom_type_schema: "public",
+    custom_type_name: "user_role",
+    not_null: false,
+    is_identity: false,
+    is_identity_always: false,
+    is_generated: false,
+    collation: null,
+    default: defaultValue,
+    comment: null,
+  };
+}
+
+function createTable(column: ColumnProps): Table {
+  return {
+    schema: "public",
+    name: "profiles",
+    stableId: "table:public.profiles",
+    columns: [column],
+  } as unknown as Table;
+}

package/src/core/plan/execution.ts

@@ -0,0 +1,115 @@
+/**
+ * Execution planning - group sorted changes into transaction-aware
+ * migration units.
+ *
+ * Execution semantics come from the `nonTransactional` and `commitBoundary`
+ * traits declared on the change classes (see `base.change.ts`), never from
+ * inspecting rendered SQL.
+ */
+
+import { escapeIdentifier } from "pg";
+import type { Change } from "../change.types.ts";
+import type { ResolvedIntegration } from "../integrations/integration.types.ts";
+import type { CommitBoundaryReason } from "../objects/base.change.ts";
+import type { ExecutionBoundaryReason, MigrationUnit } from "./types.ts";
+
+interface BuildExecutionPlanOptions {
+  integration?: ResolvedIntegration;
+  role?: string;
+}
+
+interface ExecutionPlan {
+  units: MigrationUnit[];
+  sessionStatements: string[];
+}
+
+export function buildExecutionPlan(
+  changes: Change[],
+  options: BuildExecutionPlanOptions = {},
+): ExecutionPlan {
+  return {
+    units: buildMigrationUnits(changes, options.integration),
+    sessionStatements: buildSessionStatements(changes, options),
+  };
+}
+
+function buildSessionStatements(
+  changes: Change[],
+  options: BuildExecutionPlanOptions,
+): string[] {
+  const statements: string[] = [];
+
+  if (options.role) {
+    statements.push(`SET ROLE ${escapeIdentifier(options.role)}`);
+  }
+
+  if (hasRoutineChanges(changes)) {
+    statements.push("SET check_function_bodies = false");
+  }
+
+  return statements;
+}
+
+/**
+ * Check if any changes involve routines (procedures or aggregates).
+ * Used to determine if we need to disable function body checking.
+ */
+function hasRoutineChanges(changes: Change[]): boolean {
+  return changes.some(
+    (change) =>
+      change.objectType === "procedure" || change.objectType === "aggregate",
+  );
+}
+
+function buildMigrationUnits(
+  changes: Change[],
+  integration?: ResolvedIntegration,
+): MigrationUnit[] {
+  const units: MigrationUnit[] = [];
+  let current: string[] = [];
+  let reason: ExecutionBoundaryReason = "default";
+  let pendingBoundary: CommitBoundaryReason | null = null;
+
+  function flush(): void {
+    if (current.length === 0) return;
+    units.push({
+      transactionMode: "transactional",
+      reason,
+      statements: current,
+    });
+    current = [];
+  }
+
+  for (const change of changes) {
+    const sql = integration?.serialize?.(change) ?? change.serialize();
+    const boundary = change.commitBoundary;
+
+    if (change.nonTransactional) {
+      flush();
+      pendingBoundary = null;
+      reason = "default";
+      units.push({
+        transactionMode: "none",
+        reason: "non_transactional",
+        statements: [sql],
+      });
+      continue;
+    }
+
+    // Only producers of the same boundary kind share a unit; anything else
+    // (a different kind or a non-producer) runs after the producers' COMMIT.
+    if (pendingBoundary !== null && boundary !== pendingBoundary) {
+      flush();
+      reason = pendingBoundary;
+      pendingBoundary = null;
+    }
+
+    current.push(sql);
+    if (boundary !== null) {
+      pendingBoundary = boundary;
+    }
+  }
+
+  flush();
+  return units;
+}

package/src/core/plan/index.ts

@@ -9,7 +9,7 @@
  * if (planResult) {
  *   const { plan, sortedChanges, ctx } = planResult;
  *   const hierarchy = groupChangesHierarchically(ctx, sortedChanges);
- *   console.log(plan.statements);
+ *   console.log(renderPlanSql(plan));
  * }
  * ```
  */

package/src/core/plan/io.ts

@@ -2,6 +2,7 @@
  * Plan I/O utilities for serializing and deserializing plans to/from JSON.
  */
 
+import { normalizePlan } from "./normalize.ts";
 import { type Plan, PlanSchema } from "./types.ts";
 
 /**
@@ -12,9 +13,10 @@ export function serializePlan(plan: Plan): string {
 }
 
 /**
- * Deserialize a plan from JSON string.
+ * Deserialize a plan from JSON string. Legacy v1 plans (flat `statements`)
+ * are normalized into migration units.
  */
 export function deserializePlan(json: string): Plan {
   const parsed = JSON.parse(json);
-  return PlanSchema.parse(parsed);
+  return normalizePlan(PlanSchema.parse(parsed));
 }

package/src/core/plan/normalize.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { normalizePlan } from "./normalize.ts";
+import type { SerializedPlan } from "./types.ts";
+
+describe("normalizePlan", () => {
+  test("hydrates legacy v1 plans into a single transactional unit", () => {
+    const legacy: SerializedPlan = {
+      version: 1,
+      source: { fingerprint: "source" },
+      target: { fingerprint: "target" },
+      role: "app_owner",
+      statements: [
+        'SET ROLE "app_owner"',
+        "CREATE TABLE public.users (id integer)",
+        "CREATE INDEX users_id_idx ON public.users (id)",
+      ],
+    };
+
+    const plan = normalizePlan(legacy);
+
+    expect(plan.sessionStatements).toEqual(['SET ROLE "app_owner"']);
+    expect(plan.units).toMatchInlineSnapshot(`
+      [
+        {
+          "reason": "default",
+          "statements": [
+            "CREATE TABLE public.users (id integer)",
+            "CREATE INDEX users_id_idx ON public.users (id)",
+          ],
+          "transactionMode": "transactional",
+        },
+      ]
+    `);
+    expect("statements" in plan).toBe(false);
+  });
+
+  test("hydrates legacy v1 plans with only SET statements into zero units", () => {
+    const legacy: SerializedPlan = {
+      version: 1,
+      source: { fingerprint: "source" },
+      target: { fingerprint: "target" },
+      statements: ['SET ROLE "app_owner"'],
+    };
+
+    const plan = normalizePlan(legacy);
+    expect(plan.units).toEqual([]);
+    expect(plan.sessionStatements).toEqual(['SET ROLE "app_owner"']);
+  });
+
+  test("passes v2 plans through and defaults sessionStatements", () => {
+    const units = [
+      {
+        transactionMode: "transactional" as const,
+        reason: "default" as const,
+        statements: ["CREATE TABLE public.users (id integer)"],
+      },
+    ];
+    const v2: SerializedPlan = {
+      version: 2,
+      source: { fingerprint: "source" },
+      target: { fingerprint: "target" },
+      units,
+    };
+
+    const plan = normalizePlan(v2);
+    expect(plan.units).toEqual(units);
+    expect(plan.sessionStatements).toEqual([]);
+  });
+});

package/src/core/plan/normalize.ts

@@ -0,0 +1,40 @@
+import type { MigrationUnit, Plan, SerializedPlan } from "./types.ts";
+
+/**
+ * Normalize a plan into the v2 shape: `units` + `sessionStatements`.
+ *
+ * Legacy v1 plans carry a flat `statements` array instead of units. Their
+ * leading SET statements become session statements, and the remaining
+ * statements become a single transactional unit — faithful to how the v1
+ * applier executed them (one multi-statement query, i.e. one implicit
+ * transaction).
+ */
+export function normalizePlan(plan: SerializedPlan): Plan {
+  const { statements, ...rest } = plan;
+  return {
+    ...rest,
+    units: plan.units ?? legacyUnits(statements ?? []),
+    sessionStatements:
+      plan.sessionStatements ??
+      (statements ?? []).filter((statement) => isSessionStatement(statement)),
+  };
+}
+
+function isSessionStatement(statement: string): boolean {
+  return /^SET\s+/i.test(statement.trim());
+}
+
+function legacyUnits(statements: string[]): MigrationUnit[] {
+  const schemaStatements = statements.filter(
+    (statement) => !isSessionStatement(statement),
+  );
+  if (schemaStatements.length === 0) return [];
+
+  return [
+    {
+      transactionMode: "transactional",
+      reason: "default",
+      statements: schemaStatements,
+    },
+  ];
+}

package/src/core/plan/render.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import {
+  flattenPlanStatements,
+  renderPlanFiles,
+  renderPlanSql,
+} from "./render.ts";
+import type { Plan } from "./types.ts";
+
+describe("plan rendering", () => {
+  test("renders single SQL scripts with unit boundary comments", () => {
+    expect(renderPlanSql(createPlan())).toMatchInlineSnapshot(`
+      "-- Migration unit 1: schema_changes
+      -- Transaction mode: transactional
+      -- Boundary reason: default
+
+      SET ROLE app_owner;
+
+      BEGIN;
+
+      ALTER TYPE public.user_role ADD VALUE 'store';
+
+      COMMIT;
+
+      -- Migration unit 2: after_enum_values
+      -- Transaction mode: transactional
+      -- Boundary reason: enum_value_visibility
+
+      SET ROLE app_owner;
+
+      BEGIN;
+
+      ALTER TABLE public.profiles ALTER COLUMN role SET DEFAULT 'store'::public.user_role;
+
+      COMMIT;"
+    `);
+  });
+
+  test("renders numbered migration files from units", () => {
+    const files = renderPlanFiles(createPlan());
+
+    expect(files.map((file) => file.path)).toMatchInlineSnapshot(`
+      [
+        "001_schema_changes.sql",
+        "002_after_enum_values.sql",
+      ]
+    `);
+
+    expect(files[0].sql).toMatchInlineSnapshot(`
+      "-- Migration unit 1: schema_changes
+      -- Transaction mode: transactional
+      -- Boundary reason: default
+
+      SET ROLE app_owner;
+
+      BEGIN;
+
+      ALTER TYPE public.user_role ADD VALUE 'store';
+
+      COMMIT;"
+    `);
+
+    expect(files[1].sql).toMatchInlineSnapshot(`
+      "-- Migration unit 2: after_enum_values
+      -- Transaction mode: transactional
+      -- Boundary reason: enum_value_visibility
+
+      SET ROLE app_owner;
+
+      BEGIN;
+
+      ALTER TABLE public.profiles ALTER COLUMN role SET DEFAULT 'store'::public.user_role;
+
+      COMMIT;"
+    `);
+  });
+
+  test("renders non-transactional units without transaction wrappers", () => {
+    const plan = createPlan();
+    plan.units = [
+      {
+        transactionMode: "none",
+        reason: "non_transactional",
+        statements: [
+          "CREATE INDEX CONCURRENTLY users_email_idx ON public.users (email)",
+        ],
+      },
+    ];
+
+    expect(renderPlanSql(plan)).toMatchInlineSnapshot(`
+      "-- Migration unit 1: non_transactional
+      -- Transaction mode: none
+      -- Boundary reason: non_transactional
+      -- Run statement-by-statement (psql does this; do not use psql -1 or
+      -- send this script as a single multi-statement query string).
+
+      SET ROLE app_owner;
+
+      CREATE INDEX CONCURRENTLY users_email_idx ON public.users (email);"
+    `);
+  });
+
+  test("flattenPlanStatements includes session statements", () => {
+    expect(flattenPlanStatements(createPlan())).toEqual([
+      "SET ROLE app_owner",
+      "ALTER TYPE public.user_role ADD VALUE 'store'",
+      "ALTER TABLE public.profiles ALTER COLUMN role SET DEFAULT 'store'::public.user_role",
+    ]);
+  });
+});
+
+function createPlan(): Plan {
+  return {
+    version: 2,
+    source: { fingerprint: "source" },
+    target: { fingerprint: "target" },
+    role: "app_owner",
+    sessionStatements: ["SET ROLE app_owner"],
+    units: [
+      {
+        transactionMode: "transactional",
+        reason: "default",
+        statements: ["ALTER TYPE public.user_role ADD VALUE 'store'"],
+      },
+      {
+        transactionMode: "transactional",
+        reason: "enum_value_visibility",
+        statements: [
+          "ALTER TABLE public.profiles ALTER COLUMN role SET DEFAULT 'store'::public.user_role",
+        ],
+      },
+    ],
+    risk: { level: "safe" },
+  };
+}