Skip to content
All work

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

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

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

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

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

Outcome

~40
Repos running it in CI
0
Runtime dependencies
2 s
Median diff on a 300-table schema