zenstack-migrate-from-prisma

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Migrating from Prisma to ZenStack V3

从 Prisma 迁移到 ZenStack V3

ZenStack V3 is designed as a drop-in upgrade path for Prisma: it keeps a Prisma-compatible query API and a schema language (ZModel) that is a superset of the Prisma schema. Most apps migrate with mechanical changes and no query rewrites. Supported databases: PostgreSQL, MySQL, SQLite.

For general setup/CLI details see

zenstack-project-setup

; for the client/dialect see

zenstack-querying

; for schema syntax see

zenstack-schema-modeling

ZenStack V3 旨在提供一条 Prisma 的无缝升级路径：它保留与 Prisma 兼容的查询 API，并使用一种作为 Prisma schema 超集的 schema 语言（ZModel）。大多数应用只需进行机械化更改即可完成迁移，无需重写查询。支持的数据库：PostgreSQL, MySQL, SQLite。

有关常规设置和 CLI 的详细信息，请参阅

zenstack-project-setup

；有关客户端/dialect，请参阅

zenstack-querying

；有关 schema 语法，请参阅

zenstack-schema-modeling

。

At a glance

概览

Prisma	ZenStack V3
`prisma` , `@prisma/client`	`@zenstackhq/cli` (dev), `@zenstackhq/schema` , `@zenstackhq/orm`
`schema.prisma`	`zenstack/schema.zmodel` (Prisma schema is valid ZModel)
`prisma generate`	`zen generate`
`prisma db push` / `migrate dev` / `migrate deploy`	`zen db push` / `zen migrate dev` / `zen migrate deploy`
`new PrismaClient()`	`new ZenStackClient(schema, { dialect })`
bundled DB engine	you install a DB driver ( `pg` / `mysql2` / `better-sqlite3` )

Prisma	ZenStack V3
`prisma` , `@prisma/client`	`@zenstackhq/cli` （dev）、 `@zenstackhq/schema` 、 `@zenstackhq/orm`
`schema.prisma`	`zenstack/schema.zmodel` （Prisma schema 是有效的 ZModel）
`prisma generate`	`zen generate`
`prisma db push` / `migrate dev` / `migrate deploy`	`zen db push` / `zen migrate dev` / `zen migrate deploy`
`new PrismaClient()`	`new ZenStackClient(schema, { dialect })`
内置数据库引擎	自行安装数据库驱动（ `pg` / `mysql2` / `better-sqlite3` ）

Step 1 — Swap dependencies

第 1 步——替换依赖项

bash

npm uninstall prisma @prisma/client
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack does not bundle a database engine — install the driver for your database:

Database	Install
PostgreSQL	`npm install pg` + `npm install -D @types/pg`
MySQL	`npm install mysql2`
SQLite	`npm install better-sqlite3` + `npm install -D @types/better-sqlite3`

