1# Cloudflare Durable Objects
2 
3Expert guidance for building stateful applications with Cloudflare Durable Objects.
4 
5## Reading Order
6 
71. **First time?** Read this overview + Quick Start
82. **Setting up?** See [Configuration](./configuration.md)
93. **Building features?** Use decision trees below → [Patterns](./patterns.md)
104. **Debugging issues?** Check [Gotchas](./gotchas.md)
115. **Deep dive?** [API](./api.md) and [DO Storage](../do-storage/README.md)
12 
13## Overview
14 
15Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:
16- **Globally unique instances**: Each DO has unique ID for multi-client coordination
17- **Co-located storage**: Fast, strongly-consistent storage with compute
18- **Automatic placement**: Objects spawn near first request location
19- **Stateful serverless**: In-memory state + persistent storage
20- **Single-threaded**: Serial request processing (no race conditions)
21 
22## Rules of Durable Objects
23 
24Critical rules preventing most production issues:
25 
261. **One alarm per DO** - Schedule multiple events via queue pattern
272. **~1K req/s per DO max** - Shard for higher throughput
283. **Constructor runs every wake** - Keep initialization light; use lazy loading
294. **Hibernation clears memory** - In-memory state lost; persist critical data
305. **Use `ctx.waitUntil()` for cleanup** - Ensures completion after response sent
316. **No setTimeout for persistence** - Use `setAlarm()` for reliable scheduling
32 
33## Core Concepts
34 
35### Class Structure
36All DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).
37 
38### Lifecycle States
39 
40```
41[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]
42                   ↓
43              [Destroyed]
44```
45 
46- **Not Created**: DO ID exists but instance never spawned
47- **Active**: Processing requests, in-memory state valid, billed per GB-hour
48- **Hibernated**: WebSocket connections open but zero compute, zero cost
49- **Evicted**: Removed from memory; next request triggers cold start
50- **Destroyed**: Data deleted via migration or manual deletion
51 
52### Accessing from Workers
53Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).
54 
55**RPC vs fetch() decision:**
56```
57├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)
58├─ Need HTTP semantics (headers, status) → fetch()
59├─ Proxying requests to DO → fetch()
60└─ Legacy compatibility → fetch()
61```
62 
63See [Patterns: RPC vs fetch()](./patterns.md) for examples.
64 
65### ID Generation
66- `idFromName()`: Deterministic, named coordination (rate limiting, locks)
67- `newUniqueId()`: Random IDs for sharding high-throughput workloads
68- `idFromString()`: Derive from existing IDs
69- Jurisdiction option: Data locality compliance
70 
71### Storage Options
72 
73**Which storage API?**
74```
75├─ Structured data, relations, transactions → SQLite (recommended)
76├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)
77└─ Legacy KV-only DO → ctx.storage (async KV)
78```
79 
80- **SQLite** (recommended): Structured data, transactions, 10GB/DO
81- **Synchronous KV API**: Simple key-value on SQLite objects
82- **Asynchronous KV API**: Legacy/advanced use cases
83 
84See [DO Storage](../do-storage/README.md) for deep dive.
85 
86### Special Features
87- **Alarms**: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)
88- **WebSocket Hibernation**: Zero-cost idle connections (memory cleared on hibernation)
89- **Point-in-Time Recovery**: Restore to any point in 30 days (SQLite only)
90 
91## Quick Start
92 
93```typescript
94import { DurableObject } from "cloudflare:workers";
95 
96export class Counter extends DurableObject<Env> {
97  async increment(): Promise<number> {
98    const result = this.ctx.storage.sql.exec(
99      `INSERT INTO counters (id, value) VALUES (1, 1)
100       ON CONFLICT(id) DO UPDATE SET value = value + 1
101       RETURNING value`
102    ).one();
103    return result.value;
104  }
105}
106 
107// Worker access
108export default {
109  async fetch(request: Request, env: Env): Promise<Response> {
110    const id = env.COUNTER.idFromName("global");
111    const stub = env.COUNTER.get(id);
112    const count = await stub.increment();
113    return new Response(`Count: ${count}`);
114  }
115};
116```
117 
118## Decision Trees
119 
120### What do you need?
121 
122```
123├─ Coordinate requests (rate limit, lock, session)
124│   → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)
125│
126├─ High throughput (>1K req/s)
127│   → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)
128│
129├─ Real-time updates (WebSocket, chat, collab)
130│   → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)
131│
132├─ Background work (cleanup, notifications, scheduled tasks)
133│   → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)
134│
135└─ User sessions with expiration
136    → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)
137```
138 
139### Which access pattern?
140 
141```
142├─ New project + typed methods → RPC (compat ≥2024-04-03)
143├─ Need HTTP semantics → fetch()
144├─ Proxying to DO → fetch()
145└─ Legacy compat → fetch()
146```
147 
148See [Patterns: RPC vs fetch()](./patterns.md) for examples.
149 
150### Which storage?
151 
152```
153├─ Structured data, SQL queries, transactions → SQLite (recommended)
154├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)
155└─ Legacy KV-only DO → ctx.storage (async API)
156```
157 
158See [DO Storage](../do-storage/README.md) for complete guide.
159 
160## Essential Commands
161 
162```bash
163npx wrangler dev              # Local dev with DOs
164npx wrangler dev --remote     # Test against prod DOs
165npx wrangler deploy           # Deploy + auto-apply migrations
166```
167 
168## Resources
169 
170**Docs**: https://developers.cloudflare.com/durable-objects/  
171**API Reference**: https://developers.cloudflare.com/durable-objects/api/  
172**Examples**: https://developers.cloudflare.com/durable-objects/examples/
173 
174## In This Reference
175 
176- **[Configuration](./configuration.md)** - wrangler.jsonc setup, migrations, bindings, environments
177- **[API](./api.md)** - Class structure, ctx methods, alarms, WebSocket hibernation
178- **[Patterns](./patterns.md)** - Sharding, rate limiting, locks, real-time, sessions
179- **[Gotchas](./gotchas.md)** - Limits, hibernation caveats, common errors
180 
181## See Also
182 
183- **[DO Storage](../do-storage/README.md)** - SQLite, KV, transactions (detailed storage guide)
184- **[Workers](../workers/README.md)** - Core Workers runtime features
185- **[WebSockets](../websockets/README.md)** - WebSocket APIs and patterns
186