zenstack-project-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZenStack V3 — Project Setup & Migrations

ZenStack V3 — 项目设置与迁移

ZenStack V3 is a TypeScript database toolkit with a Prisma-compatible ORM API built on Kysely (no Rust/WASM). The schema is written in ZModel (

.zmodel

), a superset of the Prisma schema language. This skill covers installing, scaffolding, the CLI, and migrations. For schema syntax see

zenstack-schema-modeling

; for queries see

zenstack-querying

; for access control see

zenstack-access-control

Always confirm exact package versions and commands against the live docs at https://zenstack.dev/docs when something looks off — V3 evolves quickly.

ZenStack V3 是一个 TypeScript 数据库工具包，提供兼容 Prisma 的 ORM API，基于 Kysely 构建（无需 Rust/WASM）。Schema 使用 ZModel（

.zmodel

）编写，它是 Prisma schema 语言的超集。本 skill 涵盖安装、项目脚手架、CLI 和迁移。有关 schema 语法，请参阅

zenstack-schema-modeling

；有关查询，请参阅

zenstack-querying

；有关访问控制，请参阅

zenstack-access-control

。

如果发现任何异常，应始终根据 https://zenstack.dev/docs 上的实时文档核实确切的包版本和命令——V3 演进速度很快。

Prerequisites

前置条件

Node.js v20+
TypeScript v5.8.0+
VSCode extension: "ZenStack V3" (language id
```
zmodel-v3
```
) — distinct from the V2 extension.

Node.js v20+
TypeScript v5.8.0+
VSCode 扩展："ZenStack V3"（language id
```
zmodel-v3
```
）——与 V2 扩展不同。

Installing

安装

Scaffold a new project (recommended)

创建新项目脚手架（推荐）

bash

npm create zenstack my-project

bash

npm create zenstack my-project

Initialize ZenStack in an existing project

在现有项目中初始化 ZenStack

bash

npx @zenstackhq/cli zen init

Then create

zenstack/schema.zmodel

and run

zen generate

bash

npx @zenstackhq/cli zen init

然后创建

zenstack/schema.zmodel

并运行

zen generate

。

Manual install

手动安装

bash

npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli

