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

package/dist/cli/utils/export-display.js

@@ -0,0 +1,202 @@
+/**
+ * CLI helpers for declarative export: file tree, diff, and summary formatting.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+// ============================================================================
+// Path safety
+// ============================================================================
+/**
+ * Ensure a relative file path does not escape the output directory.
+ * Uses Node.js path.resolve + startsWith as the canonical traversal check.
+ */
+export function assertSafePath(filePath, outputDir) {
+    const resolvedOutput = path.resolve(outputDir);
+    const resolvedFile = path.resolve(outputDir, filePath);
+    if (resolvedFile !== resolvedOutput &&
+        !resolvedFile.startsWith(resolvedOutput + path.sep)) {
+        throw new Error(`Export path traversal detected: '${filePath}' resolves outside output directory`);
+    }
+}
+function getFileStatus(path, diff) {
+    if (diff.created.includes(path))
+        return "created";
+    if (diff.updated.includes(path))
+        return "updated";
+    if (diff.deleted.includes(path))
+        return "deleted";
+    return "unchanged";
+}
+function formatLeafSegment(segment, status) {
+    switch (status) {
+        case "created":
+            return chalk.green(`+ ${segment}`);
+        case "updated":
+            return chalk.yellow(`~ ${segment}`);
+        case "deleted":
+            return chalk.red(`- ${segment}`);
+        default:
+            return chalk.dim(segment);
+    }
+}
+/**
+ * Build a directory tree string from file paths.
+ * Groups by directory, shows files as leaves with indentation.
+ * When options.diff is provided, leaf names are prefixed with + (created), ~ (updated), - (deleted) and colorized.
+ * When options.diffFocus is true, only changed paths (and their ancestors) are shown; unchanged files are omitted.
+ *
+ * @param files - Array of relative file paths (e.g. ["schemas/public/schema.sql", "schemas/public/tables/users.sql"])
+ * @param outputDir - Display name for the root (e.g. "declarative-schemas")
+ * @param options - Optional diff and diffFocus for symbols and filtering
+ */
+export function buildFileTree(files, outputDir, options) {
+    const { diff, diffFocus } = options ?? {};
+    let pathsToShow = files;
+    if (diffFocus && diff) {
+        const changed = new Set([
+            ...diff.created,
+            ...diff.updated,
+            ...diff.deleted,
+        ]);
+        pathsToShow = [...changed];
+        if (pathsToShow.length === 0) {
+            return chalk.dim("(no file changes)");
+        }
+    }
+    const tree = new Map();
+    for (const filePath of pathsToShow) {
+        const segments = filePath.split("/");
+        let parent = "";
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            const fullPath = parent ? `${parent}/${segment}` : segment;
+            let children = tree.get(parent);
+            if (!children) {
+                children = new Set();
+                tree.set(parent, children);
+            }
+            children.add(fullPath);
+            parent = fullPath;
+        }
+    }
+    const lines = [];
+    function emit(relPath, indent, isLast) {
+        const segment = relPath ? path.basename(relPath) : outputDir;
+        const prefix = indent === 0 ? "" : "  ".repeat(indent) + (isLast ? "└── " : "├── ");
+        const isLeaf = !tree.has(relPath);
+        const displaySegment = diff && isLeaf
+            ? formatLeafSegment(segment, getFileStatus(relPath, diff))
+            : segment;
+        lines.push(prefix + displaySegment);
+        const children = tree.get(relPath);
+        if (children) {
+            const sorted = [...children].sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+            for (let i = 0; i < sorted.length; i++) {
+                emit(sorted[i], indent + 1, i === sorted.length - 1);
+            }
+        }
+    }
+    emit("", 0, false);
+    return lines.join("\n");
+}
+// ============================================================================
+// File diff
+// ============================================================================
+/**
+ * Recursively collect relative paths of managed (.sql) files under a directory.
+ * Non-SQL files (README, .gitkeep, etc.) are intentionally excluded so they
+ * are never flagged as "deleted" during diff.
+ */
+async function collectExistingFiles(dir, base = "") {
+    const entries = await readdir(path.join(dir, base), { withFileTypes: true });
+    const files = [];
+    for (const e of entries) {
+        const rel = base ? `${base}/${e.name}` : e.name;
+        if (e.isFile() && e.name.endsWith(".sql")) {
+            files.push(rel);
+        }
+        else if (e.isDirectory()) {
+            files.push(...(await collectExistingFiles(dir, rel)));
+        }
+    }
+    return files;
+}
+/**
+ * Compare existing output directory with new file set.
+ * Returns created, updated, deleted, and unchanged paths.
+ */
+export async function computeFileDiff(outputDir, newFiles) {
+    const newPaths = new Set(newFiles.map((f) => f.path));
+    const newByPath = new Map(newFiles.map((f) => [f.path, f]));
+    let existingPaths = [];
+    try {
+        existingPaths = await collectExistingFiles(outputDir);
+    }
+    catch {
+        // Directory doesn't exist or not readable
+        return {
+            created: [...newPaths],
+            updated: [],
+            deleted: [],
+            unchanged: [],
+        };
+    }
+    const existingSet = new Set(existingPaths);
+    const created = [];
+    const updated = [];
+    const deleted = [];
+    const unchanged = [];
+    for (const p of newPaths) {
+        if (!existingSet.has(p)) {
+            created.push(p);
+        }
+        else {
+            const entry = newByPath.get(p);
+            if (!entry)
+                continue;
+            try {
+                const existingContent = await readFile(path.join(outputDir, p), "utf-8");
+                if (existingContent.trim() !== entry.sql.trim()) {
+                    updated.push(p);
+                }
+                else {
+                    unchanged.push(p);
+                }
+            }
+            catch {
+                updated.push(p);
+            }
+        }
+    }
+    for (const p of existingPaths) {
+        if (!newPaths.has(p)) {
+            deleted.push(p);
+        }
+    }
+    return { created, updated, deleted, unchanged };
+}
+// ============================================================================
+// Summary formatting
+// ============================================================================
+/**
+ * Format the created/deleted/updated summary with colors.
+ * In dry-run mode, uses "would create/delete/update" phrasing.
+ */
+export function formatExportSummary(diff, dryRun) {
+    const lines = [];
+    const verb = dryRun ? "Would" : "";
+    if (diff.created.length > 0) {
+        lines.push(chalk.green(`${verb ? `${verb} create` : "Created"}: ${diff.created.length} file(s)`));
+    }
+    if (diff.updated.length > 0) {
+        lines.push(chalk.yellow(`${verb ? `${verb} update` : "Updated"}: ${diff.updated.length} file(s)`));
+    }
+    if (diff.deleted.length > 0) {
+        lines.push(chalk.red(`${verb ? `${verb} delete` : "Deleted"}: ${diff.deleted.length} file(s)`));
+    }
+    if (diff.unchanged.length > 0 && !dryRun) {
+        lines.push(chalk.dim(`Unchanged: ${diff.unchanged.length} file(s)`));
+    }
+    return lines.length > 0 ? lines.join("\n") : "";
+}

