prisma-7

涵盖 Prisma 7 这款无需 Rust 的 TypeScript ORM：v6 → v7 的破坏性变更（provider 从 `prisma-client-js` 重命名为 `prisma-client`、现在必须指定 output path、导入路径从 `@prisma/client` 改为生成文件所在路径、现在必须使用数据库驱动适配器——例如，PostgreSQL 使用 `@prisma/adapter-pg`，以及配置迁移到 TS 配置文件——7.10 起使用 `prisma7.config.ts`（仍会读取 `prisma.config.*` 作为回退），7.0–7.9 使用 `prisma.config.ts`）、schema 建模、CRUD / 关系 / 筛选 / 分页 / 事务、用于类型安全原始查询的 TypedSQL，以及用于排除敏感字段的 Omit API。

还涵盖迁移（基线设置、影子数据库、压缩迁移、零停机）、性能（N+1 检测、连接池、Accelerate）、安全（SQL 注入防护、行级安全、加密）、各数据库指南（PostgreSQL、MySQL、SQLite、CockroachDB、Turso——截至 7.10 的所有 Prisma 7.x 版本均不支持 MongoDB；请继续使用 6.19）、框架集成（Next.js、Astro、SvelteKit、Remix 等），以及在 Vercel / Netlify / Railway / AWS Lambda / Cloudflare Workers / Docker 上的部署。包含符合 SOLID 原则的 TypeScript 接口参考，用于 schema 设计。不会深入介绍 Better Auth 自身的数据库适配器配置（better-auth）——此技能仅涉及 ORM 层。

Prisma 7 ORM

无需 Rust 的 TypeScript ORM，打包体积缩小 90%，查询速度提升 3 倍。

Agent 工作流（必须遵循）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 各调用一次 Agent，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有 schema 和数据库模式
2. fuse-ai-pilot:research-expert - 通过 Context7 / Exa 核实最新 Prisma 7 文档
3. mcp__context7__query-docs - 检查破坏性变更和迁移指南

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

适用场景

• 在 Next.js 16 应用中访问数据库
• 使用完整 TypeScript 类型推断的类型安全查询
• 以 schema 为先的数据库建模和迁移
• 需要 TypedSQL 的复杂查询
• 使用 Omit API 排除敏感字段

为什么选择 Prisma 7

功能	优势
无 Rust 客户端	打包体积缩小 90%（14MB → 1.6MB）
查询性能	大型数据集上的速度最高可提升 3 倍
ESM 优先	原生 ES 模块，现代化架构
TypedSQL	类型安全的原始 SQL 查询
Omit API	全局排除敏感字段
驱动适配器	直接集成数据库驱动

---

v6 的破坏性变更

关键迁移点

变更	v6	v7
Provider	prisma-client-js	prisma-client
Output path	可选	必须指定
导入	@prisma/client	./generated/prisma/client
驱动	内置	必须使用适配器
配置	仅 schema	prisma7.config.ts（7.10 起，回退时使用 prisma.config.*）；prisma.config.ts（7.0–7.9）——编辑 prisma init 创建的文件

必需的 Schema 变更

Provider 必须设为 prisma-client，并显式指定 output path。不再生成到 node_modules。

必须使用驱动适配器

PostgreSQL 必须使用 @prisma/adapter-pg，MySQL 必须使用 @prisma/adapter-mariadb，SQLite 必须使用 @prisma/adapter-better-sqlite3。

值得关注的 7.x 次要版本发布（当前稳定版本：7.10.0）

版本	变更
7.4	Prisma Client 中的查询计划缓存；partialIndexes 预览功能（@@index(..., where: raw("..."))）
7.5	通过保存点回滚嵌套事务
7.6	prisma postgres link；@prisma/adapter-pg 可直接接受连接字符串
7.7	prisma bootstrap 命令
7.8	PrismaClient 上的 queryPlanCacheMaxSize 选项（0 可禁用缓存）
7.9	CLI 补全；AI Agent 安全检查扩展至 db push --accept-data-loss；修复了 7.0 引入的 TypeScript 性能回归
7.10	Prisma Studio 绑定到 127.0.0.1 并进行来源检查；@prisma/adapter-mariadb 可接受现有连接池

Prisma 8 目前仅提供候选发布版（npm 的 latest 标签指向 8.0.0-rc.*）——稳定安装时请固定使用 prisma@7 / @prisma/client@7。

