CtrlK
BlogDocsLog inGet started
Tessl Logo

dojo-migrate

Manage world migrations, handle breaking changes, and upgrade Dojo versions. Use when updating deployed worlds, migrating to new versions, or handling schema changes.

Install with Tessl CLI

npx tessl i github:dojoengine/book --skill dojo-migrate
What are skills?

80

Review — 76%

Does it follow best practices?

Validation — 10 / 11 Passed

Validation for skill structure

SKILL.md
Review
Evals

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"

  1. Review changelog for breaking changes

  2. Build and test:

sozo build
sozo test
  1. 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
Repository
dojoengine/book
Commit

3c1874f

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill