@supabase/pg-delta 1.0.0-alpha.0 → 1.0.0-alpha.10

package/dist/core/postgres-config.js

@@ -1,46 +1,232 @@
 /**
  * PostgreSQL connection configuration with custom type handlers.
  */
+import { escapeIdentifier, Pool, types } from "pg";
+import { parseSslConfig } from "./plan/ssl-config.js";
+// ============================================================================
+// Array Parser
+// ============================================================================
 /**
- * Custom type handler for specific corner cases.
+ * Parse PostgreSQL array string into JavaScript array.
+ * Handles: {val1,val2}, {NULL,val}, {"quoted,val"}, nested arrays.
  */
-export const postgresConfig = {
-    types: {
-        int2vector: {
-            // The pg_types oid for int2vector (22 is the OID for int2vector)
-            to: 22,
-            // Array of pg_types oids to handle when parsing values coming from the db
-            from: [22],
-            // Parse int2vector from string format "1 2 3" to array [1, 2, 3]
-            parse: (value) => {
-                if (!value || value === "")
-                    return [];
-                return value
-                    .split(" ")
-                    .map(Number)
-                    .filter((n) => !Number.isNaN(n));
-            },
-            // Serialize array back to int2vector format if needed
-            serialize: (value) => {
-                if (!Array.isArray(value))
-                    return "";
-                return value.join(" ");
-            },
+function parseArray(value, parseElement = (v) => v) {
+    if (!value || value === "{}")
+        return [];
+    // Remove outer braces
+    const inner = value.slice(1, -1);
+    if (inner === "")
+        return [];
+    const result = [];
+    let current = "";
+    let inQuotes = false;
+    let depth = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const char = inner[i];
+        if (char === '"' && inner[i - 1] !== "\\") {
+            inQuotes = !inQuotes;
+            current += char;
+        }
+        else if (char === "{" && !inQuotes) {
+            depth++;
+            current += char;
+        }
+        else if (char === "}" && !inQuotes) {
+            depth--;
+            current += char;
+        }
+        else if (char === "," && !inQuotes && depth === 0) {
+            result.push(parseElement(current));
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current !== "") {
+        result.push(parseElement(current));
+    }
+    return result;
+}
+/**
+ * Parse element, handling NULL, quoted strings, and unquoted values.
+ */
+function parseStringElement(val) {
+    if (val === "NULL")
+        return null;
+    if (val.startsWith('"') && val.endsWith('"')) {
+        // Unescape quoted string
+        return val.slice(1, -1).replace(/\\(.)/g, "$1");
+    }
+    return val;
+}
+function parseIntElement(val) {
+    if (val === "NULL")
+        return null;
+    return Number.parseInt(val, 10);
+}
+// ============================================================================
+// Type Parsers
+// ============================================================================
+// int2vector: "1 2 3" -> [1, 2, 3]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(22, (val) => {
+    if (!val || val === "")
+        return [];
+    return val
+        .split(" ")
+        .map(Number)
+        .filter((n) => !Number.isNaN(n));
+});
+// bigint: string -> BigInt
+types.setTypeParser(20, (val) => BigInt(val));
+// PostgreSQL array types
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1002, (val) => parseArray(val, parseStringElement)); // "char"[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1009, (val) => parseArray(val, parseStringElement)); // text[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1015, (val) => parseArray(val, parseStringElement)); // varchar[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1005, (val) => parseArray(val, parseIntElement)); // int2[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1007, (val) => parseArray(val, parseIntElement)); // int4[]
+// @ts-expect-error - pg types expects TypeId but raw OID numbers work fine
+types.setTypeParser(1016, (val) => parseArray(val, parseIntElement)); // int8[]
+const DEFAULT_POOL_MAX = Number(process.env.PGDELTA_POOL_MAX) || 5;
+const DEFAULT_CONNECTION_TIMEOUT_MS = Number(process.env.PGDELTA_CONNECTION_TIMEOUT_MS) || 3_000;
+const DEFAULT_CONNECT_TIMEOUT_MS = Number(process.env.PGDELTA_CONNECT_TIMEOUT_MS) || 2_500;
+/**
+ * Create a Pool with custom type handlers and optional event listeners.
+ */
+export function createPool(connectionString, options) {
+    const { onConnect, onError, onAcquire, onRemove, ...config } = options ?? {};
+    const pool = new Pool({
+        connectionString,
+        max: DEFAULT_POOL_MAX,
+        connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+        ...config,
+    });
+    if (onConnect) {
+        const pendingClientSetup = new WeakMap();
+        const waitForClientSetup = async (client) => {
+            const setup = pendingClientSetup.get(client);
+            if (setup) {
+                await setup;
+                return;
+            }
+            throw new Error("Internal error: pool client was acquired before async onConnect setup was registered. This indicates a bug in the pool wrapper logic; please report it with reproduction steps.");
+        };
+        const originalConnect = pool.connect.bind(pool);
+        pool.on("connect", (client) => {
+            pendingClientSetup.set(client, Promise.resolve().then(() => onConnect(client)));
+        });
+        pool.connect = ((callback) => {
+            if (!callback) {
+                return originalConnect().then(async (client) => {
+                    try {
+                        await waitForClientSetup(client);
+                        return client;
+                    }
+                    catch (setupError) {
+                        client.release?.(setupError);
+                        throw setupError;
+                    }
+                });
+            }
+            return originalConnect(async (err, client, release) => {
+                if (err || !client) {
+                    callback(err, client, release);
+                    return;
+                }
+                try {
+                    await waitForClientSetup(client);
+                    callback(err, client, release);
+                }
+                catch (setupError) {
+                    release(setupError);
+                    callback(setupError, undefined, () => { });
+                }
+            });
+        });
+    }
+    if (onError)
+        pool.on("error", onError);
+    if (onAcquire)
+        pool.on("acquire", onAcquire);
+    if (onRemove)
+        pool.on("remove", onRemove);
+    return pool;
+}
+/**
+ * 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 async function createManagedPool(url, options) {
+    const sslConfig = await parseSslConfig(url, options?.label ?? "target");
+    const pool = createPool(sslConfig.cleanedUrl, {
+        ...(sslConfig.ssl !== undefined ? { ssl: sslConfig.ssl } : {}),
+        onError: (err) => {
+            if (err.code !== "57P01") {
+                console.error("Pool error:", err);
+            }
         },
-        // Handle bigint values from PostgreSQL
-        bigint: {
-            // The pg_types oid for bigint (20 is the OID for int8/bigint)
-            to: 20,
-            // Array of pg_types oids to handle when parsing values coming from the db
-            from: [20],
-            // Parse bigint string to JavaScript BigInt
-            parse: (value) => {
-                return BigInt(value);
-            },
-            // Serialize BigInt back to string for PostgreSQL
-            serialize: (value) => {
-                return value.toString();
-            },
+        onConnect: async (client) => {
+            await client.query("SET search_path = ''");
+            if (options?.role) {
+                await client.query(`SET ROLE ${escapeIdentifier(options.role)}`);
+            }
         },
-    },
-};
+    });
+    // Eagerly validate connectivity so SSL/auth failures surface immediately
+    // instead of hanging on the first real query. node-pg's connectionTimeoutMillis
+    // is not reliably enforced under Bun when SSL negotiation hangs.
+    const label = options?.label ?? "target";
+    const timeoutMs = DEFAULT_CONNECT_TIMEOUT_MS;
+    try {
+        const client = await Promise.race([
+            pool.connect(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Connection to ${label} database timed out after ${timeoutMs}ms. ` +
+                `The server may require SSL, use an invalid certificate, or be unreachable.`)), timeoutMs)),
+        ]);
+        client.release();
+    }
+    catch (err) {
+        await pool.end().catch(() => { });
+        throw err;
+    }
+    return { pool, close: () => endPool(pool) };
+}
+export function endPool(pool) {
+    const clientCount = pool.totalCount;
+    if (clientCount === 0) {
+        return pool.end();
+    }
+    return new Promise((resolve, reject) => {
+        let removed = 0;
+        pool.on("remove", function onRemove() {
+            if (++removed >= clientCount) {
+                pool.removeListener("remove", onRemove);
+                resolve();
+            }
+        });
+        pool.end().catch(reject);
+    });
+}

package/dist/core/sort/graph-builder.js

@@ -56,7 +56,17 @@ export function convertExplicitRequirementsToConstraints(phaseChanges, graphData
         const requiredIds = graphData.explicitRequirementSets[consumerIndex];
         if (requiredIds.size === 0)
             continue;
+        // Collect dropped IDs for this change so we can skip requirements
+        // for stableIds that this change also drops.  A change that drops a
+        // stableId should not depend on another change that creates the same
+        // stableId, because the entity already exists in the source database.
+        // This prevents false ordering constraints such as Grant → Revoke
+        // when both operate on the same ACL stableId.
+        const droppedIds = new Set(phaseChanges[consumerIndex].drops);
         for (const requiredId of requiredIds) {
+            if (droppedIds.has(requiredId)) {
+                continue;
+            }
             const producerIndexes = graphData.changeIndexesByCreatedId.get(requiredId);
             if (!producerIndexes || producerIndexes.size === 0)
                 continue;

package/dist/core/sort/logical-sort.js

@@ -145,6 +145,25 @@ function getMainStableId(change) {
         }
         return null;
     }
+    // For default_privilege operations: group by role + schema combination (before CREATE so we group and use tiebreaker)
+    if (change.scope === "default_privilege") {
+        if (change.requires.length > 0) {
+            let grantingRole = null;
+            let schemaId = null;
+            for (const id of change.requires) {
+                if (id.startsWith("role:")) {
+                    grantingRole = id;
+                }
+                else if (id.startsWith("schema:")) {
+                    schemaId = id;
+                }
+            }
+            if (schemaId && grantingRole) {
+                return `${grantingRole}:${schemaId}`;
+            }
+            return grantingRole ?? null;
+        }
+    }
     // For CREATE operations: check if creating a constraint (sub-entity of table)
     if (change.operation === "create" && change.creates.length > 0) {
         // Iterate through creates to find the first non-metadata stable ID
@@ -182,29 +201,6 @@ function getMainStableId(change) {
         // Fallback: if all drops are metadata, use first
         return change.drops[0] ?? null;
     }
-    // For default_privilege operations: group by role + schema combination
-    // This groups all "FOR ROLE X IN SCHEMA Y" statements together
-    if (change.scope === "default_privilege") {
-        if (change.requires.length > 0) {
-            // Iterate through requires to find role and schema
-            let grantingRole = null;
-            let schemaId = null;
-            for (const id of change.requires) {
-                if (id.startsWith("role:")) {
-                    grantingRole = id;
-                }
-                else if (id.startsWith("schema:")) {
-                    schemaId = id;
-                }
-            }
-            if (schemaId && grantingRole) {
-                // Create composite key: "role:postgres:schema:public"
-                return `${grantingRole}:${schemaId}`;
-            }
-            // If no schema, just group by role
-            return grantingRole ?? null;
-        }
-    }
     // For ALTER operations: check if creating/dropping a constraint
     // Skip this for privilege/comment/default_privilege scopes (handled above)
     if (change.operation === "alter") {
@@ -525,6 +521,18 @@ function sortPhase(changes, phase) {
         if (operationOrderA !== operationOrderB) {
             return operationOrderA - operationOrderB;
         }
+        // 6b. For default_privilege: deterministic tiebreaker by objtype then grantee (canonical order for objtype)
+        if (scopeA === "default_privilege" && scopeB === "default_privilege") {
+            const defPrivA = changeA;
+            const defPrivB = changeB;
+            const objtypeOrder = (code) => ({ n: 0, r: 1, S: 2, f: 3, T: 4 })[code] ?? 99;
+            const objtypeCompare = objtypeOrder(defPrivA.objtype) - objtypeOrder(defPrivB.objtype);
+            if (objtypeCompare !== 0)
+                return objtypeCompare;
+            const granteeCompare = defPrivA.grantee.localeCompare(defPrivB.grantee);
+            if (granteeCompare !== 0)
+                return granteeCompare;
+        }
         // 7. Preserve original order (stability)
         return a.originalIndex - b.originalIndex;
     });

package/dist/core/test-utils/assert-valid-sql.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export declare function assertValidSql(sql: string): Promise<void>;

package/dist/core/test-utils/assert-valid-sql.js

@@ -0,0 +1,19 @@
+import { validateSqlSyntax } from "@supabase/pg-topo";
+/**
+ * Assert that the given SQL string is syntactically valid PostgreSQL.
+ *
+ * Uses the PostgreSQL parser from `@supabase/pg-topo` to ensure that
+ * serialized DDL statements are syntactically correct. This catches
+ * issues like malformed function signatures, missing keywords, etc.
+ *
+ * @param sql - The SQL string to validate (typically from `change.serialize()`).
+ */
+export async function assertValidSql(sql) {
+    try {
+        await validateSqlSyntax(sql);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown parser error";
+        throw new Error(`Invalid SQL syntax: ${message}\nSQL: ${sql}`);
+    }
+}

