The library at the east end of the village had not closed its doors in a hundred years.

You found books by colour there. Red ribbon meant farming, blue meant seafaring, brown meant herbs, green meant old tales. The elders could find their shelf in the dark — reach up, feel the nap of the ribbon under a fingertip, and there it was.

But the books kept coming. Red went from one shelf to three, three to seven, and finding Frost Dates on the North Slope meant groping along red halfway across the hall. So Mei, the head librarian, decided on numbers: a small paper tag glued to every spine, three figures on it — floor, section, position. Any book in the building, one number away.

The trouble was that the library could not close. Not even for half a day. A hundred years is a hundred years.

Mei did not cut the ribbons off one night and be done with it.

The first thing she did was give every newly arrived book both a ribbon and a tag. Ribbon tied the old way, tag written the new way. The readers who came in those days noticed nothing at all — they still reached for the ribbons, and the ribbons were still there.

The second thing: she sent her apprentice Man through the stacks after closing, lamp in hand, adding tags to the old books, shelf by shelf. Slow work — two hundred a night. He never touched a ribbon. Not one. It took seven weeks.

The third thing: when Man finished the last shelf, Mei announced nothing. She took a notebook and pulled three hundred books at random, and for each one asked whether the ribbon and the tag told the same story about where it lived. Eleven disagreed — shelves had been moved partway through and the positions had slipped. She fixed those eleven, pulled another three hundred, and found no disagreement.

The fourth thing: the front desk changed its answer. Someone asked where the farming books were and the librarian said “three, fourteen.” But not a single ribbon was cut. One errand boy still went straight into the red section and dug around himself — and still found what he wanted. For the first two weeks, any time the new way stumbled, a librarian could fall back to “the shelf with the red ribbons” without anyone noticing.

The fifth thing came two months later. Mei stood by the door listening for many days, and not one person said the word “ribbon” any more. Only then did she have Man untie them, one by one, and pack them into a box.

— By now you have probably recognised it: this is expand–contract migration, also called parallel change.

What it is

The standard way to change a data structure or an interface contract without downtime. The insight is humble: you cannot swap the storage and every reader of that storage in the same instant. During a rolling update both versions of the code are running at once, and clients upgrade on their own schedule entirely. So don’t perform a switch — perform an overlap:

1. expand — both representations exist side by side, dual write keeps them in step, and the old path is left completely untouched;
2. backfill — a background job brings historical rows up to the new representation, in batches;
3. verify — sample or compare both sides and confirm they agree before going further;
4. cutover — move reads to the new side, leaving the old one intact as a rollback path;
5. contract — only once you are sure no old readers remain, drop the old column or old API.

Every step is independently reversible, because at every instant of the whole process, both the new reader and the old reader get a correct answer. The migrations that go wrong almost always skipped step 3, or ran step 5 too early — and discovered on the day the old column was dropped that some forgotten cronjob had been reading it all along.

Metaphor mapping

• a hundred years without closing → the zero-downtime constraint
• the ribbons → the old schema / old API version
• the numbered paper tags → the new schema / new version
• new books getting both ribbon and tag → dual write during the expand phase
• Man tagging the stacks by lamplight → backfill of historical data in batches
• never cutting a single ribbon → backward compatibility; the old path stays live throughout
• pulling three hundred books to compare → post-migration consistency verification (reconciliation)
• the eleven that disagreed → drift accumulated during backfill; fix before cutting over
• the front desk answering with numbers → read-path cutover
• the errand boy still digging through red → clients or pods that haven’t upgraded yet
• being able to say “the red-ribbon shelf” at any moment → the rollback path
• Mei listening by the door for days → deprecation metrics on the old path
• untying the ribbons two months later → the contract phase, only after no old readers remain