Skip to content

Commit fbccebc

Browse files
OxyjunOxyjun
committed
Improving explanation and code examples.
1 parent 1cf14cc commit fbccebc

File tree

1 file changed

+119
-94
lines changed

1 file changed

+119
-94
lines changed

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

Lines changed: 119 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@ sidebar:
55
order: 2
66
---
77

8-
import { GlossaryTooltip, WranglerConfig } from "~/components";
9-
import { GlossaryTooltip, WranglerConfig } from "~/components";
8+
import { GlossaryTooltip, WranglerConfig, Steps, Details } from "~/components";
109

1110
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.
1211

@@ -32,41 +31,48 @@ Updating the code for an existing Durable Object class does not require a migrat
3231

3332
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.
3433

35-
To apply a Create migration, add the following lines to your `wrangler.toml / wrangler.json` file:
34+
To apply a Create migration:
3635

37-
<WranglerConfig>
38-
```toml
39-
[[migrations]]
40-
tag = "<v1>" # Migration identifier. This should be unique for each migration entry
41-
new_classes = ["<NewDurableObjectClass>"] # Array of new classes
42-
# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
43-
```
44-
</WranglerConfig>
36+
<Steps>
37+
1. Add the following lines to your `wrangler.toml / wrangler.json` file:
4538

46-
### Create migration example
39+
<WranglerConfig>
40+
```toml
41+
[[migrations]]
42+
tag = "<v1>" # Migration identifier. This should be unique for each migration entry
43+
new_classes = ["<NewDurableObjectClass>"] # Array of new classes
44+
# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
45+
```
46+
</WranglerConfig>
47+
The Create migration contains:
4748

48-
If you are creating two new Durable Object bindings, your `wrangler.toml / wrangler.json` file should look like the following:
49+
- A `tag` to identify the migration.
50+
- The array `new_classes`, which contains the new Durable Object class.
4951

50-
<WranglerConfig>
52+
2. Ensure you reference the correct name of the Durable Object class in your Worker code.
53+
3. Deploy the Worker.
54+
</Steps>
55+
56+
<Details header="Create migration example">
57+
58+
To create a new Durable Object binding `DURABLE_OBJECT_A`, your `wrangler.toml / wrangler.json` file should look like the following:
5159

60+
<WranglerConfig>
5261
```toml
5362
# Creating a new Durable Object class
5463
[[durable_objects.bindings]]
55-
name = "DEPRECATED_DURABLE_OBJECT"
56-
class_name = "DeprecatedClass"
57-
58-
[[durable_objects.bindings]]
59-
name = "MY_DURABLE_OBJECT"
60-
class_name = "MyDurableObjectClass"
64+
name = "DURABLE_OBJECT_A"
65+
class_name = "DurableObjectAClass"
6166

6267
# Add the lines below for a Create migration.
6368
[[migrations]]
6469
tag = "v1"
65-
new_classes = ["DeprecatedClass","MyDurableObjectClass"]
70+
new_classes = ["DurableObjectAClass"]
6671
```
67-
6872
</WranglerConfig>
6973

74+
</Details>
75+
7076
## Delete migration
7177

7278
Running a Delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.
@@ -75,91 +81,98 @@ Running a Delete migration will delete all Durable Objects associated with the d
7581
- Copy any important data to some other location before deleting.
7682
- You do not have to run a Delete migration on a class that was renamed or transferred.
7783

78-
To apply a Delete migration, add the following lines to your `wrangler.toml / wrangler.json` file:
84+
To apply a Delete migration:
7985

80-
<WranglerConfig>
81-
```toml
82-
[[migrations]]
83-
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
84-
deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
85-
```
86-
</WranglerConfig>
86+
<Steps>
87+
1. Remove the binding for the class you wish to delete from the `wrangler.toml / wrangler.json` file.
88+
2. Remove references for the class you wish to delete from your Worker code.
89+
3. Add the following lines to your `wrangler.toml / wrangler.json` file.
8790

88-
### Delete migration example
91+
<WranglerConfig>
92+
```toml
93+
[[migrations]]
94+
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
95+
deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
96+
```
97+
</WranglerConfig>
98+
The Delete migration contains:
8999

90-
To run the Delete migration:
100+
- A `tag` to identify the migration.
101+
- The array `deleted_classes`, which contains the deleted Durable Object classes.
102+
4. Deploy the Worker.
103+
</Steps>
91104

92-
- Remove the binding for the `DeprecatedClass`
93-
- Deploy the Worker
105+
<Details header = "Delete migration example">
106+
To delete a Durable Object binding `DEPRECATED_OBJECT`, your `wrangler.toml / wrangler.json` file should look like the following:
94107

95108
<WranglerConfig>
96-
97109
```toml
98-
# Remove the binding for the DeprecatedClass DO
99-
[[durable_objects.bindings]]
100-
name = "MY_DURABLE_OBJECT"
101-
class_name = "MyDurableObjectClass"
102-
110+
# Remove the binding for the DeprecatedObjectClass DO
111+
#[[durable_objects.bindings]]
112+
#name = "DEPRECATED_OBJECT"
113+
#class_name = "DeprecatedObjectClass"
103114

104115
[[migrations]]
105-
tag = "v1" # Should be unique for each entry
106-
new_classes = ["DeprecatedClass","MyDurableObjectClass"] # Array of new classes
116+
tag = "v3" # Should be unique for each entry
117+
deleted_classes = ["DeprecatedObjectClass"] # Array of new classes
107118
```
108-
109119
</WranglerConfig>
110-
111-
If you just want to run the Delete migration, add the Delete migration configuration and deploy the Worker.
120+
</Details>
112121

113122
## Rename migration
114123