package/dist/index.d.ts

@@ -1 +1,18 @@
-export * from "./core/index.ts";
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.ts";
+export type { CatalogSnapshot } from "./core/catalog.snapshot.ts";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.ts";
+export { exportDeclarativeSchema } from "./core/export/index.ts";
+export type { DeclarativeSchemaOutput, FileCategory, FileEntry, FileMetadata, } from "./core/export/types.ts";
+export type { IntegrationDSL } from "./core/integrations/integration-dsl.ts";
+export { applyPlan } from "./core/plan/apply.ts";
+export type { CatalogInput } from "./core/plan/create.ts";
+export { createPlan } from "./core/plan/create.ts";
+export type { SqlFormatOptions } from "./core/plan/sql-format.ts";
+export { formatSqlStatements } from "./core/plan/sql-format.ts";
+export type { CreatePlanOptions, Plan } from "./core/plan/types.ts";
+export { createManagedPool } from "./core/postgres-config.ts";

package/dist/index.js

@@ -1 +1,16 @@
-export * from "./core/index.js";
+/**
+ * @supabase/pg-delta - PostgreSQL migrations made easy
+ *
+ * This module exports the public API for the pg-delta library.
+ */
+// Catalog model and extraction
+export { Catalog, createEmptyCatalog, extractCatalog, } from "./core/catalog.model.js";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "./core/catalog.snapshot.js";
+// Declarative schema export
+export { exportDeclarativeSchema } from "./core/export/index.js";
+// Plan operations
+export { applyPlan } from "./core/plan/apply.js";
+export { createPlan } from "./core/plan/create.js";
+export { formatSqlStatements } from "./core/plan/sql-format.js";
+// Postgres config
+export { createManagedPool } from "./core/postgres-config.js";

