zenstack-db-migration

ZenStack V3 — 数据库迁移

ZenStack 会让数据库架构与 ZModel 数据模型保持同步。迁移基于 Prisma Migrate 构建：zen CLI 会在底层根据你的 ZModel 生成 Prisma 架构，并封装相应的 Prisma 命令。如果你熟悉 Prisma Migrate，工作流完全相同——只需将 prisma 换成 zen。将现有迁移历史移入 ZenStack 的目录结构（prisma/migrations → zenstack/migrations，默认位于 zenstack/schema.zmodel 旁边）后，即可继续使用。

本文假设项目已完成设置（参见 zenstack-project-setup）。架构编写请参见 zenstack-schema-modeling。@zenstackhq/cli 对 prisma 有一个对等依赖，需要时会自动安装。

架构变更后运行 zen generate 以刷新生成的类型；迁移命令会独立于生成的客户端操作架构。

演进架构的两种方式

方式	命令	适用场景
架构原型开发	zen db push	本地开发／试验——将数据库同步到架构，不生成迁移文件。速度快，但会丢失历史记录。切勿用于生产环境。
跟踪迁移	zen migrate dev → zen migrate deploy	任何需要发布的内容——生成可供审查并提交的 SQL 迁移文件，在各环境中以确定性方式应用。

典型流程：迭代时使用 db push 进行原型开发，架构形态稳定后，再使用 migrate dev 创建迁移。

命令

所有迁移／数据库命令都接受 --schema <file>（默认为 zenstack/schema.zmodel）和 --migrations <path>（存放 migrations/ 的目录）。

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

将架构与迁移历史进行比对，生成带时间戳的新迁移文件，并将其应用到开发数据库。如果需要完全重置（例如检测到偏移），会提示你确认。

zen migrate dev --name add_published_flag

• -n, --name <name> — 为迁移命名（否则会提示你输入）。
• --create-only — 生成迁移文件，但不应用。可用它手动编辑 SQL，或实现迁移引擎尚不能生成的功能（例如数据库视图——创建一个空迁移并手动编写 SQL），之后再使用 zen migrate dev 应用。

提交到源代码管理之前，请检查生成的 SQL。

zen migrate deploy — 应用待处理的迁移（生产）

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

zen migrate deploy

zen migrate status — 检查迁移状态

显示哪些迁移已应用、哪些仍待处理。适合在部署前用于 CI。

zen migrate status

zen migrate resolve — 修正历史记录，不触碰架构

将迁移标记为已应用或已回滚，用于手动恢复（例如，迁移在其他途径中已应用，或迁移失败）。不会更改数据库架构。

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

zen migrate reset — 清空并重新应用（开发）

删除所有表，并从头重放每个迁移。此操作具有破坏性——仅限开发／测试，切勿用于生产环境。

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

如果已配置种子脚本，它会在重置后运行（使用 --skip-seed 可跳过）。

zen db push — 同步架构，不生成迁移文件（开发）

直接将架构推送到数据库。非常适合快速原型开发；不会记录历史。

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 — introspection an existing database (v3.4.0+, experimental)

加载数据库架构，将其与 ZModel 对比，并更新 ZModel 使其保持一致。适用于在现有数据库上采用 ZenStack，或在数据库发生带外更改后重新同步。此功能有自己的实现（而非 Prisma 的内省引擎）。

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>（默认值为 4）。

Warning： zen db pull 可能会覆盖你的架构文件。请先提交或备份。

zen db seed — 为数据库填充种子数据

运行 package.json 中 zenstack.seed 下声明的种子脚本：

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

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

工作流

开发

1. 编辑 zenstack/schema.zmodel。
2. 迭代时运行 zen db push 立即试用（可选运行 zen db seed）。
3. 架构定型后，运行 zen migrate dev --name <change> 创建迁移。
4. 检查 SQL，并提交迁移文件。

生产环境 / CI 部署

zen migrate deploy

在发布流水线中运行。也可以先通过 zen migrate status 进行检查。不要在生产环境中运行 db push、migrate dev 或 migrate reset。

采用现有数据库

zen init → 设置数据源 url → zen db pull → 完善架构（策略、计算字段）→ zen generate。参见 zenstack-project-setup。

从 Prisma 迁移

由于迁移功能封装了 Prisma Migrate，只要将现有迁移历史目录 prisma/migrations 移至 zenstack/migrations（ZenStack 的默认位置，与 zenstack/schema.zmodel 同级），并将 prisma migrate ... / prisma db ... 脚本替换为对应的 zen 命令，现有迁移历史就能继续使用。完整的框架迁移说明见 zenstack-migrate-from-prisma。

参考文档

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

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