Prisma ORM Framework Skill

A Claude Code skill for database development with Prisma — covering schema design, migrations, query optimization, relations, middleware, and production deployment patterns.

When to Use This Skill

Choose this skill when:

• Designing database schemas with Prisma Schema Language
• Running and managing database migrations
• Writing type-safe database queries with Prisma Client
• Optimizing Prisma query performance
• Implementing relation queries (one-to-many, many-to-many)
• Deploying Prisma-based applications to production

Consider alternatives when:

• You need raw SQL control (use a PostgreSQL skill)
• You need a different ORM (use TypeORM, Drizzle, or Knex)
• You need NoSQL databases (Prisma supports SQL databases primarily)

Quick Start

Copy
# Install Prisma
npm install prisma @prisma/client
npx prisma init

# Define schema, then run migration
npx prisma migrate dev --name init

# Generate client after schema changes
npx prisma generate

# Open Prisma Studio
npx prisma studio

Copy
// prisma/schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

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")
}

model Post {
  id        String   @id @default(uuid())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String   @map("author_id")
  tags      Tag[]
  createdAt DateTime @default(now()) @map("created_at")

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

model Tag {
  id    String @id @default(uuid())
  name  String @unique
  posts Post[]

  @@map("tags")
}

Core Concepts

Query Patterns

Operation	Method	Example
Find one	findUnique	prisma.user.findUnique({ where: { email } })
Find many	findMany	prisma.post.findMany({ where: { published: true } })
Create	create	prisma.user.create({ data: { email, name } })
Update	update	prisma.user.update({ where: { id }, data: { name } })
Upsert	upsert	prisma.user.upsert({ where, create, update })
Delete	delete	prisma.user.delete({ where: { id } })
Count	count	prisma.post.count({ where: { published: true } })
Aggregate	aggregate	prisma.order.aggregate({ _sum: { total: true } })

Relation Queries

Copy
// Eager loading with include
const user = await prisma.user.findUnique({
  where: { id: userId },
  include: {
    posts: { where: { published: true }, orderBy: { createdAt: 'desc' } },
    profile: true,
  },
});

// Nested writes
const user = await prisma.user.create({
  data: {
    email: '[email protected]',
    name: 'Jane',
    posts: {
      create: [
        { title: 'First Post', content: 'Hello world' },
        { title: 'Second Post', content: 'More content' },
      ],
    },
  },
  include: { posts: true },
});

// Transaction
const [user, post] = await prisma.$transaction([
  prisma.user.create({ data: { email, name } }),
  prisma.post.create({ data: { title, authorId: userId } }),
]);

Configuration

Parameter	Type	Default	Description
provider	string	—	Database: postgresql, mysql, sqlite, sqlserver
url	string	—	Database connection string (from env)
directUrl	string	—	Direct connection for migrations (Neon, PlanetScale)
shadowDatabaseUrl	string	—	Shadow database for migration diffs
relationMode	string	"foreignKeys"	Relation mode: foreignKeys, prisma
previewFeatures	array	[]	Enabled preview features

Best Practices

1. Use @map and @@map for database naming conventions — keep Prisma model names as PascalCase and field names as camelCase, but map them to snake_case in the database for SQL convention compliance.

2. Add @@index for foreign key columns — Prisma doesn't create indexes on foreign keys by default; add explicit @@index([authorId]) to avoid slow queries on relation filters.

3. Use select instead of include when you need few fields — select returns only the specified fields, reducing data transfer; include returns all fields plus relations.

4. Use $transaction for operations that must be atomic — batch writes that must succeed or fail together should be wrapped in a transaction to prevent partial data inconsistencies.

5. Run prisma generate after every schema change — the Prisma Client is generated code; forgetting to regenerate after schema changes causes type mismatches and runtime errors.

Common Issues

Migration drift between dev and production — Always use prisma migrate deploy in production (not dev). The dev command resets the database if drift is detected; deploy applies pending migrations safely.

N+1 query problem with relations — Accessing related data in a loop fires a query per iteration. Use include or select to eager-load relations in the initial query.

Connection pool exhausted in serverless — Each serverless function invocation creates a new Prisma Client. Use prisma.$connect() and prisma.$disconnect() explicitly, and set connection_limit in the connection string.