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

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" },
+  };
+}

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/risk.ts

@@ -0,0 +1,48 @@
+/**
+ * Risk classification for migration plans.
+ * Identifies data-loss operations that require explicit confirmation.
+ */
+
+import type { Change } from "../change.types.ts";
+import { DropSequence } from "../objects/sequence/changes/sequence.drop.ts";
+import { AlterTableDropColumn } from "../objects/table/changes/table.alter.ts";
+import { DropTable } from "../objects/table/changes/table.drop.ts";
+import type { PlanRisk } from "./types.ts";
+
+/**
+ * Classify a single change for data-loss risk.
+ */
+function classifyChangeRisk(change: Change): string | null {
+  if (change instanceof DropTable) {
+    return `drop table ${change.table.schema}.${change.table.name}`;
+  }
+
+  if (change instanceof AlterTableDropColumn) {
+    return `drop column ${change.column.name} on ${change.table.schema}.${change.table.name}`;
+  }
+
+  if (change instanceof DropSequence) {
+    return `drop sequence ${change.sequence.schema}.${change.sequence.name}`;
+  }
+
+  // Extend here if TRUNCATE or other data-loss operations are added.
+  return null;
+}
+
+/**
+ * Classify all changes for data-loss risk.
+ */
+export function classifyChangesRisk(changes: Change[]): PlanRisk {
+  const statements: string[] = [];
+
+  for (const change of changes) {
+    const reason = classifyChangeRisk(change);
+    if (reason) statements.push(reason);
+  }
+
+  if (statements.length > 0) {
+    return { level: "data_loss", statements };
+  }
+
+  return { level: "safe" };
+}

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

