prisma-next-quickstart

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma Next — Quickstart (Adoption)

Prisma Next — 快速入门（上手指南）

Edit your data contract. Prisma handles the rest.

This skill takes the user from zero (or near-zero) to a first working query against Prisma Next. Three paths — and they all converge on the same first arc: connect → write → read. Schema editing comes after the first arc, not before.

First-touch orientation — the user has arrived at a Prisma Next project for the first time (a scaffold tool like
```
npx createprisma
```
dropped them in, they cloned a teammate's repo, or they ran
```
prisma-next init
```
themselves and now want to make their first move) and they're asking "what can I do with Prisma Next?", "where do I start?", or "what's next?". The goal is to anchor them on the contract, get them connected to a database, round-trip one row, and let further commands surface organically.
Greenfield — new project, fresh database. User runs
```
prisma-next init
```
themselves.
```
init
```
seeds a starter contract with a sample model, so the path joins the first-touch orientation arc as soon as the database is initialised.
Brownfield-DB — existing database, no contract yet. Infer the contract from the database with
```
contract infer
```
, sign the marker with
```
db sign
```
, then write queries against one of the existing tables.

This skill does not cover migrating from another ORM (Drizzle, Prisma 6/7, Sequelize, TypeORM, Kysely, Knex, raw drivers). Those are separately-installable skills.

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

本指南将帮助用户从零（或接近零）开始，完成针对Prisma Next的首次有效查询。共有三种路径，最终都会汇聚到同一个核心流程：连接 → 写入 → 读取。编辑Schema是在完成核心流程之后，而非之前。

首次上手引导 — 用户首次接触Prisma Next项目（通过
```
npx createprisma
```
等脚手架工具生成、克隆队友的仓库，或是自行运行
```
prisma-next init
```
后，想要进行第一步操作），并提出“我能用Prisma Next做什么？”、“我该从哪里开始？”或“接下来该怎么做？”等问题。目标是让用户熟悉契约概念，连接到数据库，完成一次数据往返，并让后续命令根据需求自然呈现。
全新项目（Greenfield） — 新项目、全新数据库。用户自行运行
```
prisma-next init
```
。
```
init
```
会用示例模型初始化一个基础契约，因此在数据库初始化完成后，该路径会与首次上手引导流程汇合。
现有数据库（Brownfield-DB） — 已有数据库，但尚未配置Prisma Next契约。通过
```
contract infer
```
从数据库推导契约，使用
```
db sign
```
标记数据库，然后针对现有表编写查询。

本指南不涵盖从其他ORM（Drizzle、Prisma 6/7、Sequelize、TypeORM、Kysely、Knex、原生驱动）迁移的内容。这些属于可单独安装的技能。

When to Use

使用场景

User asks "what can I do with Prisma Next?", "what can I do next with Prisma?", "where do I start?", "what should I do first?" — and a PN project already exists on disk. First-touch orientation path below.
User just ran
```
createprisma
```
(or equivalent scaffold tool) and is asking what to do next. First-touch orientation path.
User is starting a new project and wants to use Prisma Next. Greenfield path.
User has an existing database (no PN contract) and wants to introduce PN. Brownfield-DB path.
User typed "prisma-next init", "get started with PN", "set up PN", "how do I scaffold a project". Greenfield path.
User says "I have an existing Postgres/Mongo, how do I start using PN?". Brownfield-DB path.

用户提出“我能用Prisma Next做什么？”、“我接下来能用Prisma做什么？”、“我该从哪里开始？”、“我首先应该做什么？”等问题，且本地已存在PN项目。请遵循下方的首次上手引导路径。
用户刚运行
```
createprisma
```
（或类似脚手架工具），询问下一步操作。请遵循首次上手引导路径。
用户想要启动新项目并使用Prisma Next。请遵循全新项目路径。
用户已有数据库（无PN契约），想要引入Prisma Next。请遵循现有数据库路径。
用户输入了“prisma-next init”、“get started with PN”、“set up PN”、“how do I scaffold a project”等内容。请遵循全新项目路径。
用户表示“我已有Postgres/Mongo数据库，如何开始使用PN？”。请遵循现有数据库路径。

When Not to Use

不适用场景

User already has a PN project and wants to add a model →
```
prisma-next-contract
```
.
User wants to migrate FROM a specific ORM → install
```
@prisma-next/migrate-from-<orm>-skill
```
(separate).
User wants to wire
```
db.ts
```
in a project that already has a contract →
```
prisma-next-runtime
```
.
User wants to integrate Prisma Next with a build tool (Vite plugin, Next.js, …) →
```
prisma-next-build
```
.

用户已有PN项目，想要添加模型 → 请使用
```
prisma-next-contract
```
。
用户想要从特定ORM迁移 → 请安装
```
@prisma-next/migrate-from-<orm>-skill
```
（单独安装）。
用户想要在已有契约的项目中配置
```
db.ts
```
→ 请使用
```
prisma-next-runtime
```
。
用户想要将Prisma Next与构建工具（Vite插件、Next.js等）集成 → 请使用
```
prisma-next-build
```
。

Key Concepts

核心概念

Contract: the data model. Authored as
```
contract.prisma
```
(PSL, the canonical surface) or
```
contract.ts
```
(TypeScript builder). The framework reads it and emits two artefacts:
```
contract.json
```
(runtime IR) and
```
contract.d.ts
```
(types).
Target: the backing store. Today:
```
postgres
```
or
```
mongodb
```
. Picked at
```
init
```
time; baked into the
```
@prisma-next/<target>
```
façade the scaffold imports from.
Authoring mode: how you write the contract.
```
psl
```
(Prisma Schema Language, default) or
```
typescript
```
(programmatic builder, optionally paired with the Vite plugin for auto-emit during
```
vite dev
```
— see
```
prisma-next-build
```
).
Façade packages. The scaffold installs exactly one façade per target —
```
@prisma-next/postgres
```
(or
```
@prisma-next/mongo
```
). User code imports from façade subpaths (
```
@prisma-next/postgres/config
```
,
```
@prisma-next/postgres/runtime
```
,
```
@prisma-next/postgres/contract-builder
```
). The façade bakes in the family / target / adapter / driver wiring; never reach past it. See
```
prisma-next-contract
```
for the full list.
db.ts
: the runtime entry point. Lives next to the contract source at
```
src/prisma/db.ts
```
. Imports the contract artefacts and exports a
```
db
```
value the rest of the app uses.
Marker: a
```
pn_meta_marker
```
row in your database that records the contract hash. Lets PN detect drift between contract and live DB. Created by
```
db init
```
(greenfield / first-touch orientation) or
```
db sign
```
(brownfield).

