1# Durable Objects Configuration
2 
3## Basic Setup
4 
5```jsonc
6{
7  "name": "my-worker",
8  "main": "src/index.ts",
9  "compatibility_date": "2025-01-01",  // Use latest; ≥2024-04-03 for RPC
10  "durable_objects": {
11    "bindings": [
12      { 
13        "name": "MY_DO",                // Env binding name
14        "class_name": "MyDO"            // Class exported from this worker
15      },
16      { 
17        "name": "EXTERNAL",             // Access DO from another worker
18        "class_name": "ExternalDO", 
19        "script_name": "other-worker"
20      }
21    ]
22  },
23  "migrations": [
24    { "tag": "v1", "new_sqlite_classes": ["MyDO"] }  // Prefer SQLite
25  ]
26}
27```
28 
29## Binding Options
30 
31```jsonc
32{
33  "name": "BINDING_NAME",
34  "class_name": "ClassName",
35  "script_name": "other-worker",        // Optional: external DO
36  "environment": "production"           // Optional: isolate by env
37}
38```
39 
40## Jurisdiction (Data Locality)
41 
42Specify jurisdiction at ID creation for data residency compliance:
43 
44```typescript
45// EU data residency
46const id = env.MY_DO.idFromName("user:123", { jurisdiction: "eu" })
47 
48// Available jurisdictions
49const jurisdictions = ["eu", "fedramp"]  // More may be added
50 
51// All operations on this DO stay within jurisdiction
52const stub = env.MY_DO.get(id)
53await stub.someMethod()  // Data stays in EU
54```
55 
56**Key points:**
57- Set at ID creation time, immutable afterward
58- DO instance physically located within jurisdiction
59- Storage and compute guaranteed within boundary
60- Use for GDPR, FedRAMP, other compliance requirements
61- No cross-jurisdiction access (requests fail if DO in different jurisdiction)
62 
63## Migrations
64 
65```jsonc
66{
67  "migrations": [
68    { "tag": "v1", "new_sqlite_classes": ["MyDO"] },            // Create SQLite (recommended)
69    // { "tag": "v1", "new_classes": ["MyDO"] },                // Create KV (paid only)
70    { "tag": "v2", "renamed_classes": [{ "from": "Old", "to": "New" }] },
71    { "tag": "v3", "transferred_classes": [{ "from": "Src", "from_script": "old", "to": "Dest" }] },
72    { "tag": "v4", "deleted_classes": ["Obsolete"] }           // Destroys ALL data!
73  ]
74}
75```
76 
77**Migration rules:**
78- Tags must be unique and sequential (v1, v2, v3...)
79- No rollback supported (test with `--dry-run` first)
80- Auto-applied on deploy
81- `new_sqlite_classes` recommended over `new_classes` (SQLite vs KV)
82- `deleted_classes` immediately destroys ALL data (irreversible)
83 
84## Environment Isolation
85 
86Separate DO namespaces per environment (staging/production have distinct object instances):
87 
88```jsonc
89{
90  "durable_objects": {
91    "bindings": [{ "name": "MY_DO", "class_name": "MyDO" }]
92  },
93  "env": {
94    "production": {
95      "durable_objects": {
96        "bindings": [
97          { "name": "MY_DO", "class_name": "MyDO", "environment": "production" }
98        ]
99      }
100    }
101  }
102}
103```
104 
105Deploy: `npx wrangler deploy --env production`
106 
107## Limits & Settings
108 
109```jsonc
110{
111  "limits": { 
112    "cpu_ms": 300000  // Max CPU time: 30s default, 300s max
113  }
114}
115```
116 
117See [Gotchas](./gotchas.md) for complete limits table.
118 
119## Types
120 
121```typescript
122import { DurableObject } from "cloudflare:workers";
123 
124interface Env {
125  MY_DO: DurableObjectNamespace<MyDO>;
126}
127 
128export class MyDO extends DurableObject<Env> {}
129 
130type DurableObjectNamespace<T> = {
131  newUniqueId(options?: { jurisdiction?: string }): DurableObjectId;
132  idFromName(name: string): DurableObjectId;
133  idFromString(id: string): DurableObjectId;
134  get(id: DurableObjectId): DurableObjectStub<T>;
135};
136```
137 
138## Commands
139 
140```bash
141# Development
142npx wrangler dev                    # Local dev
143npx wrangler dev --remote           # Test against production DOs
144 
145# Deployment
146npx wrangler deploy                 # Deploy + auto-apply migrations
147npx wrangler deploy --dry-run       # Validate migrations without deploying
148npx wrangler deploy --env production
149 
150# Management
151npx wrangler durable-objects list                      # List namespaces
152npx wrangler durable-objects info <namespace> <id>     # Inspect specific DO
153npx wrangler durable-objects delete <namespace> <id>   # Delete DO (destroys data)
154```
155 
156## See Also
157 
158- **[API](./api.md)** - DurableObjectState and lifecycle handlers
159- **[Patterns](./patterns.md)** - Multi-environment patterns
160- **[Gotchas](./gotchas.md)** - Migration caveats, limits
161