case study · open source
Schema Diff
A CLI that reads two Postgres schemas and prints the migration you actually meant to write. Now runs in a handful of teams' CI.
- Role
- Author & maintainer
- Team
- Open source
- Year
- 2025
- Stack
- Rust · Postgres
the problem
Hand-written migrations drift from the schema they claim to describe. Every team I worked on had at least one environment where the migration history and the live database disagreed, and no fast way to prove it.
what I built
A single binary that introspects two schemas — files, a live database, or both — and emits the ordered SQL that reconciles them, plus a non-zero exit code when the diff is not empty, which is all CI needs.
Decisions
Diff the catalog, not the SQL text
Parsing migration files is a losing game. The tool reads the Postgres catalog on both sides, so it is right regardless of how the schema was created.
Refuse to guess destructive changes
A dropped column and a renamed column look identical in a diff. The tool prints both candidate migrations and makes the human choose rather than silently deleting data.
Exit codes before pretty output
The first release had no colors and no flags — just a correct diff and an exit code. That made it useful in CI on day one, which is where every adopter came from.
Rust for the single binary
Not for speed. A no-dependency binary drops into any CI image without a runtime, which removed the main objection to trying it.