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

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+import type { NormalizedOptions } from "./types.ts";
+export declare function wrapStatement(statement: string, options: NormalizedOptions, noWrapPlaceholders: Set<string>): string;

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

@@ -0,0 +1,165 @@
+import { indentString } from "./format-utils.js";
+import { isWordChar, walkSql } from "./sql-scanner.js";
+/**
+ * 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, options, noWrapPlaceholders) {
+    const lines = statement.split(/\r?\n/);
+    const wrapped = [];
+    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, placeholders) {
+    for (const token of placeholders) {
+        if (line.includes(token))
+            return true;
+    }
+    return false;
+}
+function wrapLine(line, options) {
+    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 = [];
+    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, beforeIndex) {
+    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, maxWidth) {
+    /** 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/dist/core/plan/sql-format.d.ts

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

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

@@ -0,0 +1 @@
+export { formatSqlStatements } from "./sql-format/index.js";

package/dist/core/plan/ssl-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/** 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 declare function parseSslConfig(url: string, connectionType: "source" | "target"): Promise<SslConfig>;
+export {};

package/dist/core/plan/ssl-config.js

@@ -0,0 +1,115 @@
+/**
+ * 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";
+/**
+ * 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, 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, 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, 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;
+        };
+        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;
+        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: 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/dist/core/plan/statements.d.ts

@@ -1,8 +1,9 @@
 /**
  * SQL script formatting utilities.
  */
+import { type SqlFormatOptions } from "./sql-format.ts";
 /**
  * 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 declare function formatSqlScript(statements: string[]): string;
+export declare function formatSqlScript(statements: string[], options?: SqlFormatOptions): string;

package/dist/core/plan/statements.js

@@ -1,13 +1,17 @@
 /**
  * SQL script formatting utilities.
  */
