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

package/dist/core/plan/execution.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { Change } from "../change.types.ts";
+import type { ResolvedIntegration } from "../integrations/integration.types.ts";
+import type { MigrationUnit } from "./types.ts";
+interface BuildExecutionPlanOptions {
+    integration?: ResolvedIntegration;
+    role?: string;
+}
+interface ExecutionPlan {
+    units: MigrationUnit[];
+    sessionStatements: string[];
+}
+export declare function buildExecutionPlan(changes: Change[], options?: BuildExecutionPlanOptions): ExecutionPlan;
+export {};

package/dist/core/plan/execution.js

@@ -0,0 +1,76 @@
+/**
+ * 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";
+export function buildExecutionPlan(changes, options = {}) {
+    return {
+        units: buildMigrationUnits(changes, options.integration),
+        sessionStatements: buildSessionStatements(changes, options),
+    };
+}
+function buildSessionStatements(changes, options) {
+    const statements = [];
+    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) {
+    return changes.some((change) => change.objectType === "procedure" || change.objectType === "aggregate");
+}
+function buildMigrationUnits(changes, integration) {
+    const units = [];
+    let current = [];
+    let reason = "default";
+    let pendingBoundary = null;
+    function flush() {
+        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/dist/core/plan/hierarchy.js

@@ -262,7 +262,7 @@ function addClusterChange(cluster, change) {
             break;
         default: {
             const _exhaustive = objectType;
-            throw new Error(`Unhandled object type: ${_exhaustive}`);
+            throw new Error(`Unhandled object type: ${JSON.stringify(_exhaustive)}`);
         }
     }
 }
@@ -303,7 +303,7 @@ function addChildChange(schema, change) {
             break;
         default: {
             const _exhaustive = parentType;
-            throw new Error(`Unhandled parent type: ${_exhaustive}`);
+            throw new Error(`Unhandled parent type: ${JSON.stringify(_exhaustive)}`);
         }
     }
     const objectType = change.objectType;
@@ -351,7 +351,7 @@ function addChildChange(schema, change) {
             break;
         default: {
             const _exhaustive = objectType;
-            throw new Error(`Unhandled object type: ${_exhaustive}`);
+            throw new Error(`Unhandled object type: ${JSON.stringify(_exhaustive)}`);
         }
     }
 }
@@ -482,7 +482,7 @@ function addSchemaLevelChange(schema, change, enrichment) {
             break;
         default: {
             const _exhaustive = objectType;
-            throw new Error(`Unhandled object type: ${_exhaustive}`);
+            throw new Error(`Unhandled object type: ${JSON.stringify(_exhaustive)}`);
         }
     }
 }

package/dist/core/plan/index.d.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/dist/core/plan/index.js

@@ -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/dist/core/plan/io.d.ts

@@ -7,6 +7,7 @@ import { type Plan } from "./types.ts";
  */
 export declare 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 declare function deserializePlan(json: string): Plan;

package/dist/core/plan/io.js

@@ -1,6 +1,7 @@
 /**
  * Plan I/O utilities for serializing and deserializing plans to/from JSON.
  */
