Course contents
On this page
Lesson plan 41: Safe evolution
Plan schema and protocol evolution across mixed old and new versions.
Placement: Part 7: Building and operating applications on these engines.
Prerequisites: Lesson 40: Security and isolation, plus the earlier dependency chain.
Learning outcomes
- Plan schema and protocol evolution across mixed old and new versions.
- Trace online index construction, backfill, catch-up, cutover, and rollback under concurrent writes.
- Calculate migration load and retained compatibility obligations.
- Separate a general mechanism, a documented implementation choice, and an illustrative numerical assumption.
Teaching sequence
- Establish the motivating situation: A rolling deployment leaves old clients writing rows after a new schema field is introduced.
- Introduce the vocabulary and the correctness obligation before an optimization. Define schema changes, online indexes, backfills.
- Develop the mechanism: Apply expand, compatible dual operation, backfill, validation, and contract while tracking concurrent writes.
- Follow the complete worked example: Backfilling 900 million rows at 10000 rows/s takes 90000 s, or 25 h. Explain the assumptions, intermediate units, and limiting interpretation.
- Extend the scenario to changed load, skew, or failure, explaining compatibility, rolling upgrades, rollback, migration load.
- Connect the mechanism to a documented implementation and an alternative with a different workload fit. Close by stating the remaining cost and the next lesson dependency.
Required chapter material
Use a complete execution trace or worked calculation, supported by an annotated static diagram or table. Include language-neutral pseudocode or labeled SQL when it clarifies the mechanism. State preconditions, ownership, visibility, and failure boundaries for algorithms. Describe operational costs as well as the normal path. All questions raised in the narrative must be resolved in the text.
Visual explanation
An expand/backfill/contract timeline marks which application versions can run in each phase and how writes remain represented throughout the transition. The accompanying prose explains the arrows, state changes, or table entries so the lesson remains understandable in a plain Markdown reader.
Editorial checks
Confirm that the numerical example agrees with its units and assumptions. Check that a faster path preserves the stated contract, or explicitly identify the changed guarantee. Keep hypothetical figures separate from product measurements. Explain both an appropriate use and a limitation of the case design. Check terminology against the glossary and links against the course index.