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

package/src/core/plan/sql-format/wrap.ts

@@ -0,0 +1,196 @@
+import { indentString } from "./format-utils.ts";
+import { isWordChar, walkSql } from "./sql-scanner.ts";
+import type { NormalizedOptions } from "./types.ts";
+
+/**
+ * Keywords that are preferred break points when wrapping long lines.
+ * The wrapper will prefer to break just before one of these keywords
+ * rather than at an arbitrary whitespace position.
+ */
+const WRAP_PREFERRED_KEYWORDS = new Set([
+  "ADD",
+  "CHECK",
+  "CONNECTION",
+  "CONSTRAINT",
+  "DEFERRABLE",
+  "FOREIGN",
+  "HANDLER",
+  "INCLUDE",
+  "INITIALLY",
+  "INLINE",
+  "MATCH",
+  "NOT",
+  "ON",
+  "OPTIONS",
+  "PUBLICATION",
+  "REFERENCES",
+  "REFERENCING",
+  "SET",
+  "USING",
+  "VALIDATOR",
+  "WHERE",
+  "WITH",
+]);
+
+export function wrapStatement(
+  statement: string,
+  options: NormalizedOptions,
+  noWrapPlaceholders: Set<string>,
+): string {
+  const lines = statement.split(/\r?\n/);
+  const wrapped: string[] = [];
+
+  for (const line of lines) {
+    if (line.trim().startsWith("--")) {
+      wrapped.push(line);
+      continue;
+    }
+
+    if (hasNoWrapPlaceholder(line, noWrapPlaceholders)) {
+      wrapped.push(line);
+      continue;
+    }
+
+    wrapped.push(...wrapLine(line, options));
+  }
+
+  return wrapped.join("\n");
+}
+
+function hasNoWrapPlaceholder(
+  line: string,
+  placeholders: Set<string>,
+): boolean {
+  for (const token of placeholders) {
+    if (line.includes(token)) return true;
+  }
+  return false;
+}
+
+function wrapLine(line: string, options: NormalizedOptions): string[] {
+  const maxWidth = options.maxWidth;
+  if (maxWidth <= 0 || line.length <= maxWidth) {
+    return [line];
+  }
+
+  const indentMatch = line.match(/^\s*/);
+  const baseIndent = indentMatch ? indentMatch[0] : "";
+  const continuationIndent = `${baseIndent}${indentString(options.indent)}`;
+
+  let remaining = line;
+  const output: string[] = [];
+
+  while (remaining.length > maxWidth) {
+    const breakpoint = findWrapPosition(remaining, maxWidth);
+    if (breakpoint <= 0) break;
+
+    const head = remaining.slice(0, breakpoint).trimEnd();
+    const tail = remaining.slice(breakpoint).trimStart();
+    output.push(head);
+    const next = `${continuationIndent}${tail}`;
+    if (next.length >= remaining.length) {
+      remaining = next;
+      break;
+    }
+    remaining = next;
+  }
+
+  output.push(remaining);
+  return output;
+}
+
+/** Words that should not be separated from the previous word when wrapping (e.g. CREATE PUBLICATION, COMMENT ON). */
+const KEEP_WITH_PREVIOUS = new Set([
+  "PUBLICATION",
+  "TABLE",
+  "VIEW",
+  "SCHEMA",
+  "INDEX",
+  "OR", // CREATE OR REPLACE
+  "ON", // COMMENT ON
+]);
+
+function getPreviousWord(text: string, beforeIndex: number): string | null {
+  let end = beforeIndex - 1;
+  while (end >= 0 && (text[end] === " " || text[end] === "\t")) {
+    end -= 1;
+  }
+  if (end < 0 || !isWordChar(text[end])) return null;
+  let start = end;
+  while (start > 0 && isWordChar(text[start - 1])) {
+    start -= 1;
+  }
+  return text.slice(start, end + 1).toUpperCase();
+}
+
+function findWrapPosition(text: string, maxWidth: number): number {
+  /** Last whitespace at depth 0 (preferred — avoids splitting parenthesized expressions) */
+  let lastTopLevelWhitespace = -1;
+  /** Last whitespace at any depth (fallback when no depth-0 break exists) */
+  let lastAnyWhitespace = -1;
+  let lastKeywordBoundary = -1;
+  /** First (leftmost) top-level comma within maxWidth — break there so each clause gets its own line */
+  let firstComma = -1;
+
+  // Never break within the leading indent — that would produce an empty head line
+  const contentStart = text.search(/\S/);
+  if (contentStart < 0) return -1; // all whitespace
+
+  walkSql(
+    text,
+    (index, char, depth) => {
+      if (index > maxWidth) return false;
+
+      // Skip positions within leading indent
+      if (index < contentStart) return true;
+
+      // Prefer breaking after the first top-level comma so comma-separated clauses (e.g. publication tables) each get their own line
+      if (char === "," && depth === 0 && firstComma < 0) {
+        firstComma = index + 1; // position after the comma
+      }
+
+      if (char === " " || char === "\t") {
+        lastAnyWhitespace = index;
+        if (depth === 0) {
+          lastTopLevelWhitespace = index;
+        }
+
+        // Check if the next word is a preferred keyword
+        const nextWordStart = index + 1;
+        if (nextWordStart < text.length && isWordChar(text[nextWordStart])) {
+          let wordEnd = nextWordStart + 1;
+          while (wordEnd < text.length && isWordChar(text[wordEnd])) {
+            wordEnd += 1;
+          }
+          const word = text.slice(nextWordStart, wordEnd).toUpperCase();
+          if (WRAP_PREFERRED_KEYWORDS.has(word)) {
+            // Don't break between CREATE and object type, COMMENT and ON, or ALL and ON (GRANT/REVOKE ALL ON)
+            const prev = getPreviousWord(text, index);
+            if (
+              prev !== null &&
+              ((prev === "CREATE" && KEEP_WITH_PREVIOUS.has(word)) ||
+                ((prev === "COMMENT" || prev === "ALL") && word === "ON"))
+            ) {
+              return true;
+            }
+            lastKeywordBoundary = index;
+          }
+        }
+      }
+      return true;
+    },
+    { trackDepth: true },
+  );
+
+  // Prefer: 1) comma, 2) keyword boundary, 3) depth-0 whitespace, 4) any whitespace
+  if (firstComma > 0 && firstComma <= maxWidth) {
+    return firstComma;
+  }
+  if (lastKeywordBoundary > 0 && lastKeywordBoundary <= maxWidth) {
+    return lastKeywordBoundary;
+  }
+  if (lastTopLevelWhitespace > 0) {
+    return lastTopLevelWhitespace;
+  }
+  return lastAnyWhitespace;
+}