ZenStack does not bundle database drivers — install one yourself:

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`

Add access control only if needed:

npm install @zenstackhq/plugin-policy

(see

zenstack-access-control

bash

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

）。

Project structure

项目结构

Schema:
```
zenstack/schema.zmodel
```
(default; override with
```
--schema
```
).
Generated output: emitted next to the schema (override with
```
--output
```
). Import it as
```
import { schema } from './zenstack/schema'
```
.
You may commit the generated TypeScript, or
```
.gitignore
```
it and run
```
zen generate
```
in CI.

Schema：
```
zenstack/schema.zmodel
```
（默认路径；可通过
```
--schema
```
覆盖）。
生成输出：输出到 schema 所在位置（可通过
```
--output
```
覆盖）。按以下方式导入：
```
import { schema } from './zenstack/schema'
```
。
你可以提交生成的 TypeScript，也可以将其加入
```
.gitignore
```
，并在 CI 中运行
```
zen generate
```
。

The

zen

CLI

zen

CLI

The CLI is invoked as

zen

(or

zenstack

— equivalent). Add scripts to

package.json

json

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

Command	Purpose
`zen check`	Only validate `schema.zmodel` for syntax and semantic errors — does not regenerate anything. Use when you just want to confirm the schema is valid.
`zen generate`	Compile `schema.zmodel` → TypeScript (regenerate the database client); also validates the schema as it compiles. Run after every schema change, before using the client. Flags: `--schema <path>` , `--output <path>` .
`zen db push`	Push schema to the DB without a migration file. Dev/testing only — never in production.
`zen db pull`	Introspect an existing DB and update the ZModel schema (v3.4.0+, experimental). Can overwrite your schema — back up / use source control first.
`zen migrate dev`	Create a migration from schema changes and apply it (dev only). `--create-only` makes an empty migration to edit by hand (e.g. for views).
`zen migrate deploy`	Apply all pending migrations. Use this in your production/deploy pipeline.
`zen migrate reset`	Drop all tables and reapply migrations. Dev/testing only.
`zen migrate status`	Show applied vs. pending migrations.
`zen migrate resolve`	Mark a migration applied/rolled-back without changing the schema (manual recovery).

Migration commands wrap Prisma Migrate;
@zenstackhq/cli
has a peer dependency on
prisma
that is installed automatically when needed.

For the full migration story —

migrate dev

deploy

reset

status

resolve

db push

pull

, seeding,

--create-only

, and deployment-pipeline guidance — see the

zenstack-db-migration

skill.

CLI 通过

zen

调用（或使用等价的

zenstack

）。在

package.json

中添加 scripts：

json

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

命令	用途
`zen check`	仅验证 `schema.zmodel` 是否存在语法和语义错误——不会重新生成任何内容。只需确认 schema 有效时使用此命令。
`zen generate`	将 `schema.zmodel` 编译为 TypeScript（重新生成数据库 client）；同时也会在编译过程中验证 schema。每次修改 schema 后都要运行，然后才能使用 client。参数： `--schema <path>` 、 `--output <path>` 。
`zen db push`	将 schema 推送到 DB，不创建 migration file。仅用于开发/测试——切勿在生产环境中使用。
`zen db pull`	内省现有 DB 并更新 ZModel schema（v3.4.0+，实验性）。它可能覆盖 schema——请先备份或使用版本控制。
`zen migrate dev`	根据 schema 变更创建 migration 并应用（仅限开发环境）。 `--create-only` 会创建一个可手动编辑的空 migration（例如用于 views）。
`zen migrate deploy`	应用所有待处理的 migrations。用于生产/部署 pipeline。
`zen migrate reset`	删除所有表并重新应用 migrations。仅用于开发/测试。
`zen migrate status`	显示已应用和待处理的 migrations。
`zen migrate resolve`	将 migration 标记为已应用或已回滚，但不更改 schema（用于手动恢复）。

Migration 命令封装了 Prisma Migrate；
@zenstackhq/cli
对
prisma
有一个 peer dependency，会在需要时自动安装。

有关完整的 migration 方案——

migrate dev

deploy

reset

status

resolve

、

db push

pull

、seeding、

--create-only

以及部署 pipeline 指南——请参阅

zenstack-db-migration

skill。

Workflows

工作流

Development loop

Edit
```
zenstack/schema.zmodel
```
.
```
zen generate
```
(regenerate types).
```
zen db push
```
to try changes locally without a migration, or
```
zen migrate dev
```
to create a reviewable, committable migration file.
Review the migration SQL, then commit it.

Production deploy

bash

zen migrate deploy

Adopt ZenStack on an existing database

```
zen init
```
Set the datasource
```
url
```
in
```
zenstack/schema.zmodel
```
.
```
zen db pull
```
to generate the schema from the DB.
Refine it (add access policies, computed fields, etc.).
```
zen generate
```
.

开发循环

编辑
```
zenstack/schema.zmodel
```
。
运行
```
zen generate
```
（重新生成 types）。
使用
```
zen db push
```
在本地试用变更而不创建 migration，或使用
```
zen migrate dev
```
创建一个可审查、可提交的 migration file。
审查 migration SQL，然后提交。

生产部署

bash

zen migrate deploy

将 ZenStack 接入现有数据库

```
zen init
```
在
```
zenstack/schema.zmodel
```
中设置 datasource
```
url
```
。
执行
```
zen db pull
```
，从 DB 生成 schema。
完善 schema（添加 access policies、computed fields 等）。
```
zen generate
```
。

Migrating from Prisma

从 Prisma 迁移

See the dedicated

zenstack-migrate-from-prisma

skill — it walks through swapping dependencies, converting

schema.prisma

to ZModel, replacing

PrismaClient

with

ZenStackClient

, updating the generate/migrate scripts, and mapping Prisma custom generators and client extensions.

请参阅专用的

zenstack-migrate-from-prisma

skill——它会逐步讲解如何替换依赖、将

schema.prisma

转换为 ZModel、将

PrismaClient

替换为

ZenStackClient

、更新 generate/migrate scripts，以及映射 Prisma 自定义 generators 和 client extensions。

Migrating from ZenStack V2

从 ZenStack V2 迁移

See the dedicated

zenstack-migrate-from-v2

skill — it covers the package renames, moving access control to the policy plugin, the

future()

→

post-update

before()

change, abstract models → types+mixins, the

getPrisma

→

getClient

server-adapter change, and the client-side hook migration.

请参阅专用的

zenstack-migrate-from-v2

skill——它涵盖包重命名、将访问控制迁移到 policy plugin、

future()

→

post-update

before()

变更、abstract models → types+mixins、

getPrisma

→

getClient

的 server-adapter 变更，以及 client-side hook 迁移。

Reference docs

参考文档

Full ZenStack documentation for this topic is bundled under

references/

prerequisite.md — supported Node/TypeScript versions, IDE setup
quick-start.md — scaffolding and the install paths
cli.md — overview of every
```
zen
```
CLI command
cli-reference.md — full CLI reference
migration.md — dev/production migration workflow
introspection.md —
```
zen db pull
```
from an existing database

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

references/

下：

prerequisite.md——支持的 Node/TypeScript 版本、IDE 设置
quick-start.md——项目脚手架和安装路径
cli.md——每个
```
zen
```
CLI 命令的概览
cli-reference.md——完整的 CLI 参考
migration.md——开发/生产 migration 工作流
introspection.md——从现有数据库执行
```
zen db pull
```

zenstack-project-setup

Original

Translation

ZenStack V3 — Project Setup & Migrations

ZenStack V3 — 项目设置与迁移

Prerequisites

前置条件

Installing

安装

Scaffold a new project (recommended)

创建新项目脚手架（推荐）

Initialize ZenStack in an existing project

在现有项目中初始化 ZenStack

Manual install

手动安装

Project structure

项目结构

The
`zen`
CLI

`zen`
CLI

Workflows

工作流

Migrating from Prisma

从 Prisma 迁移

Migrating from ZenStack V2

从 ZenStack V2 迁移

Reference docs

参考文档