Cloudflare Durable Objects

Cloudflare Durable Objects

Status: Production Ready ✅ Last Updated: 2025-11-25 Dependencies: cloudflare-worker-base (recommended) Latest Versions: wrangler@4.81.0+, @cloudflare/workers-types@4.20260408.0+ Official Docs: https://developers.cloudflare.com/durable-objects/

Table of Contents

What are Durable Objects? • Quick Start • When to Load References • Class Structure • State API • WebSocket Hibernation • Alarms • RPC vs HTTP • Stubs & Routing • Migrations • Common Patterns • Critical Rules • Known Issues

What are Durable Objects?

Globally unique, stateful objects with single-point coordination, strong consistency (ACID), WebSocket Hibernation (thousands of connections), SQLite storage (1GB), and alarms API.

Use for: Chat rooms, multiplayer games, rate limiting, session management, leader election, stateful workflows

Quick Start (10 Minutes)

Option 1: Scaffold New DO Project

npm create cloudflare@latest my-durable-app -- \
  --template=cloudflare/durable-objects-template --ts --git --deploy false
cd my-durable-app && bun install && npm run dev

Option 2: Add to Existing Worker

1. Install types:

bun add -d @cloudflare/workers-types

2. Create DO class (src/counter.ts):

import { DurableObject } from 'cloudflare:workers';

export class Counter extends DurableObject {
  async increment(): Promise<number> {
    let value: number = (await this.ctx.storage.get('value')) || 0;
    await this.ctx.storage.put('value', ++value);
    return value;
  }
}

export default Counter;  // CRITICAL

3. Configure (wrangler.jsonc):

{
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
  ]
}

4. Call from Worker (src/index.ts):

import { Counter } from './counter';

interface Env {
  COUNTER: DurableObjectNamespace<Counter>;
}

export { Counter };

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.COUNTER.getByName('global-counter');
    return new Response(`Count: ${await stub.increment()}`);
  },
};

Deploy:

bunx wrangler deploy

Available Commands

Use these interactive commands for guided workflows:

• /do-setup - Initialize new DO project with interactive setup wizard

  • Choose storage backend (SQL, KV, both)
  • Select use case pattern (WebSocket, Sessions, Rate Limiting, etc.)
  • Optional Vitest testing setup
  • Generates complete DO implementation

• /do-migrate - Interactive migration assistant

  • New class creation (new_sqlite_classes, new_classes)
  • Rename existing classes (renamed_classes)
  • Delete classes with safety confirmations (deleted_classes)
  • Transfer classes between scripts (transferred_classes)
  • Auto-increments migration tags (v1, v2, v3...)

• /do-debug - Step-by-step debugging workflow

  • Detects error categories (deployment, runtime, performance, etc.)
  • Runs diagnostic checks on configuration and code
  • Provides specific fixes with code examples
  • Guides local testing and production verification

• /do-patterns - Pattern selection wizard

  • Recommends DO pattern based on use case
  • Supports WebSocket, Rate Limiting, Sessions, Analytics, Leader Election
  • Generates complete pattern implementation
  • Provides best practices and optimization tips

• /do-optimize - Performance optimization assistant

  • Analyzes existing DO code for bottlenecks
  • Provides targeted optimization recommendations
  • Covers constructor, queries, WebSocket, memory, alarms
  • Measures performance improvements

Autonomous Agents

These agents work autonomously without user interaction:

• do-debugger - Automatic error detection and fixing

  • Validates wrangler.jsonc configuration
  • Detects 16+ common DO errors
  • Applies fixes automatically with backups
  • Tests fixes before reporting

• do-setup-assistant - Automatic project scaffolding

  • Analyzes user requirements from natural language
  • Generates complete DO implementation
  • Creates tests, documentation, validation
  • Supports all use case patterns

• do-pattern-implementer - Production pattern implementation

  • Analyzes existing DO code
  • Recommends patterns by priority
  • Implements TTL cleanup, RPC metadata, SQL indexes, etc.
  • Generates pattern-specific tests

When to Load References

Load immediately when user mentions:

