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

package/dist/core/catalog.model.d.ts

@@ -17,7 +17,7 @@ import { type Publication } from "./objects/publication/publication.model.ts";
 import { type RlsPolicy } from "./objects/rls-policy/rls-policy.model.ts";
 import { type Role } from "./objects/role/role.model.ts";
 import { type Rule } from "./objects/rule/rule.model.ts";
-import { type Schema } from "./objects/schema/schema.model.ts";
+import { Schema } from "./objects/schema/schema.model.ts";
 import { type Sequence } from "./objects/sequence/sequence.model.ts";
 import { Subscription } from "./objects/subscription/subscription.model.ts";
 import { type Table } from "./objects/table/table.model.ts";
@@ -89,5 +89,18 @@ export declare class Catalog {
     readonly currentUser: CatalogProps["currentUser"];
     constructor(props: CatalogProps);
 }
+/**
+ * Create a baseline catalog representing a fresh PostgreSQL database.
+ *
+ * For PG 15+ this deserializes a pre-extracted snapshot of an empty `template1`
+ * database, including the `plpgsql` extension, `postgres` role with default
+ * privileges, and the `public` schema with its default ACLs and depends.
+ *
+ * For PG < 15, falls back to a minimal inline catalog with only the `public`
+ * schema. For exact fidelity on older versions, snapshot a real reference
+ * database using `serializeCatalog` and pass the deserialized result as source
+ * to `createPlan`.
+ */
+export declare function createEmptyCatalog(version: number, currentUser: string): Promise<Catalog>;
 export declare function extractCatalog(pool: Pool): Promise<Catalog>;
 export {};

package/dist/core/catalog.model.js

@@ -16,7 +16,7 @@ import { extractPublications, } from "./objects/publication/publication.model.js
 import { extractRlsPolicies, } from "./objects/rls-policy/rls-policy.model.js";
 import { extractRoles } from "./objects/role/role.model.js";
 import { extractRules } from "./objects/rule/rule.model.js";
-import { extractSchemas } from "./objects/schema/schema.model.js";
+import { extractSchemas, Schema } from "./objects/schema/schema.model.js";
 import { extractSequences, } from "./objects/sequence/sequence.model.js";
 import { extractSubscriptions, Subscription, } from "./objects/subscription/subscription.model.js";
 import { extractTables } from "./objects/table/table.model.js";
@@ -88,6 +88,108 @@ export class Catalog {
         this.currentUser = props.currentUser;
     }
 }
