dbdiff

Compare database schemas. See what changed. Generate SQL you can review.
PostgreSQL · MySQL / MariaDB · SQLite · SQL files · JSON snapshots

Try the demo · Install · CLI guide · Website · Contribute

See it in action

Static preview. Excerpts from the offline demo below, captured from the actual CLI. The full run also verifies JSON output, migration files, rollback SQL, and preview behavior.

• Find drift before a deploy: compare current and desired schemas from files or live databases.
• Review the migration: see generated SQL, destructive-operation warnings, and a rollback plan.
• Gate your pipeline: machine-readable reports and explicit exit codes for drift and blocking operations.
• Work offline: compare SQL files or export a JSON snapshot for later review.

dbdiff generates migration SQL; it does not execute that SQL against your database.

Try the demo

No database server, credentials, or Docker required. From a checkout:

git clone https://github.com/rekurt/dbdiff.git
cd dbdiff
cargo build --locked
python3 examples/demo/run.py --bin target/debug/dbdiff

Requires Rust 1.88+ and Python 3.9+. On Windows, use python and target/debug/dbdiff.exe.

The demo replaces a free-form payment date with a timestamp, adds an index, and introduces soft deletion. It verifies four changes and the CI exit codes 1 → 3 → 0, then saves the transcript, JSON report, forward migration, and rollback under target/demo/.

Or, with dbdiff installed, run the comparison directly:

dbdiff examples/demo/before.sql examples/demo/after.sql

~ table: orders
  + column  paid_at              timestamp
  - column  payment_date         text
  + index   idx_orders_paid_at ON orders(paid_at)

~ table: users
  + column  deleted_at           timestamp

See the demo walkthrough for individual commands and how to regenerate the animation.

Install

Release binaries

Download the archive for your platform from Releases, extract it, and put dbdiff (or dbdiff.exe) on your PATH.

Build from source

cargo install --git https://github.com/rekurt/dbdiff --locked

All three database backends are enabled by default. For a smaller build:

cargo install --git https://github.com/rekurt/dbdiff --locked \
  --no-default-features --features postgres,sqlite

Source builds require Rust 1.88+ and the platform's build tools; PostgreSQL/MySQL builds may also require TLS development libraries. See CONTRIBUTING.md.

Everyday usage

Compare current → desired

The first source is the current schema. The second source is the desired schema. Forward SQL changes the first to match the second.

# Two live PostgreSQL databases
dbdiff "$CURRENT_DSN" "$DESIRED_DSN"

# Live database versus a complete desired schema file
dbdiff "$CURRENT_DSN" --schema schema.sql

# MySQL / MariaDB (both variables contain mysql:// or mariadb:// DSNs)
dbdiff "$MYSQL_CURRENT_DSN" "$MYSQL_DESIRED_DSN"

# SQLite database versus a schema file
dbdiff app.db --schema schema.sql

# Two SQL files, fully offline
dbdiff current.sql desired.sql

A schema file should describe the complete desired structure with CREATE statements, rather than an incremental ALTER migration. Compare like-for-like database backends; a SQL file can be used on either side. SQL-file-only comparisons generate PostgreSQL-style migration SQL.

Preview, then save

# Preview only: this does not create migration.sql
dbdiff current.sql desired.sql --out migration.sql

# Explicitly save the forward migration
dbdiff current.sql desired.sql --emit migration.sql

# Equivalent write command
dbdiff current.sql desired.sql --out migration.sql --write

# Save a separate rollback plan
dbdiff current.sql desired.sql --direction down --emit rollback.sql

Review generated SQL before applying it. A rollback restores schema definitions; it cannot recover data lost through a dropped column or table.

Reports and offline snapshots

dbdiff current.sql desired.sql --format json > drift.json
dbdiff current.sql desired.sql --format yaml > drift.yml
dbdiff current.sql desired.sql --format sql > migration.sql

# Capture a database schema, then compare the snapshot offline
dbdiff snapshot "$CURRENT_DSN" --out current.json
dbdiff current.json desired.json

For connectivity checks, table listing, completions, PostgreSQL concurrent indexes, and configuration options, see the CLI guide or dbdiff --help.

Use it in CI

dbdiff current.sql desired.sql --ci --format json > drift-report.json

Use --format ci for a compact text report. --format json and --format yaml provide structured reports. Add --fail-on-blocking to distinguish changes classified as blocking by dbdiff.

A file-based GitHub Actions example, requiring no database secrets:

name: Schema drift
on: [pull_request]
permissions:
  contents: read
jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: dtolnay/rust-toolchain@stable
      - name: Install dbdiff
        run: cargo install --git https://github.com/rekurt/dbdiff --tag v0.2.2 --locked
      - name: Compare schemas
        run: dbdiff current.sql desired.sql --ci --format json > drift-report.json
      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: schema-drift-report
          path: drift-report.json

Replace current.sql and desired.sql with your project's schemas. For live comparisons, supply DSNs through CI secrets. When running under GitHub Actions, CI mode also emits annotations.

Configuration

Run dbdiff init to create .dbdiff.yml, or use --config path/to/config.yml:

ignore:
  tables:
    - _migrations
    - schema_version
  columns:
    - "*.created_at"
    - "sessions.*"

protected:
  tables:
    - payments
  columns:
    - "*.id"

output:
  format: pretty
  color: true

Ignored objects are filtered from both sources. Protected rules reject drops of listed tables or matching columns. See configuration details.

Capabilities and limits

• PostgreSQL, MySQL/MariaDB, and SQLite loaders are included by default. Backend-specific DDL has different capabilities; review each generated plan.
• SQL files are parsed as schema definitions. Views, enums, and sequences are excluded from comparisons involving .sql files; use JSON snapshots to preserve those objects.
• SQLite cannot perform every ALTER operation directly; generated plans can include warnings or unsupported-operation comments.
• Rename detection is experimental and opt-in (--detect-renames).
• Blocking classifications are review aids, not a guarantee about execution time, lock duration, or data preservation.

Development and community

cargo test --locked
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
python3 examples/demo/run.py --bin target/debug/dbdiff

Contributing · Architecture · Changelog · Report a bug · Request a feature · Security policy · Code of conduct

MIT © Nikita. See LICENSE.