Skip to content

Commit 7d999df

Browse files
harshil1712harshil1712
committed
Update DO migration docs
1 parent 9386c32 commit 7d999df

File tree

2 files changed

+171
-48
lines changed

2 files changed

+171
-48
lines changed

‎package-lock.json‎

Lines changed: 14 additions & 14 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

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

Lines changed: 157 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ pcx_content_type: concept
33
title: Durable Objects migrations
44
sidebar:
55
order: 2
6-
76
---
87

98
import { GlossaryTooltip } from "~/components";
@@ -12,87 +11,203 @@ A migration is a mapping process from a class name to a runtime state.
1211

1312
You must initiate a migration process when you:
1413

15-
* Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
16-
* Rename a Durable Object class.
17-
* Delete a Durable Object class.
18-
* Transfer an existing Durable Objects class.
14+
- Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
15+
- Rename a Durable Object class.
16+
- Delete a Durable Object class.
17+
- Transfer an existing Durable Objects class.
1918

2019
This process informs the Workers runtime of the changes and provides it with instructions on how to deal with those changes.
2120

2221
:::note
2322

24-
2523
Updating code for an existing Durable Object class does not require a migration. To update code for an existing Durable Object class, run [`npx wrangler deploy`](/workers/wrangler/commands/#deploy). This is true even for changes to how code interacts with persistent storage. Because of [global uniqueness](/durable-objects/platform/known-issues/#global-uniqueness), you do not have to be concerned about old and new code interacting with the same storage simultaneously. However, it is your responsibility to ensure that new code is backwards compatible with existing stored data.
2624

25+
:::
26+
27+
## Create migration
28+
29+
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.
30+
31+
import { WranglerConfig } from "~/components";
32+
33+
<WranglerConfig>
34+
35+
```toml
36+
[[migrations]]
37+
tag = "<v1>" # Should be unique for each entry
38+
new_classes = ["<NewDurableObjectClass>"] # Array of new classes
39+
# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"]
40+
```
41+
42+
</WranglerConfig>
43+
44+
## Delete migration
45+
46+
Running a delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.
47+
48+
- 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, i.e. first remove the binding from the Worker.
49+
- Copy any important data to some other location before deleting.
50+
- No need to run a delete migration on a class that was renamed or transferred.
51+
52+
<WranglerConfig>
53+
54+
```toml
55+
[[migrations]]
56+
tag = "<v2>"
57+
deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
58+
```
59+
60+
</WranglerConfig>
61+
62+
## Rename migration
63+
64+
Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.
65+
66+
<WranglerConfig>
67+
68+
```toml
69+
[[durable_objects.bindings]]
70+
name = "<MY_DURABLE_OBJECT>"
71+
class_name = "<UpdatedDurableObject>" # Update the class name to the new class name
72+
73+
[[migrations]]
74+
tag = "<v2>"
75+
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
76+
```
77+
78+
</WranglerConfig>
79+
80+
## Transfer migration
81+
82+
Migrations can also be used for transferring stored data between two Durable Object classes. Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
83+
84+
If you want to transfer stored Durable Objects between two Durable Object classes in the same Worker code file, use [rename migrations](#rename-migration) instead.
85+
86+
:::note
87+
88+
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.
2789

2890
:::
2991

30-
The most common migration performed is a new class migration, which informs the runtime that a new Durable Object class is being uploaded.
92+
<WranglerConfig>
3193

32-
Migrations can also be used for transferring stored data between two Durable Object classes:
94+
```toml
95+
[[durable_objects.bindings]]
96+
name = "<MY_DURABLE_OBJECT>"
97+
class_name = "<DestinationDurableObjectClass>"
3398

34-
* Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.
35-
* Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
99+
[[migrations]]
100+
tag = "<v1>"
101+
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
102+
```
36103

37-
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.
104+
</WranglerConfig>
38105

39106
:::caution[Important]
40107

108+
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.
41109

42110
After a rename or transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.
43111

44-
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.toml` file for their next deployment.
45-
112+
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.
46113

47114
:::
48115

49-
Migrations can also be used to delete a Durable Object class and its stored Durable Objects.
116+
## Durable Object migrations configuration in `wrangler`
117+
118+
- Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file or `migration` key in your `wrangler.json` file.
119+
120+
- Migrations require a migration tag, which is defined by the `tag` property in each migration entry.
50121

51-
:::caution[Delete migrations]
122+
- 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.
52123

124+
- 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.
53125

54-
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 class anymore. Copy any important data to some other location before deleting.
126+
- All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).
55127

128+
- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.
129+
130+
:::note
131+
132+
Note that `.toml` files do not allow line breaks in inline tables (the `{key = "value"}` syntax), but line breaks in the surrounding inline array are acceptable.
56133

57134
:::
58135

59-
### Durable Object migrations in `wrangler.toml`
136+
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
60137

61-
Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file.
138+
<WranglerConfig>
62139

63-
Migrations require a migration tag, which is defined by the `tag` property in each migration entry.
140+
```toml
141+
# Creating a new Durable Object class
142+
[[migrations]]
143+
tag = "v1" # Should be unique for each entry
144+
new_classes = ["DurableObjectExample"] # Array of new classes
145+
```
64146

65-
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.
147+
</WranglerConfig>
66148

67-
The migration list is an ordered array of tables, specified as a top-level key in your `wrangler.toml` file. The migration list is inherited by all environments and cannot be overridden by a specific environment.
149+
You can rename the `DurableObjectExample` class to `UpdatedName` and delete an outdated `DeprecatedClass` entirely. You can create seprate migrations for each operation, or combine them into a single migration as shown below.
68150

69-
All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).
151+
To create new classes, add the following to your `wrangler` configuration file and deploy the Worker:
70152

71-
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
153+
<WranglerConfig>
72154

73-
import { WranglerConfig } from "~/components";
155+
```toml
156+
# Creating a new Durable Object class
157+
[[durable_objects.bindings]]
158+
name = "DEPRECATED_DURABLE_OBJECT"
159+
class_name = "DeprecatedClass"
160+
161+
[[durable_objects.bindings]]
162+
name = "MY_DURABLE_OBJECT"
163+
class_name = "DurableObjectExample"
164+
165+
166+
[[migrations]]
167+
tag = "v1" # Should be unique for each entry
168+
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
169+
```
170+
171+
</WranglerConfig>
172+
173+
To run the Delete migration, first remove the binding for the `DeprecatedClass` and deploy the Worker.
74174

75175
<WranglerConfig>
76176

77177
```toml
178+
# Remove the binding for the DeprecatedClass DO
179+
[[durable_objects.bindings]]
180+
name = "MY_DURABLE_OBJECT"
181+
class_name = "DurableObjectExample"
182+
183+
78184
[[migrations]]
79185
tag = "v1" # Should be unique for each entry
80-
new_classes = ["DurableObjectExample"] # Array of new classes
186+
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
81187
```
82188

83189
</WranglerConfig>
84190

85-
Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity. For example, you may want to rename the `DurableObjectExample` class to `UpdatedName` and delete an outdated `DeprecatedClass` entirely.
191+
If you just want to run the Delete migration, add the Delete migration configuration and deploy the Worker.
86192

193+
To run Rename migration, update the binding for the `DurableObjectExample` to the new class name `UpdatedName`. Add the Rename migration configuration and deploy the Worker.
87194

195+
To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
88196

89197
<WranglerConfig>
90198

91199
```toml
200+
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.
201+
# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.
202+
[[durable_objects.bindings]]
203+
name = "MY_DURABLE_OBJECT"
204+
class_name = "UpdatedName"
205+
92206
[[migrations]]
93207
tag = "v1" # Should be unique for each entry
94-
new_classes = ["DurableObjectExample"] # Array of new classes
208+
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
95209

210+
# Renaming and deleting classes
96211
[[migrations]]
97212
tag = "v2"
98213
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
@@ -101,25 +216,33 @@ deleted_classes = ["DeprecatedClass"] # Array of deleted class names
101216

102217
</WranglerConfig>
103218

104-
:::note
219+
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:
105220

221+
<WranglerConfig>
106222

107-
Note that `.toml` files do not allow line breaks in inline tables (the `{key = "value"}` syntax), but line breaks in the surrounding inline array are acceptable.
223+
```toml
224+
# destination worker
225+
[[durable_objects.bindings]]
226+
name = "MY_DURABLE_OBJECT"
227+
class_name = "TransferredClass"
108228

229+
# Transferring class
230+
[[migrations]]
231+
tag = "v1"
232+
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
233+
```
109234

110-
:::
235+
</WranglerConfig>
111236

112-
### Enable SQLite storage backend on new Durable Object class migration
237+
## Enable SQLite storage backend on new Durable Object class migration
113238

114239
:::note[SQLite in Durable Objects Beta]
115240

116241
The new beta version of Durable Objects is available where each Durable Object has a private, embedded SQLite database. When deploying a new Durable Object class, users can opt-in to a SQLite storage backend in order to access new [SQL API](/durable-objects/api/sql-storage/#exec). Otherwise, a Durable Object class has a key-value storage backend.
117242

118243
:::
119244

120-
To allow a new Durable Object class to use a SQLite storage backend, use `new_sqlite_classes` on the migration in your Worker's `wrangler.toml` file:
121-
122-
245+
To allow a new Durable Object class to use a SQLite storage backend, use `new_sqlite_classes` on the migration in your Worker's `wrangler` configuration file:
123246

124247
<WranglerConfig>
125248

0 commit comments

Comments
 (0)