Durable Object class migrations (legacy)·续
- Transfer migration
- Migration Wrangler configuration

Durable Object class migrations (legacy)·续

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

</details>

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.

Note

Do not run a Create migration for the destination class before running a Transfer migration. The Transfer migration will create the destination class for you.

To apply a Transfer migration:

Edit your Wrangler configuration file in the following way:

   {
     "durable_objects": {
       "bindings": [
         {
           "name": "<MY_DURABLE_OBJECT>",
           "class_name": "<DestinationDurableObjectClass>"
         }
       ]
     },
     "migrations": [
       {
         "tag": "<v4>", // Migration identifier. This should be unique for each migration entry
         "transferred_classes": [
           {
             "from": "<SourceDurableObjectClass>",
             "from_script": "<SourceWorkerScript>",
             "to": "<DestinationDurableObjectClass>"
           }
         ]
       }
     ]
   }
   ```

```toml
   [[durable_objects.bindings]]
   name = "<MY_DURABLE_OBJECT>"
   class_name = "<DestinationDurableObjectClass>"

[[migrations]]
   tag = "<v4>"

[[migrations.transferred_classes]]
     from = "<SourceDurableObjectClass>"
     from_script = "<SourceWorkerScript>"
     to = "<DestinationDurableObjectClass>"
   ```

The Transfer migration contains:
   - A `tag` to identify the migration.
   - The `transferred_classes` 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.

&lt;details>

&lt;summary>

Transfer migration example

&lt;/summary>

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

```jsonc
{
    // 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"

</details>

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

    {
      // 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](https://developers.cloudflare.com/durable-objects/reference/environments/).
- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.

Important

- 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.
- You should not create the destination Durable Object class before running a Rename or Transfer migration. The migration will create the destination class for you.
- 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` configuration file for their next deployment.

Note

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

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.

Important

Durable Object migrations are atomic operations and cannot be gradually deployed. To provide early feedback to developers, new Worker versions with new migrations cannot be uploaded. Refer to [Gradual deployments with Durable Objects](https://developers.cloudflare.com/workers/versions-and-deployments/gradual-deployments/with-durable-objects/) for more information.

Was this helpful?

YesNo

## On this page

[![](data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NiIgaGVpZ2h0PSIzMCIgZmlsbD0ibm9uZSIgdmlld0JveD0iMCAwIDY2IDMwIj48ZyBjbGlwLXBhdGg9InVybCgjY2xpcDBfNzQ2XzIpIj48cGF0aCBmaWxsPSIjZmY5OTEwIiBkPSJNNTMuMTIgMTMuMTI1YzYuOTk3IDAgMTIuNjY4IDUuNzA4IDEyLjY2OCAxMi43NSAwIDEuMjU1LS4xOCAyLjQ2OC0uNTE2IDMuNjE0YS43Mi43MiAwIDAgMS0uNjk0LjUxMUg0Ni45NTNhLjM3NS4zNzUgMCAwIDEtLjM0OC0uNTFsLjMzNy0uODgyYzEuMDc2LTIuODMzIDQuMTQ2LTUuMTU0IDYuOTg3LTUuMjlsNS4zODQtLjI3N2EuNTQzLjU0MyAwIDAgMCAuNTE0LS41NDQuNTQzLjU0MyAwIDAgMC0uNTEtLjU0NGwtNS4wNTYtLjI5OWMtMi43MTgtLjE0LTQuMDQ2LTIuNTYtMy4zMTUtNS4wODFsLjg0Mi0yLjkwMmEuNzIuNzIgMCAwIDEgLjY0Ni0uNTI3cS4zNC0uMDIuNjg2LS4wMTkiLz48cGF0aCBmaWxsPSIjZmY1ZjA4IiBkPSJNMzUuNjA5IDBjNy4yOTUgMCAxMy40MjQgNS4wMjUgMTUuMTU3IDExLjgyNC4wNzMuMjg1LjA1LjU4Ni0uMDU0Ljg2MmwtMS4zODggMy42NzdjLTEuMDc2IDIuODMzLTMuODQyIDUuMjktNi45NyA1LjI5bC0yNC4xMDUuMjc4YS41MzMuNTMzIDAgMCAwLS41MjUuNTM1YzAgLjI5My4yMzQuNTMxLjUyNC41MzVsMjMuNzY1LjMxNmMyLjcyNCAwIDQuMDQ2IDIuNTYgMy4zMTYgNS4wODFsLS4zMDcgMS4wNjFhLjc1Ljc1IDAgMCAxLS43MTYuNTQxSC45NjRhLjcxLjcxIDAgMCAxLS43MTgtLjY0NiAxMSAxMSAwIDAgMS0uMDM0LS44NTRjMC01LjQ3NiA0LjE2Ni05Ljk3MyA5LjQ4Mi0xMC40NTZhNy4yIDcuMiAwIDAgMS0uMTY3LTEuNTQ0YzAtMy45MzUgMy4xNy03LjEyNSA3LjA4LTcuMTI1IDEuNTU1IDAgMi45OTQuNTA2IDQuMTYyIDEuMzYyQzIyLjg0OSA0LjQ5NyAyOC43MDcgMCAzNS42MDkgMCIvPjxwYXRoIGZpbGw9IiNmZjk5MTAiIGQ9Ik01My4xMiAxMy4xMjVjNi45OTcgMCAxMi42NjggNS43MDggMTIuNjY4IDEyLjc1IDAgMS4yNTUtLjE4IDIuNDY4LS41MTYgMy42MTRhLjcyLjcyIDAgMCAxLS42OTQuNTExSDQ2Ljk1M2EuMzc1LjM3NSAwIDAgMS0uMzQ4LS41MWwuMzM3LS44ODJjMS4wNzYtMi44MzMgNC4xNDYtNS4xNTQgNi45ODctNS4yOWw1LjM4NC0uMjc3YS41NDMuNTQzIDAgMCAwIC41MTQtLjU0NC41NDMuNTQzIDAgMCAwLS41MS0uNTQ0bC01LjA1Ni0uMjk5Yy0yLjcxOC0uMTQtNC4wNDYtMi41Ni0zLjMxNS01LjA4MWwuODQyLTIuOTAyYS43Mi43MiAwIDAgMSAuNjQ2LS41MjdxLjM0LS4wMi42ODYtLjAxOSIvPjxwYXRoIGZpbGw9IiNmZjVmMDgiIGQ9Ik0zNS42MDkgMGM3LjI5NSAwIDEzLjQyNCA1LjAyNSAxNS4xNTcgMTEuODI0LjA3My4yODUuMDUuNTg2LS4wNTQuODYybC0xLjM4OCAzLjY3N2MtMS4wNzYgMi44MzMtMy44NDIgNS4yOS02Ljk3IDUuMjlsLTI0LjEwNS4yNzhhLjUzMy41MzMgMCAwIDAtLjUyNS41MzVjMCAuMjkzLjIzNC41MzEuNTI0LjUzNWwyMy43NjUuMzE2YzIuNzI0IDAgNC4wNDYgMi41NiAzLjMxNiA1LjA4MWwtLjMwNyAxLjA2MWEuNzUuNzUgMCAwIDEtLjcxNi41NDFILjk2NGEuNzEuNzEgMCAwIDEtLjcxOC0uNjQ2IDExIDExIDAgMCAxLS4wMzQtLjg1NGMwLTUuNDc2IDQuMTY2LTkuOTczIDkuNDgyLTEwLjQ1NmE3LjIgNy4yIDAgMCAxLS4xNjctMS41NDRjMC0zLjkzNSAzLjE3LTcuMTI1IDcuMDgtNy4xMjUgMS41NTUgMCAyLjk5NC41MDYgNC4xNjIgMS4zNjJDMjIuODQ5IDQuNDk3IDI4LjcwNyAwIDM1LjYwOSAwIi8+PC9nPjxkZWZzPjxjbGlwUGF0aCBpZD0iY2xpcDBfNzQ2XzIiPjxwYXRoIGZpbGw9IiNmZmYiIGQ9Ik0wIDBoNjZ2MzBIMHoiLz48L2NsaXBQYXRoPjwvZGVmcz48L3N2Zz4=)Docs](https://developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/durable-objects/reference/durable-object-class-migrations-legacy/#page","headline":"Durable Object class migrations (legacy)","description":"Use the legacy Wrangler migrations array to create, rename, delete, or transfer Durable Object classes.","url":"https://developers.cloudflare.com/durable-objects/reference/durable-object-class-migrations-legacy/","inLanguage":"en","image":"https://developers.cloudflare.com/durable-objects/reference/durable-object-class-migrations-legacy/og.png?v=f4b76bf073281c62","dateModified":"2026-09-28","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Use the declarative exports field in wrangler.json to manage Durable Object class lifecycle — create, delete, rename, and transfer Durable Object classes. title: Durable Object class exports image: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/og.png?v=0b5647d0df272fdf

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/durable-objects/llms.txt
Use this file to discover all available pages before exploring further.