契约（Contract）：数据模型。以
```
contract.prisma
```
（PSL，标准格式）或
```
contract.ts
```
（TypeScript构建器）编写。框架会读取契约并生成两个产物：
```
contract.json
```
（运行时IR）和
```
contract.d.ts
```
（类型定义）。
目标（Target）：后端存储。目前支持：
```
postgres
```
或
```
mongodb
```
。在
```
init
```
时选择；会嵌入到脚手架导入的
```
@prisma-next/<target>
```
facade包中。
编写模式（Authoring mode）：契约的编写方式。
```
psl
```
（Prisma Schema Language，默认）或
```
typescript
```
（程序化构建器，可搭配Vite插件在
```
vite dev
```
期间自动生成产物 — 详见
```
prisma-next-build
```
）。
Facade包：脚手架会为每个目标安装一个对应的facade包 —
```
@prisma-next/postgres
```
（或
```
@prisma-next/mongo
```
）。用户代码从facade的子路径导入（
```
@prisma-next/postgres/config
```
、
```
@prisma-next/postgres/runtime
```
、
```
@prisma-next/postgres/contract-builder
```
）。Facade包整合了系列/目标/适配器/驱动的配置；请勿直接绕过它。完整列表请查看
```
prisma-next-contract
```
。
db.ts
：运行时入口文件。与契约源文件同目录，位于
```
src/prisma/db.ts
```
。导入契约产物并导出
```
db
```
对象供应用其他部分使用。
标记（Marker）：数据库中的
```
pn_meta_marker
```
行，记录契约哈希值。让PN能够检测契约与实际数据库之间的差异。由
```
db init
```
（全新项目/首次上手引导）或
```
db sign
```
（现有数据库）创建。

Canonical on-disk layout

标准磁盘结构

Every application that consumes Prisma Next uses the same shape:

text

<app-root>/
├── prisma-next.config.ts             ← project config at repo root
├── src/
│   └── prisma/
│       ├── contract.prisma           ← (or contract.ts) — schema source you author
│       ├── contract.json             ← emitted by `contract emit` — do not edit
│       ├── contract.d.ts             ← emitted by `contract emit` — do not edit
│       └── db.ts                     ← runtime entry; the rest of `src/` imports from here
└── migrations/
    └── app/                          ← created on first `migration plan` / `db init`
        ├── refs/head.json
        └── <timestamp>_<slug>/
            ├── migration.json
            ├── ops.json
            ├── end-contract.json
            ├── end-contract.d.ts
            └── migration.ts

Three things to internalise:

src/prisma/
is the home for the contract — source + emitted artefacts +
```
db.ts
```
all colocated. The rest of
```
src/
```
imports from
```
./prisma/db
```
(or
```
../prisma/db
```
, depending on file depth).
migrations/app/
— the
```
app/
```
segment is the consuming application's space-id. Extensions you depend on get sibling directories under
```
migrations/
```
(one per extension contract-space), but you don't write into those — only the
```
app/
```
subtree is your migrations.
prisma-next.config.ts
lives at the repo root, not under
```
src/
```
. Every command resolves paths relative to the config's directory.

Contributors building extension packages or aggregate-root monorepo packages use a different layout —

src/contract.{prisma,ts}

(no

prisma/

subdir) +

migrations/<timestamp>_<slug>/

(no

app/

segment). That distinction is intentional; see

prisma-next-contract

for which path applies to you.

Heads up —
prisma-next init
currently scaffolds the wrong layout. It writes
prisma/contract.{prisma,ts}
and
prisma/db.ts
at the repo root instead of under
src/prisma/
. Tracked as TML-2532. Until the fix lands, either pass
--schema-path src/prisma/contract.prisma
to
init
, or move the scaffolded
prisma/
directory into
src/prisma/
after
init
and update the
contract
path in
prisma-next.config.ts
to match. The canonical layout above is what the demo example uses and what the rest of the framework expects.

所有使用Prisma Next的应用都采用相同的结构：

text

<app-root>/
├── prisma-next.config.ts             ← 项目配置文件，位于仓库根目录
├── src/
│   └── prisma/
│       ├── contract.prisma           ← （或contract.ts）—— 你编写的Schema源文件
│       ├── contract.json             ← 由`contract emit`生成 — 请勿编辑
│       ├── contract.d.ts             ← 由`contract emit`生成 — 请勿编辑
│       └── db.ts                     ← 运行时入口；应用其他部分从这里导入
└── migrations/
    └── app/                          ← 首次执行`migration plan` / `db init`时创建
        ├── refs/head.json
        └── <timestamp>_<slug>/
            ├── migration.json
            ├── ops.json
            ├── end-contract.json
            ├── end-contract.d.ts
            └── migration.ts

需要牢记三点：

src/prisma/
是契约的存放目录 — 源文件、生成产物、
```
db.ts
```
都放在这里。应用其他部分从
```
./prisma/db
```
（或
```
../prisma/db
```
，取决于文件深度）导入。
migrations/app/
—
```
app/
```
是当前应用的空间ID。你依赖的扩展会在
```
migrations/
```
下创建同级目录（每个扩展契约空间对应一个目录），但你无需修改这些目录 — 只有
```
app/
```
子目录是你的迁移文件存放位置。
prisma-next.config.ts
位于仓库根目录，而非
```
src/
```
下。所有命令都会相对于配置文件所在目录解析路径。

构建扩展包或聚合根单体仓库包的贡献者使用不同的结构 —

src/contract.{prisma,ts}

（无

prisma/

子目录） +

migrations/<timestamp>_<slug>/

（无

app/

段）。这种区分是有意设计的；请查看

prisma-next-contract

了解适用的结构。

注意 — 当前
prisma-next init
生成的结构有误。它会在仓库根目录创建
prisma/contract.{prisma,ts}
和
prisma/db.ts
，而非
src/prisma/
下。该问题已记录为TML-2532。在修复完成前，你可以在
init
时传入
--schema-path src/prisma/contract.prisma
，或者在
init
完成后将生成的
prisma/
目录移动到
src/prisma/
下，并更新
prisma-next.config.ts
中的
contract
路径以匹配。上述标准结构是演示示例使用的结构，也是框架期望的结构。

Your first arc — connect, write, read

你的第一个核心流程 — 连接、写入、读取

All three paths in this skill converge here. Once the project is scaffolded and the database is reachable, the first move is always the same: connect, write a row, read it back, against whatever model the contract already declares. Don't touch the contract source on this first move — extend it later, after the round-trip works.

Write the snippet in a fresh file directly under

src/

(e.g.

src/first-arc.ts

) so the relative import resolves to one level deep:

typescript

// src/first-arc.ts
import 'dotenv/config';
import { db } from './prisma/db';

// Write a row against the starter model. Adapt the field names to whatever
// model your contract source actually declares — read it first.
await db.orm.User.create({ email: 'alice@example.com' });

// Read it back.
const users = await db.orm.User.select('id', 'email').all();
console.log(users);

If that prints

[{ id: 1, email: 'alice@example.com' }]

, the project is wired end-to-end and the user has crossed from "I have a project" to "I'm building."

db.orm.<Model>

is the default ORM lane — model-shaped, fully typed against the contract, lazily connects to the database on first use (it picks up

DATABASE_URL

from

.env

via the runtime's

dotenv/config

-loaded environment). The deeper

