@supabase/pg-delta 1.0.0-alpha.3 → 1.0.0-alpha.5

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

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

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

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

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

@@ -0,0 +1,165 @@
+import { indentString } from "./format-utils.js";
+import { isWordChar, walkSql } from "./sql-scanner.js";
+/**
+ * Keywords that are preferred break points when wrapping long lines.
+ * The wrapper will prefer to break just before one of these keywords
+ * rather than at an arbitrary whitespace position.
+ */
+const WRAP_PREFERRED_KEYWORDS = new Set([
+    "ADD",
+    "CHECK",
+    "CONNECTION",
+    "CONSTRAINT",
+    "DEFERRABLE",
+    "FOREIGN",
+    "HANDLER",
+    "INCLUDE",
+    "INITIALLY",
+    "INLINE",
+    "MATCH",
+    "NOT",
+    "ON",
+    "OPTIONS",
+    "PUBLICATION",
+    "REFERENCES",
+    "REFERENCING",
+    "SET",
+    "USING",
+    "VALIDATOR",
+    "WHERE",
+    "WITH",
+]);
+export function wrapStatement(statement, options, noWrapPlaceholders) {
+    const lines = statement.split(/\r?\n/);
+    const wrapped = [];
+    for (const line of lines) {
+        if (line.trim().startsWith("--")) {
+            wrapped.push(line);
+            continue;
+        }
+        if (hasNoWrapPlaceholder(line, noWrapPlaceholders)) {
+            wrapped.push(line);
+            continue;
+        }
+        wrapped.push(...wrapLine(line, options));
+    }
+    return wrapped.join("\n");
+}
+function hasNoWrapPlaceholder(line, placeholders) {
+    for (const token of placeholders) {
+        if (line.includes(token))
+            return true;
+    }
+    return false;
+}
+function wrapLine(line, options) {
+    const maxWidth = options.maxWidth;
+    if (maxWidth <= 0 || line.length <= maxWidth) {
+        return [line];
+    }
+    const indentMatch = line.match(/^\s*/);
+    const baseIndent = indentMatch ? indentMatch[0] : "";
+    const continuationIndent = `${baseIndent}${indentString(options.indent)}`;
+    let remaining = line;
+    const output = [];
+    while (remaining.length > maxWidth) {
+        const breakpoint = findWrapPosition(remaining, maxWidth);
+        if (breakpoint <= 0)
+            break;
+        const head = remaining.slice(0, breakpoint).trimEnd();
+        const tail = remaining.slice(breakpoint).trimStart();
+        output.push(head);
+        const next = `${continuationIndent}${tail}`;
+        if (next.length >= remaining.length) {
+            remaining = next;
+            break;
+        }
+        remaining = next;
+    }
+    output.push(remaining);
+    return output;
+}
+/** Words that should not be separated from the previous word when wrapping (e.g. CREATE PUBLICATION, COMMENT ON). */
+const KEEP_WITH_PREVIOUS = new Set([
+    "PUBLICATION",
+    "TABLE",
+    "VIEW",
+    "SCHEMA",
+    "INDEX",
+    "OR", // CREATE OR REPLACE
+    "ON", // COMMENT ON
+]);
+function getPreviousWord(text, beforeIndex) {
+    let end = beforeIndex - 1;
+    while (end >= 0 && (text[end] === " " || text[end] === "\t")) {
+        end -= 1;
+    }
+    if (end < 0 || !isWordChar(text[end]))
+        return null;
+    let start = end;
+    while (start > 0 && isWordChar(text[start - 1])) {
+        start -= 1;
+    }
+    return text.slice(start, end + 1).toUpperCase();
+}
+function findWrapPosition(text, maxWidth) {
+    /** Last whitespace at depth 0 (preferred — avoids splitting parenthesized expressions) */
+    let lastTopLevelWhitespace = -1;
+    /** Last whitespace at any depth (fallback when no depth-0 break exists) */
+    let lastAnyWhitespace = -1;
+    let lastKeywordBoundary = -1;
+    /** First (leftmost) top-level comma within maxWidth — break there so each clause gets its own line */
+    let firstComma = -1;
+    // Never break within the leading indent — that would produce an empty head line
+    const contentStart = text.search(/\S/);
+    if (contentStart < 0)
+        return -1; // all whitespace
+    walkSql(text, (index, char, depth) => {
+        if (index > maxWidth)
+            return false;
+        // Skip positions within leading indent
+        if (index < contentStart)
+            return true;
+        // Prefer breaking after the first top-level comma so comma-separated clauses (e.g. publication tables) each get their own line
+        if (char === "," && depth === 0 && firstComma < 0) {
+            firstComma = index + 1; // position after the comma
+        }
+        if (char === " " || char === "\t") {
+            lastAnyWhitespace = index;
+            if (depth === 0) {
+                lastTopLevelWhitespace = index;
+            }
+            // Check if the next word is a preferred keyword
+            const nextWordStart = index + 1;
+            if (nextWordStart < text.length && isWordChar(text[nextWordStart])) {
+                let wordEnd = nextWordStart + 1;
+                while (wordEnd < text.length && isWordChar(text[wordEnd])) {
+                    wordEnd += 1;
+                }
+                const word = text.slice(nextWordStart, wordEnd).toUpperCase();
+                if (WRAP_PREFERRED_KEYWORDS.has(word)) {
+                    // Don't break between CREATE and object type, COMMENT and ON, or ALL and ON (GRANT/REVOKE ALL ON)
+                    const prev = getPreviousWord(text, index);
+                    if (prev !== null &&
+                        ((prev === "CREATE" && KEEP_WITH_PREVIOUS.has(word)) ||
+                            ((prev === "COMMENT" || prev === "ALL") && word === "ON"))) {
+                        return true;
+                    }
+                    lastKeywordBoundary = index;
+                }
+            }
+        }
+        return true;
+    }, { trackDepth: true });
+    // Prefer: 1) comma, 2) keyword boundary, 3) depth-0 whitespace, 4) any whitespace
+    if (firstComma > 0 && firstComma <= maxWidth) {
+        return firstComma;
+    }
+    if (lastKeywordBoundary > 0 && lastKeywordBoundary <= maxWidth) {
+        return lastKeywordBoundary;
+    }
+    if (lastTopLevelWhitespace > 0) {
+        return lastTopLevelWhitespace;
+    }
+    return lastAnyWhitespace;
+}

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

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

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * SSL configuration parsing for PostgreSQL connection URLs.
+ *
+ * Supports sslmode and certificate paths (URL params or env). Used by plan,
+ * apply, and catalog-export when connecting to source/target databases.
+ */
+/** Parsed SSL options for the pg client plus URL with SSL params stripped (internal). */
+type SslConfig = {
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+        ca?: string;
+        cert?: string;
+        key?: string;
+        /**
+         * Custom server identity check function.
+         * Used to skip hostname verification for verify-ca mode.
+         * Returns undefined to indicate success (no error).
+         */
+        checkServerIdentity?: () => undefined;
+    };
+    cleanedUrl: string;
+};
+/**
+ * Parse SSL configuration from a PostgreSQL connection URL.
+ * Supports sslmode (require, verify-ca, verify-full, prefer, disable).
+ * Certificates can be provided via:
+ * - Query string parameters (file paths): sslrootcert, sslcert, sslkey (preferred)
+ * - Environment variables (content): PGDELTA_SOURCE_SSLROOTCERT/SSLCERT/SSLKEY or PGDELTA_TARGET_SSLROOTCERT/SSLCERT/SSLKEY
+ * Returns SSL options for the postgres.js library and a cleaned URL without SSL-related query parameters.
+ */
+export declare function parseSslConfig(url: string, connectionType: "source" | "target"): Promise<SslConfig>;
+export {};

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

