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

package/dist/core/postgres-config.d.ts

@@ -45,8 +45,38 @@ interface CreatePoolOptions extends Partial<PoolConfig> {
 }
 /**
  * Create a Pool with custom type handlers and optional event listeners.
+ *
+ * `connectionString` may be `undefined` when the caller needs pg to rely on
+ * explicit `host`/`port`/`user`/... fields from `options` instead — notably
+ * the bracketed-IPv6 workaround in {@link poolConfigFromUrl}, where passing
+ * the connection string would cause `pg-connection-string` to re-inject the
+ * bracketed host that breaks `getaddrinfo`.
+ */
+export declare function createPool(connectionString: string | undefined, options?: CreatePoolOptions): Pool;
+/**
+ * Build a pg {@link PoolConfig} from a cleaned connection URL.
+ *
+ * For most URLs this just returns `{ connectionString }` and pg does its
+ * normal parsing. But for URLs whose hostname is a bracketed IPv6 literal
+ * (e.g. `postgresql://user@[::1]:5432/db`, as produced by
+ * {@link normalizeConnectionUrl}), we expand the URL into explicit
+ * `host`/`port`/`user`/`password`/`database` fields with a **bare** IPv6
+ * host — no brackets.
+ *
+ * This works around a `pg-connection-string` quirk: its parser sets
+ * `config.host` to the WHATWG `URL.hostname`, which keeps the surrounding
+ * `[...]` for IPv6 literals. That bracketed value is then passed verbatim to
+ * `getaddrinfo`, which rejects it with `ENOTFOUND`. Since
+ * `pg`'s connection-parameters module does
+ * `Object.assign({}, config, parse(connectionString))`, any `host` we pass
+ * alongside `connectionString` gets clobbered — so we drop `connectionString`
+ * entirely on this path and hand pg the parsed fields directly.
+ *
+ * Remaining query parameters (e.g. `application_name`, `options`,
+ * `connect_timeout`) are forwarded as top-level config keys, mirroring how
+ * `pg-connection-string` would normally surface them.
  */