package/package.json

@@ -1,15 +1,47 @@
 {
   "name": "@supabase/pg-delta",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.10",
   "description": "PostgreSQL migrations made easy",
   "type": "module",
   "sideEffects": false,
-  "exports": "./dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./integrations/supabase": {
+      "bun": "./src/core/integrations/supabase.ts",
+      "import": "./dist/core/integrations/supabase.js",
+      "require": "./dist/core/integrations/supabase.js",
+      "types": "./dist/core/integrations/supabase.d.ts",
+      "default": "./dist/core/integrations/supabase.js"
+    },
+    "./declarative": {
+      "bun": "./src/core/declarative-apply/index.ts",
+      "import": "./dist/core/declarative-apply/index.js",
+      "require": "./dist/core/declarative-apply/index.js",
+      "types": "./dist/core/declarative-apply/index.d.ts",
+      "default": "./dist/core/declarative-apply/index.js"
+    },
+    "./catalog-export": {
+      "bun": "./src/core/catalog-export/index.ts",
+      "import": "./dist/core/catalog-export/index.js",
+      "require": "./dist/core/catalog-export/index.js",
+      "types": "./dist/core/catalog-export/index.d.ts",
+      "default": "./dist/core/catalog-export/index.js"
+    }
+  },
   "bin": {
     "pgdelta": "./dist/cli/bin/cli.js"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -23,43 +55,48 @@
   ],
   "author": "Supabase",
   "license": "MIT",
