Part 4 of 13 · 2 min read
Old state meets new code; version it or watch it break
Think of opening a decades-old file format in current software. Without a converter built in, the program either refuses the file or reads it wrong. The file's shape and the program's expectations have drifted apart.
In plain words: a schema version is a number stored with the state saying which shape it has, and a migration is a function that upgrades state from one version to the next -- without this, a checkpoint saved by an older version of your code simply fails to load once the code has moved on, because the fields the new code expects to find are not the fields the old state actually has.
A worked example. A state saved under schema v1 (with a msgs field, no budget) fails to load under the current v3 code with a KeyError, because v3's load expects messages and budget, neither of which exist yet in the raw v1 shape. Running the state through migrate first fixes this: step one renames msgs to messages and bumps the version to 2; step two adds a default budget of 10.0 and bumps to 3. After migration, the same v1 state loads cleanly under v3 code. State claiming a version newer than the code's own CURRENT (3) is refused outright rather than guessed at.
The key lines. From code/mini-durable/durable.py:
# from code/mini-durable/durable.py
def migrate(state):
v = state.get("v", 1)
s = dict(state)
if v < 2:
s["messages"] = s.pop("msgs"); v = 2
if v < 3:
s["budget"] = s.get("budget", 10.0); v = 3
if v > CURRENT:
raise ValueError("state is newer than this code")
Read it as: each if v < N block is a single, self-contained upgrade step. They run in sequence rather than jumping straight to the target version. A v1 state passes through both blocks. A v2 state only passes through the second. This chain-of-single-steps structure is what lets the function handle every old version. No separate migration path has to be hand-written for each one.
Schema version, migration
A schema version is a number stored with the state saying which shape it has. A migration is a function that upgrades state from one version to the next.
Example: the KeyError that a raw, unmigrated v1 state produces against v3 code is the exact failure a schema version exists to prevent -- not by stopping the mismatch from happening, but by making it detectable and fixable with a migration chain instead of a crash with no explanation.