1# DO Storage Gotchas & Troubleshooting
2 
3## Concurrency Model (CRITICAL)
4 
5Durable Objects use **input/output gates** to prevent race conditions:
6 
7### Input Gates
8Block new requests during storage reads from CURRENT request:
9 
10```typescript
11// SAFE: Input gate active during await
12async increment() {
13  const val = await this.ctx.storage.get("counter"); // Input gate blocks other requests
14  await this.ctx.storage.put("counter", val + 1);
15  return val;
16}
17```
18 
19### Output Gates
20Hold response until ALL writes from current request confirm:
21 
22```typescript
23// SAFE: Output gate waits for put() to confirm before returning response
24async increment() {
25  const val = await this.ctx.storage.get("counter");
26  this.ctx.storage.put("counter", val + 1); // No await
27  return new Response(String(val)); // Response delayed until write confirms
28}
29```
30 
31### Write Coalescing
32Multiple writes to same key = atomic (last write wins):
33 
34```typescript
35// SAFE: All three writes coalesce atomically
36this.ctx.storage.put("key", 1);
37this.ctx.storage.put("key", 2);
38this.ctx.storage.put("key", 3); // Final value: 3
39```
40 
41### Breaking Gates (DANGER)
42 
43**fetch() breaks input/output gates** → allows request interleaving:
44 
45```typescript
46// UNSAFE: fetch() allows another request to interleave
47async unsafe() {
48  const val = await this.ctx.storage.get("counter");
49  await fetch("https://api.example.com"); // Gate broken!
50  await this.ctx.storage.put("counter", val + 1); // Race condition possible
51}
52```
53 
54**Solution:** Use `blockConcurrencyWhile()` or `transaction()`:
55 
56```typescript
57// SAFE: Block concurrent requests explicitly
58async safe() {
59  return await this.ctx.blockConcurrencyWhile(async () => {
60    const val = await this.ctx.storage.get("counter");
61    await fetch("https://api.example.com");
62    await this.ctx.storage.put("counter", val + 1);
63    return val;
64  });
65}
66```
67 
68### allowConcurrency Option
69 
70Opt out of input gate for reads that don't need protection:
71 
72```typescript
73// Allow concurrent reads (no consistency guarantee)
74const val = await this.ctx.storage.get("metrics", { allowConcurrency: true });
75```
76 
77## Common Errors
78 
79### "Race Condition in Concurrent Calls"
80 
81**Cause:** Multiple concurrent storage operations initiated from same event (e.g., `Promise.all()`) are not protected by input gate  
82**Solution:** Avoid concurrent storage operations within single event; input gate only serializes requests from different events, not operations within same event
83 
84### "Direct SQL Transaction Statements"
85 
86**Cause:** Using `BEGIN TRANSACTION` directly instead of transaction methods  
87**Solution:** Use `this.ctx.storage.transactionSync()` for sync operations or `this.ctx.storage.transaction()` for async operations
88 
89### "Async in transactionSync"
90 
91**Cause:** Using async operations inside `transactionSync()` callback  
92**Solution:** Use async `transaction()` method instead of `transactionSync()` when async operations needed
93 
94### "TypeScript Type Mismatch at Runtime"
95 
96**Cause:** Query doesn't return all fields specified in TypeScript type  
97**Solution:** Ensure SQL query selects all columns that match the TypeScript type definition
98 
99### "Silent Data Corruption with Large IDs"
100 
101**Cause:** JavaScript numbers have 53-bit precision; SQLite INTEGER is 64-bit  
102**Symptom:** IDs > 9007199254740991 (Number.MAX_SAFE_INTEGER) silently truncate/corrupt  
103**Solution:** Store large IDs as TEXT:
104 
105```typescript
106// BAD: Snowflake/Twitter IDs will corrupt
107this.sql.exec("CREATE TABLE events(id INTEGER PRIMARY KEY)");
108this.sql.exec("INSERT INTO events VALUES (?)", 1234567890123456789n); // Corrupts!
109 
110// GOOD: Store as TEXT
111this.sql.exec("CREATE TABLE events(id TEXT PRIMARY KEY)");
112this.sql.exec("INSERT INTO events VALUES (?)", "1234567890123456789");
113```
114 
115### "Alarm Not Deleted with deleteAll()"
116 
117**Cause:** `deleteAll()` doesn't delete alarms automatically  
118**Solution:** Call `deleteAlarm()` explicitly before `deleteAll()` to remove alarm
119 
120### "Slow Performance"
121 
122**Cause:** Using async KV API instead of sync API  
123**Solution:** Use sync KV API (`ctx.storage.kv`) for better performance with simple key-value operations
124 
125### "High Billing from Storage Operations"
126 
127**Cause:** Excessive `rowsRead`/`rowsWritten` or unused objects not cleaned up  
128**Solution:** Monitor `rowsRead`/`rowsWritten` metrics and ensure unused objects call `deleteAll()`
129 
130### "Durable Object Overloaded"
131 
132**Cause:** Single DO exceeding ~1K req/sec soft limit  
133**Solution:** Shard across multiple DOs with random IDs or other distribution strategy
134 
135## Limits
136 
137| Limit | Value | Notes |
138|-------|-------|-------|
139| Max columns per table | 100 | SQL limitation |
140| Max string/BLOB per row | 2 MB | SQL limitation |
141| Max row size | 2 MB | SQL limitation |
142| Max SQL statement size | 100 KB | SQL limitation |
143| Max SQL parameters | 100 | SQL limitation |
144| Max LIKE/GLOB pattern | 50 B | SQL limitation |
145| SQLite storage per object | 10 GB | SQLite-backed storage |
146| SQLite key+value size | 2 MB | SQLite-backed storage |
147| KV storage per object | Unlimited | KV-style storage |
148| KV key size | 2 KiB | KV-style storage |
149| KV value size | 128 KiB | KV-style storage |
150| Request throughput | ~1K req/sec | Soft limit per DO |
151