package/src/core/plan/sql-format.ts

@@ -0,0 +1,2 @@
+export { formatSqlStatements } from "./sql-format/index.ts";
+export type { SqlFormatOptions } from "./sql-format/types.ts";

package/src/core/plan/ssl-config.ts

@@ -0,0 +1,172 @@
+/**
+ * SSL configuration parsing for PostgreSQL connection URLs.
+ *
+ * Supports sslmode and certificate paths (URL params or env). Used by plan,
+ * apply, and catalog-export when connecting to source/target databases.
+ */
+
+import { readFile } from "node:fs/promises";
+
+/** Parsed SSL options for the pg client plus URL with SSL params stripped (internal). */
+type SslConfig = {
+  ssl?:
+    | boolean
+    | {
+        rejectUnauthorized: boolean;
+        ca?: string;
+        cert?: string;
+        key?: string;
+        /**
+         * Custom server identity check function.
+         * Used to skip hostname verification for verify-ca mode.
+         * Returns undefined to indicate success (no error).
+         */
+        checkServerIdentity?: () => undefined;
+      };
+  cleanedUrl: string;
+};
+
+/**
+ * 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.
+ */
+export async function parseSslConfig(
+  url: string,
+  connectionType: "source" | "target",
+): Promise<SslConfig> {
+  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, ssl: false };
+  }
+
+  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: string | null,
+      envVarName: string,
+    ): Promise<string | undefined> => {
+      // 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;
+    };
+
+    const hasExplicitVerification =
+      sslmode === "verify-ca" || sslmode === "verify-full";
+
+    // Get CA certificate value.
+    // - verify-ca/verify-full: check query param first, then env var
+    // - require/prefer: only check query param (libpq backward compatibility
+    //   requires an explicit root CA *file*, not a global env var)
+    const caEnvVar =
+      connectionType === "source"
+        ? "PGDELTA_SOURCE_SSLROOTCERT"
+        : "PGDELTA_TARGET_SSLROOTCERT";
+    let caValue: string | undefined;
+    if (sslrootcert) {
+      // Explicit file path in query param — always honour it
+      caValue = await getCertValue(sslrootcert, caEnvVar);
+    } else if (hasExplicitVerification) {
+      // verify-ca / verify-full without file path — fall back to env var
+      caValue = await getCertValue(null, caEnvVar);
+    }
+    // require/prefer without sslrootcert: no CA cert, no verification
+
+    // Determine if we should verify the CA chain
+    //   From PostgreSQL docs: "if a root CA file exists, the behavior of sslmode=require
+    //   will be the same as that of verify-ca"
+    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: boolean;
+      ca?: string;
+      cert?: string;
+      key?: string;
+      checkServerIdentity?: () => undefined;
+    } = {
+      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 - explicitly disable SSL
+  return { cleanedUrl, ssl: false };
+}

package/src/core/plan/statements.ts

@@ -0,0 +1,22 @@
+/**
+ * SQL script formatting utilities.
+ */
+
+import { formatSqlStatements, type SqlFormatOptions } from "./sql-format.ts";
+
+const STATEMENT_DELIMITER = ";\n\n";
+
+/**
+ * Format an array of SQL statements into a single script string.
+ * Statements are joined with double newlines and the script ends with a semicolon.
+ */
+export function formatSqlScript(
+  statements: string[],
+  options?: SqlFormatOptions,
+): string {
+  if (statements.length === 0) return "";
+  const formatted = options
+    ? formatSqlStatements(statements, options)
+    : statements;
+  return `${formatted.join(STATEMENT_DELIMITER)};`;
+}

