Durable Objects migrations

A migration is a mapping process from a class name to a runtime state.

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.

This process informs the Workers runtime of the changes and provides it with instructions on how to deal with those changes.

The most common migration performed is a new class migration, which informs the runtime that a new Durable Object class is being uploaded.

Migrations can also be used for transferring stored data between two Durable Object classes:

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

The destination class (the class that stored Durable Objects are being transferred to) for a rename or transfer migration must be exported by the deployed Worker.

Migrations can also be used to delete a Durable Object class and its stored Durable Objects.

​​ Durable Object migrations in wrangler.toml

Migrations are performed through the [[migrations]] configurations key in your wrangler.toml 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.toml 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.

To illustrate an example migrations workflow, the DurableObjectExample class can be initially defined with:

wrangler.toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DurableObjectExample"] # Array of new classes

Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity. For example, you may want to rename the DurableObjectExample class to UpdatedName and delete an outdated DeprecatedClass entirely.

wrangler.toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DurableObjectExample"] # Array of new classes

[[migrations]]
tag = "v2"
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
deleted_classes = ["DeprecatedClass"] # Array of deleted class names