package/dist/cli/utils/resolve-input.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared utilities for resolving CLI --source/--target inputs that
+ * can be either a PostgreSQL connection URL or a catalog snapshot file path.
+ */
+import type { Catalog } from "../../core/catalog.model.ts";
+export declare function isPostgresUrl(input: string): boolean;
+export declare function loadCatalogFromFile(path: string): Promise<Catalog>;

package/dist/cli/utils/resolve-input.js

@@ -0,0 +1,13 @@
+/**
+ * Shared utilities for resolving CLI --source/--target inputs that
+ * can be either a PostgreSQL connection URL or a catalog snapshot file path.
+ */
+import { readFile } from "node:fs/promises";
+import { deserializeCatalog } from "../../core/catalog.snapshot.js";
+export function isPostgresUrl(input) {
+    return input.startsWith("postgres://") || input.startsWith("postgresql://");
+}
+export async function loadCatalogFromFile(path) {
+    const json = await readFile(path, "utf-8");
+    return deserializeCatalog(JSON.parse(json));
+}

package/dist/cli/utils.d.ts

@@ -5,6 +5,7 @@ import type { CommandContext } from "@stricli/core";
 import type { Change } from "../core/change.types.ts";
 import type { DiffContext } from "../core/context.ts";
 import { type Plan } from "../core/plan/index.ts";
