Evolving APIs and Schemas

Overview

A schema change is a distributed-systems problem wearing a one-line diff. The code that reads your data is not only the code you are about to deploy — it is also the version still running during the rollout, the client you do not control, and the rows written by last year's binary.

Core principle: Old readers and new readers must both be correct at every instant of the rollout. If there is a moment when that is false, the change needs more steps, not more confidence.

Companion skills: writing-plans for sequencing multi-release changes, verifying-before-completion before running anything destructive.

The Iron Law

ADDITIVE FIRST, DESTRUCTIVE LAST — NEVER IN THE SAME DEPLOY

Adding is reversible. Dropping, renaming, and narrowing are not. Between them must sit at least one fully deployed release where both shapes work, plus enough time to be sure you will not roll back across it.