Cloudflare 21：Durable Objects ― 名前ごとに世界に1つだけのオブジェクト

一言でいうと：名前ごとに世界に1つだけのオブジェクト

DO を一言でいうと、「名前ごとに、世界にちょうど1つだけ存在する、状態を持ったオブジェクト」です。

room:abc という名前の DO を呼ぶと、世界のどこから呼んでも、同じ1つの `room:abc` に届きます。東京の Worker も、サンパウロの Worker も、同じ相手と話します。2つ目の room:abc は、どこにも存在しません。

1つしか無いのだから、「今のいいねの数」は、その1つが持っている値が唯一の正しい値です。ばらばらになりようがありません。

DO は、次の2つがセットになったものです。

プログラミングの「クラスとインスタンス」を思い浮かべると分かりやすいでしょう。ChatRoom というクラスを1つ書くと、room:abc、room:xyz … という名前ごとにインスタンスが作られます。違うのは、そのインスタンスが世界に1つだけで、自分の保存場所を持ち、Cloudflare の網の中で生き続けることです。

Worker の役目は、「どの名前の DO に用があるか」を決めて呼び出すことだけになります。状態を持つのは DO、というように役割が分かれます。

1つだから、1つずつ処理できる

DO が「1つだけ」であることには、もう1つ大きな意味があります。1つのオブジェクトの中では、処理が1つずつ進むのです。

JavaScript は、もともと1つの流れ（シングルスレッド）で動く言語です。DO は1つの場所で1つの流れとして動くので、東京とロンドンから同時に「+1」が届いても、どちらかが先、どちらかが後に処理されます。図の左で「+1」が順番待ちをしているのはこの様子です。

さらに、DO は保存場所（ストレージ）の読み書きをしている間、他のリクエストが割り込まないように自動で入口を閉じます（入力ゲート）。そのため、「読んで、+1 して、書く」を普通に書くだけで、ロックもトランザクションも意識せずに正しく数えられます。

このように、「書いた直後から、誰が読んでも新しい値が見える」性質を、強い整合性と呼びます。20号の KV の結果整合性とは反対の性質です。

1つだけ気をつけたいのは、外部への fetch を await している間です。この間は他のリクエストが先に進めるので、その前後で値が変わっていることがあります。ストレージの読み書きだけで完結する処理は安全、と覚えておきましょう。

名前ごとに別のオブジェクト。だから数を増やせる

「1つだけ」「1つずつ処理」と聞くと、「それでは遅いのでは」と心配になるかもしれません。確かに、1つの DO がこなせる量には限りがあります。

DO の考え方の肝は、1つに全部を集めないことです。名前ごとに別のオブジェクトになるので、チャットなら部屋ごとに1つ、共同編集なら文書ごとに1つ、いいねなら記事ごとに1つ、と分けます。

オブジェクトはいくつ作っても構いません。何百万個でも作れます。1つ1つは小さく、それぞれが「自分の部屋」のことだけを正しく扱います。全体としては、部屋が増えるほどオブジェクトも増えるので、いくらでも大きくできるのです。

DO は、最初に呼ばれた場所の近くに作られ、そこに住み続けます。東京の利用者が作ったチャットの部屋は、東京の近くにできます。作る場所の希望（location hint）を指定することもできます。

逆にいえば、1つの DO は1か所にしかいないので、地球の反対側の利用者から呼ばれると、そのぶん往復の時間がかかります。これは「世界に1つ」の代償です。

中に SQLite：状態と保存場所が同じ場所にある

DO は、それぞれ自分専用の保存場所を持っています。今の標準は SQLite です。オブジェクト1つにつき、1つの小さな SQLite データベースが付いてくる、と考えてください。

図のとおり、DO の中には2種類の置き場があります。

SQLite は、DO と同じ機械の上にあります。普通のデータベースのように、ネットワークの向こうへ問い合わせに行く必要がありません。そのため、読み書きはとても速く、1つのリクエストの中で何十回と SQL を実行しても気になりません。

this.ctx.storage.sql.exec(
  "CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY, user TEXT, body TEXT, ts INTEGER)",
);
this.ctx.storage.sql.exec(
  "INSERT INTO messages (user, body, ts) VALUES (?, ?, ?)", user, body, Date.now(),
);
const recent = this.ctx.storage.sql
  .exec("SELECT user, body FROM messages ORDER BY id DESC LIMIT 50")
  .toArray();

データは、オブジェクトごとに完全に分かれています。room:abc の DO から、room:xyz のデータは見えません。全部の部屋をまとめて検索・集計したいときは、D1（23号）などに別に書き出します。

ほかに、キーと値で読み書きする API（ctx.storage.get / put）もあります。

WebSocket：部屋に全員がつながり、1か所から配る

チャットや共同編集では、誰かが書いた内容を、同じ部屋の全員へすぐに届ける必要があります。そのために使うのが WebSocket（ブラウザとサーバーがつなぎっぱなしで、双方向にやりとりできる通信）です。

普通の Worker では、これが難しいのです。同じ部屋の利用者が、それぞれ別の拠点の別の Worker につながってしまうからです。

DO を使うと、話は単純になります。部屋の全員が、同じ1つの DO に WebSocket でつながるのです。

1か所に集まっているので、発言の順番も全員で同じになります。

ここで気になるのが料金です。チャットの部屋は、つながっているだけで誰も話していない時間が長いものです。その間ずっと DO が起きていると、時間の分だけ料金がかかります。

