DBDiff is an automated database schema and data diff tool for MySQL, Postgres & SQLite. 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
• 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)
• Diffs tables, views, triggers, stored procedures/functions, enum types, 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
• 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:

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

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

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:

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

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:

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

Packages are also published to GitHub Packages as a mirror. If npmjs.org is unavailable:

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

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:

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

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).

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

Or as a project dependency:

Or globally:

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:

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.

Capture the result directly into a connection flag:

Accepts stdin too, for use in pipelines:

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:

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.

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

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:

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

DBDiff offers fine-grained control over what enters the diff. All list values support glob patterns (* matches any characters, ? matches a single character).

Priority: include list is applied first (only matching tables pass), then the exclude list narrows further. tablesDataToIgnore removes tables from data comparison only. tableScope can override a table to schema, data, or all.

Glob examples: wp_* matches all WordPress tables, *_backup matches any table ending in _backup, log_? matches log_a through log_z.

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)

• Detects created, dropped, and altered CREATE TYPE ... AS ENUM definitions
• ALTER = DROP TYPE IF EXISTS + CREATE TYPE with the new labels
• Enum diffs are ordered before table diffs (tables may reference enum types)
• MySQL and SQLite do not have standalone enum types — skipped automatically

• 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:

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)

Test DBDiff locally against any combination of PHP and MySQL:

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