migrating-motoko

To migrate Motoko actor state safely during a canister upgrade, use a `(with migration = ...)` expression with a function that transforms old records into new persistable record shapes.

You need an explicit migration function for canister upgrades when performing schema evolution like field renames, type conversions, or restructuring stored collection values beyond implicit runtime compatibility.

The Motoko migration function runs only on upgrade and automatically aborts the canister upgrade process if the state transformation encounters a trap, preventing state corruption.

Yes, you can handle complex schema evolution in Motoko by using a multi-migration `migrations/` directory structure instead of a single inline `(with migration = ...)` expression.

The Motoko state migration function requires non-generic, persistable record types for both input and output to ensure actor state serialization works correctly during the upgrade process.

Yes, Motoko supports implicit compatibility migration for safe changes like adding or removing fields, changing mutability, and widening types without requiring an explicit migration function.