dojo-migrate

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

Manages migration workflows:

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

Update existing world:

```

"Migrate my changes to the deployed world"

```

Version upgrade:

```

"Upgrade my project to Dojo v1.8.0"

```

1. Inspect Changes

```bash

sozo inspect

```

Shows:

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

2. Build and Test

```bash

sozo build

sozo test

```

3. Execute Migration

```bash

# Deploy with default dev profile

sozo migrate

# Deploy with specific profile

sozo migrate --profile sepolia

```

Additive Migrations (Safe)

Adding new model:

```cairo

// New model - safe to add

#[derive(Copy, Drop, Serde)]

#[dojo::model]

pub struct NewFeature {

#[key]

pub player: ContractAddress,

pub data: u32,

}

```

Adding new system:

```cairo

// New system - safe to add

#[dojo::contract]

pub mod new_system {

// Implementation

}

```

Adding model field:

```cairo

// 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:

```cairo

// 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:

```cairo

// 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:

```cairo

// 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,

}

```

Option 1: New World

Deploy fresh world with different seed:

```toml

# dojo_dev.toml

[world]

seed = "my_game_v2" # Different seed = new world address

```

```bash

sozo build && sozo migrate

```

Option 2: Parallel Models

Keep both old and new versions:

```cairo

// 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:

```cairo

#[dojo::contract]

pub mod migrator {

fn migrate_positions(ref self: ContractState, players: Array) {

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);

}

}

}

```

Update Dojo Version

1. Update Scarb.toml:

```toml

[dependencies]

dojo = "1.8.0"

[dev-dependencies]

dojo_cairo_test = "1.8.0"

```

1. Review changelog for breaking changes

1. Build and test:

```bash

sozo build

sozo test

```

1. Migrate:

```bash

sozo migrate

```

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

Adding a New Model

```bash

# 1. Add model to code

# 2. Build

sozo build

# 3. Migrate

sozo migrate

# 4. Verify

sozo inspect

```

Updating System Logic

```bash

# 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

```

"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

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

• 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