-  "homepage": "https://github.com/supabase/pg-delta",
+  "homepage": "https://github.com/supabase/pg-toolbelt",
   "repository": {
     "type": "git",
-    "url": "https://github.com/supabase/pg-delta.git"
+    "url": "https://github.com/supabase/pg-toolbelt.git",
+    "directory": "packages/pg-delta"
   },
-  "bugs": "https://github.com/supabase/pg-delta/issues",
+  "bugs": "https://github.com/supabase/pg-toolbelt/issues",
   "engines": {
     "node": ">=20.0.0"
   },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "format-and-lint": "biome check . --error-on-warnings",
+    "knip": "knip",
+    "pgdelta": "bun src/cli/bin/cli.ts",
+    "test": "bun scripts/run-tests.ts",
+    "test:unit": "bun run test src/",
+    "test:integration": "bun run test tests/",
+    "update-empty-baseline": "bun scripts/update-empty-catalog-baseline.ts",
+    "version": "changeset version && bun install --no-frozen-lockfile && bun run format-and-lint --write"
+  },
   "dependencies": {
     "@stricli/core": "^1.2.4",
+    "@ts-safeql/sql-tag": "^0.2.0",
+    "@supabase/pg-topo": "^1.0.0-alpha.1",
     "chalk": "^5.6.2",
     "debug": "^4.3.7",
-    "postgres": "^3.4.7",
+    "pg": "^8.17.2",
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.10",
-    "@changesets/cli": "^2.29.8",
+    "@supabase/bun-istanbul-coverage": "workspace:*",
     "@tsconfig/node-ts": "^23.6.2",
     "@tsconfig/node24": "^24.0.3",
+    "@types/bun": "^1.3.9",
     "@types/debug": "^4.1.12",
     "@types/node": "^24.10.4",
-    "@vitest/coverage-v8": "4.0.16",
+    "@types/pg": "^8.11.10",
     "dedent": "^1.7.1",
     "knip": "^5.75.2",
     "testcontainers": "^11.10.0",
-    "typescript": "^5.9.3",
-    "vitest": "^4.0.16"
-  },
-  "scripts": {
-    "build": "tsc --project tsconfig.build.json",
-    "check-types": "tsc --noEmit",
-    "format-and-lint": "biome check . --error-on-warnings",
-    "knip": "knip",
-    "pgdelta": "node src/cli/bin/cli.ts",
-    "test": "vitest",
-    "version": "changeset version && pnpm install --no-frozen-lockfile && pnpm format-and-lint --write"
+    "typescript": "^5.9.3"
   }
