OpenParable
Skip to content
← Back to skills

Migrating Motoko

Development
migrating-motoko

Migrating Motoko is an Agent Skill for development published in the caffeinelabs/motoko repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Inline actor migration with (with migration = ...). Use when upgrading canister state, changing field types, or writing migration functions without the --enhanced-migration flag.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/caffeinelabs/motoko/blob/HEAD/.agents/skills/migrating-motoko/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/migrating-motoko, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Inline Actor Migration

Migrate actor state across canister upgrades using a migration expression attached to the actor. Each upgrade has at most one migration function.

For multi-migration with a migrations/ directory, load migrating-motoko-enhanced instead.

When to Use

Implicit migration (no code needed)

The runtime allows the upgrade if the new program is compatible with the old:

  • Adding actor fields
  • Removing actor fields
  • Changing mutability (var ↔ let)
  • Adding variant constructors
  • Widening types (Nat → Int)

Explicit migration required

  • Renaming fields
  • Changing a field's type (e.g. Bool → variant, Int → Float)
  • Restructuring state (splitting/merging fields)
  • Transforming collection values

Syntax

Parenthetical expression immediately before the actor:

import Migration "migration";

(with migration = Migration.run)
actor {
  var newState : Float = 0.0;
};

Or inline:

import Int "mo:core/Int";

(with migration = func(old : { var state : Int }) : { var newState : Float } {
  { var newState = old.state.toFloat() }
})
actor {
  var newState : Float = 0.0;
};

Or using the shorthand when the imported module exports a migration field:

import { migration } "migration";

(with migration)
actor { ... };

Migration Function Rules

  • Type: func (old : { ... }) : { ... } — local, non-generic, both records must use persistable types (no functions or mutable arrays)
  • Domain: old actor fields (names and types from the previous version)
  • Codomain: new actor fields (must exist in the new actor with compatible types)
  • Runs only on upgrade — on fresh install, initializers run normally
  • If the migration traps, the upgrade is aborted and the canister stays on the old version

Field semantics

Field appears inEffect
Input and outputField is transformed
Output onlyNew field produced by migration
Input onlyField consumed (compiler warns about possible data loss)
NeitherCarried through or initialized by declaration

Migration Module Pattern

Keep migrations in a separate module. Define old types inline — do not import them from old code paths:

// migration.mo
import Types "types";
import Map "mo:core/Map";

module {
  type OldTask = { id : Nat; title : Text; completed : Bool };

  type OldActor = {
    var tasks : Map.Map<Nat, OldTask>;
    var nextId : Nat;
  };

  type NewActor = {
    var tasks : Map.Map<Nat, Types.Task>;
    var nextId : Nat;
  };

  public func run(old : OldActor) : NewActor {
    let tasks = old.tasks.map<Nat, OldTask, Types.Task>(
      func(_, task) {
        {
          id = task.id;
          title = task.title;
          due = 0;
          var status = if (task.completed) #completed else #pending;
        }
      }
    );
    { var tasks; var nextId = old.nextId };
  };
};
// main.mo
import Map "mo:core/Map";
import Types "types";
import Migration "migration";

(with migration = Migration.run)
actor {
  var tasks = Map.empty<Nat, Types.Task>();
  var nextId : Nat = 0;
};

Fields must have initializers — the migration function runs only on upgrade. On fresh install the initializers are used.

Common Patterns

Add field with default

old.users.map<Nat, OldUser, NewUser>(
  func(_, u) { { u with zipCode = "" } }
)

Add optional field

{ task with var assignee = null : ?Principal }

Bool to variant

var status = if (task.completed) #completed else #pending;

Rename a field

Consume old name, produce new name:

func(old : { var state : Int }) : { var value : Int } {
  { var value = old.state }
}

Drop a field

Consume it in the input, omit from output. Compiler warns — ensure the loss is intentional.

Checklist

  • Decide: implicit (compatible change) or explicit (migration function)
  • If explicit: define old types inline in migration.mo
  • Migration type: func (old : RecordIn) : RecordOut with persistable types
  • Attach with (with migration = Migration.run) before the actor
  • Do not use preupgrade/postupgrade for data migration
  • Verify with mops check --fix and mops build

Additional Resources

  • Load writing-motoko for general Motoko language reference
  • Load migrating-motoko-enhanced for multi-migration with --enhanced-migration