そこで、ハイバネーション（冬眠）という仕組みがあります。専用の WebSocket の API を使うと、メッセージが来ない間、DO は接続をつないだまま眠り、料金の数えられる時間が止まります。メッセージが届くと自動で起き、処理が終わるとまた眠ります。WebSocket を使うなら、ハイバネーションに対応した API を使うのが基本です。

アラーム：あとで自分を起こす

DO は、リクエストが来たときだけでなく、決めた時刻に自分で起きることもできます。これがアラームです。

export class ChatRoom extends DurableObject {
  async onMessage() {
    // 10分後に起こしてもらう（オブジェクトごとに1つ設定できる）
    await this.ctx.storage.setAlarm(Date.now() + 10 * 60 * 1000);
  }

  async alarm() {
    // 時間が来ると呼ばれる。24時間より古い発言を片付ける
    this.ctx.storage.sql.exec(
      "DELETE FROM messages WHERE ts < ?", Date.now() - 24 * 60 * 60 * 1000,
    );
  }
}

アラームは、次のような「あとで」の処理に向いています。

アラームの時刻は保存場所に記録されるので、DO が一度片付けられても、時間が来ればちゃんと起こされます。alarm() の中でエラーが起きた場合は、自動で再試行されます。

全体に対して「毎日0時に」のような定期実行をしたいときは、Cron Triggers（25号）を使います。アラームは、そのオブジェクト自身の「あとで」を扱うための仕組みです。

導入：クラスを書き、設定でバインディングとマイグレーション

DO は Worker のプロジェクトの中で作ります。必要なのは、クラスのコードと、設定ファイルへの2つの記入です。

{
  "name": "chat",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-01",
  "durable_objects": {
    "bindings": [{ "name": "ROOM", "class_name": "ChatRoom" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["ChatRoom"] }
  ]
}

マイグレーションは、DO ならではの項目です。DO は保存場所を持つので、クラスを追加したり名前を変えたりするときに、Cloudflare に「このクラスのデータをどう扱うか」を伝える必要があります。クラスを足すたびに、tag を変えた新しい行を追記していきます。前の行を書き換えてはいけません。

新しく作るクラスは、new_sqlite_classes に書きます。SQLite 型が現在のおすすめで、Free プランで使えるのも SQLite 型だけです。

クラスは、Worker の入口のファイルから export しておきます。あとは npx wrangler dev で手元で試し、npx wrangler deploy で配るのは、18号の Worker とまったく同じです。

使い方：Worker から名前で呼び、メソッドを呼ぶ

いいねを数える DO の全体を見てみましょう。

import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS c (n INTEGER)");
    ctx.storage.sql.exec("INSERT INTO c SELECT 0 WHERE NOT EXISTS (SELECT 1 FROM c)");
  }

  async increment(): Promise<number> {
    this.ctx.storage.sql.exec("UPDATE c SET n = n + 1");
    return this.ctx.storage.sql.exec<{ n: number }>("SELECT n FROM c").one().n;
  }
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const postId = new URL(request.url).searchParams.get("post") ?? "1";
    const stub = env.COUNTER.getByName(`post:${postId}`); // 世界に1つの post:<ID>
    const n = await stub.increment();                      // メソッドを直接呼ぶ
    return Response.json({ likes: n });
  },
};

流れは3段です。

getByName は、内部では「名前から ID を作る（idFromName）」と「ID からスタブを得る（get）」をまとめたものです。同じ名前からは必ず同じ ID ができるので、世界中のどこからでも同じオブジェクトに届きます。

スタブのメソッド呼び出しは、見た目は普通の関数ですが、実際には DO の住んでいる場所への通信です。1回のリクエストで何度も呼ぶより、必要な処理を DO のメソッド1つにまとめたほうが速くなります。

料金と制限：「回数」と「起きていた時間」と「保存」

DO の料金は、いくつかの要素を足したものです。2026年9月時点の考え方は次のとおりです。料金・上限は変わるので、必ず公式の Pricing と Limits のページで確かめてください。

注意したいのは時間です。DO は、処理をしていなくても、メモリに残っている間は時間が数えられることがあります。たとえば、WebSocket をハイバネーションに対応しない API でつなぎっぱなしにすると、誰も話していない間も起きたままになり、時間の料金が積み上がります。

逆に、眠れる状態の DO は時間を数えません。ハイバネーションに対応した WebSocket の API を使い、不要なタイマーを残さないように作ると、待っている時間の料金はほぼかからなくなります。

制限としては、1つの DO の保存量、1つの DO が1秒間にこなせる処理の量などがあります。1つの DO で捌ききれない量が来るなら、名前の付け方を見直して、もっと細かく分けるのが基本の対策です。

よくある落とし穴

DO でよくつまずく点をまとめます。

特に1つ目は、DO を初めて使う人がいちばんやりがちな失敗です。「世界に1つ」で正しく数えられることに安心して、サイト全体の数を1つの DO に集めてしまうのです。DO は「小さなものを、たくさん」作るための仕組みだと覚えておきましょう。

全体の合計が欲しいときは、各 DO が自分の数をときどき（アラームなどで）D1 や KV に書き出し、合計はそちらで出す、という形にします。

他の号とのつながり

DO は、他の多くの機能と組み合わせて使います。

AI のエージェントを作るための Cloudflare の道具（Agents SDK）も、会話やエージェントごとの状態を DO に持たせる作りになっています。「1つの相手ごとに、状態を持った小さなサーバーを1つ」という DO の考え方は、いろいろな場面の土台になっています。