-export declare function createPool(connectionString: string, options?: CreatePoolOptions): Pool;
+export declare function poolConfigFromUrl(cleanedUrl: string): PoolConfig;
 /**
  * End a pool and wait for all client sockets to fully close.
  *

package/dist/core/postgres-config.js

@@ -182,11 +182,17 @@ export async function connectWithRetry(opts) {
 }
 /**
  * Create a Pool with custom type handlers and optional event listeners.
+ *
+ * `connectionString` may be `undefined` when the caller needs pg to rely on
+ * explicit `host`/`port`/`user`/... fields from `options` instead — notably
+ * the bracketed-IPv6 workaround in {@link poolConfigFromUrl}, where passing
+ * the connection string would cause `pg-connection-string` to re-inject the
+ * bracketed host that breaks `getaddrinfo`.
  */
 export function createPool(connectionString, options) {
     const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
     const pool = new Pool({
-        connectionString,
+        ...(connectionString ? { connectionString } : {}),
         max: DEFAULT_POOL_MAX,
         connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
         ...config,
@@ -242,6 +248,51 @@ export function createPool(connectionString, options) {
         pool.on("remove", onRemove);
     return pool;
 }
+/**
+ * Build a pg {@link PoolConfig} from a cleaned connection URL.
+ *
+ * For most URLs this just returns `{ connectionString }` and pg does its
+ * normal parsing. But for URLs whose hostname is a bracketed IPv6 literal
+ * (e.g. `postgresql://user@[::1]:5432/db`, as produced by
+ * {@link normalizeConnectionUrl}), we expand the URL into explicit
+ * `host`/`port`/`user`/`password`/`database` fields with a **bare** IPv6
+ * host — no brackets.
+ *
+ * This works around a `pg-connection-string` quirk: its parser sets
+ * `config.host` to the WHATWG `URL.hostname`, which keeps the surrounding
+ * `[...]` for IPv6 literals. That bracketed value is then passed verbatim to
+ * `getaddrinfo`, which rejects it with `ENOTFOUND`. Since
+ * `pg`'s connection-parameters module does
+ * `Object.assign({}, config, parse(connectionString))`, any `host` we pass
+ * alongside `connectionString` gets clobbered — so we drop `connectionString`
+ * entirely on this path and hand pg the parsed fields directly.
+ *
+ * Remaining query parameters (e.g. `application_name`, `options`,
+ * `connect_timeout`) are forwarded as top-level config keys, mirroring how
+ * `pg-connection-string` would normally surface them.
+ */
+export function poolConfigFromUrl(cleanedUrl) {
+    const urlObj = new URL(cleanedUrl);
+    if (!urlObj.hostname.startsWith("[")) {
+        return { connectionString: cleanedUrl };
+    }
+    const config = {
+        host: urlObj.hostname.slice(1, -1),
+    };
+    if (urlObj.port)
+        config.port = Number(urlObj.port);
+    if (urlObj.username)
+        config.user = decodeURIComponent(urlObj.username);
+    if (urlObj.password)
+        config.password = decodeURIComponent(urlObj.password);
+    if (urlObj.pathname.length > 1) {
+        config.database = decodeURIComponent(urlObj.pathname.slice(1));
+    }
+    for (const [key, value] of urlObj.searchParams) {
+        config[key] = value;
+    }
+    return config;
+}
 /**
  * End a pool and wait for all client sockets to fully close.
  *
@@ -269,7 +320,11 @@ export async function createManagedPool(url, options) {
     // Non-IPv6 hosts are returned unchanged.
     const normalizedUrl = normalizeConnectionUrl(url);
     const sslConfig = await parseSslConfig(normalizedUrl, options?.label ?? "target");
-    const pool = createPool(sslConfig.cleanedUrl, {
+    // Expand bracketed-IPv6 URLs into explicit pg fields so the brackets never
+    // reach `getaddrinfo` — see `poolConfigFromUrl` for the full rationale.
+    const connectionConfig = poolConfigFromUrl(sslConfig.cleanedUrl);
+    const pool = createPool(connectionConfig.connectionString, {
+        ...connectionConfig,
         ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
         onError: (err) => {
             if (err.code !== "57P01") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.16",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,

package/src/core/postgres-config.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import {
   connectWithRetry,
   isRetryableConnectError,
+  poolConfigFromUrl,
 } from "./postgres-config.ts";
 
 function makeError(message: string, code?: string): Error {
@@ -239,3 +240,97 @@ describe("connectWithRetry", () => {
     expect(attempts).toBe(1);
   });
 });
+
+describe("poolConfigFromUrl", () => {
+  describe("non-IPv6 URLs pass through as connectionString", () => {
+    test("DNS hostname", () => {
+      const url = "postgresql://user:pass@db.example.com:5432/mydb";
+      expect(poolConfigFromUrl(url)).toEqual({ connectionString: url });
+    });
+
+    test("IPv4 host", () => {
+      const url = "postgresql://user:pass@127.0.0.1:5432/mydb";
+      expect(poolConfigFromUrl(url)).toEqual({ connectionString: url });
+    });
+
+    test("DNS hostname with query params", () => {
+      const url =
+        "postgresql://user:pass@db.example.com:5432/mydb?application_name=test";
+      expect(poolConfigFromUrl(url)).toEqual({ connectionString: url });
+    });
+  });
+
+  describe("bracketed IPv6 URLs expand to explicit fields with no brackets", () => {
+    test("full 8-group IPv6 — host has no brackets and no connectionString", () => {
+      const url =
+        "postgresql://user:pass@[2600:1f16:1cd0:3340:f92e:f4cb:7a52:10a1]:5432/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.connectionString).toBeUndefined();
+      expect(config.host).toBe("2600:1f16:1cd0:3340:f92e:f4cb:7a52:10a1");
+      expect(config.port).toBe(5432);
+      expect(config.user).toBe("user");
+      expect(config.password).toBe("pass");
+      expect(config.database).toBe("mydb");
+    });
+
+    test("compressed ::1 form", () => {
+      const url = "postgresql://user:pass@[::1]:5432/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).toBe("::1");
+      expect(config.port).toBe(5432);
+    });
+
+    test("host bracket strip survives percent-decoded username/password", () => {
+      const url = "postgresql://user:p%40ss%2Fword@[::1]:5432/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).toBe("::1");
+      expect(config.user).toBe("user");
+      expect(config.password).toBe("p@ss/word");
+    });
+
+    test("works without port", () => {
+      const url = "postgresql://user:pass@[::1]/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).toBe("::1");
+      expect(config.port).toBeUndefined();
+    });
+
+    test("works without database (pathname='/')", () => {
+      const url = "postgresql://user:pass@[::1]:5432/";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).toBe("::1");
+      expect(config.database).toBeUndefined();
+    });
+
+    test("works without userinfo", () => {
+      const url = "postgresql://[::1]:5432/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).toBe("::1");
+      expect(config.user).toBeUndefined();
+      expect(config.password).toBeUndefined();
+    });
+
+    test("query params are forwarded as top-level config keys", () => {
+      const url =
+        "postgresql://user:pass@[::1]:5432/mydb?application_name=pgdelta&connect_timeout=5";
+      const config = poolConfigFromUrl(url) as unknown as Record<
+        string,
+        unknown
+      >;
+      expect(config.application_name).toBe("pgdelta");
+      expect(config.connect_timeout).toBe("5");
+      expect(config.host).toBe("::1");
+    });
+
+    test("IPv4-mapped IPv6 is stripped of brackets (WHATWG canonicalisation is fine)", () => {
+      // WHATWG URL canonicalises `::ffff:192.0.2.1` to `::ffff:c000:201`;
+      // either form resolves to the same IPv6 address, and the point of this
+      // test is purely that no brackets escape to pg.
+      const url = "postgresql://user:pass@[::ffff:192.0.2.1]:5432/mydb";
+      const config = poolConfigFromUrl(url);
+      expect(config.host).not.toContain("[");
+      expect(config.host).not.toContain("]");
+      expect(config.host).toBe("::ffff:c000:201");
+    });
+  });
+});

package/src/core/postgres-config.ts

@@ -225,14 +225,20 @@ interface CreatePoolOptions extends Partial<PoolConfig> {
 
 /**
  * Create a Pool with custom type handlers and optional event listeners.
+ *
+ * `connectionString` may be `undefined` when the caller needs pg to rely on
+ * explicit `host`/`port`/`user`/... fields from `options` instead — notably
+ * the bracketed-IPv6 workaround in {@link poolConfigFromUrl}, where passing
+ * the connection string would cause `pg-connection-string` to re-inject the
+ * bracketed host that breaks `getaddrinfo`.
  */
 export function createPool(
-  connectionString: string,
+  connectionString: string | undefined,
   options?: CreatePoolOptions,
 ): Pool {
   const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
   const pool = new Pool({
-    connectionString,
+    ...(connectionString ? { connectionString } : {}),
     max: DEFAULT_POOL_MAX,
     connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
     ...config,
@@ -301,6 +307,50 @@ export function createPool(
   return pool;
 }
 
+/**
+ * Build a pg {@link PoolConfig} from a cleaned connection URL.
+ *
+ * For most URLs this just returns `{ connectionString }` and pg does its
+ * normal parsing. But for URLs whose hostname is a bracketed IPv6 literal
+ * (e.g. `postgresql://user@[::1]:5432/db`, as produced by
+ * {@link normalizeConnectionUrl}), we expand the URL into explicit
+ * `host`/`port`/`user`/`password`/`database` fields with a **bare** IPv6
+ * host — no brackets.
+ *
+ * This works around a `pg-connection-string` quirk: its parser sets
+ * `config.host` to the WHATWG `URL.hostname`, which keeps the surrounding
+ * `[...]` for IPv6 literals. That bracketed value is then passed verbatim to
+ * `getaddrinfo`, which rejects it with `ENOTFOUND`. Since
+ * `pg`'s connection-parameters module does
+ * `Object.assign({}, config, parse(connectionString))`, any `host` we pass
+ * alongside `connectionString` gets clobbered — so we drop `connectionString`
+ * entirely on this path and hand pg the parsed fields directly.
+ *
+ * Remaining query parameters (e.g. `application_name`, `options`,
+ * `connect_timeout`) are forwarded as top-level config keys, mirroring how
+ * `pg-connection-string` would normally surface them.
+ */
+export function poolConfigFromUrl(cleanedUrl: string): PoolConfig {
+  const urlObj = new URL(cleanedUrl);
+  if (!urlObj.hostname.startsWith("[")) {
+    return { connectionString: cleanedUrl };
+  }
+
+  const config: Record<string, unknown> = {
+    host: urlObj.hostname.slice(1, -1),
+  };
+  if (urlObj.port) config.port = Number(urlObj.port);
+  if (urlObj.username) config.user = decodeURIComponent(urlObj.username);
+  if (urlObj.password) config.password = decodeURIComponent(urlObj.password);
+  if (urlObj.pathname.length > 1) {
+    config.database = decodeURIComponent(urlObj.pathname.slice(1));
+  }
+  for (const [key, value] of urlObj.searchParams) {
+    config[key] = value;
+  }
+  return config as PoolConfig;
+}
+
 /**
  * End a pool and wait for all client sockets to fully close.
  *
@@ -334,7 +384,11 @@ export async function createManagedPool(
     normalizedUrl,
     options?.label ?? "target",
   );
-  const pool = createPool(sslConfig.cleanedUrl, {
+  // Expand bracketed-IPv6 URLs into explicit pg fields so the brackets never
+  // reach `getaddrinfo` — see `poolConfigFromUrl` for the full rationale.
+  const connectionConfig = poolConfigFromUrl(sslConfig.cleanedUrl);
+  const pool = createPool(connectionConfig.connectionString, {
+    ...connectionConfig,
     ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
     onError: (err: Error & { code?: string }) => {
       if (err.code !== "57P01") {