Durable Object クラスの exports

Wrangler 設定ファイル の exports フィールドは、Durable Object クラス のライフサイクルを宣言的に管理する方法です。Worker がエクスポートする各 Durable Object クラスと、それがライブか、削除済みか、名前変更済みか、転送済みかを宣言します。Cloudflare は、その宣言を、すでに Worker 向けにプロビジョニング済みの名前空間と照合します。

このページでは、次の操作を説明します。

• Durable Object クラスを 作成 する。
• Durable Object クラスとそのデータを 削除 する。
• Durable Object クラスを 名前変更 する。
• Durable Object クラスを Worker 間で 転送 する。

exports を宣言した Worker をデプロイすると、Cloudflare は次の 3 つの情報源を比較します。

1. コード — Worker が実際にエクスポートしている Durable Object クラスの集合です。
2. exports 設定 — 各クラスについて宣言した内容です。
3. プロビジョニング済みの状態 — この Worker にすでに存在する Durable Object 名前空間です。

コードにだけあるクラスは、exports で宣言するまで無視されます。Cloudflare は名前空間を暗黙にはプロビジョニングしません。そのほかの不一致（コードにクラスがないライブエントリや、対応するエントリがないプロビジョニング済み名前空間など）は、構造化されたエラーとして表面化するか、意図が明確な場合は Cloudflare が代わりに適用する操作になります。

最小の exports ブロックでは、各 Durable Object クラスをライブエントリとして宣言します。

{
	"durable_objects": {
		"bindings": [
			{
				"name": "MY_DURABLE_OBJECT",
				"class_name": "MyDurableObject",
			},
		],
	},
	"exports": {
		"MyDurableObject": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}

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

[exports.MyDurableObject]
type = "durable-object"
storage = "sqlite"

削除、名前変更、転送などの破壊的な操作を宣言するには、エントリの state を tombstone（終了状態を表すエントリ）の一種に変えます。クラス名はそのままです。値は、既存の名前空間をどうするかを Cloudflare へ伝えます。

以降の各節で操作を詳しく説明し、スキーマ全体は exports 設定リファレンス を参照します。

新しい Durable Object クラスを定義するには、クラス名をキーにしたエントリを exports に追加し、storage を "sqlite" に設定します。

最初のデプロイ時に、Cloudflare はそのクラス向けの名前空間をプロビジョニングします。同じエントリでの以降のデプロイでは、名前空間は変わりません。エントリは、クラスがまだライブであることを確認するだけです。

Durable Object クラスを退役させるには、ライブエントリを deleted tombstone に置き換えます。クラスを削除すると、その名前空間と 保存済みデータはすべて完全に削除 されます。ソフトデリートではありません。

deleted tombstone には、デプロイ時に次の 2 つの前提条件が適用されます。

• クラスが Worker のコードに含まれていてはなりません。実行時のバインディングが削除済み名前空間へ解決してしまうため、Cloudflare はまだ出荷されているクラスの名前空間を削除しません。
• アカウント内のほかの Worker が、その名前空間へバインドしていてはなりません。別の Worker がまだクラスへバインドしている場合、デプロイは tombstone_delete_blocked_by_external_bindings で拒否され、参照しているスクリプトの一覧が返ります。先にそれらの Worker からバインディングを外して再デプロイし、そのあとで自分のデプロイを再実行します。

名前空間が削除されると、tombstone は失効します。Cloudflare はこれを 照合結果 で報告し、エントリを removable_entries に載せるので、exports から安全に削除できます。

Durable Object クラスの名前変更は、同じ Worker 内で、あるクラスから別のクラスへ保存済みデータを移します。名前変更には次が必要です。

• 古いクラス名をキーにした renamed tombstone。renamed_to は新しいクラス名を指します。
• 同じ exports マップ内に、新しいクラス名のライブエントリ（データの着地先）があること。

古いクラスがコードに残っていない新規デプロイなら、デプロイは 1 回で足ります。

{
	"exports": {
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName"
		},
		"NewName": {
			"type": "durable-object",
			"storage": "sqlite"
		}
	}
}

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

