Schema changes are backward compatible

A database migration never breaks the version of the service that is running: expand first, migrate, contract later.

HighChecked by hand

Applies to:
Services that own a data store
Rule id:
data.schema-changes-compatible

Why it matters

During a rolling deploy the old and new versions of the service run against the same database. A migration that renames or drops a column breaks the old version at once, and makes rollback impossible, because the previous release can no longer read the data.

How to apply it

  • Split a breaking change into steps: add the new column or table (expand), write to both and backfill, switch reads, then remove the old one (contract) in a later release.
  • Make every single migration safe for the version before it and the version after it.
  • Keep migrations in version control and run them from the pipeline.
  • Avoid long locks: add indexes concurrently, backfill in batches.
  • Drop the old column only once no running version and no rollback target reads it.

Example

Renaming orders.total to total_cents: release 1 adds total_cents and writes both; a job backfills old rows; release 2 reads total_cents; release 3, a week later, drops total. Each release can be rolled back to the one before.

References

Checklists with this rule

Related agent skill: progressive-delivery