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.

Note

Updating code for an existing Durable Object class does not require a migration. To update code for an existing Durable Object class, run npx wrangler deploy. This is true even for changes to how 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 new code is backwards compatible with existing stored data.

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.

Important

After a rename or transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.

After a migration, any existing bindings to the original Durable Object class (for example, from other Workers) will automatically forward to the updated destination class. However, any Workers bound to the updated Durable Object class must update their Durable Object binding configuration in the wrangler.toml file for their next deployment.

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

Delete migrations

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 class anymore. Copy any important data to some other location before deleting.

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

wrangler.json

{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": [
        "DurableObjectExample"
      ]
    }
  ]
}

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

wrangler.json

{
  "migrations": [
    {
      "tag": "v1",
      "new_classes": [
        "DurableObjectExample"
      ]
    },
    {
      "tag": "v2",
      "renamed_classes": [
        {
          "from": "DurableObjectExample",
          "to": "UpdatedName"
        }
      ],
      "deleted_classes": [
        "DeprecatedClass"
      ]
    }
  ]
}

Note

Note that .toml files do not allow line breaks in inline tables (the {key = "value"} syntax), but line breaks in the surrounding inline array are acceptable.

Enable SQLite storage backend on new Durable Object class migration

SQLite in Durable Objects Beta

The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can opt-in to a SQLite storage backend in order to access new SQL API. Otherwise, a Durable Object class has a key-value storage backend.

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

wrangler.toml

[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["MyDurableObject"] # Array of new classes

wrangler.json

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

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.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!