Durable Object class のマイグレーション（レガシー）

マイグレーションは、クラス名からランタイム状態への対応付けです。この処理は Workers ランタイムへ変更を伝え、ランタイムがそれらの変更をどう扱うかの指示を渡します。

マイグレーションを適用するには、次を行います。

1. Wrangler 設定ファイルを編集します（マイグレーションの Wrangler 設定 を参照）。
2. npx wrangler deploy で Worker を再デプロイします。

次の場合は、マイグレーションを開始する必要があります。

• 新しい Durable Object class を作成する。
• Durable Object class の名前を変更する。
• Durable Object class を削除する。
• 既存の Durable Objects class を転送する。

もっともよく行うマイグレーションは、新しいクラスの作成マイグレーションです。ランタイムに、新しい Durable Object class がアップロードされることを伝えます。最初の Durable Object class を作るときにも、このマイグレーションが必要です。

作成マイグレーションを適用するには、次の手順を行います。

{
	// 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_sqlite_classes": [
				"DurableObjectAClass"
			]
		}
	]
}

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

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "DurableObjectAClass" ]

Worker の Wrangler ファイルのマイグレーションで new_classes を使い、キーバリューストレージバックエンドの Durable Object class を作成します。

{
	"migrations": [
		{
			"tag": "v1", // Should be unique for each entry
			"new_classes": [
				// Array of new classes
				"MyDurableObject",
			],
		},
	],
}

[[migrations]]
tag = "v1"
new_classes = [ "MyDurableObject" ]

削除マイグレーションを実行すると、削除したクラスに関連するすべての Durable Objects と、その保存データが削除されます。

• 削除マイグレーションをクラスに対して実行する前に、その Worker 内の Durable Objects にもう依存していないことを確認してください。つまり、先に Worker からバインディングを外します。
• 重要なデータは、削除する前に別の場所へコピーします。
• 名前変更または転送したクラスに対して、削除マイグレーションを実行する必要はありません。

削除マイグレーションを適用するには、次の手順を行います。

{
	// Remove the binding for the DeprecatedObjectClass DO
	// {"durable_objects": {"bindings": [
	//   {
	//     "name": "DEPRECATED_OBJECT",
	//     "class_name": "DeprecatedObjectClass"
	//   }
	// ]}}
	"migrations": [
		{
			"tag": "v3", // Should be unique for each entry
			"deleted_classes": [ // Array of deleted classes
				"DeprecatedObjectClass"
			]
		}
	]
}

[[migrations]]
tag = "v3"
deleted_classes = [ "DeprecatedObjectClass" ]

名前変更マイグレーションは、同じ Worker コードファイル内の 2 つの Durable Object class 間で、保存済み Durable Objects を移すために使います。

名前変更マイグレーションを適用するには、次の手順を行います。

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				// Update the binding to the new class name.
				"class_name": "UpdatedName"
			}
		]
	},
	// Renaming classes
	"migrations": [
		{
			"tag": "v3",
			"renamed_classes": [ // Array of rename directives
				{
					"from": "OldName",
					"to": "UpdatedName"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "UpdatedName"

[[migrations]]
tag = "v3"

  [[migrations.renamed_classes]]
  from = "OldName"
  to = "UpdatedName"

転送マイグレーションは、異なる Worker コードファイル内の 2 つの Durable Object class 間で、保存済み Durable Objects を移すために使います。

同じ Worker コードファイル内の 2 つの Durable Object class 間で保存済み Durable Objects を移したい場合は、代わりに 名前変更マイグレーション を使います。

転送マイグレーションを適用するには、次の手順を行います。

{
	// destination worker
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				"class_name": "TransferredClass"
			}
		]
	},
	// Transferring class
	"migrations": [
		{
			"tag": "v4",
			"transferred_classes": [
				{
					"from": "DurableObjectExample",
					"from_script": "OldWorkerScript",
					"to": "TransferredClass"
				}
			]
		}
	]
}

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

[[migrations]]
tag = "v4"

  [[migrations.transferred_classes]]
  from = "DurableObjectExample"
  from_script = "OldWorkerScript"
  to = "TransferredClass"

• マイグレーションは、wrangler.toml ファイルの [[migrations]] 設定キー、または wrangler.jsonc ファイルの migrations キーで行います。

• マイグレーションにはマイグレーションタグが必要です。各マイグレーションエントリの tag プロパティで定義します。

• マイグレーションタグは一意の名前として扱われ、どのマイグレーションがすでに適用済みかを判断するために使います。ある Worker コードにマイグレーションタグが設定されると、以降のすべての Worker コードデプロイにマイグレーションタグを含める必要があります。

• マイグレーションリストは、Wrangler 設定ファイルのキーとして指定する、順序付きのテーブル配列です。

• 各環境と、トップレベルでマイグレーションを定義できます。

  • トップレベルのマイグレーションは、Wrangler 設定ファイルのトップレベル migrations キーで指定します。
  • 環境レベルのマイグレーションは、Wrangler 設定ファイルの env キー内の migrations キー（[env.<environment_name>.migrations]）で指定します。
    • Wrangler ファイルの例:

    {
      // top-level default migrations
      "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] },
      ],
      "env": {
        "staging": {
          // migration override for staging
          "migrations": [
            { "tag": "v1-staging", "new_sqlite_classes": ["MyDurableObject"] },
          ],
        },
      },
    }

  • マイグレーションがトップレベルにだけ指定され、環境レベルにない場合、その環境はトップレベルのマイグレーションを継承します。
  • 環境レベルのマイグレーションは、トップレベルのマイグレーションを上書きします。

• すべてのマイグレーションはデプロイ時に適用されます。各マイグレーションは、環境 ごとに 1 回だけ適用できます。

• リスト内の各マイグレーションは複数のディレクティブを持てます。プロジェクトが複雑になるにつれて、複数のマイグレーションを指定できます。

既存のデプロイ済み Durable Object class で SQLite ストレージバックエンドを有効にすることはできません。そのため、後続のマイグレーションで new_sqlite_classes を設定するとエラーになります。デプロイ済みクラスのキーバリューストレージバックエンドから SQLite ストレージバックエンドへの自動マイグレーションは、今後提供予定です。