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

npm install @supabase/pg-delta

Or use with npx:

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:

pg-delta sync \
  --source postgresql://user:pass@localhost:5432/source_db \
  --target postgresql://user:pass@localhost:5432/target_db

Plan - Preview changes before applying:

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:

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:

# 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

import { main } from "@supabase/pg-delta";

const result = await main(
  "postgresql://source",
  "postgresql://target"
);

if (result) {
  console.log(result.migrationScript);
}

For plan-based workflow:

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 - Complete CLI documentation with all commands and options
• API Reference - Programmatic API documentation
• Integrations - Using and creating integrations with the DSL system
• Sorting & Safety - 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 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