Cloudflare Durable Objects Exports vs Migrations: Rename and Transfer Classes Safely

Choose exports or legacy migrations#

The Durable Object class exports reference describes the difference:

With exports, a live SQLite-backed class is declared by its class name:

1
{
2
  "durable_objects": {
3
    "bindings": [
4
      {
5
        "name": "MY_DURABLE_OBJECT",
6
        "class_name": "MyDurableObject"
7
      }
8
    ]
9
  },
10
  "exports": {
11
    "MyDurableObject": {
12
      "type": "durable-object",
13
      "storage": "sqlite"
14
    }
15
  }
16
}

Cloudflare provisions the namespace the first time the live entry is deployed. New namespaces created through exports use SQLite; legacy-kv is only accepted for an already-provisioned key-value namespace. Storage type is immutable after provisioning, so changing storage is not a harmless configuration edit.

Rename a class without losing its namespace#

Assume the current class is OldName and the desired name is NewName. The three-deploy rollout avoids a window in which the Worker code and namespace pointer disagree.

1
import { DurableObject } from 'cloudflare:workers';
2

3
export class NewName extends DurableObject {
4
  // Keep the existing Durable Object behavior here.
5
}
6

7
export { NewName as OldName };

1
{
2
  "exports": {
3
    "OldName": {
4
      "type": "durable-object",
5
      "state": "renamed",
6
      "renamed_to": "NewName"
7
    },
8
    "NewName": {
9
      "type": "durable-object",
10
      "storage": "sqlite"
11
    }
12
  }
13
}

Transfer a class between Workers#

A transfer is a separate multi-deploy operation. The target Worker first declares an expecting-transfer entry, and the source Worker later commits the handoff with a transferred tombstone:

1
// Target Worker: prepare to receive the namespace.
2
{
3
  "exports": {
4
    "MyDO": {
5
      "type": "durable-object",
6
      "state": "expecting-transfer",
7
      "storage": "sqlite",
8
      "transfer_from": "source-worker"
9
    }
10
  }
11
}

1
// Source Worker: commit the transfer.
2
{
3
  "exports": {
4
    "MyDO": {
5
      "type": "durable-object",
6
      "state": "transferred",
7
      "transferred_to": "target-worker"
8
    }
9
  }
10
}

Deploy the target first, then the source. After the source deploy commits the handoff and the rollout completes, add the target binding and remove the source class only when no other Worker references it. The source and target must be in the same Cloudflare account and compatible dispatch-namespace context.

Read reconciliation output before cleanup#

wrangler deploy prints a Durable Object exports reconciliation block when it applies a lifecycle change or has an info notice. Treat it as part of the migration result:

1
npx wrangler deploy

Look for Renamed, Transferred, Transfer pending, referencing_scripts, and Safe to remove from exports. A stale tombstone is a cleanup hint, not permission to delete it blindly. Remove it only after all bindings and code references have moved.

For request-level tests around a Worker that uses Durable Objects, Cloudflare Workers createTestHarness() can exercise the binding and failure path before a production deploy.

A safe decision checklist#

1. Confirm whether the Worker already uses migrations or exports.
2. Identify every binding and Worker that references the old class name.
3. Decide whether the operation is a rename, a transfer, or an intentional destructive delete.
4. Use the required tombstone and live-entry pair for the operation.
5. Deploy each stage separately and inspect reconciliation output.
6. Remove stale aliases and tombstones only after the namespace has no external references.

FAQ#