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

package/dist/cli/bin/cli.js

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
 import { run } from "@stricli/core";
+import { UnorderableCycleError } from "../../core/sort/unorderable-cycle-error.js";
 import { app } from "../app.js";
 import { getCommandExitCode } from "../exit-code.js";
 await run(app, process.argv.slice(2), { process }).catch((error) => {
-    console.error(error);
+    if (error instanceof UnorderableCycleError) {
+        console.error(error.message);
+        console.error("pg-delta could not find a valid execution order for these changes. Please report this plan at https://github.com/supabase/pg-toolbelt/issues.");
+    }
+    else {
+        console.error(error);
+    }
     process.exit(1);
 });
 const code = getCommandExitCode();

package/dist/cli/commands/plan.js

@@ -1,10 +1,12 @@
 /**
  * Plan command - compute schema diff and preview changes.
  */
-import { writeFile } from "node:fs/promises";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { buildCommand } from "@stricli/core";
 import { deserializeCatalog } from "../../core/catalog.snapshot.js";
 import { createPlan } from "../../core/plan/index.js";
+import { renderPlanFiles } from "../../core/plan/render.js";
 import { setCommandExitCode } from "../exit-code.js";
 import { resolveIntegrationOptions } from "../utils/integrations.js";
 import { isPostgresUrl, loadCatalogFromFile } from "../utils/resolve-input.js";
@@ -35,6 +37,12 @@ export const planCommand = buildCommand({
                 parse: String,
                 optional: true,
             },
+            "output-dir": {
+                kind: "parsed",
+                brief: "Write numbered SQL migration files to a directory using transaction-aware plan units.",
+                parse: String,
+                optional: true,
+            },
             role: {
                 kind: "parsed",
                 brief: "Role to use when executing the migration (SET ROLE will be added to statements).",
@@ -131,6 +139,23 @@ json/sql outputs are available for artifacts or piping.
             this.process.stdout.write("No changes detected.\n");
             return;
         }
+        if (flags.output && flags["output-dir"]) {
+            throw new Error("Use either --output or --output-dir, not both.");
+        }
+        if (flags["output-dir"]) {
+            await prepareOutputDirectory(flags["output-dir"]);
+            const files = renderPlanFiles(planResult.plan, {
+                sqlFormatOptions: flags["sql-format"] || flags["sql-format-options"]
+                    ? (flags["sql-format-options"] ?? {})
+                    : undefined,
+            });
+            for (const file of files) {
+                await writeFile(path.join(flags["output-dir"], file.path), file.sql, "utf-8");
+            }
+            this.process.stdout.write(`${files.length} migration file${files.length === 1 ? "" : "s"} written to ${flags["output-dir"]}\n`);
+            setCommandExitCode(2);
+            return;
+        }
         const outputPath = flags.output;
         let effectiveFormat;
         if (flags.format) {
@@ -166,3 +191,10 @@ json/sql outputs are available for artifacts or piping.
         setCommandExitCode(2);
     },
 });
+async function prepareOutputDirectory(outputDir) {
+    await mkdir(outputDir, { recursive: true });
+    const entries = await readdir(outputDir);
+    if (entries.length > 0) {
+        throw new Error(`Output directory is not empty: ${outputDir}. Choose an empty directory to avoid stale migration files.`);
+    }
+}

package/dist/cli/utils.d.ts

