Prisma ORM

---
applyTo: "**/prisma/schema.prisma, **/*.prisma"
---

# Prisma ORM Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up the latest Prisma documentation: https://www.prisma.io/docs
- Use Prisma 5+ with TypeScript for type-safe database access
- Define schema with clear relationships and proper field types
- Use migrations for database schema changes (never modify database directly)
- Implement connection pooling for production environments
- Use Prisma Client for all database operations

**Core Principles:**

- Define models with proper relationships (one-to-one, one-to-many, many-to-many)
- Use meaningful model and field names following conventions
- Implement indexes for frequently queried fields
- Use enums for fixed sets of values
- Define default values and constraints in schema

**Schema Design:**

- Use proper data types (String, Int, DateTime, Boolean, Json, etc.)
- Implement cascade deletes with @relation(onDelete: Cascade)
- Use @unique and @id attributes appropriately
- Define composite unique constraints with @@unique
- Use @map and @@map for custom database names

**Migrations:**

- Generate migrations with `prisma migrate dev` for development
- Use `prisma migrate deploy` for production
- Review migration SQL before applying
- Never edit migration files manually
- Use migration names that describe the change

**Queries:**

- Use include and select for relation loading
- Implement pagination with skip and take
- Use where clauses with proper operators
- Implement sorting with orderBy
- Use aggregations (count, sum, avg) when needed

**Transactions:**

- Use $transaction for atomic operations
- Implement interactive transactions for complex logic
- Handle transaction failures gracefully
- Keep transactions short and focused
- Use nested writes for related data

**Performance:**

- Use connection pooling (PgBouncer for PostgreSQL)
- Implement query batching with findMany
- Use select to fetch only needed fields
- Add indexes for frequently queried fields
- Monitor query performance with Prisma logging

**Type Safety:**

- Use generated Prisma Client types
- Implement type-safe queries with proper typing
- Use Prisma.validator for input validation
- Leverage TypeScript strict mode
- Use generated types for return values

**Best Practices:**

- Initialize Prisma Client once per application lifecycle
- Use middleware for logging and soft deletes
- Implement error handling for database errors
- Use seed scripts for test data
- Keep schema.prisma as single source of truth

**Relations:**

- Define relations with proper @relation attributes
- Use relation scalar fields for foreign keys
- Implement self-relations with care
- Use implicit many-to-many relations when appropriate
- Document complex relationships with comments

**Testing:**

- Use separate test database for testing
- Reset database state between tests
- Use Prisma transactions for test isolation
- Mock Prisma Client for unit tests
- Test migrations in CI/CD pipeline

**Summary:**

> For all Prisma work, always use the fetch tool to look up the latest documentation from https://www.prisma.io/docs. Write type-safe, performant database code with proper schema design and migrations.