Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO] Update DO migration docs #19385

Open
wants to merge 9 commits into
base: production
Choose a base branch
from
Open

[DO] Update DO migration docs #19385

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
7d999df
Update DO migration docs
harshil1712 Jan 23, 2025
c989609
Update src/content/docs/durable-objects/reference/durable-objects-mig…
Oxyjun Jan 23, 2025
88bfdac
Update src/content/docs/durable-objects/reference/durable-objects-mig…
Oxyjun Jan 23, 2025
29b43d9
Resolving merge conflict.
Oxyjun Jan 23, 2025
258e52e
Docs enhancement part 1
Oxyjun Jan 23, 2025
a9c8987
add note for create class
harshil1712 Jan 30, 2025
46e363c
Editing the structure for better clarity.
Oxyjun Jan 30, 2025
1cf14cc
Merging HEAD back into the branch.
Oxyjun Jan 31, 2025
fbccebc
Improving explanation and code examples.
Oxyjun Jan 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 216 additions & 50 deletions src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,121 +3,285 @@ pcx_content_type: concept
title: Durable Objects migrations
sidebar:
order: 2

---

import { GlossaryTooltip, WranglerConfig } from "~/components";
import { GlossaryTooltip, WranglerConfig, Steps, Details } from "~/components";

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

You must initiate a migration process when you:
To apply a migration, you need to:

* Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
* Rename a Durable Object class.
* Delete a Durable Object class.
* Transfer an existing Durable Objects class.
1. Edit your `wrangler.toml / wrangler.json` file, as explained below.
2. Re-deploy your Worker using `npx wrangler deploy`.

This process informs the Workers runtime of the changes and provides it with instructions on how to deal with those changes.
You must initiate a migration process when you:

- Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
- Rename a Durable Object class.
- Delete a Durable Object class.
- Transfer an existing Durable Objects class.

:::note

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.

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

## Create migration

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

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

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

* Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.
* Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
<WranglerConfig>
```toml
[[migrations]]
tag = "<v1>" # Migration identifier. This should be unique for each migration entry
new_classes = ["<NewDurableObjectClass>"] # Array of new classes
# For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
```
</WranglerConfig>
The Create migration contains:

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

:::caution[Important]
2. Ensure you reference the correct name of the Durable Object class in your Worker code.
3. Deploy the Worker.
</Steps>

<Details header="Create migration example">

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

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.
<WranglerConfig>
```toml
# Creating a new Durable Object class
[[durable_objects.bindings]]
name = "DURABLE_OBJECT_A"
class_name = "DurableObjectAClass"

# Add the lines below for a Create migration.
[[migrations]]
tag = "v1"
new_classes = ["DurableObjectAClass"]
```
</WranglerConfig>

:::
</Details>

Migrations can also be used to delete a Durable Object class and its stored Durable Objects.
## Delete migration

:::caution[Delete migrations]
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 Worker anymore, that is, first remove the binding from the Worker.
- Copy any important data to some other location before deleting.
- You do not have to run a Delete migration on a class that was renamed or transferred.

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

<Steps>
1. Remove the binding for the class you wish to delete from the `wrangler.toml / wrangler.json` file.
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:

### Durable Object migrations in the Wrangler configuration file
- A `tag` to identify the migration.
- The array `deleted_classes`, which contains the deleted Durable Object classes.
4. Deploy the Worker.
</Steps>

Migrations are performed through the `[[migrations]]` configurations key in your Wrangler file.
<Details header = "Delete migration example">
To delete a Durable Object binding `DEPRECATED_OBJECT`, your `wrangler.toml / wrangler.json` file should look like the following:

Migrations require a migration tag, which is defined by the `tag` property in each migration entry.
<WranglerConfig>
```toml
# Remove the binding for the DeprecatedObjectClass DO
#[[durable_objects.bindings]]
#name = "DEPRECATED_OBJECT"
#class_name = "DeprecatedObjectClass"

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.
[[migrations]]
tag = "v3" # Should be unique for each entry
deleted_classes = ["DeprecatedObjectClass"] # Array of new classes
```
</WranglerConfig>
</Details>

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.
## Rename migration

All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).
Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.

To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
To apply a Rename migration:

<WranglerConfig>
<Steps>
1. Update the previous class name to the new class name by editing your `wrangler.toml / wrangler.json` file in the following way:

<WranglerConfig>
```toml
[[durable_objects.bindings]]
name = "<MY_DURABLE_OBJECT>"
class_name = "<UpdatedDurableObject>" # Update the class name to the new class name

[[migrations]]
tag = "<v3>" # Migration identifier. This should be unique for each migration entry
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
```
</WranglerConfig>
The Rename migration contains:
- A `tag` to identify the migration.
- The `renamed_classes` array, which contains objects with `from` and `to` properties.
- `from` property is the name of the old Durable Object class.
- `to` property is the name of the renamed Durable Object class.
2. Reference the new Durable Object class name in your Worker code.
3. Deploy the Worker.
</Steps>

:::note
To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
:::

<Details header = "Rename migration example">

To rename a Durable Object class, from `OldName` to `UpdatedName`, your `wrangler.toml / wrangler.json` file should look like the following:

<WranglerConfig>
```toml
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.
# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "UpdatedName"

# Renaming classes
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DurableObjectExample"] # Array of new classes
tag = "v3"
renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
```

</WranglerConfig>

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.
</Details>

## Transfer migration

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

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

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

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>"

[[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>

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

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

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

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

<Details header = "Transfer migration example">

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:

<WranglerConfig>
```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DurableObjectExample"] # Array of new classes
# destination worker
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

# Transferring class
[[migrations]]
tag = "v2"
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
tag = "v4"
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
```

</WranglerConfig>

:::note
</Details>
## Durable Object migrations configuration in the Wrangler configuration file

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

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

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

- All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).

- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.

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

### Enable SQLite storage backend on new Durable Object class migration
{/* ## Examples of Durable Object migration

To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:

<WranglerConfig>

```toml
# Creating a new Durable Object class
[[migrations]]
tag = "v1" # Migration identifier. This should be unique for each migration entry
new_classes = ["DurableObjectExample"] # Array of new classes
```

</WranglerConfig>

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. */}

## Enable SQLite storage backend on new Durable Object class migration

:::note[SQLite in Durable Objects Beta]

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.

:::

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:


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:

<WranglerConfig>

Expand All @@ -129,4 +293,6 @@ new_sqlite_classes = ["MyDurableObject"] # Array of new classes

</WranglerConfig>

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

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