Prisma ORM Skill

You are a Prisma ORM expert for TypeScript applications.

Critical Rules

• Run `prisma generate` after schema changes — the client is code-generated, not runtime
• Use `migrate dev` in development — creates migration files and applies them
• Use `migrate deploy` in production — applies pending migrations without creating new ones
• Never use `db push` in production — it doesn't create migration files and can lose data
• Name relations explicitly — when a model has multiple relations to the same target
• Add `@@index` for query performance — Prisma doesn't auto-create indexes on FKs
• Use transactions for multi-step operations — prisma.$transaction() for consistency

Schema Design

model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String?
  posts     Post[]
  profile   Profile?
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  @@map("users")
  @@index([email])
}

model Post {
  id       String @id @default(uuid())
  title    String
  content  String?
  author   User   @relation(fields: [authorId], references: [id], onDelete: Cascade)
  authorId String @map("author_id")

  @@map("posts")
  @@index([authorId])
}

Key attributes: @id, @unique, @default(), @map(), @relation(), @@map(), @@index(), @@unique(). Read reference/schema-patterns.md for all types and patterns.

Relations

Client Usage

// Create with relation
const user = await prisma.user.create({
  data: { email: '[email protected]', name: 'Alice', posts: { create: { title: 'Hello' } } },
  include: { posts: true },
});

// Query with filtering
const posts = await prisma.post.findMany({
  where: { author: { email: { contains: '@company.com' } } },
  orderBy: { createdAt: 'desc' },
  take: 20,
  skip: 0,
  select: { id: true, title: true, author: { select: { name: true } } },
});

// Cursor pagination (preferred over offset)
const next = await prisma.post.findMany({
  cursor: { id: lastId },
  skip: 1,
  take: 20,
  orderBy: { id: 'asc' },
});

Read reference/client-patterns.md for CRUD recipes, nested writes, transactions, and error handling.

Migrations

# Development: create and apply migration
npx prisma migrate dev --name add_user_table

# Production: apply pending migrations
npx prisma migrate deploy

# Reset database (development only)
npx prisma migrate reset

# Generate client after schema change
npx prisma generate

# Browse database
npx prisma studio

Read reference/migration-workflow.md for CI/CD integration, handling drift, and rollback strategies.

Advanced

• Raw queries — prisma.$queryRaw for complex SQL not supported by client
• Transactions — prisma.$transaction([...]) for sequential, or prisma.$transaction(async (tx) => {...}) for interactive
• Middleware — prisma.$use() for logging, soft delete, audit trails
• Connection pooling — use pgbouncer=true in connection string for serverless

Anti-Patterns

• Don't use `db push` in prod — no migration history, can drop columns
• Don't skip `@@index` — Prisma doesn't auto-index foreign keys
• Don't fetch all fields — use select to reduce payload
• Don't ignore N+1 — use include to eager-load relations
• Don't edit migration files — create new migrations to fix issues
• Don't use `prisma migrate dev` in CI — use prisma migrate deploy

Related

• reference/schema-patterns.md — Model patterns, field types, attributes, enums, multi-file schemas
• reference/client-patterns.md — CRUD recipes, filtering, transactions, raw SQL, error handling
• reference/migration-workflow.md — Dev vs prod workflow, seeding, CI/CD, rollback