Skip to content

Commit

Permalink
Editing the structure for better clarity.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Oxyjun
Oxyjun committed Jan 30, 2025
1 parent a9c8987 commit 46e363c
Showing 1 changed file with 110 additions and 118 deletions.
228 changes: 110 additions & 118 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 @@ -11,7 +11,7 @@ A migration is a mapping process from a class name to a runtime state. This proc

To apply a migration, you need to:

1. Edit your `wrangler.json` file, as explained below.
1. Edit your `wrangler.toml / wrangler.json` file, as explained below.
2. Re-deploy your Worker using `npx wrangler deploy`.

You must initiate a migration process when you:
Expand All @@ -31,230 +31,222 @@ 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, edit your `wrangler.json` file in the following way:
To apply a Create migration, add the following lines to your `wrangler.toml / wrangler.json` file:

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

### Create migration example

If you are creating two new Durable Object bindings, 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"

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

</WranglerConfig>

## Delete migration

Running a delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.
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.
- 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.
- You do not have to run a Delete migration on a class that was renamed or transferred.

To apply a delete migration, edit your `wrangler.json` file in the following way:
To apply a Delete migration, 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>

## Rename migration
### Delete migration example

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

To apply a rename migration, edit your `wrangler.json` file in the following way:
- Remove the binding for the `DeprecatedClass`
- Deploy the Worker

<WranglerConfig>

```toml
# Remove the binding for the DeprecatedClass DO
[[durable_objects.bindings]]
name = "<MY_DURABLE_OBJECT>"
class_name = "<UpdatedDurableObject>" # Update the class name to the new class name
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObjectClass"


[[migrations]]
tag = "<v2>" # Migration identifier. This should be unique for each migration entry
renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","MyDurableObjectClass"] # Array of new classes
```

</WranglerConfig>

## Transfer migration

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

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
If you just want to run the Delete migration, add the Delete migration configuration and deploy the Worker.

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.
## 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 transfer migration, edit your `wrangler.json` file in the following way:
To apply a Rename migration, edit your `wrangler.toml / wrangler.json` file in the following way:

<WranglerConfig>

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

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

</WranglerConfig>

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

- 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.
To run Rename migration:

- After a rename or transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.
- Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`
- Add the Rename migration configuration
- Deploy the Worker

- 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.
To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.

:::
<WranglerConfig>

## Durable Object migrations configuration in `wrangler`
```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"

- Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file or `migration` key in your `wrangler.json` file.
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes

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

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

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

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

- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.
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

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.

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

## Examples of Durable Object migration
### Transfer migration example

To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
To apply a Transfer migration, edit your `wrangler.toml / wrangler.json` file in the following way:

<WranglerConfig>

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

[[migrations]]
tag = "v1" # Migration identifier. This should be unique for each migration entry
new_classes = ["DurableObjectExample"] # Array of new classes
tag = "<v1>" # Migration identifier. This should be unique for each migration entry
transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
```

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

### Create migration example

To create new classes, add the following to your `wrangler` configuration file and deploy the Worker:

<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 = "DurableObjectExample"
:::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.

[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
```
- After a Rename or Transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.

</WranglerConfig>

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

To run the Delete migration, first remove the binding for the `DeprecatedClass` and deploy the Worker.
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:

<WranglerConfig>

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

class_name = "TransferredClass"

# Transferring class
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
tag = "v1"
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
```

</WranglerConfig>

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

### Rename migration example
## Durable Object migrations configuration in the Wrangler configuration file

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.
- Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file or `migration` key in your `wrangler.json` file.

To apply both migrations in the same deploy, add the migrations configuration and deploy the Worker.
- Migrations require a migration tag, which is defined by the `tag` property in each migration entry.

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

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

[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["DeprecatedClass","DurableObjectExample"] # Array of new classes
- All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).

# 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
```
- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.

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

### Transfer migration example
{/* ## Examples of Durable Object migration
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:
To illustrate an example migrations workflow, the `DurableObjectExample` class can be initially defined with:
<WranglerConfig>
```toml
# destination worker
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

# Transferring class
# Creating a new Durable Object class
[[migrations]]
tag = "v1"
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]
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]
Expand Down

0 comments on commit 46e363c

Please sign in to comment.