@martinffx/atelier 2.0.0 → 3.0.0

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

@@ -1,392 +0,0 @@
-# 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`)