prisma-8

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma Next (Prisma 8)

Prisma Next（Prisma 8）

Edit your data contract. Prisma handles the rest.

Prisma 8 moves fast, and your training data about it is very likely outdated. This skill ships inside the installed Prisma packages, so it describes the exact version this project has — treat it and its reference files as the source of truth, over anything you remember about Prisma. The

metadata.library_version

in this file's frontmatter is the version it was published with; if it does not match the project's installed Prisma packages, run

prisma skills sync

and re-read.

Prisma Next is a contract-first data layer. This skill routes every Prisma Next task to the right reference file — open the reference before writing code; do not answer from this file alone.

编辑你的数据契约。其余工作由Prisma处理。

Prisma 8更新迭代很快，你所了解的相关知识很可能已经过时。此技能随已安装的Prisma包一同发布，因此它描述的是当前项目所安装的精确版本——请将本指南及其参考文件视为权威来源，而非你记忆中关于Prisma的内容。本文件前置元数据中的

metadata.library_version

是其发布时的版本；如果它与项目中已安装的Prisma包版本不匹配，请运行

prisma skills sync

后重新阅读。

Prisma Next是一款契约优先的数据层工具。此技能会将每一项Prisma Next任务引导至对应的参考文件——在编写代码前请先打开参考文件；不要仅依靠本文件作答。

The canonical model (one paragraph)

规范模型（概述）

You author a data contract (a

contract.prisma

file, or a TypeScript builder). The framework emits machine-readable artifacts (

contract.json

contract.d.ts

) and gives you two runtime surfaces on SQL targets: a typed SQL query builder (

db.sql.<ns>.<table>

) and a typed ORM client (

db.orm.<ns>.<Model>

). On MongoDB targets only the ORM lane exists, and its keys are collection storage names (

db.orm.users

) rather than PSL model names —

references/queries.md

§ MongoDB ORM addressing covers the rule. Migrations are planned from the contract diff; you review them, optionally edit the

migration.ts

for data transforms, and apply.

Three steps the user does:

Edit your data contract. (
```
references/contract.md
```
)
The system plans the migrations for you. (
```
references/migrations.md
```
)
If you need data migrations, you edit
migration.ts
and execute it. (
```
references/migrations.md
```
)

Everything else — queries, runtime wiring, build integration, debugging, feedback — sits on top of those three.

One cross-cutting migration fact:

migration plan

does not chain from the newest migration on disk. Its origin is

--from

, else the

db

ref, else an empty database — so a project with no ref keeps planning from scratch. Over existing migrations the CLI refuses that (

MIGRATION.PLAN_ORIGIN_UNKNOWN

) instead of writing a full-create package; choose the exit that matches your intent rather than reflexively passing

--from @empty

references/migration-model.md

§ The trap explains which to choose.

你需要编写一份数据契约（一个

contract.prisma

文件，或使用TypeScript构建器）。框架会生成机器可读的产物（

contract.json

、

contract.d.ts

），并为SQL目标提供两个运行时接口：一个类型化SQL查询构建器（

db.sql.<ns>.<table>

）和一个类型化ORM客户端（

db.orm.<ns>.<Model>

）。对于MongoDB目标，仅提供ORM接口，且其键为集合存储名称（

db.orm.users

）而非PSL模型名称——详情请参考

references/queries.md

中的MongoDB ORM寻址章节。迁移操作会根据契约差异进行规划；你可以审查这些迁移，选择性编辑

migration.ts

以进行数据转换，然后执行迁移。

用户需要完成的三个步骤：

编辑你的数据契约。（
```
references/contract.md
```
）
系统会为你规划迁移方案。（
```
references/migrations.md
```
）
如果需要数据迁移，编辑
migration.ts
并执行。（
```
references/migrations.md
```
）

其他所有操作——查询、运行时配置、构建集成、调试、反馈——都建立在这三个步骤之上。

一个关于迁移的重要跨领域事实：

migration plan

不会从磁盘上最新的迁移文件开始链式生成。它的起点是

--from

参数指定的版本，否则是

db

引用，再否则是空数据库——因此没有引用的项目会始终从头开始规划。对于已存在迁移文件的项目，CLI会拒绝这种行为（错误码

MIGRATION.PLAN_ORIGIN_UNKNOWN

），而非生成完整的创建包；请选择符合你意图的退出方式，而非习惯性地传递

