Document how to migrate a schema

[pathscale]

Why

The feature table named worktable_version! and migration_engine!, and that was the whole of it. Working out how to actually use them meant reading codegen/ and then finding a project that had already done it. That is a poor trade for a feature whose failure mode is silent data corruption.

What the doc leads with

Not the API. What goes wrong without it.

A persisted row carries no record of the columns that produced it, so a table whose columns change reads every existing row through the new layout and rkyv obliges. Nothing errors. The table opens cleanly and the fields have shifted by one:

{"id":"ment)   ","project_id":"item-03fd09c6-...","title":"proj-846b5542-...","status":"Reflect PR merge state in the UI"}

Every value present, every value in the wrong field. That output is real, from a five-column table that gained a sixth.

Verified, not inferred

Everything is checked against worktable 0.9.2 and a production migration:

• version defaults to 1 and must appear before columns
• old shapes use worktable_version!, stripped of persist, indexes and queries
• the table name stays fixed across versions; only version moves
• custom primary-key generator impls must be repeated in every version module
• hops compose, so v1 to v4 is three functions rather than one that knows every shape
• unchanged tables are copied, not migrated, and forgetting one is silent
• a source already at the current version reports Unsupported version: N, which is how a run is made idempotent

Two judgement calls, called out as such

Source and target are separate directories. A migration that fails partway leaves the only copy of the data intact, so there is nothing to undo.

Migration belongs in its own binary, not in application startup. A crash halfway through a boot-time migration is precisely the case with no good recovery.

Ends with a checklist, because the failure is silent and the steps are easy to half-do.