affaan-m/everything-claude-code/prisma-patterns
Claude Code and agent skill by affaan-m/everything-claude-code
- community
Checking that the SKILL.md file is still in the repository.
Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion. Use when writing a Prisma schema or query, or debugging transactions, migrations, or serverless connection limits.
Install
npx vskill@latest install affaan-m/everything-claude-code/prisma-patternsSKILL.md
The same SKILL.md was published earlier as affaan-m/everything-claude-code/prisma-patterns.
Prisma Patterns
Production patterns and non-obvious traps for Prisma ORM in TypeScript backends.
Check your version before applying patterns. The Prisma API surface has evolved across major releases:```bashnpx prisma --version```Notable API differences across versions:-relationJoinscan load relations via JOIN rather than separate queries, but may cause row explosion on large 1:N relations or deepinclude— benchmark both approaches-omitfield modifier andprisma.$extendsClient Extensions API were added- Newer installs: the package may be namedprismainstead of@prisma/client;PrismaClientmay require a driver adapter (e.g.@prisma/adapter-pg);datasource.urlmay live inprisma.config.tsinstead ofschema.prisma- CLI commands (migrate dev,migrate deploy,generate) are unchanged across versions
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
- Add
@@indexon every foreign key and column used inWHEREorORDER BY. - Declare
deletedAt DateTime?upfront when soft delete is a foreseeable requirement — adding it later requires a migration on a live table. updatedAt @updatedAtis set automatically by Prisma onupdateandupsertonly (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 |
Never return raw Prisma entities from API responses — map to response DTOs to control exposed fields:
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 | Outside transaction entirely |
PrismaClient Singleton
Each PrismaClient instance opens its own connection pool. Instantiate once.
Use Option A if your Prisma install requires an adapter argument in the PrismaClient constructor. Use Option B if new PrismaClient() works without arguments. Let the compiler tell you which is correct.
The globalThis pattern prevents duplicate instances during hot reload (Next.js, nodemon, ts-node-dev).
N+1 Problem
Loading relations inside a loop issues one query per row.
With Prisma 5+ relationJoins, the include form uses a single JOIN. On large 1:N sets this may increase result set size — benchmark both approaches if the relation can return many rows per parent.
Code Examples
Cursor Pagination (preferred for feeds and large datasets)
Fetch limit + 1 and pop — canonical way to detect hasNextPage without an extra count query. Always include a unique field (e.g. id) as a secondary orderBy to prevent unstable pagination when multiple rows share the same timestamp. Use offset pagination only when users need to jump to arbitrary pages (admin tables).
Soft Delete
Error Handling
Common codes: P2002 unique violation · P2025 not found · P2003 foreign key violation.
Catch at the service boundary and translate to domain errors. Never expose raw Prisma messages to API consumers.
Connection Pool — Serverless
Embed connection params directly in DATABASE_URL — string concatenation breaks if the URL already has query parameters (e.g. ?schema=public):
Anti-Patterns
updateMany returns a count, not records
Same applies to deleteMany — returns { count: n }, never the deleted rows.
$transaction interactive form times out after 5 seconds
migrate dev can reset the database
migrate dev detects schema drift and may prompt to reset the DB, dropping all data.
Manually editing a migration file breaks future deploys
Prisma checksums every migration file. Editing after apply causes P3006 checksum mismatch on every environment where the original already ran. Create a new migration instead.
Breaking schema changes require multi-step migration
Adding NOT NULL to an existing column or renaming a column in one migration will lock the table or drop data. Use expand-and-contract:
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/prisma-patterns/SKILL.md
Popularity
- Repository stars
- 188,111
- Repository forks
- 29,120
- Repository npm downloads, 7 days
- 1,810
- 7-day trend score
- 78
Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 21 May 2026, 6 months ago.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/affaan-m/everything-claude-code/prisma-patterns)