ระดับ 5c · บทที่ 1/5

Durable Objects — state ต่อ object, WebSocket, alarm และ SQLite ในตัว

⏱ 50 นาทีลองในCloudflare ↗
ข้อมูลบางส่วนอาจเปลี่ยน — ตรวจสอบก่อนใช้

บทนี้มีข้อมูลที่เปลี่ยนบ่อย (ฟีเจอร์ ราคา ชื่อเมนู) ตรวจกับเว็บทางการก่อนนำไปใช้

เป้าหมาย

รู้ว่าเมื่อไรควรใช้ Durable Object (DO) แทน KV/D1 เขียน DO ที่เก็บข้อมูลด้วย SQLite ในตัว รับ WebSocket แบบ hibernation (ไม่เสียค่า duration ตอนเงียบ) และตั้ง alarm ให้ทำงานเองตามเวลา

DO คืออะไร — "object เดียวในโลก ที่มีที่เก็บของตัวเอง"

คุณสมบัติ ความหมายในทางปฏิบัติ
ไม่ซ้ำทั่วโลก ชื่อ room-42 มี instance เดียวทั้งโลก ทุก request ไปหาตัวเดียวกัน
single-threaded ไม่มี race condition ภายใน object — อ่าน-แก้-เขียนได้โดยไม่ต้อง lock
มี storage ส่วนตัว SQLite ต่อ object (สูงสุด 10 GB ต่อ object) อ่านเขียนเร็วเพราะอยู่เครื่องเดียวกับโค้ด
อยู่ใกล้คนเรียกครั้งแรก ถูกสร้างใกล้ผู้ใช้คนแรก แล้วอยู่ที่นั่น (ไม่ย้ายตามคน)
เรียกผ่าน Worker เท่านั้น อินเทอร์เน็ตเข้า DO ตรงๆ ไม่ได้ ต้องผ่าน binding

เลือกที่เก็บให้ถูก

ต้องการ ใช้
อ่านเยอะมาก ข้อมูลเปลี่ยนไม่บ่อย ยอมช้า (eventual) KV
ฐานข้อมูลเชิงสัมพันธ์ของทั้งแอป query ข้ามผู้ใช้ D1
ประสานงานแบบ real-time ต่อ "สิ่งหนึ่ง" — ห้องแชต, เกม, ตะกร้า, ตัวนับ, rate limit ต่อผู้ใช้, เอกสารแก้ร่วมกัน Durable Objects
ไฟล์ใหญ่ R2

หลักออกแบบ: 1 object = 1 หน่วยที่ต้องการความสอดคล้อง (1 ห้อง, 1 ผู้ใช้, 1 order) — อย่าทำ "global DO ตัวเดียว" ที่ทุก request วิ่งเข้า เพราะ object เดียวรับงานได้จำกัด

⚠️ ต้องตรวจสอบ: object เดียวรับได้ราวหลักพัน request/วินาที (soft limit) ถ้าเกินจะได้ error overloaded — ดูหน้า Durable Objects › Platform › Limits

ประกาศ class: exports (แบบใหม่) กับ migrations (แบบเดิม)

ตั้งแต่ปี 2026 เอกสารทางการให้ประกาศ class ใน exports แบบ declarative — Cloudflare เทียบโค้ดกับที่มีอยู่แล้วสร้าง/เปลี่ยนชื่อ/ลบให้เอง

"exports": { "ChatRoom": { "type": "durable-object", "storage": "sqlite" } }
  • โปรเจกต์เก่าจะเห็น "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] }] — ยังใช้ได้ แต่ Worker หนึ่งใช้ได้แบบเดียว และย้ายไป exports แล้วย้อนกลับไม่ได้
  • การเปลี่ยน lifecycle (เพิ่ม/เปลี่ยนชื่อ/ลบ class) ต้องใช้ wrangler deploy เท่านั้น และหน้า DO class exports ระบุว่า Worker ที่มี DO ใน exports ใช้ versions upload/gradual deploy ไม่ได้เลย (หน้า Workers deployment เขียนว่าห้ามเฉพาะตอนเปลี่ยน lifecycle — ดูบท 04) → ระบบจริงมักแยก DO ไว้ Worker ของตัวเอง
  • ลบ class ผ่าน exports = ข้อมูลหายถาวร ไม่มีถังขยะ
  • แพลน Free ใช้ได้เฉพาะ SQLite backend (KV backend เฉพาะ Paid)

เรียก DO: stub + RPC

const stub = env.CHAT_ROOM.getByName("lobby");   // ชื่อเดิม = object เดิมเสมอ
const rows = await stub.history();               // เรียก method ตรงๆ (RPC) ไม่ต้องสร้าง Request
  • method ที่เป็น public ของ class กลายเป็น RPC — ค่าที่ส่ง/คืนต้อง serialize ได้ (structured clone)
  • idFromName() + get() คือวิธีเดิม ผลเหมือนกัน · newUniqueId() ใช้เมื่อไม่ต้องการชื่อ (ต้องเก็บ id ไว้เอง)

Storage: SQL API

