Why a rename is five migrations

Two versions are running at once

A deploy is not an instant. For anywhere from thirty seconds to an hour, the old version and the new one are both serving traffic — that is what a rolling deploy is.

A migration runs somewhere in that window. Whatever it does to the schema, the old code is still asking the old questions on the other side of it.

The one-step rename

ALTER TABLE orders RENAME COLUMN note TO memo takes ACCESS EXCLUSIVE for about two milliseconds. Nothing is rewritten and nothing is scanned. By every measure this lesson has used so far, it is a cheap migration.

Add beside, then take away

The pattern has five steps and each is safe on its own. Add the new column beside the old one. Deploy code that writes both and reads the old. Backfill the new column from the old. Deploy code that reads the new. Only then drop the old.

Four of those are deploys and one is a migration, which is the real shape of the thing: the schema change is the easy part, and the sequencing across deploys is the work.

A view can stand in for one of the steps. Keeping the old name working as a view over the new column means the old deploy does not have to be gone before the column is.

ALTER TABLE orders ADD COLUMN memo varchar(64);

You can always tell the difference: a rename changes what the old code sees, and adding beside does not. Everything else in this pattern follows from that one fact.

MongoDBThere is no rename to run. A new field simply appears on documents written by the new version, and every reader has to cope with both shapes until a backfill catches up. The same sequencing problem, without a statement to blame it on.