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

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/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/types.d.ts

@@ -4,12 +4,35 @@
 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";
 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.
@@ -110,7 +133,20 @@ export declare const PlanSchema: z.ZodObject<{
     target: z.ZodObject<{
         fingerprint: z.ZodString;
     }, z.z.core.$strip>;
-    statements: z.ZodArray<z.ZodString>;
+    units: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        transactionMode: z.ZodEnum<{
+            none: "none";
+            transactional: "transactional";
+        }>;
+        reason: z.ZodEnum<{
+            default: "default";
+            enum_value_visibility: "enum_value_visibility";
+            non_transactional: "non_transactional";
+        }>;
+        statements: z.ZodArray<z.ZodString>;
+    }, z.z.core.$strip>>>;
+    sessionStatements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    statements: z.ZodOptional<z.ZodArray<z.ZodString>>;
     role: z.ZodOptional<z.ZodString>;
     filter: z.ZodOptional<z.ZodAny>;
     serialize: z.ZodOptional<z.ZodAny>;
@@ -121,10 +157,18 @@ export declare const PlanSchema: z.ZodObject<{
         statements: z.ZodArray<z.ZodString>;
     }, z.z.core.$strip>], "level">>;
 }, z.z.core.$strip>;
+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/dist/core/plan/types.js

@@ -14,7 +14,24 @@ 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

package/dist/core/sort/sort-changes.js

@@ -20,6 +20,7 @@ import { buildGraphData, convertCatalogDependenciesToConstraints, convertConstra
 import { dedupeEdges } from "./graph-utils.js";
 import { logicalSort } from "./logical-sort.js";
 import { findCycle, formatCycleError, performStableTopologicalSort, } from "./topological-sort.js";
+import { UnorderableCycleError } from "./unorderable-cycle-error.js";
 import { getExecutionPhase } from "./utils.js";
 // `sortPhaseChanges` caps the change-injection breaker at one round per
 // node in the initial phase: there can never be more disjoint unbreakable
@@ -148,7 +149,7 @@ function attemptSortRound(phaseChanges, dependencyRows, options) {
     const topologicalOrder = performStableTopologicalSort(phaseChanges.length, finalEdgePairs);
     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 {
         kind: "sorted",
@@ -186,16 +187,16 @@ function sortPhaseChanges(initialPhaseChanges, dependencyRows, options = {}) {
         // throw with the same diagnostic the original code emitted.
         const broken = tryBreakCycleByChangeInjection(result.cycleNodeIndexes, phaseChanges);
         if (broken === null) {
-            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+            throw new UnorderableCycleError(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges), result.cycleNodeIndexes.map((index) => phaseChanges[index]));
         }
         // Loop guard: if the same cycle node-set re-appears after a break,
         // the breaker isn't making progress. Throw with full context.
         const signature = normalizeCycle(result.cycleNodeIndexes);
         if (breakerRoundSignatures.has(signature)) {
-            throw new Error(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges));
+            throw new UnorderableCycleError(formatCycleError(result.cycleNodeIndexes, phaseChanges, result.cycleEdges), result.cycleNodeIndexes.map((index) => phaseChanges[index]));
         }
         breakerRoundSignatures.add(signature);
         phaseChanges = broken;
     }
-    throw new Error(`CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`);
+    throw new UnorderableCycleError(`CycleError: change-injection breaker exceeded ${maxRounds} rounds (one per node in the phase) — likely a buggy breaker rule`);
 }

package/dist/core/sort/unorderable-cycle-error.d.ts

@@ -0,0 +1,18 @@
+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 declare class UnorderableCycleError extends Error {
+    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[]);
+}

package/dist/core/sort/unorderable-cycle-error.js

@@ -0,0 +1,20 @@
+/**
+ * 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 {
+    name = "UnorderableCycleError";
+    /**
+     * Changes participating in the cycle, in cycle order. Empty when the
+     * failure came from an internal guard rather than a concrete cycle.
+     */
+    cycle;
+    constructor(message, cycle = []) {
+        super(message);
+        this.cycle = cycle;
+    }
+}

package/dist/index.d.ts

@@ -9,10 +9,14 @@ export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from
 export { exportDeclarativeSchema } from "./core/export/index.ts";
 export type { DeclarativeSchemaOutput, FileCategory, FileEntry, FileMetadata, } from "./core/export/types.ts";
 export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+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";
 export { createManagedPool } from "./core/postgres-config.ts";

package/dist/index.js

@@ -8,9 +8,10 @@ export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.mod
 export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.js";
 // Declarative schema export
 export { exportDeclarativeSchema } from "./core/export/index.js";
-// Plan operations
 export { applyPlan } from "./core/plan/apply.js";
 export { createPlan } from "./core/plan/create.js";
+export { flattenPlanStatements, renderPlanFiles, renderPlanSql, } from "./core/plan/render.js";
 export { formatSqlStatements } from "./core/plan/sql-format.js";
+export { UnorderableCycleError } from "./core/sort/unorderable-cycle-error.js";
 // Postgres config
 export { createManagedPool } from "./core/postgres-config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.30",
   "description": "PostgreSQL migrations made easy",
   "keywords": [
     "diff",

package/src/cli/bin/cli.ts

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
 
 import { run } from "@stricli/core";
+import { UnorderableCycleError } from "../../core/sort/unorderable-cycle-error.ts";
 import { app } from "../app.ts";
 import { getCommandExitCode } from "../exit-code.ts";
 
 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);
 });
 

package/src/cli/commands/plan.ts

@@ -2,12 +2,14 @@
  * 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, type CommandContext } from "@stricli/core";
 import { deserializeCatalog } from "../../core/catalog.snapshot.ts";
 import type { FilterDSL } from "../../core/integrations/filter/dsl.ts";
 import type { SerializeDSL } from "../../core/integrations/serialize/dsl.ts";
 import { createPlan } from "../../core/plan/index.ts";
+import { renderPlanFiles } from "../../core/plan/render.ts";
 import type { SqlFormatOptions } from "../../core/plan/sql-format.ts";
 import { setCommandExitCode } from "../exit-code.ts";
 import { resolveIntegrationOptions } from "../utils/integrations.ts";
@@ -43,6 +45,13 @@ 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:
@@ -129,6 +138,7 @@ json/sql outputs are available for artifacts or piping.
       target: string;
       format?: "json" | "sql";
       output?: string;
+      "output-dir"?: string;
       role?: string;
       filter?: FilterDSL;
       serialize?: SerializeDSL;
@@ -169,6 +179,32 @@ json/sql outputs are available for artifacts or piping.
       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: "tree" | "json" | "sql";
     if (flags.format) {
@@ -208,3 +244,13 @@ json/sql outputs are available for artifacts or piping.
     setCommandExitCode(2);
   },
 });
+
+async function prepareOutputDirectory(outputDir: string): Promise<void> {
+  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.`,
+    );
+  }
+}