Durable Object class migrations (legacy)

Last updated Sep 28, 2026 Prefer declarative exports for new Workers

For new Workers, use the declarative exports field instead of the migrations array described on this page. The migrations array remains fully supported for existing Workers and continues to work as documented here.

You cannot use migrations and Durable Object entries in exports in the same Worker configuration. Workflow entries in exports can be used alongside migrations. To move an existing Worker from migrations to exports, refer to Migrate from migrations to exports.

A migration is a mapping process from a class name to a runtime state. This process communicates the changes to the Workers runtime and provides the runtime with instructions on how to deal with those changes.

To apply a migration, you need to:

  1. Edit your Wrangler configuration file (refer to Migration Wrangler configuration).
  2. Re-deploy your Worker using npx wrangler deploy.

You must initiate a migration process when you:

  • Create a new Durable Object class.
  • Rename a Durable Object class.
  • Delete a Durable Object class.
  • Transfer an existing Durable Objects class.

Note

Updating the code for an existing Durable Object class does not require a migration. To update the code for an existing Durable Object class, run npx wrangler deploy. This is true even for changes to how the code interacts with persistent storage. Because of global uniqueness, you do not have to be concerned about old and new code interacting with the same storage simultaneously. However, it is your responsibility to ensure that the new code is backwards compatible with existing stored data.

Create migration

The most common migration performed is a new class migration, which informs the runtime that a new Durable Object class is being uploaded. This is also the migration you need when creating your first Durable Object class.

To apply a Create migration:

  1. Add the following lines to your Wrangler configuration file:
   {
     "migrations": [
       {
         "tag": "<v1>", // Migration identifier. This should be unique for each migration entry
         "new_sqlite_classes": [ // Array of new classes
           "<NewDurableObjectClass>"
         ]
       }
     ]
   }
   ```

```toml
   [[migrations]]
   tag = "<v1>"
   new_sqlite_classes = [ "<NewDurableObjectClass>" ]
   ```

The Create migration contains:
   - A `tag` to identify the migration.
   - The array `new_sqlite_classes`, which contains the new Durable Object class.
2. Ensure you reference the correct name of the Durable Object class in your Worker code.
3. Deploy the Worker.

&lt;details>

&lt;summary>

Create migration example

&lt;/summary>

To create a new Durable Object binding &lt;code>DURABLE_OBJECT_A&lt;/code>, your Wrangler configuration file should look like the following:

```jsonc
{
    // Creating a new Durable Object class
    "durable_objects": {
        "bindings": [
            {
                "name": "DURABLE_OBJECT_A",
                "class_name": "DurableObjectAClass"
            }
        ]
    },
    // Add the lines below for a Create migration.
    "migrations": [
        {
            "tag": "v1",
            "new_sqlite_classes": [
                "DurableObjectAClass"
            ]
        }
    ]
}

[[durable_objects.bindings]]
name = "DURABLE_OBJECT_A"
class_name = "DurableObjectAClass"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectAClass" ]

</details>

Create Durable Object class with key-value storage

Recommended SQLite-backed Durable Objects

Cloudflare recommends all new Durable Object namespaces use the SQLite storage backend. These Durable Objects can continue to use storage key-value API.

Additionally, SQLite-backed Durable Objects allow you to store more types of data (such as tables), and offer Point In Time Recovery API which can restore a Durable Object's embedded SQLite database contents (both SQL data and key-value data) to any point in the past 30 days.

Creating new namespaces with the key-value storage backend is no longer supported for accounts without an existing key-value-backed namespace. The key-value storage backend remains available for existing namespaces, and a migration path from the key-value storage backend to the SQLite storage backend will be available in the future.

Use new_classes on the migration in your Worker's Wrangler file to create a Durable Object class with the key-value storage backend:

{
    "migrations": [
        {
            "tag": "v1", // Should be unique for each entry
            "new_classes": [
                // Array of new classes
                "MyDurableObject",
            ],
        },
    ],
}

[[migrations]]
tag = "v1"
new_classes = [ "MyDurableObject" ]

Note

Durable Objects are available both on Workers Free and Workers Paid plans.

  • Workers Free plan: Only Durable Objects with SQLite storage backend are available.
  • Workers Paid plan: Durable Objects with the SQLite storage backend are available. The key-value storage backend is only available to accounts that already have a key-value-backed namespace.

If you wish to downgrade from a Workers Paid plan to a Workers Free plan, you must first ensure that you have deleted all Durable Object namespaces with the key-value storage backend.

Delete migration

Running a Delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.

  • Do not run a Delete migration on a class without first ensuring that you are not relying on the Durable Objects within that Worker anymore, that is, first remove the binding from the Worker.
  • Copy any important data to some other location before deleting.
  • You do not have to run a Delete migration on a class that was renamed or transferred.

To apply a Delete migration:

  1. Remove the binding for the class you wish to delete from the Wrangler configuration file.
  2. Remove references for the class you wish to delete from your Worker code.
  3. Add the following lines to your Wrangler configuration file.
   {
     "migrations": [
       {
         "tag": "<v2>", // Migration identifier. This should be unique for each migration entry
         "deleted_classes": [ // Array of deleted class names
           "<ClassToDelete>"
         ]
       }
     ]
   }
   ```

```toml
   [[migrations]]
   tag = "<v2>"
   deleted_classes = [ "<ClassToDelete>" ]
   ```

The Delete migration contains:
   - A `tag` to identify the migration.
   - The array `deleted_classes`, which contains the deleted Durable Object classes.
4. Deploy the Worker.

&lt;details>

&lt;summary>

Delete migration example

&lt;/summary>

To delete a Durable Object binding &lt;code>DEPRECATED_OBJECT&lt;/code>, your Wrangler configuration file should look like the following:

```jsonc
{
    // Remove the binding for the DeprecatedObjectClass DO
    // {"durable_objects": {"bindings": [
    //   {
    //     "name": "DEPRECATED_OBJECT",
    //     "class_name": "DeprecatedObjectClass"
    //   }
    // ]}}
    "migrations": [
        {
            "tag": "v3", // Should be unique for each entry
            "deleted_classes": [ // Array of deleted classes
                "DeprecatedObjectClass"
            ]
        }
    ]
}

[[migrations]]
tag = "v3"
deleted_classes = [ "DeprecatedObjectClass" ]

</details>

Rename migration

Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.

To apply a Rename migration:

  1. Update the previous class name to the new class name by editing your Wrangler configuration file in the following way:

jsonc { "durable_objects": { "bindings": [ { "name": "<MY_DURABLE_OBJECT>", "class_name": "<UpdatedDurableObject>" // Update the class name to the new class name } ] }, "migrations": [ { "tag": "<v3>", // Migration identifier. This should be unique for each migration entry "renamed_classes": [ // Array of rename directives { "from": "<OldDurableObject>", "to": "<UpdatedDurableObject>" } ] } ] }

```toml [[durable_objects.bindings]] name = "" class_name = ""

[[migrations]] tag = ""

[[migrations.renamed_classes]] from = "" to = "" ```

The Rename migration contains: - A tag to identify the migration. - The renamed_classes array, which contains objects with from and to properties. - from property is the old Durable Object class name. - to property is the renamed Durable Object class name. 2. Reference the new Durable Object class name in your Worker code. 3. Deploy the Worker.

<details>

<summary>

Rename migration example

</summary>

To rename a Durable Object class, from <code>OldName</code> to <code>UpdatedName</code>, your Wrangler configuration file should look like the following: