@supabase/pg-delta 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/core/postgres-config.js

@@ -2,6 +2,7 @@
  * PostgreSQL connection configuration with custom type handlers.
  */
 import { escapeIdentifier, Pool, types } from "pg";
+import { normalizeConnectionUrl } from "./connection-url.js";
 import { parseSslConfig } from "./plan/ssl-config.js";
 // ============================================================================
 // Array Parser
@@ -96,6 +97,89 @@ types.setTypeParser(1016, (val) => 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;
+const DEFAULT_CONNECT_MAX_ATTEMPTS = Number(process.env.PGDELTA_CONNECT_MAX_ATTEMPTS) || 3;
+const DEFAULT_CONNECT_BASE_BACKOFF_MS = Number(process.env.PGDELTA_CONNECT_BASE_BACKOFF_MS) || 250;
+const DEFAULT_CONNECT_MAX_BACKOFF_MS = Number(process.env.PGDELTA_CONNECT_MAX_BACKOFF_MS) || 1_000;
+// PostgreSQL auth-class SQLSTATE codes: not retryable.
+const NON_RETRYABLE_PG_CODES = new Set([
+    "28000", // invalid_authorization_specification
+    "28P01", // invalid_password
+    "28P02", // pgdelta: alias reserved here to future-proof against new auth codes
+]);
+// Non-retryable TLS/SSL markers. The `pg` driver surfaces TLS failures as
+// either plain Node `Error` instances with a code on `ERR_TLS_*` or error
+// messages that include well-known cert/TLS terminology; we match both
+// because node-pg normalises some of these.
+const TLS_MESSAGE_MARKERS = [
+    "self-signed certificate",
+    "self signed certificate",
+    "unable to verify the first certificate",
+    "certificate has expired",
+    "tls",
+    "ssl",
+];
+/**
+ * Return true when `err` represents a transient connect failure that makes
+ * sense to retry with backoff (e.g. refused connections, DNS blips, our own
+ * eager-connect timeout wrapper). Returns false for permanent failures such
+ * as authentication errors, TLS negotiation errors, and `ENOTFOUND`.
+ *
+ * Unknown errors are treated as retryable on purpose: transient-by-default
+ * is safer here because a duplicated retry is strictly cheaper than a spurious
+ * hard failure during catalog extraction.
+ */
+export function isRetryableConnectError(err) {
+    if (!(err instanceof Error))
+        return true;
+    const code = err.code;
+    if (code && NON_RETRYABLE_PG_CODES.has(code))
+        return false;
+    if (code === "ENOTFOUND")
+        return false;
+    if (code && typeof code === "string" && code.startsWith("ERR_TLS")) {
+        return false;
+    }
+    const message = err.message?.toLowerCase() ?? "";
+    // Our own eager-connect timeout wrapper is retryable (flaky network).
+    if (message.includes("timed out after"))
+        return true;
+    for (const marker of TLS_MESSAGE_MARKERS) {
+        if (message.includes(marker))
+            return false;
+    }
+    return true;
+}
+/**
+ * Retry an async `connect` operation with bounded exponential backoff.
+ * Stops immediately on a non-retryable error. On exhausted attempts, throws
+ * the last observed error.
+ *
+ * Exposed for testing — production call sites always go through
+ * {@link createManagedPool}.
+ */
+export async function connectWithRetry(opts) {
+    const maxAttempts = opts.maxAttempts ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+    const baseBackoffMs = opts.baseBackoffMs ?? DEFAULT_CONNECT_BASE_BACKOFF_MS;
+    const maxBackoffMs = opts.maxBackoffMs ?? DEFAULT_CONNECT_MAX_BACKOFF_MS;
+    const isRetryable = opts.isRetryable ?? isRetryableConnectError;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await opts.connect(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt >= maxAttempts || !isRetryable(err)) {
+                throw err;
+            }
+            const backoff = Math.min(baseBackoffMs * 2 ** (attempt - 1), maxBackoffMs);
+            await sleep(backoff);
+        }
+    }
+    // Unreachable: loop either returns or throws.
+    throw lastError;
+}
 /**
  * Create a Pool with custom type handlers and optional event listeners.
  */