+// Lazily cached deserialized baselines (shared across calls)
+let _pg1516Baseline = null;
+let _pg17Baseline = null;
+async function loadBaselineJson() {
+    const mod = await import("./fixtures/empty-catalogs/postgres-15-16-baseline.json");
+    return mod.default;
+}
+async function getPg1516Baseline() {
+    if (!_pg1516Baseline) {
+        const { deserializeCatalog } = await import("./catalog.snapshot.js");
+        const json = await loadBaselineJson();
+        _pg1516Baseline = deserializeCatalog(json);
+    }
+    return _pg1516Baseline;
+}
+async function getPg17Baseline() {
+    if (!_pg17Baseline) {
+        const { deserializeCatalog } = await import("./catalog.snapshot.js");
+        // PG 17 is identical to PG 15-16 except for a single addition:
+        // the MAINTAIN privilege on default relation (objtype "r") privileges.
+        // We patch the 15-16 baseline to avoid shipping a second full JSON file.
+        const json = await loadBaselineJson();
+        const patched = structuredClone(json);
+        const roles = patched.roles;
+        const pgRole = roles?.["role:postgres"];
+        if (pgRole) {
+            const defaultPrivileges = pgRole.default_privileges;
+            const relPrivs = defaultPrivileges?.find((dp) => dp.objtype === "r" && dp.grantee === "postgres");
+            if (relPrivs) {
+                const insertIdx = relPrivs.privileges.findIndex((p) => p.privilege === "INSERT");
+                if (insertIdx === -1) {
+                    throw new Error("PG17 baseline patch failed: INSERT privilege not found in default relation privileges");
+                }
+                relPrivs.privileges.splice(insertIdx + 1, 0, {
+                    privilege: "MAINTAIN",
+                    grantable: false,
+                });
+            }
+        }
+        _pg17Baseline = deserializeCatalog(patched);
+    }
+    return _pg17Baseline;
+}
+/**
+ * Create a baseline catalog representing a fresh PostgreSQL database.
+ *
+ * For PG 15+ this deserializes a pre-extracted snapshot of an empty `template1`
+ * database, including the `plpgsql` extension, `postgres` role with default
+ * privileges, and the `public` schema with its default ACLs and depends.
+ *
+ * For PG < 15, falls back to a minimal inline catalog with only the `public`
+ * schema. For exact fidelity on older versions, snapshot a real reference
+ * database using `serializeCatalog` and pass the deserialized result as source
+ * to `createPlan`.
+ */
+export async function createEmptyCatalog(version, currentUser) {
+    if (version >= 170000) {
+        const baseline = await getPg17Baseline();
+        return new Catalog({ ...baseline, version, currentUser });
+    }
+    if (version >= 150000) {
+        const baseline = await getPg1516Baseline();
+        return new Catalog({ ...baseline, version, currentUser });
+    }
+    const publicSchema = new Schema({
+        name: "public",
+        owner: currentUser,
+        comment: "standard public schema",
+        privileges: [],
+    });
+    return new Catalog({
+        aggregates: {},
+        collations: {},
+        compositeTypes: {},
+        domains: {},
+        enums: {},
+        extensions: {},
+        procedures: {},
+        indexes: {},
+        materializedViews: {},
+        subscriptions: {},
+        publications: {},
+        rlsPolicies: {},
+        roles: {},
+        schemas: { [publicSchema.stableId]: publicSchema },
+        sequences: {},
+        tables: {},
+        triggers: {},
+        eventTriggers: {},
+        rules: {},
+        ranges: {},
+        views: {},
+        foreignDataWrappers: {},
+        servers: {},
+        userMappings: {},
+        foreignTables: {},
+        depends: [],
+        indexableObjects: {},
+        version,
+        currentUser,
+    });
+}
 export async function extractCatalog(pool) {
     const [aggregates, collations, compositeTypes, domains, enums, extensions, indexes, materializedViews, subscriptions, publications, procedures, rlsPolicies, roles, schemas, sequences, tables, triggers, eventTriggers, rules, ranges, views, foreignDataWrappers, servers, userMappings, foreignTables, depends, version, currentUser,] = await Promise.all([
         extractAggregates(pool).then(listToRecord),

package/dist/core/catalog.snapshot.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Catalog snapshot - full JSON-serializable representation of a Catalog.
+ *
+ * Enables catalog-export (snapshot a live DB) and catalog-import
+ * (use a snapshot as source/target for createPlan).
+ */
+import { Catalog } from "./catalog.model.ts";
+import type { PgDepend } from "./depend.ts";
+/**
+ * Full JSON-serializable representation of a Catalog.
+ *
+ * Every object record uses plain props objects (not class instances).
+ * `indexableObjects` is omitted -- it is reconstructed on deserialization.
+ */
+export interface CatalogSnapshot {
+    version: number;
+    currentUser: string;
+    aggregates: Record<string, Record<string, unknown>>;
+    collations: Record<string, Record<string, unknown>>;
+    compositeTypes: Record<string, Record<string, unknown>>;
+    domains: Record<string, Record<string, unknown>>;
+    enums: Record<string, Record<string, unknown>>;
+    extensions: Record<string, Record<string, unknown>>;
+    procedures: Record<string, Record<string, unknown>>;
+    indexes: Record<string, Record<string, unknown>>;
+    materializedViews: Record<string, Record<string, unknown>>;
+    subscriptions: Record<string, Record<string, unknown>>;
+    publications: Record<string, Record<string, unknown>>;
+    rlsPolicies: Record<string, Record<string, unknown>>;
+    roles: Record<string, Record<string, unknown>>;
+    schemas: Record<string, Record<string, unknown>>;
+    sequences: Record<string, Record<string, unknown>>;
+    tables: Record<string, Record<string, unknown>>;
+    triggers: Record<string, Record<string, unknown>>;
+    eventTriggers: Record<string, Record<string, unknown>>;
+    rules: Record<string, Record<string, unknown>>;
+    ranges: Record<string, Record<string, unknown>>;
+    views: Record<string, Record<string, unknown>>;
+    foreignDataWrappers: Record<string, Record<string, unknown>>;
+    servers: Record<string, Record<string, unknown>>;
+    userMappings: Record<string, Record<string, unknown>>;
+    foreignTables: Record<string, Record<string, unknown>>;
+    depends: PgDepend[];
+}
+/**
+ * Serialize a Catalog to a JSON-serializable CatalogSnapshot.
+ *
+ * Expects a normalized catalog (as returned by `extractCatalog`).
+ * BigInt values (Sequence min/max) are converted to strings by the
+ * custom JSON replacer -- call `stringifyCatalogSnapshot` for JSON output.
+ */
+export declare function serializeCatalog(catalog: Catalog): CatalogSnapshot;
+/**
+ * Serialize a CatalogSnapshot to a JSON string.
+ *
+ * Handles BigInt values (Sequence min/max) by converting them to strings.
+ */
+export declare function stringifyCatalogSnapshot(snapshot: CatalogSnapshot): string;
+/**
+ * Deserialize a CatalogSnapshot (plain JSON data) back into a Catalog.
+ *
+ * Validates the top-level structure with Zod, then constructs model
+ * class instances via their constructors. Rebuilds `indexableObjects`
+ * from tables + materializedViews.
+ */
+export declare function deserializeCatalog(data: unknown): Catalog;

package/dist/core/catalog.snapshot.js

@@ -0,0 +1,206 @@
+/**
+ * Catalog snapshot - full JSON-serializable representation of a Catalog.
+ *
+ * Enables catalog-export (snapshot a live DB) and catalog-import
+ * (use a snapshot as source/target for createPlan).
+ */
+import z from "zod";
+import { Catalog } from "./catalog.model.js";
+import { Aggregate } from "./objects/aggregate/aggregate.model.js";
+import { Collation } from "./objects/collation/collation.model.js";
+import { Domain } from "./objects/domain/domain.model.js";
+import { EventTrigger } from "./objects/event-trigger/event-trigger.model.js";
+import { Extension } from "./objects/extension/extension.model.js";
+import { ForeignDataWrapper } from "./objects/foreign-data-wrapper/foreign-data-wrapper/foreign-data-wrapper.model.js";
+import { ForeignTable } from "./objects/foreign-data-wrapper/foreign-table/foreign-table.model.js";
+import { Server } from "./objects/foreign-data-wrapper/server/server.model.js";
+import { UserMapping } from "./objects/foreign-data-wrapper/user-mapping/user-mapping.model.js";
+import { Index } from "./objects/index/index.model.js";
+import { MaterializedView } from "./objects/materialized-view/materialized-view.model.js";
+import { Procedure } from "./objects/procedure/procedure.model.js";
+import { Publication } from "./objects/publication/publication.model.js";
+import { RlsPolicy } from "./objects/rls-policy/rls-policy.model.js";
+import { Role } from "./objects/role/role.model.js";
+import { Rule } from "./objects/rule/rule.model.js";
+import { Schema } from "./objects/schema/schema.model.js";
+import { Sequence } from "./objects/sequence/sequence.model.js";
+import { Subscription } from "./objects/subscription/subscription.model.js";
+import { Table } from "./objects/table/table.model.js";
+import { Trigger } from "./objects/trigger/trigger.model.js";
+import { CompositeType } from "./objects/type/composite-type/composite-type.model.js";
+import { Enum } from "./objects/type/enum/enum.model.js";
+import { Range } from "./objects/type/range/range.model.js";
+import { View } from "./objects/view/view.model.js";
+// ============================================================================
+// Zod schema for validation on deserialization
+// ============================================================================
+const objectRecord = z.record(z.string(), z.any());
+const CatalogSnapshotSchema = z.object({
+    version: z.number(),
+    currentUser: z.string(),
+    aggregates: objectRecord,
+    collations: objectRecord,
+    compositeTypes: objectRecord,
+    domains: objectRecord,
+    enums: objectRecord,
+    extensions: objectRecord,
+    procedures: objectRecord,
+    indexes: objectRecord,
+    materializedViews: objectRecord,
+    subscriptions: objectRecord,
+    publications: objectRecord,
+    rlsPolicies: objectRecord,
+    roles: objectRecord,
+    schemas: objectRecord,
+    sequences: objectRecord,
+    tables: objectRecord,
+    triggers: objectRecord,
+    eventTriggers: objectRecord,
+    rules: objectRecord,
+    ranges: objectRecord,
+    views: objectRecord,
+    foreignDataWrappers: objectRecord,
+    servers: objectRecord,
+    userMappings: objectRecord,
+    foreignTables: objectRecord,
+    depends: z.array(z.object({
+        dependent_stable_id: z.string(),
+        referenced_stable_id: z.string(),
+        deptype: z.enum(["n", "a", "i"]),
+    })),
+});
+// ============================================================================
+// Serialization
+// ============================================================================
+function spreadRecord(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, instance]) => [
+        key,
+        { ...instance },
+    ]));
+}
+/**
+ * Serialize Aggregate instances back to their Props shape.
+ *
+ * Aggregate renames `identity_arguments` -> `identityArguments` and trims it
+ * on construction. We must map it back to `identity_arguments` so
+ * deserialization through the constructor works.
+ */
+function serializeAggregates(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, agg]) => {
+        const { identityArguments: _, ...rest } = agg;
+        return [key, { ...rest, identity_arguments: agg.identityArguments }];
+    }));
+}
+/**
+ * Serialize a Catalog to a JSON-serializable CatalogSnapshot.
+ *
+ * Expects a normalized catalog (as returned by `extractCatalog`).
+ * BigInt values (Sequence min/max) are converted to strings by the
+ * custom JSON replacer -- call `stringifyCatalogSnapshot` for JSON output.
+ */
+export function serializeCatalog(catalog) {
+    return {
+        version: catalog.version,
+        currentUser: catalog.currentUser,
+        aggregates: serializeAggregates(catalog.aggregates),
+        collations: spreadRecord(catalog.collations),
+        compositeTypes: spreadRecord(catalog.compositeTypes),
+        domains: spreadRecord(catalog.domains),
+        enums: spreadRecord(catalog.enums),
+        extensions: spreadRecord(catalog.extensions),
+        procedures: spreadRecord(catalog.procedures),
+        indexes: spreadRecord(catalog.indexes),
+        materializedViews: spreadRecord(catalog.materializedViews),
+        subscriptions: spreadRecord(catalog.subscriptions),
+        publications: spreadRecord(catalog.publications),
+        rlsPolicies: spreadRecord(catalog.rlsPolicies),
+        roles: spreadRecord(catalog.roles),
+        schemas: spreadRecord(catalog.schemas),
+        sequences: spreadRecord(catalog.sequences),
+        tables: spreadRecord(catalog.tables),
+        triggers: spreadRecord(catalog.triggers),
+        eventTriggers: spreadRecord(catalog.eventTriggers),
+        rules: spreadRecord(catalog.rules),
+        ranges: spreadRecord(catalog.ranges),
+        views: spreadRecord(catalog.views),
+        foreignDataWrappers: spreadRecord(catalog.foreignDataWrappers),
+        servers: spreadRecord(catalog.servers),
+        userMappings: spreadRecord(catalog.userMappings),
+        foreignTables: spreadRecord(catalog.foreignTables),
+        depends: catalog.depends,
+    };
+}
+/**
+ * Serialize a CatalogSnapshot to a JSON string.
+ *
+ * Handles BigInt values (Sequence min/max) by converting them to strings.
+ */
+export function stringifyCatalogSnapshot(snapshot) {
+    return JSON.stringify(snapshot, (_key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+}
+// ============================================================================
+// Deserialization
+// ============================================================================
+function buildRecord(record, ctor) {
+    return Object.fromEntries(Object.entries(record).map(([key, props]) => [
+        key,
+        new ctor(props),
+    ]));
+}
+/**
+ * Coerce BigInt fields in Sequence props from string back to BigInt.
+ * JSON has no BigInt type, so these are stored as strings.
+ */
+function coerceSequenceBigInts(record) {
+    return Object.fromEntries(Object.entries(record).map(([key, props]) => [
+        key,
+        {
+            ...props,
+            minimum_value: BigInt(props.minimum_value),
+            maximum_value: BigInt(props.maximum_value),
+        },
+    ]));
+}
+/**
+ * Deserialize a CatalogSnapshot (plain JSON data) back into a Catalog.
+ *
+ * Validates the top-level structure with Zod, then constructs model
+ * class instances via their constructors. Rebuilds `indexableObjects`
+ * from tables + materializedViews.
+ */
+export function deserializeCatalog(data) {
+    const s = CatalogSnapshotSchema.parse(data);
+    const tables = buildRecord(s.tables, Table);
+    const materializedViews = buildRecord(s.materializedViews, MaterializedView);
+    return new Catalog({
+        version: s.version,
+        currentUser: s.currentUser,
+        aggregates: buildRecord(s.aggregates, Aggregate),
+        collations: buildRecord(s.collations, Collation),
+        compositeTypes: buildRecord(s.compositeTypes, CompositeType),
+        domains: buildRecord(s.domains, Domain),
+        enums: buildRecord(s.enums, Enum),
+        extensions: buildRecord(s.extensions, Extension),
+        procedures: buildRecord(s.procedures, Procedure),
+        indexes: buildRecord(s.indexes, Index),
+        materializedViews,
+        subscriptions: buildRecord(s.subscriptions, Subscription),
+        publications: buildRecord(s.publications, Publication),
+        rlsPolicies: buildRecord(s.rlsPolicies, RlsPolicy),
+        roles: buildRecord(s.roles, Role),
+        schemas: buildRecord(s.schemas, Schema),
+        sequences: buildRecord(coerceSequenceBigInts(s.sequences), Sequence),
+        tables,
+        triggers: buildRecord(s.triggers, Trigger),
+        eventTriggers: buildRecord(s.eventTriggers, EventTrigger),
+        rules: buildRecord(s.rules, Rule),
+        ranges: buildRecord(s.ranges, Range),
+        views: buildRecord(s.views, View),
+        foreignDataWrappers: buildRecord(s.foreignDataWrappers, ForeignDataWrapper),
+        servers: buildRecord(s.servers, Server),
+        userMappings: buildRecord(s.userMappings, UserMapping),
+        foreignTables: buildRecord(s.foreignTables, ForeignTable),
+        depends: s.depends,
+        indexableObjects: { ...tables, ...materializedViews },
+    });
+}

package/dist/core/change-utils.d.ts

@@ -0,0 +1,9 @@
+import type { Change } from "./change.types.ts";
+/**
+ * Extract the schema name from a Change using the model sub-object.
+ *
+ * This is a convenience function used by the filter DSL (for schema
+ * normalization) and the sort module. It reads the `schema` (or `name`
+ * for schema objectType) from the model sub-object.
+ */
+export declare function getSchema(change: Change): string | null;

package/dist/core/change-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Extract the schema name from a Change using the model sub-object.
+ *
+ * This is a convenience function used by the filter DSL (for schema
+ * normalization) and the sort module. It reads the `schema` (or `name`
+ * for schema objectType) from the model sub-object.
+ */
+export function getSchema(change) {
+    if (change.scope === "default_privilege") {
+        return change.inSchema;
+    }
+    switch (change.objectType) {
+        case "aggregate":
+            return change.aggregate.schema;
+        case "collation":
+            return change.collation.schema;
+        case "composite_type":
+            return change.compositeType.schema;
+        case "domain":
+            return change.domain.schema;
+        case "enum":
+            return change.enum.schema;
+        case "event_trigger":
+            return change.eventTrigger.function_schema;
+        case "extension":
+            return change.extension.schema;
+        case "index":
+            return change.index.schema;
+        case "language":
+            return null;
+        case "materialized_view":
+            return change.materializedView.schema;
+        case "procedure":
+            return change.procedure.schema;
+        case "publication":
+            return null;
+        case "range":
+            return change.range.schema;
+        case "rls_policy":
+            return change.policy.schema;
+        case "role":
+            return null;
+        case "rule":
+            return change.rule.schema;
+        case "schema":
+            return change.schema.name;
+        case "sequence":
+            return change.sequence.schema;
+        case "subscription":
+            return null;
+        case "table":
+            return change.table.schema;
+        case "trigger":
+            return change.trigger.schema;
+        case "view":
+            return change.view.schema;
+        case "foreign_data_wrapper":
+            return null;
+        case "server":
+            return null;
+        case "user_mapping":
+            return null;
+        case "foreign_table":
+            return change.foreignTable.schema;
+        default: {
+            // exhaustiveness check
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}

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

@@ -19,4 +19,26 @@ import type { TableChange } from "./objects/table/changes/table.types.ts";
 import type { TriggerChange } from "./objects/trigger/changes/trigger.types.ts";
 import type { TypeChange } from "./objects/type/type.types.ts";
 import type { ViewChange } from "./objects/view/changes/view.types.ts";
+/**
+ * Discriminated union of all PostgreSQL object change types.
+ *
+ * Every member shares a common `objectType` discriminant (e.g. `"table"`,
+ * `"view"`, `"role"`) that the filter DSL pattern-matches against. Use
+ * {@link OBJECT_TYPE_TO_PROPERTY_KEY} to map an `objectType` value to the
+ * corresponding JS property key on the Change instance.
+ *
+ * @category Change Types
+ */
 export type Change = AggregateChange | CollationChange | DomainChange | ExtensionChange | IndexChange | LanguageChange | MaterializedViewChange | SubscriptionChange | PublicationChange | ProcedureChange | RlsPolicyChange | RoleChange | SchemaChange | SequenceChange | TableChange | TriggerChange | EventTriggerChange | RuleChange | TypeChange | ViewChange | ForeignDataWrapperChange;
+/**
+ * Exhaustive map from every `objectType` discriminant value to the JS property
+ * key that holds the model sub-object on the corresponding {@link Change}.
+ *
+ * Used internally by the filter DSL flattening logic to locate nested
+ * properties and expose them as `<objectType>/<field>` paths.
+ *
+ * @category Change Types
+ */
+export declare const OBJECT_TYPE_TO_PROPERTY_KEY: {
+    [K in Change["objectType"]]: string;
+};

package/dist/core/change.types.js

@@ -1 +1,37 @@
-export {};
+/**
+ * Exhaustive map from every `objectType` discriminant value to the JS property
+ * key that holds the model sub-object on the corresponding {@link Change}.
+ *
+ * Used internally by the filter DSL flattening logic to locate nested
+ * properties and expose them as `<objectType>/<field>` paths.
+ *
+ * @category Change Types
+ */
+export const OBJECT_TYPE_TO_PROPERTY_KEY = {
+    aggregate: "aggregate",
+    collation: "collation",
+    composite_type: "compositeType",
+    domain: "domain",
+    enum: "enum",
+    event_trigger: "eventTrigger",
+    extension: "extension",
+    foreign_data_wrapper: "foreignDataWrapper",
+    foreign_table: "foreignTable",
+    index: "index",
+    language: "language",
+    materialized_view: "materializedView",
+    procedure: "procedure",
+    publication: "publication",
+    range: "range",
+    rls_policy: "policy",
+    role: "role",
+    rule: "rule",
+    schema: "schema",
+    sequence: "sequence",
+    server: "server",
+    subscription: "subscription",
+    table: "table",
+    trigger: "trigger",
+    user_mapping: "userMapping",
+    view: "view",
+};

package/dist/core/connection-url.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function isIPv6(value: string): boolean;
+/**
+ * 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 declare function normalizeConnectionUrl(url: string): string;

package/dist/core/connection-url.js

@@ -0,0 +1,77 @@
+/**
+ * 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) {
+    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) {
+    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}`;
+}