+import { normalizePlan } from "./normalize.js";
 import { PlanSchema } from "./types.js";
 /**
  * Serialize a plan to JSON string.
@@ -9,9 +10,10 @@ export function serializePlan(plan) {
     return JSON.stringify(plan, null, 2);
 }
 /**
- * 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) {
     const parsed = JSON.parse(json);
-    return PlanSchema.parse(parsed);
+    return normalizePlan(PlanSchema.parse(parsed));
 }

package/dist/core/plan/normalize.d.ts

@@ -0,0 +1,11 @@
+import type { 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 declare function normalizePlan(plan: SerializedPlan): Plan;

package/dist/core/plan/normalize.js

@@ -0,0 +1,33 @@
+/**
+ * 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) {
+    const { statements, ...rest } = plan;
+    return {
+        ...rest,
+        units: plan.units ?? legacyUnits(statements ?? []),
+        sessionStatements: plan.sessionStatements ??
+            (statements ?? []).filter((statement) => isSessionStatement(statement)),
+    };
+}
+function isSessionStatement(statement) {
+    return /^SET\s+/i.test(statement.trim());
+}
+function legacyUnits(statements) {
+    const schemaStatements = statements.filter((statement) => !isSessionStatement(statement));
+    if (schemaStatements.length === 0)
+        return [];
+    return [
+        {
+            transactionMode: "transactional",
+            reason: "default",
+            statements: schemaStatements,
+        },
+    ];
+}

package/dist/core/plan/render.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Plan rendering - turn migration units into executable SQL scripts.
+ */
+import type { SqlFormatOptions } from "./sql-format.ts";
+import type { MigrationUnit, SerializedPlan } from "./types.ts";
+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 declare function renderPlanSql(plan: SerializedPlan, options?: RenderPlanSqlOptions): string;
+/**
+ * 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 declare function renderPlanFiles(plan: SerializedPlan, options?: RenderPlanSqlOptions): RenderedPlanFile[];
+/**
+ * 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 declare function flattenPlanStatements(plan: SerializedPlan): string[];

package/dist/core/plan/render.js

@@ -0,0 +1,104 @@
+/**
+ * Plan rendering - turn migration units into executable SQL scripts.
+ */
+import { normalizePlan } from "./normalize.js";
+import { formatSqlStatements } from "./sql-format.js";
+const STATEMENT_DELIMITER = ";\n\n";
+/**
+ * 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, options = {}) {
+    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, options = {}) {
+    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) {
+    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) {
+    switch (reason) {
+        case "default":
+            return "schema_changes";
+        case "enum_value_visibility":
+            return "after_enum_values";
+        case "non_transactional":
+            return "non_transactional";
+    }
+}
+function renderUnitSql(plan, unit, index, options) {
+    const includeTransactions = options.includeTransactions !== false;
+    const body = options.sqlFormatOptions != null
+        ? formatSqlStatements(unit.statements, options.sqlFormatOptions)
+        : unit.statements;
+    const lines = [
+        `-- 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) {
+    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) {
+    const trimmed = statement.trim();
+    let end = trimmed.length;
+    while (end > 0 && trimmed.charCodeAt(end - 1) === 59) {
+        end--;
+    }
+    return trimmed.slice(0, end);
+}

package/dist/core/plan/serialize.js

@@ -139,10 +139,22 @@ export function getParentInfo(change) {
             const parentType = change.index.table_relkind === "m" ? "materialized_view" : "table";
             return { type: parentType, name: change.index.table_name };
         }
-        case "trigger":
-            return { type: "table", name: change.trigger.table_name };
-        case "rule":
-            return { type: "table", name: change.rule.table_name };
+        case "trigger": {
+            const parentType = change.trigger.table_relkind === "v"
+                ? "view"
+                : change.trigger.table_relkind === "m"
+                    ? "materialized_view"
+                    : "table";
+            return { type: parentType, name: change.trigger.table_name };
+        }
+        case "rule": {
+            const parentType = change.rule.relation_kind === "v"
+                ? "view"
+                : change.rule.relation_kind === "m"
+                    ? "materialized_view"
+                    : "table";
+            return { type: parentType, name: change.rule.table_name };
+        }
         case "rls_policy":
             return { type: "table", name: change.policy.table_name };
         case "aggregate":

package/dist/core/plan/sql-format/constants.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedOptions } from "./types.ts";
+export declare const DEFAULT_OPTIONS: NormalizedOptions;

package/dist/core/plan/sql-format/constants.js

@@ -0,0 +1,11 @@
+export const DEFAULT_OPTIONS = {
+    keywordCase: "preserve",
+    indent: 2,
+    maxWidth: 100,
+    commaStyle: "trailing",
+    alignColumns: true,
+    alignKeyValues: true,
+    preserveRoutineBodies: true,
+    preserveViewBodies: true,
+    preserveRuleBodies: true,
+};

package/dist/core/plan/sql-format/fixtures.d.ts

@@ -0,0 +1,2 @@
+import type { SqlFormatOptions } from "../sql-format.ts";
+export declare function renderScript(options?: SqlFormatOptions): string;