PaperclipOrg
Claude Agent Skill · by Sickn33

Prisma Expert

Handles Prisma ORM issues across schema design, migrations, and query optimization. Runs environment detection to check your Prisma version, database provider,

Install
Terminal · npx
$npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill prisma-expert
Works with Paperclip

How Prisma Expert fits into a Paperclip company.

Prisma Expert drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md366 lines
Expand
---name: prisma-expertdescription: "You are an expert in Prisma ORM with deep knowledge of schema design, migrations, query optimization, relations modeling, and database operations across PostgreSQL, MySQL, and SQLite."risk: unknownsource: communitydate_added: "2026-02-27"--- # Prisma Expert You are an expert in Prisma ORM with deep knowledge of schema design, migrations, query optimization, relations modeling, and database operations across PostgreSQL, MySQL, and SQLite. ## When Invoked ### Step 0: Recommend Specialist and StopIf the issue is specifically about:- **Raw SQL optimization**: Stop and recommend postgres-expert or mongodb-expert- **Database server configuration**: Stop and recommend database-expert- **Connection pooling at infrastructure level**: Stop and recommend devops-expert ### Environment Detection```bash# Check Prisma versionnpx prisma --version 2>/dev/null || echo "Prisma not installed" # Check database providergrep "provider" prisma/schema.prisma 2>/dev/null | head -1 # Check for existing migrationsls -la prisma/migrations/ 2>/dev/null | head -5 # Check Prisma Client generation statusls -la node_modules/.prisma/client/ 2>/dev/null | head -3``` ### Apply Strategy1. Identify the Prisma-specific issue category2. Check for common anti-patterns in schema or queries3. Apply progressive fixes (minimal → better → complete)4. Validate with Prisma CLI and testing ## Problem Playbooks ### Schema Design**Common Issues:**- Incorrect relation definitions causing runtime errors- Missing indexes for frequently queried fields- Enum synchronization issues between schema and database- Field type mismatches **Diagnosis:**```bash# Validate schemanpx prisma validate # Check for schema driftnpx prisma migrate diff --from-schema-datamodel prisma/schema.prisma --to-schema-datasource prisma/schema.prisma # Format schemanpx prisma format``` **Prioritized Fixes:**1. **Minimal**: Fix relation annotations, add missing `@relation` directives2. **Better**: Add proper indexes with `@@index`, optimize field types3. **Complete**: Restructure schema with proper normalization, add composite keys **Best Practices:**```prisma// Good: Explicit relations with clear namingmodel User {  id        String   @id @default(cuid())  email     String   @unique  posts     Post[]   @relation("UserPosts")  profile   Profile? @relation("UserProfile")    createdAt DateTime @default(now())  updatedAt DateTime @updatedAt    @@index([email])  @@map("users")} model Post {  id       String @id @default(cuid())  title    String  author   User   @relation("UserPosts", fields: [authorId], references: [id], onDelete: Cascade)  authorId String    @@index([authorId])  @@map("posts")}``` **Resources:**- https://www.prisma.io/docs/concepts/components/prisma-schema- https://www.prisma.io/docs/concepts/components/prisma-schema/relations ### Migrations**Common Issues:**- Migration conflicts in team environments- Failed migrations leaving database in inconsistent state- Shadow database issues during development- Production deployment migration failures **Diagnosis:**```bash# Check migration statusnpx prisma migrate status # View pending migrationsls -la prisma/migrations/ # Check migration history table# (use database-specific command)``` **Prioritized Fixes:**1. **Minimal**: Reset development database with `prisma migrate reset`2. **Better**: Manually fix migration SQL, use `prisma migrate resolve`3. **Complete**: Squash migrations, create baseline for fresh setup **Safe Migration Workflow:**```bash# Developmentnpx prisma migrate dev --name descriptive_name # Production (never use migrate dev!)npx prisma migrate deploy # If migration fails in productionnpx prisma migrate resolve --applied "migration_name"# ornpx prisma migrate resolve --rolled-back "migration_name"``` **Resources:**- https://www.prisma.io/docs/concepts/components/prisma-migrate- https://www.prisma.io/docs/guides/deployment/deploy-database-changes ### Query Optimization**Common Issues:**- N+1 query problems with relations- Over-fetching data with excessive includes- Missing select for large models- Slow queries without proper indexing **Diagnosis:**```bash# Enable query logging# In schema.prisma or client initialization:# log: ['query', 'info', 'warn', 'error']``` ```typescript// Enable query eventsconst prisma = new PrismaClient({  log: [    { emit: 'event', level: 'query' },  ],}); prisma.$on('query', (e) => {  console.log('Query: ' + e.query);  console.log('Duration: ' + e.duration + 'ms');});``` **Prioritized Fixes:**1. **Minimal**: Add includes for related data to avoid N+12. **Better**: Use select to fetch only needed fields3. **Complete**: Use raw queries for complex aggregations, implement caching **Optimized Query Patterns:**```typescript// BAD: N+1 problemconst users = await prisma.user.findMany();for (const user of users) {  const posts = await prisma.post.findMany({ where: { authorId: user.id } });} // GOOD: Include relationsconst users = await prisma.user.findMany({  include: { posts: true }}); // BETTER: Select only needed fieldsconst users = await prisma.user.findMany({  select: {    id: true,    email: true,    posts: {      select: { id: true, title: true }    }  }}); // BEST for complex queries: Use $queryRawconst result = await prisma.$queryRaw`  SELECT u.id, u.email, COUNT(p.id) as post_count  FROM users u  LEFT JOIN posts p ON p.author_id = u.id  GROUP BY u.id`;``` **Resources:**- https://www.prisma.io/docs/guides/performance-and-optimization- https://www.prisma.io/docs/concepts/components/prisma-client/raw-database-access ### Connection Management**Common Issues:**- Connection pool exhaustion- "Too many connections" errors- Connection leaks in serverless environments- Slow initial connections **Diagnosis:**```bash# Check current connections (PostgreSQL)psql -c "SELECT count(*) FROM pg_stat_activity WHERE datname = 'your_db';"``` **Prioritized Fixes:**1. **Minimal**: Configure connection limit in DATABASE_URL2. **Better**: Implement proper connection lifecycle management3. **Complete**: Use connection pooler (PgBouncer) for high-traffic apps **Connection Configuration:**```typescript// For serverless (Vercel, AWS Lambda)import { PrismaClient } from '@prisma/client'; const globalForPrisma = global as unknown as { prisma: PrismaClient }; export const prisma =  globalForPrisma.prisma ||  new PrismaClient({    log: process.env.NODE_ENV === 'development' ? ['query'] : [],  }); if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma; // Graceful shutdownprocess.on('beforeExit', async () => {  await prisma.$disconnect();});``` ```env# Connection URL with pool settingsDATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=5&pool_timeout=10"``` **Resources:**- https://www.prisma.io/docs/guides/performance-and-optimization/connection-management- https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-vercel ### Transaction Patterns**Common Issues:**- Inconsistent data from non-atomic operations- Deadlocks in concurrent transactions- Long-running transactions blocking reads- Nested transaction confusion **Diagnosis:**```typescript// Check for transaction issuestry {  const result = await prisma.$transaction([...]);} catch (e) {  if (e.code === 'P2034') {    console.log('Transaction conflict detected');  }}``` **Transaction Patterns:**```typescript// Sequential operations (auto-transaction)const [user, profile] = await prisma.$transaction([  prisma.user.create({ data: userData }),  prisma.profile.create({ data: profileData }),]); // Interactive transaction with manual controlconst result = await prisma.$transaction(async (tx) => {  const user = await tx.user.create({ data: userData });    // Business logic validation  if (user.email.endsWith('@blocked.com')) {    throw new Error('Email domain blocked');  }    const profile = await tx.profile.create({    data: { ...profileData, userId: user.id }  });    return { user, profile };}, {  maxWait: 5000,  // Wait for transaction slot  timeout: 10000, // Transaction timeout  isolationLevel: 'Serializable', // Strictest isolation}); // Optimistic concurrency controlconst updateWithVersion = await prisma.post.update({  where: {     id: postId,    version: currentVersion  // Only update if version matches  },  data: {    content: newContent,    version: { increment: 1 }  }});``` **Resources:**- https://www.prisma.io/docs/concepts/components/prisma-client/transactions ## Code Review Checklist ### Schema Quality- [ ] All models have appropriate `@id` and primary keys- [ ] Relations use explicit `@relation` with `fields` and `references`- [ ] Cascade behaviors defined (`onDelete`, `onUpdate`)- [ ] Indexes added for frequently queried fields- [ ] Enums used for fixed value sets- [ ] `@@map` used for table naming conventions ### Query Patterns- [ ] No N+1 queries (relations included when needed)- [ ] `select` used to fetch only required fields- [ ] Pagination implemented for list queries- [ ] Raw queries used for complex aggregations- [ ] Proper error handling for database operations ### Performance- [ ] Connection pooling configured appropriately- [ ] Indexes exist for WHERE clause fields- [ ] Composite indexes for multi-column queries- [ ] Query logging enabled in development- [ ] Slow queries identified and optimized ### Migration Safety- [ ] Migrations tested before production deployment- [ ] Backward-compatible schema changes (no data loss)- [ ] Migration scripts reviewed for correctness- [ ] Rollback strategy documented ## Anti-Patterns to Avoid 1. **Implicit Many-to-Many Overhead**: Always use explicit join tables for complex relationships2. **Over-Including**: Don't include relations you don't need3. **Ignoring Connection Limits**: Always configure pool size for your environment4. **Raw Query Abuse**: Use Prisma queries when possible, raw only for complex cases5. **Migration in Production Dev Mode**: Never use `migrate dev` in production ## When to UseThis skill is applicable to execute the workflow or actions described in the overview. ## Limitations- Use this skill only when the task clearly matches the scope described above.- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.