--from @empty

参数。

references/migration-model.md

中的陷阱章节解释了该如何选择。

Routing table

路由表

Open the reference whose triggers match the task. If more than one matches, open each — they are written to compose.

Task	Reference	Triggers
Adopt / set up / first steps	`references/quickstart.md`	new project, existing database, "what can I do with Prisma Next", "where do I start", "just ran createprisma", `npx create-prisma` , first steps, first query, `prisma orm init` greenfield setup, `contract infer` + `db sign` brownfield adoption, connect-write-read first arc, day-to-day commands ( `contract emit` , `db init` , `db update` , `migration plan` , `db migrate` , `db schema` , `db verify` ), flags `--target` / `--authoring` / `--schema-path` / `--probe-db` / `--output`
Edit the data contract	`references/contract.md`	schema, models, fields, attributes, relations, indexes, enums, value objects (composite types), type aliases, namespaces (Postgres schemas), cross-contract foreign keys (cross-space FK), polymorphic types ( `@@discriminator` / `@@base` ), extension namespaces ( `pgvector.Vector(...)` , `cipherstash.EncryptedString(...)` ), `prisma.config.ts` / `defineConfig` , `prisma contract emit` , PSL, `contract.prisma` , `contract.ts` , `contract.json` , `contract.d.ts` , `@internal/postgres/config` , `@internal/postgres/contract-builder` , `@internal/mongo/config` , `extensions:` , pgvector, cipherstash, postgis, paradedb, `@@control` , control policy (managed / tolerated / external / observed), soft delete, validations, callbacks
Author migrations	`references/migrations.md`	`db update` vs `migration plan` , `db migrate` , `migration new` , `migration show` , `db update --dry-run` , `db verify` , `db sign` , data migration, `dataTransform` , placeholder sentinels in framework-rendered `migration.ts` , `MIGRATION.HASH_MISMATCH` , PN-MIG-2001 unfilled placeholder, schema drift
Migration graph, refs, plan origin	`references/migration-model.md`	migration graph, refs, `migration ref set` / `list` / `delete` , the `db` ref, `--advance-ref` , `migration plan --from` , `from: (baseline)` in plan output, greenfield / from-scratch plan, baseline, first migration before deploy (Composer / CD-managed databases), chaining migrations, retrofitting migrations onto an existing database, `MIGRATION.HASH_NOT_IN_GRAPH` , `MIGRATION.PATH_UNREACHABLE` at plan/chain time
Review migrations on deploy	`references/migration-review.md`	"what migrations are going to run", "what runs on deploy / merge", merge conflict, diamond convergence, concurrent migrations, migration status, ref management for CI, staging / production environment refs, `MIGRATION.DIVERGED` , `MIGRATION.NO_MARKER` , `MIGRATION.MARKER_NOT_IN_HISTORY` , `db migrate status` , `db migrate diff` , `db migrate resolve`
Write queries	`references/queries.md`	query, where, select, project, orderBy, limit, offset, take, skip, include, lookup, first, all, count, aggregate, groupBy, create, update, delete, upsert, returning, transaction, `db.orm` , `db.sql` , `db.query.from(...)` (Mongo pipeline), namespace-aware accessors, `.all()` Thenable, single-use iterators ( `RUNTIME.ITERATOR_CONSUMED` ), target-declared aggregate types ( `count` , integer `sum` , and integer `avg` are `number` ; `count` and integer `sum` throw outside ±(2^53 − 1) rather than round, while `avg` is a fraction already and carries no guard; `countBigInt` / `sumBigInt` / `avgDecimal` are the lossless forms, `avgDecimal` on PostgreSQL only), drizzle-style, kysely-style. Postgres/SQLite specifics: `references/queries-postgres.md` ; Mongo specifics: `references/queries-mongo.md`
Wire the runtime	`references/runtime.md`	`db.ts` , `postgres<Contract>(...)` / `sqlite<Contract>(...)` / `mongo<Contract>(...)` façades, middleware composition (telemetry, lints, budgets), `DATABASE_URL` , `.env` , connection pool / `poolOptions` , dev vs prod config, transactions, read replicas, multi-database, script won't exit / hangs, `db.close` / `pool.end` , `await using` / `[Symbol.asyncDispose]`
Build-tool integration	`references/build.md`	Vite plugin ( `@internal/vite-plugin-contract-emit` , Vite 7/8), `vite.config.ts` , contract emit on save, HMR / dev server, Next.js / Webpack / esbuild / Rollup / Turbopack (named gaps, not fabricated)
Supabase	`references/supabase.md`	`@internal/extension-supabase` , RLS, row level security, policies ( `policy_select` / `policy_update` / `@@rls` , `auth.uid()` ), role binding ( `asUser(jwt)` / `asAnon()` / `asServiceRole()` ), `auth.users` , cross-space FKs to `supabase:auth.AuthUser` , JWT / JWKS ( `SUPABASE_JWKS_URL` , `SUPABASE_JWT_SECRET` ), `SUPABASE.JWT_INVALID` , `SUPABASE.CONFIG_INVALID` , `RoleBoundDb` , session pooler
Debug an error	`references/debug.md`	any structured error envelope (code, domain, severity, why, fix, meta), emit failed, query won't typecheck, query crashed, migration won't apply, `MIGRATION.HASH_MISMATCH` , `BUDGET.ROWS_EXCEEDED` , `BUDGET.TIME_EXCEEDED` , `RUNTIME.ABORTED` , `PLAN.HASH_MISMATCH` , `CONTRACT.MARKER_MISSING` , PN-RUN-/ PN-MIG- / PN-CLI-/ PN-SCHEMA- codes, drift, capability missing, planner conflict, EXPLAIN, query log, script won't exit / close connection
Upgrade Prisma in an app	`references/upgrade-app.md`	"upgrade Prisma", "upgrade Prisma Next", "bump Prisma Next", "move to Prisma Next X.Y", `@internal/` version bump in an application, per-transition upgrade instructions in `upgrading/app/upgrades/` , extension-pin pre-flight, `PN-UPGRADE-`
Upgrade Prisma in an extension	`references/upgrade-extension.md`	the same request in a package that is a Prisma extension ( `@internal/contract` / SPI dependency, `^@.*/extension-` name), `prisma-8-check-pins` , exact-pin rule, per-transition instructions in `upgrading/extension/upgrades/`
File feedback / ask the team	`references/feedback.md`	bug report, file an issue, feature request, missing feature, capability gap, "this is broken", surprising behaviour, Q&A / design discussion, ask the Prisma team, Prisma Discord (pris.ly/discord), extension-author questions

