Prisma Migrate 操作指南

阿豪啊
168 阅读4分钟

Prisma Migrate 操作指南

1. 简介与基础概念 (Introduction and Core Concepts)

1.1 什么是 Prisma Migrate？

  • 定义：Prisma 数据库 schema 迁移工具，用于管理数据库结构随应用代码的演变。
  • 核心作用：将 schema.prisma 文件中的模型定义转换为数据库特定的 DDL (Data Definition Language) 语句。

1.2 为什么使用迁移工具？

  • Schema 版本控制：像管理代码一样管理数据库结构。
  • 环境同步：确保开发、测试和生产环境的数据库结构一致。
  • 可重复性：通过迁移文件，可以重复地、安全地应用数据库变更。

1.3 核心哲学：声明式迁移

  • Prisma 不要求你手写 SQL。你只需要修改 schema.prisma，Prisma 会计算出差异并生成迁移文件。借助AI编程工具，甚至都不需要了解Prisma的语法，直接对AI提需求即可完成表的设计。

2. 环境准备与初始化 (Setup and Initialization)

2.1 依赖安装与配置

  • 安装 prisma CLI 和 @prisma/client。
  • 初始化项目 (npm init 或类似)。
  • 创建 schema.prisma 文件并配置 datasource（数据库连接）和 generator（Prisma Client）。

2.2 首次迁移：建立基线

  • 在 schema.prisma 中定义第一个模型。

  • 运行 prisma migrate dev。

    • migrate dev 的作用：创建迁移文件夹，生成初始 SQL，应用到开发数据库。

  • 生成 Prisma Client (prisma generate)，这个作用是为了让代码跟schema中的表结构保持一致，比如新增了User表，如果不执行generate，将无法访问User表。

3. 开发阶段的工作流 (The Development Workflow)

3.1 核心命令：prisma migrate dev

  • 用途：在开发环境中迭代和应用数据库结构更改。

  • 操作流程：

    1. 修改 schema.prisma。
    2. 运行 prisma migrate dev --name <migration_name>，可以认为这里的migration_name是一个注释或者标记。
    3. Prisma 计算差异、生成新的迁移文件（SQL）。
    4. Prisma 将新迁移应用到数据库。

  • 应用实例-首次操作数据库

# 首次执行
npx prisma migrate dev --name init

执行的命令窗口有如下提示内容：

image.png

看图里面触发了两件事，第一件是生成了sql文件，第二件是执行了prisma generate命令。
生成的sql目录以及内容如下：

image.png

  • 应用实例-为已有的表新增字段
    如果我在appointment表增加一个status2字段，如下图现在schema文件中添加字段。
    image.png
    然后执行npx prisma migrate dev --name init2命令，如下：

image.png 在mirations目录下也会生成对应的sql文件，如下：

image.png

那么问题来了，prisma怎么知道哪些sql已经执行了呢？答案在下面这张表。表_prisma_migrations记录了每个目录的执行情况，所以不会重复执行。

image.png

3.2 应对数据丢失 (Handling Data Loss)

  • 何时会出现警告（如删除字段、更改列类型）。
  • 强制应用迁移：使用 --create-only 或 -n 标志来生成文件而不应用。
  • 手动检查生成的 SQL。

3.3 数据库重置 (Resetting the Database)

  • 命令：prisma migrate reset
  • 用途：清空数据库，重新运行所有迁移，并执行 Seeding。
  • 注意：此命令仅用于本地开发环境。

4. 生产环境的部署工作流 (Production Deployment)

4.1 部署命令：prisma migrate deploy

  • 用途：在生产、暂存或 CI/CD 环境中应用已完成的迁移。

  • 特性：

    • 只读取 /prisma/migrations 文件夹中的文件。
    • 只应用尚未在目标数据库上运行过的迁移。
    • 不会创建新的迁移文件。
    • 不会执行数据库重置。

4.2 部署步骤

  1. 确保在 CI/CD 管道中运行 prisma generate。
  2. 确保 prisma/migrations 文件夹与应用代码一起部署。
  3. 运行 prisma migrate deploy。

5. 维护、检查与高级操作 (Maintenance and Advanced)

5.1 查看迁移状态

  • 命令：prisma migrate status
  • 作用：查看哪些迁移已应用、哪些未应用、是否存在不一致。

5.2 数据填充 (Seeding)

  • Seeding 的作用：为数据库填充初始数据（如管理员账户、默认配置等）。
  • Prisma 的 Seeding 配置（在 package.json 中配置 prisma.seed）。
  • 运行 Seeding：prisma db seed 或 prisma migrate dev (如果配置了)。

5.3 故障排除

  • 迁移历史记录不一致 (Diverged History) 的处理。
  • 手动修复迁移文件（仅限专家操作）。
  • 解决连接问题。

6. 总结与最佳实践 (Conclusion and Best Practices)

6.1 总结：dev vs deploy

命令用途适用环境主要动作
migrate dev迭代开发 Schema本地/开发计算差异，创建/更新 SQL，应用 SQL，运行 Seeding
migrate deploy部署到生产环境生产/CI/CD仅应用未运行的 SQL 迁移

6.2 版本控制建议

  • 将 prisma/migrations 文件夹提交到 Git。
  • 不要将 node_modules 或生成的 Prisma Client 提交到 Git。
  • 每个功能分支都应该有自己的迁移文件，并在合并前解决冲突。
avatar
文章
阅读
粉丝