1# Cloudflare Durable Objects Storage
2 
3Persistent storage API for Durable Objects with SQLite and KV backends, PITR, and automatic concurrency control.
4 
5## Overview
6 
7DO Storage provides:
8- SQLite-backed (recommended) or KV-backed
9- SQL API + synchronous/async KV APIs
10- Automatic input/output gates (race-free)
11- 30-day point-in-time recovery (PITR)
12- Transactions and alarms
13 
14**Use cases:** Stateful coordination, real-time collaboration, counters, sessions, rate limiters
15 
16**Billing:** Charged by request, GB-month storage, and rowsRead/rowsWritten for SQL operations
17 
18## Quick Start
19 
20```typescript
21export class Counter extends DurableObject {
22  sql: SqlStorage;
23  
24  constructor(ctx: DurableObjectState, env: Env) {
25    super(ctx, env);
26    this.sql = ctx.storage.sql;
27    this.sql.exec('CREATE TABLE IF NOT EXISTS data(key TEXT PRIMARY KEY, value INTEGER)');
28  }
29  
30  async increment(): Promise<number> {
31    const result = this.sql.exec(
32      'INSERT INTO data VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + 1 RETURNING value',
33      'counter', 1
34    ).one();
35    return result?.value || 1;
36  }
37}
38```
39 
40## Storage Backends
41 
42| Backend | Create Method | APIs | PITR |
43|---------|---------------|------|------|
44| SQLite (recommended) | `new_sqlite_classes` | SQL + sync KV + async KV | ✅ |
45| KV (legacy) | `new_classes` | async KV only | ❌ |
46 
47## Core APIs
48 
49- **SQL API** (`ctx.storage.sql`): Full SQLite with extensions (FTS5, JSON, math)
50- **Sync KV** (`ctx.storage.kv`): Synchronous key-value (SQLite only)
51- **Async KV** (`ctx.storage`): Asynchronous key-value (both backends)
52- **Transactions** (`transactionSync()`, `transaction()`)
53- **PITR** (`getBookmarkForTime()`, `onNextSessionRestoreBookmark()`)
54- **Alarms** (`setAlarm()`, `alarm()` handler)
55 
56## Reading Order
57 
58**New to DO storage:** configuration.md → api.md → patterns.md → gotchas.md  
59**Building features:** patterns.md → api.md → gotchas.md  
60**Debugging issues:** gotchas.md → api.md  
61**Writing tests:** testing.md
62 
63## In This Reference
64 
65- [configuration.md](./configuration.md) - wrangler.jsonc migrations, SQLite vs KV setup, RPC binding
66- [api.md](./api.md) - SQL exec/cursors, KV methods, storage options, transactions, alarms, PITR
67- [patterns.md](./patterns.md) - Schema migrations, caching, rate limiting, batch processing, parent-child coordination
68- [gotchas.md](./gotchas.md) - Concurrency gates, INTEGER precision, transaction rules, SQL limits
69- [testing.md](./testing.md) - vitest-pool-workers setup, testing DOs with SQL/alarms/PITR
70 
71## See Also
72 
73- [durable-objects](../durable-objects/) - DO fundamentals and coordination patterns
74- [workers](../workers/) - Worker runtime for DO stubs
75- [d1](../d1/) - Shared database alternative to per-DO storage
76