1# DO Storage API Reference
2 
3## SQL API
4 
5```typescript
6const cursor = this.sql.exec('SELECT * FROM users WHERE email = ?', email);
7for (let row of cursor) {} // Objects: { id, name, email }
8cursor.toArray(); cursor.one(); // Single row (throws if != 1)
9for (let row of cursor.raw()) {} // Arrays: [1, "Alice", "..."]
10 
11// Manual iteration
12const iter = cursor[Symbol.iterator]();
13const first = iter.next(); // { value: {...}, done: false }
14 
15cursor.columnNames; // ["id", "name", "email"]
16cursor.rowsRead; cursor.rowsWritten; // Billing
17 
18type User = { id: number; name: string; email: string };
19const user = this.sql.exec<User>('...', userId).one();
20```
21 
22## Sync KV API (SQLite only)
23 
24```typescript
25this.ctx.storage.kv.get("counter"); // undefined if missing
26this.ctx.storage.kv.put("counter", 42);
27this.ctx.storage.kv.put("user", { name: "Alice", age: 30 });
28this.ctx.storage.kv.delete("counter"); // true if existed
29 
30for (let [key, value] of this.ctx.storage.kv.list()) {}
31 
32// List options: start, prefix, reverse, limit
33this.ctx.storage.kv.list({ start: "user:", prefix: "user:", reverse: true, limit: 100 });
34```
35 
36## Async KV API (Both backends)
37 
38```typescript
39await this.ctx.storage.get("key"); // Single
40await this.ctx.storage.get(["key1", "key2"]); // Multiple (max 128)
41await this.ctx.storage.put("key", value); // Single
42await this.ctx.storage.put({ "key1": "v1", "key2": { nested: true } }); // Multiple (max 128)
43await this.ctx.storage.delete("key");
44await this.ctx.storage.delete(["key1", "key2"]);
45await this.ctx.storage.list({ prefix: "user:", limit: 100 });
46 
47// Options: allowConcurrency, noCache, allowUnconfirmed
48await this.ctx.storage.get("key", { allowConcurrency: true, noCache: true });
49await this.ctx.storage.put("key", value, { allowUnconfirmed: true, noCache: true });
50```
51 
52### Storage Options
53 
54| Option | Methods | Effect | Use Case |
55|--------|---------|--------|----------|
56| `allowConcurrency` | get, list | Skip input gate; allow concurrent requests during read | Read-heavy metrics that don't need strict consistency |
57| `noCache` | get, put, list | Skip in-memory cache; always read from disk | Rarely-accessed data or testing storage directly |
58| `allowUnconfirmed` | put, delete | Return before write confirms (still protected by output gate) | Non-critical writes where latency matters more than confirmation |
59 
60## Transactions
61 
62```typescript
63// Sync (SQL/sync KV only)
64this.ctx.storage.transactionSync(() => {
65  this.sql.exec('UPDATE accounts SET balance = balance - ? WHERE id = ?', 100, 1);
66  this.sql.exec('UPDATE accounts SET balance = balance + ? WHERE id = ?', 100, 2);
67  return "result";
68});
69 
70// Async
71await this.ctx.storage.transaction(async () => {
72  const value = await this.ctx.storage.get("counter");
73  await this.ctx.storage.put("counter", value + 1);
74  if (value > 100) this.ctx.storage.rollback(); // Explicit rollback
75});
76```
77 
78## Point-in-Time Recovery
79 
80```typescript
81await this.ctx.storage.getCurrentBookmark();
82await this.ctx.storage.getBookmarkForTime(Date.now() - 2 * 24 * 60 * 60 * 1000);
83await this.ctx.storage.onNextSessionRestoreBookmark(bookmark);
84this.ctx.abort(); // Restart to apply; bookmarks lexically comparable (earlier < later)
85```
86 
87## Alarms
88 
89```typescript
90await this.ctx.storage.setAlarm(Date.now() + 60000); // Timestamp or Date
91await this.ctx.storage.getAlarm();
92await this.ctx.storage.deleteAlarm();
93 
94async alarm() { await this.doScheduledWork(); }
95```
96 
97## Misc
98 
99```typescript
100await this.ctx.storage.deleteAll(); // Atomic for SQLite; alarm NOT included
101this.ctx.storage.sql.databaseSize; // Bytes
102```
103