zenstack-migrate-from-prisma

从 Prisma 迁移到 ZenStack V3

ZenStack V3 旨在为 Prisma 提供无缝升级路径：它保留了与 Prisma 兼容的查询 API，并提供超集于 Prisma schema 的模式语言（ZModel）。大多数应用只需进行机械式修改，无需重写查询。支持的数据库：PostgreSQL、MySQL、SQLite。

常规设置和 CLI 详情请参阅 zenstack-project-setup；客户端和方言请参阅 zenstack-querying；模式语法请参阅 zenstack-schema-modeling。

概览

Prisma	ZenStack V3
prisma、@prisma/client	@zenstackhq/cli（开发依赖）、@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）

第 1 步 — 替换依赖项

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 依赖，需要执行迁移命令时会自动安装（ZenStack 的迁移命令会封装 Prisma Migrate）。

第 2 步 — 移动并重命名模式文件

将 schema.prisma 移至 zenstack/schema.zmodel。无需修改 — 所有有效的 Prisma schema 都是有效的 ZModel。可选的清理工作：

• 删除 generator client { ... } 块（它在 ZenStack 中不起作用 — 代码生成由 zen generate 驱动）。
• 保留 datasource 块；其 url 会被迁移引擎使用（ORM 运行时则从驱动和方言获取连接）。
• 如果使用了 Prisma 的多文件/多 schema 功能，请使用 ZModel import 语句合并文件。

继续操作前，运行 zen check 确认转换后的模式有效（语法和语义均有效）。

完成迁移后，即可开始使用 Prisma 不具备的 ZenStack 专属功能 — 访问策略（zenstack-access-control）、@@delegate 多态、类型化 JSON、混入、计算字段（zenstack-schema-modeling）。

第 3 步 — 更新生成脚本

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

每次修改模式后，都要先运行 zen generate，再使用客户端。

第 4 步 — 替换客户端

将 new PrismaClient() 替换为 new ZenStackClient(schema, { dialect })，为所用驱动提供 Kysely 方言（所有方言请参阅 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 兼容。

第 5 步 — 更新类型引用

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

大多数代码依赖推断类型，无需显式导入。

第 6 步 — 更新迁移脚本

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

将现有迁移历史从 prisma/migrations 移至 zenstack/migrations（ZenStack 的默认位置，与 zenstack/schema.zmodel 同级）。由于 ZenStack 的迁移命令会封装 Prisma Migrate，因此可以继续原样使用。完整迁移工作流请参阅 zenstack-db-migration 技能。

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

如果依赖会读取 schema.prisma 的 Prisma 自定义生成器（例如 zod、ERD、类型生成器），请使用 @core/prisma 插件继续生成该文件，并串联执行这些命令：

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

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

Prisma Client 扩展的映射

Prisma 扩展	ZenStack 对应项
Query 扩展（拦截调用）	通过 db.$use(...) 添加运行时插件，并使用 onQuery 钩子
Result 扩展（计算字段）	在 ZModel 中定义 @computed 字段，并在 ZenStackClient 上设置 computedFields 选项（参见 zenstack-schema-modeling）

迁移后

通过以下步骤进行验证：zen generate → 类型检查 → 运行测试套件 / 应用。然后逐步采用 ZenStack 的增值功能（访问控制、查询构建器逃生口、通过 zenstack-crud-server 自动生成 CRUD API）。

已在使用 ZenStack V2？请从这里开始（V2 基于 Prisma），然后在 zenstack-project-setup 中应用 V2→V3 的差异（包重命名、策略插件、 post-update/before()、类型 + 混入、分组钩子）。

参考文档

此主题的完整 ZenStack 文档已打包在 references/ 下：

• migrate-prisma.md — 官方《从 Prisma 迁移》指南