prisma-next-queries

skill covers the rest of the surface (filters, joins, transactions, the SQL builder, raw SQL, TypedSQL) when the user is ready.

Prerequisites for the arc to work. All three paths leave these in place by the time you reach the arc:

```
prisma-next.config.ts
```
exists at the repo root and declares the target + contract source (typically
```
src/prisma/contract.prisma
```
or
```
src/prisma/contract.ts
```
).
The contract source exists at
```
src/prisma/contract.{prisma,ts}
```
(a starter model from
```
init
```
, or the inferred contract from
```
contract infer
```
, or whatever the bootstrap tool generated).
```
src/prisma/db.ts
```
exists and instantiates the runtime with the emitted contract.
```
DATABASE_URL
```
is set in
```
.env
```
(or wherever the runtime's config tells it to look).
The database has been initialised (
```
db init
```
) or marker-signed (
```
db sign
```
), so the marker row exists and the schema matches the contract.

The three workflows below each describe how their path gets the user to that state. After that, the arc above is the same.

本指南中的三种路径最终都会汇聚到这里。一旦项目搭建完成且数据库可访问，第一步操作始终是相同的：连接数据库，写入一行数据，再读取回来，针对契约中已有的任意模型进行操作。在完成首次数据往返前，请勿修改契约源文件 — 等往返成功后再扩展契约。

在

src/

下新建一个文件（例如

src/first-arc.ts

），写入以下代码，确保相对导入路径正确：

typescript

// src/first-arc.ts
import 'dotenv/config';
import { db } from './prisma/db';

// 针对基础模型写入一行数据。请根据契约源文件中实际定义的模型调整字段名 — 先查看契约内容。
await db.orm.User.create({ email: 'alice@example.com' });

// 读取数据
const users = await db.orm.User.select('id', 'email').all();
console.log(users);

如果控制台输出

[{ id: 1, email: 'alice@example.com' }]

，说明项目已完成端到端配置，用户已从“我有一个项目”过渡到“我正在构建应用”。

db.orm.<Model>

是默认的ORM操作入口 — 与模型结构一致，完全根据契约进行类型定义，首次使用时会延迟连接到数据库（通过运行时加载的

dotenv/config

从

.env

中获取

DATABASE_URL

）。当用户准备深入了解更多功能（过滤、关联、事务、SQL构建器、原生SQL、TypedSQL）时，可查看

prisma-next-queries

技能。

核心流程的前提条件。三种路径在到达核心流程时都会满足以下条件：

仓库根目录存在
```
prisma-next.config.ts
```
，并声明了目标（
```
postgres
```
/
```
mongodb
```
）和契约源文件路径（通常为
```
src/prisma/contract.prisma
```
或
```
src/prisma/contract.ts
```
）。
契约源文件存在于
```
src/prisma/contract.{prisma,ts}
```
（由
```
init
```
生成的基础模型、由
```
contract infer
```
推导的契约，或由脚手架工具生成的内容）。
```
src/prisma/db.ts
```
存在，并使用生成的契约实例化运行时。
```
.env
```
中已设置
```
DATABASE_URL
```
（或运行时配置指定的其他位置）。
数据库已初始化（
```
db init
```
）或已标记签署（
```
db sign
```
），因此标记行存在且Schema与契约匹配。

以下三个工作流分别描述了不同路径如何让用户满足上述条件。之后，核心流程都是相同的。

Workflow — First-touch orientation

工作流 — 首次上手引导

Triggers: "what can I do with Prisma Next?", "what can I do next with Prisma?", "where do I start?", "I just ran createprisma", "what's next?", or any close variant — paired with a PN project already on disk (scaffolded by

createprisma

, by

prisma-next init

, by a teammate, however).

The user's high-level intent is "I want to be running an application against my database, against this thing called Prisma Next." The job of this workflow is to anchor them on the contract, get one round-trip working, and let further commands surface organically as their next move requires them. It is orientation, not a tour, not a feature inventory, not a syllabus.

触发场景：用户提出“我能用Prisma Next做什么？”、“我接下来能用Prisma做什么？”、“我该从哪里开始？”、“我刚运行了createprisma”、“接下来该怎么做？”等类似问题，且本地已存在PN项目（由

createprisma

、

prisma-next init

、队友创建等方式生成）。

用户的核心需求是“我想要让我的应用运行在数据库上，使用Prisma Next”。本工作流的任务是让用户熟悉契约概念，完成一次数据往返，并让后续命令根据用户的下一步需求自然呈现。这是引导，不是功能介绍、不是命令清单、不是教程大纲。

Concept — what to communicate first

概念 — 首先要传达的内容

Prisma Next is contract-first. Everything the framework does — query types, migrations, runtime types, drift detection — flows from a single source of truth: the contract. The contract describes the user's application's data model. The framework reads it; the framework derives the rest. Lead with this.

The first response to "what can I do with Prisma Next?" names the contract path, frames its role in one sentence, and then steers toward getting the user's application running. Don't open with a feature inventory. Don't open with a list of commands. Open with: "Your contract is at
<path>
. It describes your application — your query types, migrations, and runtime types all flow from it. Let's get you connected to a database so your app can actually run against it."

The first arc — once oriented — is connect → write → read. Not edit-the-contract-first, not plan-a-migration-first. The user's win is I have application code running against my database.

Prisma Next是契约优先的框架。框架的所有功能 — 查询类型、迁移、运行时类型、差异检测 — 都源于单一的事实来源：契约。契约描述了应用的数据模型。框架读取契约，然后衍生出其他所有内容。首先要强调这一点。

对于“我能用Prisma Next做什么？”的第一个回答，要指出契约的路径，用一句话说明其作用，然后引导用户连接数据库让应用运行起来。不要一开始就罗列功能，不要一开始就列出命令。可以这样开头：“你的契约位于

<path>

，它描述了你的应用 — 框架提供的所有查询类型、迁移和运行时类型都源于这个文件。接下来让我们连接到数据库，让你的应用能够真正运行起来。”具体措辞可以调整，但关键是让用户在第一次回复中知道契约在哪里以及它是事实来源。

完成引导后的第一个核心流程是连接 → 写入 → 读取。不是先编辑契约，不是先规划迁移。用户的目标是“我的应用运行在数据库上”。

Step 1 — Read the project, name the contract

步骤1 — 了解项目，明确契约位置

Before saying anything specific to the user, read:

```
prisma-next.config.ts
```
at the repo root — what target (
```
postgres
```
/
```
mongodb
```
) is wired, what
```
contract:
```
path it declares, what extensions are installed.
The contract source the config declares (canonically
```
src/prisma/contract.prisma
```
or
```
src/prisma/contract.ts
```
; a project that pre-dates TML-2532 may have it at
```
prisma/contract.{prisma,ts}
```
instead — check the
```
contract
```
field of the config) — what starter models, if any, exist.
```
src/prisma/db.ts
```
(next to the contract) — the runtime entry point.
```
.env
```
/
```
.env.example
```
— is
```
DATABASE_URL
```
set, or only the example?
Optionally
```
pnpm prisma-next db verify
```
— does the live DB match the contract?

Then say the contract path back to the user, with its role attached. Something like: "Your contract is at
src/prisma/contract.prisma
, and it currently declares a
User
model. The contract describes your app — every query type, migration, and runtime type the framework gives you flows from this file. Let's get your app connected to a database next." The exact wording is up to the agent; what matters is that the user leaves the first response knowing where the contract is and that it is the source of truth.

在向用户提出具体建议前，先查看：

仓库根目录的
```
prisma-next.config.ts
```
— 配置了什么目标（
```
postgres
```
/
```
mongodb
```
），声明了什么
```
contract:
```
路径，安装了哪些扩展。
配置中声明的契约源文件（标准位置为
```
src/prisma/contract.prisma
```
或
```
src/prisma/contract.ts
```
；早于TML-2532的项目可能位于
```
prisma/contract.{prisma,ts}
```
— 请查看配置中的
```
contract
```
字段） — 存在哪些基础模型（如果有的话）。
契约文件同目录下的
```
src/prisma/db.ts
```
— 运行时入口文件。
```
.env
```
/
```
.env.example
```
— 是否已设置
```
DATABASE_URL
```
，还是只有示例？
可选：运行
```
pnpm prisma-next db verify
```
— 实际数据库是否与契约匹配？

然后向用户说明契约的位置及其作用。例如：“你的契约位于

src/prisma/contract.prisma

，当前声明了一个

User

模型。契约描述了你的应用 — 框架提供的所有查询类型、迁移和运行时类型都源于这个文件。接下来让我们连接到数据库。”具体措辞可以调整，但关键是让用户知道契约的位置和它是事实来源。

Step 2 — Get the user's app connected and round-tripping

步骤2 — 让用户的应用连接到数据库并完成数据往返

The motivation is "so your app can actually run against your database", not "so the prerequisite checklist passes". The mechanics depend on what's already in place from Step 1:

Everything already wired. Go straight to writing and reading a row (see Your first arc — connect, write, read above). Adapt the snippet to whatever model the contract declares.
DATABASE_URL
not set. Have the user set it in
```
.env
```
(not in
```
prisma-next.config.ts
```
— see Pitfall 5). Then
```
pnpm prisma-next db init
```
to apply the current contract to that database and write the marker row. Now the app can connect.
Database is connectable but not yet aware of the contract (marker row missing;
```
db verify
```
reports drift). Run
```
pnpm prisma-next db init
```
. (
```
db update
```
is the alternative for quick dev cycles — it's looser, doesn't write a migration history, and is what users reach for when they want to iterate on the schema fast. Mention it if the user asks how to make schema changes flow to the DB; don't pre-explain it.)
Contract is empty (bootstrap left the source blank). Add one model with two fields (e.g.
```
User { id, email }
```
),
```
pnpm prisma-next contract emit
```
, then
```
pnpm prisma-next db init
```
. Minimal — get the round-trip working, then extend.

The user encounters

db init

(and optionally

db update

contract emit

) here because they're the commands their current move requires. They learn what those commands are by using them.

目的是“让你的应用能够真正运行在数据库上”，而不是“满足前提条件清单”。具体操作取决于步骤1中已有的配置：

所有配置已完成。直接进行写入和读取操作（详见上方“你的第一个核心流程 — 连接、写入、读取”）。根据契约中声明的模型调整代码片段。
未设置
DATABASE_URL
。让用户在
```
.env
```
中设置该值（不要在
```
prisma-next.config.ts
```
中设置 — 详见陷阱5）。然后运行
```
pnpm prisma-next db init
```
将当前契约应用到数据库并写入标记行。现在应用可以连接到数据库了。
数据库可连接但尚未关联契约（缺少标记行；
```
db verify
```
报告差异）。运行
```
pnpm prisma-next db init
```
。（
```
db update
```
是快速开发周期的替代方案 — 它更灵活，不会保留迁移历史，适合用户想要快速迭代Schema的场景。如果用户询问如何将Schema变更同步到数据库，可以提及它；不要提前解释。）
契约为空（脚手架工具生成的源文件为空）。添加一个模型，包含两个字段（例如
```
User { id, email }
```
），运行
```
pnpm prisma-next contract emit
```
，然后运行
```
pnpm prisma-next db init
```
。保持最简 — 先让数据往返成功，然后再扩展。

用户会在这里接触到

db init

（以及可选的

db update

、

contract emit

），因为这些是当前操作必需的命令。用户通过使用这些命令来了解它们的作用。

Step 3 — Round-trip a row

步骤3 — 完成数据往返

Run the snippet from Your first arc — connect, write, read above against whatever model the contract declares. When it prints the row back, the user has crossed from "I have a project" to "my app runs against my database". That's the win.

运行上方“你的第一个核心流程 — 连接、写入、读取”中的代码片段，针对契约中声明的任意模型进行操作。当控制台输出数据行时，用户已从“我有一个项目”过渡到“我的应用运行在数据库上”。这就是目标。

Step 4 — Hand off to the next move

步骤4 — 引导到下一步操作

Now ask the user what they want to build. Route to the skill that owns that move:

More queries (filters, joins, transactions, raw SQL, TypedSQL) →
```
prisma-next-queries
```
.
Add a model, change a field, add a relation →
```
prisma-next-contract
```
. They'll touch
```
contract emit
```
and
```
db update
```
(or
```
migration plan
```
+
```
migrate
```
) as part of that workflow.
Middleware, environment config, multiple targets →
```
prisma-next-runtime
```
.
Vite / Next.js / dev-server integration →
```
prisma-next-build
```
.
They want a fuller toolbelt overview at this point — Commands you'll use day-to-day below is the one-glance summary.

现在询问用户想要构建什么，引导到对应的技能：

更多查询功能（过滤、关联、事务、原生SQL、TypedSQL） →
```
prisma-next-queries
```
。
添加模型、修改字段、添加关联 →
```
prisma-next-contract
```
。用户在该工作流中会用到
```
contract emit
```
和
```
db update
```
（或
```
migration plan
```
+
```
migrate
```
）。
中间件、环境配置、多目标 →
```
prisma-next-runtime
```
。
Vite / Next.js / 开发服务器集成 →
```
prisma-next-build
```
。
用户此时想要了解更多常用命令 — 下方的“日常使用命令”是一目了然的总结。

Anti-patterns on this path

该路径的反模式

Leading with a feature tour or capability inventory. The user asked what they can do. Get them doing it.
Listing commands before any have been used. Commands belong to specific moves; surface them when the move requires them.
Diving into migration concepts before one query has run. Migrations exist; their value lands later.
Adding several models in one go. Add one, get one query green, then iterate.
Walking the user through
prisma-next.config.ts
keys. The scaffold's defaults are correct; revisit when the user needs to change something.
Skipping the contract framing. Even one line — "your contract is at
<path>
, it's the source of truth" — anchors the user; without it, the rest of the workflow lands as disconnected ceremony.

一开始就进行功能介绍或罗列功能。用户问的是他们能做什么，让他们动手操作。
在使用命令前先罗列所有命令。命令属于特定操作；在需要时再呈现它们。
在完成首次查询前深入讲解迁移概念。迁移确实存在，但它的价值在后续体现。
一次性添加多个模型。先添加一个，让一次查询成功，然后再迭代。
引导用户查看
prisma-next.config.ts
的所有配置项。脚手架的默认配置是正确的；当用户需要修改时再回顾。
跳过契约的概念说明。即使只用一句话 — “你的契约位于
```
<path>
```
，它是事实来源” — 也能让用户建立认知；否则，后续工作流会显得杂乱无章。

Workflow — Greenfield

工作流 — 全新项目（Greenfield）

The concept:

prisma-next init

is one CLI command that scaffolds config, schema, runtime, dependencies, and the contract emit step. It operates on the current working directory — there is no positional project-name argument. Make the directory,

cd

in, then run init.

bash

mkdir my-app && cd my-app
pnpm init                                          # if no package.json yet
pnpm dlx prisma-next init                          # interactive

核心概念：

prisma-next init

是一个CLI命令，用于生成配置、Schema、运行时、依赖项和契约生成步骤。它在当前工作目录下操作 — 不需要指定项目名称参数。创建目录，进入目录，然后运行init命令。

bash

mkdir my-app && cd my-app
pnpm init                                          # 如果还没有package.json
pnpm dlx prisma-next init                          # 交互式

or non-interactive (CI / agent runs):

或非交互式（CI/自动化运行）：

pnpm dlx prisma-next init --yes --target postgres --authoring psl


The flags `init` accepts (run `prisma-next init --help` for the source of truth):

- `--target <db>` — `postgres` or `mongodb`.
- `--authoring <style>` — `psl` or `typescript`.
- `--schema-path <path>` — defaults to `prisma/contract.prisma` (or `prisma/contract.ts`). **Pass `--schema-path src/prisma/contract.prisma` (or `.../contract.ts`)** to scaffold into the canonical `src/prisma/` location directly — `init`'s default is wrong today, see [TML-2532](https://linear.app/prisma-company/issue/TML-2532).
- `--force` — overwrite an existing scaffold without prompting (re-running init in a scaffolded directory triggers the reinit flow — `--force` skips the confirmation).
- `--write-env` — also write `.env` (default writes only `.env.example`; `.env` stays under your control).
- `--probe-db` — connect to `DATABASE_URL` once and check the server version against the target's minimum.
- `--strict-probe` — fail init if the probe fails (no-op without `--probe-db`).
- `--no-install` — skip dependency install + initial contract emit.
- `--no-skill` — skip Prisma Next skills installation (air-gapped / restricted environments). The skill cluster is always installed at the project level — never globally — so its version stays locked to the project's Prisma Next version.

`init` writes (when it runs cleanly):

- `prisma-next.config.ts` at the project root.
- The contract source at `--schema-path` — `src/prisma/contract.prisma` if you passed the canonical override, `prisma/contract.prisma` if you accepted the (currently-wrong) default.
- `db.ts` in the same directory as the contract source.
- `prisma-next.md` — a human quick-reference.
- `.env.example` (and `.env` if `--write-env`).
- Updates `package.json` (deps + scripts) and `tsconfig.json` (required compiler options).
- Installs deps and runs `prisma-next contract emit` once.
- Registers Prisma Next skills with the local agent runtime.

**If you took `init`'s default and ended up with a top-level `prisma/` directory** (TML-2532), the cleanup is one move + one config edit:

```bash
mkdir -p src && mv prisma src/prisma

pnpm dlx prisma-next init --yes --target postgres --authoring psl


`init`支持的参数（运行`prisma-next init --help`查看权威说明）：

- `--target <db>` — `postgres`或`mongodb`。
- `--authoring <style>` — `psl`或`typescript`。
- `--schema-path <path>` — 默认值为`prisma/contract.prisma`（或`prisma/contract.ts`）。**请传入`--schema-path src/prisma/contract.prisma`（或`.../contract.ts`）**，直接生成到标准的`src/prisma/`位置 — 当前`init`的默认路径有误，详见[TML-2532](https://linear.app/prisma-company/issue/TML-2532)。
- `--force` — 覆盖现有脚手架文件，无需提示（在已搭建的目录中重新运行init会触发重新初始化流程 — `--force`会跳过确认）。
- `--write-env` — 同时写入`.env`（默认只写入`.env.example`；`.env`由用户自行管理）。
- `--probe-db` — 连接到`DATABASE_URL`一次，检查服务器版本是否符合目标数据库的最低要求。
- `--strict-probe` — 如果探测失败，则终止init（没有`--probe-db`时无效）。
- `--no-install` — 跳过依赖安装和首次契约生成。
- `--no-skill` — 跳过Prisma Next技能安装（适用于离线/受限环境）。技能集群始终安装在项目级别 — 不会全局安装，因此其版本会与项目的Prisma Next版本保持一致。

当`init`成功运行时，会生成以下文件：

- 项目根目录下的`prisma-next.config.ts`。
- 契约源文件，位于`--schema-path`指定的位置 — 如果传入了标准路径，则为`src/prisma/contract.prisma`；如果接受了当前（错误的）默认值，则为`prisma/contract.prisma`。
- 与契约源文件同目录的`db.ts`。
- `prisma-next.md` — 人类可读的快速参考文档。
- `.env.example`（如果使用`--write-env`，则同时生成`.env`）。
- 更新`package.json`（依赖项 + 脚本）和`tsconfig.json`（必需的编译选项）。
- 安装依赖项并运行一次`prisma-next contract emit`。
- 在本地代理运行时中注册Prisma Next技能。

**如果你接受了`init`的默认值，生成了顶级的`prisma/`目录**（TML-2532），只需一步操作+一处配置修改即可修复：

```bash
mkdir -p src && mv prisma src/prisma

Then update prisma-next.config.ts so

contract

reads

然后更新prisma-next.config.ts中的

contract

路径

'src/prisma/contract.prisma' (or .ts) instead of 'prisma/contract.prisma'.

从'prisma/contract.prisma'（或.ts）改为'src/prisma/contract.prisma'（或.ts）。

pnpm prisma-next contract emit # re-emits contract.json + contract.d.ts under src/prisma/


Do this before running `db init` — once the marker row is written, restructuring is harder.

After init succeeds, the path converges on *Your first arc — connect, write, read* above. `init` has already seeded a starter contract with `User` and `Post` models (with a relation between them) and run `contract emit` once; the only remaining prerequisites are setting `DATABASE_URL` and initialising the database. Two commands:

1. Set `DATABASE_URL` in `.env` (copy from `.env.example`).
2. Initialise the database: `pnpm prisma-next db init`. Creates tables, indexes, constraints, and writes the marker row — using the starter contract `init` generated.

Then run the snippet from *Your first arc* above against the `User` model. When the user is ready to extend the contract — add more models, change fields, add relations — chain to `prisma-next-contract`. For more queries, chain to `prisma-next-queries`.

**Why this is queries-first, not schema-editing-first.** `init` ships with `User` and `Post` on purpose: the user shouldn't have to design a schema to prove their setup works. Extending the contract is the next move *after* the first arc lands, not part of getting there. If the user asks you to skip straight to *"add a Comment model"* — sure, do that — but get one query green against `User` or `Post` first if there's any doubt the project is wired correctly.

pnpm prisma-next contract emit # 重新生成src/prisma/下的contract.json + contract.d.ts


请在运行`db init`前完成此操作 — 一旦写入标记行，调整结构会更困难。

init成功后，路径会汇聚到上方的“你的第一个核心流程 — 连接、写入、读取”。`init`已经生成了包含`User`和`Post`模型（两者有关联）的基础契约，并运行了一次`contract emit`；剩下的前提条件只有设置`DATABASE_URL`和初始化数据库。只需两个命令：

1. 在`.env`中设置`DATABASE_URL`（从`.env.example`复制）。
2. 初始化数据库：`pnpm prisma-next db init`。创建表、索引、约束，并写入标记行 — 使用`init`生成的基础契约。

然后针对`User`模型运行上方核心流程中的代码片段。当用户准备扩展契约 — 添加更多模型、修改字段、添加关联 — 时，引导到`prisma-next-contract`。如需更多查询功能，引导到`prisma-next-queries`。

**为什么先做查询，而不是先编辑Schema**。`init`默认生成`User`和`Post`模型是有目的的：用户无需设计Schema即可验证设置是否成功。扩展契约是完成核心流程后的下一步操作，而非设置过程的一部分。如果用户要求直接“添加Comment模型” — 可以，但如果对项目配置是否正确有疑问，请先确保针对`User`或`Post`的一次查询成功。

Workflow — Brownfield-DB (existing database, no contract)

工作流 — 现有数据库（Brownfield-DB，已有数据库，无契约）

The concept: against an existing database with no PN contract,

contract infer

walks the live schema (tables, columns, indexes, constraints) and writes a PSL contract that describes it. The result is a starting point, not the final contract — review and clean it up, then

db sign

to record the current contract hash as the marker (instead of letting

db init

try to recreate the schema from scratch).

bash

mkdir my-app && cd my-app
pnpm init
pnpm dlx prisma-next init --yes --target postgres --authoring psl

核心概念：针对没有PN契约的现有数据库，

contract infer

会遍历实际Schema（表、列、索引、约束），生成描述该数据库的PSL契约。结果是一个起点，而非最终契约 — 请先检查并清理，然后使用

db sign

记录当前契约哈希值作为标记（而非让

db init

尝试从头重建Schema）。

bash

mkdir my-app && cd my-app
pnpm init
pnpm dlx prisma-next init --yes --target postgres --authoring psl

scaffold lands; you'll overwrite the starter schema below

脚手架生成完成；接下来会覆盖基础Schema


Then, with `DATABASE_URL` set in `.env`:

```bash
pnpm prisma-next contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

(Note: the flag is

--output

, not

--out

. Run

prisma-next contract infer --help

for the full surface.)

The agent should pause here and read the inferred PSL. Symptoms a re-author pass is needed:

Tables PN couldn't categorise (e.g. legacy linking tables you could express as relations).
Columns where PN's type guess is wrong (e.g.
```
String
```
where you want an extension type like
```
pgvector.Vector(length: 1536)
```
).
Missing
```
@unique
```
/
```
@index
```
hints PN couldn't see.
Field names you'd prefer to alias.

Then re-emit and sign:

bash

pnpm prisma-next contract emit
pnpm prisma-next db sign
pnpm prisma-next db verify   # confirms the DB matches the contract; reports drift if not

Then run the snippet from Your first arc — connect, write, read above, using one of your existing tables in place of the starter model. The arc is the same; only the path that got you there differs.


然后，在`.env`中设置`DATABASE_URL`后：

```bash
pnpm prisma-next contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

（注意：参数是

--output

，不是

--out

。运行

prisma-next contract infer --help

查看完整参数。）

此时应该暂停并检查生成的PSL。出现以下情况时需要重新编辑：

PN无法分类的表（例如可以表示为关联的遗留关联表）。
PN类型猜测错误的列（例如应该使用
```
pgvector.Vector(length: 1536)
```
等扩展类型，而不是
```
String
```
）。
PN无法识别的缺失
```
@unique
```
/
```
@index
```
提示。
你想要别名的字段名。

然后重新生成契约并标记数据库：

bash

pnpm prisma-next contract emit
pnpm prisma-next db sign
pnpm prisma-next db verify   # 确认数据库与契约匹配；如果不匹配则报告差异

然后运行上方“你的第一个核心流程 — 连接、写入、读取”中的代码片段，用现有表替换基础模型。核心流程是相同的，只有到达该流程的路径不同。

Commands you'll use day-to-day

日常使用命令

A reference table — not a script to recite at the user. Commands surface in the workflow above as the user's next move requires them; this table is here for the moment the user asks for a wider view (typically after the first round-trip), and as a one-glance summary anyone newly oriented to Prisma Next can scan. For flag-level detail, run

<command> --help

; the help output is the source of truth.

What you want to do	Command	Deeper skill
Apply the current contract to the DB the first time	`prisma-next db init`	this skill
Re-emit `contract.json` + `contract.d.ts` after editing the contract source	`prisma-next contract emit`	`prisma-next-contract`
Quick dev-only schema sync (no migration history kept)	`prisma-next db update`	`prisma-next-migrations`
Plan a migration from a contract diff	`prisma-next migration plan --name <slug>`	`prisma-next-migrations`
Apply pending migrations	`prisma-next migrate`	`prisma-next-migrations`
Inspect the live database	`prisma-next db schema`	`prisma-next-debug`
Confirm the DB matches the contract (drift check)	`prisma-next db verify`	`prisma-next-debug`
Bring an existing DB into a PN contract	`prisma-next contract infer --db "$DATABASE_URL"`	this skill (brownfield)
Decode a structured error envelope	(read the `code` / `why` / `fix` fields)	`prisma-next-debug`
Report a bug or request a feature	(file via the feedback skill)	`prisma-next-feedback`

这是一个参考表 — 不是要向用户背诵的脚本。命令会在上述工作流中根据用户的下一步需求自然呈现；当用户想要了解更多（通常在首次数据往返后）时，这个表可以作为一目了然的总结，也适合刚接触Prisma Next的用户快速浏览。如需参数细节，请运行

<command> --help

；帮助输出是权威来源。

操作目标	命令	深入技能
首次将当前契约应用到数据库	`prisma-next db init`	本技能
编辑契约源文件后重新生成 `contract.json` + `contract.d.ts`	`prisma-next contract emit`	`prisma-next-contract`
快速开发环境下的Schema同步（不保留迁移历史）	`prisma-next db update`	`prisma-next-migrations`
根据契约差异规划迁移	`prisma-next migration plan --name <slug>`	`prisma-next-migrations`
应用待处理的迁移	`prisma-next migrate`	`prisma-next-migrations`
查看实际数据库的Schema	`prisma-next db schema`	`prisma-next-debug`
确认数据库与契约匹配（差异检查）	`prisma-next db verify`	`prisma-next-debug`
将现有数据库引入PN契约	`prisma-next contract infer --db "$DATABASE_URL"`	本技能（现有数据库场景）
解析结构化错误信息	（查看 `code` / `why` / `fix` 字段）	`prisma-next-debug`
报告Bug或请求功能	（通过反馈技能提交）	`prisma-next-feedback`

Decision — PSL vs TypeScript authoring

选择 — PSL vs TypeScript编写模式

PSL (
```
contract.prisma
```
) — the default. Concise, declarative, familiar to anyone who has used Prisma. Recommended for most projects.
TypeScript (
```
contract.ts
```
) — a programmatic builder. Use when the contract is genuinely computed (multi-tenant per-tenant variants), when you reuse contract fragments across files, or when an extension requires constructs PSL doesn't yet express (e.g. pgvector's parameterised storage-type registration). Pairs with the Vite plugin from
```
prisma-next-build
```
for auto-emit on save.

Switch authoring later by re-running

prisma-next init

in the same directory. The init flow detects the existing scaffold and prompts to reinit (use

--force

to skip the prompt in non-interactive runs). Existing contract content is not automatically translated — you'll re-author by hand in the target language.

PSL（
```
contract.prisma
```
） — 默认选项。简洁、声明式，适合任何使用过Prisma的用户。推荐大多数项目使用。
TypeScript（
```
contract.ts
```
） — 程序化构建器。当契约需要动态生成（多租户的租户专属变体）、需要在多个文件中复用契约片段，或扩展需要PSL尚未支持的结构（例如pgvector的参数化存储类型注册）时使用。搭配
```
prisma-next-build
```
中的Vite插件可实现保存时自动生成产物。

之后可以通过在同一目录下重新运行

prisma-next init

切换编写模式。init流程会检测到现有脚手架并提示重新初始化（非交互式运行时使用

--force

跳过提示）。现有契约内容不会自动转换 — 需要手动用目标语言重新编写。

Common Pitfalls

常见陷阱

Running
prisma-next init <project-name>
with a positional argument.
```
init
```
operates on the current working directory; there is no positional project-name argument.
```
mkdir foo && cd foo && pnpm dlx prisma-next init
```
.
init
doesn't connect to your database. It only scaffolds files and installs dependencies (and runs the initial
```
contract emit
```
). You connect with
```
db init
```
/
```
db update
```
/
```
migrate
```
. If
```
init
```
succeeds and queries fail, the issue is
```
DATABASE_URL
```
, not
```
init
```
.
Treating inferred PSL as the final contract.
```
contract infer
```
produces a starting point. Don't
```
db sign
```
against a contract you haven't read.
Forgetting to emit after editing the contract. The contract artefacts (
```
contract.json
```
,
```
contract.d.ts
```
) are stale until you run
```
contract emit
```
. If the type-checker says a model "doesn't exist", you skipped emit.
Setting
DATABASE_URL
in
prisma-next.config.ts
instead of
.env
. The config reads
```
.env
```
automatically via
```
dotenv/config
```
. Hardcoding the URL leaks credentials and bypasses per-environment overrides. See
```
prisma-next-runtime
```
.
Hand-editing
contract.json
or
contract.d.ts
. They're emitted artefacts; the next
```
contract emit
```
overwrites your changes. Edit the source instead.
Using
--out
for
contract infer
. The flag is
```
--output
```
.