• state-api-reference.md → "storage", "sql", "database", "query", "get/put", "KV", "1GB limit"
• websocket-hibernation.md → "websocket", "real-time", "chat", "hibernation", "serializeAttachment"
• alarms-api.md → "alarms", "scheduled tasks", "cron", "periodic", "batch processing"
• rpc-patterns.md → "RPC", "fetch", "HTTP", "methods", "routing"
• rpc-metadata.md → "RpcTarget", "metadata", "DO name", "idFromName access"
• stubs-routing.md → "stubs", "idFromName", "newUniqueId", "location hints", "jurisdiction"
• migrations-guide.md → "migrations", "rename", "delete", "transfer", "schema changes"
• migration-cheatsheet.md → "migration quick reference", "migration types", "common migrations"
• common-patterns.md → "patterns", "examples", "rate limiting", "sessions", "leader election"
• vitest-testing.md → "test", "testing", "vitest", "unit test", "@cloudflare/vitest-pool-workers"
• gradual-deployments.md → "gradual", "deployment", "traffic split", "rollout", "canary"
• typescript-config.md → "TypeScript", "types", "tsconfig", "wrangler.jsonc", "bindings"
• advanced-sql-patterns.md → "CTE", "window functions", "FTS5", "full-text search", "JSON functions", "complex SQL"
• security-best-practices.md → "security", "authentication", "authorization", "SQL injection", "CORS", "encryption", "rate limiting"
• error-codes.md → "error codes", "error catalog", "specific error", "E001", "troubleshooting"
• top-errors.md → errors, "not working", debugging, "binding not found"

Load proactively when:

• Building new feature → Load relevant pattern from common-patterns.md
• Debugging issue → Load error-codes.md for specific errors, then top-errors.md
• Implementing WebSocket → Load websocket-hibernation.md before coding
• Setting up storage → Load state-api-reference.md for SQL/KV APIs
• Complex SQL queries → Load advanced-sql-patterns.md for CTEs, window functions, FTS5
• Security review → Load security-best-practices.md for authentication, authorization, SQL injection prevention
• Creating first DO → Load stubs-routing.md for ID methods
• Writing tests → Load vitest-testing.md for testing patterns
• Planning deployment → Load gradual-deployments.md for rollout strategy
• Migration needed → Load migration-cheatsheet.md for quick reference
• Using DO name inside DO → Load rpc-metadata.md for RpcTarget pattern
• TypeScript configuration → Load typescript-config.md for setup

Durable Object Class Structure

All DOs extend DurableObject and MUST be exported:

import { DurableObject } from 'cloudflare:workers';

export class MyDO extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);  // Required first line
    // Keep minimal - heavy work blocks hibernation
    ctx.blockConcurrencyWhile(async () => {
      // Load from storage before handling requests
    });
  }

  async myMethod(): Promise<string> {  // RPC method (recommended)
    return 'Hello!';
  }
}

export default MyDO;  // CRITICAL: Must export

this.ctx provides: storage (SQL/KV), id (unique ID), waitUntil(), acceptWebSocket()

State API - Persistent Storage

Durable Objects provide two storage options:

SQL API (SQLite backend, recommended):

• Access via ctx.storage.sql
• Up to 1GB storage per instance
• SQL queries with transactions, indexes, cursors
• Atomic operations (deleteAll is all-or-nothing)
• Use new_sqlite_classes in migrations

Key-Value API (available on both backends):

• Access via ctx.storage (get/put/delete/list)
• Simple key-value operations
• Async transactions supported
• 128MB limit on KV backend, 1GB on SQLite

Quick example:

export class Counter extends DurableObject {
  sql: SqlStorage;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;
    this.sql.exec('CREATE TABLE IF NOT EXISTS counts (key TEXT PRIMARY KEY, value INTEGER)');
  }

  async increment(): Promise<number> {
    this.sql.exec('INSERT OR REPLACE INTO counts (key, value) VALUES (?, ?)', 'count', 1);
    return this.sql.exec('SELECT value FROM counts WHERE key = ?', 'count').one<{value: number}>().value;
  }
}

Load references/state-api-reference.md for complete SQL and KV API documentation, cursor operations, transactions, parameterized queries, storage limits, and migration patterns.

WebSocket Hibernation API

