DBDiff is an automated database schema and data diff tool. It compares two databases, local or remote, and produces a migration file of the differences automatically.

When used alongside a compatible database migration tool, it can help enable database version control within your team or enterprise.

• Compares two databases (local or remote) and generates SQL migrations automatically
• Diffs tables, views, triggers, stored procedures/functions, and data — with deterministic, predictable output
• Up and down SQL generated in the same file
• Built-in migration runner: migration:up, down, status, validate, repair, baseline
• Supports MySQL, PostgreSQL, and SQLite via --driver
• Connect via DSN URLs (--server1-url, --server2-url, --db-url) — works with any connection string
• Supabase-ready via --supabase one-flag shorthand (not required when using DSN URLs)
• Works with Flyway, Liquibase, Laravel Migrations, and more
• Ignore specific tables or fields via a YAML config file
• Unicode / UTF-8 aware
• Fast — tested on databases with millions of rows
• Runs on Windows, Linux and macOS (command-line / Terminal)

Other versions may work but are not actively tested. PRs to add official support are welcome.

Use --driver=pgsql (or driver: pgsql in your .dbdiff config).

Use --driver=sqlite. The file path is passed as the database name:

./dbdiff --driver=sqlite server1./path/to/source.db:server1./path/to/target.db

SQLite 3.x is supported (any version supported by the installed pdo_sqlite PHP extension).

--supabase sets driver=pgsql and enables SSL automatically:

./dbdiff --supabase --server1=user:[email protected]:5432 server1.mydb:server1.mydb

The databases below work with DBDiff's existing drivers with no code changes. Unless otherwise noted, these have not been tested by the core team. PRs to add official support are welcome.

Neon's copy-on-write branching lets you diff any two branches directly:

./dbdiff \
  --server1-url postgres://user:[email protected]/mydb \
  --server2-url postgres://user:[email protected]/mydb \
  --format=flyway --description=my_feature

Dolt is a MySQL-compatible database with Git-style branching. Each branch is exposed as a separate database:

./dbdiff server1.main:server1.feature_add_users

The quickest way to get started is to download a pre-built release directly from GitHub Releases — no PHP, Node, or Composer required:

PHP requirement: Pre-built binaries, npm packages, and Docker/Podman images bundle PHP 8.3 — no system PHP needed. The PHAR and Composer installs require PHP ≥ 8.1 on your system.

Download from GitHub Releases. No PHP, Node, or Composer required.

After downloading, make it executable (Linux/macOS) and optionally move it to your PATH:

chmod +x dbdiff-linux-x64
sudo mv dbdiff-linux-x64 /usr/local/bin/dbdiff
dbdiff --version

npm install -g @dbdiff/cli
dbdiff --version

The correct platform binary is selected automatically at install time. Supported: Linux x64/arm64 (glibc + musl), macOS x64/arm64, Windows x64/arm64.

Download dbdiff.phar from GitHub Releases. Requires PHP ≥ 8.1.

chmod +x dbdiff.phar
sudo mv dbdiff.phar /usr/local/bin/dbdiff
dbdiff --version

To build a PHAR locally from source, see Building a PHAR.

Pre-built multi-arch images (linux/amd64 + linux/arm64) are published to GHCR on every release. Both Docker and Podman are fully supported — use whichever is available on your system. No local PHP installation is required.

Docker:

docker pull ghcr.io/dbdiff/dbdiff
docker run --rm ghcr.io/dbdiff/dbdiff --version
docker run --rm ghcr.io/dbdiff/dbdiff --driver=mysql \
  --server1=user:pass@host:3306 server1.mydb:server1.mydb

Podman (drop-in replacement — commands are identical):

podman pull ghcr.io/dbdiff/dbdiff
podman run --rm ghcr.io/dbdiff/dbdiff --version
podman run --rm ghcr.io/dbdiff/dbdiff --driver=mysql \
  --server1=user:pass@host:3306 server1.mydb:server1.mydb

Podman on Linux runs rootless by default — no daemon required. Install via your package manager: sudo apt install podman (Debian/Ubuntu) or brew install podman (macOS).

# Slim image (requires dist/dbdiff.phar — run `vendor/bin/box compile` first)
# Replace 'docker' with 'podman' if using Podman
docker build -f docker/Dockerfile.slim -t dbdiff:slim .
docker run --rm dbdiff:slim --version

# Full image (Composer install from source — no PHAR needed)
docker build -f docker/Dockerfile -t dbdiff:full .

See DOCKER.md for cross-version testing, Podman setup, and start.sh flags.

git clone https://github.com/DBDiff/DBDiff.git
cd DBDiff
composer install --optimize-autoloader

Or as a project dependency:

