Prisma Patterns
Ship safer Prisma schemas, queries, and migrations in TypeScript APIs without falling into production traps around bulk writes, transactions, and serverless connections.
Overview
Prisma Patterns is an agent skill for the Build phase that teaches production Prisma ORM patterns and critical traps for TypeScript backends.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill prisma-patternsWhat is this skill?
- Documents ID strategies (cuid, uuid, autoincrement) with clear when-to-use guidance
- Covers query optimization, pagination, transactions, soft delete, and multi-tenant filtering patterns
- Calls out non-obvious traps: updateMany/deleteMany return counts not rows, $transaction timeouts, migrate dev DB resets
- Flags @updatedAt skipping on bulk writes and serverless connection pool exhaustion
- Version-aware notes for Prisma 5.x/6.x including relationJoins row-explosion risks on deep includes
- Covers Prisma 5.x and 6.x with explicit version check step
- Documents multiple critical trap categories including updateMany, $transaction, migrate dev, @updatedAt, and serverless
Adoption & trust: 909 installs on skills.sh; 210k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are shipping a Prisma-backed API but keep hitting silent footguns—bulk writes, migrations, transactions, and serverless pools—that only fail under real traffic.
Who is it for?
Solo builders maintaining or greenfielding a TypeScript API with Prisma who want checklists before merging schema or query changes.
Skip if: Teams on non-Prisma ORMs, raw-SQL-only stacks, or projects where the database layer is already frozen and migrations are owned entirely by a DBA workflow.
When should I use this skill?
Designing or modifying Prisma schema models and relations; writing queries, transactions, or pagination; using updateMany, deleteMany, or bulk ops; running migrations; deploying to serverless; implementing soft delete or
What do I get? / Deliverables
You get schema, query, migration, and deployment patterns aligned to your Prisma version, with explicit guardrails around bulk ops, transactions, and connection limits.
- Schema and relation designs following documented ID and indexing patterns
- Query and transaction snippets with pagination and bulk-write caveats applied
- Migration and serverless connection guidance matched to detected Prisma version
Recommended Skills
Journey fit
Prisma work happens while implementing persistence layers, relations, and migration workflows during product build—not during idea research or launch distribution. Canonical shelf is backend because the skill centers on ORM schema design, query optimization, transactions, pagination, and migration behavior for TypeScript services.
How it compares
Structured ORM playbook for agent sessions—not a generic SQL tutor or a hosted database MCP connector.
Common Questions / FAQ
Who is prisma-patterns for?
Indie and solo developers building TypeScript backends with Prisma who want agent-guided patterns instead of trial-and-error in production.
When should I use prisma-patterns?
During Build when you design schemas, write queries or transactions, run migrations, use updateMany/deleteMany, or deploy Prisma to serverless environments like Vercel or Lambda.
Is prisma-patterns safe to install?
It is procedural documentation for your agent; review the Security Audits panel on this Prism page and inspect the skill package in your repo before granting shell or network access to migrations.
SKILL.md
READMESKILL.md - Prisma Patterns
# Prisma Patterns Production patterns and non-obvious traps for Prisma ORM in TypeScript backends. Tested against Prisma 5.x and 6.x. Some behaviors differ from Prisma 4. Check the Prisma version before applying version-specific patterns: ```bash npx prisma --version ``` Prisma 5 introduced `relationJoins`, which can load relations via JOIN rather than separate queries depending on query strategy and configuration. The `omit` field modifier and `prisma.$extends` Client Extensions API were also added. Note: `relationJoins` can cause row explosion on large 1:N relations or deep nested `include` — benchmark both approaches when relations may return many rows per parent. ## When to Activate - Designing or modifying Prisma schema models and relations - Writing queries, transactions, or pagination logic - Using `updateMany`, `deleteMany`, or any bulk operation - Running or planning database migrations - Deploying to serverless environments (Vercel, Lambda, Cloudflare Workers) - Implementing soft delete or multi-tenant row filtering ## Core Concepts ### ID Strategy | Strategy | Use When | Avoid When | |---|---|---| | `@default(cuid())` | Default choice — URL-safe, sortable, no collisions | Sequential IDs needed for external systems | | `@default(uuid())` | Interoperability with non-Prisma systems required | High-write tables (random UUIDs fragment B-tree indexes) | | `@default(autoincrement())` | Internal join tables, audit logs | Public-facing IDs (exposes record count) | ### Schema Defaults ```prisma model User { id String @id @default(cuid()) email String @unique // @unique already creates an index — no @@index needed name String role Role @default(USER) posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt deletedAt DateTime? @@index([createdAt]) @@index([deletedAt, createdAt]) // composite for soft-delete + sort queries } ``` - Add `@@index` on every foreign key and column used in `WHERE` or `ORDER BY`. - Declare `deletedAt DateTime?` upfront when soft delete is a foreseeable requirement — adding it later requires a migration on a live table. - `updatedAt @updatedAt` is set automatically by Prisma on `update` and `upsert` only (see Anti-Patterns for bulk update trap). ### `include` vs `select` | | `include` | `select` | |---|---|---| | Returns | All scalar fields + specified relations | Only specified fields | | Use when | You need most fields plus a relation | Hot paths, large tables, avoiding over-fetch | | Performance | May over-fetch on wide tables | Minimal payload, faster on large datasets | | Prisma 5 note | Uses JOIN by default (`relationJoins`) | Same | ```ts // include — all columns + relation const user = await prisma.user.findUnique({ where: { id }, include: { posts: { select: { id: true, title: true } } }, }); // select — explicit allowlist const user = await prisma.user.findUnique({ where: { id }, select: { id: true, email: true, name: true }, }); ``` Never return raw Prisma entities from API responses — map to response DTOs to control exposed fields: ```ts // BAD: leaks passwordHash, deletedAt, internal fields return await prisma.user.findUniqueOrThrow({ where: { id } }); // GOOD: explicit DTO mapping const user = await prisma.user.findUniqueOrThrow({ where: { id } }); return { id: user.id, name: user.name, email: user.email }; ``` ### Transaction Form Selection | Situation | Use | |---|---| | Independent operations, no inter-dependency | Array form | | Later step depends on earlier result | Interactive form | | External calls (email, HTTP) involved | Outsi