prisma-7

Covers Prisma 7's Rust-free TypeScript ORM: the v6→v7 breaking changes (provider renamed `prisma-client-js` → `prisma-client`, output path now REQUIRED, import moves from `@prisma/client` to the generated path, database driver adapters now required — e.g. `@prisma/adapter-pg` for PostgreSQL — and config moved to a TS config file — `prisma7.config.ts` from 7.10 (`prisma.config.*` still read as fallback), `prisma.config.ts` on 7.0–7.9), schema modeling, CRUD/relations/filtering/pagination/transactions, TypedSQL for type-safe raw queries, and the Omit API for excluding sensitive fields.

Also spans migrations (baselining, shadow database, squashing, zero-downtime), performance (N+1 detection, connection pooling, Accelerate), security (SQL injection prevention, row-level security, encryption), per-database guides (PostgreSQL, MySQL, SQLite, CockroachDB, Turso — MongoDB unsupported in all Prisma 7.x releases through 7.10; stay on 6.19), framework integrations (Next.js, Astro, SvelteKit, Remix, and more), and deployment across Vercel/Netlify/Railway/AWS Lambda/Cloudflare Workers/Docker. Includes SOLID-compliant TypeScript interface references for schema design. Does not cover Better Auth's own database adapter configuration in depth (better-auth) — this skill is the ORM layer itself.

Prisma 7 ORM

Rust-free TypeScript ORM with 90% smaller bundles and 3x faster queries.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing schema and database patterns
2. fuse-ai-pilot:research-expert - Verify latest Prisma 7 docs via Context7/Exa
3. mcp__context7__query-docs - Check breaking changes and migration guide

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

When to Use

• Database access in Next.js 16 applications
• Type-safe queries with full TypeScript inference
• Schema-first database modeling and migrations
• Complex queries requiring TypedSQL
• Excluding sensitive fields with Omit API

Why Prisma 7

Feature	Benefit
Rust-free client	90% smaller bundles (14MB → 1.6MB)
Query performance	Up to 3x faster on large datasets
ESM-first	Native ES modules, modern architecture
TypedSQL	Type-safe raw SQL queries
Omit API	Exclude sensitive fields globally
Driver adapters	Direct database driver integration

---

Breaking Changes from v6

Critical Migration Points

Change	v6	v7
Provider	prisma-client-js	prisma-client
Output path	Optional	REQUIRED
Import	@prisma/client	./generated/prisma/client
Drivers	Built-in	Adapter required
Config	Schema only	prisma7.config.ts (7.10+, falls back to prisma.config.*); prisma.config.ts (7.0–7.9) — edit the file prisma init created

Required Schema Changes

Provider must be prisma-client with explicit output path. No more generation to node_modules.

Driver Adapters Required

PostgreSQL requires @prisma/adapter-pg, MySQL requires @prisma/adapter-mariadb, SQLite requires @prisma/adapter-better-sqlite3.

Notable 7.x Minor Releases (current stable: 7.10.0)

Version	Change
7.4	Query plan caching in Prisma Client; partialIndexes preview feature (@@index(..., where: raw("...")))
7.5	Nested transaction rollbacks via savepoints
7.6	prisma postgres link; @prisma/adapter-pg accepts a connection string directly
7.7	prisma bootstrap command
7.8	queryPlanCacheMaxSize option on PrismaClient (0 disables the cache)
7.9	CLI tab completions; AI-agent safety checks extended to db push --accept-data-loss; TypeScript perf regression from 7.0 fixed
7.10	Prisma Studio bound to 127.0.0.1 with origin checks; @prisma/adapter-mariadb accepts an existing pool

Prisma 8 is in release candidate only (npm latest tag points to 8.0.0-rc.*) — pin prisma@7 / @prisma/client@7 for stable installs.

---

SOLID Architecture

Module Structure

Database code organized in modules/cores/db/:

• modules/cores/db/prisma.ts - Singleton PrismaClient
• modules/cores/db/generated/ - Generated client
• prisma/schema.prisma - Schema definition
• prisma/migrations/ - Migration history
• prisma7.config.ts - Prisma configuration (7.0–7.9: prisma.config.ts)

File Organization

File	Purpose
prisma.ts	Singleton client
schema.prisma	Models, relations
seed.ts	Database seeding

---

Key Concepts

Singleton Pattern (Next.js)

Prevent multiple PrismaClient instances during hot-reload. Use globalThis to cache instance in development.

Output Path

Generated client goes to custom path, not node_modules. Import from generated folder.

Driver Adapters

Direct database driver integration for better performance and control. Configure connection pooling at driver level.

TypedSQL

Write raw SQL with full type safety. Results are typed based on query.

Omit API

Exclude fields globally or per-query. Perfect for passwords and sensitive data.

---

Reference Guide (130 files)

Core Setup

Need	Reference
Initial setup	installation.md
PrismaClient singleton	client.md
Client API methods	client-api.md
Configuration	prisma-config.md
CLI commands	cli-reference.md
Editor setup	editor-setup.md

Schema & Modeling

Need	Reference
Schema design	schema.md
Schema syntax	schema-reference.md
Data modeling	data-modeling.md
Field attributes	field-attributes.md
Model attributes	model-attributes.md
Enums	enums.md
Default values	default-values.md
Composite types	composite-types.md
Scalar lists/arrays	scalar-lists.md
Referential actions	referential-actions.md

Queries & Operations

Need	Reference
CRUD operations	queries.md
Relations	relations.md
Filtering	filtering.md
Sorting	sorting.md
Select vs Include	select-include.md
Pagination (cursor)	pagination-cursor.md
Pagination (offset)	pagination-offset.md
Distinct	distinct.md
Count & exists	count-exists.md
Case sensitivity	case-sensitivity.md
Aggregations	aggregations.md
Transactions	transactions.md

