Skip to content

Commit 577a206

Browse files
harshil1712Oxyjunhyperlint-ai[bot]
authored and
jonesphillip
committed
[DO] Update DO migration docs (#19385)
* Update DO migration docs * Update src/content/docs/durable-objects/reference/durable-objects-migrations.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Update src/content/docs/durable-objects/reference/durable-objects-migrations.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Docs enhancement part 1 * add note for create class * Editing the structure for better clarity. * Improving explanation and code examples. * Improving structure. --------- Co-authored-by: Jun Lee <[email protected]> Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>
1 parent 2c13767 commit 577a206

File tree

1 file changed

+213
-50
lines changed

1 file changed

+213
-50
lines changed

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

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

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

11-
A migration is a mapping process from a class name to a runtime state.
10+
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

13-
You must initiate a migration process when you:
12+
To apply a migration, you need to:
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+
1. Edit your `wrangler.toml / wrangler.json` file, as explained below.
15+
2. Re-deploy your Worker using `npx wrangler deploy`.
1916

20-
This process informs the Workers runtime of the changes and provides it with instructions on how to deal with those changes.
17+
You must initiate a migration process when you:
18+
19+
- Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
20+
- Rename a Durable Object class.
21+
- Delete a Durable Object class.
22+
- Transfer an existing Durable Objects class.
2123

2224
:::note
2325

26+
Updating the code for an existing Durable Object class does not require a migration. To update the code for an existing Durable Object class, run [`npx wrangler deploy`](/workers/wrangler/commands/#deploy). This is true even for changes to how the 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 the new code is backwards compatible with existing stored data.
2427

25-
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.
28+
:::
2629

30+
## Create migration
2731

28-
:::
32+
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.
2933

30-
The most common migration performed is a new class migration, which informs the runtime that a new Durable Object class is being uploaded.
34+
To apply a Create migration:
3135

32-
Migrations can also be used for transferring stored data between two Durable Object classes:
36+
<Steps>
37+
1. Add the following lines to your `wrangler.toml / wrangler.json` file:
3338

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

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.
49+
- A `tag` to identify the migration.
50+
- The array `new_classes`, which contains the new Durable Object class.
3851

39-
:::caution[Important]
52+
2. Ensure you reference the correct name of the Durable Object class in your Worker code.
53+
3. Deploy the Worker.
54+
</Steps>
4055

56+
<Details header="Create migration example">
4157

42-
After a rename or transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.
58+
To create a new Durable Object binding `DURABLE_OBJECT_A`, your `wrangler.toml / wrangler.json` file should look like the following:
4359

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 file for their next deployment.
60+
<WranglerConfig>
61+
```toml
62+
# Creating a new Durable Object class
63+
[[durable_objects.bindings]]
64+
name = "DURABLE_OBJECT_A"
65+
class_name = "DurableObjectAClass"
4566

67+
# Add the lines below for a Create migration.
68+
[[migrations]]
69+
tag = "v1"
70+
new_classes = ["DurableObjectAClass"]
71+
```
72+
</WranglerConfig>
4673

47-
:::
74+
</Details>
4875

49-
Migrations can also be used to delete a Durable Object class and its stored Durable Objects.
76+
## Delete migration
5077

51-
:::caution[Delete migrations]
78+
Running a Delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.
5279

80+
- 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, that is, first remove the binding from the Worker.
81+
- Copy any important data to some other location before deleting.
82+
- You do not have to run a Delete migration on a class that was renamed or transferred.
5383

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.
84+
To apply a Delete migration:
5585

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

57-
:::
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:
99+
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>
104+
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:
107+
108+
<WranglerConfig>
109+
```toml
110+
# Remove the binding for the DeprecatedObjectClass DO
111+
#[[durable_objects.bindings]]
112+
#name = "DEPRECATED_OBJECT"
113+
#class_name = "DeprecatedObjectClass"
58114

59-
### Durable Object migrations in the Wrangler configuration file
115+
[[migrations]]
116+
tag = "v3" # Should be unique for each entry
117+
deleted_classes = ["DeprecatedObjectClass"] # Array of new classes
118+
```
119+
</WranglerConfig>
120+
</Details>
60121

61-
Migrations are performed through the `[[migrations]]` configurations key in your Wrangler file.
122+
## Rename migration
62123

63-
Migrations require a migration tag, which is defined by the `tag` property in each migration entry.
124+
Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.
64125

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.
126+
To apply a Rename migration:
66127

67-
The migration list is an ordered array of tables, specified as a top-level key in your Wrangler file. The migration list is inherited by all environments and cannot be overridden by a specific environment.
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:
68130

69-
All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).
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
70136

71-
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
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>
72142

73-
<WranglerConfig>
143+
The Rename migration contains:
144+
- A `tag` to identify the migration.
145+
- The `renamed_classes` array, which contains objects with `from` and `to` properties.
146+
- `from` property is the old Durable Object class name.
147+
- `to` property is the renamed Durable Object class name.
148+
2. Reference the new Durable Object class name in your Worker code.
149+
3. Deploy the Worker.
150+
</Steps>
74151

152+
<Details header = "Rename migration example">
153+
154+
To rename a Durable Object class, from `OldName` to `UpdatedName`, your `wrangler.toml / wrangler.json` file should look like the following:
155+
156+
<WranglerConfig>
75157
```toml
158+
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.
159+
# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.
160+
[[durable_objects.bindings]]
161+
name = "MY_DURABLE_OBJECT"
162+
class_name = "UpdatedName"
163+
164+
# Renaming classes
76165
[[migrations]]
77-
tag = "v1" # Should be unique for each entry
78-
new_classes = ["DurableObjectExample"] # Array of new classes
166+
tag = "v3"
167+
renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
79168
```
80-
81169
</WranglerConfig>
82170

83-
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.
171+
</Details>
84172

173+
## Transfer migration
85174

175+
Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
86176

87-
<WranglerConfig>
177+
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.
178+
179+
:::note
180+
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.
181+
:::
182+
183+
To apply a Transfer migration:
184+
185+
<Steps>
186+
1. Edit your `wrangler.toml / wrangler.json` file in the following way:
187+
188+
<WranglerConfig>
189+
```toml
190+
[[durable_objects.bindings]]
191+
name = "<MY_DURABLE_OBJECT>"
192+
class_name = "<DestinationDurableObjectClass>"
88193

194+
[[migrations]]
195+
tag = "<v4>" # Migration identifier. This should be unique for each migration entry
196+
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
197+
```
198+
</WranglerConfig>
199+
The Transfer migration contains:
200+
- A `tag` to identify the migration.
201+
- The `transferred_class` array, which contains objects with `from`, `from_script`, and `to` properties.
202+
- `from` property is the name of the source Durable Object class.
203+
- `from_script` property is the name of the source Worker script.
204+
- `to` property is the name of the destination Durable Object class.
205+
2. Ensure you reference the name of the new, destination Durable Object class in your Worker code.
206+
3. Deploy the Worker.
207+
</Steps>
208+
209+
<Details header = "Transfer migration example">
210+
211+
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:
212+
213+
<WranglerConfig>
89214
```toml
90-
[[migrations]]
91-
tag = "v1" # Should be unique for each entry
92-
new_classes = ["DurableObjectExample"] # Array of new classes
215+
# destination worker
216+
[[durable_objects.bindings]]
217+
name = "MY_DURABLE_OBJECT"
218+
class_name = "TransferredClass"
93219

220+
# Transferring class
94221
[[migrations]]
95-
tag = "v2"
96-
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
97-
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
222+
tag = "v4"
223+
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
98224
```
99-
100225
</WranglerConfig>
101226

102-
:::note
227+
</Details>
228+
## Migration Wrangler configuration
103229

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

105-
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.
232+
- Migrations require a migration tag, which is defined by the `tag` property in each migration entry.
106233

234+
- 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.
107235

236+
- 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.
237+
238+
- All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).
239+
240+
- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.
241+
242+
:::caution[Important]
243+
- 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.
244+
245+
- 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.
246+
247+
- After a Rename or Transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.
248+
249+
- 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.
108250
:::
109251

