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

package/src/core/plan/apply.ts

@@ -0,0 +1,217 @@
+/**
+ * Plan application - execute migration plans against target databases.
+ */
+
+import type { Pool, PoolClient } from "pg";
+import { diffCatalogs } from "../catalog.diff.ts";
+import { extractCatalog } from "../catalog.model.ts";
+import type { DiffContext } from "../context.ts";
+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 { 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;
+      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 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> {
+  const normalizedPlan = normalizePlan(plan);
+  const units = normalizedPlan.units;
+  if (units.length === 0) {
+    return {
+      status: "invalid_plan",
+      message: "Plan contains no SQL statements to execute.",
+    };
+  }
+
+  let currentPool: Pool;
+  let desiredPool: Pool;
+  let shouldCloseCurrent = false;
+  let shouldCloseDesired = false;
+
+  if (typeof source === "string") {
+    const managed = await createManagedPool(source, {
+      role: normalizedPlan.role,
+      label: "source",
+    });
+    currentPool = managed.pool;
+    shouldCloseCurrent = true;
+  } else {
+    currentPool = source;
+  }
+
+  if (typeof target === "string") {
+    const managed = await createManagedPool(target, {
+      role: normalizedPlan.role,
+      label: "target",
+    });
+    desiredPool = managed.pool;
+    shouldCloseDesired = true;
+  } else {
+    desiredPool = target;
+  }
+
+  try {
+    // Recompute stableIds and fingerprints from current and desired catalogs
+    const [currentCatalog, desiredCatalog] = await Promise.all([
+      extractCatalog(currentPool),
+      extractCatalog(desiredPool),
+    ]);
+
+    const changes = diffCatalogs(currentCatalog, desiredCatalog);
+    const ctx: DiffContext = {
+      mainCatalog: currentCatalog,
+      branchCatalog: desiredCatalog,
+    };
+
+    // Apply the same filter that was used to create the plan (if any)
+    let filteredChanges = changes;
+    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 === normalizedPlan.target.fingerprint) {
+      return { status: "already_applied" };
+    }
+
+    if (fingerprintFrom !== normalizedPlan.source.fingerprint) {
+      return {
+        status: "fingerprint_mismatch",
+        current: fingerprintFrom,
+        expected: normalizedPlan.source.fingerprint,
+      };
+    }
+
+    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 {
+      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,
+        failedUnitIndex: unitStarted ? completedUnits : undefined,
+        completedUnits,
+      };
+    } finally {
+      client.release();
+    }
+
+    const warnings: string[] = [];
+
+    if (options.verifyPostApply !== false) {
+      try {
+        const updatedCatalog = await extractCatalog(currentPool);
+        const updatedFingerprint = hashStableIds(updatedCatalog, stableIds);
+        if (updatedFingerprint !== normalizedPlan.target.fingerprint) {
+          warnings.push(
+            "Post-apply fingerprint does not match the plan target fingerprint.",
+          );
+        }
+      } catch (error) {
+        warnings.push(
+          `Could not verify post-apply fingerprint: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+
+    return {
+      status: "applied",
+      // 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 {
+    const closers: Promise<unknown>[] = [];
+    if (shouldCloseCurrent) closers.push(endPool(currentPool));
+    if (shouldCloseDesired) closers.push(endPool(desiredPool));
+    if (closers.length) {
+      await Promise.all(closers);
+    }
+  }
+}
+
+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

@@ -0,0 +1,329 @@
+/**
+ * Plan creation - the main entry point for creating migration plans.
+ */
+
+import type { Pool } from "pg";
+import { diffCatalogs } from "../catalog.diff.ts";
+import type { Catalog } from "../catalog.model.ts";
+import { createEmptyCatalog, extractCatalog } from "../catalog.model.ts";
+import type { Change } from "../change.types.ts";
+import type { DiffContext } from "../context.ts";
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.ts";
+import type { FilterDSL } from "../integrations/filter/dsl.ts";
+import {
+  type ResolvedIntegration,
+  resolveIntegration,
+} from "../integrations/integration.types.ts";
+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";
+
+// ============================================================================
+// Plan Creation
+// ============================================================================
+
+/**
+ * Input for source/target: a postgres connection URL, an existing Pool, or
+ * an already-resolved Catalog (e.g. deserialized from a snapshot file).
+ */
+export type CatalogInput = string | Pool | Catalog;
+
+/**
+ * Bundle-safe catalog detection: treat input as a resolved Catalog when it has
+ * the catalog shape and is not a pg Pool. Deserialized or cross-bundle Catalog
+ * instances may fail `instanceof Catalog` but pass this guard.
+ */
+function isResolvedCatalog(input: CatalogInput): input is Catalog {
+  return (
+    typeof input === "object" &&
+    input !== null &&
+    typeof (input as { query?: unknown }).query !== "function" &&
+    "version" in input &&
+    "currentUser" in input &&
+    "depends" in input &&
+    "schemas" in input &&
+    "tables" in input &&
+    "views" in input
+  );
+}
+
+/**
+ * Create a migration plan by comparing two catalog states.
+ *
+ * Each input can be:
+ * - A postgres connection URL (string) -- a pool is created and catalog extracted
+ * - An existing pg Pool -- catalog is extracted directly
+ * - A Catalog instance -- used as-is (e.g. from a deserialized snapshot)
+ *
+ * When `source` is `null`, a minimal empty catalog (`createEmptyCatalog`) is
+ * used as the baseline. For a more accurate baseline, pass a Catalog
+ * deserialized from a snapshot of `template1` or another reference database.
+ *
+ * @param source - Source catalog input (current state), or null for empty baseline
+ * @param target - Target catalog input (desired state)
+ * @param options - Optional configuration
+ * @returns A Plan if there are changes, null if databases are identical
+ */
+export async function createPlan(
+  source: CatalogInput | null,
+  target: CatalogInput,
+  options: CreatePlanOptions = {},
+): Promise<{ plan: Plan; sortedChanges: Change[]; ctx: DiffContext } | null> {
+  const resolvePool = async (
+    input: string | Pool,
+    label: "source" | "target",
+  ): Promise<{ pool: Pool; shouldClose: boolean }> => {
+    if (typeof input === "string") {
+      const managed = await createManagedPool(input, {
+        role: options.role,
+        label,
+      });
+      return { pool: managed.pool, shouldClose: true };
+    }
+    return { pool: input, shouldClose: false };
+  };
+
+  /**
+   * Resolve a CatalogInput to a Catalog, tracking pools that need cleanup.
+   */
+  const resolveCatalog = async (
+    input: CatalogInput,
+    label: "source" | "target",
+    pools: Array<{ pool: Pool; shouldClose: boolean }>,
+  ): Promise<Catalog> => {
+    if (isResolvedCatalog(input)) {
+      return input;
+    }
+    const resolved = await resolvePool(input, label);
+    pools.push(resolved);
+    return extractCatalog(resolved.pool, {
+      extractRetries: options.extractRetries,
+    });
+  };
+
+  const pools: Array<{ pool: Pool; shouldClose: boolean }> = [];
+
+  try {
+    const toCatalog = await resolveCatalog(target, "target", pools);
+
+    const fromCatalog =
+      source !== null
+        ? await resolveCatalog(source, "source", pools)
+        : await createEmptyCatalog(toCatalog.version, toCatalog.currentUser);
+
+    return buildPlanForCatalogs(fromCatalog, toCatalog, options);
+  } finally {
+    const closers = pools
+      .filter((p) => p.shouldClose)
+      .map((p) => endPool(p.pool));
+    if (closers.length) await Promise.all(closers);
+  }
+}
+
+/**
+ * Build a plan (and supporting artifacts) from already extracted catalogs.
+ */
+function buildPlanForCatalogs(
+  fromCatalog: Catalog,
+  toCatalog: Catalog,
+  options: CreatePlanOptions = {},
+): { plan: Plan; sortedChanges: Change[]; ctx: DiffContext } | null {
+  const changes = diffCatalogs(fromCatalog, toCatalog, {
+    role: options.role,
+    skipDefaultPrivilegeSubtraction: options.skipDefaultPrivilegeSubtraction,
+  });
+
+  const filterOption = options.filter;
+  const serializeOption = options.serialize;
+  const ctx: DiffContext = {
+    mainCatalog: fromCatalog,
+    branchCatalog: toCatalog,
+  };
+
+  // Determine if filter/serialize are DSL or functions, and extract DSL for storage
+  const isFilterDSL = filterOption && typeof filterOption !== "function";
+  const isSerializeDSL =
+    serializeOption && typeof serializeOption !== "function";
+  const filterDSL = isFilterDSL ? (filterOption as FilterDSL) : undefined;
+  const serializeDSL = isSerializeDSL
+    ? (serializeOption as SerializeDSL)
+    : undefined;
+
+  // Build final integration: compile DSL if needed, use functions directly otherwise
+  const finalIntegration = resolveIntegration({
+    filter: filterOption,
+    serialize: serializeOption,
+  });
+
+  // Use filter from final integration
+  const filterFn = finalIntegration?.filter;
+
+  let filteredChanges = filterFn
+    ? changes.filter((change) => filterFn(change))
+    : changes;
+
+  // Cascade dependency exclusions: when a change is excluded by the filter,
+  // also exclude changes that depend on it (via requires or pg_depend).
+  // DSL filters: cascade only if explicitly opted in (cascade: true). Function filters: cascade by default.
+  const shouldCascade = isFilterDSL
+    ? (filterDSL as Record<string, unknown>)?.cascade === true
+    : true;
+  if (filterFn && filteredChanges.length < changes.length && shouldCascade) {
+    filteredChanges = cascadeExclusions(
+      filteredChanges,
+      changes,
+      toCatalog.depends,
+    );
+  }
+
+  if (filteredChanges.length === 0) {
+    return null;
+  }
+
+  const sortedChanges = sortChanges(ctx, filteredChanges);
+  const plan = buildPlan(
+    ctx,
+    sortedChanges,
+    options,
+    filterDSL,
+    serializeDSL,
+    finalIntegration,
+  );
+
+  return { plan, sortedChanges, ctx };
+}
+
+// ============================================================================
+// Dependency Cascading
+// ============================================================================
+
+/**
+ * Cascade exclusions through dependency relationships.
+ *
+ * When a change is excluded by the filter, any change that depends on it
+ * (via explicit `requires` or via catalog `pg_depend`) should also be excluded.
+ * This runs as a fixpoint loop, bounded by the total number of changes to
+ * guarantee deterministic termination.
+ *
+ * @param filteredChanges - Changes that passed the initial filter
+ * @param allChanges - All changes before filtering
+ * @param catalogDepends - Dependency rows from the target catalog (pg_depend)
+ * @returns The filtered changes with cascading exclusions applied
+ */
+function cascadeExclusions(
+  filteredChanges: Change[],
+  allChanges: Change[],
+  catalogDepends: PgDependRow[],
+): Change[] {
+  // Collect stableIds created by initially-excluded changes
+  const filteredSet = new Set(filteredChanges);
+  const excludedIds = new Set<string>();
+  for (const change of allChanges) {
+    if (!filteredSet.has(change)) {
+      for (const id of change.creates ?? []) {
+        excludedIds.add(id);
+      }
+    }
+  }
+
+  if (excludedIds.size === 0) {
+    return filteredChanges;
+  }
+
+  // Build reverse dependency map: referenced_stable_id -> Set(dependent_stable_ids)
+  const catalogDependents = new Map<string, Set<string>>();
+  for (const dep of catalogDepends) {
+    const existing = catalogDependents.get(dep.referenced_stable_id);
+    if (existing) {
+      existing.add(dep.dependent_stable_id);
+    } else {
+      catalogDependents.set(
+        dep.referenced_stable_id,
+        new Set([dep.dependent_stable_id]),
+      );
+    }
+  }
+
+  // Fixpoint loop: bounded by total changes to guarantee termination.
+  // Each iteration must remove at least one change, otherwise we break.
+  let result = filteredChanges;
+  for (let i = 0; i < allChanges.length; i++) {
+    const beforeLength = result.length;
+    result = result.filter((change) => {
+      // Check explicit requirements: does this change require an excluded id?
+      const requires = change.requires ?? [];
+      if (requires.some((dep) => excludedIds.has(dep))) {
+        for (const id of change.creates ?? []) {
+          excludedIds.add(id);
+        }
+        return false;
+      }
+
+      // Check catalog dependencies: does anything this change creates
+      // depend on an excluded id via pg_depend?
+      const creates = change.creates ?? [];
+      for (const createdId of creates) {
+        for (const excludedId of excludedIds) {
+          const dependents = catalogDependents.get(excludedId);
+          if (dependents?.has(createdId)) {
+            for (const id of creates) {
+              excludedIds.add(id);
+            }
+            return false;
+          }
+        }
+      }
+
+      return true;
+    });
+
+    // No changes removed this iteration — fixpoint reached
+    if (result.length === beforeLength) {
+      break;
+    }
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Plan Building
+// ============================================================================
+
+/**
+ * Build a Plan from sorted changes.
+ */
+function buildPlan(
+  ctx: DiffContext,
+  changes: Change[],
+  options?: CreatePlanOptions,
+  filterDSL?: FilterDSL,
+  serializeDSL?: SerializeDSL,
+  integration?: ResolvedIntegration,
+): Plan {
+  const role = options?.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: 2,
+    source: { fingerprint: fingerprintFrom },
+    target: { fingerprint: fingerprintTo },
+    units: execution.units,
+    sessionStatements: execution.sessionStatements,
+    role,
+    filter: filterDSL,
+    serialize: serializeDSL,
+    risk,
+  };
+}