composer require "dbdiff/dbdiff:@dev"

Or globally:

composer global require "dbdiff/dbdiff:@dev"

After installing from source, continue with Setup.

For source installs (git clone / Composer) only. Binaries, PHAR, npm, and Docker do not require these steps.

1. Create a .dbdiff config file — see File Examples
2. Run: ./dbdiff server1.db1:server1.db2

Expected output:

ℹ Now calculating schema diff for table `foo`
ℹ Now generating UP migration
ℹ Writing migration file to /path/to/dbdiff/migration.sql
✔ Completed

Flags always override settings in .dbdiff.

UP only by default: The generated file includes only the UP (forward) migration by default. To also generate the DOWN (rollback) section, pass --include=all. Example: dbdiff diff --include=all ...

DSN URLs vs --server flags: Use --server1-url / --server2-url when you have a connection string (common with Supabase, Neon, Railway, etc.). Use --server1 / --server2 when specifying credentials separately.

Passwords with special characters: Embed the password percent-encoded in the URL. Use dbdiff url:encode to safely encode any password (see url:encode below). If dbdiff is not yet installed, scripts/encode-password.sh works without any dependencies.

Memory: The CLI sets a default PHP memory limit of 1G. Diffing very large databases may need more — pass --memory-limit=2G on the command line or add memory_limit: 2G to your .dbdiff / dbdiff.yml config. The CLI flag always wins over the config file.

Percent-encodes a raw password for safe embedding in any --server-url connection string.

dbdiff url:encode '<raw password>'

Capture the result directly into a connection flag:

PASS=$(dbdiff url:encode 'my$ecret#pass@word%123')
dbdiff diff \
  --server1-url="postgres://user:${PASS}@db.xxxx.supabase.co:5432/postgres" \
  --server2-url="postgres://user:[email protected]:5432/postgres"

Accepts stdin too, for use in pipelines:

echo 'my$ecret#pass' | dbdiff url:encode

All characters except RFC 3986 unreserved characters (A–Z a–z 0–9 - _ . ~) are encoded. This is the safe, zero-guesswork approach for any password — including ones containing @, #, ?, /, +, and literal %.

If dbdiff is not yet installed (e.g. you are setting up CI), use the included bash script instead — no Python, Node, or PHP required:

PASS=$(scripts/encode-password.sh 'my$ecret#pass@word%123')

DBDiff includes a built-in migration runner. All migration:* commands accept:

DBDiff supports two on-disk formats in the same directory:

If both formats exist for the same version timestamp, the native .up.sql file takes precedence.

When DBDiff is run inside (or below) a directory that contains supabase/config.toml, it automatically:

• Sets the migrations directory to supabase/migrations/ (no --migrations-dir needed)
• Defaults migration:new to Supabase format — creating a plain .sql file
• Shows a Supa? column in migration:status, indicating which migrations Supabase's own schema_migrations table considers applied

Pass --format=native to migration:new to override the auto-detected format.

./dbdiff server1.db1:server2.db2

./dbdiff server1.dev.table1:server2.prod.table1 --nocomments --type=data

./dbdiff --format=flyway --description=add_users --include=all \
  server1.db1:server2.db2 --output=./sql/

./dbdiff --driver=pgsql --server1=user:pass@localhost:5432 server1.staging:server1.production

./dbdiff --supabase --server1=postgres:[email protected]:5432 \
  server1.staging:server1.production

./dbdiff --driver=sqlite server1./var/db/v1.db:server1./var/db/v2.db

./dbdiff diff \
  --server1-url='postgres://user:[email protected]:5432/postgres' \
  --server2-url='postgres://user:[email protected]:5432/postgres'

If your password contains special characters, use dbdiff url:encode (see url:encode in the Command-Line API section):

PASS=$(dbdiff url:encode 'my$ecret#pass@word%123')
./dbdiff diff \
  --server1-url="postgres://user:${PASS}@db.xxxx.supabase.co:5432/postgres" \
  --server2-url='postgres://user:[email protected]:5432/postgres'

# Scaffold a new migration (DBDiff native format)
./dbdiff migration:new create_users_table

# Scaffold a Supabase-format migration (plain .sql, no DOWN file)
./dbdiff migration:new create_users_table --format=supabase

# Inside a Supabase project, format and directory are auto-detected:
cd my-supabase-project   # contains supabase/config.toml
./dbdiff migration:new create_users_table   # → supabase/migrations/{ts}_create_users_table.sql

# Apply all pending migrations
./dbdiff migration:up --db-url='postgres://user:pass@localhost:5432/mydb'

# Check status (adds a Supa? column inside Supabase projects)
./dbdiff migration:status --db-url='postgres://user:pass@localhost:5432/mydb'