package/src/core/plan/types.ts

@@ -0,0 +1,236 @@
+/**
+ * Type definitions for the Plan module.
+ */
+
+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";
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+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.
+ */
+type ObjectType = Change["objectType"];
+
+/**
+ * Parent types for child objects.
+ */
+export type ParentType = Extract<
+  ObjectType,
+  "table" | "view" | "materialized_view" | "foreign_table"
+>;
+
+/**
+ * A change entry storing both serialized and original change for instanceof checks.
+ */
+export interface ChangeEntry {
+  original: Change;
+}
+
+/**
+ * A group of changes organized by operation.
+ */
+export interface ChangeGroup {
+  create: ChangeEntry[];
+  alter: ChangeEntry[];
+  drop: ChangeEntry[];
+}
+
+/**
+ * Children objects of a table/view (indexes, triggers, policies, etc.)
+ */
+export interface TableChildren {
+  changes: ChangeGroup;
+  columns: ChangeGroup;
+  indexes: ChangeGroup;
+  triggers: ChangeGroup;
+  rules: ChangeGroup;
+  policies: ChangeGroup;
+  /** Partition tables (only for partitioned tables) */
+  partitions: Record<string, TableChildren>;
+}
+
+/**
+ * Children objects of a materialized view
+ */
+export interface MaterializedViewChildren {
+  changes: ChangeGroup;
+  indexes: ChangeGroup;
+}
+
+/**
+ * Type grouping within a schema
+ */
+export interface TypeGroup {
+  enums: ChangeGroup;
+  composites: ChangeGroup;
+  ranges: ChangeGroup;
+  domains: ChangeGroup;
+}
+
+/**
+ * Schema-level grouping of objects
+ */
+export interface SchemaGroup {
+  changes: ChangeGroup;
+  tables: Record<string, TableChildren>;
+  views: Record<string, TableChildren>;
+  materializedViews: Record<string, MaterializedViewChildren>;
+  functions: ChangeGroup;
+  procedures: ChangeGroup;
+  aggregates: ChangeGroup;
+  sequences: ChangeGroup;
+  types: TypeGroup;
+  collations: ChangeGroup;
+  foreignTables: Record<string, TableChildren>;
+}
+
+/**
+ * Cluster-wide objects (no schema)
+ */
+export interface ClusterGroup {
+  roles: ChangeGroup;
+  extensions: ChangeGroup;
+  eventTriggers: ChangeGroup;
+  publications: ChangeGroup;
+  subscriptions: ChangeGroup;
+  foreignDataWrappers: ChangeGroup;
+  servers: ChangeGroup;
+  userMappings: ChangeGroup;
+}
+
+/**
+ * Fully hierarchical plan structure for tree display.
+ */
+export interface HierarchicalPlan {
+  cluster: ClusterGroup;
+  schemas: Record<string, SchemaGroup>;
+}
+
+/**
+ * Plan schema for serialization/deserialization.
+ */
+export const PlanSchema = z.object({
+  version: z.number(),
+  toolVersion: z.string().optional(),
+  source: z.object({
+    fingerprint: z.string(),
+  }),
+  target: z.object({
+    fingerprint: 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
+  risk: z
+    .discriminatedUnion("level", [
+      z.object({
+        level: z.literal("safe"),
+      }),
+      z.object({
+        level: z.literal("data_loss"),
+        statements: z.array(z.string()),
+      }),
+    ])
+    .optional(),
+});
+
+export type SerializedPlan = z.infer<typeof PlanSchema>;
+
+/**
+ * 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 = Omit<
+  SerializedPlan,
+  "units" | "statements" | "sessionStatements"
+> & {
+  units: MigrationUnit[];
+  sessionStatements: string[];
+};
+
+/**
+ * Options for creating a plan.
+ */
+export interface CreatePlanOptions {
+  /** Filter - either FilterDSL (stored in plan) or ChangeFilter function (not stored) */
+  filter?: Integration["filter"];
+  /** Serialize - either SerializeDSL (stored in plan) or ChangeSerializer function (not stored) */
+  serialize?: Integration["serialize"];
+  /** Role to use when executing the migration (SET ROLE will be added to statements) */
+  role?: string;
+  /**
+   * When true, don't subtract privileges covered by ALTER DEFAULT PRIVILEGES
+   * from explicit GRANTs during diffing. Use this for declarative export where
+   * the output must be self-contained and not rely on statement execution order.
+   */
+  skipDefaultPrivilegeSubtraction?: boolean;
+  /**
+   * Number of retry attempts for catalog extractors when `pg_get_*def()`
+   * returns NULL for at least one row (a transient race with concurrent DDL).
+   * Total attempts is `extractRetries + 1`. When undefined, the value is read
+   * from the `PGDELTA_EXTRACT_RETRIES` environment variable, falling back to
+   * a default of 1 (i.e. the first attempt plus one retry, 2 attempts total).
+   */
+  extractRetries?: number;
+}