zenstack-db-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZenStack V3 — Database Migrations

ZenStack V3 — 数据库迁移

ZenStack keeps your database schema in sync with your ZModel data model. Migration is built on top of Prisma Migrate: the

zen

CLI generates a Prisma schema from your ZModel under the hood and wraps the corresponding Prisma command. If you know Prisma Migrate, the workflow is identical — just swap

prisma

for

zen

. Existing migration history keeps working once moved into ZenStack's layout (

prisma/migrations

→

zenstack/migrations

, the default location next to

zenstack/schema.zmodel

This skill assumes a project is already set up (see

zenstack-project-setup

). Schema authoring is in

zenstack-schema-modeling

@zenstackhq/cli

carries a peer dependency on

prisma

, installed automatically when needed.

Run
zen generate
after schema changes to refresh generated types; migration commands operate on the schema independently of the generated client.

ZenStack 让数据库 Schema 与你的 ZModel 数据模型保持同步。迁移功能建立在 Prisma Migrate 之上：

zen

CLI 会在底层从 ZModel 生成 Prisma Schema，并封装对应的 Prisma 命令。如果你熟悉 Prisma Migrate，工作流程完全相同，只需将

prisma

换成

zen

。迁移到 ZenStack 的目录结构后，现有迁移历史仍然可用（

prisma/migrations

→

zenstack/migrations

，默认位置与

zenstack/schema.zmodel

相邻）。

本 skill 假定项目已经完成设置（参见

zenstack-project-setup

）。Schema 建模请参见

zenstack-schema-modeling

。

@zenstackhq/cli

将

prisma

作为 peer dependency，需要时会自动安装。

Schema 更改后运行
zen generate
以刷新生成的类型；迁移命令独立于生成的 Client，直接对 Schema 进行操作。

Two ways to evolve the schema

演进 Schema 的两种方式

Approach	Command	When
Schema prototyping	`zen db push`	Local dev/experimentation — syncs the DB to the schema with no migration file. Fast, but loses history. Never in production.
Tracked migrations	`zen migrate dev` → `zen migrate deploy`	Anything you ship — generates reviewable, committed SQL migration files applied deterministically across environments.

Typical loop: prototype with

db push

while iterating, then create a migration with

migrate dev

once the shape settles.

方法	命令	使用场景
Schema 原型设计	`zen db push`	本地开发或实验——将数据库同步至 Schema，不生成迁移文件。速度快，但不会保留历史记录。切勿在生产环境中使用。
受跟踪的迁移	`zen migrate dev` → `zen migrate deploy`	任何需要发布上线的场景——生成可审查、可提交到源码控制的 SQL 迁移文件，并在各个环境中确定性地应用。

典型流程：迭代时使用

db push

进行原型开发，待结构确定后，再使用

migrate dev

创建迁移。

Commands

命令

All migration/db commands accept

--schema <file>

(defaults to

zenstack/schema.zmodel

) and

--migrations <path>

