codecruise 0.1.0

package/config/skills/database/SKILL.md

@@ -0,0 +1,426 @@
+---
+name: db-patterns
+description: Database patterns - N+1 prevention, transactions, cursors, migrations
+keywords: [database, query, transaction, migration, drizzle, prisma, n+1, cursor, pagination]
+---
+
+# Database Standards
+
+Query performance, transactions, and migration best practices.
+
+## Query Performance
+
+### N+1 Prevention
+
+**N+1 queries are blockers in code review.**
+
+```typescript
+// ❌ N+1 PROBLEM
+const users = await db.user.findMany();
+for (const user of users) {
+  const orders = await db.order.findMany({ where: { userId: user.id } });
+  // This executes N+1 queries!
+}
+
+// ✅ EAGER LOADING (Prisma)
+const users = await db.user.findMany({
+  include: {
+    orders: true,
+  },
+});
+
+// ✅ BATCH LOADING (DataLoader pattern)
+const ordersByUserLoader = new DataLoader(async (userIds: string[]) => {
+  const orders = await db.order.findMany({
+    where: { userId: { in: userIds } },
+  });
+  return userIds.map(id => orders.filter(o => o.userId === id));
+});
+
+// Now fetches in batches
+const users = await db.user.findMany();
+const ordersPerUser = await Promise.all(
+  users.map(u => ordersByUserLoader.load(u.id))
+);
+```
+
+### Index Requirements
+
+| Column Type | Index Required |
+|-------------|----------------|
+| Foreign keys | Always |
+| Frequently filtered | Always |
+| Frequently sorted | Always |
+| Unique constraints | Automatic |
+| Full-text search | Specialized (GIN/GIST) |
+
+```sql
+-- Foreign keys
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+
+-- Composite for common queries
+CREATE INDEX idx_orders_user_status ON orders(user_id, status);
+CREATE INDEX idx_orders_created_at ON orders(created_at DESC);
+
+-- Partial index for common filter
+CREATE INDEX idx_orders_pending ON orders(created_at)
+  WHERE status = 'pending';
+```
+
+### Query Analysis
+
+Before deploying any complex query, run EXPLAIN ANALYZE:
+
+```sql
+EXPLAIN ANALYZE
+SELECT o.*, u.email
+FROM orders o
+JOIN users u ON o.user_id = u.id
+WHERE o.status = 'pending'
+  AND o.created_at > NOW() - INTERVAL '7 days'
+ORDER BY o.created_at DESC
+LIMIT 100;
+```
+
+**Red flags in execution plan:**
+- Sequential scan on large tables
+- Nested loops with large row counts
+- Sort operations without index
+- Hash joins with memory spills
+
+### Pagination
+
+Never use OFFSET for large datasets:
+
+```typescript
+// ❌ OFFSET pagination (slow on large datasets)
+const page2 = await db.order.findMany({
+  skip: 1000,
+  take: 100,
+});
+
+// ✅ CURSOR pagination (constant time)
+const page2 = await db.order.findMany({
+  take: 100,
+  cursor: { id: lastSeenId },
+  skip: 1, // Skip the cursor itself
+  orderBy: { createdAt: 'desc' },
+});
+```
+
+## Transactions
+
+### When to Use
+
+- Multi-table mutations that must be atomic
+- Read-then-write patterns (check-then-act)
+- Operations requiring consistent snapshots
+- Financial/billing operations (always)
+
+### Implementation
+
+```typescript
+// Prisma interactive transaction
+async function transferFunds(
+  fromAccountId: string,
+  toAccountId: string,
+  amount: number
+): Promise<void> {
+  await db.$transaction(async (tx) => {
+    // Debit source account
+    const fromAccount = await tx.account.update({
+      where: { id: fromAccountId },
+      data: { balance: { decrement: amount } },
+    });
+
+    if (fromAccount.balance < 0) {
+      throw new ValidationError('INSUFFICIENT_FUNDS', 'Insufficient balance');
+    }
+
+    // Credit destination account
+    await tx.account.update({
+      where: { id: toAccountId },
+      data: { balance: { increment: amount } },
+    });
+
+    // Record transfer
+    await tx.transfer.create({
+      data: {
+        fromAccountId,
+        toAccountId,
+        amount,
+        status: 'completed',
+      },
+    });
+  });
+}
+```
+
+### Isolation Levels
+
+| Level | Use Case | Trade-off |
+|-------|----------|-----------|
+| Read Committed | Default, most operations | Allows non-repeatable reads |
+| Repeatable Read | Financial reports, analytics | Slightly slower |
+| Serializable | Critical financial ops | Slowest, potential retries |
+
+```typescript
+// Set isolation level for sensitive operations
+await db.$transaction(
+  async (tx) => {
+    // ... sensitive operations
+  },
+  {
+    isolationLevel: 'Serializable',
+    maxWait: 5000,
+    timeout: 10000,
+  }
+);
+```
+
+### Deadlock Handling
+
+```typescript
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  maxRetries = 3
+): Promise<T> {
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error as Error;
+
+      // Check if deadlock
+      const isDeadlock =
+        error instanceof Prisma.PrismaClientKnownRequestError &&
+        error.code === 'P2034';
+
+      if (!isDeadlock || attempt === maxRetries) {
+        throw error;
+      }
+
+      // Exponential backoff
+      await sleep(Math.pow(2, attempt) * 100 + Math.random() * 100);
+    }
+  }
+
+  throw lastError!;
+}
+
+// Usage
+await withRetry(() => transferFunds(from, to, amount));
+```
+
+## Connection Management
+
+### Pool Configuration
+
+```typescript
+// Prisma connection pool (via DATABASE_URL)
+// postgresql://user:pass@host:5432/db?connection_limit=20&pool_timeout=10
+
+const poolConfig = {
+  connectionLimit: Math.floor(maxConnections / numberOfInstances),
+  poolTimeout: 10, // seconds to wait for connection
+  idleTimeout: 60, // seconds before idle connection is closed
+};
+```
+
+### Connection Limits
+
+| Environment | Pool Size | Reasoning |
+|-------------|-----------|-----------|
+| Development | 5 | Single instance |
+| Staging | 10 | Limited replicas |
+| Production | 20-50 | Depends on RDS/instance |
+
+Formula: `pool_size = (max_connections - reserved) / num_instances`
+
+## Migrations
+
+### Requirements
+
+1. **Idempotent**: Can run multiple times safely
+2. **Reversible**: Down migration provided
+3. **Tested**: Verified with production-scale data
+4. **Documented**: Breaking changes noted
+
+### Migration Template
+
+```typescript
+// migrations/20240115_add_user_preferences.ts
+
+export async function up(db: Knex): Promise<void> {
+  // Check if already exists (idempotent)
+  const hasTable = await db.schema.hasTable('user_preferences');
+  if (hasTable) return;
+
+  await db.schema.createTable('user_preferences', (table) => {
+    table.uuid('id').primary().defaultTo(db.raw('gen_random_uuid()'));
+    table.uuid('user_id').notNullable().references('users.id').onDelete('CASCADE');
+    table.string('theme').defaultTo('light');
+    table.boolean('email_notifications').defaultTo(true);
+    table.jsonb('settings').defaultTo('{}');
+    table.timestamps(true, true);
+
+    table.unique(['user_id']);
+    table.index(['user_id']);
+  });
+}
+
+export async function down(db: Knex): Promise<void> {
+  await db.schema.dropTableIfExists('user_preferences');
+}
+```
+
+### Breaking Changes
+
+For breaking changes, use multi-phase deployment:
+
+```
+Phase 1: Add new column (nullable)
+  - Deploy code that writes to both old and new
+
+Phase 2: Backfill data
+  - Migrate existing data to new column
+
+Phase 3: Switch reads
+  - Deploy code that reads from new column
+
+Phase 4: Remove old column
+  - Drop old column after verification
+```
+
+### Data Migration Example
+
+```typescript
+// Large table migration with batching
+export async function up(db: Knex): Promise<void> {
+  const BATCH_SIZE = 1000;
+  let processed = 0;
+  let hasMore = true;
+
+  while (hasMore) {
+    const result = await db.raw(`
+      UPDATE users
+      SET email_verified = true
+      WHERE id IN (
+        SELECT id FROM users
+        WHERE email_verified IS NULL
+        LIMIT ${BATCH_SIZE}
+      )
+      RETURNING id
+    `);
+
+    processed += result.rowCount;
+    hasMore = result.rowCount === BATCH_SIZE;
+
+    // Allow other operations between batches
+    await sleep(100);
+  }
+
+  console.log(`Migrated ${processed} users`);
+}
+```
+
+## Soft Deletes
+
+```typescript
+// Model with soft delete
+model User {
+  id        String    @id @default(uuid())
+  email     String    @unique
+  deletedAt DateTime? // Soft delete marker
+
+  @@index([deletedAt])
+}
+
+// Middleware to filter soft-deleted records
+prisma.$use(async (params, next) => {
+  if (params.model === 'User') {
+    if (params.action === 'findMany' || params.action === 'findFirst') {
+      params.args.where = {
+        ...params.args.where,
+        deletedAt: null,
+      };
+    }
+  }
+  return next(params);
+});
+
+// Soft delete operation
+async function deleteUser(id: string): Promise<void> {
+  await db.user.update({
+    where: { id },
+    data: { deletedAt: new Date() },
+  });
+}
+
+// Hard delete (when needed)
+async function permanentlyDeleteUser(id: string): Promise<void> {
+  await db.user.delete({ where: { id } });
+}
+```
+
+## Audit Columns
+
+All tables should have:
+
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- ... business columns
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  created_by UUID REFERENCES users(id),
+  updated_by UUID REFERENCES users(id)
+);
+
+-- Auto-update updated_at
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER orders_updated_at
+  BEFORE UPDATE ON orders
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+```
+
+## Query Timeouts
+
+```typescript
+// Set statement timeout
+await db.$executeRaw`SET statement_timeout = '30s'`;
+
+// Or per-query with Prisma
+const results = await db.$queryRaw`
+  SELECT /*+ MAX_EXECUTION_TIME(30000) */ *
+  FROM large_table
+  WHERE ...
+`;
+```
+
+## Quality Checklist
+
+- [ ] No N+1 queries
+- [ ] Indexes on all FKs and common filters
+- [ ] Complex queries analyzed with EXPLAIN
+- [ ] Cursor pagination for large datasets
+- [ ] Transactions for multi-step mutations
+- [ ] Deadlock handling implemented
+- [ ] Connection pool sized correctly
+- [ ] Migrations are idempotent
+- [ ] Down migrations provided
+- [ ] Breaking changes use phased rollout
+- [ ] Soft deletes where appropriate
+- [ ] Audit columns on all tables
+- [ ] Query timeouts configured