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

package/src/core/catalog.snapshot.ts

@@ -0,0 +1,289 @@
+/**
+ * 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.ts";
+import type { PgDepend } from "./depend.ts";
+import { Aggregate } from "./objects/aggregate/aggregate.model.ts";
+import { Collation } from "./objects/collation/collation.model.ts";
+import { Domain } from "./objects/domain/domain.model.ts";
+import { EventTrigger } from "./objects/event-trigger/event-trigger.model.ts";
+import { Extension } from "./objects/extension/extension.model.ts";
+import { ForeignDataWrapper } from "./objects/foreign-data-wrapper/foreign-data-wrapper/foreign-data-wrapper.model.ts";
+import { ForeignTable } from "./objects/foreign-data-wrapper/foreign-table/foreign-table.model.ts";
+import { Server } from "./objects/foreign-data-wrapper/server/server.model.ts";
+import { UserMapping } from "./objects/foreign-data-wrapper/user-mapping/user-mapping.model.ts";
+import { Index } from "./objects/index/index.model.ts";
+import { MaterializedView } from "./objects/materialized-view/materialized-view.model.ts";
+import { Procedure } from "./objects/procedure/procedure.model.ts";
+import { Publication } from "./objects/publication/publication.model.ts";
+import { RlsPolicy } from "./objects/rls-policy/rls-policy.model.ts";
+import { Role } from "./objects/role/role.model.ts";
+import { Rule } from "./objects/rule/rule.model.ts";
+import { Schema } from "./objects/schema/schema.model.ts";
+import { Sequence } from "./objects/sequence/sequence.model.ts";
+import { Subscription } from "./objects/subscription/subscription.model.ts";
+import { Table } from "./objects/table/table.model.ts";
+import { Trigger } from "./objects/trigger/trigger.model.ts";
+import { CompositeType } from "./objects/type/composite-type/composite-type.model.ts";
+import { Enum } from "./objects/type/enum/enum.model.ts";
+import { Range } from "./objects/type/range/range.model.ts";
+import { View } from "./objects/view/view.model.ts";
+
+// ============================================================================
+// CatalogSnapshot type
+// ============================================================================
+
+/**
+ * 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[];
+}
+
+// ============================================================================
+// 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<T>(
+  record: Record<string, T>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, instance]) => [
+      key,
+      { ...(instance as Record<string, unknown>) },
+    ]),
+  );
+}
+
+/**
+ * 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: Record<string, Aggregate>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, agg]) => {
+      const { identityArguments: _, ...rest } = agg as unknown as Record<
+        string,
+        unknown
+      >;
+      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: Catalog): CatalogSnapshot {
+  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: CatalogSnapshot): string {
+  return JSON.stringify(
+    snapshot,
+    (_key, value) => (typeof value === "bigint" ? value.toString() : value),
+    2,
+  );
+}
+
+// ============================================================================
+// Deserialization
+// ============================================================================
+
+function buildRecord<T>(
+  record: Record<string, Record<string, unknown>>,
+  ctor: new (props: never) => T,
+): Record<string, T> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, props]) => [
+      key,
+      new ctor(props as never),
+    ]),
+  );
+}
+
+/**
+ * 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: Record<string, Record<string, unknown>>,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, props]) => [
+      key,
+      {
+        ...props,
+        minimum_value: BigInt(props.minimum_value as string | bigint),
+        maximum_value: BigInt(props.maximum_value as string | bigint),
+      },
+    ]),
+  );
+}
+
+/**
+ * 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: unknown): Catalog {
+  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/src/core/change-utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import type { Change } from "./change.types.ts";
+import { getSchema } from "./change-utils.ts";
+
+describe("getSchema", () => {
+  test("returns schema for table", () => {
+    const change = {
+      objectType: "table",
+      table: { schema: "public" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("public");
+  });
+
+  test("returns schema for view", () => {
+    const change = {
+      objectType: "view",
+      view: { schema: "app" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("app");
+  });
+
+  test("returns schema for enum", () => {
+    const change = {
+      objectType: "enum",
+      enum: { schema: "types" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("types");
+  });
+
+  test("returns schema.name for schema type", () => {
+    const change = {
+      objectType: "schema",
+      schema: { name: "auth" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBe("auth");
+  });
+
+  test("returns null for role", () => {
+    const change = {
+      objectType: "role",
+      role: { name: "admin" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for publication", () => {
+    const change = {
+      objectType: "publication",
+      publication: { name: "pub1" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+
+  test("returns null for language", () => {
+    const change = {
+      objectType: "language",
+      language: { name: "plpgsql" },
+    } as unknown as Change;
+    expect(getSchema(change)).toBeNull();
+  });
+});

package/src/core/change-utils.ts

@@ -0,0 +1,73 @@
+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 function getSchema(change: Change): string | null {
+  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: never = change;
+      return _exhaustive;
+    }
+  }
+}

package/src/core/change.types.ts

@@ -0,0 +1,94 @@
+import type { AggregateChange } from "./objects/aggregate/changes/aggregate.types.ts";
+import type { CollationChange } from "./objects/collation/changes/collation.types.ts";
+import type { DomainChange } from "./objects/domain/changes/domain.types.ts";
+import type { EventTriggerChange } from "./objects/event-trigger/changes/event-trigger.types.ts";
+import type { ExtensionChange } from "./objects/extension/changes/extension.types.ts";
+import type { ForeignDataWrapperChange } from "./objects/foreign-data-wrapper/foreign-data-wrapper.types.ts";
+import type { IndexChange } from "./objects/index/changes/index.types.ts";
+import type { LanguageChange } from "./objects/language/changes/language.types.ts";
+import type { MaterializedViewChange } from "./objects/materialized-view/changes/materialized-view.types.ts";
+import type { ProcedureChange } from "./objects/procedure/changes/procedure.types.ts";
+import type { PublicationChange } from "./objects/publication/changes/publication.types.ts";
+import type { RlsPolicyChange } from "./objects/rls-policy/changes/rls-policy.types.ts";
+import type { RoleChange } from "./objects/role/changes/role.types.ts";
+import type { RuleChange } from "./objects/rule/changes/rule.types.ts";
+import type { SchemaChange } from "./objects/schema/changes/schema.types.ts";
+import type { SequenceChange } from "./objects/sequence/changes/sequence.types.ts";
+import type { SubscriptionChange } from "./objects/subscription/changes/subscription.types.ts";
+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 const OBJECT_TYPE_TO_PROPERTY_KEY: {
+  [K in Change["objectType"]]: string;
+} = {
+  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/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);
+    });
+  });
+});