---

SOLID 架构

模块结构

数据库代码组织在 modules/cores/db/ 中：

• modules/cores/db/prisma.ts - PrismaClient 单例
• modules/cores/db/generated/ - 生成的客户端
• prisma/schema.prisma - Schema 定义
• prisma/migrations/ - 迁移历史
• prisma7.config.ts - Prisma 配置（7.0–7.9：prisma.config.ts）

文件组织

文件	用途
prisma.ts	客户端单例
schema.prisma	模型、关系
seed.ts	数据库填充

---

核心概念

单例模式（Next.js）

防止热重载时创建多个 PrismaClient 实例。在开发环境中使用 globalThis 缓存实例。

输出路径

生成的客户端会放在自定义路径，而不是 node_modules。从生成的文件夹导入。

驱动适配器

直接集成数据库驱动，以获得更好的性能和控制力。在驱动层配置连接池。

TypedSQL

编写具备完整类型安全性的原始 SQL。结果会根据查询进行类型定义。

Omit API

全局或按查询排除字段。非常适合用于密码和敏感数据。

---

参考指南（130 个文件）

核心设置

需求	参考文档
初始设置	installation.md
PrismaClient 单例	client.md
客户端 API 方法	client-api.md
配置	prisma-config.md
CLI 命令	cli-reference.md
编辑器设置	editor-setup.md

Schema 与建模

需求	参考文档
Schema 设计	schema.md
Schema 语法	schema-reference.md
数据建模	data-modeling.md
字段属性	field-attributes.md
模型属性	model-attributes.md
枚举	enums.md
默认值	default-values.md
复合类型	composite-types.md
标量列表/数组	scalar-lists.md
参照操作	referential-actions.md

查询与操作

需求	参考文档
CRUD 操作	queries.md
关系	relations.md
筛选	filtering.md
排序	sorting.md
Select 与 Include	select-include.md
分页（游标）	pagination-cursor.md
分页（偏移量）	pagination-offset.md
去重	distinct.md
计数与存在性	count-exists.md
大小写敏感性	case-sensitivity.md
聚合	aggregations.md
事务	transactions.md

高级查询

需求	参考文档
TypedSQL	typedsql.md
原始查询	raw-queries.md
JSON 字段	json-fields.md
全文搜索	full-text-search.md
视图	views.md
存储过程	stored-procedures.md
触发器	triggers.md
约束	constraints.md
高级索引	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 接口（SOLID）

references/interfaces/ 存放符合 SOLID 原则的 Prisma 7 架构类型定义，与实现分离。编写或审查类型化架构代码时，请加载这些定义：

需求	参考资料
所有接口文件概览	interfaces/INDEX.md
架构类型：GeneratorConfig、ModelDefinition、FieldAttribute、EnumDefinition	interfaces/schema.types.md
数据建模类型：规范化、基数	interfaces/data-modeling.types.md
枚举类型：值定义、状态／角色模式	interfaces/enums.types.md
字段属性类型：标识、唯一性、默认值、映射	interfaces/field-attributes.types.md
模型属性类型：复合键、复合索引	interfaces/model-attributes.types.md
关系类型：一对一、引用操作、级联	interfaces/relations.types.md
迁移类型：工作流、部署、数据填充	interfaces/migrations.types.md

---

最佳实践

1. Next.js 中的单例 - 在 globalThis 中缓存 PrismaClient
2. 必须指定输出路径 - 切勿生成到 node_modules
3. 驱动适配器 - 使用原生驱动以获得更好的性能
4. 省略敏感字段 - 配置全局省略密码
5. 复杂查询使用 TypedSQL - 用于 Prisma 无法表达的查询
6. 验证索引 - 检查查询计划，排查 N+1 问题

---

禁止的模式

模式	原因	替代方案
从 @prisma/client 导入	v7 要求使用生成路径	从 ./generated/prisma/client 导入
prisma-client-js provider	已在 v7 中弃用	使用 prisma-client
未指定输出路径	v7 中为必需项	在生成器中设置 output
MongoDB	在 v7.x（7.0-7.10）中不受支持	使用 Prisma 6.19
datasource 中的 url	已弃用	使用配置文件（7.10+ 使用 prisma7.config.ts，7.0–7.9 使用 prisma.config.ts）