Skip to content

secondsky/claude-skills / plugins/cloudflare-durable-objects/skills/cloudflare-durable-objects

cloudflare-durable-objects

Verified

Cloudflare Durable Objects for stateful coordination and real-time apps. Use for chat, multiplayer games, WebSocket hibernation, or encountering class export, migration, alarm errors.

FileKindSize
SKILL.mdskill md21.6 KB
references/advanced-sql-patterns.mdmarkdown15.8 KB
references/alarms-api.mdmarkdown6.5 KB
references/best-practices.mdmarkdown8.5 KB
references/common-patterns.mdmarkdown16.7 KB
references/data-modeling.mdmarkdown16.9 KB
references/error-codes.mdmarkdown7.7 KB
references/gradual-deployments.mdmarkdown13.9 KB
references/migration-cheatsheet.mdmarkdown3.2 KB
references/migrations-guide.mdmarkdown7.3 KB
references/monitoring-debugging.mdmarkdown18.2 KB
references/performance-optimization.mdmarkdown16.2 KB
references/rpc-metadata.mdmarkdown16.9 KB
references/rpc-patterns.mdmarkdown6.5 KB
references/security-best-practices.mdmarkdown15.9 KB
references/state-api-reference.mdmarkdown6.0 KB
references/stubs-routing.mdmarkdown10.6 KB
references/top-errors.mdmarkdown10.2 KB
references/typescript-config.mdmarkdown8.3 KB
references/vitest-testing.mdmarkdown18.1 KB
references/websocket-hibernation.mdmarkdown6.3 KB
references/wrangler-commands.mdmarkdown3.4 KB
scripts/check-versions.shexecutablescript593 B
scripts/migration-generator.shexecutablescript13.4 KB
scripts/setup-vitest-do.shexecutablescript10.2 KB
scripts/validate-do-config.shexecutablescript10.0 KB
templates/alarms-api-do.tsscript6.1 KB
templates/basic-do.tsscript2.9 KB
templates/gradual-deployment-config.jsoncother10.4 KB
templates/location-hints.tsscript6.8 KB
templates/multi-do-coordination.tsscript7.8 KB
templates/package.jsonmanifest384 B
templates/rpc-metadata-do.tsscript10.8 KB
templates/rpc-vs-fetch.tsscript6.0 KB
templates/state-api-patterns.tsscript5.8 KB
templates/ttl-cleanup-do.tsscript17.6 KB
templates/vitest-do-test.tsscript12.3 KB
templates/websocket-hibernation-do.tsscript6.0 KB
templates/wrangler-do-config.jsoncother2.0 KB

references/migrations-guide.md

View on GitHub
# Durable Objects Migrations Guide

Complete guide to managing DO class lifecycles with migrations.

---

## Why Migrations?

Migrations tell Cloudflare Workers runtime about changes to Durable Object classes:

**Required for:**
- ✅ Creating new DO class
- ✅ Renaming DO class
- ✅ Deleting DO class
- ✅ Transferring DO class to another Worker

**NOT required for:**
- ❌ Code changes to existing DO class
- ❌ Storage schema changes within DO

---

## Migration Types

### 1. Create New DO Class

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "COUNTER",
        "class_name": "Counter"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",                    // Unique migration identifier
      "new_sqlite_classes": [         // SQLite backend (recommended)
        "Counter"
      ]
    }
  ]
}
```

**For KV backend (legacy):**

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["Counter"]      // KV backend (128MB limit)
    }
  ]
}
```

**CRITICAL:**
- ✅ Use `new_sqlite_classes` for new DOs (1GB storage, atomic operations)
- ❌ **Cannot** change KV backend to SQLite after deployment

---

### 2. Rename DO Class

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_DO",
        "class_name": "NewClassName"    // Updated class name
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["OldClassName"]
    },
    {
      "tag": "v2",                      // New migration tag
      "renamed_classes": [
        {
          "from": "OldClassName",
          "to": "NewClassName"
        }
      ]
    }
  ]
}
```

**What happens:**
- ✅ All existing DO instances keep their data
- ✅ Old bindings automatically forward to new class
- ✅ `idFromName('foo')` still routes to same instance
- ⚠️ **Must export new class** in Worker code

---

### 3. Delete DO Class

```jsonc
{
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["Counter"]
    },
    {
      "tag": "v2",
      "deleted_classes": ["Counter"]    // Mark for deletion
    }
  ]
}
```

**What happens:**
- ✅ All DO instances **immediately deleted**
- ✅ All storage **permanently deleted**
- ⚠️ **CANNOT UNDO** - data is gone forever

**Before deleting:**
1. Export data if needed
2. Update Workers that reference this DO
3. Consider rename instead (if migrating)

---

### 4. Transfer DO Class to Another Worker

**Destination Worker:**

```jsonc
{
  "durable_objects": {
    "bindings": [
      {
        "name": "TRANSFERRED_DO",
        "class_name": "TransferredClass"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "transferred_classes": [
        {
          "from": "OriginalClass",
          "from_script": "original-worker",  // Source Worker name
          "to": "TransferredClass"
        }
      ]
    }
  ]
}
```

**What happens:**
- ✅ DO instances move to new Worker
- ✅ All storage is transferred
- ✅ Old bindings automatically forward to new Worker
- ⚠️ **Must export new class** in destination Worker

---

## Migration Rules

### Tags Must Be Unique

```jsonc
// ✅ CORRECT
{
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["A"] },
    { "tag": "v2", "new_sqlite_classes": ["B"] },
    { "tag": "v3", "renamed_classes": [{ "from": "A", "to": "C" }] }
  ]
}