this.ctx.storage.sql.exec("INSERT INTO messages (user, text, at) VALUES (?, ?, ?)", user, text, Date.now());
const rows = this.ctx.storage.sql.exec("SELECT * FROM messages ORDER BY id DESC LIMIT ?", 20).toArray();
const n = this.ctx.storage.sql.exec("SELECT COUNT(*) AS n FROM messages").one().n;
  • exec เป็น synchronous — ไม่ต้อง await (เร็วเพราะ SQLite อยู่ในเครื่องเดียวกัน)
  • ใช้ ? bind ค่าเสมอ (สูงสุด 100 ตัวต่อ query) ห้ามต่อ string เป็น SQL
  • เขียนหลายคำสั่งติดกันโดยไม่มี await คั่น = commit ไปพร้อมกัน (atomic) — ถ้ามี await fetch() คั่นกลาง request อื่นแทรกได้

WebSocket แบบ Hibernation — ประหยัดเงินจริง

DO คิดเงิน duration (GB-s) ตลอดเวลาที่อยู่ในหน่วยความจำ ถ้าใช้ ws.accept() แบบเดิม object ต้องตื่นตลอด = จ่ายตลอด

ws.accept() this.ctx.acceptWebSocket(ws)
object หลับได้ตอนไม่มีข้อความ ❌ ✅ (การเชื่อมต่อยังค้างอยู่)
รับข้อความด้วย addEventListener method webSocketMessage()
state ต่อ connection ตัวแปรในหน่วยความจำ (หายตอนหลับ) serializeAttachment() (≤ 16 KB, อยู่รอดตอนหลับ)
  • ตื่นมาใหม่ constructor จะรันอีกรอบ → ห้ามเก็บ state สำคัญไว้ในตัวแปร class อย่างเดียว
  • compat date ≥ 2026-04-07 runtime ตอบ Close frame ให้เอง ไม่ต้องเรียก close() ใน webSocketClose

Alarm — ตั้งเวลาให้ object ตื่นมาทำงานเอง

  • object ละ 1 alarm (setAlarm(epochMs) ทับของเดิม) ถ้าต้องการหลายเหตุการณ์ เก็บตารางเวลาใน SQL แล้วให้ alarm() ตั้งรอบถัดไปเอง
  • รับประกัน at-least-once ถ้า alarm() throw จะ retry แบบ backoff สูงสุด 6 ครั้ง → งานใน alarm ต้อง ทำซ้ำได้ไม่พัง (idempotent)
  • ใช้แทน cron ต่อผู้ใช้ เช่น "ลบข้อความเก่ากว่า 24 ชม." หรือ "หมดเวลาจองที่นั่ง 15 นาที"

ลองเลย 🧪

ต้องมี Node.js 22+ และ npx wrangler login แล้ว · ทั้งหมดอยู่ใน Workers Free ได้

1) สร้างโปรเจกต์

npm create cloudflare@latest -- chat-do
# เลือก: Hello World example → Worker + Durable Objects → TypeScript → git: Yes → Deploy: No
cd chat-do

2) แทน wrangler.jsonc ด้วย

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "chat-do",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "observability": { "enabled": true },
  "durable_objects": {
    "bindings": [{ "name": "CHAT_ROOM", "class_name": "ChatRoom" }]
  },
  "exports": {
    "ChatRoom": { "type": "durable-object", "storage": "sqlite" }
  }
}

3) แทน src/index.ts ด้วย

import { DurableObject } from "cloudflare:workers";

type Msg = { id: number; user: string; text: string; at: number };
const HOUR = 60 * 60 * 1000;