115124
Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.
116125

117-
To apply a Rename migration, edit your `wrangler.toml / wrangler.json` file in the following way:
126+
To apply a Rename migration:
127+
128+
<Steps>
129+
1. Update the previous class name to the new class name by editing your `wrangler.toml / wrangler.json` file in the following way:
130+
131+
<WranglerConfig>
132+
```toml
133+
[[durable_objects.bindings]]
134+
name = "<MY_DURABLE_OBJECT>"
135+
class_name = "<UpdatedDurableObject>" # Update the class name to the new class name
136+
137+
[[migrations]]
138+
tag = "<v3>" # Migration identifier. This should be unique for each migration entry
139+
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
140+
```
141+
</WranglerConfig>
142+
The Rename migration contains:
143+
- A `tag` to identify the migration.
144+
- The `renamed_classes` array, which contains objects with `from` and `to` properties.
145+
- `from` property is the name of the old Durable Object class.
146+
- `to` property is the name of the renamed Durable Object class.
147+
2. Reference the new Durable Object class name in your Worker code.
148+
3. Deploy the Worker.
149+
</Steps>
118150

119-
<WranglerConfig>
120-
```toml
121-
[[durable_objects.bindings]]
122-
name = "<MY_DURABLE_OBJECT>"
123-
class_name = "<UpdatedDurableObject>" # Update the class name to the new class name
124-
125-
[[migrations]]
126-
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
127-
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
128-
```
129-
</WranglerConfig>
130-
131-
### Rename migration example
132-
133-
To run Rename migration:
151+
:::note
152+
To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
153+
:::
134154

135-
- Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`
136-
- Add the Rename migration configuration
137-
- Deploy the Worker
155+
<Details header = "Rename migration example">
138156

139-
To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
157+
To rename a Durable Object class, from `OldName` to `UpdatedName`, your `wrangler.toml / wrangler.json` file should look like the following:
140158

141159
<WranglerConfig>
142-
143160
```toml
144161
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.
145162
# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.
146163
[[durable_objects.bindings]]
147164
name = "MY_DURABLE_OBJECT"
148165
class_name = "UpdatedName"
149166

167+
# Renaming classes
150168
[[migrations]]
151-
tag = "v1" # Should be unique for each entry
152-
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
153-
154-
# Renaming and deleting classes
155-
[[migrations]]
156-
tag = "v2"
157-
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
158-
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
169+
tag = "v3"
170+
renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
159171
```
160-
161172
</WranglerConfig>
162173

174+
</Details>
175+
163176
## Transfer migration
164177

165178
Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
@@ -170,33 +183,45 @@ If you want to transfer stored Durable Objects between two Durable Object classe
170183
Do not run a [Create migration](#create-migration) for the destination class before running a Transfer migration. The Transfer migration will create the destination class for you.
171184
:::
172185

173-
### Transfer migration example
174-
175-
To apply a Transfer migration, edit your `wrangler.toml / wrangler.json` file in the following way:
176-
177-
<WranglerConfig>
178-
```toml
179-
[[durable_objects.bindings]]
180-
name = "<MY_DURABLE_OBJECT>"
181-
class_name = "<DestinationDurableObjectClass>"
182-
183-
[[migrations]]
184-
tag = "<v1>" # Migration identifier. This should be unique for each migration entry
185-
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
186-
```
187-
</WranglerConfig>
186+
To apply a Transfer migration:
187+
188+
<Steps>
189+
1. Edit your `wrangler.toml / wrangler.json` file in the following way:
190+
191+
<WranglerConfig>
192+
```toml
193+
[[durable_objects.bindings]]
194+
name = "<MY_DURABLE_OBJECT>"
195+
class_name = "<DestinationDurableObjectClass>"
196+
197+
[[migrations]]
198+
tag = "<v4>" # Migration identifier. This should be unique for each migration entry
199+
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
200+
```
201+
</WranglerConfig>
202+
The Transfer migration contains:
203+
- A `tag` to identify the migration.
204+
- The `transferred_class` array, which contains objects with `from`, `from_script`, and `to` properties.
205+
- `from` property is the name of the source Durable Object class.
206+
- `from_script` property is the name of the source Worker script.
207+
- `to` property is the name of the destination Durable Object class.
208+
2. Ensure you reference the name of the new, destination Durable Object class in your Worker code.
209+
3. Deploy the Worker.
210+
</Steps>
188211

189212
:::caution[Important]
190213
- 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.
191214

192-
- You don't have to create the destination Durable Object class before running a Rename or Transfer migration. The migration will create the destination class for you.
215+
- 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.
193216

194217
- After a Rename or Transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.
195218

196219
- 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.
197220
:::
198221

199-
You can transfer stored Durable Objects from `DurableObjectExample` to `TransferredClass` from a Worker script named `OldWorkerScript`. The configuration of the `wrangler` file for your new Worker code (destination Worker code) would look like this:
222+
<Details header = "Transfer migration example">
223+
224+
You can transfer stored Durable Objects from `DurableObjectExample` to `TransferredClass` from a Worker script named `OldWorkerScript`. The configuration of the `wrangler.toml / wrangler.json` file for your new Worker code (destination Worker code) would look like this:
200225

201226
<WranglerConfig>
202227
```toml
@@ -207,12 +232,12 @@ class_name = "TransferredClass"
207232

208233
# Transferring class
209234
[[migrations]]
210-
tag = "v1"
235+
tag = "v4"
211236
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
212237
```
213238
</WranglerConfig>
214239

215-
240+
</Details>
216241
## Durable Object migrations configuration in the Wrangler configuration file
217242

218243
- Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file or `migration` key in your `wrangler.json` file.

0 commit comments

Comments
 (0)