What it does
dbdiff treats the first source as the current schema and the second source as the desired schema. Each source can be a live database connection string, a SQL schema file, or a JSON snapshot. Forward SQL changes the first source to match the second. dbdiff lists table, column and index differences. It generates migration SQL with warnings for destructive or locking operations. You can preview the output, save it with --emit or --out with --write, and review it before running it through your normal deployment process. dbdiff generates migration SQL. It does not execute that SQL against your database.
Capabilities
- Loaders for PostgreSQL, MySQL and MariaDB, and SQLite are included by default.
- Migration plans can be forward, rollback, or both. A rollback restores schema definitions but cannot recover data lost through a dropped column or table.
- In --ci mode, dbdiff exits with code 0 when there is no schema drift and code 1 when drift is detected. Adding --fail-on-blocking makes it exit with code 3 when blocking operations are detected. Exit code 2 covers invalid arguments, load or connection failures, and other errors.
- Reports can be written in JSON, YAML, SQL, or a compact CI text format.
- Running dbdiff init creates a .dbdiff.yml configuration file. Its ignore rules filter listed tables and columns from both sources. Its protected rules reject drops of listed tables or matching columns.
When to use it
- Comparing current and desired schemas from files or live databases before a deploy.
- Reviewing generated migration SQL, destructive-operation warnings, and a rollback plan before applying changes.
- Gating a pipeline with machine-readable reports and explicit exit codes for drift and blocking operations.
