dojo-migrate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dojo Migration Management

Dojo 迁移管理

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

在更新已部署的Dojo World时，处理World迁移、版本升级及破坏性变更。

When to Use This Skill

何时使用该Skill

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

迁移我的World变更
升级至新的Dojo版本
处理破坏性变更
更新已部署的模型

What This Skill Does

该Skill的功能

Manages migration workflows:

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

管理迁移工作流：

分析迁移差异
规划迁移策略
执行迁移操作
处理破坏性变更
升级Dojo版本

Quick Start

快速开始

Update existing world:

"Migrate my changes to the deployed world"

Version upgrade:

"Upgrade my project to Dojo v1.8.0"

更新现有World：

"将我的变更迁移至已部署的World"

版本升级：

"将我的项目升级至Dojo v1.8.0"

Migration Workflow

迁移工作流

1. Inspect Changes

1. 检查变更

bash

sozo inspect

Shows:

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

bash

sozo inspect

展示内容：

新增模型
修改后的模型
新增系统/合约
修改后的系统
所有资源的状态

2. Build and Test

2. 构建与测试

bash

sozo build
sozo test

bash

sozo build
sozo test

3. Execute Migration

3. 执行迁移

bash

undefined

bash

undefined

Deploy with default dev profile

使用默认开发配置文件部署

sozo migrate

Deploy with specific profile

使用指定配置文件部署

sozo migrate --profile sepolia

undefined

sozo migrate --profile sepolia

undefined

Migration Types

迁移类型

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
}

新增模型：

cairo

// 新增模型 - 可安全添加
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct NewFeature {
    #[key]
    pub player: ContractAddress,
    pub data: u32,
}

新增系统：

cairo

// 新增系统 - 可安全添加
#[dojo::contract]
pub mod new_system {
    // 实现代码
}

为模型新增字段：

cairo

// 新增字段 - 现有数据将使用默认值（零）
struct Position {
    #[key] player: ContractAddress,
    x: u32,
    y: u32,
    z: u32,  // 新增字段
}

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

修改关键字段：

cairo

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

// 新版本 - 破坏性变更！关键字段结构不同
struct Position {
    #[key] entity_id: u32,  // 已修改关键字段
    x: u32, y: u32,
}

移除字段：

cairo

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

// 新版本 - 破坏性变更！会丢失数据
struct Stats {
    #[key] player: ContractAddress,
    health: u8,
    // mana已移除
}

修改字段类型：

cairo

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

// 新版本 - 破坏性变更！类型不兼容
struct Position {
    #[key] player: ContractAddress,
    x: u128,  // 已修改类型
    y: u128,
}

Handling Breaking Changes

处理破坏性变更

Option 1: New World

方案1：部署新World

Deploy fresh world with different seed:

toml

undefined

使用不同的种子部署全新World：

toml

undefined

dojo_dev.toml

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


```bash
sozo build && sozo migrate

[world] seed = "my_game_v2" # 不同种子对应不同的World地址


```bash
sozo build && sozo migrate

Option 2: Parallel Models

方案2：并行模型

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

保留新旧两个版本的模型：

cairo

// 保留旧模型
#[derive(Copy, Drop, Serde)]
#[dojo::model]
pub struct PositionV1 {
    #[key] player: ContractAddress,
    x: u32, y: u32,
}

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

Option 3: Data Migration System

方案3：数据迁移系统

Create a migration system to transform data:

cairo

#[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);
        }
    }
}

创建迁移系统来转换数据格式：

cairo

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

        for player in players {
            // 读取旧格式数据
            let old_pos: PositionV1 = world.read_model(player);

            // 转换为新格式
            let new_pos = PositionV2 {
                entity_id: world.uuid(),
                x: old_pos.x,
                y: old_pos.y,
                z: 0,
            };

            // 写入新格式数据
            world.write_model(@new_pos);
        }
    }
}

Version Upgrades

版本升级

Update Dojo Version

更新Dojo版本

Update
```
Scarb.toml
```
:

toml

[dependencies]
dojo = "1.8.0"

[dev-dependencies]
dojo_cairo_test = "1.8.0"

Review changelog for breaking changes
Build and test:

bash

sozo build
sozo test

Migrate:

bash

sozo migrate

更新
```
Scarb.toml
```
：

toml

[dependencies]
dojo = "1.8.0"

[dev-dependencies]
dojo_cairo_test = "1.8.0"

查看更新日志，确认是否存在破坏性变更
构建并测试：

bash

sozo build
sozo test

执行迁移：

bash

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

使用
```
sozo inspect
```
检查变更
在Katana本地环境测试变更
识别破坏性变更
如有需要，规划数据迁移方案
先在测试网测试迁移流程

Migration

迁移中

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

构建成功（
```
sozo build
```
）
测试通过（
```
sozo test
```
）
迁移执行完成（
```
sozo migrate
```
）
验证新模型/系统可正常工作
检查现有数据的完整性

Post-Migration

迁移后

Common Scenarios

常见场景

Adding a New Model

新增模型

bash

undefined

bash

undefined

1. Add model to code

1. 在代码中添加模型

2. Build

2. 构建项目

sozo build

3. Migrate

3. 执行迁移

sozo migrate

4. Verify

4. 验证结果

sozo inspect

undefined

sozo inspect

undefined

Updating System Logic

更新系统逻辑

bash

undefined

bash

undefined

1. Update system code

1. 更新系统代码

2. Build and test

2. 构建并测试

sozo build sozo test

3. Migrate (redeploys system)

3. 执行迁移（重新部署系统）

sozo migrate

4. Test updated system

4. 测试更新后的系统

sozo execute my_game-actions spawn

undefined

sozo execute my_game-actions spawn

undefined

Troubleshooting

故障排除

"Class hash not found"

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

先运行
```
sozo build
```
检查Scarb.toml中的版本兼容性
清空
```
target/
```
目录后重新构建

"Model already exists"

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

无法从World中移除模型
若结构变更，可使用带版本号的模型名称
考虑部署新的World

"Migration failed"

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

检查账户是否有足够的Gas费用
验证配置文件的配置信息
查看
```
sozo inspect
```
的输出内容

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

迁移完成后：

测试所有功能
更新客户端绑定（
```
sozo build --typescript
```
）
若模型变更，更新Torii（使用
```
dojo-indexer
```
skill）
监控World运行状态，排查潜在问题