@supabase/pg-delta 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/core/plan/create.js

@@ -1,177 +1,83 @@
 /**
  * Plan creation - the main entry point for creating migration plans.
  */
-import { readFile } from "node:fs/promises";
 import { escapeIdentifier } from "pg";
 import { diffCatalogs } from "../catalog.diff.js";
-import { extractCatalog } from "../catalog.model.js";
+import { createEmptyCatalog, 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 { createPool } from "../postgres-config.js";
+import { resolveIntegration, } from "../integrations/integration.types.js";
+import { createManagedPool, endPool } 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.
+ * 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.
  */
-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") {
-        // 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 value (needed for verify-ca, verify-full, and libpq compatibility with require/prefer)
-        const caEnvVar = connectionType === "source"
-            ? "PGDELTA_SOURCE_SSLROOTCERT"
-            : "PGDELTA_TARGET_SSLROOTCERT";
-        const caValue = await getCertValue(sslrootcert, caEnvVar);
-        // Determine if we should verify the CA chain
-        // - verify-ca and verify-full: always verify CA
-        // - require/prefer with CA cert provided: verify CA (libpq backward compatibility)
-        //   From PostgreSQL docs: "if a root CA file exists, the behavior of sslmode=require
-        //   will be the same as that of verify-ca"
-        const hasExplicitVerification = sslmode === "verify-ca" || sslmode === "verify-full";
-        const hasLibpqCompatibility = (sslmode === "require" || sslmode === "prefer") && caValue !== undefined;
-        const shouldVerifyCa = hasExplicitVerification || hasLibpqCompatibility;
-        // Determine if we should verify hostname
-        // - verify-full: verify both CA and hostname
-        // - verify-ca: verify CA only (skip hostname)
-        // - require/prefer with CA (libpq compat): behaves like verify-ca (skip hostname)
-        const shouldVerifyHostname = sslmode === "verify-full";
-        const ssl = {
-            rejectUnauthorized: shouldVerifyCa,
-        };
-        // Add CA certificate if verifying
-        if (shouldVerifyCa && caValue) {
-            ssl.ca = caValue;
-        }
-        // For verify-ca and libpq compatibility mode: skip hostname verification
-        // This matches PostgreSQL semantics where verify-ca only checks the CA chain
-        if (shouldVerifyCa && !shouldVerifyHostname) {
-            ssl.checkServerIdentity = () => undefined;
-        }
-        // 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 };
+function isResolvedCatalog(input) {
+    return (typeof input === "object" &&
+        input !== null &&
+        typeof input.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, target, options = {}) {
-    let sourcePool;
-    let targetPool;
-    let shouldCloseSource = false;
-    let shouldCloseTarget = false;
-    // Suppress expected shutdown errors from idle pool connections (57P01 = admin_shutdown)
-    const onError = (err) => {
-        if (err.code !== "57P01") {
-            console.error("Pool error:", err);
+    const resolvePool = async (input, label) => {
+        if (typeof input === "string") {
+            const managed = await createManagedPool(input, {
+                role: options.role,
+                label,
+            });
+            return { pool: managed.pool, shouldClose: true };
         }
+        return { pool: input, shouldClose: false };
     };
-    if (typeof source === "string") {
-        const sslConfig = await parseSslConfig(source, "source");
-        sourcePool = createPool(sslConfig.cleanedUrl, {
-            ...(sslConfig.ssl ? { ssl: sslConfig.ssl } : {}),
-            onError,
-            onConnect: async (client) => {
-                // Force fully qualified names in catalog queries
-                await client.query("SET search_path = ''");
-                if (options.role) {
-                    await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
-                }
-            },
-        });
-        shouldCloseSource = true;
-    }
-    else {
-        sourcePool = source;
-    }
-    if (typeof target === "string") {
-        const sslConfig = await parseSslConfig(target, "target");
-        targetPool = createPool(sslConfig.cleanedUrl, {
-            ...(sslConfig.ssl ? { ssl: sslConfig.ssl } : {}),
-            onError,
-            onConnect: async (client) => {
-                // Force fully qualified names in catalog queries
-                await client.query("SET search_path = ''");
-                if (options.role) {
-                    await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
-                }
-            },
-        });
-        shouldCloseTarget = true;
-    }
-    else {
-        targetPool = target;
-    }
+    /**
+     * Resolve a CatalogInput to a Catalog, tracking pools that need cleanup.
+     */
+    const resolveCatalog = async (input, label, pools) => {
+        if (isResolvedCatalog(input)) {
+            return input;
+        }
+        const resolved = await resolvePool(input, label);
+        pools.push(resolved);
+        return extractCatalog(resolved.pool);
+    };
+    const pools = [];
     try {
-        const [fromCatalog, toCatalog] = await Promise.all([
-            extractCatalog(sourcePool),
-            extractCatalog(targetPool),
-        ]);
+        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 = [];
-        if (shouldCloseSource)
-            closers.push(sourcePool.end());
-        if (shouldCloseTarget)
-            closers.push(targetPool.end());
-        if (closers.length) {
+        const closers = pools
+            .filter((p) => p.shouldClose)
+            .map((p) => endPool(p.pool));
+        if (closers.length)
             await Promise.all(closers);
-        }
     }
 }
 /**
@@ -180,6 +86,7 @@ export async function createPlan(source, target, options = {}) {
 function buildPlanForCatalogs(fromCatalog, toCatalog, options = {}) {
     const changes = diffCatalogs(fromCatalog, toCatalog, {
         role: options.role,
+        skipDefaultPrivilegeSubtraction: options.skipDefaultPrivilegeSubtraction,
     });
     const filterOption = options.filter;
     const serializeOption = options.serialize;
@@ -195,26 +102,24 @@ function buildPlanForCatalogs(fromCatalog, toCatalog, options = {}) {
         ? 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,
-        };
-    }
+    const finalIntegration = resolveIntegration({
+        filter: filterOption,
+        serialize: serializeOption,
+    });
     // Use filter from final integration
     const filterFn = finalIntegration?.filter;
-    const filteredChanges = filterFn
+    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?.cascade === true
+        : true;
+    if (filterFn && filteredChanges.length < changes.length && shouldCascade) {
+        filteredChanges = cascadeExclusions(filteredChanges, changes, toCatalog.depends);
+    }
     if (filteredChanges.length === 0) {
         return null;
     }
@@ -223,6 +128,84 @@ function buildPlanForCatalogs(fromCatalog, toCatalog, options = {}) {
     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, allChanges, catalogDepends) {
+    // Collect stableIds created by initially-excluded changes
+    const filteredSet = new Set(filteredChanges);
+    const excludedIds = new Set();
+    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();
+    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
 // ============================================================================
 /**

package/dist/core/plan/serialize.js

@@ -139,10 +139,22 @@ export function getParentInfo(change) {
             const parentType = change.index.table_relkind === "m" ? "materialized_view" : "table";
             return { type: parentType, name: change.index.table_name };
         }
-        case "trigger":
-            return { type: "table", name: change.trigger.table_name };
-        case "rule":
-            return { type: "table", name: change.rule.table_name };
+        case "trigger": {
+            const parentType = change.trigger.table_relkind === "v"
+                ? "view"
+                : change.trigger.table_relkind === "m"
+                    ? "materialized_view"
+                    : "table";
+            return { type: parentType, name: change.trigger.table_name };
+        }
+        case "rule": {
+            const parentType = change.rule.relation_kind === "v"
+                ? "view"
+                : change.rule.relation_kind === "m"
+                    ? "materialized_view"
+                    : "table";
+            return { type: parentType, name: change.rule.table_name };
+        }
         case "rls_policy":
             return { type: "table", name: change.policy.table_name };
         case "aggregate":

package/dist/core/plan/sql-format/constants.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedOptions } from "./types.ts";
+export declare const DEFAULT_OPTIONS: NormalizedOptions;

package/dist/core/plan/sql-format/constants.js

@@ -0,0 +1,11 @@
+export const DEFAULT_OPTIONS = {
+    keywordCase: "preserve",
+    indent: 2,
+    maxWidth: 100,
+    commaStyle: "trailing",
+    alignColumns: true,
+    alignKeyValues: true,
+    preserveRoutineBodies: true,
+    preserveViewBodies: true,
+    preserveRuleBodies: true,
+};

package/dist/core/plan/sql-format/fixtures.d.ts

@@ -0,0 +1,2 @@
+import type { SqlFormatOptions } from "../sql-format.ts";
+export declare function renderScript(options?: SqlFormatOptions): string;