@@ -0,0 +1,317 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "../change.types.ts";
+import { getObjectName, getObjectSchema, getParentInfo } from "./serialize.ts";
+
+describe("getObjectName", () => {
+  const cases: [string, unknown, string][] = [
+    [
+      "aggregate",
+      { objectType: "aggregate", aggregate: { name: "my_agg" } },
+      "my_agg",
+    ],
+    [
+      "collation",
+      { objectType: "collation", collation: { name: "my_coll" } },
+      "my_coll",
+    ],
+    [
+      "composite_type",
+      { objectType: "composite_type", compositeType: { name: "my_comp" } },
+      "my_comp",
+    ],
+    [
+      "domain",
+      { objectType: "domain", domain: { name: "my_domain" } },
+      "my_domain",
+    ],
+    ["enum", { objectType: "enum", enum: { name: "my_enum" } }, "my_enum"],
+    [
+      "event_trigger",
+      { objectType: "event_trigger", eventTrigger: { name: "my_evt" } },
+      "my_evt",
+    ],
+    [
+      "extension",
+      { objectType: "extension", extension: { name: "my_ext" } },
+      "my_ext",
+    ],
+    [
+      "foreign_data_wrapper",
+      {
+        objectType: "foreign_data_wrapper",
+        foreignDataWrapper: { name: "my_fdw" },
+      },
+      "my_fdw",
+    ],
+    [
+      "foreign_table",
+      { objectType: "foreign_table", foreignTable: { name: "my_ft" } },
+      "my_ft",
+    ],
+    ["index", { objectType: "index", index: { name: "my_idx" } }, "my_idx"],
+    [
+      "language",
+      { objectType: "language", language: { name: "plpgsql" } },
+      "plpgsql",
+    ],
+    [
+      "materialized_view",
+      { objectType: "materialized_view", materializedView: { name: "my_mv" } },
+      "my_mv",
+    ],
+    [
+      "procedure",
+      { objectType: "procedure", procedure: { name: "my_proc" } },
+      "my_proc",
+    ],
+    [
+      "publication",
+      { objectType: "publication", publication: { name: "my_pub" } },
+      "my_pub",
+    ],
+    ["range", { objectType: "range", range: { name: "my_range" } }, "my_range"],
+    [
+      "rls_policy",
+      { objectType: "rls_policy", policy: { name: "my_policy" } },
+      "my_policy",
+    ],
+    ["role", { objectType: "role", role: { name: "my_role" } }, "my_role"],
+    ["rule", { objectType: "rule", rule: { name: "my_rule" } }, "my_rule"],
+    [
+      "schema",
+      { objectType: "schema", schema: { name: "my_schema" } },
+      "my_schema",
+    ],
+    [
+      "sequence",
+      { objectType: "sequence", sequence: { name: "my_seq" } },
+      "my_seq",
+    ],
+    [
+      "server",
+      { objectType: "server", server: { name: "my_server" } },
+      "my_server",
+    ],
+    [
+      "subscription",
+      { objectType: "subscription", subscription: { name: "my_sub" } },
+      "my_sub",
+    ],
+    ["table", { objectType: "table", table: { name: "my_table" } }, "my_table"],
+    [
+      "trigger",
+      { objectType: "trigger", trigger: { name: "my_trigger" } },
+      "my_trigger",
+    ],
+    [
+      "user_mapping",
+      {
+        objectType: "user_mapping",
+        userMapping: { user: "alice", server: "remote" },
+      },
+      "alice@remote",
+    ],
+    ["view", { objectType: "view", view: { name: "my_view" } }, "my_view"],
+  ];
+
+  for (const [label, stub, expected] of cases) {
+    test(label, () => {
+      expect(getObjectName(stub as unknown as Change)).toBe(expected);
+    });
+  }
+});
+
+describe("getObjectSchema", () => {
+  const withSchema: [string, unknown, string][] = [
+    [
+      "aggregate",
+      { objectType: "aggregate", aggregate: { schema: "public" } },
+      "public",
+    ],
+    [
+      "collation",
+      { objectType: "collation", collation: { schema: "pg_catalog" } },
+      "pg_catalog",
+    ],
+    [
+      "composite_type",
+      { objectType: "composite_type", compositeType: { schema: "public" } },
+      "public",
+    ],
+    [
+      "domain",
+      { objectType: "domain", domain: { schema: "public" } },
+      "public",
+    ],
+    ["enum", { objectType: "enum", enum: { schema: "public" } }, "public"],
+    [
+      "extension",
+      { objectType: "extension", extension: { schema: "public" } },
+      "public",
+    ],
+    [
+      "foreign_table",
+      { objectType: "foreign_table", foreignTable: { schema: "public" } },
+      "public",
+    ],
+    ["index", { objectType: "index", index: { schema: "public" } }, "public"],
+    [
+      "materialized_view",
+      {
+        objectType: "materialized_view",
+        materializedView: { schema: "public" },
+      },
+      "public",
+    ],
+    [
+      "procedure",
+      { objectType: "procedure", procedure: { schema: "public" } },
+      "public",
+    ],
+    ["range", { objectType: "range", range: { schema: "public" } }, "public"],
+    [
+      "rls_policy",
+      { objectType: "rls_policy", policy: { schema: "public" } },
+      "public",
+    ],
+    ["rule", { objectType: "rule", rule: { schema: "public" } }, "public"],
+    [
+      "schema",
+      { objectType: "schema", schema: { name: "my_schema" } },
+      "my_schema",
+    ],
+    [
+      "sequence",
+      { objectType: "sequence", sequence: { schema: "public" } },
+      "public",
+    ],
+    ["table", { objectType: "table", table: { schema: "public" } }, "public"],
+    [
+      "trigger",
+      { objectType: "trigger", trigger: { schema: "public" } },
+      "public",
+    ],
+    ["view", { objectType: "view", view: { schema: "public" } }, "public"],
+  ];
+
+  for (const [label, stub, expected] of withSchema) {
+    test(`${label} returns schema`, () => {
+      expect(getObjectSchema(stub as unknown as Change)).toBe(expected);
+    });
+  }
+
+  const withoutSchema: [string, unknown][] = [
+    ["event_trigger", { objectType: "event_trigger" }],
+    ["foreign_data_wrapper", { objectType: "foreign_data_wrapper" }],
+    ["language", { objectType: "language" }],
+    ["publication", { objectType: "publication" }],
+    ["role", { objectType: "role" }],
+    ["server", { objectType: "server" }],
+    ["subscription", { objectType: "subscription" }],
+    ["user_mapping", { objectType: "user_mapping" }],
+  ];
+
+  for (const [label, stub] of withoutSchema) {
+    test(`${label} returns null`, () => {
+      expect(getObjectSchema(stub as unknown as Change)).toBeNull();
+    });
+  }
+});
+
+describe("getParentInfo", () => {
+  test("index on table", () => {
+    const change = {
+      objectType: "index",
+      index: { table_name: "users", table_relkind: "r" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "table", name: "users" });
+  });
+
+  test("index on materialized view", () => {
+    const change = {
+      objectType: "index",
+      index: { table_name: "user_stats", table_relkind: "m" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({
+      type: "materialized_view",
+      name: "user_stats",
+    });
+  });
+
+  test("trigger on table", () => {
+    const change = {
+      objectType: "trigger",
+      trigger: { table_name: "orders", table_relkind: "r" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "table", name: "orders" });
+  });
+
+  test("trigger on view", () => {
+    const change = {
+      objectType: "trigger",
+      trigger: { table_name: "order_view", table_relkind: "v" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "view", name: "order_view" });
+  });
+
+  test("trigger on materialized view", () => {
+    const change = {
+      objectType: "trigger",
+      trigger: { table_name: "order_mv", table_relkind: "m" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({
+      type: "materialized_view",
+      name: "order_mv",
+    });
+  });
+
+  test("rule on table", () => {
+    const change = {
+      objectType: "rule",
+      rule: { table_name: "items", relation_kind: "r" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "table", name: "items" });
+  });
+
+  test("rule on view", () => {
+    const change = {
+      objectType: "rule",
+      rule: { table_name: "item_view", relation_kind: "v" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "view", name: "item_view" });
+  });
+
+  test("rule on materialized view", () => {
+    const change = {
+      objectType: "rule",
+      rule: { table_name: "item_mv", relation_kind: "m" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({
+      type: "materialized_view",
+      name: "item_mv",
+    });
+  });
+
+  test("rls_policy", () => {
+    const change = {
+      objectType: "rls_policy",
+      policy: { table_name: "secrets" },
+    } as unknown as Change;
+    expect(getParentInfo(change)).toEqual({ type: "table", name: "secrets" });
+  });
+
+  const nullCases = [
+    "table",
+    "view",
+    "schema",
+    "sequence",
+    "role",
+    "extension",
+  ] as const;
+  for (const objectType of nullCases) {
+    test(`${objectType} returns null`, () => {
+      const change = { objectType } as unknown as Change;
+      expect(getParentInfo(change)).toBeNull();
+    });
+  }
+});