Chapter 04

Prisma Migrate

掌握从开发迭代到生产部署的完整迁移工作流：migrate dev、迁移文件、migrate deploy、db push 与漂移处理。

4.1 迁移的核心概念

迁移（migration）
一段把数据库结构从旧状态演进到新状态的 SQL 脚本。Prisma 把每次变更记录为 prisma/migrations/ 下带时间戳的目录。
migrate dev
开发命令：对比 schema 与迁移历史，生成新迁移 SQL、应用到开发库，并重新 generate Client。可能触发库重置（数据丢失）。
migrate deploy
生产命令：只按顺序应用尚未执行的迁移文件，不生成新迁移、不重置库、不改 schema。CI/CD 与生产环境用它。
db push
原型模式：直接把 schema 推送到数据库使二者一致，不生成迁移文件。适合快速试验，不适合有迁移历史的生产。
schema drift（模式漂移）
数据库实际结构与迁移历史期望的不一致（如有人手改了库）。Prisma 检测到会警告，避免盲目应用迁移。
_prisma_migrations 表
Prisma 在目标库自动维护的元数据表，记录哪些迁移已应用、校验和是否匹配，是迁移状态的事实来源。

4.2 开发工作流：migrate dev

# 改完 schema.prisma 后
$ npx prisma migrate dev --name add_post_table

# 它会：
# 1) 依据 schema 与历史 diff 出 SQL
# 2) 在 prisma/migrations/20260707_add_post_table/migration.sql 落盘
# 3) 应用到开发数据库
# 4) 自动 prisma generate 更新 Client 类型

生成的迁移文件是纯 SQL，可 review、可手改（如加数据回填逻辑）：

-- migration.sql
CREATE TABLE "Post" (
  "id" SERIAL NOT NULL,
  "title" TEXT NOT NULL,
  "authorId" INTEGER NOT NULL,
  CONSTRAINT "Post_pkey" PRIMARY KEY ("id")
);

4.3 生产工作流：migrate deploy

# CI/CD 或部署脚本里（幂等、安全）
$ npx prisma migrate deploy
生产禁用 migrate dev

migrate dev 会在检测到漂移或不可逆变更时重置数据库，生产上会清空数据。生产环境只用 migrate deploy；它只顺序应用未执行的迁移，永不生成新迁移或重置。

4.4 db push：原型模式

$ npx prisma db push          # 让库结构匹配 schema，不生成迁移
$ npx prisma db push --accept-data-loss  # 允许删列等破坏性变更
场景推荐命令
本地快速试模型db push
团队/需要历史migrate dev
生产/CI 部署migrate deploy
MongoDB（无迁移概念）db push

4.5 查看状态与处理漂移

$ npx prisma migrate status   # 查看已应用/待应用/漂移
$ npx prisma migrate resolve --applied 20260707_xxx  # 标记某迁移已手动应用
$ npx prisma migrate reset     # 清库 + 重放所有迁移 + 跑 seed（仅开发）
reset 会清空数据

migrate reset 删库重建、重放全部迁移并执行 seed 脚本，仅用于开发环境重置到干净状态，切勿对生产执行。

4.6 迁移中的数据变换

加非空列到已有数据的表时，纯 CREATE/ALTER 会失败。推荐展开-收缩（expand-contract）三步：先加可空列并生成迁移；手动在 SQL 里回填数据；再改为非空生成第二个迁移。

-- 手动编辑迁移 SQL 加回填
ALTER TABLE "User" ADD COLUMN "slug" TEXT;
UPDATE "User" SET "slug" = lower("name") WHERE "slug" IS NULL;
ALTER TABLE "User" ALTER COLUMN "slug" SET NOT NULL;

4.7 从已有数据库引入：introspect

$ npx prisma db pull          # 反向工程：读现有库结构生成 schema.prisma

接手遗留库时用 db pull 生成初始 schema，再 generate 得到 Client，之后即可切到迁移工作流。

4.8 小结与下一步