名前変更が適用されると、名前空間のクラス名は NewName に更新されます。新しいクラス名を参照する実行時バインディングは、同じデータへ解決します。

Durable Object クラスの名前変更では、ランタイム層で完全にはアトミックでない 2 つの更新が起きます。名前空間のクラスポインターと、クラスをエクスポートする Worker コードです。デプロイのロールアウト中、片方の更新がもう片方より数秒先に見えることがあります。このあいだの実行時エラーを避けるには、3 回のデプロイによる名前変更 を使います。

renamed_to の対象は、次を満たす必要があります。

• 有効な JavaScript 識別子であり、元のクラス名と異なること。
• 同じ exports マップ内にライブエントリ（state: "created" または省略）として存在すること。別の tombstone を指す、または欠落している renamed_to は拒否されます。
• この Worker 上で、同じ名前の既存名前空間と衝突しないこと。対象名ですでに名前空間がある場合は、先のデプロイでその名前空間自身の deleted tombstone により削除します。

転送は、既存の Durable Object 名前空間を、同じアカウント内のある Worker（ソース）から別の Worker（ターゲット）へ移します。2 つの Worker が協調する必要があるため、転送は複数回のデプロイになります。

ターゲット Worker は、ソース Worker を指名する expecting-transfer エントリを宣言します。ソース Worker は、ターゲット Worker を指名する transferred tombstone を宣言します。実際の受け渡しは、ソース Worker のデプロイが着地したときに確定します。

推奨する順序は、4 回のデプロイです。

受け渡しが全体にロールアウトしたら、ソース Worker のコードから MyDO を削除し、ソースの exports マップから transferred tombstone を削除できます。アカウント内のほかの Worker が、まだソース上の MyDO へバインドしているあいだは、照合結果がそれらを referencing_scripts に載せます。ソースの tombstone を削除する前に、各 Worker を再デプロイし、バインディングをターゲットへ付け替えてください。

保留中の転送は、ソース Worker が transferred tombstone で確定するか、ターゲット Worker が expecting-transfer エントリを外してキャンセルするまで残ります。キャンセルするには、そのエントリなし（または通常のライブエントリへ置き換えて）ターゲットを再デプロイします。Cloudflare は保留レコードを削除し、ソース Worker は名前空間を保持します。

• 両方の Worker が、同じ Cloudflare アカウント内にある必要があります。
• dispatch-namespace をまたぐ転送はサポートされません。ソースとターゲットの Worker は、同じ dispatch-namespace コンテキスト内（またはどちらも dispatch namespace の外）にある必要があります。
• ターゲット Worker が同時に持てる、クラスごとの保留中フェーズ 1 ヒントは 1 つだけです。保留中の転送を別のソースへ付け替えるには、先に現在の保留中転送をキャンセルします。

ライブエントリ（state: "created" と state: "expecting-transfer"）は、storage の値を宣言する必要があります。

• "sqlite" は SQLite ストレージバックエンドを選びます。新しい名前空間では推奨され、使える唯一の経路です。SQLite バックエンドの名前空間は SQL、Point-in-Time Recovery、およびより高いオブジェクトあたりのストレージ上限に対応します。
• "legacy-kv" はキーバリューストレージバックエンドを選びます。Cloudflare がこの値を受け付けるのは、すでにキーバリューストレージでプロビジョニング済みの名前空間だけです（通常は、SQLite がデフォルトになる前に 従来の migrations 配列 で始めた Workers）。exports 経由で 新しい キーバリューバックエンドの名前空間を作ることはできません。

名前空間が存在したあと、ストレージの種類は変更できません。プロビジョニング済み名前空間の sqlite と legacy-kv を切り替える exports の変更は、storage_type_mismatch エラーで拒否されます。ストレージバックエンドを本当に変えるには、deleted tombstone で名前空間を削除し、新しいバックエンドで再プロビジョニングします（そのあいだデータはすべて失われます）。

デプロイが Durable Object クラスのライフサイクル変更を適用すると、wrangler deploy は Durable Object exports reconciliation ブロックを出力します。照合が警告、情報通知、または削除可能なエントリを出したときも、このブロックが出ます。変更がなく通知もない場合、Wrangler はブロックを出しません。

