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

package/src/core/connection-url.ts

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

package/src/core/context.ts

@@ -0,0 +1,26 @@
+import { sql } from "@ts-safeql/sql-tag";
+import type { Pool } from "pg";
+import type { Catalog } from "./catalog.model.ts";
+
+/**
+ * Context for diff operations, containing both source and target catalogs.
+ */
+export interface DiffContext {
+  mainCatalog: Catalog;
+  branchCatalog: Catalog;
+}
+
+export async function extractVersion(pool: Pool) {
+  const { rows } = await pool.query<{ version: number }>(
+    sql`select current_setting('server_version_num')::int as version`,
+  );
+
+  return rows[0].version;
+}
+
+export async function extractCurrentUser(pool: Pool) {
+  const { rows } = await pool.query<{ current_user: string }>(
+    sql`select quote_ident(current_user) as current_user`,
+  );
+  return rows[0].current_user;
+}

package/src/core/declarative-apply/discover-sql.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { loadDeclarativeSchema } from "./discover-sql.ts";
+
+describe("loadDeclarativeSchema", () => {
+  test("throws when path does not exist", async () => {
+    const nonExistent = path.join(
+      tmpdir(),
+      `pgdelta-nonexistent-${Date.now()}`,
+    );
+
+    await expect(loadDeclarativeSchema(nonExistent)).rejects.toThrow(
+      /Cannot access.*ENOENT/,
+    );
+  });
+
+  test("throws when path is a file but not .sql", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const txtFile = path.join(dir, "foo.txt");
+    await writeFile(txtFile, "not sql");
+
+    try {
+      await expect(loadDeclarativeSchema(txtFile)).rejects.toThrow(
+        /Path is not a \.sql file/,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads a single .sql file and returns one entry with relative path", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const sqlFile = path.join(dir, "schema.sql");
+    const content = "CREATE SCHEMA foo;";
+    await writeFile(sqlFile, content);
+
+    try {
+      const entries = await loadDeclarativeSchema(sqlFile);
+      expect(entries).toHaveLength(1);
+      expect(entries[0].filePath).toBe("schema.sql");
+      expect(entries[0].sql).toBe(content);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("loads directory of .sql files in deterministic order (match pg-topo)", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    const clusterDir = path.join(dir, "cluster");
+    const subDir = path.join(dir, "schemas", "public");
+    await mkdir(clusterDir, { recursive: true });
+    await mkdir(subDir, { recursive: true });
+    await writeFile(path.join(clusterDir, "roles.sql"), "SELECT 1;");
+    await writeFile(path.join(subDir, "schema.sql"), "CREATE SCHEMA public;");
+    await writeFile(
+      path.join(subDir, "tables.sql"),
+      "CREATE TABLE t (id int);",
+    );
+
+    try {
+      const entries = await loadDeclarativeSchema(dir);
+      expect(entries.length).toBeGreaterThanOrEqual(3);
+      const paths = entries.map((e) => e.filePath);
+      const sorted = [...paths].sort((a, b) => a.localeCompare(b));
+      expect(paths).toEqual(sorted);
+      expect(paths).toContain("schemas/public/schema.sql");
+      expect(paths).toContain("schemas/public/tables.sql");
+      expect(paths).toContain("cluster/roles.sql");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns empty array when directory has no .sql files", async () => {
+    const dir = path.join(
+      tmpdir(),
+      `pgdelta-discover-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, "readme.txt"), "no sql here");
+
+    try {
+      const entries = await loadDeclarativeSchema(dir);
+      expect(entries).toHaveLength(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/core/declarative-apply/discover-sql.ts

@@ -0,0 +1,107 @@
+/**
+ * Discover and read .sql files under a schema path (file or directory).
+ * Matches pg-topo's discovery order for deterministic statement ordering.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+export interface SqlFileEntry {
+  /** Relative path from base (forward slashes, e.g. schemas/public/views/billing.sql) */
+  filePath: string;
+  /** File content */
+  sql: string;
+}
+
+/**
+ * Recursively collect .sql files in a directory. Entries sorted by name,
+ * then full paths sorted for deterministic order (matches pg-topo discover).
+ */
+async function readSqlFilesInDirectory(
+  directoryPath: string,
+  outFiles: Set<string>,
+): Promise<void> {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  for (const entry of entries) {
+    const fullPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      await readSqlFilesInDirectory(fullPath, outFiles);
+      continue;
+    }
+
+    if (entry.isFile() && fullPath.toLowerCase().endsWith(".sql")) {
+      outFiles.add(path.resolve(fullPath));
+    }
+  }
+}
+
+/**
+ * Stable relative path: path.relative(basePath, absolutePath) with forward slashes.
+ */
+function toStablePath(absolutePath: string, basePath: string): string {
+  return path.relative(basePath, absolutePath).split(path.sep).join("/");
+}
+
+/**
+ * Load all .sql files under schemaPath (a single .sql file or a directory).
+ * Returns entries in the same order as pg-topo's discover (sorted by full path).
+ *
+ * @throws If schemaPath does not exist, is not a file/directory, or any file cannot be read.
+ *         Error message includes path and code (e.g. ENOENT, EACCES) for CLI to display.
+ */
+export async function loadDeclarativeSchema(
+  schemaPath: string,
+): Promise<SqlFileEntry[]> {
+  const resolvedRoot = path.resolve(schemaPath);
+
+  let rootStats: Awaited<ReturnType<typeof stat>>;
+  try {
+    rootStats = await stat(resolvedRoot);
+  } catch (err) {
+    const code =
+      err && typeof err === "object" && "code" in err
+        ? String((err as NodeJS.ErrnoException).code)
+        : "UNKNOWN";
+    throw new Error(`Cannot access '${schemaPath}': ${code}`);
+  }
+
+  let files: string[];
+  let basePath: string;
+
+  if (rootStats.isFile()) {
+    if (!resolvedRoot.toLowerCase().endsWith(".sql")) {
+      throw new Error(`Path is not a .sql file: '${schemaPath}'`);
+    }
+    files = [resolvedRoot];
+    basePath = path.dirname(resolvedRoot);
+  } else if (rootStats.isDirectory()) {
+    const fileSet = new Set<string>();
+    await readSqlFilesInDirectory(resolvedRoot, fileSet);
+    files = [...fileSet].sort((a, b) => a.localeCompare(b));
+    basePath = resolvedRoot;
+  } else {
+    throw new Error(`Path is not a file or directory: '${schemaPath}'`);
+  }
+
+  const entries: SqlFileEntry[] = [];
+  for (const filePath of files) {
+    try {
+      const sql = await readFile(filePath, "utf-8");
+      entries.push({
+        filePath: toStablePath(filePath, basePath),
+        sql,
+      });
+    } catch (err) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? String((err as NodeJS.ErrnoException).code)
+          : "UNKNOWN";
+      const relative = toStablePath(filePath, basePath);
+      throw new Error(`Cannot read file '${relative}': ${code}`);
+    }
+  }
+
+  return entries;
+}

package/src/core/declarative-apply/extract-catalog-providers.ts

@@ -0,0 +1,220 @@
+/**
+ * Extract functions, types, and other catalog objects from the target database
+ * so pg-topo can treat them as external providers and suppress false
+ * UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), gen_random_uuid(), nextval(),
+ * auth.users, extensions.uuid_generate_v4, etc.).
+ */
+
+import type { ObjectRef } from "@supabase/pg-topo";
+import type { Pool } from "pg";
+
+type FunctionRow = {
+  name: string;
+  schema: string;
+  kind: string;
+  signature: string;
+};
+type TypeRow = { name: string; schema: string; typetype: string };
+type SchemaRow = { name: string };
+type RelationRow = { name: string; schema: string; relkind: string };
+type ExtensionRow = { name: string; schema: string | null };
+type RoleRow = { name: string };
+type LanguageRow = { name: string };
+type CollationRow = { name: string; schema: string };
+type FdwRow = { name: string };
+type ServerRow = { name: string };
+type EventTriggerRow = { name: string };
+type PublicationRow = { name: string };
+type SubscriptionRow = { name: string };
+
+function addProvider(
+  providers: ObjectRef[],
+  ref: ObjectRef,
+  alsoUnderPublic = false,
+): void {
+  providers.push(ref);
+  if (
+    alsoUnderPublic &&
+    (ref.schema === "pg_catalog" || ref.schema === "information_schema")
+  ) {
+    providers.push({ ...ref, schema: "public" });
+  }
+}
+
+/**
+ * Query the target database for all catalog objects that can be dependencies.
+ * Returns ObjectRefs that pg-topo can use as external providers so it does
+ * not flag false UNRESOLVED_DEPENDENCY diagnostics (e.g. now(), text, public).
+ *
+ * This is intentionally separate from {@link extractCatalog} in catalog.model.ts:
+ * - extractCatalog is for schema diffing and excludes system objects (filters
+ *   out pg_catalog, information_schema, extension-owned). It also does not
+ *   extract languages. We need the opposite here: all objects that might be
+ *   referenced by SQL, including built-in functions, types, and schemas.
+ * - Objects in pg_catalog/information_schema are registered under both their
+ *   real schema and "public" (via addProvider's alsoUnderPublic) so
+ *   unqualified references in SQL resolve the same way the parser does.
+ */
+export async function extractCatalogProviders(
+  pool: Pool,
+): Promise<ObjectRef[]> {
+  const providers: ObjectRef[] = [];
+
+  const [
+    functionsResult,
+    typesResult,
+    schemasResult,
+    relationsResult,
+    extensionsResult,
+    rolesResult,
+    languagesResult,
+    collationsResult,
+    fdwsResult,
+    serversResult,
+    eventTriggersResult,
+    publicationsResult,
+    subscriptionsResult,
+  ] = await Promise.all([
+    pool.query<FunctionRow>(`
+      SELECT
+        p.proname AS name,
+        n.nspname AS schema,
+        p.prokind AS kind,
+        COALESCE((
+          SELECT string_agg(
+            CASE WHEN p.proargmodes IS NOT NULL AND p.proargmodes[ord] = 'v'
+                 THEN 'VARIADIC ' || format_type(t.oid, NULL)
+                 ELSE format_type(t.oid, NULL)
+            END, ',' ORDER BY ord)
+          FROM unnest(p.proargtypes) WITH ORDINALITY AS t(oid, ord)
+        ), '') AS signature
+      FROM pg_proc p
+      JOIN pg_namespace n ON n.oid = p.pronamespace
+    `),
+    pool.query<TypeRow>(`
+      SELECT t.typname AS name, n.nspname AS schema, t.typtype AS typetype
+      FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname NOT LIKE 'pg_toast%'
+        AND t.typtype IN ('b', 'c', 'd', 'e', 'r')
+    `),
+    pool.query<SchemaRow>(`
+      SELECT nspname AS name FROM pg_namespace
+      WHERE nspname NOT LIKE 'pg_toast%'
+    `),
+    pool.query<RelationRow>(`
+      SELECT c.relname AS name, n.nspname AS schema, c.relkind AS relkind
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('r', 'p', 'v', 'm', 'S', 'i')
+        AND n.nspname NOT LIKE 'pg_toast%'
+    `),
+    pool.query<ExtensionRow>(`
+      SELECT e.extname AS name, n.nspname AS schema
+      FROM pg_extension e
+      LEFT JOIN pg_namespace n ON n.oid = e.extnamespace
+    `),
+    pool.query<RoleRow>(`SELECT rolname AS name FROM pg_roles`),
+    pool.query<LanguageRow>(`SELECT lanname AS name FROM pg_language`),
+    pool.query<CollationRow>(`
+      SELECT c.collname AS name, n.nspname AS schema
+      FROM pg_collation c
+      JOIN pg_namespace n ON n.oid = c.collnamespace
+      WHERE n.nspname NOT LIKE 'pg_toast%'
+    `),
+    pool.query<FdwRow>(`SELECT fdwname AS name FROM pg_foreign_data_wrapper`),
+    pool.query<ServerRow>(`SELECT srvname AS name FROM pg_foreign_server`),
+    pool.query<EventTriggerRow>(`SELECT evtname AS name FROM pg_event_trigger`),
+    pool.query<PublicationRow>(`SELECT pubname AS name FROM pg_publication`),
+    pool.query<SubscriptionRow>(`SELECT subname AS name FROM pg_subscription`),
+  ]);
+
+  for (const fn of functionsResult.rows) {
+    const kind =
+      fn.kind === "a"
+        ? "aggregate"
+        : fn.kind === "p"
+          ? "procedure"
+          : "function";
+    const sig = fn.signature.trim() ? `(${fn.signature})` : "()";
+    const ref: ObjectRef = {
+      kind,
+      name: fn.name,
+      schema: fn.schema,
+      signature: sig,
+    };
+    addProvider(providers, ref, true);
+  }
+
+  for (const t of typesResult.rows) {
+    const kind = t.typetype === "d" ? "domain" : "type";
+    const ref: ObjectRef = { kind, name: t.name, schema: t.schema };
+    addProvider(providers, ref, true);
+  }
+
+  for (const row of schemasResult.rows) {
+    providers.push({ kind: "schema", name: row.name });
+  }
+
+  const relkindToKind: Record<string, ObjectRef["kind"]> = {
+    r: "table",
+    p: "table",
+    v: "view",
+    m: "materialized_view",
+    S: "sequence",
+    i: "index",
+  };
+  for (const row of relationsResult.rows) {
+    const kind = relkindToKind[row.relkind];
+    if (!kind) continue;
+    const ref: ObjectRef = { kind, name: row.name, schema: row.schema };
+    addProvider(providers, ref, true);
+  }
+
+  for (const row of extensionsResult.rows) {
+    providers.push({
+      kind: "extension",
+      name: row.name,
+      schema: row.schema ?? undefined,
+    });
+  }
+
+  for (const row of rolesResult.rows) {
+    providers.push({ kind: "role", name: row.name });
+  }
+
+  for (const row of languagesResult.rows) {
+    providers.push({ kind: "language", name: row.name });
+  }
+
+  for (const row of collationsResult.rows) {
+    const ref: ObjectRef = {
+      kind: "collation",
+      name: row.name,
+      schema: row.schema,
+    };
+    addProvider(providers, ref, true);
+  }
+
+  for (const row of fdwsResult.rows) {
+    providers.push({ kind: "foreign_data_wrapper", name: row.name });
+  }
+
+  for (const row of serversResult.rows) {
+    providers.push({ kind: "foreign_server", name: row.name });
+  }
+
+  for (const row of eventTriggersResult.rows) {
+    providers.push({ kind: "event_trigger", name: row.name });
+  }
+
+  for (const row of publicationsResult.rows) {
+    providers.push({ kind: "publication", name: row.name });
+  }
+
+  for (const row of subscriptionsResult.rows) {
+    providers.push({ kind: "subscription", name: row.name });
+  }
+
+  return providers;
+}

package/src/core/declarative-apply/index.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { Pool } from "pg";
+import { applyDeclarativeSchema } from "./index.ts";
+
+// Mock extractCatalogProviders to throw, simulating an early failure
+// before roundApply is ever reached.
+mock.module("./extract-catalog-providers.ts", () => ({
+  extractCatalogProviders: async () => {
+    throw new Error("simulated catalog extraction failure");
+  },
+}));
+
+// Track the pool created internally via createManagedPool so we can verify cleanup.
+let lastCreatedPool: Pool & { closeCalled: boolean };
+
+mock.module("../postgres-config.ts", () => ({
+  createManagedPool: async () => {
+    lastCreatedPool = createMockPool();
+    return {
+      pool: lastCreatedPool,
+      close: async () => {
+        lastCreatedPool.closeCalled = true;
+      },
+    };
+  },
+}));
+
+function createMockPool(): Pool & { closeCalled: boolean } {
+  const pool = {
+    closeCalled: false,
+    connect: async () => {
+      throw new Error("should not connect");
+    },
+    end: async () => {},
+    query: async () => {
+      throw new Error("should not query");
+    },
+  } as unknown as Pool & { closeCalled: boolean };
+  return pool;
+}
+
+describe("applyDeclarativeSchema", () => {
+  test("caller-owned pool is NOT closed on early failure", async () => {
+    const pool = createMockPool();
+
+    await expect(
+      applyDeclarativeSchema({
+        content: [{ filePath: "test.sql", sql: "CREATE TABLE t(id int);" }],
+        pool,
+      }),
+    ).rejects.toThrow("simulated catalog extraction failure");
+
+    expect(pool.closeCalled).toBe(false);
+  });
+
+  test("internally-created pool IS closed on early failure", async () => {
+    await expect(
+      applyDeclarativeSchema({
+        content: [{ filePath: "test.sql", sql: "CREATE TABLE t(id int);" }],
+        targetUrl: "postgresql://localhost/test",
+      }),
+    ).rejects.toThrow("simulated catalog extraction failure");
+
+    expect(lastCreatedPool).toBeDefined();
+    expect(lastCreatedPool.closeCalled).toBe(true);
+  });
+});