prisma-postgres-upgrade

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prisma Postgres Upgrade: Prisma ORM 6 or 7 to Prisma 8

Prisma Postgres 升级：Prisma ORM 6 或 7 到 Prisma 8

Move a Node.js server on Prisma ORM 6 or 7 and PostgreSQL to Prisma 8 in one pass. The schema, the database and its data stay, and the app keeps running wherever it runs today.

This skill is the bridge. It covers only what is specific to leaving Prisma ORM 6 or 7. Prisma 8 itself (the contract, migrations, queries, errors) is covered by the

prisma-8

skill that ships inside

@prisma/orm-postgres

, which step 2 installs. Follow it for anything Prisma 8 specific; it matches the installed version, and this skill does not.

prisma-8

says it does not apply to a project that still has

schema.prisma

and

@prisma/client

. That is expected mid-upgrade: this skill keeps both until step 5, and

prisma7Schema(...)

reads that

schema.prisma

. Use

prisma-8

for the Prisma 8 side anyway.

The Prisma ORM 6 or 7 to 8 (PostgreSQL) guide is the source of truth for the steps.

Never do either of these:

Never route a PostgreSQL Prisma ORM 6 app through Prisma ORM 7 first. Prisma 8 reads a Prisma ORM 6
```
schema.prisma
```
unchanged, so
```
prisma-upgrade-v7
```
is only for apps that stay on 7.
Never install
```
prisma@latest
```
or
```
@prisma/orm-postgres@latest
```
when the app will deploy on Prisma Compute: the latest pair does not work with the Composer version the Console's setup installs, so the deploy fails.

将基于 Prisma ORM 6 或 7 和 PostgreSQL 的 Node.js 服务一次性迁移到 Prisma 8。schema、database 及其数据保持不变，应用仍可在当前运行环境中继续运行。

本 skill 是二者之间的桥梁，仅涵盖从 Prisma ORM 6 或 7 迁移时特有的内容。Prisma 8 本身（contract、migrations、queries、errors）由随

@prisma/orm-postgres

提供的

prisma-8

skill 覆盖；该 skill 会在步骤 2 中安装。凡涉及 Prisma 8 特有内容，请遵循

prisma-8

；它与已安装的版本匹配，而本 skill 不匹配。

prisma-8

会提示不适用于仍包含

schema.prisma

和

@prisma/client

的项目。迁移进行中出现这种情况是预期现象：本 skill 会将二者保留到步骤 5，而

prisma7Schema(...)

会读取该

schema.prisma

。无论如何，Prisma 8 端仍应使用

prisma-8

。

Prisma ORM 6 或 7 到 8（PostgreSQL）升级指南是执行这些步骤的权威依据。

绝不要执行以下任一操作：

绝不要让基于 PostgreSQL 的 Prisma ORM 6 应用先迁移到 Prisma ORM 7。Prisma 8 可以原样读取 Prisma ORM 6 的
```
schema.prisma
```
，因此
```
prisma-upgrade-v7
```
仅适用于继续使用 7 的应用。
当应用将部署到 Prisma Compute 时，绝不要安装
```
prisma@latest
```
或
```
@prisma/orm-postgres@latest
```
：这两个 latest 版本与 Console 设置所安装的 Composer 版本不兼容，部署会失败。

When to Apply

适用场景

A PostgreSQL project on Prisma ORM 6 or 7 asks to upgrade to Prisma 8 in one pass
A Prisma ORM 6 or 7 app wants to deploy on Prisma Compute, or the Console blocked its setup with "move to Prisma 8": upgrade here, then deploy with
```
prisma-compute
```