export class ChatRoom extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    // รันทุกครั้งที่ object ตื่น — ใช้ IF NOT EXISTS เสมอ
    this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS messages (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      user TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)`);
  }

  // RPC: ดึงประวัติล่าสุด
  async history(limit = 20): Promise<Msg[]> {
    return this.ctx.storage.sql
      .exec<Msg>("SELECT id, user, text, at FROM messages ORDER BY id DESC LIMIT ?", limit)
      .toArray()
      .reverse();
  }

  // รับ WebSocket แบบ hibernation
  async fetch(request: Request): Promise<Response> {
    const user = (new URL(request.url).searchParams.get("user") ?? "anon").slice(0, 32);
    const [client, server] = Object.values(new WebSocketPair());
    this.ctx.acceptWebSocket(server);
    server.serializeAttachment({ user });
    return new Response(null, { status: 101, webSocket: client });
  }

  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
    if (typeof message !== "string" || message.length === 0 || message.length > 500) return;
    const { user } = ws.deserializeAttachment() as { user: string };
    const at = Date.now();
    this.ctx.storage.sql.exec("INSERT INTO messages (user, text, at) VALUES (?, ?, ?)", user, message, at);
    const payload = JSON.stringify({ user, text: message, at });
    for (const peer of this.ctx.getWebSockets()) peer.send(payload);
    if ((await this.ctx.storage.getAlarm()) === null) {
      await this.ctx.storage.setAlarm(at + HOUR);   // ตั้งรอบล้างข้อมูลถ้ายังไม่มี
    }
  }

  async webSocketClose(ws: WebSocket, code: number) {
    const { user } = ws.deserializeAttachment() as { user: string };
    console.log({ event: "ws_close", user, code });  // runtime ตอบ Close ให้เอง (compat ≥ 2026-04-07)
  }

  // ลบข้อความเก่ากว่า 24 ชม. ทำซ้ำกี่รอบผลก็เหมือนเดิม (idempotent)
  async alarm() {
    this.ctx.storage.sql.exec("DELETE FROM messages WHERE at < ?", Date.now() - 24 * HOUR);
    const left = this.ctx.storage.sql.exec<{ n: number }>("SELECT COUNT(*) AS n FROM messages").one().n;
    if (left > 0) await this.ctx.storage.setAlarm(Date.now() + HOUR);
  }
}

export default {
  async fetch(request, env): Promise<Response> {
    const m = new URL(request.url).pathname.match(/^\/rooms\/([a-z0-9-]{1,32})(\/history)?$/);
    if (!m) return new Response("not found", { status: 404 });
    const room = env.CHAT_ROOM.getByName(m[1]);
    if (m[2]) return Response.json(await room.history());
    if (request.headers.get("Upgrade") !== "websocket") {
      return new Response("expected websocket", { status: 426 });
    }
    return room.fetch(request);
  },
} satisfies ExportedHandler<Env>;

4) รันในเครื่องแล้วคุยกันสองหน้าต่าง

npx wrangler types
npx wrangler dev

เปิด terminal ใหม่ 2 อัน:

npx wscat -c "ws://localhost:8787/rooms/lobby?user=somchai"
npx wscat -c "ws://localhost:8787/rooms/lobby?user=suda"

พิมพ์ สวัสดี ในหน้าต่างแรก แล้วดูประวัติ:

curl -s http://localhost:8787/rooms/lobby/history

ผลที่ควรเห็น:

# ทั้งสองหน้าต่าง wscat
< {"user":"somchai","text":"สวัสดี","at":1760000000000}
# curl
[{"id":1,"user":"somchai","text":"สวัสดี","at":1760000000000}]

ลอง /rooms/other/history → ได้ [] เพราะเป็นคนละ object คนละฐานข้อมูล

5) deploy แล้วดูว่า object หลับจริง

npx wrangler deploy
npx wscat -c "wss://chat-do.[subdomain].workers.dev/rooms/lobby?user=somchai"

ทิ้งการเชื่อมต่อไว้เฉยๆ สักพัก แล้วดูกราฟ Workers & Pages › chat-do › Durable Objects — duration ไม่ควรวิ่งตอนไม่มีข้อความ (hibernate)

ถ้าพัง: Cannot apply ... exports → wrangler เก่า อัปเดตด้วย npm i -D wrangler@latest · env.CHAT_ROOM เป็น any → ลืม npx wrangler types · 426 expected websocket → เรียก URL ห้องด้วย curl ธรรมดา ให้ใช้ /history

เก็บกวาด

npx wrangler delete

ตรวจในแดชบอร์ดว่าไม่มี Worker chat-do และ namespace ของ DO เหลือ

กับดักที่เจอบ่อย

อาการ สาเหตุ / แก้
ข้อมูลใน this.xxx หายเป็นระยะ object ถูก evict/hibernate แล้วตื่นใหม่ — เก็บใน SQL หรือ serializeAttachment
DO ตัวเดียวช้า/overloaded ตอนคนเยอะ ออกแบบให้ทุก request วิ่งเข้า object เดียว — แตกตามห้อง/ผู้ใช้/shard
บิล duration สูงทั้งที่คนใช้น้อย ใช้ ws.accept() หรือมี setInterval ค้าง — เปลี่ยนเป็น acceptWebSocket + alarm
alarm ทำงานซ้ำ ส่งอีเมลสองฉบับ at-least-once — บันทึกสถานะ "ส่งแล้ว" ใน SQL ก่อน/หลังทำ และเช็กก่อนส่ง
alarm หยุดถาวรหลัง API ปลายทางล่มนาน retry แค่ 6 ครั้ง — try/catch แล้ว setAlarm รอบใหม่เอง
wrangler versions upload error เรื่อง Durable Object Worker มี DO ใน exports หรือเปลี่ยน lifecycle ของ class — ใช้ wrangler deploy และแยก DO ไว้ Worker ต่างหาก (บท 04)
deploy ใหม่แล้ว WebSocket หลุดทั้งหมด โค้ดใหม่ = object รีเซ็ต — client ต้องมี reconnect + ดึง history ใหม่

สรุปจำง่าย

DO = 1 ชื่อ 1 object ทั้งโลก, single-thread, มี SQLite ของตัวเอง — แตก object ตามหน่วยงาน อย่ารวมศูนย์ — WebSocket ใช้ acceptWebSocket ให้หลับได้ — alarm at-least-once ต้อง idempotent — เพิ่ม/ลบ class ผ่าน exports ด้วย wrangler deploy และลบแล้วข้อมูลหาย