打开与任务触发条件匹配的参考文件。如果有多个匹配项，请依次打开——这些文件的内容是互补的。

任务	参考文件	触发条件
采用/设置/初始步骤	`references/quickstart.md`	新项目、现有数据库、“我可以用Prisma Next做什么”、“我从哪里开始”、“刚运行createprisma”、 `npx create-prisma` 、初始步骤、首次查询、 `prisma orm init` 从零搭建、 `contract infer` + `db sign` 现有数据库适配、连接-写入-读取流程、日常命令（ `contract emit` 、 `db init` 、 `db update` 、 `migration plan` 、 `db migrate` 、 `db schema` 、 `db verify` ）、参数 `--target` / `--authoring` / `--schema-path` / `--probe-db` / `--output`
编辑数据契约	`references/contract.md`	schema、模型、字段、属性、关联关系、索引、枚举、值对象（复合类型）、类型别名、命名空间（Postgres模式）、跨契约外键（跨空间FK）、多态类型（ `@@discriminator` / `@@base` ）、扩展命名空间（ `pgvector.Vector(...)` 、 `cipherstash.EncryptedString(...)` ）、 `prisma.config.ts` / `defineConfig` 、 `prisma contract emit` 、PSL、 `contract.prisma` 、 `contract.ts` 、 `contract.json` 、 `contract.d.ts` 、 `@internal/postgres/config` 、 `@internal/postgres/contract-builder` 、 `@internal/mongo/config` 、 `extensions:` 、pgvector、cipherstash、postgis、paradedb、 `@@control` 、控制策略（managed / tolerated / external / observed）、软删除、验证、回调
编写迁移脚本	`references/migrations.md`	`db update` 对比 `migration plan` 、 `db migrate` 、 `migration new` 、 `migration show` 、 `db update --dry-run` 、 `db verify` 、 `db sign` 、数据迁移、 `dataTransform` 、框架生成的 `migration.ts` 中的占位符标记、 `MIGRATION.HASH_MISMATCH` 、PN-MIG-2001未填充占位符、schema漂移
迁移图、引用、规划起点	`references/migration-model.md`	迁移图、引用、 `migration ref set` / `list` / `delete` 、 `db` 引用、 `--advance-ref` 、 `migration plan --from` 、规划输出中的 `from: (baseline)` 、从零开始规划、基线、部署前的首次迁移（Composer / CD管理的数据库）、链式迁移、为现有数据库添加迁移、 `MIGRATION.HASH_NOT_IN_GRAPH` 、规划/链式生成时的 `MIGRATION.PATH_UNREACHABLE`
部署时审查迁移	`references/migration-review.md`	“将要执行哪些迁移”、“部署/合并时会运行什么”、合并冲突、菱形收敛、并发迁移、迁移状态、CI环境的引用管理、预发布/生产环境引用、 `MIGRATION.DIVERGED` 、 `MIGRATION.NO_MARKER` 、 `MIGRATION.MARKER_NOT_IN_HISTORY` 、 `db migrate status` 、 `db migrate diff` 、 `db migrate resolve`
编写查询语句	`references/queries.md`	查询、where、select、project、orderBy、limit、offset、take、skip、include、lookup、first、all、count、aggregate、groupBy、create、update、delete、upsert、returning、事务、 `db.orm` 、 `db.sql` 、 `db.query.from(...)` （Mongo管道）、支持命名空间的访问器、 `.all()` Thenable、单次迭代器（ `RUNTIME.ITERATOR_CONSUMED` ）、目标声明的聚合类型（ `count` 、整数 `sum` 和整数 `avg` 为 `number` 类型； `count` 和整数 `sum` 超出±(2^53 − 1)范围时会抛出错误而非四舍五入，而 `avg` 本身是分数，无保护机制； `countBigInt` / `sumBigInt` / `avgDecimal` 是无损形式， `avgDecimal` 仅支持PostgreSQL）、drizzle风格、kysely风格。PostgreSQL/SQLite特定内容： `references/queries-postgres.md` ；Mongo特定内容： `references/queries-mongo.md`
配置运行时	`references/runtime.md`	`db.ts` 、 `postgres<Contract>(...)` / `sqlite<Contract>(...)` / `mongo<Contract>(...)` 外观类、中间件组合（遥测、检查、预算）、 `DATABASE_URL` 、 `.env` 、连接池 / `poolOptions` 、开发与生产环境配置、事务、只读副本、多数据库、脚本无法退出/挂起、 `db.close` / `pool.end` 、 `await using` / `[Symbol.asyncDispose]`
构建工具集成	`references/build.md`	Vite插件（ `@internal/vite-plugin-contract-emit` 、Vite 7/8）、 `vite.config.ts` 、保存时生成契约、HMR / 开发服务器、Next.js / Webpack / esbuild / Rollup / Turbopack（注明未支持项，非虚构）
Supabase	`references/supabase.md`	`@internal/extension-supabase` 、RLS、行级安全、策略（ `policy_select` / `policy_update` / `@@rls` 、 `auth.uid()` ）、角色绑定（ `asUser(jwt)` / `asAnon()` / `asServiceRole()` ）、 `auth.users` 、跨空间外键关联 `supabase:auth.AuthUser` 、JWT / JWKS（ `SUPABASE_JWKS_URL` 、 `SUPABASE_JWT_SECRET` ）、 `SUPABASE.JWT_INVALID` 、 `SUPABASE.CONFIG_INVALID` 、 `RoleBoundDb` 、会话池
调试错误	`references/debug.md`	任何结构化错误包（代码、领域、严重程度、原因、修复方案、元数据）、生成失败、查询无法通过类型检查、查询崩溃、迁移无法执行、 `MIGRATION.HASH_MISMATCH` 、 `BUDGET.ROWS_EXCEEDED` 、 `BUDGET.TIME_EXCEEDED` 、 `RUNTIME.ABORTED` 、 `PLAN.HASH_MISMATCH` 、 `CONTRACT.MARKER_MISSING` 、PN-RUN-/ PN-MIG- / PN-CLI-/ PN-SCHEMA- 错误码、漂移、功能缺失、规划冲突、EXPLAIN、查询日志、脚本无法退出/关闭连接
在应用中升级Prisma	`references/upgrade-app.md`	“升级Prisma”、“升级Prisma Next”、“更新Prisma Next版本”、“迁移至Prisma Next X.Y”、应用中 `@internal/` 版本更新、 `upgrading/app/upgrades/` 中的版本迁移说明、扩展包锁定预检查、 `PN-UPGRADE-`
在扩展包中升级Prisma	`references/upgrade-extension.md`	在Prisma扩展包（依赖 `@internal/contract` / SPI、名称包含 `^@.*/extension-` ）中执行上述升级操作、 `prisma-8-check-pins` 、精确锁定规则、 `upgrading/extension/upgrades/` 中的版本迁移说明
提交反馈/咨询团队	`references/feedback.md`	错误报告、提交Issue、功能请求、功能缺失、功能缺口、“这部分坏了”、意外行为、问答/设计讨论、咨询Prisma团队、Prisma Discord（pris.ly/discord）、扩展包开发者问题