# Roll back the last migration
./dbdiff migration:down --db-url='postgres://user:pass@localhost:5432/mydb'

# Validate checksums
./dbdiff migration:validate --db-url='postgres://user:pass@localhost:5432/mydb'

When inside a Supabase project (supabase/config.toml present) and the local stack is running (supabase start), --server1-url is resolved automatically from supabase status:

# Only supply the remote (production) URL — local stack fills in automatically
./dbdiff diff --server2-url='postgres://user:[email protected]:5432/postgres'

A single dbdiff.yml file in your project root configures both the diff command and the migration runner. Copy dbdiff.yml.example to get started.

Auto-detected filenames, in priority order:

You can also pass any filename explicitly: ./dbdiff --config=myconfig.yml server1.db:server2.db

# ── Diff command (./dbdiff server1.db:server2.db) ─────────────────────────
server1:
  user: user
  password: password
  port: 3306      # MySQL: 3306 | PostgreSQL: 5432
  host: localhost
server2:
  user: user
  password: password
  port: 3306
  host: host2
driver: mysql     # mysql | pgsql | sqlite
type: all
include: all
nocomments: true
tablesToIgnore:
  - table1
  - table2
fieldsToIgnore:
  table1:
    - field1
    - field2

# ── Migration runner (dbdiff migration:up) ────────────────────────────────
database:
  driver: mysql
  host: localhost
  port: 3306
  name: mydb
  user: root
  password: secret

migrations:
  dir: ./migrations
  history_table: _dbdiff_migrations

Comparisons run in this order:

• Checks both databases exist and are accessible
• Compares database collation between source and target

• Detects differences in column count, name, type, collation or attributes
• New columns in the source are added to the target

• Detects created, dropped, and altered views across source and target
• ALTER = DROP IF EXISTS + CREATE with the new definition

• Detects created, dropped, and altered triggers
• PostgreSQL DROP TRIGGER includes the required ON table clause

• Detects created, dropped, and altered routines (MySQL and PostgreSQL)
• SQLite has no stored procedures — routines are skipped automatically
• MySQL definitions are normalized (DEFINER, ALGORITHM, SQL SECURITY stripped)

• Compares table storage engine, collation, and row count
• Records changed rows and missing rows per table

DBDiff supports multiple output formats via --format. Use --description=<slug> to customise generated filenames.

Let us know if you're using DBDiff with other tools so we can add them here.

PHARs are built automatically and attached to every GitHub Release. To build locally from source:

composer install
vendor/bin/box compile

Output: dist/dbdiff.phar — rename and move to /usr/local/bin/dbdiff if desired.

box.json is pre-configured with GZ compression and check-requirements: false so the PHAR works correctly when stitched with the static micro SAPI runtime used in the pre-built binaries.

1. Go to GitHub Actions → Release DBDiff → Run workflow
2. Enter the version number (e.g. 2.1.0 — no v prefix)
3. The workflow will:
   • Build the PHAR with Box
   • Build self-contained binaries for all 8 platforms via static-php-cli
   • Publish all @dbdiff/cli-* packages to npm (skips any already published)
   • Create or update the GitHub Release with all assets
   • Create the git tag (skipped if it already exists)

# Build PHAR + tag
scripts/release.sh v2.1.0
git push origin v2.1.0

# Build Linux binaries locally (requires Podman or Docker)
SKIP_PHAR=1 scripts/release-binaries.sh 2.1.0

# Upload assets to an existing GitHub Release
gh release upload v2.1.0 --clobber \
  dist/dbdiff.phar \
  packages/@dbdiff/cli-linux-x64/dbdiff \
  packages/@dbdiff/cli-linux-x64-musl/dbdiff \
  packages/@dbdiff/cli-linux-arm64/dbdiff \
  packages/@dbdiff/cli-linux-arm64-musl/dbdiff

# Update the Homebrew tap formula
scripts/update-homebrew-formula.sh 2.1.0 ../homebrew-dbdiff

Test DBDiff locally against any combination of PHP and MySQL:

# Single combination
./start.sh 8.3 8.0

# All 16 combinations in parallel
./start.sh all all --parallel

The CI matrix: 5 PHP × 4 MySQL = 20 jobs, plus dedicated jobs for SQLite, PostgreSQL, DSN URLs, and Supabase.

See DOCKER.md for flags covering fast restarts, recording fixtures, and CI usage.

• Open a new issue or check existing ones
• For commercial support enquiries, get in touch

Please read the Contributing Guide before submitting a PR.

Could you spare 2 minutes to share your feedback?

https://forms.gle/gjdJxZxdVsz7BRxg7

MIT

Made with 💖 by