/do-migrate

name: cloudflare-durable-objects:migrate
description: Interactive Durable Objects migration assistant. Guides through new class creation, renaming, deletion, and transfer migrations with validation.

Durable Objects Migration Command

Interactive command to safely create and manage Durable Objects migrations. Handles new classes, renaming, deletion, and transfers with automatic validation and backup.

Overview

This command simplifies DO migration management by:

• Generating correct migration syntax for all migration types
• Validating migration configuration before committing
• Auto-incrementing migration tags (v1, v2, v3...)
• Backing up wrangler.jsonc before changes
• Checking for common migration errors
• Providing rollback instructions

Step 1: Analyze Current Configuration

Before prompting user, analyze the current project state:

Read wrangler.jsonc

cat wrangler.jsonc

Parse configuration to extract:

• Existing Durable Object bindings
• Current migrations array
• Last migration tag (for auto-increment)
• Class names currently in use

Identify Migration Context

Determine project state:

**Case 1: No Existing Migrations**

• First-time migration setup
• Recommend new_sqlite_classes for all DOs
• Suggest v1 as initial tag

**Case 2: Existing Migrations**

• Extract last migration tag
• Suggest next sequential tag (v2, v3, etc.)
• Show migration history for context

**Case 3: No DO Bindings**

• No DOs configured yet
• Recommend running `/do-setup` first
• Offer to continue anyway (for planning)

Display Current State

Show user the current configuration:

Current Durable Objects Configuration:

Bindings:
  - MY_DO → MyDurableObject
  - CHAT_ROOM → ChatRoom

Migrations:
  - v1: new_sqlite_classes [MyDurableObject]
  - v2: new_sqlite_classes [ChatRoom]

Next migration tag: v3

Step 2: Gather Migration Requirements

Use AskUserQuestion tool to determine migration type and details:

Question 1: Migration Type

**Question**: "What type of migration do you need to perform?" **Header**: "Migration Type" **Options**:

• **New Class** - Add a new Durable Object class
• Description: "Create migration for newly added DO class (new_sqlite_classes)"
• **Rename Class** - Rename existing Durable Object class
• Description: "Migrate DO instances to renamed class (renamed_classes)"
• **Delete Class** - Remove Durable Object class
• Description: "Delete all DO instances and remove class (deleted_classes)"
• **Transfer Class** - Move DO class to different Worker script
• Description: "Transfer DO instances to another script (transferred_classes)"

Question 2: Storage Backend (Only for "New Class")

If user selected **New Class**, ask:

**Question**: "Which storage backend will this Durable Object use?" **Header**: "Storage Backend" **Options**:

• **SQL Storage (Recommended)** - SQLite backend with 1GB limit
• Description: "Use new_sqlite_classes in migration"
• **Key-Value Storage** - KV backend with 128MB limit
• Description: "Use new_classes in migration"

**Note**: For other migration types, storage backend is already determined by existing class.

Question 3: Class Details

Gather class name(s) based on migration type:

For "New Class"

**Prompt**: "Enter the name of the new Durable Object class to add:"

Show existing class names for reference:

Existing classes:
  - MyDurableObject
  - ChatRoom

New class name: _______

Validation:

• Must be PascalCase
• Must not already exist in bindings
• Must be exported in Worker code (check src/)

For "Rename Class"

**Prompt 1**: "Enter the current class name to rename:"

Show dropdown/autocomplete of existing class names:

Select class to rename:
  > MyDurableObject
    ChatRoom

**Prompt 2**: "Enter the new class name:"

Validation:

• New name must be PascalCase
• New name must not conflict with existing classes
• Warn about code changes required

For "Delete Class"

**Prompt**: "Enter the class name to delete:"

Show dropdown of existing classes with WARNING:

⚠️  WARNING: Deleting a class permanently destroys all DO instances and data!

Select class to delete:
  > MyDurableObject
    ChatRoom

This action cannot be undone. Continue? [y/N]

Require explicit confirmation due to data loss.

For "Transfer Class"

**Prompt 1**: "Enter the class name to transfer:"

Show existing classes:

Select class to transfer:
  > MyDurableObject
    ChatRoom

**Prompt 2**: "Enter the destination Worker script name:"

Current script: my-worker
Destination script: _______

Validation:

• Destination script must exist
• Destination script must have wrangler.jsonc configured

Question 4: Migration Tag

**Question**: "What tag should this migration use?" **Header**: "Migration Tag"

**Suggested Tag**: Auto-calculated based on existing migrations (e.g., v3)

**Options**:

• **Use Suggested Tag (v3)** - Auto-incremented version
• Description: "Recommended: sequential versioning"
• **Custom Tag** - Specify custom migration tag
• Description: "Advanced: use semantic versioning (e.g., v2.1.0)"

If **Custom Tag** selected, prompt:

Enter custom migration tag: _______

Validation:

• Tag must be unique
• Tag must not already exist in migrations array
• Warn if tag breaks sequential pattern

Step 3: Validate Migration

Before generating migration, perform validation checks:

Check 1: Class Export Validation

For **New Class** migrations, verify class is exported:

# Check if class is exported in main file
grep "export class NEW_CLASS_NAME" src/index.ts

If not found:

⚠️  WARNING: Class 'MyNewDO' not found in src/index.ts

Before deploying, ensure:
  export class MyNewDO extends DurableObject { ... }

Continue anyway? [y/N]

Check 2: Binding Validation

For **New Class** migrations, check if binding exists:

# Check wrangler.jsonc for binding
jq '.durable_objects.binding