writing-migrations

Name: writing-migrations
Availability: InStock
Author: Moonsong-Labs

Automate Moonbeam runtime migrations with OnRuntimeUpgrade and try-runtime checks.

3|2|Updated Mar 9, 2026

Search Tags:#testing #migration #pallet #runtime-upgrade #on-runtime-upgrade

Ready to run

npx skills add https://github.com/Moonsong-Labs/knowledge-work-plugins --skill writing-migrations-moonsong-labs

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: writing-migrations
Source: https://github.com/Moonsong-Labs/knowledge-work-plugins/tree/main/moonbeam-engineering/skills/writing-migrations
Command: npx skills add https://github.com/Moonsong-Labs/knowledge-work-plugins --skill writing-migrations-moonsong-labs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Moonbeam runtime migrations are complex and error-prone. This skill provides a structured approach to writing, registering, and testing migrations that safely transform storage layouts, rename or remove storage items, update data formats, and adjust pallet indices across upgrades.

Core Features & Use Cases

Guidance through the full migration lifecycle: drafting, registering, testing, deploying, and removing migrations.
Patterns for OnRuntimeUpgrade and Lazy Migrations to handle both small and large datasets with guardrails.
Comprehensive testing strategies including unit tests, try-runtime checks, and pre/post-upgrade verification to ensure data integrity.

Quick Start

Run a test on_runtime_upgrade against a local runtime to validate the migration flow.

Frequently Asked Questions about writing-migrations

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write a safe runtime migration for Moonbeam storage layout changes?▼

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.

When do I need an on-runtime-upgrade migration for pallet index updates?▼

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.

How do I test runtime migrations using try-runtime checks?▼

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.

What is the best way to handle large dataset migrations during a runtime upgrade?▼

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.

Does this migration approach support weight accounting in runtime code?▼

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.

What are the limitations of using OnRuntimeUpgrade for Moonbeam runtime migrations?▼

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.