+import type { SqlFormatOptions } from "../core/plan/sql-format.ts";
 type ApplyPlanResult = {
     status: "invalid_plan";
     message: string;
@@ -31,6 +32,7 @@ type PlanResult = {
 interface FormatPlanOptions {
     disableColors?: boolean;
     showUnsafeFlagSuggestion?: boolean;
+    sqlFormatOptions?: SqlFormatOptions;
 }
 /**
  * Formats a plan result for display in various formats.

package/dist/cli/utils.js

@@ -19,7 +19,7 @@ export function formatPlanForDisplay(planResult, format, options = {}) {
         case "sql": {
             const content = [
                 `-- Risk: ${risk.level === "data_loss" ? `data-loss (${risk.statements.length})` : "safe"}`,
-                formatSqlScript(plan.statements),
+                formatSqlScript(plan.statements, options.sqlFormatOptions),
             ].join("\n");
             return { content, label: "Migration script" };
         }

package/dist/core/catalog-export/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Catalog export – programmatic API for extracting a database catalog
+ * and serializing it to a JSON snapshot.
+ *
+ * Use this subpath when you only need catalog export (e.g. Supabase CLI
+ * edge-runtime templates) without pulling in the full pg-delta API.
+ */
+export { Catalog, createEmptyCatalog, extractCatalog, } from "../catalog.model.ts";
+export type { CatalogSnapshot } from "../catalog.snapshot.ts";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "../catalog.snapshot.ts";
+export { createManagedPool } from "../postgres-config.ts";

package/dist/core/catalog-export/index.js

@@ -0,0 +1,10 @@
+/**
+ * Catalog export – programmatic API for extracting a database catalog
+ * and serializing it to a JSON snapshot.
+ *
+ * Use this subpath when you only need catalog export (e.g. Supabase CLI
+ * edge-runtime templates) without pulling in the full pg-delta API.
+ */
+export { Catalog, createEmptyCatalog, extractCatalog, } from "../catalog.model.js";
+export { deserializeCatalog, serializeCatalog, stringifyCatalogSnapshot, } from "../catalog.snapshot.js";
+export { createManagedPool } from "../postgres-config.js";

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

@@ -2,4 +2,5 @@ import type { Catalog } from "./catalog.model.ts";
 import type { Change } from "./change.types.ts";
 export declare function diffCatalogs(main: Catalog, branch: Catalog, options?: {
     role?: string;
+    skipDefaultPrivilegeSubtraction?: boolean;
 }): Change[];

package/dist/core/catalog.diff.js

@@ -29,6 +29,48 @@ import { diffEnums } from "./objects/type/enum/enum.diff.js";
 import { diffRanges } from "./objects/type/range/range.diff.js";
 import { stringifyWithBigInt } from "./objects/utils.js";
 import { diffViews } from "./objects/view/view.diff.js";
+/**
+ * Get the stableId of the target object for a privilege change.
+ * Used to filter out redundant REVOKE statements for dropped objects.
+ */
+function getPrivilegeTargetStableId(change) {
+    switch (change.objectType) {
+        case "composite_type":
+            return change.compositeType.stableId;
+        case "domain":
+            return change.domain.stableId;
+        case "enum":
+            return change.enum.stableId;
+        case "language":
+            return change.language.stableId;
+        case "materialized_view":
+            return change.materializedView.stableId;
+        case "aggregate":
+            return change.aggregate.stableId;
+        case "procedure":
+            return change.procedure.stableId;
+        case "range":
+            return change.range.stableId;
+        case "schema":
+            return change.schema.stableId;
+        case "sequence":
+            return change.sequence.stableId;
+        case "table":
+            return change.table.stableId;
+        case "view":
+            return change.view.stableId;
+        case "foreign_data_wrapper":
+            return change.foreignDataWrapper.stableId;
+        case "server":
+            return change.server.stableId;
+        case "foreign_table":
+            return change.foreignTable.stableId;
+        default: {
+            const _exhaustive = change;
+            return _exhaustive;
+        }
+    }
+}
 export function diffCatalogs(main, branch, options) {
     const changes = [];
     // Step 1: Diff roles first to get default privilege changes
@@ -38,13 +80,22 @@ export function diffCatalogs(main, branch, options) {
     // This represents what defaults will be in effect after all ALTER DEFAULT PRIVILEGES
     // Since ALTER DEFAULT PRIVILEGES runs before CREATE (via constraint spec),
     // all created objects will use these final defaults.
-    const defaultPrivilegeState = new DefaultPrivilegeState(main.roles);
-    for (const change of roleChanges) {
-        if (change instanceof GrantRoleDefaultPrivileges) {
-            defaultPrivilegeState.applyGrant(change.role.name, change.objtype, change.inSchema, change.grantee, change.privileges);
-        }
-        else if (change instanceof RevokeRoleDefaultPrivileges) {
-            defaultPrivilegeState.applyRevoke(change.role.name, change.objtype, change.inSchema, change.grantee, change.privileges);
+    //
+    // When skipDefaultPrivilegeSubtraction is true, we use an empty state so that
+    // getEffectiveDefaults always returns [] -- no privileges are subtracted and
+    // every GRANT is emitted explicitly.  This is needed for declarative export
+    // where the output must be self-contained regardless of statement execution order.
+    const defaultPrivilegeState = options?.skipDefaultPrivilegeSubtraction
+        ? new DefaultPrivilegeState({})
+        : new DefaultPrivilegeState(main.roles);
+    if (!options?.skipDefaultPrivilegeSubtraction) {
+        for (const change of roleChanges) {
+            if (change instanceof GrantRoleDefaultPrivileges) {
+                defaultPrivilegeState.applyGrant(change.role.name, change.objtype, change.inSchema, change.grantee, change.privileges);
+            }
+            else if (change instanceof RevokeRoleDefaultPrivileges) {
+                defaultPrivilegeState.applyRevoke(change.role.name, change.objtype, change.inSchema, change.grantee, change.privileges);
+            }
         }
     }
     // Step 3: Create context with default privileges state for object diffing
@@ -58,25 +109,26 @@ export function diffCatalogs(main, branch, options) {
         currentUser: effectiveUser,
         defaultPrivilegeState,
         mainRoles: main.roles,
+        skipDefaultPrivilegeSubtraction: options?.skipDefaultPrivilegeSubtraction,
     };
     // Step 4: Diff all other objects with default privileges context
     changes.push(...diffAggregates(diffContext, main.aggregates, branch.aggregates));
-    changes.push(...diffCollations({ currentUser: effectiveUser }, main.collations, branch.collations));
+    changes.push(...diffCollations(diffContext, main.collations, branch.collations));
     changes.push(...diffCompositeTypes(diffContext, main.compositeTypes, branch.compositeTypes));
     changes.push(...diffDomains(diffContext, main.domains, branch.domains));
     changes.push(...diffEnums(diffContext, main.enums, branch.enums));
     changes.push(...diffExtensions(main.extensions, branch.extensions));
     changes.push(...diffIndexes(main.indexes, branch.indexes, branch.indexableObjects));
     changes.push(...diffMaterializedViews(diffContext, main.materializedViews, branch.materializedViews));
-    changes.push(...diffSubscriptions({ currentUser: effectiveUser }, main.subscriptions, branch.subscriptions));
-    changes.push(...diffPublications({ currentUser: effectiveUser }, main.publications, branch.publications));
+    changes.push(...diffSubscriptions(diffContext, main.subscriptions, branch.subscriptions));
+    changes.push(...diffPublications(diffContext, main.publications, branch.publications));
     changes.push(...diffProcedures(diffContext, main.procedures, branch.procedures));
     changes.push(...diffRlsPolicies(main.rlsPolicies, branch.rlsPolicies));
     changes.push(...diffSchemas(diffContext, main.schemas, branch.schemas));
     changes.push(...diffSequences(diffContext, main.sequences, branch.sequences, branch.tables));
     changes.push(...diffTables(diffContext, main.tables, branch.tables));
     changes.push(...diffTriggers(main.triggers, branch.triggers, branch.indexableObjects));
-    changes.push(...diffEventTriggers({ currentUser: effectiveUser }, main.eventTriggers, branch.eventTriggers));
+    changes.push(...diffEventTriggers(diffContext, main.eventTriggers, branch.eventTriggers));
     changes.push(...diffRules(main.rules, branch.rules));
     changes.push(...diffRanges(diffContext, main.ranges, branch.ranges));
     changes.push(...diffViews(diffContext, main.views, branch.views));
@@ -97,43 +149,7 @@ export function diffCatalogs(main, branch, options) {
     }
     let filteredChanges = changes.filter((change) => {
         if (change.operation === "alter" && change.scope === "privilege") {
-            switch (change.objectType) {
-                case "composite_type":
-                    return !droppedObjectStableIds.has(change.compositeType.stableId);
-                case "domain":
-                    return !droppedObjectStableIds.has(change.domain.stableId);
-                case "enum":
-                    return !droppedObjectStableIds.has(change.enum.stableId);
-                case "language":
-                    return !droppedObjectStableIds.has(change.language.stableId);
-                case "materialized_view":
-                    return !droppedObjectStableIds.has(change.materializedView.stableId);
-                case "aggregate":
-                    return !droppedObjectStableIds.has(change.aggregate.stableId);
-                case "procedure":
-                    return !droppedObjectStableIds.has(change.procedure.stableId);
-                case "range":
-                    return !droppedObjectStableIds.has(change.range.stableId);
-                case "schema":
-                    return !droppedObjectStableIds.has(change.schema.stableId);
-                case "sequence":
-                    return !droppedObjectStableIds.has(change.sequence.stableId);
-                case "table":
-                    return !droppedObjectStableIds.has(change.table.stableId);
-                case "view":
-                    return !droppedObjectStableIds.has(change.view.stableId);
-                case "foreign_data_wrapper":
-                    return !droppedObjectStableIds.has(change.foreignDataWrapper.stableId);
-                case "server":
-                    return !droppedObjectStableIds.has(change.server.stableId);
-                case "foreign_table":
-                    return !droppedObjectStableIds.has(change.foreignTable.stableId);
-                default: {
-                    // exhaustiveness check
-                    const _exhaustive = change;
-                    return _exhaustive;
-                }
-            }
+            return !droppedObjectStableIds.has(getPrivilegeTargetStableId(change));
         }
         return true;
     });

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

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

package/dist/core/catalog.model.js

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

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

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