Initial commit

skills/optimizing-query-performance/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: optimizing-query-performance
+description: Optimize queries with indexes, batching, and efficient Prisma operations for production performance.
+allowed-tools: Read, Write, Edit, Bash
+version: 1.0.0
+---
+
+<overview>
+Query optimization requires strategic indexing, efficient batching, and monitoring to prevent common production anti-patterns.
+
+Key capabilities: Strategic index placement (@@index, @@unique) · Efficient batch operations (createMany, transactions) · Query analysis & N+1 prevention · Field selection optimization & cursor pagination
+</overview>
+
+<workflow>
+**Phase 1 — Identify:** Enable query logging; analyze patterns/execution times; identify missing indexes, N+1 problems, or inefficient batching
+
+**Phase 2 — Optimize:** Add indexes for filtered/sorted fields; replace loops with batch operations; select only needed fields; use cursor pagination for large datasets
+
+**Phase 3 — Validate:** Measure execution time before/after; verify index usage with EXPLAIN ANALYZE; monitor connection pool under load
+</workflow>
+
+## Quick Reference
+
+**Index Strategy:**
+
+| Scenario              | Index Type                          | Example                        |
+| --------------------- | ----------------------------------- | ------------------------------ |
+| Single field filter   | `@@index([field])`                  | `@@index([status])`            |
+| Multiple field filter | `@@index([field1, field2])`         | `@@index([userId, status])`    |
+| Sort + filter         | `@@index([filterField, sortField])` | `@@index([status, createdAt])` |
+
+**Batch Operations:**
+
+| Operation | Slow (Loop)            | Fast (Batch)   |
+| --------- | ---------------------- | -------------- |
+| Insert    | `for...await create()` | `createMany()` |
+| Update    | `for...await update()` | `updateMany()` |
+| Delete    | `for...await delete()` | `deleteMany()` |
+
+**Performance Gains:** Indexes (10-100x) · Batch ops (50-100x for 1000+ records) · Cursor pagination (constant vs O(n))
+
+<constraints>
+**MUST:** Add indexes for WHERE/ORDER BY/FK fields with frequent queries; use createMany for 100+ records; cursor pagination for deep pagination; select only needed fields; monitor query duration in production
+
+**SHOULD:** Test indexes with production data; chunk 100k+ batches into smaller sizes; use `@@index([field1, field2])` for multi-field filters; remove unused indexes
+
+**NEVER:** Add indexes without performance measurement; offset pagination beyond page 100 on large tables; fetch all
+
+fields when only needing few; loop with individual creates/updates; ignore slow query warnings
+</constraints>
+
+<validation>
+**Measure Performance:**
+```typescript
+const start = Date.now()
+const result = await prisma.user.findMany({ ... })
+console.log(`Query took ${Date.now() - start}ms`)
+```
+Expected: 50-90% improvement for indexed queries, 50-100x for batch operations
+
+**Verify Index Usage:** Run EXPLAIN ANALYZE; confirm "Index Scan" vs "Seq Scan"
+
+**Monitor Production:** Track P95/P99 latency; expect reduced slow query frequency
+
+**Check Write Performance:** Writes may increase 10-30% per index if rarely-used; consider removal
+</validation>
+
+## References
+
+- **Index Strategy**: `references/index-strategy.md` — indexing patterns and trade-offs
+- **Batch Operations**: `references/batch-operations.md` — bulk operations and chunking
+- **Query Monitoring**: `references/query-monitoring.md` — logging setup and slow query analysis
+- **Field Selection**: `references/field-selection.md` — select vs include patterns and N+1 prevention
+- **Optimization Examples**: `references/optimization-examples.md` — real-world improvements
+- **Next.js Integration**: Next.js plugin for App Router-specific patterns
+- **Serverless**: CLIENT-serverless-config skill for connection pooling