Skip to content

非公式 / UnofficialCloudflare, Inc. 非提携。アカウント情報は入力しないでください。Not affiliated with Cloudflare, Inc. Do not enter Cloudflare credentials here.Official docsこのサイトについてプライバシー

Durable Object class のマイグレーション(レガシー)

最終更新 Markdown で表示Agent セットアップ

マイグレーションは、クラス名からランタイム状態への対応付けです。この処理は 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 を作るときにも、このマイグレーションが必要です。

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

  1. Wrangler 設定ファイルに次の行を追加します。

    {
      "migrations": [
        {
          "tag": "<v1>", // Migration identifier. This should be unique for each migration entry
          "new_sqlite_classes": [ // Array of new classes
            "<NewDurableObjectClass>"
          ]
        }
      ]
    }
    [[migrations]]
    tag = "<v1>"
    new_sqlite_classes = [ "<NewDurableObjectClass>" ]

    作成マイグレーションには次が含まれます。

    • マイグレーションを識別する tag。
    • 新しい Durable Object class を含む配列 new_sqlite_classes。
  2. Worker コードで、Durable Object class の正しい名前を参照していることを確認します。

  3. Worker をデプロイします。

作成マイグレーションの例

新しい Durable Object バインディング DURABLE_OBJECT_A を作成する場合、Wrangler 設定ファイルは次のようになります。

{
	// 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" ]

キーバリューストレージで Durable Object class を作成する

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 からバインディングを外します。
  • 重要なデータは、削除する前に別の場所へコピーします。
  • 名前変更または転送したクラスに対して、削除マイグレーションを実行する必要はありません。

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

  1. 削除したいクラスのバインディングを、Wrangler 設定ファイルから外します。

  2. 削除したいクラスへの参照を、Worker コードから外します。

  3. Wrangler 設定ファイルに次の行を追加します。

    {
      "migrations": [
        {
          "tag": "<v2>", // Migration identifier. This should be unique for each migration entry
          "deleted_classes": [ // Array of deleted class names
            "<ClassToDelete>"
          ]
        }
      ]
    }
    [[migrations]]
    tag = "<v2>"
    deleted_classes = [ "<ClassToDelete>" ]

    削除マイグレーションには次が含まれます。

    • マイグレーションを識別する tag。
    • 削除した Durable Object class を含む配列 deleted_classes。
  4. Worker をデプロイします。

削除マイグレーションの例

Durable Object バインディング DEPRECATED_OBJECT を削除する場合、Wrangler 設定ファイルは次のようになります。

{
	// 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 を移すために使います。

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

  1. Wrangler 設定ファイルを次のように編集し、以前のクラス名を新しいクラス名に更新します。

    {
      "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": [ // Array of rename directives
            {
              "from": "<OldDurableObject>",
              "to": "<UpdatedDurableObject>"
            }
          ]
        }
      ]
    }
    [[durable_objects.bindings]]
    name = "<MY_DURABLE_OBJECT>"
    class_name = "<UpdatedDurableObject>"
    
    [[migrations]]
    tag = "<v3>"
    
      [[migrations.renamed_classes]]
      from = "<OldDurableObject>"
      to = "<UpdatedDurableObject>"

    名前変更マイグレーションには次が含まれます。

    • マイグレーションを識別する tag。
    • from と to プロパティを持つオブジェクトを含む renamed_classes 配列。
    • from プロパティは、古い Durable Object class 名です。
    • to プロパティは、名前変更後の Durable Object class 名です。
  2. Worker コードで、新しい Durable Object class 名を参照します。

  3. Worker をデプロイします。

名前変更マイグレーションの例

Durable Object class の名前を OldName から UpdatedName に変更する場合、Wrangler 設定ファイルは次のようになります。

{
	"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 を移したい場合は、代わりに 名前変更マイグレーション を使います。

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

  1. Wrangler 設定ファイルを次のように編集します。

    {
      "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>"
            }
          ]
        }
      ]
    }
    [[durable_objects.bindings]]
    name = "<MY_DURABLE_OBJECT>"
    class_name = "<DestinationDurableObjectClass>"
    
    [[migrations]]
    tag = "<v4>"
    
      [[migrations.transferred_classes]]
      from = "<SourceDurableObjectClass>"
      from_script = "<SourceWorkerScript>"
      to = "<DestinationDurableObjectClass>"

    転送マイグレーションには次が含まれます。

    • マイグレーションを識別する tag。
    • from、from_script、to プロパティを持つオブジェクトを含む transferred_classes 配列。
      • from プロパティは、転送元 Durable Object class の名前です。
      • from_script プロパティは、転送元 Worker スクリプトの名前です。
      • to プロパティは、転送先 Durable Object class の名前です。
  2. Worker コードで、新しい転送先 Durable Object class の名前を参照していることを確認します。

  3. Worker をデプロイします。

転送マイグレーションの例

Worker スクリプト OldWorkerScript から、DurableObjectExample の保存済み Durable Objects を TransferredClass へ転送できます。新しい Worker コード(転送先 Worker コード)の Wrangler 設定ファイルは、次のようになります。

{
	// 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 設定

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

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

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

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

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

    • トップレベルのマイグレーションは、Wrangler 設定ファイルのトップレベル migrations キーで指定します。
    • 環境レベルのマイグレーションは、Wrangler 設定ファイルの env キー内の migrations キー([env.<environment_name>.migrations])で指定します。
      • Wrangler ファイルの例:
      wrangler.jsoncjsonc
      {
        // 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 ストレージバックエンドへの自動マイグレーションは、今後提供予定です。

役に立ちましたか?