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

1. Update Scarb.toml:

[dependencies]
dojo = "1.8.0"

[dev-dependencies]
dojo_cairo_test = "1.8.0"

2. Review changelog for breaking changes

3. Build and test:

sozo build
sozo test

4. 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:

1. Test all functionality
2. Update client bindings (sozo build --typescript)
3. Update Torii if model changes (dojo-indexer skill)
4. 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