Dbdiff Laravel Package

Getting Started

• Install: composer require --dev jawbfl/dbdiff. It shells out to PDO, so you also need the matching PDO driver (pdo_mysql for the common case) enabled in the PHP CLI you'll run it with.
• Read first: the repo README.md (it doubles as the CLI reference), then the CLI entry point (dbdiff / bin/) and the src/ comparators. The CLI is a thin wrapper — the entry point tells you exactly which comparator and renderer classes are public API if you want to script it.
• Minimal invocation: point it at two databases and let it emit SQL. The CLI takes two connection strings (server1 = source/reference, server2 = target) plus flags for what to compare (--type=schema|data|all), which direction to emit (--include=up|down|both), and an output template. Confirm exact flag spelling against the README for your pinned version — this is a small project and flags have shifted between releases.
• First use case: dump your production schema, restore it into a scratch database, then diff scratch (server1) against your dev/staging database (server2). Read the generated ALTER script by hand. That single loop — dump, diff, review, apply — is 90% of how this tool earns its keep.

Implementation Patterns

• Drift detection in CI: keep a canonical schema.sql in the repo, restore it to a throwaway MySQL service in CI, and diff it against the schema built by your migrations. Treat any non-empty diff as a build failure. This catches "someone changed the table by hand" and "the migration doesn't match the model" long before deploy.
• Pre-deploy migration drafts: diff staging against production right before a release, save the output to build/predeploy.sql, and hand it to a reviewer. Use the up/down template so you get a rollback script in the same pass — the down half is usually the part people forget to write.
• Template-driven output: the --template option lets you wrap the generated statements in your own boilerplate (transaction guards, SET FOREIGN_KEY_CHECKS, header comments with the two DSNs and a timestamp). Keep one template per environment so the artifact is self-describing when it lands in a ticket.
• Data diffing for reference tables: for small lookup/seed tables, --type=data compares rows rather than structure. Wire this into a check that your seeders still match production for things like countries, plans, or feature flags — not for user tables.
• Wrap it, don't call it raw: put the invocation in a Composer script or Makefile target that pins the DSNs from env vars, writes to a file, and prints a line count. Nobody remembers seven flags; everybody remembers make schema-diff.
• Programmatic use: if you need the diff as data (JSON report, Slack message, custom renderer), instantiate the comparators directly instead of parsing CLI stdout. The CLI's output format is a rendering concern; the comparator objects are the stable part.

Gotchas and Tips

• It generates SQL; it does not apply it. There is no --execute. That's a feature — but it means foreign-key ordering, DROP-before-ADD sequences, and destructive column changes are your responsibility to review. Always run the script against a restored copy first.
• Direction is easy to invert. server1 is the reference, server2 is what gets changed. Getting this backwards produces a script that drops the columns you just added. Put the DSNs in a config file with source/target names rather than positional args.
• Noise sources: AUTO_INCREMENT counters, table comments, and default charset/collation differences generate diffs that don't matter. Normalize collations across environments or you'll train the team to ignore the output. --nocomments also keeps generated files stable in version control.
• Version-sensitive parsing: MySQL 8 features (CHECK constraints, generated columns, functional indexes, utf8mb4_0900_* collations) may round-trip imperfectly or appear as spurious changes. MariaDB is close but not identical. Pin the MySQL/MariaDB version in CI to the one you run in production.
• Data mode needs a primary key and is row-oriented — it's fine for hundreds of rows and painful for millions. Never point it at a large table on a live primary during business hours.
• Credentials on the command line are visible in ps. Prefer the config file, chmod 600 it, and give the account SELECT-only on both sides. The tool never needs write access.
• Check the exit code before you build a CI gate on it — if differences don't produce a non-zero status in your pinned version, wrap the call and test the output file's size/content instead.
• Low bus factor: 747 stars but essentially no dependents and a single maintainer. Pin an exact version in composer.json, commit the lockfile, and be prepared to fork. The codebase is small enough that patching a MySQL-8 parsing quirk yourself is realistic — the comparators under src/ are the place to look.