@supabase/pg-delta 1.0.0-alpha.1 → 1.0.0-alpha.11

package/src/core/postgres-config.ts

@@ -0,0 +1,293 @@
+/**
+ * PostgreSQL connection configuration with custom type handlers.
+ */
+
+import type { ClientBase, PoolClient, PoolConfig } from "pg";
+import { escapeIdentifier, Pool, types } from "pg";
+import { parseSslConfig } from "./plan/ssl-config.ts";
+
+// ============================================================================
+// Array Parser
+// ============================================================================
+
+/**
+ * Parse PostgreSQL array string into JavaScript array.
+ * Handles: {val1,val2}, {NULL,val}, {"quoted,val"}, nested arrays.
+ */
+function parseArray(
+  value: string,
+  parseElement: (val: string) => unknown = (v) => v,
+): unknown[] {
+  if (!value || value === "{}") return [];
+
+  // Remove outer braces
+  const inner = value.slice(1, -1);
+  if (inner === "") return [];
+
+  const result: unknown[] = [];
+  let current = "";
+  let inQuotes = false;
+  let depth = 0;
+
+  for (let i = 0; i < inner.length; i++) {
+    const char = inner[i];
+
+    if (char === '"' && inner[i - 1] !== "\\") {
+      inQuotes = !inQuotes;
+      current += char;
+    } else if (char === "{" && !inQuotes) {
+      depth++;
+      current += char;
+    } else if (char === "}" && !inQuotes) {
+      depth--;
+      current += char;
+    } else if (char === "," && !inQuotes && depth === 0) {
+      result.push(parseElement(current));
+      current = "";
+    } else {
+      current += char;
+    }
+  }
+
+  if (current !== "") {
+    result.push(parseElement(current));
+  }
+
+  return result;
+}
+
+/**
+ * Parse element, handling NULL, quoted strings, and unquoted values.
+ */
+function parseStringElement(val: string): string | null {
+  if (val === "NULL") return null;
+  if (val.startsWith('"') && val.endsWith('"')) {
+    // Unescape quoted string
+    return val.slice(1, -1).replace(/\\(.)/g, "$1");
+  }
+  return val;
+}
+
+function parseIntElement(val: string): number | null {
+  if (val === "NULL") return null;
+  return Number.parseInt(val, 10);
+}
+
+// ============================================================================
+// Type Parsers
+// ============================================================================
+
+// int2vector: "1 2 3" -> [1, 2, 3]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(22, (val: string) => {
+  if (!val || val === "") return [];
+  return val
+    .split(" ")
+    .map(Number)
+    .filter((n: number) => !Number.isNaN(n));
+});
+
+// bigint: string -> BigInt
+types.setTypeParser(20, (val: string) => BigInt(val));
+
+// PostgreSQL array types
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1002, (val: string) => parseArray(val, parseStringElement)); // "char"[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1009, (val: string) => parseArray(val, parseStringElement)); // text[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1015, (val: string) => parseArray(val, parseStringElement)); // varchar[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1005, (val: string) => parseArray(val, parseIntElement)); // int2[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1007, (val: string) => parseArray(val, parseIntElement)); // int4[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1016, (val: string) => parseArray(val, parseIntElement)); // int8[]
+
+const DEFAULT_POOL_MAX = Number(process.env.PGDELTA_POOL_MAX) || 5;
+const DEFAULT_CONNECTION_TIMEOUT_MS =
+  Number(process.env.PGDELTA_CONNECTION_TIMEOUT_MS) || 3_000;
+const DEFAULT_CONNECT_TIMEOUT_MS =
+  Number(process.env.PGDELTA_CONNECT_TIMEOUT_MS) || 2_500;
+
+/**
+ * Options for creating a Pool with event listeners.
+ */
+interface CreatePoolOptions extends Partial<PoolConfig> {
+  /** Called when a new client connects to the pool */
+  onConnect?: (client: ClientBase) => void | Promise<void>;
+  /** Called when an idle client emits an error */
+  onError?: (err: Error, client: PoolClient) => void;
+  /** Called when a client is acquired from the pool */
+  onAcquire?: (client: PoolClient) => void;
+  /** Called when a client is removed from the pool */
+  onRemove?: (client: PoolClient) => void;
+}
+
+/**
+ * Create a Pool with custom type handlers and optional event listeners.
+ */
+export function createPool(
+  connectionString: string,
+  options?: CreatePoolOptions,
+): Pool {
+  const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
+  const pool = new Pool({
+    connectionString,
+    max: DEFAULT_POOL_MAX,
+    connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+    ...config,
+  });
+
+  if (onConnect) {
+    const pendingClientSetup = new WeakMap<PoolClient, Promise<void>>();
+    const waitForClientSetup = async (client: PoolClient) => {
+      const setup = pendingClientSetup.get(client);
+      if (setup) {
+        await setup;
+        return;
+      }
+      throw new Error(
+        "Internal error: pool client was acquired before async onConnect setup was registered. This indicates a bug in the pool wrapper logic; please report it with reproduction steps.",
+      );
+    };
+    const originalConnect = pool.connect.bind(pool);
+
+    pool.on("connect", (client) => {
+      pendingClientSetup.set(
+        client,
+        Promise.resolve().then(() => onConnect(client)),
+      );
+    });
+
+    pool.connect = ((
+      callback?: (
+        err: Error | undefined,
+        client: PoolClient | undefined,
+        release: (err?: Error | boolean) => void,
+      ) => void,
+    ) => {
+      if (!callback) {
+        return originalConnect().then(async (client) => {
+          try {
+            await waitForClientSetup(client);
+            return client;
+          } catch (setupError) {
+            (client as PoolClient).release?.(setupError as Error);
+            throw setupError;
+          }
+        });
+      }
+
+      return originalConnect(async (err, client, release) => {
+        if (err || !client) {
+          callback(err, client, release);
+          return;
+        }
+
+        try {
+          await waitForClientSetup(client);
+          callback(err, client, release);
+        } catch (setupError) {
+          release(setupError as Error);
+          callback(setupError as Error, undefined, () => {});
+        }
+      });
+    }) as Pool["connect"];
+  }
+  if (onError) pool.on("error", onError);
+  if (onAcquire) pool.on("acquire", onAcquire);
+  if (onRemove) pool.on("remove", onRemove);
+
+  return pool;
+}
+
+/**
+ * End a pool and wait for all client sockets to fully close.
+ *
+ * pg-pool's `pool.end()` resolves once clients are removed from its
+ * internal bookkeeping, but the underlying `client.end()` calls (which
+ * close the TCP/TLS sockets) are fired asynchronously *after* that.
+ * If the server (e.g. a test container) is stopped right after
+ * `pool.end()` resolves, the still-open sockets receive an unexpected
+ * RST and emit unhandled "Connection terminated unexpectedly" errors.
+ *
+ * This helper waits for every `remove` event — which pg-pool emits
+ * inside each `client.end()` callback — ensuring all sockets are
+ * truly closed before it resolves.
+ */
+/**
+ * Create a pool from a connection URL with standard session setup:
+ * SSL parsing, search_path isolation, optional SET ROLE, and 57P01 suppression.
+ *
+ * Returns the pool and a `close` function that properly waits for all sockets
+ * to close (via {@link endPool}).
+ */
+export async function createManagedPool(
+  url: string,
+  options?: { role?: string; label?: "source" | "target" },
+): Promise<{ pool: Pool; close: () => Promise<void> }> {
+  const sslConfig = await parseSslConfig(url, options?.label ?? "target");
+  const pool = createPool(sslConfig.cleanedUrl, {
+    ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
+    onError: (err: Error & { code?: string }) => {
+      if (err.code !== "57P01") {
+        console.error("Pool error:", err);
+      }
+    },
+    onConnect: async (client) => {
+      await client.query("SET search_path = ''");
+      if (options?.role) {
+        await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
+      }
+    },
+  });
+
+  // Eagerly validate connectivity so SSL/auth failures surface immediately
+  // instead of hanging on the first real query. node-pg's connectionTimeoutMillis
+  // is not reliably enforced under Bun when SSL negotiation hangs.
+  const label = options?.label ?? "target";
+  const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
+  try {
+    const client = await Promise.race([
+      pool.connect(),
+      new Promise<never>((_, reject) =>
+        setTimeout(
+          () =>
+            reject(
+              new Error(
+                `Connection to ${label} database timed out after ${timeoutMs}ms. ` +
+                  `The server may require SSL, use an invalid certificate, or be unreachable.`,
+              ),
+            ),
+          timeoutMs,
+        ),
+      ),
+    ]);
+    client.release();
+  } catch (err) {
+    await pool.end().catch(() => {});
+    throw err;
+  }
+
+  return { pool, close: () => endPool(pool) };
+}
+
+export function endPool(pool: Pool): Promise<void> {
+  const clientCount = pool.totalCount;
+
+  if (clientCount === 0) {
+    return pool.end();
+  }
+
+  return new Promise<void>((resolve, reject) => {
+    let removed = 0;
+    pool.on("remove", function onRemove() {
+      if (++removed >= clientCount) {
+        pool.removeListener("remove", onRemove);
+        resolve();
+      }
+    });
+    pool.end().catch(reject);
+  });
+}