典型的な出力は次のとおりです。

Durable Object exports reconciliation:
  Created: ChatRoom
  Renamed: OldRoom → ChatRoom
  Transferred (committed): Widget → target-worker
  Transfer pending: Incoming ← source-worker

  Info:
    [tombstone_class_still_in_code] OldRoom: Tombstone of type 'renamed' applied. Class 'OldRoom' is still exported in code; this is the supported pattern for zero-downtime rename rollouts.
    [stale_tombstone] OldGone: Tombstone of type 'deleted' for class 'OldGone' has no effect (no namespace exists with this class name). Safe to remove from `exports`.

  Safe to remove from `exports`: OldGone

ブロックには 4 つの節があります。

• 操作行（Created、Updated、Deleted、Renamed、Transferred、Transfer pending）は、このデプロイで Cloudflare が適用した変更を報告します。
• 警告（黄色）は、調査すべきだがデプロイは止めない状態を示します。警告シナリオの集合は将来用に予約されており、現在の Cloudflare デプロイでは出力されません。
• 情報（薄い表示）は、ブロックしない通知です。もう適用されない失効 tombstone と、ソースクラスがまだコードにある状態で適用された tombstone（ゼロダウンタイムロールアウトのサポート対象パターン）です。
• exports から安全に削除できる項目 は、失効していて、アカウント内のほかの Worker がソースクラスへバインドしていない tombstone エントリを列挙します。次の設定編集で、これらのエントリを exports マップから削除できます。

情報エントリには referencing_scripts 一覧が付くことがあります。影響を受ける名前空間へ、まだバインディングが解決している、アカウント内のほかの Worker です。tombstone を削除する前に、それらの Worker を新しいクラス名へバインディングを付け替えて再デプロイしないと、バインディングが孤立します。

デプロイが失敗した場合、出力はクラスごとに構造化されたエラーを示します。

✘ [orphaned_provisioned_namespace] class 'Bar': A namespace exists for 'Bar' but no `exports` entry declares it.
    Suggestion: add an `exports` entry for 'Bar', or add a `deleted` tombstone to remove the namespace.
    Referencing scripts: worker-foo, worker-bar

1 回のデプロイで出たクラス単位のエラーはまとめて報告されるので、1 往復で直せます。シナリオの一覧は エラーリファレンス を参照してください。

tombstone は、適用しても状態が変わらないときに 失効 します。たとえば、名前空間がすでに削除されたクラス向けの deleted tombstone や、名前変更がすでに着地したあとの renamed tombstone です。

Cloudflare は、tombstone が失効しているデプロイのたびに stale_tombstone 情報通知を出します。exports からエントリを削除するまで続きます。通知は意図的に繰り返され、クリーンアップを忘れないようにします。

名前変更と転送の tombstone では、Cloudflare はアカウント内のほかの Worker のうち、durable_objects.bindings がまだソースのクラス名を参照しているものも列挙します。これらは情報通知の referencing_scripts に出ます。referencing_scripts が空でないあいだに tombstone を削除すると、それらのバインディングが孤立する可能性があります。先に参照側 Worker を再デプロイし、バインディングを新しいクラスへ付け替えてください。

照合結果の先頭付近にある「Safe to remove from exports」行は、referencing_scripts が空の失効 tombstone をすべて指名します。この一覧を、「今削除してよい」公式の手がかりとして使います。

exports は Wrangler 設定ファイルのトップレベルで指定でき、環境 ごとに上書きできます。

{
	// top-level exports apply to the default environment
	"exports": {
		"MyDO": { "type": "durable-object", "storage": "sqlite" }
	},
	"env": {
		"staging": {
			// override for the staging environment
			"exports": {
				"MyDO": { "type": "durable-object", "storage": "sqlite" }
			}
		}
	}
}

[exports.MyDO]
type = "durable-object"
storage = "sqlite"

[env.staging.exports.MyDO]
type = "durable-object"
storage = "sqlite"