@@ -180,7 +264,11 @@ export function createPool(connectionString, options) {
  * to close (via {@link endPool}).
  */
 export async function createManagedPool(url, options) {
-    const sslConfig = await parseSslConfig(url, options?.label ?? "target");
+    // Normalize percent-encoded IPv6 hosts (e.g. `2406%3A...%3Ab3c9`) into the
+    // canonical bracketed form before the URL reaches `parseSslConfig` or pg.
+    // Non-IPv6 hosts are returned unchanged.
+    const normalizedUrl = normalizeConnectionUrl(url);
+    const sslConfig = await parseSslConfig(normalizedUrl, options?.label ?? "target");
     const pool = createPool(sslConfig.cleanedUrl, {
         ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
         onError: (err) => {
@@ -197,15 +285,19 @@ export async function createManagedPool(url, options) {
     });
     // 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.
+    // is not reliably enforced under Bun when SSL negotiation hangs. Transient
+    // failures (refused connections, flaky DNS, our own timeout wrapper) are
+    // retried with bounded exponential backoff; auth/TLS/ENOTFOUND fail fast.
     const label = options?.label ?? "target";
     const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
     try {
-        const client = await Promise.race([
-            pool.connect(),
-            new Promise((_, 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)),
-        ]);
+        const client = await connectWithRetry({
+            connect: () => Promise.race([
+                pool.connect(),
+                new Promise((_, 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,
@@ -72,6 +72,7 @@
     "format-and-lint": "biome check . --error-on-warnings",
     "knip": "knip",
     "pgdelta": "bun src/cli/bin/cli.ts",
+    "sync-base-images": "bun scripts/sync-supabase-base-images.ts",
     "test": "bun scripts/run-tests.ts",
     "test:unit": "bun run test src/",
     "test:integration": "bun run test tests/",

package/src/core/catalog.diff.ts

@@ -1,6 +1,7 @@
 import debug from "debug";
 import type { Catalog } from "./catalog.model.ts";
 import { expandReplaceDependencies } from "./expand-replace-dependencies.ts";
+import { normalizePostDiffCycles } from "./post-diff-cycle-breaking.ts";
 
 const debugCatalog = debug("pg-delta:catalog");
 
@@ -232,11 +233,16 @@ export function diffCatalogs(
     return true;
   });
 
-  filteredChanges = expandReplaceDependencies({
+  const expandedDependencies = expandReplaceDependencies({
     changes: filteredChanges,
     mainCatalog: main,
     branchCatalog: branch,
   });
+  filteredChanges = normalizePostDiffCycles({
+    changes: expandedDependencies.changes,
+    mainCatalog: main,
+    replacedTableIds: expandedDependencies.replacedTableIds,
+  });
 
   debugCatalog(
     "changes catalog diff: %O",

package/src/core/connection-url.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, test } from "bun:test";
+import { isIPv6, normalizeConnectionUrl } from "./connection-url.ts";
+
+describe("isIPv6", () => {
+  describe("accepted", () => {
+    const accepted = [
+      "::",
+      "::1",
+      "1::",
+      "1:2:3:4:5:6:7:8",
+      "2406:da18:243:740f:abda:9a5c:a92d:b3c9",
+      "::ffff:192.0.2.1",
+      "fe80::AbCd",
+      "fe80::1%eth0",
+    ];
+    for (const value of accepted) {
+      test(`accepts "${value}"`, () => {
+        expect(isIPv6(value)).toBe(true);
+      });
+    }
+  });
+
+  describe("rejected", () => {
+    const rejected = [
+      "",
+      "2406:da18:243:740f", // only 4 groups
+      "1:2:3:4:5:6:7:8:9", // 9 groups
+      "1::2::3", // double compression
+      "gggg::1", // invalid hex
+      "1.2.3.4", // pure IPv4
+      "[::1]", // bracketed
+      "localhost",
+      "example.com",
+      ":::", // malformed
+    ];
+    for (const value of rejected) {
+      test(`rejects ${JSON.stringify(value)}`, () => {
+        expect(isIPv6(value)).toBe(false);
+      });
+    }
+  });
+});
+
+describe("normalizeConnectionUrl", () => {
+  describe("normalizes percent-encoded IPv6 hosts", () => {
+    test("full 8-group IPv6 becomes bracketed", () => {
+      const input =
+        "postgresql://user:pass@2406%3Ada18%3A243%3A740f%3Aabda%3A9a5c%3Aa92d%3Ab3c9:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[2406:da18:243:740f:abda:9a5c:a92d:b3c9]:5432/db",
+      );
+    });
+
+    test("compressed ::1 form", () => {
+      const input = "postgresql://user:pass@%3A%3A1:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[::1]:5432/db",
+      );
+    });
+
+    test("IPv4-mapped ::ffff:192.0.2.1", () => {
+      const input = "postgresql://user:pass@%3A%3Affff%3A192.0.2.1:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[::ffff:192.0.2.1]:5432/db",
+      );
+    });
+
+    test("mixed-case percent triples (%3a and %3A)", () => {
+      const input =
+        "postgresql://user:pass@2406%3ada18%3A243%3a740f%3Aabda%3A9a5c%3Aa92d%3Ab3c9:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[2406:da18:243:740f:abda:9a5c:a92d:b3c9]:5432/db",
+      );
+    });
+
+    test("preserves URL-encoded password and query string", () => {
+      const input =
+        "postgresql://user:p%40ss%2Fword@%3A%3A1:5432/db?sslmode=require&application_name=pgdelta";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:p%40ss%2Fword@[::1]:5432/db?sslmode=require&application_name=pgdelta",
+      );
+    });
+
+    test("preserves fragment", () => {
+      const input = "postgresql://user:pass@%3A%3A1:5432/db#frag";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[::1]:5432/db#frag",
+      );
+    });
+
+    test("works without a port", () => {
+      const input = "postgresql://user:pass@%3A%3A1/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user:pass@[::1]/db",
+      );
+    });
+
+    test("works without userinfo", () => {
+      const input = "postgresql://%3A%3A1:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe("postgresql://[::1]:5432/db");
+    });
+
+    test("works with username only (no password)", () => {
+      const input = "postgresql://user@%3A%3A1:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(
+        "postgresql://user@[::1]:5432/db",
+      );
+    });
+  });
+
+  describe("leaves URL unchanged (guardrail)", () => {
+    test("already-bracketed IPv6", () => {
+      const input = "postgresql://user:pass@[::1]:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+
+    test("IPv4 host", () => {
+      const input = "postgresql://user:pass@127.0.0.1:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+
+    test("DNS hostname", () => {
+      const input = "postgresql://user:pass@db.example.com:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+
+    test("percent-encoded colons that do not decode to a valid IPv6 (4 groups only)", () => {
+      const input = "postgresql://user:pass@2406%3Ada18%3A243%3A740f:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+
+    test("non-colon percent-encoded character in hostname", () => {
+      const input = "postgresql://user:pass@host%2Dname:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+
+    test("garbage host `%3A%3Azzz` decodes to `::zzz`, not valid IPv6", () => {
+      const input = "postgresql://user:pass@%3A%3Azzz:5432/db";
+      expect(normalizeConnectionUrl(input)).toBe(input);
+    });
+  });
+});

package/src/core/connection-url.ts

@@ -0,0 +1,82 @@
+/**
+ * Connection URL normalization for pg-delta.
+ *
+ * Auto-normalizes percent-encoded IPv6 hosts in PostgreSQL connection URLs.
+ * A URL like `postgresql://user:pass@2406%3Ada18%3A...%3Ab3c9:5432/db`
+ * becomes `postgresql://user:pass@[2406:da18:...:b3c9]:5432/db` before it
+ * reaches `pg-connection-string` / `pg.Pool`, so DNS resolution sees the
+ * address in its canonical bracketed form.
+ *
+ * Non-IPv6 hosts (IPv4, DNS names, already-bracketed IPv6, partial fragments
+ * that just happen to contain `%3A`) are returned verbatim.
+ */
+
+// IPv6 detection regex vendored from ip-regex (Sindre Sorhus, MIT).
+// https://github.com/sindresorhus/ip-regex
+const v4 =
+  "(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)){3}";
+const v6seg = "[a-fA-F\\d]{1,4}";
+const v6 = `
+(?:
+(?:${v6seg}:){7}(?:${v6seg}|:)|
+(?:${v6seg}:){6}(?:${v4}|:${v6seg}|:)|
+(?:${v6seg}:){5}(?::${v4}|(?::${v6seg}){1,2}|:)|
+(?:${v6seg}:){4}(?:(?::${v6seg}){0,1}:${v4}|(?::${v6seg}){1,3}|:)|
+(?:${v6seg}:){3}(?:(?::${v6seg}){0,2}:${v4}|(?::${v6seg}){1,4}|:)|
+(?:${v6seg}:){2}(?:(?::${v6seg}){0,3}:${v4}|(?::${v6seg}){1,5}|:)|
+(?:${v6seg}:){1}(?:(?::${v6seg}){0,4}:${v4}|(?::${v6seg}){1,6}|:)|
+(?::(?:(?::${v6seg}){0,5}:${v4}|(?::${v6seg}){1,7}|:))
+)(?:%[0-9a-zA-Z]{1,})?
+`
+  .replace(/\s*\/\/.*$/gm, "")
+  .replace(/\n/g, "")
+  .trim();
+
+const V6_EXACT = new RegExp(`^${v6}$`);
+
+/**
+ * Return true if `value` is a valid IPv6 literal in any canonical form:
+ * full 8-group, `::` compression, or IPv4-mapped (`::ffff:1.2.3.4`).
+ * RFC 4007 zone identifiers (`fe80::1%eth0`) are accepted.
+ */
+export function isIPv6(value: string): boolean {
+  return typeof value === "string" && V6_EXACT.test(value);
+}
+
+/**
+ * Normalize a PostgreSQL connection URL so IPv6 hosts reach pg in the
+ * canonical bracketed form.
+ *
+ * If the URL's hostname contains a percent-encoded colon AND the decoded
+ * hostname is a valid IPv6 literal, the hostname is decoded and wrapped in
+ * `[...]`. All other fields (scheme, userinfo, port, path, query, fragment)
+ * are preserved byte-for-byte from the input.
+ *
+ * Any URL whose decoded hostname does not validate as IPv6 is returned
+ * verbatim, so a malformed input will surface its usual downstream error
+ * instead of being silently rewritten.
+ */
+export function normalizeConnectionUrl(url: string): string {
+  const urlObj = new URL(url);
+  // Cheap pre-filter: only look closer if the hostname contains a
+  // percent-encoded colon. Anything else is left entirely untouched.
+  if (!/%3[aA]/.test(urlObj.hostname)) return url;
+
+  const decodedHost = decodeURIComponent(urlObj.hostname);
+  // Authoritative validation: only normalize when the decoded string is a
+  // real IPv6 literal. Rejects partial fragments, random hostnames that
+  // happen to contain `%3A`, and any malformed input.
+  if (!isIPv6(decodedHost)) return url;
+
+  // Preserve username/password/port/path/search/hash exactly as they appear
+  // in the WHATWG URL model (these are returned already percent-encoded).
+  const scheme = `${urlObj.protocol}//`;
+  const auth = urlObj.username
+    ? urlObj.password
+      ? `${urlObj.username}:${urlObj.password}@`
+      : `${urlObj.username}@`
+    : "";
+  const port = urlObj.port ? `:${urlObj.port}` : "";
+  const tail = `${urlObj.pathname}${urlObj.search}${urlObj.hash}`;
+  return `${scheme}${auth}[${decodedHost}]${port}${tail}`;
+}