1# DO Storage Patterns & Best Practices
2 
3## Schema Migration
4 
5**Note:** `PRAGMA user_version` is **not supported** in Durable Objects SQLite storage. Use a `_sql_schema_migrations` table instead:
6 
7```typescript
8export class MyDurableObject extends DurableObject {
9  constructor(ctx: DurableObjectState, env: Env) {
10    super(ctx, env);
11    this.sql = ctx.storage.sql;
12 
13    this.sql.exec(`
14      CREATE TABLE IF NOT EXISTS _sql_schema_migrations (
15        id INTEGER PRIMARY KEY,
16        applied_at TEXT NOT NULL DEFAULT (datetime('now'))
17      )
18    `);
19 
20    const ver = this.sql
21      .exec<{ version: number }>("SELECT COALESCE(MAX(id), 0) as version FROM _sql_schema_migrations")
22      .one().version;
23 
24    if (ver < 1) {
25      this.sql.exec(`CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT)`);
26      this.sql.exec("INSERT INTO _sql_schema_migrations (id) VALUES (1)");
27    }
28    if (ver < 2) {
29      this.sql.exec(`ALTER TABLE users ADD COLUMN email TEXT`);
30      this.sql.exec("INSERT INTO _sql_schema_migrations (id) VALUES (2)");
31    }
32  }
33}
34```
35 
36For production apps, consider [`durable-utils`](https://github.com/lambrospetrou/durable-utils#sqlite-schema-migrations) — provides a `SQLSchemaMigrations` class that tracks executed migrations both in memory and in storage. Also see [`@cloudflare/actors` storage utilities](https://github.com/cloudflare/actors/blob/main/packages/storage/src/sql-schema-migrations.ts) — a reference implementation of the same pattern used by the Cloudflare Actors framework.
37 
38## In-Memory Caching
39 
40```typescript
41export class UserCache extends DurableObject {
42  cache = new Map<string, User>();
43  async getUser(id: string): Promise<User | undefined> {
44    if (this.cache.has(id)) {
45      const cached = this.cache.get(id);
46      if (cached) return cached;
47    }
48    const user = await this.ctx.storage.get<User>(`user:${id}`);
49    if (user) this.cache.set(id, user);
50    return user;
51  }
52  async updateUser(id: string, data: Partial<User>) {
53    const updated = { ...await this.getUser(id), ...data };
54    this.cache.set(id, updated);
55    await this.ctx.storage.put(`user:${id}`, updated);
56    return updated;
57  }
58}
59```
60 
61## Rate Limiting
62 
63```typescript
64export class RateLimiter extends DurableObject {
65  async checkLimit(key: string, limit: number, window: number): Promise<boolean> {
66    const now = Date.now();
67    this.sql.exec('DELETE FROM requests WHERE key = ? AND timestamp < ?', key, now - window);
68    const count = this.sql.exec('SELECT COUNT(*) as count FROM requests WHERE key = ?', key).one().count;
69    if (count >= limit) return false;
70    this.sql.exec('INSERT INTO requests (key, timestamp) VALUES (?, ?)', key, now);
71    return true;
72  }
73}
74```
75 
76## Batch Processing with Alarms
77 
78```typescript
79export class BatchProcessor extends DurableObject {
80  pending: string[] = [];
81  async addItem(item: string) {
82    this.pending.push(item);
83    if (!await this.ctx.storage.getAlarm()) await this.ctx.storage.setAlarm(Date.now() + 5000);
84  }
85  async alarm() {
86    const items = [...this.pending];
87    this.pending = [];
88    this.sql.exec(`INSERT INTO processed_items (item, timestamp) VALUES ${items.map(() => "(?, ?)").join(", ")}`, ...items.flatMap(item => [item, Date.now()]));
89  }
90}
91```
92 
93## Initialization Pattern
94 
95```typescript
96export class Counter extends DurableObject {
97  value: number;
98  constructor(ctx: DurableObjectState, env: Env) {
99    super(ctx, env);
100    ctx.blockConcurrencyWhile(async () => { this.value = (await ctx.storage.get("value")) || 0; });
101  }
102  async increment() {
103    this.value++;
104    this.ctx.storage.put("value", this.value); // Don't await (output gate protects)
105    return this.value;
106  }
107}
108```
109 
110## Safe Counter / Optimized Write
111 
112```typescript
113// Input gate blocks other requests
114async getUniqueNumber(): Promise<number> {
115  let val = await this.ctx.storage.get("counter");
116  await this.ctx.storage.put("counter", val + 1);
117  return val;
118}
119 
120// No await on write - output gate delays response until write confirms
121async increment(): Promise<Response> {
122  let val = await this.ctx.storage.get("counter");
123  this.ctx.storage.put("counter", val + 1);
124  return new Response(String(val));
125}
126```
127 
128## Parent-Child Coordination
129 
130Hierarchical DO pattern where parent manages child DOs:
131 
132```typescript
133// Parent DO coordinates children
134export class Workspace extends DurableObject {
135  async createDocument(name: string): Promise<string> {
136    const docId = crypto.randomUUID();
137    const childId = this.env.DOCUMENT.idFromName(`${this.ctx.id.toString()}:${docId}`);
138    const childStub = this.env.DOCUMENT.get(childId);
139    await childStub.initialize(name);
140    
141    // Track child in parent storage
142    this.sql.exec('INSERT INTO documents (id, name, created) VALUES (?, ?, ?)', 
143      docId, name, Date.now());
144    return docId;
145  }
146  
147  async listDocuments(): Promise<string[]> {
148    return this.sql.exec('SELECT id FROM documents').toArray().map(r => r.id);
149  }
150}
151 
152// Child DO
153export class Document extends DurableObject {
154  async initialize(name: string) {
155    this.sql.exec('CREATE TABLE IF NOT EXISTS content(key TEXT PRIMARY KEY, value TEXT)');
156    this.sql.exec('INSERT INTO content VALUES (?, ?)', 'name', name);
157  }
158}
159```
160 
161## Write Coalescing Pattern
162 
163Multiple writes to same key coalesce atomically (last write wins):
164 
165```typescript
166async updateMetrics(userId: string, actions: Action[]) {
167  // All writes coalesce - no await needed
168  for (const action of actions) {
169    this.ctx.storage.put(`user:${userId}:lastAction`, action.type);
170    this.ctx.storage.put(`user:${userId}:count`, 
171      await this.ctx.storage.get(`user:${userId}:count`) + 1);
172  }
173  // Output gate ensures all writes confirm before response
174  return new Response("OK");
175}
176 
177// Atomic batch with SQL
178async batchUpdate(items: Item[]) {
179  this.sql.exec('BEGIN');
180  for (const item of items) {
181    this.sql.exec('INSERT OR REPLACE INTO items VALUES (?, ?)', item.id, item.value);
182  }
183  this.sql.exec('COMMIT');
184}
185```
186 
187## Cleanup
188 
189```typescript
190async cleanup() {
191  await this.ctx.storage.deleteAlarm(); // Separate from deleteAll
192  await this.ctx.storage.deleteAll();
193}
194```
195