Handle thousands of WebSocket connections per DO instance with automatic hibernation when idle (~10s no activity), saving duration costs. Connections stay open at the edge while DO sleeps.

CRITICAL Rules:

• ✅ Use ctx.acceptWebSocket(server) (enables hibernation)
• ✅ Use ws.serializeAttachment(data) to persist metadata across hibernation
• ✅ Restore connections in constructor with ctx.getWebSockets()
• ❌ Don't use ws.accept() (standard API, no hibernation)
• ❌ Don't use setTimeout/setInterval (prevents hibernation)

Handler methods: webSocketMessage(), webSocketClose(), webSocketError()

Quick pattern:

export class ChatRoom extends DurableObject {
  sessions: Map<WebSocket, any>;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sessions = new Map();
    // Restore connections after hibernation
    ctx.getWebSockets().forEach(ws => {
      this.sessions.set(ws, ws.deserializeAttachment());
    });
  }

  async fetch(request: Request): Promise<Response> {
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    this.ctx.acceptWebSocket(server);  // ← Enables hibernation
    server.serializeAttachment({ userId: 'alice' });  // ← Persists across hibernation
    this.sessions.set(server, { userId: 'alice' });

    return new Response(null, { status: 101, webSocket: client });
  }

  async webSocketMessage(ws: WebSocket, message: string): Promise<void> {
    const session = this.sessions.get(ws);
    // Broadcast to all
    this.sessions.forEach((_, w) => w.send(message));
  }
}

Load references/websocket-hibernation.md for complete handler patterns, hibernation lifecycle, serializeAttachment API, connection management, broadcasting patterns, and hibernation troubleshooting.

Alarms API - Scheduled Tasks

Schedule DO to wake up at a future time for batching, cleanup, reminders, or periodic tasks.

Core API:

• await ctx.storage.setAlarm(timestamp) - Schedule alarm
• await ctx.storage.getAlarm() - Get current alarm time (null if not set)
• await ctx.storage.deleteAlarm() - Cancel alarm
• async alarm(info) - Handler called when alarm fires

Key Features:

• ✅ Guaranteed at-least-once execution with automatic retries (up to 6)
• ✅ Survives hibernation and eviction
• ✅ Deleted automatically after successful execution
• ⚠️ Only ONE alarm per DO (setting new one overwrites previous)

Quick pattern:

export class Batcher extends DurableObject {
  async addItem(item: string): Promise<void> {
    await this.ctx.storage.put('items', [...existingItems, item]);

    // Schedule batch processing if not already scheduled
    if (await this.ctx.storage.getAlarm() === null) {
      await this.ctx.storage.setAlarm(Date.now() + 10000);  // 10 seconds
    }
  }

  async alarm(info: { retryCount: number; isRetry: boolean }): Promise<void> {
    const items = await this.ctx.storage.get('items');
    await this.processBatch(items);  // Send to API, write to DB, etc.
    await this.ctx.storage.put('items', []);  // Clear buffer
  }
}

Load references/alarms-api.md for periodic alarms pattern, retry handling, error scenarios, cleanup jobs, and batching strategies.

RPC vs HTTP Fetch

RPC (Recommended): Call DO methods directly like await stub.increment(). Type-safe, simple, auto-serialization. Requires compatibility_date >= 2024-04-03.

HTTP Fetch: Traditional HTTP request/response with async fetch(request) handler. Required for WebSocket upgrades.

Quick comparison:

// RPC Pattern (simpler)
export class Counter extends DurableObject {
  async increment(): Promise<number> {  // ← Direct method
    let value = await this.ctx.storage.get<number>('count') || 0;
    return ++value;
  }
}
const count = await stub.increment();  // ← Direct call

// HTTP Fetch Pattern
export class Counter extends DurableObject {
  async fetch(request: Request): Promise<Response> {  // ← HTTP handler
    const url = new URL(request.url);
    if (url.pathname === '/increment') { /* ... */ }
  }
}
const response = await stub.fetch('/increment', { method: 'POST' });

Use RPC for: New projects, type safety, simple method calls Use HTTP Fetch for: WebSocket upgrades, complex routing, legacy code

Load references/rpc-patterns.md for complete RPC vs Fetch comparison, migration guide, error handling patterns, and method visibility control.