Migration

Migrations are code, not configuration#

A migration is a versioned data transformation, so it belongs in review and in tests. It is registered at initialisation, not typed into an asset:

NexusForgePersistence.Initialize(options, logger, migrations: registry, keyProvider: keys);

The pipeline runs the steps in order, one edge at a time (1 → 2, then 2 → 3), and journals each step into the load result's MigrationReport, so a load can tell you exactly what it did.

The chain is bounded#

Versioning.MaxMigrationChainLength (32) refuses an absurd chain rather than looping through it. If you need more than a handful of steps, the older formats should probably be abandoned rather than carried forever.

The checklist that works#

1. Bump the schema version you pass to SaveRequestOptions.SchemaVersion.
2. Write one migration step per version edge and register them.
3. Declare the versions your build can load, so validation fails at build time rather than load time.
4. Test with a real old save, not a new one. Keep a file written by the previous build in your fixtures — a migration that has never seen real old data is a guess.
5. Never delete a member a player's value depends on unless you have decided to. PreserveAndReport keeps unknown members across a load/edit/save cycle.
6. Never reuse a schema number. Two shapes under one number is undetectable — see Schema versions.

What a migration is not for#

• It is not for changing the container format: that is the framework's business and is handled for you.
• It is not for moving values between slots. That is a game decision, made with load, edit and save.

Next#

• Unknown data — the policy that keeps a downgrade from wiping data.
• Upgrade guide — what changes when the package is upgraded.
• Samples — 03_MigrationAndVersioning does this end to end.