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

package/src/cli/utils.ts

@@ -9,9 +9,9 @@ import type { Change } from "../core/change.types.ts";
 import type { DiffContext } from "../core/context.ts";
 import { groupChangesHierarchically } from "../core/plan/hierarchy.ts";
 import { type Plan, serializePlan } from "../core/plan/index.ts";
+import { renderPlanSql } from "../core/plan/render.ts";
 import { classifyChangesRisk } from "../core/plan/risk.ts";
 import type { SqlFormatOptions } from "../core/plan/sql-format.ts";
-import { formatSqlScript } from "../core/plan/statements.ts";
 import { formatTree } from "./formatters/index.ts";
 
 // Re-export ApplyPlanResult type for convenience
@@ -19,8 +19,19 @@ type ApplyPlanResult =
   | { status: "invalid_plan"; message: string }
   | { status: "fingerprint_mismatch"; current: string; expected: string }
   | { status: "already_applied" }
-  | { status: "applied"; statements: number; warnings?: string[] }
-  | { status: "failed"; error: unknown; script: string };
+  | {
+      status: "applied";
+      statements: number;
+      units: number;
+      warnings?: string[];
+    }
+  | {
+      status: "failed";
+      error: unknown;
+      script: string;
+      failedUnitIndex?: number;
+      completedUnits: number;
+    };
 
 type PlanResult = {
   plan: Plan;
@@ -50,7 +61,7 @@ export function formatPlanForDisplay(
     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" };
     }
@@ -184,12 +195,17 @@ export function handleApplyResult(
       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`,
+        `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) {

package/src/core/catalog.snapshot.test.ts

@@ -12,6 +12,7 @@ import { Role } from "./objects/role/role.model.ts";
 import { Schema } from "./objects/schema/schema.model.ts";
 import { Sequence } from "./objects/sequence/sequence.model.ts";
 import { Table } from "./objects/table/table.model.ts";
+import { flattenPlanStatements } from "./plan/render.ts";
 
 function emptyCatalogProps() {
   return {
@@ -330,7 +331,7 @@ describe("catalog snapshot serde", () => {
 
     const result = await createPlan(null, target);
     expect(result).not.toBeNull();
-    expect(result?.plan.statements.length).toBeGreaterThan(0);
+    expect(flattenPlanStatements(result!.plan).length).toBeGreaterThan(0);
   });
 
   test("createPlan with filter DSL without cascade keeps dependents of excluded changes", async () => {

package/src/core/objects/base.change.ts

@@ -2,6 +2,17 @@ import type { SerializeOptions } from "../integrations/serialize/serialize.types
 
 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.
  *
@@ -27,10 +38,40 @@ export 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 {
+    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(): string {
-    return `${this.operation}:${this.scope}:${this.objectType}:${this.serialize()}`;
+  get commitBoundary(): CommitBoundaryReason | null {
+    return null;
   }
 
   /**

package/src/core/objects/subscription/changes/subscription.alter.ts

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

package/src/core/objects/subscription/changes/subscription.create.test.ts

@@ -45,8 +45,11 @@ describe("subscription.create", () => {
     expect(change.creates).toEqual([subscription.stableId]);
     expect(change.requires).toEqual([stableId.role(subscription.owner)]);
     await assertValidSql(change.serialize());
+    // The slot already exists on the publisher, so the statement must reuse
+    // it: create_slot defaults to true and would fail with "replication slot
+    // already exists" (and 25001 inside a transaction block).
     expect(change.serialize()).toBe(
-      "CREATE SUBSCRIPTION sub_base CONNECTION 'host=example dbname=postgres' PUBLICATION pub_base",
+      "CREATE SUBSCRIPTION sub_base CONNECTION 'host=example dbname=postgres' PUBLICATION pub_base WITH (create_slot = false)",
     );
   });
 

package/src/core/objects/subscription/changes/subscription.create.ts

@@ -23,6 +23,11 @@ export class CreateSubscription extends CreateSubscriptionChange {
     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?: SerializeOptions): string {
     const parts: string[] = [
       "CREATE SUBSCRIPTION",
@@ -41,7 +46,11 @@ export class CreateSubscription extends CreateSubscriptionChange {
       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");
 

package/src/core/objects/subscription/changes/subscription.drop.ts

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

package/src/core/objects/subscription/changes/subscription.traits.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import type { Subscription, SubscriptionProps } from "../subscription.model.ts";
+import { Subscription as SubscriptionModel } from "../subscription.model.ts";
+import { AlterSubscriptionSetPublication } from "./subscription.alter.ts";
+import { CreateSubscription } from "./subscription.create.ts";
+import { DropSubscription } from "./subscription.drop.ts";
+
+function makeSubscription(
+  overrides: Partial<SubscriptionProps> = {},
+): Subscription {
+  return new SubscriptionModel({
+    name: "sub_orders",
+    raw_name: "sub_orders",
+    owner: "postgres",
+    comment: null,
+    enabled: false,
+    binary: false,
+    streaming: "off",
+    two_phase: false,
+    disable_on_error: false,
+    password_required: true,
+    run_as_owner: false,
+    failover: false,
+    conninfo: "host=publisher dbname=app",
+    slot_name: "sub_orders",
+    slot_is_none: false,
+    replication_slot_created: false,
+    synchronous_commit: "off",
+    publications: ["pub_orders"],
+    origin: "any",
+    ...overrides,
+  });
+}
+
+describe("subscription transaction-block traits", () => {
+  test("CREATE SUBSCRIPTION is always transactional", () => {
+    // PostgreSQL's transaction-block gate is on create_slot = true, and
+    // serialize() always emits create_slot = false: connect stays true when
+    // the slot already exists (it is reused, never recreated), and connect
+    // is false otherwise.
+    const withSlot = new CreateSubscription({
+      subscription: makeSubscription({ replication_slot_created: true }),
+    });
+    expect(withSlot.nonTransactional).toBe(false);
+    expect(withSlot.serialize()).toContain("create_slot = false");
+
+    const withoutSlot = new CreateSubscription({
+      subscription: makeSubscription({ replication_slot_created: false }),
+    });
+    expect(withoutSlot.nonTransactional).toBe(false);
+    expect(withoutSlot.serialize()).toContain("create_slot = false");
+  });
+
+  test("ALTER SUBSCRIPTION SET PUBLICATION with implicit refresh cannot run in a transaction block", () => {
+    // serialize() omits WITH (refresh = false) when the subscription is
+    // enabled, and refresh = true is rejected inside a transaction block.
+    const change = new AlterSubscriptionSetPublication({
+      subscription: makeSubscription({ enabled: true }),
+    });
+    expect(change.nonTransactional).toBe(true);
+  });
+
+  test("ALTER SUBSCRIPTION SET PUBLICATION with refresh = false is transactional", () => {
+    const change = new AlterSubscriptionSetPublication({
+      subscription: makeSubscription({ enabled: false }),
+    });
+    expect(change.nonTransactional).toBe(false);
+  });
+
+  test("DROP SUBSCRIPTION with an associated slot cannot run in a transaction block", () => {
+    const change = new DropSubscription({
+      subscription: makeSubscription({ slot_is_none: false }),
+    });
+    expect(change.nonTransactional).toBe(true);
+  });
+
+  test("DROP SUBSCRIPTION with slot_name = NONE is transactional", () => {
+    const change = new DropSubscription({
+      subscription: makeSubscription({ slot_is_none: true, slot_name: null }),
+    });
+    expect(change.nonTransactional).toBe(false);
+  });
+});

package/src/core/objects/type/enum/changes/enum.alter.ts

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

package/src/core/plan/apply.ts

@@ -2,7 +2,7 @@
  * Plan application - execute migration plans against target databases.
  */
 
-import type { Pool } from "pg";
+import type { Pool, PoolClient } from "pg";
 import { diffCatalogs } from "../catalog.diff.ts";
 import { extractCatalog } from "../catalog.model.ts";
 import type { DiffContext } from "../context.ts";
@@ -10,14 +10,29 @@ import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.ts";
 import { compileFilterDSL } from "../integrations/filter/dsl.ts";
 import { createManagedPool, endPool } from "../postgres-config.ts";
 import { sortChanges } from "../sort/sort-changes.ts";
-import type { Plan } from "./types.ts";
+import { normalizePlan } from "./normalize.ts";
+import { renderPlanSql } from "./render.ts";
+import type { MigrationUnit, Plan } from "./types.ts";
 
 type ApplyPlanResult =
   | { status: "invalid_plan"; message: string }
   | { status: "fingerprint_mismatch"; current: string; expected: string }
   | { status: "already_applied" }
-  | { status: "applied"; statements: number; warnings?: string[] }
-  | { status: "failed"; error: unknown; script: string };
+  | {
+      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;
@@ -26,25 +41,22 @@ interface ApplyPlanOptions {
 type ConnectionInput = string | Pool;
 
 /**
- * Check if a statement is a session configuration statement (standalone SET statements).
- * These statements should not be counted as changes.
- */
-function isSessionStatement(statement: string): boolean {
-  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: Plan,
   source: ConnectionInput,
   target: ConnectionInput,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
-  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.",
@@ -58,7 +70,7 @@ export async function applyPlan(
 
   if (typeof source === "string") {
     const managed = await createManagedPool(source, {
-      role: plan.role,
+      role: normalizedPlan.role,
       label: "source",
     });
     currentPool = managed.pool;
@@ -69,7 +81,7 @@ export async function applyPlan(
 
   if (typeof target === "string") {
     const managed = await createManagedPool(target, {
-      role: plan.role,
+      role: normalizedPlan.role,
       label: "target",
     });
     desiredPool = managed.pool;
@@ -93,8 +105,8 @@ export async function applyPlan(
 
     // 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));
     }
 
@@ -106,31 +118,44 @@ export async function applyPlan(
     // 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: string[] = [];
@@ -139,7 +164,7 @@ export async function applyPlan(
       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.",
           );
@@ -151,14 +176,11 @@ export async function applyPlan(
       }
     }
 
-    // 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,
     };
   } finally {
@@ -170,3 +192,26 @@ export async function applyPlan(
     }
   }
 }
+
+async function applyUnit(
+  client: PoolClient,
+  unit: MigrationUnit,
+): Promise<void> {
+  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/src/core/plan/create.ts

@@ -3,7 +3,6 @@
  */
 
 import type { Pool } from "pg";
-import { escapeIdentifier } from "pg";
 import { diffCatalogs } from "../catalog.diff.ts";
 import type { Catalog } from "../catalog.model.ts";
 import { createEmptyCatalog, extractCatalog } from "../catalog.model.ts";
@@ -19,6 +18,7 @@ import type { SerializeDSL } from "../integrations/serialize/dsl.ts";
 import { createManagedPool, endPool } from "../postgres-config.ts";
 import { sortChanges } from "../sort/sort-changes.ts";
 import type { PgDependRow } from "../sort/types.ts";
+import { buildExecutionPlan } from "./execution.ts";
 import { classifyChangesRisk } from "./risk.ts";
 import type { CreatePlanOptions, Plan } from "./types.ts";
 
@@ -306,10 +306,7 @@ function buildPlan(
   integration?: ResolvedIntegration,
 ): Plan {
   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(
@@ -319,52 +316,14 @@ function buildPlan(
   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: Change[],
-  options?: {
-    integration?: ResolvedIntegration;
-    role?: string;
-  },
-): string[] {
-  const statements: string[] = [];
-
-  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: Change[]): boolean {
-  return changes.some(
-    (change) =>
-      change.objectType === "procedure" || change.objectType === "aggregate",
-  );
-}