Back to Details

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:
  1. Edit your data contract. (
    references/contract.md
    )
  2. The system plans the migrations for you. (
    references/migrations.md
    )
  3. 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
以进行数据转换，然后执行迁移。
用户需要完成的三个步骤：
  1. 编辑你的数据契约。（
    references/contract.md
    ）
  2. 系统会为你规划迁移方案。（
    references/migrations.md
    ）
  3. 如果需要数据迁移，编辑
    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.
TaskReferenceTriggers
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
    。