@martinffx/atelier 0.1.0

package/skills/typescript-drizzle-orm/references/cloudflare.md

@@ -0,0 +1,392 @@
+# Cloudflare Patterns with Drizzle ORM
+
+Drizzle ORM patterns for Cloudflare D1 and Durable Objects SQLite storage.
+
+## Cloudflare D1
+
+D1 is Cloudflare's managed SQLite database service. Use it for shared data accessed by multiple Workers.
+
+### D1 Connection
+
+```typescript
+import { drizzle } from 'drizzle-orm/d1'
+import * as schema from './schema'
+
+export interface Env {
+  DB: D1Database
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const db = drizzle(env.DB, { schema })
+
+    // Use db for queries
+    const users = await db.query.users.findMany()
+
+    return Response.json(users)
+  },
+}
+```
+
+### D1 Binding Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-worker",
+  "main": "./src/index.ts",
+  "compatibility_date": "2024-11-01",
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "my-database",
+      "database_id": "xxxx-xxxx-xxxx-xxxx"
+    }
+  ]
+}
+```
+
+### D1 Migrations Configuration
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './drizzle',
+  dialect: 'sqlite',
+  driver: 'd1-http',
+  dbCredentials: {
+    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
+    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
+    token: process.env.CLOUDFLARE_D1_TOKEN!,
+  },
+})
+```
+
+### Running D1 Migrations
+
+```bash
+# Generate migration SQL files
+npx drizzle-kit generate
+
+# Apply migrations via wrangler
+npx wrangler d1 migrations apply <DATABASE_NAME>
+
+# Or apply specific migration
+npx wrangler d1 execute <DATABASE_NAME> --file=./drizzle/0001_migration.sql
+```
+
+### Local D1 Development
+
+```bash
+# Use --local flag for development
+npx wrangler dev --local
+
+# Create local D1 database
+npx wrangler d1 create <DATABASE_NAME> --local
+
+# Apply migrations locally
+npx wrangler d1 migrations apply <DATABASE_NAME> --local
+```
+
+## Durable Objects SQLite
+
+Durable Objects with SQLite provide per-object isolated storage. Each DO instance has its own SQLite database.
+
+### DO Connection (from budget app)
+
+```typescript
+import { DurableObject } from 'cloudflare:workers'
+import { drizzle } from 'drizzle-orm/durable-sqlite'
+import { migrate } from 'drizzle-orm/durable-sqlite/migrator'
+import * as schema from './schema'
+import migrations from '../drizzle/migrations'
+
+export interface Env {
+  USER_LEDGER: DurableObjectNamespace<UserLedger>
+}
+
+export class UserLedger extends DurableObject {
+  private readonly db: ReturnType<typeof drizzle>
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env)
+
+    // Initialize Drizzle with DO storage
+    this.db = drizzle(ctx.storage, { schema })
+
+    // Run migrations on first instantiation
+    ctx.blockConcurrencyWhile(async () => {
+      migrate(this.db, migrations)
+    })
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    // Use this.db for queries
+    const users = await this.db.query.users.findMany()
+    return Response.json(users)
+  }
+}
+```
+
+### DO Binding Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "budget",
+  "main": "./workers/app.ts",
+  "compatibility_date": "2024-11-01",
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "USER_LEDGER",
+        "class_name": "UserLedger"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["UserLedger"]
+    }
+  ]
+}
+```
+
+### DO Migrations Configuration
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './app/repositories/schema.ts',
+  out: './drizzle',
+  dialect: 'sqlite',
+  driver: 'durable-sqlite',
+})
+```
+
+### Running DO Migrations
+
+Migrations run automatically when the DO is first instantiated:
+
+```typescript
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env)
+  this.db = drizzle(ctx.storage, { schema })
+
+  // Block concurrent requests during migration
+  ctx.blockConcurrencyWhile(async () => {
+    migrate(this.db, migrations)
+  })
+}
+```
+
+### Importing Migrations
+
+```typescript
+// drizzle/migrations.ts (auto-generated by drizzle-kit)
+export default [
+  {
+    sql: 'CREATE TABLE users ...',
+    batchIdx: 0,
+  },
+  // ... more migrations
+]
+
+// Import in DO
+import migrations from '../drizzle/migrations'
+migrate(this.db, migrations)
+```
+
+## Testing with Cloudflare Workers
+
+### Testing D1
+
+Use `better-sqlite3` for local testing (see [sqlite.md](./sqlite.md)):
+
+```typescript
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import * as schema from './schema'
+
+const sqlite = new Database(':memory:')
+const db = drizzle(sqlite, { schema })
+```
+
+### Testing Durable Objects (from budget app)
+
+Use `@cloudflare/vitest-pool-workers` to run tests inside actual DO instances:
+
+```typescript
+// vitest.config.ts
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'
+
+export default defineWorkersConfig({
+  test: {
+    pool: '@cloudflare/vitest-pool-workers',
+    poolOptions: {
+      workers: {
+        wrangler: { configPath: './wrangler.jsonc' },
+      },
+    },
+  },
+})
+```
+
+```typescript
+// test/database.ts - Test helper
+import { env, runInDurableObject } from 'cloudflare:test'
+import { drizzle } from 'drizzle-orm/durable-sqlite'
+import * as schema from '~/repositories/schema'
+
+export async function runWithTestDB(
+  fn: (db: ReturnType<typeof drizzle>) => Promise<void>
+): Promise<void> {
+  // Create a unique Durable Object instance for this test
+  const id = env.USER_LEDGER.newUniqueId()
+  const stub = env.USER_LEDGER.get(id)
+
+  return await runInDurableObject(stub, async (_instance, state) => {
+    const db = drizzle(state.storage, { schema })
+    return fn(db)
+  })
+}
+```
+
+```typescript
+// repository.test.ts
+import { test, expect } from 'vitest'
+import { runWithTestDB } from '../test/database'
+import { UserRepository } from './UserRepository'
+
+test('create user', async () => {
+  await runWithTestDB(async (db) => {
+    const repo = new UserRepository(db)
+    const user = await repo.create({
+      id: crypto.randomUUID(),
+      name: 'Alice',
+      email: 'alice@example.com',
+    })
+
+    expect(user.name).toBe('Alice')
+  })
+})
+```
+
+### Key Testing Differences
+
+| Approach | D1 | Durable Objects |
+|----------|----|-----------------|
+| Test Driver | `better-sqlite3` (in-memory) | `@cloudflare/vitest-pool-workers` |
+| Test Environment | Node.js process | Miniflare DO instance |
+| Migration | Manual `migrate()` call | Automatic via DO constructor |
+| Isolation | Per-test database | Per-test DO instance |
+
+## When to Use D1 vs Durable Objects
+
+### Use D1 When:
+
+- **Shared database** - Multiple Workers access the same data
+- **Traditional patterns** - Standard REST API, CRUD operations
+- **External tooling** - Need HTTP API access for migrations/admin
+- **Familiar architecture** - Workers query database over network
+- **Simple deployment** - Don't want to manage per-user isolation
+
+### Use Durable Objects SQLite When:
+
+- **Per-user isolation** - Each user has their own database
+- **Colocated compute+storage** - Business logic runs next to data
+- **Strong consistency** - Single-threaded execution guarantees
+- **Real-time coordination** - WebSocket connections, presence, sessions
+- **Stateful actors** - Per-entity business logic (e.g., game rooms, chat)
+
+### Architecture Comparison
+
+**D1 Architecture:**
+```
+Worker → (network) → D1 Database
+Worker → (network) → D1 Database
+Worker → (network) → D1 Database
+```
+
+**Durable Objects Architecture:**
+```
+Worker → DO Instance (compute + SQLite)
+Worker → DO Instance (compute + SQLite)
+Worker → DO Instance (compute + SQLite)
+```
+
+### Performance Considerations
+
+- **D1**: Network latency between Worker and database
+  - Use Smart Placement to colocate Worker near D1
+  - Good for read-heavy workloads
+
+- **DO**: Zero network latency (storage is local)
+  - Single-threaded (one request at a time per DO)
+  - Good for write-heavy, per-user workloads
+
+### Pricing (as of 2024)
+
+**D1:**
+- Shared database across all requests
+- Billed per row read/written
+- Free tier: 5M row reads, 100K row writes/day
+
+**Durable Objects SQLite:**
+- Per-DO instance billing
+- Billed per SQL query + storage
+- Free tier: SQLite-backed DO only (no KV-backed)
+
+## Migration Strategy
+
+If starting with D1 and need to migrate to DO SQLite:
+
+1. Schema is the same (both use `sqlite-core`)
+2. Change `drizzle-orm/d1` → `drizzle-orm/durable-sqlite`
+3. Change connection from `env.DB` → `ctx.storage`
+4. Add DO routing logic in Worker
+5. Migrate data (custom script needed)
+
+```typescript
+// Before (D1)
+const db = drizzle(env.DB, { schema })
+
+// After (DO)
+const db = drizzle(ctx.storage, { schema })
+```
+
+## Best Practices
+
+### D1
+
+- Use connection pooling (handled by Workers runtime)
+- Batch queries when possible
+- Index frequently queried columns
+- Use prepared statements (automatic with Drizzle)
+- Monitor query performance via Cloudflare dashboard
+
+### Durable Objects
+
+- Keep DO instances lightweight (single responsibility)
+- Use `blockConcurrencyWhile()` for initialization
+- Run migrations on first instantiation
+- Handle alarms for periodic cleanup
+- Design for single-threaded execution
+- Avoid long-running operations in constructor
+
+### Both
+
+- Use transactions for multi-step operations
+- Define foreign keys for data integrity
+- Create indexes for query performance
+- Use type inference (`$inferSelect`, `$inferInsert`)
+- Follow repository pattern for data access
+- Test with actual CF runtime (`vitest-pool-workers` or `better-sqlite3`)