(the directory holding

migrations/

所有迁移和数据库命令都接受

--schema <file>

（默认为

zenstack/schema.zmodel

）和

--migrations <path>

（存放

migrations/

的目录）。

zen migrate dev

— create + apply a migration (development)

zen migrate dev

— 创建并应用迁移（开发环境）

Diffs the schema against migration history, generates a new timestamped migration file, and applies it to the dev database. Prompts if a full reset is required (e.g. drift).

bash

zen migrate dev --name add_published_flag

```
-n, --name <name>
```
— name the migration (otherwise you're prompted).
```
--create-only
```
— generate the migration file without applying it. Use this to hand-edit SQL, or to implement features the migration engine doesn't generate yet (e.g. database views — create an empty migration and write the SQL manually), then apply later with
```
zen migrate dev
```
.

Review the generated SQL before committing it to source control.

将 Schema 与迁移历史进行差异比较，生成一个带时间戳的新迁移文件，并将其应用到开发数据库。如果需要完全重置（例如存在 Schema drift），会提示你确认。

bash

zen migrate dev --name add_published_flag

```
-n, --name <name>
```
— 指定迁移名称（否则会提示输入）。
```
--create-only
```
— 仅生成迁移文件，不应用该文件。如果需要手动编辑 SQL，或实现迁移引擎尚不能生成的功能（例如数据库视图——创建一个空迁移并手动编写 SQL），可以使用此选项，之后再通过
```
zen migrate dev
```
应用。

将生成的 SQL 提交到源码控制前，请先进行审查。

zen migrate deploy

— apply pending migrations (production)

zen migrate deploy

— 应用待处理迁移（生产环境）

Applies all not-yet-applied migrations. Idempotent and non-interactive — this is the command for your deployment pipeline. It never generates new migrations or resets data.

bash

zen migrate deploy

应用所有尚未应用的迁移。该命令具有幂等性且无需交互，是部署流水线应使用的命令。它不会生成新迁移，也不会重置数据。

bash

zen migrate deploy

zen migrate status

— inspect migration state

zen migrate status

— 检查迁移状态

Shows which migrations are applied vs. pending. Useful in CI before deploying.

bash

zen migrate status

显示哪些迁移已应用、哪些迁移待应用。在部署前用于 CI 检查非常有用。

bash

zen migrate status

zen migrate resolve

— fix history without touching the schema

zen migrate resolve

— 修复迁移历史而不修改 Schema

Marks a migration as applied or rolled back — for manual recovery (e.g. a migration applied out-of-band, or a failed one). Does not change the database schema.

bash

zen migrate resolve --applied 20240101120000_add_users
zen migrate resolve --rolled-back 20240101120000_add_users

将迁移标记为已应用或已回滚，用于手动恢复（例如迁移曾被带外应用，或某个迁移执行失败）。不会更改数据库 Schema。

bash

zen migrate resolve --applied 20240101120000_add_users
zen migrate resolve --rolled-back 20240101120000_add_users

zen migrate reset

— wipe and reapply (development)

zen migrate reset

— 清除并重新应用迁移（开发环境）

Drops all tables and replays every migration from scratch. Destructive — dev/testing only, never production.

bash

zen migrate reset --force   # --force skips the confirmation prompt

If a seed script is configured, it runs after reset (use

--skip-seed

to skip).

删除所有表，并从头重新执行每个迁移。该操作具有破坏性——仅限开发或测试环境，切勿在生产环境中使用。

bash

zen migrate reset --force   # --force skips the confirmation prompt

如果配置了种子脚本，重置后会自动运行该脚本（使用

--skip-seed

可跳过）。

zen db push

— sync schema, no migration file (development)

zen db push

— 同步 Schema，不生成迁移文件（开发环境）

Pushes the schema straight to the database. Great for rapid prototyping; no history is recorded.

bash

zen db push
zen db push --accept-data-loss   # proceed despite data-loss warnings
zen db push --force-reset        # reset the DB before pushing

直接将 Schema 推送到数据库。适合快速原型开发；不会记录迁移历史。

bash

zen db push
zen db push --accept-data-loss   # proceed despite data-loss warnings
zen db push --force-reset        # reset the DB before pushing

zen db pull

— introspect an existing database (v3.4.0+, experimental)

zen db pull

— 对现有数据库进行内省（v3.4.0+，实验性）

Loads the database schema, diffs it against your ZModel, and updates the ZModel to match. Useful for adopting ZenStack on an existing DB, or re-syncing after out-of-band DB changes. This has its own implementation (not Prisma's introspection engine).

bash

zen db pull

Options:

-o, --output <path>

--model-casing <pascal|camel|snake|none>

(default

pascal

--field-casing <...>

(default

camel

--always-map

(always emit

@map

@@map

--quote <double|single>

(default

single

--indent <number>

(default

Warning:
zen db pull
can overwrite your schema file. Commit or back it up first.

加载数据库 Schema，将其与 ZModel 进行差异比较，并更新 ZModel 以使其保持一致。适用于在现有数据库上采用 ZenStack，或在数据库发生带外更改后重新同步。该命令使用自己的实现，而不是 Prisma 的 introspection engine。

bash

zen db pull

选项：

-o, --output <path>

、

--model-casing <pascal|camel|snake|none>

（默认为

pascal

）、

--field-casing <...>

（默认为

camel

）、

--always-map

（始终生成

@map

@@map

）、

--quote <double|single>

（默认为

single

）、

--indent <number>

（默认为

）。

警告：
zen db pull
可能覆盖你的 Schema 文件。请先提交或备份该文件。

zen db seed

— seed the database

zen db seed

— 初始化数据库种子数据

Runs the seed script declared in

package.json

under

zenstack.seed

json

{ "zenstack": { "seed": "tsx ./zenstack/seed.ts" } }

bash

zen db seed
zen db seed -- --users 10   # args after -- are forwarded to the seed script

运行

package.json

中在

zenstack.seed

下声明的种子脚本：

json

{ "zenstack": { "seed": "tsx ./zenstack/seed.ts" } }

bash

zen db seed
zen db seed -- --users 10   # args after -- are forwarded to the seed script

Workflows

工作流

Development

Edit
```
zenstack/schema.zmodel
```
.
```
zen db push
```
to try it instantly while iterating (optionally
```
zen db seed
```
).
When the shape is final,
```
zen migrate dev --name <change>
```
to create the migration.
Review the SQL, commit the migration file.

Production / CI deployment

bash

zen migrate deploy

Run it in the release pipeline. Optionally gate on

zen migrate status

first. Do not run

db push

migrate dev

, or

migrate reset

against production.

Adopt an existing database

zen init

→ set the datasource

url

→

zen db pull

→ refine the schema (policies, computed fields) →

zen generate

. See

zenstack-project-setup

开发环境

编辑
```
zenstack/schema.zmodel
```
。
迭代时运行
```
zen db push
```
以立即应用更改（也可以选择运行
```
zen db seed
```
）。
结构最终确定后，运行
```
zen migrate dev --name <change>
```
创建迁移。
审查 SQL，然后提交迁移文件。

生产环境 / CI 部署

bash

zen migrate deploy

在发布流水线中运行该命令。也可以先用

zen migrate status

设置部署前的检查关卡。不要对生产环境运行

db push

、

migrate dev

或

migrate reset

。

采用现有数据库

zen init

→ 设置数据源

url

→

zen db pull

→ 完善 Schema（policies、computed fields） →

zen generate

。参见

zenstack-project-setup

。

Adopting from Prisma

从 Prisma 迁移

Because migration wraps Prisma Migrate, your existing migration history keeps working once you move the

prisma/migrations

directory to

zenstack/migrations

(ZenStack's default, next to

zenstack/schema.zmodel

) and replace the

prisma migrate ...

prisma db ...

scripts with the

zen

equivalents. Full framework migration is covered by

zenstack-migrate-from-prisma

由于迁移功能封装了 Prisma Migrate，将现有的

prisma/migrations

目录移动到

zenstack/migrations

（ZenStack 的默认位置，与

zenstack/schema.zmodel

相邻），并将

prisma migrate ...

prisma db ...

脚本替换为对应的

zen

命令后，现有迁移历史仍然可用。完整的框架迁移流程参见

zenstack-migrate-from-prisma

。

Reference docs

参考文档

Full ZenStack documentation for this topic is bundled under

references/

migration.md — migration concepts and workflows
introspection.md —
```
zen db pull
```
introspection
cli-reference.md — complete
```
migrate
```
/
```
db
```
command + option reference

本主题的完整 ZenStack 文档随附于

references/

：

migration.md — 迁移概念与工作流
introspection.md —
```
zen db pull
```
内省
cli-reference.md — 完整的
```
migrate
```
/
```
db
```
命令及选项参考

zenstack-db-migration

Original

Translation

ZenStack V3 — Database Migrations

ZenStack V3 — 数据库迁移

Two ways to evolve the schema

演进 Schema 的两种方式

Commands

命令

`zen migrate dev`
— create + apply a migration (development)

`zen migrate dev`
— 创建并应用迁移（开发环境）

`zen migrate deploy`
— apply pending migrations (production)

`zen migrate deploy`
— 应用待处理迁移（生产环境）

`zen migrate status`
— inspect migration state

`zen migrate status`
— 检查迁移状态

`zen migrate resolve`
— fix history without touching the schema

`zen migrate resolve`
— 修复迁移历史而不修改 Schema

`zen migrate reset`
— wipe and reapply (development)

`zen migrate reset`
— 清除并重新应用迁移（开发环境）

`zen db push`
— sync schema, no migration file (development)

`zen db push`
— 同步 Schema，不生成迁移文件（开发环境）

`zen db pull`
— introspect an existing database (v3.4.0+, experimental)

`zen db pull`
— 对现有数据库进行内省（v3.4.0+，实验性）

`zen db seed`
— seed the database

`zen db seed`
— 初始化数据库种子数据

Workflows

工作流

Adopting from Prisma

从 Prisma 迁移

Reference docs

参考文档