运行
prisma-next init <project-name>
时传入项目名称参数。
```
init
```
在当前工作目录下操作；没有项目名称参数。正确做法：
```
mkdir foo && cd foo && pnpm dlx prisma-next init
```
。
init
不会连接到你的数据库。它只会生成文件并安装依赖项（以及运行首次
```
contract emit
```
）。你需要通过
```
db init
```
/
```
db update
```
/
```
migrate
```
连接数据库。如果
```
init
```
成功但查询失败，问题出在
```
DATABASE_URL
```
，而非
```
init
```
。
将推导的PSL视为最终契约。
```
contract infer
```
生成的是起点。不要在未检查的情况下运行
```
db sign
```
。
编辑契约源文件后忘记生成产物。在运行
```
contract emit
```
前，契约产物（
```
contract.json
```
、
```
contract.d.ts
```
）是过时的。如果类型检查器提示模型“不存在”，说明你跳过了生成步骤。
在
prisma-next.config.ts
中设置
DATABASE_URL
，而非
.env
。配置文件会通过
```
dotenv/config
```
自动读取
```
.env
```
。硬编码URL会泄露凭据，并绕过环境特定的覆盖。详见
```
prisma-next-runtime
```
。
手动编辑
contract.json
或
contract.d.ts
。它们是生成的产物；下一次
```
contract emit
```
会覆盖你的修改。请编辑源文件。
为
contract infer
使用
--out
参数。正确参数是
```
--output
```
。

