Time to test our migrations! — Seqwall

Andrey Karchevsky — Tue, 06 May 2025 20:39:25 +0000

A few months ago, I started wondering: “How should we actually test database migrations?”

(Yes, that thing no one really does.)

Well — sometimes people do test them, to be fair. The standard approach usually involves writing integration tests and checking how the application behaves with the new schema version.

But honestly, that’s not nearly enough to ensure the migration itself is correct.

A lot can go wrong:

ALTER TABLE suddenly takes an EXCLUSIVE ACCESS lock and production freezes until it’s done.
An index works on your local machine — but silently fails on prod.
A migration wipes out data (someone forgot to delete a DROP TABLE used for debugging), and the last dump was from the Mesozoic era.
…

There are many hypothetical issues like this — enough material for several talks.

I decided to focus on something simple and fundamental:

How do we validate that a migration is correct in terms of schema state?

My reasoning

A valid migration should:

apply cleanly;
be reversible (a downgrade should work);
be idempotent (you can apply/rollback it as many times as needed);
and most importantly — after a up + down, the schema should match the original, semantically.

That led me to build a CLI tool that tests your migrations for schema correctness.

You can read more about the methodology in the project’s repository.

So I’d really appreciate your help: bug reports, issues, PRs — all welcome.

👉 Seqwall on GitHub: https://github.com/realkarych/seqwall

Forem: Andrey Karchevsky

Time to test our migrations! — Seqwall