@@ -0,0 +1,115 @@
+/**
+ * SSL configuration parsing for PostgreSQL connection URLs.
+ *
+ * Supports sslmode and certificate paths (URL params or env). Used by plan,
+ * apply, and catalog-export when connecting to source/target databases.
+ */
+import { readFile } from "node:fs/promises";
+/**
+ * Parse SSL configuration from a PostgreSQL connection URL.
+ * Supports sslmode (require, verify-ca, verify-full, prefer, disable).
+ * Certificates can be provided via:
+ * - Query string parameters (file paths): sslrootcert, sslcert, sslkey (preferred)
+ * - Environment variables (content): PGDELTA_SOURCE_SSLROOTCERT/SSLCERT/SSLKEY or PGDELTA_TARGET_SSLROOTCERT/SSLCERT/SSLKEY
+ * Returns SSL options for the postgres.js library and a cleaned URL without SSL-related query parameters.
+ */
+export async function parseSslConfig(url, connectionType) {
+    const urlObj = new URL(url);
+    const sslmode = urlObj.searchParams.get("sslmode");
+    const sslrootcert = urlObj.searchParams.get("sslrootcert");
+    const sslcert = urlObj.searchParams.get("sslcert");
+    const sslkey = urlObj.searchParams.get("sslkey");
+    // Remove SSL-related query parameters since we parse them ourselves
+    urlObj.searchParams.delete("sslmode");
+    urlObj.searchParams.delete("sslrootcert");
+    urlObj.searchParams.delete("sslcert");
+    urlObj.searchParams.delete("sslkey");
+    const cleanedUrl = urlObj.toString();
+    // Handle different SSL modes
+    if (sslmode === "disable") {
+        return { cleanedUrl, ssl: false };
+    }
+    if (sslmode === "require" ||
+        sslmode === "prefer" ||
+        sslmode === "verify-ca" ||
+        sslmode === "verify-full") {
+        // Helper function to get certificate value: query param (file path) takes precedence over env var (content)
+        const getCertValue = async (queryParam, envVarName) => {
+            // Prefer query parameter (file path)
+            if (queryParam) {
+                try {
+                    return await readFile(queryParam, "utf-8");
+                }
+                catch (error) {
+                    throw new Error(`Failed to read certificate file '${queryParam}': ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            // Fallback to environment variable (content)
+            const envValue = process.env[envVarName];
+            return envValue || undefined;
+        };
+        const hasExplicitVerification = sslmode === "verify-ca" || sslmode === "verify-full";
+        // Get CA certificate value.
+        // - verify-ca/verify-full: check query param first, then env var
+        // - require/prefer: only check query param (libpq backward compatibility
+        //   requires an explicit root CA *file*, not a global env var)
+        const caEnvVar = connectionType === "source"
+            ? "PGDELTA_SOURCE_SSLROOTCERT"
+            : "PGDELTA_TARGET_SSLROOTCERT";
+        let caValue;
+        if (sslrootcert) {
+            // Explicit file path in query param — always honour it
+            caValue = await getCertValue(sslrootcert, caEnvVar);
+        }
+        else if (hasExplicitVerification) {
+            // verify-ca / verify-full without file path — fall back to env var
+            caValue = await getCertValue(null, caEnvVar);
+        }
+        // require/prefer without sslrootcert: no CA cert, no verification
+        // Determine if we should verify the CA chain
+        //   From PostgreSQL docs: "if a root CA file exists, the behavior of sslmode=require
+        //   will be the same as that of verify-ca"
+        const hasLibpqCompatibility = (sslmode === "require" || sslmode === "prefer") && caValue !== undefined;
+        const shouldVerifyCa = hasExplicitVerification || hasLibpqCompatibility;
+        // Determine if we should verify hostname
+        // - verify-full: verify both CA and hostname
+        // - verify-ca: verify CA only (skip hostname)
+        // - require/prefer with CA (libpq compat): behaves like verify-ca (skip hostname)
+        const shouldVerifyHostname = sslmode === "verify-full";
+        const ssl = {
+            rejectUnauthorized: shouldVerifyCa,
+        };
+        // Add CA certificate if verifying
+        if (shouldVerifyCa && caValue) {
+            ssl.ca = caValue;
+        }
+        // For verify-ca and libpq compatibility mode: skip hostname verification
+        // This matches PostgreSQL semantics where verify-ca only checks the CA chain
+        if (shouldVerifyCa && !shouldVerifyHostname) {
+            ssl.checkServerIdentity = () => undefined;
+        }
+        // Get client certificate (optional, for mutual TLS)
+        const certEnvVar = connectionType === "source"
+            ? "PGDELTA_SOURCE_SSLCERT"
+            : "PGDELTA_TARGET_SSLCERT";
+        const certValue = await getCertValue(sslcert, certEnvVar);
+        if (certValue) {
+            ssl.cert = certValue;
+        }
+        // Get client key (optional, for mutual TLS, required if cert is provided)
+        const keyEnvVar = connectionType === "source"
+            ? "PGDELTA_SOURCE_SSLKEY"
+            : "PGDELTA_TARGET_SSLKEY";
+        const keyValue = await getCertValue(sslkey, keyEnvVar);
+        if (keyValue) {
+            ssl.key = keyValue;
+        }
+        // Warn if cert is provided without key (or vice versa)
+        if ((ssl.cert && !ssl.key) || (!ssl.cert && ssl.key)) {
+            throw new Error("Both client certificate and key must be provided together for mutual TLS");
+        }
+        return { ssl, cleanedUrl };
+    }
+    // No sslmode specified or invalid value - explicitly disable SSL
+    return { cleanedUrl, ssl: false };
+}

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

@@ -1,8 +1,9 @@
 /**
  * SQL script formatting utilities.
  */
+import { type SqlFormatOptions } from "./sql-format.ts";
 /**
  * Format an array of SQL statements into a single script string.
  * Statements are joined with double newlines and the script ends with a semicolon.
  */
-export declare function formatSqlScript(statements: string[]): string;
+export declare function formatSqlScript(statements: string[], options?: SqlFormatOptions): string;

package/dist/core/plan/statements.js

@@ -1,13 +1,17 @@
 /**
  * SQL script formatting utilities.
  */
+import { formatSqlStatements } from "./sql-format.js";
 const STATEMENT_DELIMITER = ";\n\n";
 /**
  * Format an array of SQL statements into a single script string.
  * Statements are joined with double newlines and the script ends with a semicolon.
  */
-export function formatSqlScript(statements) {
+export function formatSqlScript(statements, options) {
     if (statements.length === 0)
         return "";
-    return `${statements.join(STATEMENT_DELIMITER)};`;
+    const formatted = options
+        ? formatSqlStatements(statements, options)
+        : statements;
+    return `${formatted.join(STATEMENT_DELIMITER)};`;
 }

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

@@ -138,5 +138,11 @@ export interface CreatePlanOptions {
     serialize?: SerializeDSL | ChangeSerializer;
     /** Role to use when executing the migration (SET ROLE will be added to statements) */
     role?: string;
+    /**
+     * When true, don't subtract privileges covered by ALTER DEFAULT PRIVILEGES
+     * from explicit GRANTs during diffing. Use this for declarative export where
+     * the output must be self-contained and not rely on statement execution order.
+     */
+    skipDefaultPrivilegeSubtraction?: boolean;
 }
 export {};

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

@@ -20,4 +20,33 @@ interface CreatePoolOptions extends Partial<PoolConfig> {
  * Create a Pool with custom type handlers and optional event listeners.
  */
 export declare function createPool(connectionString: string, options?: CreatePoolOptions): 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 declare function createManagedPool(url: string, options?: {
+    role?: string;
+    label?: "source" | "target";
+}): Promise<{
+    pool: Pool;
+    close: () => Promise<void>;
+}>;
+export declare function endPool(pool: Pool): Promise<void>;
 export {};

package/dist/core/postgres-config.js

@@ -1,7 +1,8 @@
 /**
  * PostgreSQL connection configuration with custom type handlers.
  */
-import { Pool, types } from "pg";
+import { escapeIdentifier, Pool, types } from "pg";
+import { parseSslConfig } from "./plan/ssl-config.js";
 // ============================================================================
 // Array Parser
 // ============================================================================
@@ -92,12 +93,20 @@ types.setTypeParser(1005, (val) => parseArray(val, parseIntElement)); // int2[]
 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, ...config });
+    const pool = new Pool({
+        connectionString,
+        max: DEFAULT_POOL_MAX,
+        connectionTimeoutMillis: DEFAULT_CONNECTION_TIMEOUT_MS,
+        ...config,
+    });
     if (onConnect)
         pool.on("connect", onConnect);
     if (onError)
@@ -108,3 +117,75 @@ export function createPool(connectionString, options) {
         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);
+            }
+        },
+        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

@@ -3,7 +3,15 @@
  *
  * 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";