Home › Prisma › Prisma ORM rules

Prisma ORM rules

Cursor rules for Prisma ORM 6 with PostgreSQL: schema changes, migrations, typed queries, and transactions.

CursorPrisma

How to use

Save this as .cursor/rules/prisma.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Prisma ORM conventions
globs: ["prisma/**","src/**/*.ts"]
alwaysApply: false
---

# Prisma ORM

- The schema is `prisma/schema.prisma`. After editing it, run `npx prisma migrate dev --name <change>` (creates SQL + regenerates the client). Never edit an applied migration; add a new one.
- Production applies migrations with `npx prisma migrate deploy` only. Don't use `db push` outside prototypes.
- One shared `PrismaClient` instance (`src/lib/db.ts`), cached on `globalThis` in dev to survive hot reload.
- Select only needed fields with `select`; use `include` deliberately. Never send whole user rows (password hashes) to the client.
- Avoid N+1: load relations in one query with `include`/`select`, or batch with `findMany({ where: { id: { in: ids } } })`.
- Multi-step writes in `prisma.$transaction(async (tx) => {...})` using `tx`, not the global client.
- Paginate with `take` + `cursor` for large tables.
- Raw SQL only through tagged `$queryRaw` templates (parameterized); never `$queryRawUnsafe` with user input.
- Handle `Prisma.PrismaClientKnownRequestError` codes (`P2002` unique, `P2025` not found) and map them to domain errors.
- Add `@@index` for fields used in `where`/`orderBy` on large tables; name relations explicitly when a model has two relations to the same table.

## Don't
- Don't run `migrate reset` or anything that drops data without asking.

## Done when
`npx prisma validate`, `npx prisma migrate status`, typecheck and tests pass.