@@ -18,11 +18,14 @@ type ApplyPlanResult = {
 } | {
     status: "applied";
     statements: number;
+    units: number;
     warnings?: string[];
 } | {
     status: "failed";
     error: unknown;
     script: string;
+    failedUnitIndex?: number;
+    completedUnits: number;
 };
 type PlanResult = {
     plan: Plan;

package/dist/cli/utils.js

@@ -5,8 +5,8 @@ import { createInterface } from "node:readline";
 import chalk from "chalk";
 import { groupChangesHierarchically } from "../core/plan/hierarchy.js";
 import { serializePlan } from "../core/plan/index.js";
+import { renderPlanSql } from "../core/plan/render.js";
 import { classifyChangesRisk } from "../core/plan/risk.js";
-import { formatSqlScript } from "../core/plan/statements.js";
 import { formatTree } from "./formatters/index.js";
 /**
  * Formats a plan result for display in various formats.
@@ -19,7 +19,7 @@ export function formatPlanForDisplay(planResult, format, options = {}) {
         case "sql": {
             const content = [
                 `-- Risk: ${risk.level === "data_loss" ? `data-loss (${risk.statements.length})` : "safe"}`,
-                formatSqlScript(plan.statements, options.sqlFormatOptions),
+                renderPlanSql(plan, { sqlFormatOptions: options.sqlFormatOptions }),
             ].join("\n");
             return { content, label: "Migration script" };
         }
@@ -123,11 +123,14 @@ export function handleApplyResult(result, context) {
             return { exitCode: 0 };
         case "failed": {
             context.process.stderr.write(`Failed to apply changes: ${result.error instanceof Error ? result.error.message : String(result.error)}\n`);
+            if (result.failedUnitIndex !== undefined) {
+                context.process.stderr.write(`Failed in migration unit ${result.failedUnitIndex + 1} (${result.completedUnits} unit${result.completedUnits === 1 ? "" : "s"} already committed).\n`);
+            }
             context.process.stderr.write(`Migration script:\n${result.script}\n`);
             return { exitCode: 1 };
         }
         case "applied": {
-            context.process.stdout.write(`Applying ${result.statements} changes to database...\n`);
+            context.process.stdout.write(`Applied ${result.statements} change${result.statements === 1 ? "" : "s"} across ${result.units} migration unit${result.units === 1 ? "" : "s"}.\n`);
             context.process.stdout.write("Successfully applied all changes.\n");
             if (result.warnings?.length) {
                 for (const warning of result.warnings) {

package/dist/core/objects/base.change.d.ts

@@ -1,5 +1,15 @@
 import type { SerializeOptions } from "../integrations/serialize/serialize.types.ts";
 type ChangeOperation = "create" | "alter" | "drop";
+/**
+ * Kinds of commit-visibility boundaries a change can force.
+ *
+ * Each kind names a PostgreSQL behavior where a statement's effects only
+ * become usable by later statements after the enclosing transaction commits.
+ * The token becomes the `reason` of the migration unit that follows the
+ * producer run, so adding a kind requires a matching arm in the renderer's
+ * `unitName` switch (the exhaustive switch enforces this at compile time).
+ */
+export type CommitBoundaryReason = "enum_value_visibility";
 /**
  * Abstract base class for all change objects.
  *
@@ -24,9 +34,36 @@ export declare abstract class BaseChange {
      */
     abstract readonly scope: string;
     /**
-     * A unique identifier for the change.
+     * True when the serialized statement cannot run inside a transaction block
+     * (PostgreSQL rejects it with SQLSTATE 25001, e.g. `CREATE INDEX
+     * CONCURRENTLY`, `CREATE SUBSCRIPTION` with `connect = true`).
+     *
+     * The planner emits such a change as its own single-statement migration
+     * unit with `transactionMode: "none"`, and `applyPlan` executes it without
+     * a `BEGIN`/`COMMIT` wrapper. Never derive this from the rendered SQL —
+     * declare it on the change class.
+     *
+     * Defaults to false. Override in subclasses whose statement PostgreSQL
+     * forbids inside a transaction block.
+     */
+    get nonTransactional(): boolean;
+    /**
+     * Non-null when this statement's effects only become usable by later
+     * statements after the enclosing transaction commits. The canonical case is
+     * `ALTER TYPE ... ADD VALUE`: using the new enum value in the same
+     * transaction fails with 55P04.
+     *
+     * This is a conservative boundary signal: the planner groups consecutive
+     * producers of the same kind into one unit, and pushes any other statement
+     * (different kind or non-producer) past a commit boundary, regardless of
+     * whether it references the produced effects. No consumer detection is
+     * attempted. Never derive this from the rendered SQL — declare it on the
+     * change class.
+     *
+     * Defaults to null. Override in subclasses whose effects PostgreSQL defers
+     * until commit.
      */
-    get changeId(): string;
+    get commitBoundary(): CommitBoundaryReason | null;
     /**
      * Stable identifiers this change creates.
      *

package/dist/core/objects/base.change.js

@@ -10,10 +10,39 @@
  */
 export class BaseChange {
     /**
-     * A unique identifier for the change.
+     * True when the serialized statement cannot run inside a transaction block
+     * (PostgreSQL rejects it with SQLSTATE 25001, e.g. `CREATE INDEX
+     * CONCURRENTLY`, `CREATE SUBSCRIPTION` with `connect = true`).
+     *
+     * The planner emits such a change as its own single-statement migration
+     * unit with `transactionMode: "none"`, and `applyPlan` executes it without
+     * a `BEGIN`/`COMMIT` wrapper. Never derive this from the rendered SQL —
+     * declare it on the change class.
+     *
+     * Defaults to false. Override in subclasses whose statement PostgreSQL
+     * forbids inside a transaction block.
+     */
+    get nonTransactional() {
+        return false;
+    }
+    /**
+     * Non-null when this statement's effects only become usable by later
+     * statements after the enclosing transaction commits. The canonical case is
+     * `ALTER TYPE ... ADD VALUE`: using the new enum value in the same
+     * transaction fails with 55P04.
+     *
+     * This is a conservative boundary signal: the planner groups consecutive
+     * producers of the same kind into one unit, and pushes any other statement
+     * (different kind or non-producer) past a commit boundary, regardless of
+     * whether it references the produced effects. No consumer detection is
+     * attempted. Never derive this from the rendered SQL — declare it on the
+     * change class.
+     *
+     * Defaults to null. Override in subclasses whose effects PostgreSQL defers
+     * until commit.
      */
-    get changeId() {
-        return `${this.operation}:${this.scope}:${this.objectType}:${this.serialize()}`;
+    get commitBoundary() {
+        return null;
     }
     /**
      * Stable identifiers this change creates.

package/dist/core/objects/subscription/changes/subscription.alter.d.ts

@@ -16,6 +16,7 @@ export declare class AlterSubscriptionSetPublication extends AlterSubscriptionCh
     constructor(props: {
         subscription: Subscription;
     });
+    get nonTransactional(): boolean;
     serialize(_options?: SerializeOptions): string;
 }
 export declare class AlterSubscriptionEnable extends AlterSubscriptionChange {

package/dist/core/objects/subscription/changes/subscription.alter.js

@@ -20,6 +20,11 @@ export class AlterSubscriptionSetPublication extends AlterSubscriptionChange {
         super();
         this.subscription = props.subscription;
     }
+    // When the subscription is enabled, serialize() keeps the refresh = true
+    // default, which PostgreSQL rejects inside a transaction block.
+    get nonTransactional() {
+        return this.subscription.enabled;
+    }
     serialize(_options) {
         const base = `ALTER SUBSCRIPTION ${this.subscription.name} SET PUBLICATION ${this.subscription.publications.join(", ")}`;
         if (!this.subscription.enabled) {

package/dist/core/objects/subscription/changes/subscription.create.js

@@ -16,6 +16,10 @@ export class CreateSubscription extends CreateSubscriptionChange {
     get requires() {
         return [stableId.role(this.subscription.owner)];
     }
+    // No nonTransactional override: PostgreSQL's transaction-block gate for
+    // CREATE SUBSCRIPTION is on create_slot = true, and serialize() always
+    // emits create_slot = false (either reusing an existing slot or skipping
+    // the connect entirely).
     serialize(_options) {
         const parts = [
             "CREATE SUBSCRIPTION",
@@ -30,7 +34,12 @@ export class CreateSubscription extends CreateSubscriptionChange {
             includeEnabled: true,
         });
         const optionsMap = new Map(optionEntries.map(({ key, value }) => [key, value]));
-        if (!this.subscription.replication_slot_created) {
+        if (this.subscription.replication_slot_created) {
+            // The slot already exists on the publisher: keep the connect = true
+            // default so it is looked up, but never recreated.
+            optionsMap.set("create_slot", "false");
+        }
+        else {
             optionsMap.set("create_slot", "false");
             optionsMap.set("connect", "false");
             const defaultSlotName = this.subscription.raw_name;

package/dist/core/objects/subscription/changes/subscription.drop.d.ts

@@ -8,5 +8,6 @@ export declare class DropSubscription extends DropSubscriptionChange {
         subscription: Subscription;
     });
     get drops(): `subscription:${string}`[];
+    get nonTransactional(): boolean;
     serialize(_options?: SerializeOptions): string;
 }

package/dist/core/objects/subscription/changes/subscription.drop.js

@@ -9,6 +9,11 @@ export class DropSubscription extends DropSubscriptionChange {
     get drops() {
         return [this.subscription.stableId];
     }
+    // PostgreSQL forbids DROP SUBSCRIPTION inside a transaction block when a
+    // replication slot is associated with the subscription.
+    get nonTransactional() {
+        return !this.subscription.slot_is_none;
+    }
     serialize(_options) {
         return `DROP SUBSCRIPTION ${this.subscription.name}`;
     }

package/dist/core/objects/type/enum/changes/enum.alter.d.ts

@@ -49,5 +49,6 @@ export declare class AlterEnumAddValue extends AlterEnumChange {
         };
     });
     get requires(): `type:${string}`[];
+    get commitBoundary(): "enum_value_visibility";
     serialize(_options?: SerializeOptions): string;
 }

package/dist/core/objects/type/enum/changes/enum.alter.js

@@ -41,6 +41,10 @@ export class AlterEnumAddValue extends AlterEnumChange {
     get requires() {
         return [this.enum.stableId];
     }
+    // New enum values are not usable until the transaction commits (55P04).
+    get commitBoundary() {
+        return "enum_value_visibility";
+    }
     serialize(_options) {
         const parts = [
             "ALTER TYPE",

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

@@ -15,19 +15,28 @@ type ApplyPlanResult = {
 } | {
     status: "applied";
     statements: number;
+    units: number;
     warnings?: string[];
 } | {
     status: "failed";
     error: unknown;
     script: string;
+    /** 0-based index of the unit that failed; undefined if a session statement failed. */
+    failedUnitIndex?: number;
+    /** Number of units fully committed before the failure. */
+    completedUnits: number;
 };
 interface ApplyPlanOptions {
     verifyPostApply?: boolean;
 }
 type ConnectionInput = string | Pool;
 /**
- * Apply a plan's SQL statements to a target database with integrity checks.
+ * Apply a plan's migration units to a target database with integrity checks.
  * Validates fingerprints before and after application to ensure plan integrity.
+ *
+ * Units are applied in order on a single session: transactional units inside
+ * an explicit BEGIN/COMMIT, non-transactional units without a wrapper. A
+ * failure does not roll back units that already committed.
  */
 export declare function applyPlan(plan: Plan, source: ConnectionInput, target: ConnectionInput, options?: ApplyPlanOptions): Promise<ApplyPlanResult>;
 export {};

package/dist/core/plan/apply.js

@@ -7,19 +7,20 @@ import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
 import { compileFilterDSL } from "../integrations/filter/dsl.js";
 import { createManagedPool, endPool } from "../postgres-config.js";
 import { sortChanges } from "../sort/sort-changes.js";
+import { normalizePlan } from "./normalize.js";
+import { renderPlanSql } from "./render.js";
 /**
- * Check if a statement is a session configuration statement (standalone SET statements).
- * These statements should not be counted as changes.
- */
-function isSessionStatement(statement) {
-    return statement.trim().startsWith("SET ");
-}
-/**
- * Apply a plan's SQL statements to a target database with integrity checks.
+ * Apply a plan's migration units to a target database with integrity checks.
  * Validates fingerprints before and after application to ensure plan integrity.
+ *
+ * Units are applied in order on a single session: transactional units inside
+ * an explicit BEGIN/COMMIT, non-transactional units without a wrapper. A
+ * failure does not roll back units that already committed.
  */
 export async function applyPlan(plan, source, target, options = {}) {
-    if (!plan.statements || plan.statements.length === 0) {
+    const normalizedPlan = normalizePlan(plan);
+    const units = normalizedPlan.units;
+    if (units.length === 0) {
         return {
             status: "invalid_plan",
             message: "Plan contains no SQL statements to execute.",
@@ -31,7 +32,7 @@ export async function applyPlan(plan, source, target, options = {}) {
     let shouldCloseDesired = false;
     if (typeof source === "string") {
         const managed = await createManagedPool(source, {
-            role: plan.role,
+            role: normalizedPlan.role,
             label: "source",
         });
         currentPool = managed.pool;
@@ -42,7 +43,7 @@ export async function applyPlan(plan, source, target, options = {}) {
     }
     if (typeof target === "string") {
         const managed = await createManagedPool(target, {
-            role: plan.role,
+            role: normalizedPlan.role,
             label: "target",
         });
         desiredPool = managed.pool;
@@ -64,43 +65,58 @@ export async function applyPlan(plan, source, target, options = {}) {
         };
         // Apply the same filter that was used to create the plan (if any)
         let filteredChanges = changes;
-        if (plan.filter) {
-            const filterFn = compileFilterDSL(plan.filter);
+        if (normalizedPlan.filter) {
+            const filterFn = compileFilterDSL(normalizedPlan.filter);
             filteredChanges = filteredChanges.filter((change) => filterFn(change));
         }
         const sortedChanges = sortChanges(ctx, filteredChanges);
         const { hash: fingerprintFrom, stableIds } = buildPlanScopeFingerprint(ctx.mainCatalog, sortedChanges);
         // We intentionally recompute target fingerprint only after applying.
         // Pre-apply fingerprint validation
-        if (fingerprintFrom === plan.target.fingerprint) {
+        if (fingerprintFrom === normalizedPlan.target.fingerprint) {
             return { status: "already_applied" };
         }
-        if (fingerprintFrom !== plan.source.fingerprint) {
+        if (fingerprintFrom !== normalizedPlan.source.fingerprint) {
             return {
                 status: "fingerprint_mismatch",
                 current: fingerprintFrom,
-                expected: plan.source.fingerprint,
+                expected: normalizedPlan.source.fingerprint,
             };
         }
-        // Execute the SQL script
-        // TODO: mark statements that can't be run within a transaction
-        const statements = plan.statements;
-        const script = (() => {
-            const joined = statements.join(";\n");
-            return joined.endsWith(";") ? joined : `${joined};`;
-        })();
+        const script = renderPlanSql(normalizedPlan);
+        let completedUnits = 0;
+        let unitStarted = false;
+        // A single session for the whole plan: session statements (SET ROLE,
+        // SET check_function_bodies) must stay in effect across all units.
+        const client = await currentPool.connect();
         try {
-            await currentPool.query(script);
+            for (const statement of normalizedPlan.sessionStatements) {
+                await client.query(statement);
+            }
+            for (const unit of units) {
+                unitStarted = true;
+                await applyUnit(client, unit);
+                completedUnits++;
+            }
         }
         catch (error) {
-            return { status: "failed", error, script };
+            return {
+                status: "failed",
+                error,
+                script,
+                failedUnitIndex: unitStarted ? completedUnits : undefined,
+                completedUnits,
+            };
+        }
+        finally {
+            client.release();
         }
         const warnings = [];
         if (options.verifyPostApply !== false) {
             try {
                 const updatedCatalog = await extractCatalog(currentPool);
                 const updatedFingerprint = hashStableIds(updatedCatalog, stableIds);
-                if (updatedFingerprint !== plan.target.fingerprint) {
+                if (updatedFingerprint !== normalizedPlan.target.fingerprint) {
                     warnings.push("Post-apply fingerprint does not match the plan target fingerprint.");
                 }
             }
@@ -108,11 +124,11 @@ export async function applyPlan(plan, source, target, options = {}) {
                 warnings.push(`Could not verify post-apply fingerprint: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        // Count only actual changes, excluding session configuration statements
-        const changeStatements = statements.filter((stmt) => !isSessionStatement(stmt));
         return {
             status: "applied",
-            statements: changeStatements.length,
+            // Units contain only change statements; session statements are not counted.
+            statements: units.reduce((sum, unit) => sum + unit.statements.length, 0),
+            units: units.length,
             warnings: warnings.length ? warnings : undefined,
         };
     }
@@ -127,3 +143,22 @@ export async function applyPlan(plan, source, target, options = {}) {
         }
     }
 }
+async function applyUnit(client, unit) {
+    if (unit.transactionMode === "transactional") {
+        await client.query("BEGIN");
+        try {
+            for (const statement of unit.statements) {
+                await client.query(statement);
+            }
+            await client.query("COMMIT");
+        }
+        catch (error) {
+            await client.query("ROLLBACK").catch(() => { });
+            throw error;
+        }
+        return;
+    }
+    for (const statement of unit.statements) {
+        await client.query(statement);
+    }
+}

package/dist/core/plan/create.js

@@ -1,13 +1,13 @@
 /**
  * Plan creation - the main entry point for creating migration plans.
  */
-import { escapeIdentifier } from "pg";
 import { diffCatalogs } from "../catalog.diff.js";
 import { createEmptyCatalog, extractCatalog } from "../catalog.model.js";
 import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
 import { resolveIntegration, } from "../integrations/integration.types.js";
 import { createManagedPool, endPool } from "../postgres-config.js";
 import { sortChanges } from "../sort/sort-changes.js";
+import { buildExecutionPlan } from "./execution.js";
 import { classifyChangesRisk } from "./risk.js";
 /**
  * Bundle-safe catalog detection: treat input as a resolved Catalog when it has
@@ -215,45 +215,19 @@ function cascadeExclusions(filteredChanges, allChanges, catalogDepends) {
  */
 function buildPlan(ctx, changes, options, filterDSL, serializeDSL, integration) {
     const role = options?.role;
-    const statements = generateStatements(changes, {
-        integration,
-        role,
-    });
+    const execution = buildExecutionPlan(changes, { integration, role });
     const risk = classifyChangesRisk(changes);
     const { hash: fingerprintFrom, stableIds } = buildPlanScopeFingerprint(ctx.mainCatalog, changes);
     const fingerprintTo = hashStableIds(ctx.branchCatalog, stableIds);
     return {
-        version: 1,
+        version: 2,
         source: { fingerprint: fingerprintFrom },
         target: { fingerprint: fingerprintTo },
-        statements,
+        units: execution.units,
+        sessionStatements: execution.sessionStatements,
         role,
         filter: filterDSL,
         serialize: serializeDSL,
         risk,
     };
 }
-/**
- * Generate the individual SQL statements that make up the plan.
- */
-function generateStatements(changes, options) {
-    const statements = [];
-    if (options?.role) {
-        statements.push(`SET ROLE ${escapeIdentifier(options.role)}`);
-    }
-    if (hasRoutineChanges(changes)) {
-        statements.push("SET check_function_bodies = false");
-    }
-    for (const change of changes) {
-        const sql = options?.integration?.serialize?.(change) ?? change.serialize();
-        statements.push(sql);
-    }
-    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");
-}

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 {};