เป้าหมาย
รู้ว่าเมื่อไรควรใช้ 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-do2) แทน 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และลบแล้วข้อมูลหาย