Advanced Queries

Need	Reference
TypedSQL	typedsql.md
Raw queries	raw-queries.md
JSON fields	json-fields.md
Full-text search	full-text-search.md
Views	views.md
Stored procedures	stored-procedures.md
Triggers	triggers.md
Constraints	constraints.md
Advanced indexes	indexes-advanced.md

Migrations

Need	Reference
Migration workflow	migrations.md
Seeding	seeding.md
Baselining	baselining.md
Shadow database	shadow-database.md
Migration history	migration-history.md
Squashing	squashing.md
Hotfixing	hotfixing.md
Down migrations	down-migrations.md
Data migrations	data-migrations.md
Zero-downtime	zero-downtime.md

Performance

Need	Reference
Optimization	optimization.md
Query optimization	query-optimization.md
N+1 problem	n-plus-one.md
Batching	batching.md
Lazy loading	lazy-loading.md
Caching strategies	caching-strategies.md
Connection limits	connection-limits.md
Cold starts	cold-starts.md
Bundle size	bundle-size.md
Accelerate	accelerate.md
Connection pooling	connection-pooling.md

Security

Need	Reference
Connection URLs	connection-urls.md
Environment variables	environment-variables.md
SSL/TLS	ssl-tls.md
SQL injection	sql-injection.md
Row-level security	row-level-security.md
Encryption	encryption.md
Audit logging	audit-logging.md
GDPR compliance	gdpr-compliance.md

Databases

Need	Reference
PostgreSQL	postgresql.md
MySQL	mysql.md
SQLite	sqlite.md
MongoDB (deprecated)	mongodb.md
CockroachDB	cockroachdb.md
PlanetScale	planetscale.md
Supabase	supabase.md
Neon	neon.md
Turso	turso.md

Extensions & Integrations

Need	Reference
Extensions	extensions.md
Driver adapters	driver-adapters.md
Omit API	omit-api.md
Middleware (deprecated)	middleware.md
Soft delete	soft-delete.md
Read replicas	read-replicas.md
Multi-database	multi-database.md
Multi-schema	multi-schema.md

Framework Integrations

Need	Reference
Next.js	nextjs-integration.md
Astro	astro.md
Nuxt	nuxt.md
SvelteKit	sveltekit.md
SolidStart	solidstart.md
Remix	remix.md
React Router	react-router.md
Hono	hono.md
Express	express.md

Auth Integrations

Need	Reference
Clerk	clerk.md
Auth.js	authjs.md
Better Auth	betterauth.md
Permit.io	permit-io.md

Deployment

Need	Reference
Deployment guide	deployment.md
Vercel	vercel.md
Netlify	netlify.md
Railway	railway.md
Render	render.md
Fly.io	flyio.md
AWS Lambda	aws-lambda.md
Cloudflare Workers	cloudflare-workers.md
Docker	docker.md
Heroku	heroku.md
Deno Deploy	deno-deploy.md

Tooling

Need	Reference
VS Code	vscode.md
GitHub Copilot	github-copilot.md
Tabnine	tabnine.md
SafeQL	safeql.md
Prisma AI	prisma-ai.md
MCP Server	mcp-server.md
Turborepo	turborepo.md
pnpm workspaces	pnpm-workspaces.md

Monitoring

Need	Reference
Error handling	error-handling.md
Error codes	error-codes.md
Logging	logging.md
OpenTelemetry	opentelemetry.md
DataDog	datadog.md
Studio	studio.md
Testing	testing.md

ORM Comparisons

Need	Reference
vs TypeORM	vs-typeorm.md
vs Sequelize	vs-sequelize.md
vs Drizzle	vs-drizzle.md
vs Mongoose	vs-mongoose.md
vs Kysely	vs-kysely.md

Migration Guides

Need	Reference
From TypeORM	migrate-from-typeorm.md
From Sequelize	migrate-from-sequelize.md
From Drizzle	migrate-from-drizzle.md

TypeScript Interfaces (SOLID)

references/interfaces/ holds SOLID-compliant type definitions for Prisma 7 schema design, separated from implementation. Load when writing or reviewing typed schema code:

Need	Reference
Overview of all interface files	interfaces/INDEX.md
Schema types: GeneratorConfig, ModelDefinition, FieldAttribute, EnumDefinition	interfaces/schema.types.md
Data modeling types: normalization, cardinality	interfaces/data-modeling.types.md
Enum types: value definitions, status/role patterns	interfaces/enums.types.md
Field attribute types: identity, unique, default, mapping	interfaces/field-attributes.types.md
Model attribute types: composite keys, composite indexes	interfaces/model-attributes.types.md
Relation types: one-to-one, referential actions, cascade	interfaces/relations.types.md
Migration types: workflow, deploy, seeding	interfaces/migrations.types.md

---

Best Practices

1. Singleton in Next.js - Cache PrismaClient in globalThis
2. Output path required - Never generate to node_modules
3. Driver adapters - Use native drivers for better performance
4. Omit sensitive fields - Configure global omit for passwords
5. TypedSQL for complex - Use for queries Prisma can't express
6. Index verification - Check query plans for N+1 issues

---

Forbidden Patterns

Pattern	Reason	Alternative
Import from @prisma/client	v7 requires generated path	Import from ./generated/prisma/client
prisma-client-js provider	Deprecated in v7	Use prisma-client
No output path	Required in v7	Set output in generator
MongoDB	Not supported in v7.x (7.0-7.10)	Stay on Prisma 6.19
url in datasource	Deprecated	Use the config file (prisma7.config.ts on 7.10+, prisma.config.ts on 7.0–7.9)