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

package/README.md

@@ -2,13 +2,14 @@
 
 PostgreSQL migrations made easy.
 
-Generate migration scripts by comparing two PostgreSQL databases. Automatically detects schema differences and creates safe, ordered migration scripts.
+Generate migration scripts by comparing two PostgreSQL databases. Automatically detects schema differences and creates safe, ordered migration scripts. Supports both imperative diff-based migrations and declarative file-based schema management.
 
 ## Features
 
 - 🔍 Compare databases and generate migration scripts automatically
 - 🔒 Safety-first: detects data-loss operations and requires explicit confirmation
 - 📋 Plan-based workflow: preview changes before applying, store plans for version control
+- 📁 Declarative schemas: export/apply schemas as version-controlled `.sql` files
 - 🎯 Integration DSL: filter and customize serialization with JSON-based rules
 - 🛠️ Developer-friendly: interactive CLI with tree-formatted change previews
 
@@ -28,7 +29,9 @@ npx @supabase/pg-delta --source <source> --target <target>
 
 ### CLI Usage
 
-The CLI provides three main commands:
+The CLI provides two paradigms: **imperative** (diff-based migrations) and **declarative** (file-based schemas).
+
+#### Imperative: diff-based migrations
 
 **Sync (default)** - Plan and apply changes in one go:
 
