Durable Object class migrations (legacy)

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.

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:

{
	// 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" ]

Create Durable Object class with key-value storage

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" ]

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:

{
	// 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" ]

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:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				// Update the binding to the new class name.
				"class_name": "UpdatedName"
			}
		]
	},
	// Renaming classes
	"migrations": [
		{
			"tag": "v3",
			"renamed_classes": [ // Array of rename directives
				{
					"from": "OldName",
					"to": "UpdatedName"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "UpdatedName"

[[migrations]]
tag = "v3"

[[migrations.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:

{
	// 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"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

[[migrations]]
tag = "v4"

[[migrations.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 migrations key in your wrangler.jsonc 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 key in your Wrangler configuration file.

• You can define the migration for each environment, as well as at the top level.

  • Top-level migration is specified at the top-level migrations key in the Wrangler configuration file.
  • Environment-level migration is specified by a migrations key inside the env key of the Wrangler configuration file ([env.<environment_name>.migrations]).
    • Example Wrangler file:
    wrangler.jsonc

    {
      // top-level default migrations
      "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] },
      ],
      "env": {
        "staging": {
          // migration override for staging
          "migrations": [
            { "tag": "v1-staging", "new_sqlite_classes": ["MyDurableObject"] },
          ],
        },
      },
    }

  • If a migration is only specified at the top-level, but not at the environment-level, the environment will inherit the top-level migration.
  • Migrations at the environment-level override migrations at the top level.

• 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.

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.