Skip to content

Durable Objects migrations

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.toml / wrangler.json file, as explained below.
  2. Re-deploy your Worker using npx wrangler deploy.

You must initiate a migration process when you:

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

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.toml / wrangler.json file:

    {
    "migrations": [
    {
    "tag": "<v1>",
    "new_classes": [
    "<NewDurableObjectClass>"
    ]
    }
    ]
    }

    The Create migration contains:

    • A tag to identify the migration.
    • The array new_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.

Create migration example

To create a new Durable Object binding DURABLE_OBJECT_A, your wrangler.toml / wrangler.json file should look like the following:

{
"durable_objects": {
"bindings": [
{
"name": "DURABLE_OBJECT_A",
"class_name": "DurableObjectAClass"
}
]
},
"migrations": [
{
"tag": "v1",
"new_classes": [
"DurableObjectAClass"
]
}
]
}

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.toml / wrangler.json file.

  2. Remove references for the class you wish to delete from your Worker code.

  3. Add the following lines to your wrangler.toml / wrangler.json file.

    {
    "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.

Delete migration example

To delete a Durable Object binding DEPRECATED_OBJECT, your wrangler.toml / wrangler.json file should look like the following:

{
"migrations": [
{
"tag": "v3",
"deleted_classes": [
"DeprecatedObjectClass"
]
}
]
}

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.toml / wrangler.json file in the following way:

    {
    "durable_objects": {
    "bindings": [
    {
    "name": "<MY_DURABLE_OBJECT>",
    "class_name": "<UpdatedDurableObject>"
    }
    ]
    },
    "migrations": [
    {
    "tag": "<v3>",
    "renamed_classes": [
    {
    "from": "<OldDurableObject>",
    "to": "<UpdatedDurableObject>"
    }
    ]
    }
    ]
    }

    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.

Rename migration example

To rename a Durable Object class, from OldName to UpdatedName, your wrangler.toml / wrangler.json file should look like the following:

{
"durable_objects": {
"bindings": [
{
"name": "MY_DURABLE_OBJECT",
"class_name": "UpdatedName"
}
]
},
"migrations": [
{
"tag": "v3",
"renamed_classes": [
{
"from": "OldName",
"to": "UpdatedName"
}
]
}
]
}

Transfer migration

Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.

If you want to transfer stored Durable Objects between two Durable Object classes in the same Worker code file, use Rename migrations instead.

To apply a Transfer migration:

  1. Edit your wrangler.toml / wrangler.json file in the following way:

    {
    "durable_objects": {
    "bindings": [
    {
    "name": "<MY_DURABLE_OBJECT>",
    "class_name": "<DestinationDurableObjectClass>"
    }
    ]
    },
    "migrations": [
    {
    "tag": "<v4>",
    "transferred_classes": [
    {
    "from": "<SourceDurableObjectClass>",
    "from_script": "<SourceWorkerScript>",
    "to": "<DestinationDurableObjectClass>"
    }
    ]
    }
    ]
    }

    The Transfer migration contains:

    • A tag to identify the migration.
    • The transferred_class array, which contains objects with from, from_script, and to properties.
      • from property is the name of the source Durable Object class.
      • from_script property is the name of the source Worker script.
      • to property is the name of the destination Durable Object class.
  2. Ensure you reference the name of the new, destination Durable Object class in your Worker code.

  3. Deploy the Worker.

Transfer migration example

You can transfer stored Durable Objects from DurableObjectExample to TransferredClass from a Worker script named OldWorkerScript. The configuration of the wrangler.toml / wrangler.json file for your new Worker code (destination Worker code) would look like this:

{
"durable_objects": {
"bindings": [
{
"name": "MY_DURABLE_OBJECT",
"class_name": "TransferredClass"
}
]
},
"migrations": [
{
"tag": "v4",
"transferred_classes": [
{
"from": "DurableObjectExample",
"from_script": "OldWorkerScript",
"to": "TransferredClass"
}
]
}
]
}

Migration Wrangler configuration

  • Migrations are performed through the [[migrations]] configurations key in your wrangler.toml file or migration key in your wrangler.json file.

  • Migrations require a migration tag, which is defined by the tag property in each migration entry.

  • Migration tags are treated like unique names and are used to determine which migrations have already been applied. Once a given Worker code has a migration tag set on it, all future Worker code deployments must include a migration tag.

  • The migration list is an ordered array of tables, specified as a top-level key in your wrangler configuration file. The migration list is inherited by all environments and cannot be overridden by a specific environment.

  • All migrations are applied at deployment. Each migration can only be applied once per environment.

  • Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.

Enable SQLite storage backend on new Durable Object class migration

To allow a new Durable Object class to use a SQLite storage backend, use new_sqlite_classes on the migration in your Worker's wrangler configuration file:

{
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": [
"MyDurableObject"
]
}
]
}

For an example of a new class migration, refer to Get started: Configure Durable Object class with SQLite storage backend.

You cannot enable a SQLite storage backend on an existing, deployed Durable Object class, so setting new_sqlite_classes on later migrations will fail with an error. Automatic migration of deployed classes from their key-value storage backend to SQLite storage backend will be available in the future.