What Prisma Next doesn't do yet

Prisma Next目前不支持的功能

Migration from another ORM. Prisma Next doesn't migrate your schema from Drizzle / Prisma 6/7 / Sequelize / TypeORM / Kysely / Knex / a raw driver. Workaround: install the matching
```
@prisma-next/migrate-from-<orm>-skill
```
if one exists for your source, or treat the source as a brownfield database and
```
contract infer
```
from it. If you need a guided migration flow built-in, file a feature request via the
```
prisma-next-feedback
```
skill.
prisma db push
-style production sync.
```
db update
```
is the quick development path; for production, use migrations (
```
migration plan
```
+
```
migrate
```
). PN deliberately does not offer a "push-to-prod-without-a-migration" surface — see
```
prisma-next-migrations
```
.
Studio / GUI database browser. Use
```
prisma-next db schema
```
for a CLI tree-style summary of the live DB. If you need an interactive UI, file a feature request via the
```
prisma-next-feedback
```
skill.

从其他ORM迁移。Prisma Next不支持从Drizzle / Prisma 6/7 / Sequelize / TypeORM / Kysely / Knex / 原生驱动迁移Schema。解决方法：如果有对应的
```
@prisma-next/migrate-from-<orm>-skill
```
，请安装；或者将源数据库视为现有数据库，使用
```
contract infer
```
推导契约。如果需要内置的引导迁移流程，请通过
```
prisma-next-feedback
```
技能提交功能请求。
类似
prisma db push
的生产环境同步。
```
db update
```
是快速开发路径；生产环境请使用迁移（
```
migration plan
```
+
```
migrate
```
）。PN故意不提供“无需迁移即可推送到生产环境”的功能 — 详见
```
prisma-next-migrations
```
。
Studio / GUI数据库浏览器。使用
```
prisma-next db schema
```
查看CLI树形结构的实际数据库摘要。如果需要交互式UI，请通过
```
prisma-next-feedback
```
技能提交功能请求。

