migrating-motoko-enhanced

Generate timestamped enhanced migration chains for Motoko actor state evolution.

588|127|Updated May 11, 2018
One-click install
npx skills add https://github.com/caffeinelabs/motoko --skill migrating-motoko-enhanced
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: migrating-motoko-enhanced
Source: https://github.com/caffeinelabs/motoko/tree/main/.agents/skills/migrating-motoko-enhanced
Command: npx skills add https://github.com/caffeinelabs/motoko --skill migrating-motoko-enhanced

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps Motoko developers manage complex canister state evolution by defining a consistent chain of enhanced migration modules, avoiding unsafe or inconsistent upgrade logic.

Core Features & Use Cases

  • Chained enhanced migrations: Break each state change (add/rename/drop/transform) into a dedicated migration module and rely on compiler-verified chain consistency.
  • Enhanced multi-migration rules: Enforce required constraints like lexicographic ordering, uninitialized actor variables, and static actor bodies.
  • Upgrade workflow for persistent actors: Use migrations for fresh deploy initialization, safe upgrades that apply only unapplied steps, and fast-forward across skipped deployments.

Use case: you are changing persistent actor state across multiple releases (e.g., initialize new fields, rename a field, and transform a type) and want the compiler to validate the full migration chain end-to-end before deploying.

Quick Start

Use the migrating-motoko-enhanced skill to generate a timestamped migrations/ chain and the corresponding actor field declarations that match the final migrated state after all modules run in lexicographic order.

Frequently Asked Questions about migrating-motoko-enhanced

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

FAQPage Schema
How do I safely upgrade Motoko canister state across multiple releases?

To safely upgrade Motoko canister state, you define a chain of enhanced migration modules that apply persistent field initialization, renaming, and type transformations in lexicographic order. This allows the compiler to validate the full migration chain end-to-end before deploying.

What is an enhanced migration chain in Motoko actor persistence?

An enhanced migration chain in Motoko breaks each state change into a dedicated migration module exporting a public migration function. It enforces lexicographic ordering and uninitialized actor variables to ensure safe, compiler-verified actor state evolution without stable variables.

How do I initialize new persistent fields in a Motoko canister upgrade?

You initialize new persistent fields by creating a timestamped migration module within a migrations/ directory. Actor variables are declared without initializers, and the migration modules handle the state transformation to populate the new fields during the canister upgrade.

Does Motoko enhanced migration work without stable variables and preupgrade hooks?

Yes, enhanced migrations are performed without using stable variables or preupgrade/postupgrade hooks. The workflow relies entirely on migration modules and static actor bodies to manage state persistence and transformation across deployments.

Can I fast-forward Motoko canister migrations across skipped deployments?

Yes, the enhanced multi-migration workflow supports fast-forwarding across skipped deployments. When you perform a safe upgrade, the system automatically applies only the unapplied migration steps from the chain, bringing the canister state fully up to date.

What are the limitations of using inline migration bindings for Motoko canister upgrades?

Inline migration bindings do not satisfy the constraints of enhanced multi-migration rules. You must avoid inline bindings and instead use a dedicated migrations/ chain to enforce lexicographic ordering, uninitialized actor variables, and compiler-verified chain consistency.