Not for: deploying on Compute (use

prisma-compute

deploy-existing-app

), MongoDB (use

prisma-mongodb-upgrade

), a Prisma ORM 7 app moving one route at a time beside Prisma 8 (follow the route-by-route guide), a project already on Prisma 8 (use the synced

prisma-8

skill), or a new project (use

prisma-orm-setup

基于 PostgreSQL 且使用 Prisma ORM 6 或 7 的项目希望一次性升级到 Prisma 8
使用 Prisma ORM 6 或 7 的应用希望部署到 Prisma Compute，或者 Console 使用“move to Prisma 8”阻止其设置：在此处完成升级，然后使用
```
prisma-compute
```
部署

不适用于：部署到 Compute（使用

prisma-compute

、

deploy-existing-app

）、MongoDB（使用

prisma-mongodb-upgrade

）、在 Prisma 8 旁逐路由迁移的 Prisma ORM 7 应用（遵循逐路由升级指南）、已经使用 Prisma 8 的项目（使用同步后的

prisma-8

skill），或新项目（使用

prisma-orm-setup

）。

Versions

版本

Install exact versions with

--save-exact

. For an app headed to Compute, use the versions the Console's setup uses: today

prisma

8.0.0-rc.27

(dev dependency) and

@prisma/orm-postgres

8.0.0-rc.20

. If the Console's message or an existing setup pull request names other versions, use those. Use Node.js 24.11 or newer if the app will run under

prisma dev

使用

--save-exact

安装精确版本。对于将部署到 Compute 的应用，使用 Console 设置所用的版本：目前

prisma

8.0.0-rc.27

（dev dependency）和

@prisma/orm-postgres

8.0.0-rc.20

。如果 Console 消息或现有 setup pull request 指定了其他版本，则使用这些版本。如果应用将在

prisma dev

下运行，请使用 Node.js 24.11 或更高版本。

The path

迁移路径


verify-upgrade-checklist
prisma
adopt-schema-and-migrations
adopt-schema-and-migrations
client-api-mapping
@prisma/client
verify-upgrade-checklist

Step	What happens	Where the detail is
0	Run the repo's own checks and record the results	`verify-upgrade-checklist`
1	Remove `prisma` , install the versions above, remove `prisma generate` from scripts	this file
2	Write the Prisma 8 `prisma.config.ts` , then `npx prisma skills sync`	`adopt-schema-and-migrations`
3	`contract emit` , `db sign` , baseline migration, retire `prisma/migrations`	`adopt-schema-and-migrations`
4	Create the Prisma 8 client and rewrite every query	`client-api-mapping`
5	Remove `@prisma/client` , the adapter and the generated client	this file
6	Run the same checks again and start the app	`verify-upgrade-checklist`

In step 1, also remove

prisma generate

from

build

postinstall

and any other script: the Prisma 8 CLI has no

generate

and fails with

CLI.UNKNOWN_COMMAND

. Step 1 removes the only command that generated the old client. It keeps working locally, but a fresh install (CI, a new clone) has none, so finish step 4 before pushing to a branch CI builds.

The sync in step 2 installs

prisma-8

prisma-platform-core-concepts

and

prisma-composer-core-concepts

in one go, because the CLI depends on Composer. It writes them for every agent it knows unless

skills.agents

in the config lists only the ones the repository uses. In a Prisma ORM 7 app, replace the old

prisma.config.ts

before syncing: the sync fails with

CLI.CONFIG_UNREADABLE

while the old one is in place.

Commit what Prisma 8 writes:

src/prisma/contract.json

src/prisma/contract.d.ts

and the whole

migrations/

folder. There is no generate step to recreate them in CI.

In step 5,

npm uninstall @prisma/client

leaves the generated client behind; delete

node_modules/.prisma

too, then run a fresh install and the checks so nothing still imports it.


verify-upgrade-checklist
prisma
adopt-schema-and-migrations
adopt-schema-and-migrations
client-api-mapping
@prisma/client
verify-upgrade-checklist

步骤	执行内容	详细信息位置
0	运行仓库自身的检查并记录结果	`verify-upgrade-checklist`
1	移除 `prisma` ，安装上述版本，并从 scripts 中移除 `prisma generate`	本文件
2	编写 Prisma 8 的 `prisma.config.ts` ，然后运行 `npx prisma skills sync`	`adopt-schema-and-migrations`
3	执行 `contract emit` 、 `db sign` 、创建 baseline migration，并淘汰 `prisma/migrations`	`adopt-schema-and-migrations`
4	创建 Prisma 8 client，并重写所有 query	`client-api-mapping`
5	移除 `@prisma/client` 、adapter 和生成的 client	本文件
6	再次运行相同的检查并启动应用	`verify-upgrade-checklist`

步骤 1 还会从

build

、

postinstall

以及其他所有 script 中移除

prisma generate

：Prisma 8 CLI 没有

generate

命令，执行时会报

CLI.UNKNOWN_COMMAND

。步骤 1 移除了生成旧 client 的唯一命令。这样在本地仍可正常工作，但全新安装环境（CI、新克隆的仓库）中不会有该 client，因此必须在推送到会由 CI 构建的分支前完成步骤 4。

步骤 2 中的 sync 会一次性安装

prisma-8

、

prisma-platform-core-concepts

和

prisma-composer-core-concepts

，因为 CLI 依赖 Composer。除非 config 中的

skills.agents

仅列出仓库使用的 Agent，否则它会为所有已知 Agent 写入这些 skills。对于 Prisma ORM 7 应用，请在 sync 前替换旧的

prisma.config.ts

：旧文件存在时，sync 会因

CLI.CONFIG_UNREADABLE

而失败。

请提交 Prisma 8 生成的内容：

src/prisma/contract.json

、

src/prisma/contract.d.ts

以及整个

migrations/

文件夹。CI 中没有 generate 步骤可重新创建它们。

在步骤 5 中，

npm uninstall @prisma/client

会留下生成的 client；还需删除

node_modules/.prisma

，然后执行全新安装和各项检查，确保没有任何代码仍在导入它。

Deploying on Compute

部署到 Compute

When the upgrade is done and the checks pass, deploy with the

prisma-compute

skill (

references/deploy-existing-app.md

). Compute runs only Prisma 8, so the upgrade has to be finished first.

升级完成且检查通过后，使用

prisma-compute

skill（

references/deploy-existing-app.md

）进行部署。Compute 仅支持 Prisma 8，因此必须先完成升级。

What the user does

用户需要完成的事项

The agent cannot do these; stop and ask:

Decide what to do about a database time zone other than UTC (see
```
client-api-mapping
```
).
Sign every other existing database (staging, production) with
```
npx prisma db sign
```
. The agent has only the local one.
Review the change before it ships, especially when the repository has no tests.

Agent 无法完成以下操作；请停止并询问用户：

决定如何处理非 UTC 的 database 时区（参见
```
client-api-mapping
```
）。
使用
```
npx prisma db sign
```
为所有其他现有 database（staging、production）执行签名。Agent 只能访问本地 database。
在变更上线前进行审查，尤其当仓库没有测试时。

Reference files

参考文件

Reference	What it covers
`references/adopt-schema-and-migrations.md`	The first `prisma.config.ts` , keeping `schema.prisma` as the contract, CommonJS `tsconfig` , the baseline, retiring the old migration setup
`references/client-api-mapping.md`	The Prisma 8 client, Prisma ORM 6/7 calls to Prisma 8, and the differences that break rewrites
`references/verify-upgrade-checklist.md`	Proving the upgrade with the repo's own checks

参考文件	涵盖内容
`references/adopt-schema-and-migrations.md`	首个 `prisma.config.ts` 、将 `schema.prisma` 保留为 contract、CommonJS `tsconfig` 、baseline，以及淘汰旧 migration setup
`references/client-api-mapping.md`	Prisma 8 client、将 Prisma ORM 6/7 调用迁移到 Prisma 8，以及会导致重写失败的差异
`references/verify-upgrade-checklist.md`	使用仓库自身的检查验证升级结果

Verified against

验证环境

A Prisma ORM 6.19 app (Express 4, EJS,

tsc

, CommonJS) on PostgreSQL 18, with

prisma

8.0.0-rc.27 and

@prisma/orm-postgres

8.0.0-rc.20. Two agents with no context and only these skills upgraded it: pages and API output were identical before and after against the same database, and

prisma db verify

passed.

在一个 Prisma ORM 6.19 应用（Express 4、EJS、

tsc

、CommonJS）上完成验证，database 为 PostgreSQL 18，使用

prisma

8.0.0-rc.27 和

@prisma/orm-postgres

8.0.0-rc.20。两个没有上下文且仅拥有这些 skills 的 Agent 完成了升级：针对同一个 database，升级前后的页面和 API 输出完全一致，并且

prisma db verify

通过。

Hand-off rule

交接规则

Once the app runs on Prisma 8, use the synced

prisma-8

skill for day-to-day work and

prisma-compute

to deploy and operate it on Compute. This skill covers the upgrade only.

应用在 Prisma 8 上运行后，日常开发使用同步后的

prisma-8

skill，并使用

prisma-compute

在 Compute 上部署和运维。本 skill 仅涵盖升级过程。