dojo-migrate_skill

Overview

This skill manages Dojo world migrations, upgrades, and breaking-change workflows when updating deployed Dojo worlds. It helps you inspect diffs, plan safe strategies, and execute migrations while preserving data integrity and minimizing downtime.

How this skill works

The skill inspects current world state and code changes (sozo inspect), builds and tests locally (sozo build, sozo test), and runs migrations (sozo migrate) using profiles. It classifies changes as additive or breaking, recommends strategies (new world, parallel models, or data-migration systems), and provides a checklist and troubleshooting guidance for successful upgrades.

When to use it

• Deploy changes to an existing Dojo world
• Upgrade your project to a new Dojo version
• Handle schema or model breaking changes
• Migrate data between model versions
• Validate migration on testnet before production

Best practices

• Run sozo inspect to understand new, modified, and removed resources before migrating
• Prefer additive changes where possible; treat key, type, or removed-field changes as breaking
• For breaking changes, choose between new world, parallel models, or an explicit data migration system
• Build and run full test suites (sozo build; sozo test) and test migrations on Katana or testnet first
• Keep a migration checklist: inspect, plan, build, test, migrate, verify, and monitor

Example use cases

• Add a new model and migrate safely with default profile
• Upgrade project dependencies to Dojo v1.8.0, run tests, then migrate
• Handle a changed model key by deploying parallel model versions and writing a migrator to copy data
• Deploy a new world seed to avoid irreversible breaking changes and migrate clients to the new address
• Debug migration failures by rebuilding, checking Scarb.toml compatibility, and verifying account gas profiles