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 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 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.
你需要编写一份数据契约（
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
    )
其他所有内容——查询、运行时配置、构建集成、调试、反馈——都是基于这三个步骤展开的。

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-next 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
, 
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-next.config.ts
/ 
defineConfig
, 
prisma-next 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
, 
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
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
, 
migrate status
, 
migrate diff
, 
migrate resolve
Write queries
references/queries.md
query, where, select, project, orderBy, 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
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-next init
全新项目设置、
contract infer
+ 
db sign
现有数据库适配、连接-写入-读取流程、日常命令（
contract emit
、
db init
、
db update
、
migration plan
、
migrate
、
db schema
、
db verify
）、参数
--target
/ 
--authoring
/ 
--schema-path
/ 
--probe-db
/ 
--output
编辑数据契约
references/contract.md
模式、模型、字段、属性、关联、索引、枚举、值对象（复合类型）、类型别名、命名空间（Postgres模式）、跨契约外键（跨空间FK）、多态类型（
@@discriminator
/ 
@@base
）、扩展命名空间（
pgvector.Vector(...)
、
cipherstash.EncryptedString(...)
）、
prisma-next.config.ts
/ 
defineConfig
、
prisma-next 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
、
migrate
、
migration new
、
migration show
、
db update --dry-run
、
db verify
、
db sign
、数据迁移、
dataTransform
、框架生成的
migration.ts
中的占位符标记、
MIGRATION.HASH_MISMATCH
、PN-MIG-2001未填充占位符、模式漂移
部署时审核迁移
references/migration-review.md
“将运行哪些迁移”、“部署/合并时会运行什么”、合并冲突、菱形收敛、并发迁移、迁移状态、CI的引用管理、预发布/生产环境引用、
MIGRATION.DIVERGED
、
MIGRATION.NO_MARKER
、
MIGRATION.MARKER_NOT_IN_HISTORY
、
migrate status
、
migrate diff
、
migrate resolve
编写查询
references/queries.md
查询、where、select、project、orderBy、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风格。Postgres/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、查询日志、脚本无法退出/关闭连接
提交反馈/咨询团队
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
    .
  • "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
    .
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
    。
  • “这是关于将Prisma Next集成到构建工具（Vite / Next.js / …），还是关于配置
    db.ts
    和运行时中间件？”     → 
    references/build.md
     对比 
    references/runtime.md
    。
  • “你遇到了什么错误或症状？” → 
    references/debug.md
    。
  • “你想向Prisma Next团队报告这个bug，还是提交功能请求？” → 
    references/feedback.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
    。