110-
### Enable SQLite storage backend on new Durable Object class migration
252+
:::note
253+
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.
254+
:::
255+
256+
{/* ## Examples of Durable Object migration
257+
258+
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
259+
260+
<WranglerConfig>
261+
262+
```toml
263+
# Creating a new Durable Object class
264+
[[migrations]]
265+
tag = "v1" # Migration identifier. This should be unique for each migration entry
266+
new_classes = ["DurableObjectExample"] # Array of new classes
267+
```
268+
269+
</WranglerConfig>
270+
271+
You can rename the `DurableObjectExample` class to `UpdatedName` and delete an outdated `DeprecatedClass` entirely. You can create separate migrations for each operation, or combine them into a single migration as shown below. */}
272+
273+
## Enable SQLite storage backend on new Durable Object class migration
111274

112275
:::note[SQLite in Durable Objects Beta]
113276

114277
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.
115278

116279
:::
117280

118-
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 file:
119-
120-
281+
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:
121282

122283
<WranglerConfig>
123284

@@ -129,4 +290,6 @@ new_sqlite_classes = ["MyDurableObject"] # Array of new classes
129290

130291
</WranglerConfig>
131292

293+
For an example of a new class migration, refer to [Get started: Configure Durable Object class with SQLite storage backend](/durable-objects/get-started/tutorial-with-sql-api/#6-configure-durable-object-class-with-sqlite-storage-backend).
294+
132295
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.

0 commit comments

Comments
 (0)