Skip to content

Commit

Permalink
Improving explanation and code examples.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Oxyjun
Oxyjun committed Jan 31, 2025
1 parent 1cf14cc commit fbccebc
Showing 1 changed file with 119 additions and 94 deletions.
213 changes: 119 additions & 94 deletions src/content/docs/durable-objects/reference/durable-objects-migrations.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@ sidebar:
order: 2
---

import { GlossaryTooltip, WranglerConfig } from "~/components";
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. This process communicates the changes to the Workers runtime and provides the runtime with instructions on how to deal with those changes.

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

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.

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

<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>
<Steps>
1. Add the following lines to your `wrangler.toml / wrangler.json` file:

### Create migration example
<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:

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

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

To create a new Durable Object binding `DURABLE_OBJECT_A`, your `wrangler.toml / wrangler.json` file should look like the following:

<WranglerConfig>
```toml
# Creating a new Durable Object class
[[durable_objects.bindings]]
name = "DEPRECATED_DURABLE_OBJECT"
class_name = "DeprecatedClass"

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObjectClass"
name = "DURABLE_OBJECT_A"
class_name = "DurableObjectAClass"

# Add the lines below for a Create migration.
[[migrations]]
tag = "v1"
new_classes = ["DeprecatedClass","MyDurableObjectClass"]
new_classes = ["DurableObjectAClass"]
```

</WranglerConfig>

</Details>

## Delete migration

Running a Delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.
Expand All @@ -75,91 +81,98 @@ Running a Delete migration will delete all Durable Objects associated with the d
- 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.

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

<WranglerConfig>
```toml
[[migrations]]
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
```
</WranglerConfig>
<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.

### Delete migration example
<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:

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

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

<WranglerConfig>

```toml
# Remove the binding for the DeprecatedClass DO
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObjectClass"

# Remove the binding for the DeprecatedObjectClass DO
#[[durable_objects.bindings]]
#name = "DEPRECATED_OBJECT"
#class_name = "DeprecatedObjectClass"

[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","MyDurableObjectClass"] # Array of new classes
tag = "v3" # Should be unique for each entry
deleted_classes = ["DeprecatedObjectClass"] # Array of new classes
```

</WranglerConfig>

If you just want to run the Delete migration, add the Delete migration configuration and deploy the Worker.
</Details>

## Rename migration

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

To apply a Rename migration, edit your `wrangler.toml / wrangler.json` file in the following way:
To apply a Rename migration:

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

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

[[migrations]]
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
```
</WranglerConfig>

### Rename migration example

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

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

To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
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 = ["DeprecatedClass","DurableObjectExample"] # Array of new classes

# Renaming and deleting classes
[[migrations]]
tag = "v2"
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
tag = "v3"
renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
```

</WranglerConfig>

</Details>

## Transfer migration

Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.
Expand All @@ -170,33 +183,45 @@ If you want to transfer stored Durable Objects between two Durable Object classe
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.
:::

### Transfer migration example

To apply a Transfer migration, 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 = "<v1>" # Migration identifier. This should be unique for each migration entry
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
```
</WranglerConfig>
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 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.
- 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.
:::

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:
<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
Expand All @@ -207,12 +232,12 @@ class_name = "TransferredClass"

# Transferring class
[[migrations]]
tag = "v1"
tag = "v4"
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
```
</WranglerConfig>


</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.
Expand Down

0 comments on commit fbccebc

Please sign in to comment.