Reference Files

参考文件

This skill is intentionally body-only;

prisma-next init --help

contract infer --help

, and

db sign --help

are the authoritative surfaces for flag-level detail. When in doubt, run

--help

and read the actual command's description rather than guessing from this skill.

本指南仅包含核心内容；

prisma-next init --help

、

contract infer --help

和

db sign --help

是参数细节的权威来源。如有疑问，请运行

--help

并查看命令的实际描述，而非根据本指南猜测。

Checklist

检查清单

Confirmed which path applies (first-touch orientation / greenfield / brownfield) before proposing commands.
First-touch orientation: named the contract path back to the user and framed its role (source of truth from which query types, migrations, and runtime types flow) before proposing any commands.
All paths: brought the project to the Your first arc prerequisites (config, contract source,
```
db.ts
```
,
```
DATABASE_URL
```
, marker row) before writing application code.
All paths: ran the first arc — one
```
create
```
+ one
```
select
```
against the starter (or inferred) model — and got the round-trip working green.
All paths: did not edit the contract source as part of the first arc. Schema extension is the next move, not the first.
All paths: did not lead with a feature tour, capability inventory, or recital of CLI commands. Commands surfaced as the user's current move required them.
Confirmed the user's target (
```
postgres
```
/
```
mongodb
```
) and authoring mode (
```
psl
```
/
```
typescript
```
).
First-touch orientation: read
```
prisma-next.config.ts
```
, the contract source,
```
db.ts
```
, and
```
.env
```
before proposing anything — didn't assume what the scaffold tool / teammate left in place.
Greenfield path: ran
```
prisma-next init
```
from the project directory — no positional project-name argument.
All paths: the project ended up in the canonical
```
src/prisma/contract.{prisma,ts}
```
+
```
src/prisma/db.ts
```
+
```
migrations/app/
```
layout — including moving the scaffolded directory out of a top-level
```
prisma/
```
if
```
init
```
produced one (TML-2532).

