Repository: cloudflare/cloudflare-docs
Pull request #22394: Remove incorrect statement that migrations are not environment specific
Author: login: joshthoward
Labels: name: product:durable-objects
description: Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/
name: size/m
Created: 2025-05-13T16:19:30Z | Merged: 2025-05-15T08:44:48Z

### Summary

<!-- Add context such as the type of documentation being updated or added -->

### Screenshots (optional)

<!-- Add imagery to convey the changes made by this PR (optional) -->

### Documentation checklist

<!-- Remove items that do not apply -->

- [ ] The [documentation style guide](https://developers.cloudflare.com/style-guide/) has been adhered to.
- [ ] If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
- [ ] Files which have changed name or location have been allocated [redirects](https://developers.cloudflare.com/pages/configuration/redirects/#per-file).



Diff:
diff --git a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
index be0f56672bdf2c3..57be9a90813b017 100644
--- a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
+++ b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
@@ -5,7 +5,13 @@ sidebar:
   order: 2
 ---
 
-import { Render, GlossaryTooltip, WranglerConfig, Steps, Details } from "~/components";
+import {
+	Render,
+	GlossaryTooltip,
+	WranglerConfig,
+	Steps,
+	Details,
+} from "~/components";
 
 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.
 
@@ -36,18 +42,18 @@ To apply a Create migration:
 <Steps>
 1. Add the following lines to your `wrangler.toml / wrangler.json` file:
 
-	<WranglerConfig>
-	```toml
-	[[migrations]]
-	tag = "<v1>" # Migration identifier. This should be unique for each migration entry
-	new_sqlite_classes = ["<NewDurableObjectClass>"] # Array of new classes
-	# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
-	```
-	</WranglerConfig>
-	The Create migration contains:
+    <WranglerConfig>
+    ```toml
+    [[migrations]]
+    tag = "<v1>" # Migration identifier. This should be unique for each migration entry
+    new_sqlite_classes = ["<NewDurableObjectClass>"] # Array of new classes
+    # For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
+    ```
+    </WranglerConfig>
+    The Create migration contains:
 
-	- A `tag` to identify the migration.
-	- The array `new_sqlite_classes`, which contains the new Durable Object class.
+    - A `tag` to identify the migration.
+    - The array `new_sqlite_classes`, which contains the new Durable Object class.
 
 2. Ensure you reference the correct name of the Durable Object class in your Worker code.
 3. Deploy the Worker.
@@ -65,9 +71,11 @@ name = "DURABLE_OBJECT_A"
 class_name = "DurableObjectAClass"
 
 # Add the lines below for a Create migration.
+
 [[migrations]]
 tag = "v1"
 new_sqlite_classes = ["DurableObjectAClass"]
+
 ```
 </WranglerConfig>
 
@@ -93,7 +101,7 @@ new_classes = ["MyDurableObject"] # Array of new classes
 
 </WranglerConfig>
 
-<Render file="do-plans-note"/>
+<Render file="do-plans-note" />
 
 ## Delete migration
 
@@ -110,17 +118,18 @@ To apply a Delete migration:
 2. Remove references for the class you wish to delete from your Worker code.
 3. Add the following lines to your `wrangler.toml / wrangler.json` file.
 
-	<WranglerConfig>
-	```toml
-	[[migrations]]
-	tag = "<v2>" # Migration identifier. This should be unique for each migration entry
-	deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
-	```
-	</WranglerConfig>
-	The Delete migration contains:
+    <WranglerConfig>
+    ```toml
+    [[migrations]]
+    tag = "<v2>" # Migration identifier. This should be unique for each migration entry
+    deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
+    ```
+    </WranglerConfig>
+    The Delete migration contains:
+
+    - A `tag` to identify the migration.
+    - The array `deleted_classes`, which contains the deleted Durable Object classes.
 
-	- A `tag` to identify the migration.
-	- The array `deleted_classes`, which contains the deleted Durable Object classes.
 4. Deploy the Worker.
 </Steps>
 
@@ -137,6 +146,7 @@ To delete a Durable Object binding `DEPRECATED_OBJECT`, your `wrangler.toml / wr
 [[migrations]]
 tag = "v3" # Should be unique for each entry
 deleted_classes = ["DeprecatedObjectClass"] # Array of deleted classes
+
 ```
 </WranglerConfig>
 </Details>
@@ -188,6 +198,7 @@ class_name = "UpdatedName"
 tag = "v3"
 renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
 ```
+
 </WranglerConfig>
 
 </Details>
@@ -207,23 +218,24 @@ To apply a Transfer migration:
 <Steps>
 1. Edit your `wrangler.toml / wrangler.json` file in the following way:
 
-	<WranglerConfig>
-	```toml
-	[[durable_objects.bindings]]
-	name = "<MY_DURABLE_OBJECT>"
-	class_name = "<DestinationDurableObjectClass>"
+    <WranglerConfig>
+    ```toml
+    [[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>" }]
+    ```
+    </WranglerConfig>
+    The Transfer migration contains:
+    - A `tag` to identify the migration.
+    - The `transferred_class` 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.
 
-	[[migrations]]
-	tag = "<v4>" # Migration identifier. This should be unique for each migration entry
-	transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
-	```
-	</WranglerConfig>
-	The Transfer migration contains:
-	- A `tag` to identify the migration.
-	- The `transferred_class` 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.
 </Steps>
@@ -240,9 +252,11 @@ name = "MY_DURABLE_OBJECT"
 class_name = "TransferredClass"
 
 # Transferring class
+
 [[migrations]]
 tag = "v4"
 transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
+
 ```
 </WranglerConfig>
 
@@ -255,7 +269,26 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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:
+    ```jsonc title="wrangler.jsonc"
+    {
+    // top-level default migrations
+    "migrations": [{ ... }],
+    "env": {
+    "staging": {
+      // migration override for staging
+      "migrations": [{...}]
+      }
+     }
+    }
+    ```
+  - 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 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](/durable-objects/reference/environments/).
 
@@ -279,4 +312,5 @@ You cannot enable a SQLite storage backend on an existing, deployed Durable Obje
 
 :::caution[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 for Durable Objects](/workers/configuration/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects) for more information.
-:::
\ No newline at end of file
+:::
+
diff --git a/src/content/docs/durable-objects/reference/environments.mdx b/src/content/docs/durable-objects/reference/environments.mdx
index a57eedae40d6384..3a1d92974aca6ee 100644
--- a/src/content/docs/durable-objects/reference/environments.mdx
+++ b/src/content/docs/durable-objects/reference/environments.mdx
@@ -61,6 +61,12 @@ durable_objects.bindings = [
 
 </WranglerConfig>
 
+### Migration environments
+
+You can define a Durable Object migration for each environment, as well as at the top level. Migrations at at the environment-level override migrations at the top level.
+
+For more information, refer to [Migration Wrangler Configuration](/durable-objects/reference/durable-objects-migrations/#migration-wrangler-configuration).
+
 ## Local development
 
 Local development sessions create a standalone, local-only environment that mirrors the production environment, so that you can test your Worker and Durable Objects before you deploy to production.


Reviews:
user: login: petebacondarwin
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T19:02:59Z
user: login: petebacondarwin
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T19:04:08Z
user: login: petebacondarwin
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-13T19:06:07Z
user: login: Oxyjun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T10:11:41Z
user: login: Oxyjun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T12:28:04Z
user: login: vy-ton
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T14:54:46Z
user: login: Oxyjun
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T15:09:30Z
user: login: Oxyjun
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T16:41:34Z
user: login: vy-ton
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T19:33:45Z

Review comments:
diff_hunk: @@ -89,11 +97,11 @@ Use `new_classes` on the migration in your Worker's Wrangler file to create a Du
 [[migrations]]
 tag = "v1" # Should be unique for each entry
 new_classes = ["MyDurableObject"] # Array of new classes
-```
+````
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: petebacondarwin
body: Did you mean to add an extra backtick here?
created_at: 2025-05-13T19:02:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,7 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- The migration list is an ordered array of tables, specified as a top-level key in your `wrangler` configuration file.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: petebacondarwin
body: Actually even this sentence is slightly wrong. It doesn't have to be a top-level key, you can define the key for each environment, as well as at the top level
created_at: 2025-05-13T19:06:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,7 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- The migration list is an ordered array of tables, specified as a top-level key in your `wrangler` configuration file.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: Oxyjun
body: Thanks, I've added this to the PR.
created_at: 2025-05-14T10:11:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,11 +97,11 @@ Use `new_classes` on the migration in your Worker's Wrangler file to create a Du
 [[migrations]]
 tag = "v1" # Should be unique for each entry
 new_classes = ["MyDurableObject"] # Array of new classes
-```
+````
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: Oxyjun
body: Removed redundant backticks from all affected lines - thanks for catching!
created_at: 2025-05-14T12:28:04Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,11 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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.
+
+- 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 at the environment-level can override migrations at the top level.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: vy-ton
body: ```suggestion
- Migrations at at the environment-level override migrations at the top level.
```

not can, it will
created_at: 2025-05-14T14:51:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,11 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: vy-ton
body: Should have 1 bullet with all the environments info starting with `You can define the migration for each environment, as well as at the top level.` and the next 2 bullets.

Can you cross link and make sure this info is also present in https://developers.cloudflare.com/durable-objects/reference/environments/?
created_at: 2025-05-14T14:53:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,11 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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.
+
+- If a migration is only specified at the top-level, but not at the environment-level, the environment will inherit the top-level migration.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: vy-ton
body: Help illustrate for user that top-level means `migrations` and environment level is `[env.<environment_name>.migrations]`
created_at: 2025-05-14T14:54:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,11 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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.
+
+- 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 at the environment-level can override migrations at the top level.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: Oxyjun
body: Good catch, I'll push a fix commit.
created_at: 2025-05-14T15:09:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -255,7 +269,26 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS
 
 - 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.
+- 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.
path: src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
user: login: vy-ton
body: ```suggestion
- The migration list is an ordered array of tables, specified as a key in your Wrangler configuration file. 
```
created_at: 2025-05-14T19:30:23Z
author_association: CONTRIBUTOR

PR comments:
user: login: hyperlint-ai-deprecated[bot]
created_at: 2025-05-13T16:19:51Z
body: Howdy and thanks for contributing to our repo. The Cloudflare team reviews new, external PRs within **two (2) weeks**. If it's been two weeks or longer without any movement, please tag the PR **Assignees** in a comment.

We review internal PRs within **1 week**. If it's something urgent or has been sitting without a comment, start a thread in the *Developer Docs* space internally.

---

## PR Change Summary

Clarified that migrations are environment-specific in the Durable Objects documentation.
- Removed incorrect statement regarding migrations not being environment-specific.
- Updated migration examples for clarity and consistency.
- Improved formatting for better readability.


**Modified Files**

- `src/content/docs/durable-objects/reference/durable-objects-migrations.mdx`


 







---

<details>

<summary>How can I customize these reviews?</summary>

Check out the [Hyperlint AI Reviewer docs](https://docs.hyperlint.com/guides/ai-reviewer/) for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the `hyperlint-ignore` label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add `hyperlint-ignore` to the PR to ignore the link check for this PR.
</details>
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-13T16:20:29Z
body: This pull request requires reviews from **CODEOWNERS** as it changes files that match the following patterns:
| Pattern | Owners |
| ------- | ------ |
| `/src/content/docs/durable-objects/` | `@elithrar`, `@vy-ton`, `@joshthoward`, `@oxyjun`, `@harshil1712`, `@cloudflare/pcx-technical-writing` |
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-05-13T17:17:59Z
body: **Preview URL:** https://fecf6203.preview.developers.cloudflare.com
**Preview Branch URL:** https://joshthoward-do-migration-edit.preview.developers.cloudflare.com

**Files with changes (up to 15)**

| Original Link | Updated Link |
| --- | --- |
| [https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/) | [https://joshthoward-do-migration-edit.preview.developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/](https://joshthoward-do-migration-edit.preview.developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/) |
| [https://developers.cloudflare.com/durable-objects/reference/environments/](https://developers.cloudflare.com/durable-objects/reference/environments/) | [https://joshthoward-do-migration-edit.preview.developers.cloudflare.com/durable-objects/reference/environments/](https://joshthoward-do-migration-edit.preview.developers.cloudflare.com/durable-objects/reference/environments/) |
author_association: CONTRIBUTOR