// ❌ WRONG: Duplicate tag
{
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["A"] },
    { "tag": "v1", "new_sqlite_classes": ["B"] }  // ERROR
  ]
}
```

### Tags Are Append-Only

```jsonc
// ✅ CORRECT: Add new tag
{
  "migrations": [
    { "tag": "v1", ... },
    { "tag": "v2", ... }  // Append
  ]
}

// ❌ WRONG: Remove or reorder
{
  "migrations": [
    { "tag": "v2", ... }  // Can't remove v1
  ]
}
```

### Migrations Are Atomic

⚠️ **Cannot use gradual deployments** with migrations

- All DO instances migrate at once when you deploy
- No partial rollout support
- Use canary releases at Worker level, not DO level

---

## Migration Gotchas

### Global Uniqueness

DO class names are **globally unique per account**.

```typescript
// Worker A
export class Counter extends DurableObject { }

// Worker B
export class Counter extends DurableObject { }
// ❌ ERROR: Class name "Counter" already exists in account
```

**Solution:** Use unique class names (e.g., prefix with Worker name)

```typescript
// Worker A
export class CounterA extends DurableObject { }

// Worker B
export class CounterB extends DurableObject { }
```

### Cannot Enable SQLite on Existing KV-backed DO

```jsonc
// Deployed with:
{ "tag": "v1", "new_classes": ["Counter"] }  // KV backend

// ❌ WRONG: Cannot change to SQLite
{ "tag": "v2", "renamed_classes": [{ "from": "Counter", "to": "CounterSQLite" }] }
{ "tag": "v3", "new_sqlite_classes": ["CounterSQLite"] }

// ✅ CORRECT: Create new class instead
{ "tag": "v2", "new_sqlite_classes": ["CounterV2"] }
// Then migrate data from Counter to CounterV2
```

### Code Changes Don't Need Migrations

```typescript
// ✅ CORRECT: Just deploy code changes
export class Counter extends DurableObject {
  async increment(): Promise<number> {
    // Changed implementation
    let value = await this.ctx.storage.get<number>('count') || 0;
    value += 2;  // Changed from += 1
    await this.ctx.storage.put('count', value);
    return value;
  }
}

// No migration needed - deploy directly
```

Only schema changes (new/rename/delete/transfer) need migrations.

---

## Environment-Specific Migrations

You can define migrations per environment:

```jsonc
{
  // Top-level (default) migrations
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
  ],

  "env": {
    "production": {
      // Production-specific migrations override top-level
      "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["Counter"] },
        { "tag": "v2", "new_sqlite_classes": ["Analytics"] }
      ]
    }
  }
}
```

**Rules:**
- If migration defined at environment level, it overrides top-level
- If NOT defined at environment level, inherits top-level

---

## Migration Workflow

### Example: Rename DO Class

**Step 1:** Current state (v1)

```jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "OldName" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["OldName"] }
  ]
}
```

**Step 2:** Update wrangler.jsonc

```jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "MY_DO", "class_name": "NewName" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["OldName"] },
    { "tag": "v2", "renamed_classes": [{ "from": "OldName", "to": "NewName" }] }
  ]
}
```

**Step 3:** Update Worker code

```typescript
// Rename class
export class NewName extends DurableObject { }
export default NewName;
```

**Step 4:** Deploy

```bash
npx wrangler deploy
```

Migration applies atomically on deploy.

---

## Troubleshooting

### Error: "Migration tag already exists"

**Cause:** Trying to reuse a migration tag

**Solution:** Use a new, unique tag

### Error: "Class not found"

**Cause:** Class not exported from Worker

**Solution:** Ensure `export default MyDOClass;`

### Error: "Cannot enable SQLite on existing class"

**Cause:** Trying to migrate KV-backed DO to SQLite

**Solution:** Create new SQLite-backed class, migrate data manually

---

**Official Docs**: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall