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