Initial commit

skills/devops/references/cloudflare-d1-kv.md

@@ -0,0 +1,123 @@
+# Cloudflare D1 & KV
+
+## D1 (SQLite Database)
+
+### Setup
+```bash
+# Create database
+wrangler d1 create my-database
+
+# Add to wrangler.toml
+[[d1_databases]]
+binding = "DB"
+database_name = "my-database"
+database_id = "YOUR_DATABASE_ID"
+
+# Apply schema
+wrangler d1 execute my-database --file=./schema.sql
+```
+
+### Usage
+
+```typescript
+// Query
+const result = await env.DB.prepare(
+  "SELECT * FROM users WHERE id = ?"
+).bind(userId).first();
+
+// Insert
+await env.DB.prepare(
+  "INSERT INTO users (name, email) VALUES (?, ?)"
+).bind("Alice", "alice@example.com").run();
+
+// Batch (atomic)
+await env.DB.batch([
+  env.DB.prepare("UPDATE accounts SET balance = balance - 100 WHERE id = ?").bind(user1),
+  env.DB.prepare("UPDATE accounts SET balance = balance + 100 WHERE id = ?").bind(user2)
+]);
+
+// All results
+const { results } = await env.DB.prepare("SELECT * FROM users").all();
+```
+
+### Features
+- Global read replication (low-latency reads)
+- Single-writer consistency
+- Standard SQLite syntax
+- 25GB database size limit
+- ACID transactions with batch
+
+## KV (Key-Value Store)
+
+### Setup
+```bash
+# Create namespace
+wrangler kv:namespace create MY_KV
+
+# Add to wrangler.toml
+[[kv_namespaces]]
+binding = "KV"
+id = "YOUR_NAMESPACE_ID"
+```
+
+### Usage
+
+```typescript
+// Put with TTL
+await env.KV.put("session:token", JSON.stringify(data), {
+  expirationTtl: 3600,
+  metadata: { userId: "123" }
+});
+
+// Get
+const value = await env.KV.get("session:token");
+const json = await env.KV.get("session:token", "json");
+const buffer = await env.KV.get("session:token", "arrayBuffer");
+const stream = await env.KV.get("session:token", "stream");
+
+// Get with metadata
+const { value, metadata } = await env.KV.getWithMetadata("session:token");
+
+// Delete
+await env.KV.delete("session:token");
+
+// List
+const list = await env.KV.list({ prefix: "user:" });
+```
+
+### Features
+- Sub-millisecond reads (edge-cached)
+- Eventual consistency (~60 seconds globally)
+- 25MB value size limit
+- Automatic expiration (TTL)
+
+## Use Cases
+
+### D1
+- Relational data
+- Complex queries with JOINs
+- ACID transactions
+- User accounts, orders, inventory
+
+### KV
+- Cache
+- Sessions
+- Feature flags
+- Rate limiting
+- Real-time counters
+
+## Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| SQL queries | D1 |
+| Sub-millisecond reads | KV |
+| ACID transactions | D1 |
+| Large values (>25MB) | R2 |
+| Strong consistency | D1 (writes), Durable Objects |
+| Automatic expiration | KV |
+
+## Resources
+
+- D1: https://developers.cloudflare.com/d1/
+- KV: https://developers.cloudflare.com/kv/