prisma

Prisma Cursor Rules

You are an expert Prisma developer (v5+). Follow these rules:

Schema Design

• One schema.prisma file by default. Use prismaSchemaFolder preview feature or prisma-merge for multi-file schemas in large projects
• Explicit @relation names on ambiguous relations (same model referenced twice) — Prisma will error without them, but naming all relations is clearer
• @map("snake_case") on fields, @@map("snake_case_table") on models to keep camelCase in code with snake_case in the database — this is how most teams bridge JS and PostgreSQL conventions
• @default(cuid()) or @default(uuid()) for public IDs — never expose auto-increment IDs to users (enumerable, leaks count)
• Enums for fixed value sets — they generate TypeScript types automatically and constrain at the database level

Relations

• Always define both sides of a relation — Prisma requires it for full type generation
• @relation(fields: [userId], references: [id]) with explicit fields and references every time — don't rely on implicit inference
• onDelete: Cascade only when the parent truly owns the children (e.g., delete user → delete their sessions). Use SetNull or Restrict when children can exist independently
• Optional relations (?) for nullable FKs — required relations block delete of the referenced record unless cascade is set
• Explicit join tables (model UserRole { ... }) when many-to-many needs extra fields (role, assignedAt). Implicit @relation M2M can't hold metadata

Queries

• select only the fields you need — fetching 20 columns when you need 3 wastes bandwidth and leaks data to the client
• include for eager loading relations (full objects), select on relations for partial fields — don't include then destructure, let Prisma handle the projection
• findUniqueOrThrow / findFirstOrThrow instead of findUnique + manual null checks — cleaner and throws a typed NotFoundError
• Cursor-based pagination (cursor + take) for infinite scroll and large datasets. Offset pagination (skip + take) for numbered pages — but offset is O(n) on large tables
• prisma.$transaction([]) for multi-step mutations. Use interactive transactions prisma.$transaction(async (tx) => { ... }) when steps depend on each other's results
• Batch operations: createMany, updateMany, deleteMany are single SQL statements — don't loop create() for bulk inserts