@supabase/pg-delta 0.0.0 → 1.0.0-alpha.0

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

@@ -0,0 +1,33 @@
+/**
+ * Plan application - execute migration plans against target databases.
+ */
+import { type Sql } from "postgres";
+import type { 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;
+};
+interface ApplyPlanOptions {
+    verifyPostApply?: boolean;
+}
+type ConnectionInput = string | Sql;
+/**
+ * Apply a plan's SQL statements to a target database with integrity checks.
+ * Validates fingerprints before and after application to ensure plan integrity.
+ */
+export declare function applyPlan(plan: Plan, source: ConnectionInput, target: ConnectionInput, options?: ApplyPlanOptions): Promise<ApplyPlanResult>;
+export {};

package/dist/core/plan/apply.js

@@ -0,0 +1,112 @@
+/**
+ * Plan application - execute migration plans against target databases.
+ */
+import postgres, {} from "postgres";
+import { diffCatalogs } from "../catalog.diff.js";
+import { extractCatalog } from "../catalog.model.js";
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
+import { compileFilterDSL } from "../integrations/filter/dsl.js";
+import { postgresConfig } from "../postgres-config.js";
+import { sortChanges } from "../sort/sort-changes.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.
+ * Validates fingerprints before and after application to ensure plan integrity.
+ */
+export async function applyPlan(plan, source, target, options = {}) {
+    if (!plan.statements || plan.statements.length === 0) {
+        return {
+            status: "invalid_plan",
+            message: "Plan contains no SQL statements to execute.",
+        };
+    }
+    const currentSql = typeof source === "string"
+        ? postgres(source, postgresConfig)
+        : source;
+    const desiredSql = typeof target === "string"
+        ? postgres(target, postgresConfig)
+        : target;
+    const shouldCloseCurrent = typeof source === "string";
+    const shouldCloseDesired = typeof target === "string";
+    try {
+        // Recompute stableIds and fingerprints from current and desired catalogs
+        const [currentCatalog, desiredCatalog] = await Promise.all([
+            extractCatalog(currentSql),
+            extractCatalog(desiredSql),
+        ]);
+        const changes = diffCatalogs(currentCatalog, desiredCatalog);
+        const ctx = {
+            mainCatalog: currentCatalog,
+            branchCatalog: desiredCatalog,
+        };
+        // Apply the same filter that was used to create the plan (if any)
+        let filteredChanges = changes;
+        if (plan.filter) {
+            const filterFn = compileFilterDSL(plan.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) {
+            return { status: "already_applied" };
+        }
+        if (fingerprintFrom !== plan.source.fingerprint) {
+            return {
+                status: "fingerprint_mismatch",
+                current: fingerprintFrom,
+                expected: plan.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};`;
+        })();
+        try {
+            await currentSql.unsafe(script);
+        }
+        catch (error) {
+            return { status: "failed", error, script };
+        }
+        const warnings = [];
+        if (options.verifyPostApply !== false) {
+            try {
+                const updatedCatalog = await extractCatalog(currentSql);
+                const updatedFingerprint = hashStableIds(updatedCatalog, stableIds);
+                if (updatedFingerprint !== plan.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)}`);
+            }
+        }
+        // Count only actual changes, excluding session configuration statements
+        const changeStatements = statements.filter((stmt) => !isSessionStatement(stmt));
+        return {
+            status: "applied",
+            statements: changeStatements.length,
+            warnings: warnings.length ? warnings : undefined,
+        };
+    }
+    finally {
+        const closers = [];
+        if (shouldCloseCurrent)
+            closers.push(currentSql.end());
+        if (shouldCloseDesired)
+            closers.push(desiredSql.end());
+        if (closers.length) {
+            await Promise.all(closers);
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Plan creation - the main entry point for creating migration plans.
+ */
+import type { Change } from "../change.types.ts";
+import type { DiffContext } from "../context.ts";
+import type { CreatePlanOptions, Plan } from "./types.ts";
+/**
+ * Create a migration plan by comparing two databases.
+ *
+ * @param fromUrl - Source database connection URL (current state)
+ * @param toUrl - Target database connection URL (desired state)
+ * @param options - Optional configuration
+ * @returns A Plan if there are changes, null if databases are identical
+ */
+import type { Sql } from "postgres";
+type ConnectionInput = string | Sql;
+export declare function createPlan(source: ConnectionInput, target: ConnectionInput, options?: CreatePlanOptions): Promise<{
+    plan: Plan;
+    sortedChanges: Change[];
+    ctx: DiffContext;
+} | null>;
+export {};

package/dist/core/plan/create.js

@@ -0,0 +1,228 @@
+/**
+ * Plan creation - the main entry point for creating migration plans.
+ */
+import { readFile } from "node:fs/promises";
+import postgres from "postgres";
+import { diffCatalogs } from "../catalog.diff.js";
+import { extractCatalog } from "../catalog.model.js";
+import { buildPlanScopeFingerprint, hashStableIds } from "../fingerprint.js";
+import { compileFilterDSL, } from "../integrations/filter/dsl.js";
+import { compileSerializeDSL, } from "../integrations/serialize/dsl.js";
+import { postgresConfig } from "../postgres-config.js";
+import { sortChanges } from "../sort/sort-changes.js";
+import { classifyChangesRisk } from "./risk.js";
+/**
+ * Parse SSL configuration from a PostgreSQL connection URL.
+ * Supports sslmode (require, verify-ca, verify-full, prefer, disable).
+ * Certificates can be provided via:
+ * - Query string parameters (file paths): sslrootcert, sslcert, sslkey (preferred)
+ * - Environment variables (content): PGDELTA_SOURCE_SSLROOTCERT/SSLCERT/SSLKEY or PGDELTA_TARGET_SSLROOTCERT/SSLCERT/SSLKEY
+ * Returns SSL options for the postgres.js library and a cleaned URL without SSL-related query parameters.
+ */
+async function parseSslConfig(url, connectionType) {
+    const urlObj = new URL(url);
+    const sslmode = urlObj.searchParams.get("sslmode");
+    const sslrootcert = urlObj.searchParams.get("sslrootcert");
+    const sslcert = urlObj.searchParams.get("sslcert");
+    const sslkey = urlObj.searchParams.get("sslkey");
+    // Remove SSL-related query parameters since we parse them ourselves
+    urlObj.searchParams.delete("sslmode");
+    urlObj.searchParams.delete("sslrootcert");
+    urlObj.searchParams.delete("sslcert");
+    urlObj.searchParams.delete("sslkey");
+    const cleanedUrl = urlObj.toString();
+    // Handle different SSL modes
+    if (sslmode === "disable") {
+        return { cleanedUrl };
+    }
+    if (sslmode === "require" ||
+        sslmode === "prefer" ||
+        sslmode === "verify-ca" ||
+        sslmode === "verify-full") {
+        const rejectUnauthorized = sslmode === "verify-ca" || sslmode === "verify-full";
+        const ssl = {
+            rejectUnauthorized,
+        };
+        // Helper function to get certificate value: query param (file path) takes precedence over env var (content)
+        const getCertValue = async (queryParam, envVarName) => {
+            // Prefer query parameter (file path)
+            if (queryParam) {
+                try {
+                    return await readFile(queryParam, "utf-8");
+                }
+                catch (error) {
+                    throw new Error(`Failed to read certificate file '${queryParam}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Fallback to environment variable (content)
+            const envValue = process.env[envVarName];
+            return envValue || undefined;
+        };
+        // Get CA certificate (required for verify-ca/verify-full)
+        if (rejectUnauthorized) {
+            const caEnvVar = connectionType === "source"
+                ? "PGDELTA_SOURCE_SSLROOTCERT"
+                : "PGDELTA_TARGET_SSLROOTCERT";
+            const caValue = await getCertValue(sslrootcert, caEnvVar);
+            if (caValue) {
+                ssl.ca = caValue;
+            }
+        }
+        // Get client certificate (optional, for mutual TLS)
+        const certEnvVar = connectionType === "source"
+            ? "PGDELTA_SOURCE_SSLCERT"
+            : "PGDELTA_TARGET_SSLCERT";
+        const certValue = await getCertValue(sslcert, certEnvVar);
+        if (certValue) {
+            ssl.cert = certValue;
+        }
+        // Get client key (optional, for mutual TLS, required if cert is provided)
+        const keyEnvVar = connectionType === "source"
+            ? "PGDELTA_SOURCE_SSLKEY"
+            : "PGDELTA_TARGET_SSLKEY";
+        const keyValue = await getCertValue(sslkey, keyEnvVar);
+        if (keyValue) {
+            ssl.key = keyValue;
+        }
+        // Warn if cert is provided without key (or vice versa)
+        if ((ssl.cert && !ssl.key) || (!ssl.cert && ssl.key)) {
+            throw new Error("Both client certificate and key must be provided together for mutual TLS");
+        }
+        return { ssl, cleanedUrl };
+    }
+    // No sslmode specified or invalid value - no SSL configuration
+    return { cleanedUrl };
+}
+export async function createPlan(source, target, options = {}) {
+    const sourceSslConfig = typeof source === "string" ? await parseSslConfig(source, "source") : null;
+    const targetSslConfig = typeof target === "string" ? await parseSslConfig(target, "target") : null;
+    const sourceSql = typeof source === "string" && sourceSslConfig
+        ? postgres(sourceSslConfig.cleanedUrl, {
+            ...postgresConfig,
+            ...(sourceSslConfig.ssl ? { ssl: sourceSslConfig.ssl } : {}),
+        })
+        : source;
+    const targetSql = typeof target === "string" && targetSslConfig
+        ? postgres(targetSslConfig.cleanedUrl, {
+            ...postgresConfig,
+            ...(targetSslConfig.ssl ? { ssl: targetSslConfig.ssl } : {}),
+        })
+        : target;
+    const shouldCloseFrom = typeof source === "string";
+    const shouldCloseTo = typeof target === "string";
+    try {
+        const [fromCatalog, toCatalog] = await Promise.all([
+            extractCatalog(sourceSql),
+            extractCatalog(targetSql),
+        ]);
+        return buildPlanForCatalogs(fromCatalog, toCatalog, options);
+    }
+    finally {
+        const closers = [];
+        if (shouldCloseFrom)
+            closers.push(sourceSql.end());
+        if (shouldCloseTo)
+            closers.push(targetSql.end());
+        if (closers.length) {
+            await Promise.all(closers);
+        }
+    }
+}
+/**
+ * Build a plan (and supporting artifacts) from already extracted catalogs.
+ */
+function buildPlanForCatalogs(fromCatalog, toCatalog, options = {}) {
+    const changes = diffCatalogs(fromCatalog, toCatalog, {
+        role: options.role,
+    });
+    const filterOption = options.filter;
+    const serializeOption = options.serialize;
+    const ctx = {
+        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 : undefined;
+    const serializeDSL = isSerializeDSL
+        ? serializeOption
+        : undefined;
+    // Build final integration: compile DSL if needed, use functions directly otherwise
+    let finalIntegration;
+    if (filterOption || serializeOption) {
+        finalIntegration = {
+            filter: typeof filterOption === "function"
+                ? filterOption
+                : filterDSL
+                    ? compileFilterDSL(filterDSL)
+                    : undefined,
+            serialize: typeof serializeOption === "function"
+                ? serializeOption
+                : serializeDSL
+                    ? compileSerializeDSL(serializeDSL)
+                    : undefined,
+        };
+    }
+    // Use filter from final integration
+    const filterFn = finalIntegration?.filter;
+    const filteredChanges = filterFn
+        ? changes.filter((change) => filterFn(change))
+        : changes;
+    if (filteredChanges.length === 0) {
+        return null;
+    }
+    const sortedChanges = sortChanges(ctx, filteredChanges);
+    const plan = buildPlan(ctx, sortedChanges, options, filterDSL, serializeDSL, finalIntegration);
+    return { plan, sortedChanges, ctx };
+}
+// ============================================================================
+// Plan Building
+// ============================================================================
+/**
+ * Build a Plan from sorted changes.
+ */
+function buildPlan(ctx, changes, options, filterDSL, serializeDSL, integration) {
+    const role = options?.role;
+    const statements = generateStatements(changes, {
+        integration,
+        role,
+    });
+    const risk = classifyChangesRisk(changes);
+    const { hash: fingerprintFrom, stableIds } = buildPlanScopeFingerprint(ctx.mainCatalog, changes);
+    const fingerprintTo = hashStableIds(ctx.branchCatalog, stableIds);
+    return {
+        version: 1,
+        source: { fingerprint: fingerprintFrom },
+        target: { fingerprint: fingerprintTo },
+        statements,
+        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 "${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/hierarchy.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Hierarchical grouping of changes for tree display.
+ */
+import type { Change } from "../change.types.ts";
+import type { DiffContext } from "../context.ts";
+import type { HierarchicalPlan } from "./types.ts";
+/**
+ * Group changes into a hierarchical structure for tree display.
+ *
+ * This function takes original Change objects (not SerializedChange) to enable
+ * detection of column operations, partitions, and other type-specific details.
+ *
+ * Organizes changes by:
+ * 1. Cluster-wide vs schema-scoped
+ * 2. Schema > Object Type > Object Name
+ * 3. Parent > Child (e.g., Table > Index, Table > Column)
+ * 4. Partitioned Table > Partition
+ */
+export declare function groupChangesHierarchically(ctx: DiffContext, changes: Change[]): HierarchicalPlan;