1# Cloudflare D1 Database
2 
3Expert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.
4 
5## Overview
6 
7D1 is Cloudflare's managed, serverless database with:
8- SQLite SQL semantics and compatibility
9- Built-in disaster recovery via Time Travel (30-day point-in-time recovery)
10- Horizontal scale-out architecture (10 GB per database)
11- Worker and HTTP API access
12- Pricing based on query and storage costs only
13 
14**Architecture Philosophy**: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.
15 
16## Quick Start
17 
18```bash
19# Create database
20wrangler d1 create <database-name>
21 
22# Execute migration
23wrangler d1 migrations apply <db-name> --remote
24 
25# Local development
26wrangler dev
27```
28 
29## Core Query Methods
30 
31```typescript
32// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value
33// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)
34const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();
35const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
36```
37 
38## Batch Operations
39 
40```typescript
41// Multiple queries in single round trip (atomic transaction)
42const results = await env.DB.batch([
43  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
44  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
45  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)
46]);
47```
48 
49## Sessions API (Paid Plans)
50 
51```typescript
52// Create long-running session for analytics/migrations (up to 15 minutes)
53const session = env.DB.withSession();
54try {
55  await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run();
56  await session.prepare('ANALYZE').run();
57} finally {
58  session.close(); // Always close to release resources
59}
60```
61 
62## Read Replication (Paid Plans)
63 
64```typescript
65// Read from nearest replica for lower latency (automatic failover)
66const user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();
67 
68// Writes always go to primary
69await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();
70```
71 
72## Platform Limits
73 
74| Limit | Free Tier | Paid Plans |
75|-------|-----------|------------|
76| Database size | 500 MB | 10 GB per database |
77| Row size | 1 MB max | 1 MB max |
78| Query timeout | 30 seconds | 30 seconds |
79| Batch size | 1,000 statements | 10,000 statements |
80| Time Travel retention | 7 days | 30 days |
81| Read replicas | Not available | Yes (paid add-on) |
82 
83**Pricing**: $0.001 per million rows read + $1.00 per million rows written + $0.75/GB storage/month (includes free monthly allowance; no per-database fee)
84 
85## CLI Commands
86 
87```bash
88# Database management
89wrangler d1 create <db-name>
90wrangler d1 list
91wrangler d1 delete <db-name>
92 
93# Migrations
94wrangler d1 migrations create <db-name> <migration-name>    # Create new migration file
95wrangler d1 migrations apply <db-name> --remote             # Apply pending migrations
96wrangler d1 migrations apply <db-name> --local              # Apply locally
97wrangler d1 migrations list <db-name> --remote              # Show applied migrations
98 
99# Direct SQL execution
100wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
101wrangler d1 execute <db-name> --local --file=./schema.sql
102 
103# Backups & Import/Export
104wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export with schema
105wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
106wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time recovery
107 
108# Development
109wrangler dev --persist-to=./.wrangler/state
110```
111 
112## Reading Order
113 
114**Start here**: Quick Start above → configuration.md (setup) → api.md (queries)
115 
116**Common tasks**:
117- First time setup: configuration.md → Run migrations
118- Adding queries: api.md → Prepared statements
119- Pagination/caching: patterns.md
120- Production optimization: Read Replication + Sessions API (this file)
121- Debugging: gotchas.md
122 
123## In This Reference
124 
125- [configuration.md](./configuration.md) - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev
126- [api.md](./api.md) - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling
127- [patterns.md](./patterns.md) - Pagination, bulk operations, caching, multi-tenant, sessions, analytics
128- [gotchas.md](./gotchas.md) - SQL injection, limits by plan tier, performance, common errors
129 
130## See Also
131 
132- [workers](../workers/) - Worker runtime and fetch handler patterns
133- [hyperdrive](../hyperdrive/) - Connection pooling for external databases
134