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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Supabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# pg-delta
+
+PostgreSQL migrations made easy.
+
+Generate migration scripts by comparing two PostgreSQL databases. Automatically detects schema differences and creates safe, ordered migration scripts.
+
+## 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
+- 🎯 Integration DSL: filter and customize serialization with JSON-based rules
+- 🛠️ Developer-friendly: interactive CLI with tree-formatted change previews
+
+## Installation
+
+```bash
+npm install @supabase/pg-delta
+```
+
+Or use with `npx`:
+
+```bash
+npx @supabase/pg-delta --source <source> --target <target>
+```
+
+## Quick Start
+
+### CLI Usage
+
+The CLI provides three main commands:
+
+**Sync (default)** - Plan and apply changes in one go:
+
+```bash
+pg-delta sync \
+  --source postgresql://user:pass@localhost:5432/source_db \
+  --target postgresql://user:pass@localhost:5432/target_db
+```
+
+**Plan** - Preview changes before applying:
+
+```bash
+pg-delta plan \
+  --source postgresql://user:pass@localhost:5432/source_db \
+  --target postgresql://user:pass@localhost:5432/target_db \
+  --output plan.json
+```
+
+**Apply** - Apply a previously created plan:
+
+```bash
+pg-delta apply \
+  --plan plan.json \
+  --source postgresql://user:pass@localhost:5432/source_db \
+  --target postgresql://user:pass@localhost:5432/target_db
+```
+
+### Using Integrations
+
+Use built-in integrations or custom JSON files:
+
+```bash
+# Built-in Supabase integration
+pg-delta sync --source <source> --target <target> --integration supabase
+
+# Custom integration file
+pg-delta sync --source <source> --target <target> --integration ./my-integration.json
+```
+
+### Programmatic Usage
+
+```typescript
+import { main } from "@supabase/pg-delta";
+
+const result = await main(
+  "postgresql://source",
+  "postgresql://target"
+);
+
+if (result) {
+  console.log(result.migrationScript);
+}
+```
+
+For plan-based workflow:
+
+```typescript
+import { createPlan, applyPlan } from "@supabase/pg-delta";
+
+// Create a plan
+const planResult = await createPlan(sourceUrl, targetUrl, {
+  filter: { schema: "public" },
+  serialize: [{ when: { type: "schema" }, options: { skipAuthorization: true } }]
+});
+
+if (planResult) {
+  // Apply the plan
+  const result = await applyPlan(
+    planResult.plan,
+    sourceUrl,
+    targetUrl
+  );
+}
+```
+
+## Documentation
+
+- [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
+- [Sorting & Safety](./docs/sorting.md) - How migrations are ordered for safety
+
+## Key Concepts
+
+### Plan-Based Workflow
+
+`pg-delta` uses a plan-based workflow that provides:
+
+- **Preview before apply**: Review changes before executing them
+- **Self-contained plans**: Plans store filtering and serialization rules
+- **Reproducibility**: Plans can be version-controlled and shared
+- **Safety checks**: Automatic detection of data-loss operations
+
+### Integration DSL
+
+Integrations use a JSON-based DSL for filtering and serialization:
+
+- **Filter DSL**: Pattern matching to include/exclude changes
+- **Serialization DSL**: Rules to customize SQL generation
+- **Serializable**: Can be stored in plans and passed as CLI flags
+
+See [Integrations Documentation](./docs/integrations.md) for complete details.
+
+## Use Cases
+
+- Generate migrations between environments (dev → staging → production)
+- Compare database states and review differences
+- Automate migration creation in CI/CD pipelines
+- Maintain schema version control with plan files
+- Filter platform-specific changes (e.g., Supabase system schemas)
+
+## Contributing
+
+Contributions welcome! Feel free to submit issues and pull requests.
+
+## License
+
+MIT

package/dist/cli/app.d.ts

@@ -0,0 +1 @@
+export declare const app: import("@stricli/core").Application<import("@stricli/core").CommandContext>;

package/dist/cli/app.js

@@ -0,0 +1,26 @@
+import { buildApplication, buildRouteMap } from "@stricli/core";
+import { applyCommand } from "./commands/apply.js";
+import { planCommand } from "./commands/plan.js";
+import { syncCommand } from "./commands/sync.js";
+const root = buildRouteMap({
+    routes: {
+        plan: planCommand,
+        apply: applyCommand,
+        sync: syncCommand,
+    },
+    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
+    `.trim(),
+    },
+});
+export const app = buildApplication(root, {
+    name: "pgdelta",
+});

package/dist/cli/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "@stricli/core";
+import { app } from "../app.js";
+await run(app, process.argv.slice(2), { process }).catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

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

@@ -0,0 +1,5 @@
+/**
+ * Apply command - apply a plan's migration script to a target database.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const applyCommand: import("@stricli/core").Command<CommandContext>;

package/dist/cli/commands/apply.js

@@ -0,0 +1,85 @@
+/**
+ * Apply command - apply a plan's migration script to a target database.
+ */
+import { readFile } from "node:fs/promises";
+import { buildCommand } from "@stricli/core";
+import { applyPlan } from "../../core/plan/apply.js";
+import { deserializePlan } from "../../core/plan/index.js";
+import { handleApplyResult, validatePlanRisk } from "../utils.js";
+export const applyCommand = buildCommand({
+    parameters: {
+        flags: {
+            plan: {
+                kind: "parsed",
+                brief: "Path to plan file (JSON format)",
+                parse: String,
+            },
+            source: {
+                kind: "parsed",
+                brief: "Source database connection URL (current state)",
+                parse: String,
+            },
+            target: {
+                kind: "parsed",
+                brief: "Target database connection URL (desired state)",
+                parse: String,
+            },
+            unsafe: {
+                kind: "boolean",
+                brief: "Allow data-loss operations (unsafe mode)",
+                optional: true,
+            },
+        },
+        aliases: {
+            p: "plan",
+            s: "source",
+            t: "target",
+            u: "unsafe",
+        },
+    },
+    docs: {
+        brief: "Apply a plan's migration script to a database",
+        fullDescription: `
+Apply changes from a plan file to a target database.
+
+The plan file should be a JSON file created with "pgdelta plan --output <file>.plan.json" (or any .plan/.json path).
+
+Safe by default: will refuse plans containing data-loss unless --unsafe is set.
+
+Exit codes:
+  0 - Success (changes applied)
+  1 - Error occurred
+    `.trim(),
+    },
+    async func(flags) {
+        // Read and parse plan file
+        let planJson;
+        try {
+            planJson = await readFile(flags.plan, "utf-8");
+        }
+        catch (error) {
+            this.process.stderr.write(`Error reading plan file: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        let plan;
+        try {
+            plan = deserializePlan(planJson);
+        }
+        catch (error) {
+            this.process.stderr.write(`Error parsing plan file: ${error instanceof Error ? error.message : String(error)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const validation = validatePlanRisk(plan, !!flags.unsafe, this);
+        if (!validation.valid) {
+            process.exitCode = validation.exitCode ?? 1;
+            return;
+        }
+        const result = await applyPlan(plan, flags.source, flags.target, {
+            verifyPostApply: true,
+        });
+        const { exitCode } = handleApplyResult(result, this);
+        process.exitCode = exitCode;
+    },
+});

package/dist/cli/commands/plan.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Plan command - compute schema diff and preview changes.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const planCommand: import("@stricli/core").Command<CommandContext>;

package/dist/cli/commands/plan.js

@@ -0,0 +1,137 @@
+/**
+ * Plan command - compute schema diff and preview changes.
+ */
+import { writeFile } from "node:fs/promises";
+import { buildCommand } from "@stricli/core";
+import { createPlan } from "../../core/plan/index.js";
+import { loadIntegrationDSL } from "../utils/integrations.js";
+import { formatPlanForDisplay } from "../utils.js";
+export const planCommand = buildCommand({
+    parameters: {
+        flags: {
+            source: {
+                kind: "parsed",
+                brief: "Source database connection URL (current state)",
+                parse: String,
+            },
+            target: {
+                kind: "parsed",
+                brief: "Target database connection URL (desired state)",
+                parse: String,
+            },
+            format: {
+                kind: "enum",
+                brief: "Output format override: json (plan) or sql (script).",
+                values: ["json", "sql"],
+                optional: true,
+            },
+            output: {
+                kind: "parsed",
+                brief: "Write output to file (stdout by default). If format is not set: .sql infers sql, .json infers json, otherwise uses human output.",
+                parse: String,
+                optional: true,
+            },
+            role: {
+                kind: "parsed",
+                brief: "Role to use when executing the migration (SET ROLE will be added to statements).",
+                parse: String,
+                optional: true,
+            },
+            filter: {
+                kind: "parsed",
+                brief: 'Filter DSL as inline JSON to filter changes (e.g., \'{"schema":"public"}\').',
+                parse: (value) => {
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch (error) {
+                        throw new Error(`Invalid filter JSON: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                },
+                optional: true,
+            },
+            serialize: {
+                kind: "parsed",
+                brief: 'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\').',
+                parse: (value) => {
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch (error) {
+                        throw new Error(`Invalid serialize JSON: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                },
+                optional: true,
+            },
+            integration: {
+                kind: "parsed",
+                brief: "Integration name (e.g., 'supabase') or path to integration JSON file (must end with .json). Loads from core/integrations/ or file path.",
+                parse: String,
+                optional: true,
+            },
+        },
+        aliases: {
+            s: "source",
+            t: "target",
+            o: "output",
+        },
+    },
+    docs: {
+        brief: "Compute schema diff and preview changes",
+        fullDescription: `
+Compute the schema diff between two PostgreSQL databases (source → target),
+and preview it for review or scripting. Defaults to tree display;
+json/sql outputs are available for artifacts or piping.
+    `.trim(),
+    },
+    async func(flags) {
+        // Load integration if provided and extract filter/serialize DSL
+        let filterOption = flags.filter;
+        let serializeOption = flags.serialize;
+        if (flags.integration) {
+            const integrationDSL = await loadIntegrationDSL(flags.integration);
+            // Use integration DSL if explicit flags not provided
+            filterOption = filterOption ?? integrationDSL.filter;
+            serializeOption = serializeOption ?? integrationDSL.serialize;
+        }
+        const planResult = await createPlan(flags.source, flags.target, {
+            role: flags.role,
+            filter: filterOption,
+            serialize: serializeOption,
+        });
+        if (!planResult) {
+            this.process.stdout.write("No changes detected.\n");
+            return;
+        }
+        const outputPath = flags.output;
+        let effectiveFormat;
+        if (flags.format) {
+            effectiveFormat = flags.format;
+        }
+        else if (outputPath?.endsWith(".sql")) {
+            effectiveFormat = "sql";
+        }
+        else if (outputPath?.endsWith(".json")) {
+            effectiveFormat = "json";
+        }
+        else {
+            effectiveFormat = "tree";
+        }
+        const { content, label } = formatPlanForDisplay(planResult, effectiveFormat, {
+            disableColors: !!outputPath,
+            showUnsafeFlagSuggestion: false,
+        });
+        if (outputPath) {
+            await writeFile(outputPath, content, "utf-8");
+            this.process.stdout.write(`${label} written to ${outputPath}\n`);
+        }
+        else {
+            this.process.stdout.write(content);
+            if (!content.endsWith("\n")) {
+                this.process.stdout.write("\n");
+            }
+        }
+        // Exit code 2 indicates changes were detected
+        process.exitCode = 2;
+    },
+});

package/dist/cli/commands/sync.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Sync command - plan and apply changes in one go with confirmation prompt.
+ */
+import { type CommandContext } from "@stricli/core";
+export declare const syncCommand: import("@stricli/core").Command<CommandContext>;

package/dist/cli/commands/sync.js

@@ -0,0 +1,141 @@
+/**
+ * Sync command - plan and apply changes in one go with confirmation prompt.
+ */
+import { buildCommand } from "@stricli/core";
+import { applyPlan } from "../../core/plan/apply.js";
+import { createPlan } from "../../core/plan/index.js";
+import { loadIntegrationDSL } from "../utils/integrations.js";
+import { formatPlanForDisplay, handleApplyResult, promptConfirmation, validatePlanRisk, } from "../utils.js";
+export const syncCommand = buildCommand({
+    parameters: {
+        flags: {
+            source: {
+                kind: "parsed",
+                brief: "Source database connection URL (current state)",
+                parse: String,
+            },
+            target: {
+                kind: "parsed",
+                brief: "Target database connection URL (desired state)",
+                parse: String,
+            },
+            yes: {
+                kind: "boolean",
+                brief: "Skip confirmation prompt and apply changes automatically",
+                optional: true,
+            },
+            unsafe: {
+                kind: "boolean",
+                brief: "Allow data-loss operations (unsafe mode)",
+                optional: true,
+            },
+            role: {
+                kind: "parsed",
+                brief: "Role to use when executing the migration (SET ROLE will be added to statements).",
+                parse: String,
+                optional: true,
+            },
+            filter: {
+                kind: "parsed",
+                brief: 'Filter DSL as inline JSON to filter changes (e.g., \'{"schema":"public"}\').',
+                parse: (value) => {
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch (error) {
+                        throw new Error(`Invalid filter JSON: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                },
+                optional: true,
+            },
+            serialize: {
+                kind: "parsed",
+                brief: 'Serialize DSL as inline JSON array (e.g., \'[{"when":{"type":"schema"},"options":{"skipAuthorization":true}}]\').',
+                parse: (value) => {
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch (error) {
+                        throw new Error(`Invalid serialize JSON: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                },
+                optional: true,
+            },
+            integration: {
+                kind: "parsed",
+                brief: "Integration name (e.g., 'supabase') or path to integration JSON file (must end with .json). Loads from core/integrations/ or file path.",
+                parse: String,
+                optional: true,
+            },
+        },
+        aliases: {
+            s: "source",
+            t: "target",
+            y: "yes",
+            u: "unsafe",
+        },
+    },
+    docs: {
+        brief: "Plan and apply schema changes in one go",
+        fullDescription: `
+Compute the schema diff between two PostgreSQL databases (source → target),
+display the plan, prompt for confirmation, and apply changes if confirmed.
+
+Use --yes to skip the confirmation prompt and apply changes automatically.
+Safe by default: refuses data-loss changes unless --unsafe is set.
+
+Exit codes:
+  0 - Success (changes applied or no changes detected)
+  1 - Error occurred
+  2 - User cancelled or changes detected but not applied
+    `.trim(),
+    },
+    async func(flags) {
+        // Load integration if provided and extract filter/serialize DSL
+        let filterOption = flags.filter;
+        let serializeOption = flags.serialize;
+        if (flags.integration) {
+            const integrationDSL = await loadIntegrationDSL(flags.integration);
+            // Use integration DSL if explicit flags not provided
+            filterOption = filterOption ?? integrationDSL.filter;
+            serializeOption = serializeOption ?? integrationDSL.serialize;
+        }
+        // 1. Create the plan
+        const planResult = await createPlan(flags.source, flags.target, {
+            role: flags.role,
+            filter: filterOption,
+            serialize: serializeOption,
+        });
+        if (!planResult) {
+            this.process.stdout.write("No changes detected.\n");
+            process.exitCode = 0;
+            return;
+        }
+        // 2. Display the plan
+        const { content } = formatPlanForDisplay(planResult, "tree");
+        this.process.stdout.write(content);
+        // 3. Validate risk (suppress warning since it's already shown in the plan)
+        const validation = validatePlanRisk(planResult.plan, !!flags.unsafe, this, {
+            suppressWarning: true,
+        });
+        if (!validation.valid) {
+            process.exitCode = validation.exitCode ?? 1;
+            return;
+        }
+        // 4. Prompt for confirmation (unless --yes)
+        if (!flags.yes) {
+            const confirmed = await promptConfirmation("Apply these changes? (y/N) ", this);
+            if (!confirmed) {
+                process.exitCode = 2;
+                return;
+            }
+        }
+        // 5. Apply the plan
+        const result = await applyPlan(planResult.plan, flags.source, flags.target, {
+            verifyPostApply: true,
+        });
+        // 6. Handle apply result
+        const { exitCode } = handleApplyResult(result, this);
+        process.exitCode = exitCode;
+    },
+});

package/dist/cli/formatters/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Formatters for displaying plans in various formats.
+ */
+export { formatTree } from "./tree/tree.ts";

package/dist/cli/formatters/index.js

@@ -0,0 +1,4 @@
+/**
+ * Formatters for displaying plans in various formats.
+ */
+export { formatTree } from "./tree/tree.js";

package/dist/cli/formatters/tree/tree-builder.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Builds a generic tree structure from a HierarchicalPlan.
+ * Shows only structural changes (scope === "object"), grouped for readability.
+ */
+import type { HierarchicalPlan } from "../../../core/plan/index.ts";
+import type { TreeGroup } from "./tree-renderer.ts";
+/**
+ * Build a generic tree structure from a HierarchicalPlan.
+ */
+export declare function buildPlanTree(plan: HierarchicalPlan): TreeGroup;