Brownfield path: ran

contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

, reviewed the result, then

contract emit

db sign

Set
```
DATABASE_URL
```
in
```
.env
```
and confirmed the value is reachable.
Initialised the DB (
```
db init
```
greenfield / first-touch orientation) or signed the marker (
```
db sign
```
brownfield).
Did NOT hand-edit
```
contract.json
```
or
```
contract.d.ts
```
.
Did NOT set
```
DATABASE_URL
```
in
```
prisma-next.config.ts
```
.
Confirmed the user understands what the next skill is for their workflow (typically
```
prisma-next-queries
```
for more queries, then
```
prisma-next-contract
```
when they're ready to extend the schema).

在建议命令前确认适用的路径（首次上手引导 / 全新项目 / 现有数据库）。
首次上手引导：在建议任何命令前，向用户说明契约的位置并解释其作用（查询类型、迁移和运行时类型都源于此事实来源）。
所有路径：在编写应用代码前，确保项目满足“你的第一个核心流程”的前提条件（配置、契约源文件、
```
db.ts
```
、
```
DATABASE_URL
```
、标记行）。
所有路径：完成第一个核心流程 — 针对基础（或推导的）模型执行一次
```
create
```
+ 一次
```
select
```
，并确保数据往返成功。
所有路径：在第一个核心流程中不编辑契约源文件。扩展Schema是下一步操作，而非第一步。
所有路径：不一开始就进行功能介绍、罗列功能或背诵CLI命令。命令根据用户当前操作的需求呈现。
确认用户的目标（
```
postgres
```
/
```
mongodb
```
）和编写模式（
```
psl
```
/
```
typescript
```
）。
首次上手引导：在建议任何操作前，查看
```
prisma-next.config.ts
```
、契约源文件、
```
db.ts
```
和
```
.env
```
— 不要假设脚手架工具/队友留下的配置。
全新项目路径：在项目目录下运行
```
prisma-next init
```
— 不传入项目名称参数。
所有路径：项目最终采用标准结构
```
src/prisma/contract.{prisma,ts}
```
+
```
src/prisma/db.ts
```
+
```
migrations/app/
```
— 如果
```
init
```
生成了顶级的
```
prisma/
```
目录，需将其移动到
```
src/prisma/
```
下（TML-2532）。

现有数据库路径：运行

contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma

，检查结果，然后运行

contract emit

db sign

。

在
```
.env
```
中设置
```
DATABASE_URL
```
并确认该值可访问。
初始化数据库（全新项目/首次上手引导使用
```
db init
```
）或标记数据库（现有数据库使用
```
db sign
```
）。
不手动编辑
```
contract.json
```
或
```
contract.d.ts
```
。
不在
```
prisma-next.config.ts
```
中设置
```
DATABASE_URL
```
。
确认用户了解其工作流的下一个技能（通常是
```
prisma-next-queries
```
用于更多查询功能，然后是
```
prisma-next-contract
```
用于扩展Schema）。

prisma-next-quickstart

Original

Translation

Prisma Next — Quickstart (Adoption)

Prisma Next — 快速入门（上手指南）

When to Use

使用场景

When Not to Use

不适用场景

Key Concepts

核心概念

Canonical on-disk layout

标准磁盘结构

Your first arc — connect, write, read

你的第一个核心流程 — 连接、写入、读取

Workflow — First-touch orientation

工作流 — 首次上手引导

Concept — what to communicate first

概念 — 首先要传达的内容

Step 1 — Read the project, name the contract

步骤1 — 了解项目，明确契约位置

Step 2 — Get the user's app connected and round-tripping

步骤2 — 让用户的应用连接到数据库并完成数据往返

Step 3 — Round-trip a row

步骤3 — 完成数据往返

Step 4 — Hand off to the next move

步骤4 — 引导到下一步操作

Anti-patterns on this path

该路径的反模式

Workflow — Greenfield

工作流 — 全新项目（Greenfield）

or non-interactive (CI / agent runs):

或非交互式（CI/自动化运行）：

Then update prisma-next.config.ts so contract reads

然后更新prisma-next.config.ts中的contract路径

'src/prisma/contract.prisma' (or .ts) instead of 'prisma/contract.prisma'.

从'prisma/contract.prisma'（或.ts）改为'src/prisma/contract.prisma'（或.ts）。

Workflow — Brownfield-DB (existing database, no contract)

工作流 — 现有数据库（Brownfield-DB，已有数据库，无契约）

scaffold lands; you'll overwrite the starter schema below

脚手架生成完成；接下来会覆盖基础Schema

Commands you'll use day-to-day

日常使用命令

Decision — PSL vs TypeScript authoring

选择 — PSL vs TypeScript编写模式

Common Pitfalls

常见陷阱

What Prisma Next doesn't do yet

Prisma Next目前不支持的功能

Reference Files

参考文件

Checklist

检查清单

Then update prisma-next.config.ts so
`contract`
reads

然后更新prisma-next.config.ts中的
`contract`
路径