package/src/core/sort/custom-constraints.ts

@@ -0,0 +1,161 @@
+import type { Change } from "../change.types.ts";
+import { getSchema } from "../change-utils.ts";
+import {
+  GrantRoleDefaultPrivileges,
+  RevokeRoleDefaultPrivileges,
+} from "../objects/role/changes/role.privilege.ts";
+import type { Constraint } from "./types.ts";
+
+/**
+ * Maps object type names to PostgreSQL default privilege objtype codes.
+ * This mirrors the mapping in base.default-privileges.ts.
+ */
+function objectTypeToObjtype(objectType: string): string | null {
+  switch (objectType) {
+    case "table":
+    case "view":
+    case "materialized_view":
+      return "r"; // Relations
+    case "sequence":
+      return "S"; // Sequences
+    case "procedure":
+    case "function":
+    case "aggregate":
+      return "f"; // Functions/routines
+    case "type":
+    case "domain":
+    case "enum":
+    case "range":
+    case "composite_type":
+      return "T"; // Types
+    case "schema":
+      return "n"; // Schemas
+    default:
+      return null;
+  }
+}
+
+/**
+ * A function that generates constraints for a list of changes.
+ * Should be optimized to avoid O(N²) complexity by using lookups/indexing.
+ */
+type ConstraintGenerator = (changes: Change[]) => Constraint[];
+
+/**
+ * Generate constraints to ensure ALTER DEFAULT PRIVILEGES comes before CREATE statements.
+ *
+ * Rules:
+ * - Only applies when the default privilege's schema matches the CREATE statement's schema
+ *   (or if the default privilege is global, applies to all schemas)
+ * - Only applies when the default privilege's objtype matches the CREATE statement's object type
+ * - Excludes CREATE ROLE and CREATE SCHEMA since they are dependencies
+ *   of ALTER DEFAULT PRIVILEGES and must come before it
+ *
+ * implementation: O(N) using schema/objtype indexing.
+ */
+function generateDefaultPrivilegeConstraints(changes: Change[]): Constraint[] {
+  const constraints: Constraint[] = [];
+  const defaultPrivilegeIndices: number[] = [];
+  // Map<objtype_code, Map<schema_name, index[]>>
+  const createsByObjTypeAndSchema = new Map<string, Map<string, number[]>>();
+
+  // Pass 1: Index changes
+  for (let i = 0; i < changes.length; i++) {
+    const change = changes[i];
+
+    // Identify default privilege changes
+    if (
+      change instanceof GrantRoleDefaultPrivileges ||
+      change instanceof RevokeRoleDefaultPrivileges
+    ) {
+      defaultPrivilegeIndices.push(i);
+      continue;
+    }
+
+    // Identify CREATE object changes (excluding role/schema)
+    if (
+      change.operation === "create" &&
+      change.scope === "object" &&
+      change.objectType !== "role" &&
+      change.objectType !== "schema"
+    ) {
+      const objTypeCode = objectTypeToObjtype(change.objectType);
+      if (!objTypeCode) continue;
+
+      const schema = getSchema(change);
+      // Default privileges only apply to schema-contained objects.
+      if (schema) {
+        let schemaMap = createsByObjTypeAndSchema.get(objTypeCode);
+        if (!schemaMap) {
+          schemaMap = new Map();
+          createsByObjTypeAndSchema.set(objTypeCode, schemaMap);
+        }
+
+        let indices = schemaMap.get(schema);
+        if (!indices) {
+          indices = [];
+          schemaMap.set(schema, indices);
+        }
+        indices.push(i);
+      }
+    }
+  }
+
+  // Pass 2: Generate constraints
+  for (const privIndex of defaultPrivilegeIndices) {
+    const privChange = changes[privIndex] as {
+      inSchema: string | null;
+      objtype: string;
+    };
+    const privSchema = privChange.inSchema;
+    const privObjType = privChange.objtype;
+
+    const schemaMap = createsByObjTypeAndSchema.get(privObjType);
+    if (!schemaMap) continue;
+
+    if (privSchema === null) {
+      // Global default privilege: applies to ALL schemas
+      for (const indices of schemaMap.values()) {
+        for (const createIndex of indices) {
+          // (No self-check needed as types differ)
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    } else {
+      // Specific schema: applies only to that schema
+      const indices = schemaMap.get(privSchema);
+      if (indices) {
+        for (const createIndex of indices) {
+          constraints.push({
+            sourceChangeIndex: privIndex,
+            targetChangeIndex: createIndex,
+            source: "custom",
+          });
+        }
+      }
+    }
+  }
+
+  return constraints;
+}
+
+/**
+ * All custom constraint generators.
+ */
+const customConstraintGenerators: ConstraintGenerator[] = [
+  generateDefaultPrivilegeConstraints,
+];
+
+/**
+ * Generate Constraints from custom constraint generators.
+ *
+ * Iterates through registered generators to produce constraints.
+ * Generators should be optimized (e.g. using indexing) to avoid O(N²) complexity.
+ */
+export function generateCustomConstraints(changes: Change[]): Constraint[] {
+  return customConstraintGenerators.flatMap((generate) => generate(changes));
+}

package/src/core/sort/debug-visualization.ts

@@ -0,0 +1,239 @@
+import debug from "debug";
+import type { Change } from "../change.types.ts";
+import { findCycle } from "./topological-sort.ts";
+import type { Constraint, GraphData, PgDependRow } from "./types.ts";
+
+const debugGraph = debug("pg-delta:graph");
+
+/**
+ * Generate a Mermaid diagram representation of the dependency graph for debugging.
+ */
+function generateMermaidDiagram(
+  phaseChanges: Change[],
+  graphData: GraphData,
+  edges: Array<[number, number]>,
+  requirementSets: Array<Set<string>>,
+  dependenciesByReferencedId: Map<string, Set<string>>,
+): string {
+  const cycleNodeIndexes = findCycle(phaseChanges.length, edges) ?? [];
+  const mermaidLines: string[] = [];
+  mermaidLines.push("flowchart TD");
+
+  // Add nodes
+  for (let changeIndex = 0; changeIndex < phaseChanges.length; changeIndex++) {
+    const changeInstance = phaseChanges[changeIndex];
+    const changeClassName = changeInstance?.constructor?.name ?? "Change";
+    const truncatedCreates = Array.isArray(changeInstance.creates)
+      ? changeInstance.creates.slice(0, 3)
+      : [];
+    const nodeLabel = `${changeIndex}: ${changeClassName} ${
+      truncatedCreates.length > 0 ? `[${truncatedCreates.join(",")}]` : ""
+    }`.replaceAll('"', "'");
+    mermaidLines.push(`  n${changeIndex}["${nodeLabel}"]`);
+  }
+
+  // Add edges with descriptions
+  for (const [sourceIndex, targetIndex] of edges) {
+    const edgeDescription = describeEdge(
+      sourceIndex,
+      targetIndex,
+      graphData,
+      requirementSets,
+      dependenciesByReferencedId,
+    ).replaceAll('"', "'");
+    if (edgeDescription.length > 0) {
+      mermaidLines.push(
+        `  n${sourceIndex} -- "${edgeDescription}" --> n${targetIndex}`,
+      );
+    } else {
+      mermaidLines.push(`  n${sourceIndex} --> n${targetIndex}`);
+    }
+  }
+
+  // Highlight cycles if any
+  if (cycleNodeIndexes.length > 0) {
+    mermaidLines.push(
+      "  classDef cycleNode fill:#ffe6e6,stroke:#ff4d4f,stroke-width:2px;",
+    );
+    for (const nodeIndex of cycleNodeIndexes) {
+      mermaidLines.push(`  class n${nodeIndex} cycleNode;`);
+    }
+
+    const cycleEdges: Array<[number, number]> = [];
+    for (
+      let cycleIndex = 0;
+      cycleIndex < cycleNodeIndexes.length;
+      cycleIndex++
+    ) {
+      const sourceIndex = cycleNodeIndexes[cycleIndex];
+      const targetIndex =
+        cycleNodeIndexes[(cycleIndex + 1) % cycleNodeIndexes.length];
+      cycleEdges.push([sourceIndex, targetIndex]);
+    }
+
+    let edgeIndex = 0;
+    for (const [sourceIndex, targetIndex] of edges) {
+      const edgeBelongsToCycle = cycleEdges.some(
+        ([cycleSourceIndex, cycleTargetIndex]) =>
+          cycleSourceIndex === sourceIndex && cycleTargetIndex === targetIndex,
+      );
+      if (edgeBelongsToCycle) {
+        mermaidLines.push(
+          `  linkStyle ${edgeIndex} stroke:#ff4d4f,stroke-width:2px;`,
+        );
+      }
+      edgeIndex++;
+    }
+  }
+
+  return mermaidLines.join("\n");
+}
+
+/**
+ * Build requirementSets from explicit requirements and constraints (for debug visualization).
+ *
+ * This reconstructs what requirements were inferred from constraints by looking at
+ * the constraints that were processed. Only processes catalog/explicit constraints,
+ * as custom constraints don't affect requirement sets.
+ */
+function buildRequirementSets(
+  explicitRequirementSets: Array<Set<string>>,
+  constraints: Constraint[],
+  changeIndexesByCreatedId: Map<string, Set<number>>,
+  _changeIndexesByExplicitRequirementId: Map<string, Set<number>>,
+): Array<Set<string>> {
+  // Start with explicit requirements
+  const requirementSets: Array<Set<string>> = explicitRequirementSets.map(
+    (explicitRequirements) => new Set<string>(explicitRequirements),
+  );
+
+  // Add requirements inferred from catalog/explicit constraints
+  // For each constraint with a reason, if the referenced ID is created by some change,
+  // then the target change requires the referenced ID
+  for (const constraint of constraints) {
+    // Only process catalog/explicit constraints (custom constraints don't affect requirements)
+    if (constraint.source === "custom" || !constraint.reason) continue;
+
+    const referencedProducers = changeIndexesByCreatedId.get(
+      constraint.reason.referencedStableId,
+    );
+    if (!referencedProducers || referencedProducers.size === 0) continue;
+
+    // The target change requires the referenced stable ID
+    requirementSets[constraint.targetChangeIndex].add(
+      constraint.reason.referencedStableId,
+    );
+  }
+
+  return requirementSets;
+}
+
+/**
+ * Build dependenciesByReferencedId from dependency rows (for debug visualization).
+ */
+function buildDependenciesByReferencedId(
+  dependencyRows: PgDependRow[],
+): Map<string, Set<string>> {
+  const dependenciesByReferencedId = new Map<string, Set<string>>();
+  for (const dependencyRow of dependencyRows) {
+    // Filter out unknown dependencies
+    if (
+      dependencyRow.referenced_stable_id.startsWith("unknown:") ||
+      dependencyRow.dependent_stable_id.startsWith("unknown:")
+    ) {
+      continue;
+    }
+
+    let dependentIds = dependenciesByReferencedId.get(
+      dependencyRow.referenced_stable_id,
+    );
+    if (!dependentIds) {
+      dependentIds = new Set<string>();
+      dependenciesByReferencedId.set(
+        dependencyRow.referenced_stable_id,
+        dependentIds,
+      );
+    }
+    dependentIds.add(dependencyRow.dependent_stable_id);
+  }
+  return dependenciesByReferencedId;
+}
+
+/**
+ * Describe an edge in the dependency graph for visualization.
+ */
+function describeEdge(
+  sourceIndex: number,
+  targetIndex: number,
+  graphData: GraphData,
+  requirementSets: Array<Set<string>>,
+  dependenciesByReferencedId: Map<string, Set<string>>,
+): string {
+  // Check if target explicitly requires something created by source
+  for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+    if (requirementSets[targetIndex].has(createdId)) {
+      return `${createdId} -> (requires)`;
+    }
+  }
+
+  // Check pg_depend relationships
+  for (const createdId of graphData.createdStableIdSets[sourceIndex]) {
+    const outgoingDependencies = dependenciesByReferencedId.get(createdId);
+    if (!outgoingDependencies) continue;
+
+    // Check if target requires this ID
+    for (const requiredId of requirementSets[targetIndex]) {
+      if (outgoingDependencies.has(requiredId)) {
+        return `${createdId} -> ${requiredId}`;
+      }
+    }
+
+    // Check if target creates something that depends on this ID
+    for (const targetCreatedId of graphData.createdStableIdSets[targetIndex]) {
+      if (outgoingDependencies.has(targetCreatedId)) {
+        return `${createdId} -> ${targetCreatedId}`;
+      }
+    }
+  }
+
+  return "";
+}
+
+/**
+ * Print debug information about the dependency graph.
+ *
+ * Builds debug-only data structures (requirementSets, dependenciesByReferencedId) just-in-time.
+ */
+export function printDebugGraph(
+  phaseChanges: Change[],
+  graphData: GraphData,
+  edges: Array<[number, number]>,
+  dependencyRows: PgDependRow[],
+  constraints: Constraint[],
+): void {
+  try {
+    // Build debug-only data structures just-in-time
+    const requirementSets = buildRequirementSets(
+      graphData.explicitRequirementSets,
+      constraints,
+      graphData.changeIndexesByCreatedId,
+      graphData.changeIndexesByExplicitRequirementId,
+    );
+    const dependenciesByReferencedId =
+      buildDependenciesByReferencedId(dependencyRows);
+
+    const mermaidDiagram = generateMermaidDiagram(
+      phaseChanges,
+      graphData,
+      edges,
+      requirementSets,
+      dependenciesByReferencedId,
+    );
+    debugGraph(
+      "\n==== Mermaid (cycle detected) ====\n%s\n==== end ====",
+      mermaidDiagram,
+    );
+  } catch (_error) {
+    // ignore debug printing errors
+  }
+}