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:
- Edit your
wrangler.toml / wrangler.json
file, as explained below. - 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.
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:
-
Add the following lines to your
wrangler.toml / wrangler.json
file:{"migrations": [{"tag": "<v1>","new_classes": ["<NewDurableObjectClass>"]}]}[[migrations]]tag = "<v1>" # Migration identifier. This should be unique for each migration entrynew_classes = ["<NewDurableObjectClass>"] # Array of new classes# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] insteadThe Create migration contains:
- A
tag
to identify the migration. - The array
new_classes
, which contains the new Durable Object class.
- A
-
Ensure you reference the correct name of the Durable Object class in your Worker code.
-
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" ] } ]}
# 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_classes = ["DurableObjectAClass"]
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:
-
Remove the binding for the class you wish to delete from the
wrangler.toml / wrangler.json
file. -
Remove references for the class you wish to delete from your Worker code.
-
Add the following lines to your
wrangler.toml / wrangler.json
file.{"migrations": [{"tag": "<v2>","deleted_classes": ["<ClassToDelete>"]}]}[[migrations]]tag = "<v2>" # Migration identifier. This should be unique for each migration entrydeleted_classes = ["<ClassToDelete>"] # Array of deleted class namesThe Delete migration contains:
- A
tag
to identify the migration. - The array
deleted_classes
, which contains the deleted Durable Object classes.
- A
-
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" ] } ]}
# Remove the binding for the DeprecatedObjectClass DO#[[durable_objects.bindings]]#name = "DEPRECATED_OBJECT"#class_name = "DeprecatedObjectClass"
[[migrations]]tag = "v3" # Should be unique for each entrydeleted_classes = ["DeprecatedObjectClass"] # Array of new classes
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:
-
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>"}]}]}[[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 entryrenamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directivesThe Rename migration contains:
- A
tag
to identify the migration. - The
renamed_classes
array, which contains objects withfrom
andto
properties.from
property is the old Durable Object class name.to
property is the renamed Durable Object class name.
- A
-
Reference the new Durable Object class name in your Worker code.
-
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" } ] } ]}
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.[[durable_objects.bindings]]name = "MY_DURABLE_OBJECT"class_name = "UpdatedName"
# Renaming classes[[migrations]]tag = "v3"renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
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:
-
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>"}]}]}[[durable_objects.bindings]]name = "<MY_DURABLE_OBJECT>"class_name = "<DestinationDurableObjectClass>"[[migrations]]tag = "<v4>" # Migration identifier. This should be unique for each migration entrytransferred_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 withfrom
,from_script
, andto
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.
- A
-
Ensure you reference the name of the new, destination Durable Object class in your Worker code.
-
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" } ] } ]}
# destination worker[[durable_objects.bindings]]name = "MY_DURABLE_OBJECT"class_name = "TransferredClass"
# Transferring class[[migrations]]tag = "v4"transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
-
Migrations are performed through the
[[migrations]]
configurations key in yourwrangler.toml
file ormigration
key in yourwrangler.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.
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" ] } ]}
[[migrations]]tag = "v1" # Should be unique for each entrynew_sqlite_classes = ["MyDurableObject"] # Array of new classes
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.