exports をトップレベルだけに宣言した場合、名前付き環境は同じ値を継承します。各環境は独自のプロビジョニング済み名前空間を持つため、tombstone は宣言した環境内にだけ適用されます。

プレビューデプロイ と dispatch namespace も同じ規則です。dispatch-namespace をまたぐ転送はサポートされません。transferred / expecting-transfer の組のソースとターゲット Worker は、同じ dispatch-namespace コンテキスト内（またはどちらも dispatch namespace の外）にある必要があります。

exports フィールドは、Durable Object クラス名をキーにしたマップです。各値はオブジェクトで、フィールドは state に依存します。

• type string 必須

  • Durable Object クラスのエントリでは、これを "durable-object" に設定します。

• state string 任意

  • ライフサイクルの状態です。"created"（デフォルト、省略可）、"deleted"、"renamed"、"transferred"、"expecting-transfer" のいずれかです。

• storage string 条件付き

  • state が "created" または "expecting-transfer" のときに必須です。"sqlite"（推奨。新しい名前空間で有効な唯一の値）または "legacy-kv"（既存のキーバリューバックエンド名前空間のみ）のいずれかです。tombstone の状態では使えません。

• renamed_to string 条件付き

  • state が "renamed" のときに必須です。転送先のクラス名です。有効な JavaScript 識別子であり、元のクラス名と異なり、同じ exports マップ内にライブエントリとして存在する必要があります。

• transferred_to string 条件付き

  • state が "transferred" のときに必須です。名前空間を受け取るターゲット Worker の名前です。

• transfer_from string 条件付き

  • state が "expecting-transfer" のときに必須です。名前空間の転送元であるソース Worker の名前です。

次の表は、各 state で使えるフィールドと使えないフィールドです。

照合でデプロイが失敗すると、Cloudflare はクラスごとに 1 件のエラーを返します。構造化された scenario タグ、人が読めるメッセージ、該当する場合は suggestion と referencing_scripts 一覧が付きます。

• exports と migrations は同時に使えません。 両方のフィールドを含む Worker 設定は、検証時に拒否されます。一度 exports でデプロイした Worker は、以降のデプロイでも exports を使い続ける必要があります（どちらも使わない場合は空の設定と照合され、通常は誤りです）。
• wrangler versions upload はライフサイクル変更を適用しません。 従来の migrations 配列と同じく、Durable Object のライフサイクル変更は wrangler deploy 経由でのみ適用できます。Wrangler 設定に exports エントリがある場合、wrangler versions upload は対処可能なエラーですぐ失敗します。デプロイ管理 - Durable Object のマイグレーション を参照してください。
• 段階的デプロイは exports では使えません。 ライフサイクル変更は Cloudflare コントロールプレーンでアトミックであり、段階的にはロールアウトできません。Durable Objects での段階的デプロイ - Durable Object クラスのライフサイクル変更 を参照してください。
• ロールバックはライフサイクル変更をまたげません。 exports によるライフサイクル変更より前にデプロイしたバージョンへは、ロールバックできません。ロールバック - バインディング を参照してください。
• ストレージバックエンドは、プロビジョニング後は変更できません。 名前空間の storage の値をその場で変えることはできません。削除して再プロビジョニングします。

migrations 配列 を使っている既存の Workers は、データの移行なしで exports へ移れます。プロビジョニング済み名前空間はそのまま残り、変わるのは設定の形だけです。

クラスの既存ストレージバックエンドを知るには、最初に作成したマイグレーションまでたどります。new_sqlite_classes で導入したクラスは sqlite、new_classes で導入したクラスは legacy-kv です。

典型的な migrations 履歴と等価な内容を並べると、次のとおりです。

{
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] }
	]
}

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

{
	"exports": {
		"ChatRoom": { "type": "durable-object", "storage": "sqlite" }
	}
}

[exports.ChatRoom]
type = "durable-object"
storage = "sqlite"

以降のライフサイクル変更（削除、名前変更、転送）は、すべて exports 経由で行います。tag フィールドに相当するものはなく、履歴エントリを残す必要もありません。いまの exports マップの状態が、信頼できる情報源です。