hjemmesidekongen/prisma-patterns

prisma-patterns

Model the domain first, then let Prisma reflect it. Schema decisions made carelessly early become expensive migrations later.

Schema Design

Define relations explicitly with @relation. Always add @@index on fields used in where, orderBy, or as FK targets. Use @@map and @map to decouple Prisma names from database names — keeps the schema clean while the DB follows conventions.

Enums in Prisma map to DB enums. Prefer them for stable, bounded sets. For extensible value sets, use a string field with application-level validation instead.

Migration Workflow

• prisma migrate dev — development: generates + applies + regenerates client. Use this locally.
• prisma migrate deploy — production: applies pending migrations only. Never generates. CI/CD safe.
• Never edit migration SQL by hand after it's been applied to any environment. Create a new migration instead.
• Baseline an existing DB with migrate diff + migrate resolve --applied before introducing Prisma to a legacy schema.

Query Optimization

Default rule: select only what you need. Use select to project specific fields rather than pulling full records. Use include only for relations actually rendered. Avoid findMany inside loops — batch with include or a single query with where: { id: { in: ids } }.

Add take and skip on any unbounded findMany. Paginate by cursor (cursor + take) for large datasets — offset pagination degrades at scale.

Raw Queries

Use $queryRaw for reads that require DB-specific syntax (window functions, CTEs, full-text search). Use $executeRaw for writes. Always use tagged template literals — never string interpolation — to prevent SQL injection. Raw results are not typed by default; cast with Prisma.sql and validate output shape.

Transactions

Use $transaction([...]) for sequential operations that must succeed together. Use the interactive transaction ($transaction(async (tx) => { ... }) for conditional logic mid-transaction. Keep transactions short — long-running transactions cause lock contention.

See references/process.md for schema patterns, seeding, Prisma Client extensions, middleware, soft deletes, multi-tenancy, and anti-patterns with fixes.