Motoko Actor Migrations

Expert guidance for migrating actor state across canister upgrades with orthogonal persistence.

Critical: Never use classical persistence or pre/post upgrade

Do not use classical (legacy) persistence or system func preupgrade / system func postupgrade. They are error-prone, can leave canisters stuck if they trap, and do not scale.

Also do not use the legacy (with migration = ...) actor-attached syntax. This skill covers mops-managed migrations. When a change requires an explicit migration, write it as a timestamped file in src/backend/migrations/; the chain replays automatically.

How stable state is initialized

Stable actor fields have no initializers in the actor body. The chain in src/backend/migrations/ is what gives them values: the runtime walks it in lexicographic order, running every file on a fresh install and only the files not yet applied to the canister on an upgrade.

When to Use This Skill