Routing rules

路由规则

If the task clearly matches a row, open that reference directly without asking.

For a vague prompt, ask one disambiguating question. Pick from:

"Are you new to Prisma Next and asking what you can do with it, or where to start?" →
```
references/quickstart.md
```
(first-touch orientation path).
"Do you want to set up a new Prisma Next project, or wire it into an existing database?" →
```
references/quickstart.md
```
.
"Do you want to edit your data contract (add a model / field / relation), or work with the database (migrations, queries)?" →
```
references/contract.md
```
vs the others.
"Is this about authoring a migration, or about reviewing what's going to run on deploy?" →
```
references/migrations.md
```
vs
```
references/migration-review.md
```
. If it's about where a plan starts, refs, or an unexpected from-scratch plan →
```
references/migration-model.md
```
.
"Is this about wiring Prisma Next into your build tool (Vite / Next.js / …), or about wiring
db.ts
and middleware at runtime?" →
```
references/build.md
```
vs
```
references/runtime.md
```
.
"What error or symptom are you seeing?" →
```
references/debug.md
```
.
"Do you want to report this as a bug to the Prisma Next team, or is this a feature request?" →
```
references/feedback.md
```
.
"Is the project you want to upgrade an application, or a Prisma extension package?" →
```
references/upgrade-app.md
```
vs
```
references/upgrade-extension.md
```
.