@zenstackhq/cli
has a peer dependency on
prisma
, which is installed automatically when needed for migration commands (ZenStack's migrate commands wrap Prisma Migrate).

bash

npm uninstall prisma @prisma/client
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack 不捆绑数据库引擎——请为你的数据库安装驱动：

数据库	安装命令
PostgreSQL	`npm install pg` + `npm install -D @types/pg`
MySQL	`npm install mysql2`
SQLite	`npm install better-sqlite3` + `npm install -D @types/better-sqlite3`

@zenstackhq/cli
对
prisma
有一个 peer dependency，在 migration 命令需要时会自动安装（ZenStack 的 migrate 命令会包装 Prisma Migrate）。

Step 2 — Move and rename the schema

第 2 步——移动并重命名 schema

Move

schema.prisma

→

zenstack/schema.zmodel

. No edits are required — every valid Prisma schema is valid ZModel. Optional cleanup:

Drop the
```
generator client { ... }
```
block (no effect in ZenStack — code gen is driven by
```
zen generate
```
).
The
```
datasource
```
block is kept; its
```
url
```
is used by the migration engine (the ORM runtime gets its connection from the driver/dialect instead).
If you used Prisma's multi-file/multi-schema feature, merge files using ZModel
```
import
```
statements.

Run zen check
to confirm the converted schema is valid (syntax + semantics) before moving on.

Once moved, you can start adding ZenStack-only features that Prisma lacks — access policies (

zenstack-access-control

@@delegate

polymorphism, typed JSON, mixins, computed fields (

zenstack-schema-modeling

将

schema.prisma

移动至

zenstack/schema.zmodel

。无需进行任何编辑——每个有效的 Prisma schema 都是有效的 ZModel。可选清理：

删除
```
generator client { ... }
```
块（在 ZenStack 中不起作用——代码生成由
```
zen generate
```
驱动）。
保留
```
datasource
```
块；其
```
url
```
供 migration engine 使用（ORM runtime 的连接则来自 driver/dialect）。
如果使用了 Prisma 的 multi-file/multi-schema 功能，请使用 ZModel
```
import
```
语句合并文件。

运行 zen check
，在继续之前确认转换后的 schema 在语法和语义上均有效。

完成迁移后，可以开始添加 Prisma 尚不具备的 ZenStack 专属功能——访问策略（

zenstack-access-control

）、

@@delegate

多态、类型化 JSON、mixins、计算字段（

zenstack-schema-modeling

）。

Step 3 — Update the generate script

第 3 步——更新生成脚本

json

{ "scripts": { "generate": "zen generate" } }

Run

zen generate

after every schema change, before using the client.

json

{ "scripts": { "generate": "zen generate" } }

每次更改 schema 后、使用客户端前，请运行

zen generate

。

Step 4 — Replace the client

第 4 步——替换客户端

Swap

new PrismaClient()

for

new ZenStackClient(schema, { dialect })

, supplying a Kysely dialect for your driver (see

zenstack-querying

for all dialects). PostgreSQL example:

import { ZenStackClient } from '@zenstackhq/orm';
import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { schema } from './zenstack/schema';
import { Pool } from 'pg';

export const db = new ZenStackClient(schema, {
    dialect: new PostgresDialect({
        pool: new Pool({ connectionString: process.env.DATABASE_URL }),
    }),
});

Your existing

findMany

create

update

/etc. calls keep working — the ORM API is Prisma-compatible.

将

new PrismaClient()

替换为

new ZenStackClient(schema, { dialect })

，并为你的驱动提供 Kysely dialect（所有 dialect 请参阅

zenstack-querying

）。PostgreSQL 示例：

import { ZenStackClient } from '@zenstackhq/orm';
import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { schema } from './zenstack/schema';
import { Pool } from 'pg';

export const db = new ZenStackClient(schema, {
    dialect: new PostgresDialect({
        pool: new Pool({ connectionString: process.env.DATABASE_URL }),
    }),
});

现有的

findMany

create

update

等调用仍然可用——ORM API 与 Prisma 兼容。

Step 5 — Update type references

第 5 步——更新类型引用

Model types (e.g.
```
User
```
) — import from the generated
```
models
```
.
Input/argument types (e.g.
```
UserCreateArgs
```
) — import from the generated
```
input
```
.

Most code relies on inferred types and needs no explicit imports.

模型类型（例如
```
User
```
）— 从生成的
```
models
```
导入。
输入/参数类型（例如
```
UserCreateArgs
```
）— 从生成的
```
input
```
导入。

大多数代码依赖推断类型，因此不需要显式导入。

Step 6 — Update migration scripts

第 6 步——更新 migration 脚本

json

{
  "scripts": {
    "db:push": "zen db push",
    "migrate:dev": "zen migrate dev",
    "migrate:deploy": "zen migrate deploy"
  }
}

Move your existing migration history from

prisma/migrations

zenstack/migrations

(ZenStack's default location, next to

zenstack/schema.zmodel

). It continues to work unchanged since ZenStack migrate wraps Prisma Migrate. See the

zenstack-db-migration

skill for the full migration workflow.

json

{
  "scripts": {
    "db:push": "zen db push",
    "migrate:dev": "zen migrate dev",
    "migrate:deploy": "zen migrate deploy"
  }
}

将现有 migration history 从

prisma/migrations

移动到

zenstack/migrations

（ZenStack 的默认位置，与

zenstack/schema.zmodel

相邻）。由于 ZenStack migrate 包装了 Prisma Migrate，它无需更改即可继续工作。有关完整的 migration 工作流，请参阅

zenstack-db-migration

skill。

Special case — Prisma custom generators

特殊情况——Prisma 自定义生成器

If you depend on Prisma custom generators (e.g. zod, ERD, type generators) that read a

schema.prisma

, keep emitting one with the

@core/prisma

plugin and chain the commands:

zmodel

plugin prisma {
    provider = '@core/prisma'
    output = './schema.prisma'
}

json

{ "scripts": { "generate": "zen generate && prisma generate --schema=zenstack/schema.prisma" } }

如果你依赖读取

schema.prisma

的 Prisma 自定义生成器（例如 zod、ERD、类型生成器），请继续使用

@core/prisma

plugin 生成该文件，并串联命令：

zmodel

plugin prisma {
    provider = '@core/prisma'
    output = './schema.prisma'
}

json

{ "scripts": { "generate": "zen generate && prisma generate --schema=zenstack/schema.prisma" } }

Mapping Prisma Client extensions

Prisma Client 扩展映射

Prisma extension	ZenStack equivalent
Query extension (intercept calls)	A runtime plugin via `db.$use(...)` with an `onQuery` hook
Result extension (computed fields)	`@computed` field in ZModel + the `computedFields` option on `ZenStackClient` (see `zenstack-schema-modeling` )

Prisma extension	ZenStack 对应功能
Query extension（拦截调用）	通过 `db.$use(...)` 使用 runtime plugin，并设置 `onQuery` hook
Result extension（计算字段）	ZModel 中的 `@computed` 字段 + `ZenStackClient` 上的 `computedFields` 选项（请参阅 `zenstack-schema-modeling` ）

After migrating

迁移完成后

Verify with:

zen generate

→ typecheck → run your test suite / app. Then incrementally adopt ZenStack's value-add features (access control, query builder escape hatch, auto CRUD APIs via

zenstack-crud-server

Already on ZenStack V2? Start here (V2 was Prisma-based), then apply the V2→V3 deltas in
zenstack-project-setup
(package renames, policy plugin,
post-update
/
before()
, types+mixins, grouped hooks).

验证流程：

zen generate

→ typecheck → 运行测试套件/应用。然后逐步采用 ZenStack 的增值功能（访问控制、query builder 逃生通道、通过

zenstack-crud-server

实现自动 CRUD API）。

已经使用 ZenStack V2？请从这里开始（V2 基于 Prisma），然后应用
zenstack-project-setup
中的 V2→V3 差异项（package 重命名、policy plugin、
post-update
/
before()
、types+mixins、grouped hooks）。

Reference docs

参考文档

Full ZenStack documentation for this topic is bundled under

references/

migrate-prisma.md — official "Migrating from Prisma" guide

本主题的完整 ZenStack 文档打包在

references/

下：

migrate-prisma.md — 官方 "Migrating from Prisma" 指南