Dojo Migration Management Skill

Dojo Migration Management

Handle world migrations, upgrades, and breaking changes when updating deployed Dojo worlds.

When to Use This Skill

"Migrate my world changes"
"Upgrade to new Dojo version"
"Handle breaking changes"
"Update deployed models"

What This Skill Does

Manages migration workflows:

Analyze migration diffs
Plan migration strategies
Execute migrations
Handle breaking changes
Upgrade Dojo versions

Quick Start

Update existing world:

"Migrate my changes to the deployed world"

Version upgrade:

"Upgrade my project to Dojo v1.8.0"

Migration Workflow

1. Inspect Changes

sozo inspect

Shows:

New models
Modified models
New systems/contracts
Modified systems
Status of all resources

2. Build and Test

sozo build
sozo test

3. Execute Migration

# Deploy with default dev profile
sozo migrate

# Deploy with specific profile
sozo migrate --profile sepolia

Migration Types

Additive Migrations (Safe)

Adding new model:

// New model - safe to add
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct NewFeature {
    #[key]
    pub player: ContractAddress,
    pub data: u32,
}

Adding new system:

// New system - safe to add
#[dojo::contract]
pub mod new_system {
    // Implementation
}

Adding model field:

// Adding field - existing data will have default (zero) value
struct Position {
    #[key] player: ContractAddress,
    x: u32,
    y: u32,
    z: u32,  // New field
}

Breaking Migrations (Dangerous)

Changing key fields:

// Old
struct Position {
    #[key] player: ContractAddress,
    x: u32, y: u32,
}

// New - BREAKING! Different key structure
struct Position {
    #[key] entity_id: u32,  // Changed key
    x: u32, y: u32,
}

Removing fields:

// Old
struct Stats {
    #[key] player: ContractAddress,
    health: u8,
    mana: u8,
}

// New - BREAKING! Data loss
struct Stats {
    #[key] player: ContractAddress,
    health: u8,
    // mana removed
}

Changing field types:

// Old
struct Position {
    #[key] player: ContractAddress,
    x: u32,
    y: u32,
}

// New - BREAKING! Type incompatible
struct Position {
    #[key] player: ContractAddress,
    x: u128,  // Changed type
    y: u128,
}

Handling Breaking Changes

Option 1: New World

Deploy fresh world with different seed:

# dojo_dev.toml
[world]
seed = "my_game_v2"  # Different seed = new world address

sozo build && sozo migrate

Option 2: Parallel Models

Keep both old and new versions:

// Keep old model
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct PositionV1 {
    #[key] player: ContractAddress,
    x: u32, y: u32,
}

// Add new model
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct PositionV2 {
    #[key] entity_id: u32,
    x: u32, y: u32, z: u32,
}

Option 3: Data Migration System

Create a migration system to transform data:

#[dojo::contract]
pub mod migrator {
    fn migrate_positions(ref self: ContractState, players: Array<ContractAddress>) {
        let mut world = self.world_default();

        for player in players {
            // Read old format
            let old_pos: PositionV1 = world.read_model(player);

            // Transform to new format
            let new_pos = PositionV2 {
                entity_id: world.uuid(),
                x: old_pos.x,
                y: old_pos.y,
                z: 0,
            };

            // Write new format
            world.write_model(@new_pos);
        }
    }
}

Version Upgrades

Update Dojo Version

Update Scarb.toml:

[dependencies]
dojo = "1.8.0"

[dev-dependencies]
dojo_cairo_test = "1.8.0"

Review changelog for breaking changes
Build and test:

sozo build
sozo test

Migrate:

sozo migrate

Migration Checklist

Pre-Migration

[ ] Review changes with sozo inspect
[ ] Test changes locally on Katana
[ ] Identify breaking changes
[ ] Plan data migration if needed
[ ] Test migration on testnet first

Migration

[ ] Build succeeds (sozo build)
[ ] Tests pass (sozo test)
[ ] Migration executes (sozo migrate)
[ ] Verify new models/systems work
[ ] Check existing data integrity

Post-Migration

[ ] Test all systems still work
[ ] Update Torii indexer if needed
[ ] Regenerate client bindings
[ ] Update client integration
[ ] Monitor for issues

Common Scenarios

Adding a New Model

# 1. Add model to code
# 2. Build
sozo build

# 3. Migrate
sozo migrate

# 4. Verify
sozo inspect

Updating System Logic

# 1. Update system code
# 2. Build and test
sozo build
sozo test

# 3. Migrate (redeploys system)
sozo migrate

# 4. Test updated system
sozo execute my_game-actions spawn

Troubleshooting

"Class hash not found"

Run sozo build first
Check Scarb.toml version compatibility
Clear target/ directory and rebuild

"Model already exists"

Models cannot be removed from world
Use versioned model names if structure changes
Consider deploying new world

"Migration failed"

Check account has funds for gas
Verify profile configuration
Review sozo inspect output

Next Steps

After migration:

Test all functionality
Update client bindings (sozo build --typescript)
Update Torii if model changes (dojo-indexer skill)
Monitor world for issues

Related Skills

dojo-deploy: Initial deployment
dojo-config: Update configuration
dojo-world: Manage permissions after migration
dojo-indexer: Update indexer for new schema
dojo-client: Update client bindings

Agent Skills: Dojo Migration Management

Install this agent skill to your local

Skill Files