Remove incorrect statement that migrations are not environment specific (#22394)

* Remove incorrect statement that migrations are not environment specific

* Fixing Steps component to fix CI

* Fixing too many backticks on Wrangler snippets

* Adding migration inheritance detail.

* Separating out into separate bullet point.

* Adding more detail, addressing VT feedback.

* Update src/content/docs/durable-objects/reference/durable-objects-migrations.mdx

Co-authored-by: Vy Ton <[email protected]>

---------

Co-authored-by: Jun Lee <[email protected]>
Co-authored-by: Vy Ton <[email protected]>

Author: 3 people

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.
-:::
+:::
+

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.