Problem
Once a database exists, schema changes need to be reproducible across
development, staging, and production. Ad-hoc SQL applied by hand diverges
between environments, and the divergence is usually discovered during an
incident.
What to do
- Versioned migration files committed to the repository, applied in order.
- Migrations run as an explicit deploy step, not automatically at application
boot — concurrent instances racing to migrate is a real failure mode.
- Every migration reversible, with the down path actually exercised in CI
rather than assumed.
- Expand-contract for breaking changes: add the new column, backfill, switch
reads, then drop the old one in a later release. Never in one step.
- Test migrations against a realistically sized dataset — a migration that
takes eight hours and locks a table is a different problem than one that runs
in a second.
Acceptance criteria
Notes
Exercising the down path in CI is the part teams skip, and it is the part that
matters at 3am.
Problem
Once a database exists, schema changes need to be reproducible across
development, staging, and production. Ad-hoc SQL applied by hand diverges
between environments, and the divergence is usually discovered during an
incident.
What to do
boot — concurrent instances racing to migrate is a real failure mode.
rather than assumed.
reads, then drop the old one in a later release. Never in one step.
takes eight hours and locks a table is a different problem than one that runs
in a second.
Acceptance criteria
Notes
Exercising the down path in CI is the part teams skip, and it is the part that
matters at 3am.