-}
+}

package/src/cli/app.ts

@@ -0,0 +1,52 @@
+import { buildApplication, buildRouteMap } from "@stricli/core";
+import { applyCommand } from "./commands/apply.ts";
+import { catalogExportCommand } from "./commands/catalog-export.ts";
+import { declarativeApplyCommand } from "./commands/declarative-apply.ts";
+import { declarativeExportCommand } from "./commands/declarative-export.ts";
+import { planCommand } from "./commands/plan.ts";
+import { syncCommand } from "./commands/sync.ts";
+
+const declarativeRouteMap = buildRouteMap({
+  routes: {
+    apply: declarativeApplyCommand,
+    export: declarativeExportCommand,
+  },
+  docs: {
+    brief: "Declarative schema management",
+    fullDescription: `
+Manage declarative SQL schemas.
+
+Commands:
+  apply  - Apply a declarative SQL schema to a database
+  export - Export a declarative schema from a database diff
+    `.trim(),
+  },
+});
+
+const root = buildRouteMap({
+  routes: {
+    plan: planCommand,
+    apply: applyCommand,
+    sync: syncCommand,
+    declarative: declarativeRouteMap,
+    "catalog-export": catalogExportCommand,
+  },
+  defaultCommand: "sync",
+  docs: {
+    brief: "PostgreSQL migrations made easy",
+    fullDescription: `
+pgdelta generates migration scripts by comparing two PostgreSQL databases.
+
+Commands:
+  plan           - Compute schema diff and preview changes
+  apply          - Apply a plan's migration script to a database
+  sync           - Plan and apply changes in one go
+  declarative    - Declarative schema (apply | export)
+  catalog-export - Export a database catalog as a snapshot JSON file
+    `.trim(),
+  },
+});
+
+export const app = buildApplication(root, {
+  name: "pgdelta",
+});

package/src/cli/bin/cli.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { run } from "@stricli/core";
+import { app } from "../app.ts";
+import { getCommandExitCode } from "../exit-code.ts";
+
+await run(app, process.argv.slice(2), { process }).catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+
+const code = getCommandExitCode();
+if (code !== undefined) {
+  process.exitCode = code;
+}