writing-migrations

To write a safe runtime migration for Moonbeam, you need a structured approach for transforming storage layouts, renaming or removing storage items, and updating pallet indices across upgrades. This involves drafting, registering, and testing migrations using OnRuntimeUpgrade patterns to ensure data integrity.

You need an on-runtime-upgrade migration when applying upgrade scenarios that require pallet index updates, renamed or removed storage items, or data format changes across Moonbeam-based networks. These migrations safely transform storage layouts during the runtime upgrade execution.

Testing runtime migrations using try-runtime checks involves building comprehensive test scaffolding that validates pre and post-upgrade states. You run local on-runtime-upgrade tests to verify the migration flow, ensuring data format changes and storage item updates maintain integrity before deployment.

The best way to handle large dataset migrations during a runtime upgrade is implementing Lazy Migrations with guardrails. This approach contrasts with OnRuntimeUpgrade patterns by distributing the storage transformation workload, preventing execution timeouts when updating extensive pallet storage items.

Yes, this migration approach explicitly supports weight accounting in runtime code. When you register OnRuntimeUpgrade migrations for Moonbeam runtimes, the process includes weight accounting to ensure the storage layout changes and pallet updates consume properly tracked computational resources.

A limitation of using OnRuntimeUpgrade for Moonbeam runtime migrations is the risk of execution timeouts when transforming large datasets. While it handles storage layout changes and pallet index updates directly during the upgrade, complex scenarios may require Lazy Migrations to avoid exceeding block weight limits.