+import { formatSqlStatements } from "./sql-format.js";
 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) {
+export function formatSqlScript(statements, options) {
     if (statements.length === 0)
         return "";
-    return `${statements.join(STATEMENT_DELIMITER)};`;
+    const formatted = options
+        ? formatSqlStatements(statements, options)
+        : statements;
+    return `${formatted.join(STATEMENT_DELIMITER)};`;
 }

package/dist/core/plan/types.d.ts

@@ -3,10 +3,7 @@
  */
 import z from "zod";
 import type { Change } from "../change.types.ts";
-import type { FilterDSL } from "../integrations/filter/dsl.ts";
-import type { ChangeFilter } from "../integrations/filter/filter.types.ts";
-import type { SerializeDSL } from "../integrations/serialize/dsl.ts";
-import type { ChangeSerializer } from "../integrations/serialize/serialize.types.ts";
+import type { Integration } from "../integrations/integration.types.ts";
 export type PlanRisk = {
     level: "safe";
 } | {
@@ -133,10 +130,16 @@ export type Plan = z.infer<typeof PlanSchema>;
  */
 export interface CreatePlanOptions {
     /** Filter - either FilterDSL (stored in plan) or ChangeFilter function (not stored) */
-    filter?: FilterDSL | ChangeFilter;
+    filter?: Integration["filter"];
     /** Serialize - either SerializeDSL (stored in plan) or ChangeSerializer function (not stored) */
-    serialize?: SerializeDSL | ChangeSerializer;
+    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;
 }
 export {};

package/dist/core/post-diff-cycle-breaking.d.ts

@@ -0,0 +1,29 @@
+import type { Change } from "./change.types.ts";
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export declare function normalizePostDiffCycles({ changes, replacedTableIds, }: {
+    changes: Change[];
+    replacedTableIds?: ReadonlySet<string>;
+}): Change[];

package/dist/core/post-diff-cycle-breaking.js

@@ -0,0 +1,100 @@
+import { AlterTableAddConstraint, AlterTableDropColumn, AlterTableDropConstraint, AlterTableValidateConstraint, } from "./objects/table/changes/table.alter.js";
+import { CreateCommentOnConstraint } from "./objects/table/changes/table.comment.js";
+import { stableId } from "./objects/utils.js";
+function constraintStableId(table, constraintName) {
+    return stableId.constraint(table.schema, table.name, constraintName);
+}
+function isSupersededByTableReplacement(change, replacedTableIds) {
+    if (!(change instanceof AlterTableDropColumn) &&
+        !(change instanceof AlterTableDropConstraint)) {
+        return false;
+    }
+    return replacedTableIds.has(change.table.stableId);
+}
+/**
+ * Drop earlier duplicates of `AlterTableAddConstraint` /
+ * `AlterTableValidateConstraint` / `CreateCommentOnConstraint` targeting
+ * replaced tables, keeping only the last occurrence of each
+ * `(changeType, table.stableId, constraint.name)`.
+ *
+ * When `expandReplaceDependencies()` promotes a table to a full
+ * `DropTable + CreateTable` pair, it also emits one
+ * `AlterTableAddConstraint` (plus optional `VALIDATE CONSTRAINT` /
+ * `COMMENT ON CONSTRAINT`) per branch constraint. If `diffTables()` already
+ * emitted the same change for a shape flip or a new constraint on that
+ * table, the plan ends up with two identical `ALTER TABLE ... ADD
+ * CONSTRAINT ...` statements and PostgreSQL fails at apply time with
+ * `constraint "..." for relation "..." already exists`. Because
+ * `expandReplaceDependencies()` appends its additions after the original
+ * `diffTables()` output, the last occurrence is the expansion's emission —
+ * keeping it preserves correctness while removing the duplicate.
+ */
+function dropReplacedTableDuplicateConstraintChanges(changes, replacedTableIds) {
+    if (replacedTableIds.size === 0)
+        return changes;
+    const keyFor = (change) => {
+        if (!(change instanceof AlterTableAddConstraint) &&
+            !(change instanceof AlterTableValidateConstraint) &&
+            !(change instanceof CreateCommentOnConstraint)) {
+            return null;
+        }
+        if (!replacedTableIds.has(change.table.stableId))
+            return null;
+        const tag = change instanceof AlterTableAddConstraint
+            ? "add"
+            : change instanceof AlterTableValidateConstraint
+                ? "validate"
+                : "comment";
+        return `${tag}:${constraintStableId(change.table, change.constraint.name)}`;
+    };
+    const seen = new Set();
+    const reversedKept = [];
+    let mutated = false;
+    // Walk backwards: the first encounter of each key corresponds to its LAST
+    // occurrence in the original order. `expandReplaceDependencies()` appends
+    // additions after the original changes, so "last wins" keeps the
+    // expansion's emission and drops the earlier diffTables duplicate.
+    for (let i = changes.length - 1; i >= 0; i--) {
+        const change = changes[i];
+        const key = keyFor(change);
+        if (key !== null) {
+            if (seen.has(key)) {
+                mutated = true;
+                continue;
+            }
+            seen.add(key);
+        }
+        reversedKept.push(change);
+    }
+    return mutated ? reversedKept.reverse() : changes;
+}
+/**
+ * Apply structural rewrites to the change list that are only obvious once
+ * every object diff has been collected. This pass does NOT prevent dependency
+ * cycles — that responsibility now lives in the sort phase, where
+ * `sortPhaseChanges` invokes `tryBreakCycleByChangeInjection` lazily on cycles
+ * that edge filtering can't break (FK SCC of dropped tables,
+ * AlterPublicationDropTables ↔ AlterTableDropColumn, …).
+ *
+ * Concretely, this pass:
+ *
+ * - Prunes `AlterTableDropColumn(T.*)` / `AlterTableDropConstraint(T.*)`
+ *   changes that are made redundant by an expansion-emitted
+ *   `DropTable(T) + CreateTable(T)` pair. Without this, the apply phase
+ *   would try to drop a column that no longer exists in the freshly
+ *   recreated table.
+ * - Dedupes duplicate `AlterTableAddConstraint` /
+ *   `AlterTableValidateConstraint` / `CreateCommentOnConstraint` changes
+ *   produced when `diffTables()` and `expandReplaceDependencies()` both
+ *   emit the same constraint operation for a replaced table. Last write
+ *   wins so the expansion's emission survives.
+ *
+ * Object-local PostgreSQL semantics (for example owned-sequence cascades)
+ * stay in the corresponding `diff*` function instead of this pass.
+ */
+export function normalizePostDiffCycles({ changes, replacedTableIds = new Set(), }) {
+    const dedupedChanges = dropReplacedTableDuplicateConstraintChanges(changes, replacedTableIds);
+    if (replacedTableIds.size === 0)
+        return dedupedChanges;
+    return dedupedChanges.filter((change) => !isSupersededByTableReplacement(change, replacedTableIds));
+}

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

@@ -1,14 +1,41 @@
 /**
  * PostgreSQL connection configuration with custom type handlers.
  */
-import type { PoolClient, PoolConfig } from "pg";
+import type { ClientBase, PoolClient, PoolConfig } from "pg";
 import { Pool } from "pg";
+/**
+ * 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 declare function isRetryableConnectError(err: unknown): boolean;
+/**
+ * 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 declare function connectWithRetry<T>(opts: {
+    connect: (attempt: number) => Promise<T>;
+    isRetryable?: (err: unknown) => boolean;
+    maxAttempts?: number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T>;
 /**
  * Options for creating a Pool with event listeners.
  */
 interface CreatePoolOptions extends Partial<PoolConfig> {
     /** Called when a new client connects to the pool */
-    onConnect?: (client: PoolClient) => void | Promise<void>;
+    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 */
@@ -18,6 +45,65 @@ 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 poolConfigFromUrl(cleanedUrl: string): PoolConfig;
+/**
+ * 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 declare function createPool(connectionString: string, options?: CreatePoolOptions): Pool;
+export declare function createManagedPool(url: string, options?: {
+    role?: string;
+    label?: "source" | "target";
+}): Promise<{
+    pool: Pool;
+    close: () => Promise<void>;
+}>;
+export declare function endPool(pool: Pool): Promise<void>;
 export {};