# How we test a migration before it runs
Author: Digest Engineering
Author URL: https://dmeodigest.superblog.click/author/digest-engineering/
Published: 2026-08-18
Category: Engineering
Category URL: https://dmeodigest.superblog.click/category/engineering/
Meta Title: How we test a migration before it runs · Digest
Meta Description: Every schema change runs against a copy of production, twice, before it touches production once. The pipeline, in detail.
Tags: engineering, database, migrations
Tag URLs: engineering (https://dmeodigest.superblog.click/tag/engineering/), database (https://dmeodigest.superblog.click/tag/database/), migrations (https://dmeodigest.superblog.click/tag/migrations/)
URL: https://dmeodigest.superblog.click/how-we-test-a-migration-before-it-runs/

![A whiteboard covered in a system diagram](https://images.unsplash.com/photo-1532619675605-1ede6c2ed2b0?ixid=M3w3OTAzOTJ8MHwxfHNlYXJjaHw0fHx3aGl0ZWJvYXJkJTIwZGlhZ3JhbSUyMGVuZ2luZWVyaW5nfGVufDF8MHx8fDE3ODg2Mzg0NTJ8MA&ixlib=rb-4.1.0&w=1600&q=80&auto=format&fit=crop)

Digest runs about thirty schema migrations a month against a database of several terabytes. None has caused an outage in two years. That is not luck; it is a pipeline, and this is what is in it.

## Step one: the shadow

Every night a copy of production is restored to a shadow cluster from the previous night's snapshot. It is a real copy with real sizes, not a fixture.

## Step two: the dry run

A pull request containing a migration triggers a run against the shadow. The run records wall time, lock time per table, and the query plan for every statement. If any lock exceeds two seconds, the check fails and says which statement.

## Step three: the second run

The migration runs again on the same shadow, to prove it is idempotent, and then its down migration runs, to prove it is reversible. A migration that cannot go backwards does not merge.

## Step four: production, gradually

Migrations that add run first, in a separate deploy from the code that uses the new columns. Migrations that remove run last, one release after the code stopped using them. Nothing adds and removes in one step.

## What it costs

The shadow cluster is about four percent of our database spend. A migration takes a day longer to ship than it would with no pipeline. Both are cheap.


---
This blog is powered by Superblog. Visit https://superblog.ai to know more.
---