zenstack-project-setup

ZenStack V3 — 项目设置与迁移

ZenStack V3 是一款 TypeScript 数据库工具包，基于 Kysely 构建，提供兼容 Prisma 的 ORM API（不使用 Rust/WASM）。其架构使用 ZModel（.zmodel）编写，这是 Prisma 架构语言的超集。本技能涵盖安装、脚手架、CLI 和迁移。有关架构语法，请参阅 zenstack-schema-modeling；有关查询，请参阅 zenstack-querying；有关访问控制，请参阅 zenstack-access-control。

如果发现内容有误，请务必对照实时文档 https://zenstack.dev/docs 确认准确的包版本和命令 — V3 更新很快。

先决条件

• Node.js v20+
• TypeScript v5.8.0+
• VSCode 扩展：“ZenStack V3”（语言 ID zmodel-v3）— 与 V2 扩展不同。

安装

创建新项目（推荐）

npm create zenstack my-project

在现有项目中初始化 ZenStack

npx @zenstackhq/cli zen init

然后创建 zenstack/schema.zmodel 并运行 zen generate。

手动安装

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

仅在需要时添加访问控制：npm install @zenstackhq/plugin-policy（参见 zenstack-access-control）。

项目结构

• 架构：zenstack/schema.zmodel（默认；使用 --schema 覆盖）。
• 生成的输出：输出到架构文件旁边（使用 --output 覆盖）。导入方式为 import { schema } from './zenstack/schema'。
• 你可以提交生成的 TypeScript，也可以将其加入 .gitignore，并在 CI 中运行 zen generate。

zen CLI

CLI 命令为 zen（或 zenstack — 两者等效）。在 package.json 中添加脚本：

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

命令	用途
zen check	仅验证 schema.zmodel 是否存在语法和语义错误 — 不会重新生成任何内容。仅想确认架构有效时使用。
zen generate	将 schema.zmodel 编译为 TypeScript（重新生成数据库客户端）；编译时也会验证架构。每次修改架构后都要运行，然后再使用客户端。标志：--schema <path>、--output <path>。
zen db push	将架构推送到数据库，但不生成迁移文件。仅用于开发/测试 — 切勿用于生产环境。
zen db pull	检查现有数据库并更新 ZModel 架构（v3.4.0+，实验性功能）。可能覆盖架构 — 请先备份或使用源代码管理。
zen migrate dev	根据架构变更创建迁移并应用（仅限开发环境）。--create-only 会创建一个空迁移，供手动编辑（例如用于视图）。
zen migrate deploy	应用所有待处理的迁移。在生产/部署流水线中使用。
zen migrate reset	删除所有表并重新应用迁移。仅用于开发/测试。
zen migrate status	显示已应用和待处理的迁移。
zen migrate resolve	在不更改架构的情况下，将迁移标记为已应用/已回滚（手动恢复）。

迁移命令封装了 Prisma Migrate；@zenstackhq/cli 依赖同级依赖 prisma，并会在需要时自动安装。

有关完整的迁移说明 — migrate dev/deploy/reset/status/resolve、db push/pull、 填充数据、--create-only 以及部署流水线指南 — 请参阅 zenstack-db-migration 技能。

工作流

开发循环

1. 编辑 zenstack/schema.zmodel。
2. 运行 zen generate（重新生成类型）。
3. 运行 zen db push，在本地尝试更改而不创建迁移，或者运行 zen migrate dev，创建可供审查和提交的迁移文件。
4. 审查迁移 SQL，然后提交。

生产环境部署

zen migrate deploy

在现有数据库上采用 ZenStack

1. 运行 zen init
2. 在 zenstack/schema.zmodel 中设置数据源 url。
3. 运行 zen db pull，从数据库生成架构。
4. 完善架构（添加访问策略、计算字段等）。
5. 运行 zen generate。

从 Prisma 迁移

请参阅专门的 zenstack-migrate-from-prisma 技能——它将指导你替换依赖项、将 schema.prisma 转换为 ZModel、将 PrismaClient 替换为 ZenStackClient、更新生成和迁移脚本，以及映射 Prisma 自定义生成器和客户端扩展。

从 ZenStack V2 迁移

请参阅专门的 zenstack-migrate-from-v2 技能——它涵盖包重命名、将访问控制移至策略插件、future() → post-update/before() 的变更、将抽象模型改为类型+混入、服务器适配器从 getPrisma → getClient 的变更，以及客户端钩子的迁移。

参考文档

本主题的完整 ZenStack 文档位于 references/ 目录下：

• prerequisite.md — 支持的 Node/TypeScript 版本、IDE 设置
• quick-start.md — 脚手架搭建和安装方式
• cli.md — 所有 zen CLI 命令概览
• cli-reference.md — 完整 CLI 参考
• migration.md — 开发和生产环境的迁移工作流
• introspection.md — 从现有数据库运行 zen db pull