@@ -56,6 +59,38 @@ pg-delta apply \
   --target postgresql://user:pass@localhost:5432/target_db
 ```
 
+#### Declarative: file-based schemas
+
+**Declarative export** - Export a database schema as `.sql` files:
+
+```bash
+pg-delta declarative export \
+  --target postgresql://user:pass@localhost:5432/mydb \
+  --output ./declarative-schemas/
+```
+
+**Declarative apply** - Apply `.sql` files to a database:
+
+```bash
+pg-delta declarative apply \
+  --path ./declarative-schemas/ \
+  --target postgresql://user:pass@localhost:5432/fresh_db
+```
+
+#### Utilities
+
+**Catalog export** - Snapshot a database catalog to JSON for offline diffing:
+
+```bash
+pg-delta catalog-export \
+  --target postgresql://user:pass@localhost:5432/mydb \
+  --output snapshot.json
+```
+
+The snapshot can be used as `--source` or `--target` for `plan` and `declarative export`, enabling offline diffs without a live database connection.
+
+See the [Workflow Guide](./docs/workflow.md) for end-to-end examples combining these commands.
+
 ### Using Integrations
 
 Use built-in integrations or custom JSON files:
@@ -106,6 +141,7 @@ if (planResult) {
 
 ## Documentation
 
+- [Workflow Guide](./docs/workflow.md) - Full flow documentation for all commands and end-to-end workflows
 - [CLI Reference](./docs/cli.md) - Complete CLI documentation with all commands and options
 - [API Reference](./docs/api.md) - Programmatic API documentation
 - [Integrations](./docs/integrations.md) - Using and creating integrations with the DSL system
@@ -138,11 +174,20 @@ See [Integrations Documentation](./docs/integrations.md) for complete details.
 - Compare database states and review differences
 - Automate migration creation in CI/CD pipelines
 - Maintain schema version control with plan files
+- Export and version-control schemas as declarative `.sql` files
+- Apply declarative schemas to fresh databases (provisioning, restore)
+- Snapshot databases for offline, reproducible diffs
 - Filter platform-specific changes (e.g., Supabase system schemas)
 
 ## Contributing
 
-Contributions welcome! Feel free to submit issues and pull requests.
+Please follow the repository-level guide in [../../CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+In particular:
+
+- Open an issue first.
+- Wait for maintainer triage via one of `✨ Feature`, `🐛 Bug`, `📘 Docs`, or `🛠️ Chore` before opening a pull request.
+- Use [../../ISSUES.md](../../ISSUES.md) when reporting `pg-delta` bugs so maintainers have what they need to reproduce them.
 
 ## License
 

package/dist/cli/app.js

@@ -1,12 +1,33 @@
 import { buildApplication, buildRouteMap } from "@stricli/core";
 import { applyCommand } from "./commands/apply.js";
+import { catalogExportCommand } from "./commands/catalog-export.js";
+import { declarativeApplyCommand } from "./commands/declarative-apply.js";
+import { declarativeExportCommand } from "./commands/declarative-export.js";
 import { planCommand } from "./commands/plan.js";
 import { syncCommand } from "./commands/sync.js";
+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: {
@@ -15,9 +36,11 @@ const root = buildRouteMap({
 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
+  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(),
     },
 });

package/dist/cli/bin/cli.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import { run } from "@stricli/core";
 import { app } from "../app.js";
+import { getCommandExitCode } from "../exit-code.js";
 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;
+}

package/dist/cli/commands/catalog-export.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Catalog export command - extract a database catalog and save as a snapshot JSON file.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const catalogExportCommand: import("@stricli/core").Command<CommandContext>;

package/dist/cli/commands/catalog-export.js

@@ -0,0 +1,64 @@
+/**
+ * Catalog export command - extract a database catalog and save as a snapshot JSON file.
+ */
+import { writeFile } from "node:fs/promises";
+import { buildCommand } from "@stricli/core";
+import { extractCatalog } from "../../core/catalog.model.js";
+import { serializeCatalog, stringifyCatalogSnapshot, } from "../../core/catalog.snapshot.js";
+import { createManagedPool } from "../../core/postgres-config.js";
+export const catalogExportCommand = buildCommand({
+    parameters: {
+        flags: {
+            target: {
+                kind: "parsed",
+                brief: "Target database connection URL to extract the catalog from",
+                parse: String,
+            },
+            output: {
+                kind: "parsed",
+                brief: "Output file path for the catalog snapshot JSON",
+                parse: String,
+            },
+            role: {
+                kind: "parsed",
+                brief: "Role to use when extracting the catalog (SET ROLE)",
+                parse: String,
+                optional: true,
+            },
+        },
+        aliases: {
+            t: "target",
+            o: "output",
+        },
+    },
+    docs: {
+        brief: "Export a database catalog as a snapshot JSON file",
+        fullDescription: `
+Extract the full catalog from a live PostgreSQL database and save it
+as a JSON snapshot file. The snapshot can later be used as --source or
+--target for the plan and declarative export commands, enabling
+offline diffing without a live database connection.
+
+Use cases:
+  - Snapshot template1 for use as an empty-database baseline
+  - Snapshot a production database to generate revert migrations
+  - Snapshot any state for reproducible offline diffs
+    `.trim(),
+    },
+    async func(flags) {
+        const { pool, close } = await createManagedPool(flags.target, {
+            role: flags.role,
+            label: "target",
+        });
+        try {
+            const catalog = await extractCatalog(pool);
+            const snapshot = serializeCatalog(catalog);
+            const json = stringifyCatalogSnapshot(snapshot);
+            await writeFile(flags.output, json, "utf-8");
+            this.process.stdout.write(`Catalog snapshot written to ${flags.output}\n`);
+        }
+        finally {
+            await close();
+        }
+    },
+});

package/dist/cli/commands/declarative-apply.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Declarative-apply command - apply a declarative SQL schema to a database
+ * using pg-topo static analysis + round-based execution.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const declarativeApplyCommand: import("@stricli/core").Command<CommandContext>;

package/dist/cli/commands/declarative-apply.js

@@ -0,0 +1,288 @@
+/**
+ * Declarative-apply command - apply a declarative SQL schema to a database
+ * using pg-topo static analysis + round-based execution.
+ */
+import { readFile } from "node:fs/promises";
+import { buildCommand } from "@stricli/core";
+import chalk from "chalk";
+import { loadDeclarativeSchema } from "../../core/declarative-apply/discover-sql.js";
+import { applyDeclarativeSchema, } from "../../core/declarative-apply/index.js";
+import { buildDiagnosticDisplayItems, formatStatementError, positionToLineColumn, requiredObjectKeyFromDiagnostic, resolveSqlFilePath, } from "../utils/apply-display.js";
+export const declarativeApplyCommand = buildCommand({
+    parameters: {
+        flags: {
+            path: {
+                kind: "parsed",
+                brief: "Path to the declarative schema directory (containing .sql files) or a single .sql file",
+                parse: String,
+            },
+            target: {
+                kind: "parsed",
+                brief: "Target database connection URL to apply the schema to",
+                parse: String,
+            },
+            "max-rounds": {
+                kind: "parsed",
+                brief: "Maximum number of application rounds before giving up (default: 100)",
+                parse: Number,
+                optional: true,
+            },
+            "skip-function-validation": {
+                kind: "boolean",
+                brief: "Skip final function body validation pass",
+                optional: true,
+            },
+            verbose: {
+                kind: "boolean",
+                brief: "Show detailed per-round progress",
+                optional: true,
+            },
+            "ungroup-diagnostics": {
+                kind: "boolean",
+                brief: "Show full per-diagnostic detail instead of grouped summary output",
+                optional: true,
+            },
+        },
+        aliases: {
+            p: "path",
+            t: "target",
+            v: "verbose",
+        },
+    },
+    docs: {
+        brief: "Apply a declarative SQL schema to a database",
+        fullDescription: `
+Apply SQL files from a declarative schema directory to a target database.
+
+Uses pg-topo for static dependency analysis and topological ordering,
+then applies statements round-by-round to handle any remaining
+dependency gaps. Statements that fail with dependency errors are
+deferred to subsequent rounds until all succeed or no progress is made.
+
+Function body checks are disabled during rounds to avoid false failures
+from functions referencing not-yet-created objects. A final validation
+pass re-runs all function/procedure definitions with body checks enabled.
+
+Exit codes:
+  0 - Success (all statements applied)
+  1 - Error (hard failures or validation errors)
+  2 - Stuck (dependency cycle or unresolvable ordering)
+
+Tip: Use DEBUG=pg-delta:declarative-apply for detailed defer/skip/fail logs (which statements are deferred and why).
+    `.trim(),
+    },
+    async func(flags) {
+        const verbose = !!flags.verbose;
+        const ungroupDiagnostics = !!flags["ungroup-diagnostics"];
+        const onRoundComplete = verbose
+            ? (round) => {
+                const parts = [
+                    `Round ${round.round}:`,
+                    chalk.green(`${round.applied} applied`),
+                ];
+                if (round.deferred > 0) {
+                    parts.push(chalk.yellow(`${round.deferred} deferred`));
+                }
+                if (round.failed > 0) {
+                    parts.push(chalk.red(`${round.failed} failed`));
+                }
+                this.process.stdout.write(`${parts.join("  ")}\n`);
+            }
+            : undefined;
+        this.process.stdout.write(`Analyzing SQL files in ${flags.path}...\n`);
+        let content;
+        try {
+            content = await loadDeclarativeSchema(flags.path);
+        }
+        catch (error) {
+            this.process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (content.length === 0) {
+            this.process.stderr.write(`No .sql files found in '${flags.path}'. Pass a directory containing .sql files or a single .sql file.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        let result;
+        try {
+            result = await applyDeclarativeSchema({
+                content,
+                targetUrl: flags.target,
+                maxRounds: flags["max-rounds"],
+                validateFunctionBodies: !flags["skip-function-validation"],
+                onRoundComplete,
+            });
+        }
+        catch (error) {
+            this.process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        // Report pg-topo diagnostics grouped by severity (least noisy first).
+        // UNKNOWN_STATEMENT_CLASS is always hidden; DUPLICATE_PRODUCER,
+        // CYCLE_EDGE_SKIPPED, and UNRESOLVED_DEPENDENCY are verbose-only.
+        const diagnosticDisplayOrder = {
+            UNKNOWN_STATEMENT_CLASS: 0,
+            DUPLICATE_PRODUCER: 1,
+            CYCLE_EDGE_SKIPPED: 2,
+            UNRESOLVED_DEPENDENCY: 3,
+        };
+        const diagnosticColor = {
+            DUPLICATE_PRODUCER: chalk.yellow,
+            CYCLE_EDGE_SKIPPED: chalk.red,
+            UNRESOLVED_DEPENDENCY: chalk.dim,
+        };
+        const verboseOnlyCodes = new Set([
+            "UNRESOLVED_DEPENDENCY",
+            "DUPLICATE_PRODUCER",
+            "CYCLE_EDGE_SKIPPED",
+        ]);
+        const warnings = result.diagnostics
+            .filter((d) => d.code !== "UNKNOWN_STATEMENT_CLASS" &&
+            (verbose || !verboseOnlyCodes.has(d.code)))
+            .sort((a, b) => (diagnosticDisplayOrder[a.code] ?? 99) -
+            (diagnosticDisplayOrder[b.code] ?? 99));
+        if (warnings.length > 0 && verbose) {
+            const fileContentCache = new Map();
+            for (const diag of warnings) {
+                const id = diag.statementId;
+                if (id &&
+                    id.sourceOffset != null &&
+                    id.filePath &&
+                    !fileContentCache.has(id.filePath)) {
+                    // Try to resolve the exact file path of the statement to get the exact location of the error
+                    try {
+                        const fullPath = await resolveSqlFilePath(flags.path, id.filePath);
+                        const content = await readFile(fullPath, "utf-8");
+                        fileContentCache.set(id.filePath, content);
+                    }
+                    catch {
+                        // Fall back to statementIndex display
+                    }
+                }
+            }
+            this.process.stderr.write(chalk.yellow(`\n${warnings.length} diagnostic(s) from static analysis:\n`));
+            const entries = warnings.map((diag) => {
+                let location;
+                if (diag.statementId) {
+                    const id = diag.statementId;
+                    const offset = id.sourceOffset;
+                    const content = offset != null ? fileContentCache.get(id.filePath) : undefined;
+                    if (content != null && offset != null) {
+                        const { line, column } = positionToLineColumn(content, offset + 1);
+                        location = `${id.filePath}:${line}:${column}`;
+                    }
+                    else {
+                        location = `${id.filePath}:${id.statementIndex}`;
+                    }
+                }
+                return {
+                    diagnostic: diag,
+                    location,
+                    requiredObjectKey: requiredObjectKeyFromDiagnostic(diag),
+                };
+            });
+            const displayItems = buildDiagnosticDisplayItems(entries, !ungroupDiagnostics);
+            let lastCode = "";
+            const previewLimit = 5;
+            for (const item of displayItems) {
+                if (item.code !== lastCode) {
+                    if (lastCode !== "") {
+                        this.process.stderr.write("\n");
+                    }
+                    lastCode = item.code;
+                }
+                const colorFn = diagnosticColor[item.code] ?? chalk.yellow;
+                const location = item.locations.length > 0 ? ` (${item.locations[0]})` : "";
+                const occurrences = !ungroupDiagnostics && item.locations.length > 1
+                    ? ` x${item.locations.length}`
+                    : "";
+                this.process.stderr.write(colorFn(`  [${item.code}]${location}${occurrences} ${item.message}\n`));
+                if (!ungroupDiagnostics && item.requiredObjectKey) {
+                    this.process.stderr.write(colorFn(`    -> Object: ${item.requiredObjectKey}\n`));
+                }
+                if (!ungroupDiagnostics && item.locations.length > 1) {
+                    for (const locationEntry of item.locations.slice(0, previewLimit)) {
+                        this.process.stderr.write(colorFn(`    at ${locationEntry}\n`));
+                    }
+                    const remaining = item.locations.length - previewLimit;
+                    if (remaining > 0) {
+                        this.process.stderr.write(colorFn(`    ... and ${remaining} more location(s)\n`));
+                    }
+                }
+                if (item.suggestedFix) {
+                    this.process.stderr.write(colorFn(`    -> Fix: ${item.suggestedFix}\n`));
+                }
+            }
+            this.process.stderr.write("\n");
+        }
+        const { apply } = result;
+        // Summary
+        this.process.stdout.write("\n");
+        this.process.stdout.write(`Statements: ${result.totalStatements} total, ${apply.totalApplied} applied`);
+        if (apply.totalSkipped > 0) {
+            this.process.stdout.write(`, ${apply.totalSkipped} skipped`);
+        }
+        this.process.stdout.write("\n");
+        this.process.stdout.write(`Rounds: ${apply.totalRounds}\n`);
+        switch (apply.status) {
+            case "success": {
+                this.process.stdout.write(chalk.green("All statements applied successfully.\n"));
+                if (apply.validationErrors && apply.validationErrors.length > 0) {
+                    this.process.stderr.write(chalk.yellow(`\n${apply.validationErrors.length} function body validation error(s):\n`));
+                    for (const err of apply.validationErrors) {
+                        const formatted = await formatStatementError(err, flags.path);
+                        this.process.stderr.write(chalk.yellow(formatted));
+                        this.process.stderr.write("\n\n");
+                    }
+                    process.exitCode = 1;
+                }
+                else {
+                    process.exitCode = 0;
+                }
+                break;
+            }
+            case "stuck": {
+                this.process.stderr.write(chalk.red(`\nStuck after ${apply.totalRounds} round(s). ${apply.stuckStatements?.length ?? 0} statement(s) could not be applied:\n`));
+                if (apply.stuckStatements) {
+                    for (const stuck of apply.stuckStatements) {
+                        const formatted = await formatStatementError(stuck, flags.path);
+                        this.process.stderr.write(chalk.red(formatted));
+                        this.process.stderr.write("\n\n");
+                    }
+                }
+                if (apply.errors && apply.errors.length > 0) {
+                    this.process.stderr.write(chalk.red(`\nAdditionally, ${apply.errors.length} statement(s) had non-dependency errors:\n`));
+                    for (const err of apply.errors) {
+                        const formatted = await formatStatementError(err, flags.path);
+                        this.process.stderr.write(chalk.red(formatted));
+                        this.process.stderr.write("\n\n");
+                    }
+                }
+                process.exitCode = 2;
+                break;
+            }
+            case "error": {
+                this.process.stderr.write(chalk.red(`\nCompleted with errors. ${apply.errors?.length ?? 0} statement(s) failed:\n`));
+                if (apply.errors) {
+                    for (const err of apply.errors) {
+                        const formatted = await formatStatementError(err, flags.path);
+                        this.process.stderr.write(chalk.red(formatted));
+                        this.process.stderr.write("\n\n");
+                    }
+                }
+                if (apply.validationErrors && apply.validationErrors.length > 0) {
+                    this.process.stderr.write(chalk.yellow(`\n${apply.validationErrors.length} function body validation error(s):\n`));
+                    for (const err of apply.validationErrors) {
+                        const formatted = await formatStatementError(err, flags.path);
+                        this.process.stderr.write(chalk.yellow(formatted));
+                        this.process.stderr.write("\n\n");
+                    }
+                }
+                process.exitCode = 1;
+                break;
+            }
+        }
+    },
+});

package/dist/cli/commands/declarative-export.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Declarative export command - export a declarative SQL schema from a database diff.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const declarativeExportCommand: import("@stricli/core").Command<CommandContext>;