If you still can't tell which reference applies, ask the user what they want to do. Do not guess.

如果任务明确匹配某一行，请直接打开对应的参考文件，无需询问。

对于模糊的请求，请提出一个明确的问题。可选问题如下：

“你是刚接触Prisma Next，想了解它的功能或入门方法吗？” →
```
references/quickstart.md
```
（首次接触的引导路径）。
“你想要搭建一个新的Prisma Next项目，还是将其接入现有的数据库？” →
```
references/quickstart.md
```
。
“你想要编辑数据契约（添加模型/字段/关联关系），还是进行数据库相关操作（迁移、查询）？” →
```
references/contract.md
```
或其他对应文件。
“这是关于编写迁移脚本，还是关于审查部署时将要执行的内容？” →
```
references/migrations.md
```
对比
```
references/migration-review.md
```
。如果是关于规划起点、引用或意外的从头规划问题 →
```
references/migration-model.md
```
。
“这是关于将Prisma Next接入构建工具（Vite / Next.js / …），还是关于配置
db.ts
和运行时中间件？” →
```
references/build.md
```
对比
```
references/runtime.md
```
。
“你遇到了什么错误或症状？” →
```
references/debug.md
```
。
“你想要向Prisma Next团队提交错误报告，还是提出功能请求？” →
```
references/feedback.md
```
。
“你想要升级的项目是应用，还是Prisma扩展包？” →
```
references/upgrade-app.md
```
对比
```
references/upgrade-extension.md
```
。

如果仍然无法确定适用的参考文件，请询问用户具体想要做什么。不要猜测。

Checklist

检查清单

If the task matches a routing-table row, open that reference before writing code.
If the prompt is vague, ask one disambiguating question.
Do not attempt to answer from this file alone — the references carry the verified tool surface.
If the user describes a missing feature or a misbehaviour they want fixed, open
```
references/feedback.md
```
.

如果任务匹配路由表中的某一行，请在编写代码前打开对应的参考文件。
如果请求模糊，请提出一个明确的问题。
不要仅依靠本文件作答——参考文件包含经过验证的工具接口信息。
如果用户描述了缺失的功能或需要修复的异常行为，请打开
```
references/feedback.md
```
。