跳到主要内容

合并迁移

本指南描述了如何将多个迁移文件合并为一个单独的迁移。

关于合并迁移​

有时将部分或全部迁移文件合并为一个单独的迁移会很有用。本指南将描述你可能想要这样做的两种场景

在这两种情况下，Prisma Migrate 都提供了执行此操作的工具，通过使用 migrate diff 命令来比较两个数据库 schema 并输出一个单独的 SQL 文件，该文件将你从一个 schema 迁移到另一个 schema。本指南的其余部分详细说明了如何在这两种场景中执行此操作。

从开发环境干净地迁移​

当使用基于分支的工作流进行开发时，合并迁移可能很有用。在功能分支上进行大型本地开发工作期间，你可能会使用 migrate dev 生成多个迁移。功能完成后，迁移历史记录可能包含不必要的中间步骤，这些步骤在将推送到 main 分支的最终迁移历史记录中是不需要的。

可能存在避免在生产环境中应用中间步骤的重要原因——它们可能会丢失数据或非常缓慢/破坏性的。即使不是这种情况，你也可能希望避免生产环境的迁移历史记录中出现混乱。

有关如何使用 migrate dev 实现此目的的详细步骤，请参阅关于 如何从开发环境干净地迁移 的部分。

在生产环境中创建干净的历史记录​

合并迁移也可以在生产环境中使用，将所有迁移文件合并为一个。当生产环境积累了较长的迁移历史记录，并且由于中间步骤需要额外的时间，在新环境中重放迁移历史记录已成为负担时，这会很有用。由于团队没有从迁移步骤中获得价值（并且可以在紧急情况下从版本控制历史记录中找回它们），因此决定将整个历史记录合并为一个单独的迁移。

有关如何使用 migrate diff 和 migrate resolve 实现此目的的详细步骤，请参阅关于 如何在生产环境中创建干净的历史记录 的部分。

合并迁移时的注意事项​

警告

当合并迁移时，请注意你的 migration.sql 文件中任何手动更改或添加的 SQL 都不会被保留。如果你的迁移文件有自定义添加，例如视图或触发器，请确保在迁移合并后重新添加它们。

如何合并迁移​

本节提供了关于如何在上面讨论的两种场景中合并迁移的逐步说明

如何从开发环境干净地迁移​

在合并迁移之前，请确保你具备以下起始条件

  • 要合并的迁移的内容尚未应用到生产数据库
  • 已应用到生产环境的所有迁移都已是本地迁移历史记录的一部分
  • 你在分支中添加的任何新迁移文件中都没有自定义 SQL
信息

如果在你创建功能分支后，生产数据库上的迁移历史记录已发散，那么你需要首先将生产环境的迁移历史记录和数据模型更改合并到你的本地历史记录中。

然后按照这些步骤操作

  1. 重置你的本地 ./prisma/migrations 文件夹的内容，以匹配 main 分支上的迁移历史记录

  2. 创建一个新的迁移

    npx prisma migrate dev --name squashed_migrations

    这将创建一个单独的迁移，它将你从

    • 从 main 分支的状态（如你的重置迁移历史记录中所述）
    • 到你的本地功能的状态（如你的 ./prisma/schema.prisma 文件中所述）
    • 并将此输出到新目录中以 squashed_migrations 结尾的新 migration.sql 文件（使用 --name 标志指定）

这个单独的迁移文件现在可以使用 migrate deploy 应用到生产环境。

如何在生产环境中创建干净的历史记录​

在合并迁移之前，请确保你具备以下起始条件

  • 迁移历史记录中的所有迁移都已应用到生产数据库
  • 数据模型与迁移历史记录匹配
  • 数据模型和迁移历史记录同步

然后按照这些步骤操作，可以在你的 main 分支上，也可以在新的检出分支上进行，该分支在其他任何更改之前合并回 main

  1. 删除 ./prisma/migrations 目录的所有内容

  2. 在 ./prisma/migrations 目录中创建一个新的空目录。在本指南中，这将被称为 000000000000_squashed_migrations。在此目录下，添加一个新的空 migration.sql 文件。

    信息

    我们将迁移命名为 000000000000_squashed_migrations 并带有所有前导零，因为我们希望它成为迁移目录中的第一个迁移。Migrate 按照目录中的迁移的字典顺序（字母顺序）运行迁移。这就是为什么当你使用 migrate dev 时，它会生成带有日期和时间作为前缀的迁移。你可以给迁移另一个名称，只要它排序低于以后的迁移，例如 0_squashed 或 202207180000_squashed。

  3. 创建一个单独的迁移，它将你从

    • 从一个空数据库
    • 到生产数据库 schema 的当前状态（如你的 ./prisma/schema.prisma 文件中所述）
    • 并将此输出到上面创建的 migration.sql 文件

    你可以使用 migrate diff 命令执行此操作。从你的项目的根目录，运行以下命令

    npx prisma migrate diff \
     --from-empty \
     --to-schema-datamodel ./prisma/schema.prisma \
     --script > ./prisma/migrations/000000000000_squashed_migrations/migration.sql

  4. 将此迁移标记为已在生产环境中应用，以防止它在那里运行

    你可以使用 migrate resolve 命令将 000000000000_squashed_migrations 目录中的迁移标记为已应用

    npx prisma migrate resolve \
     --applied 000000000000_squashed_migrations

你现在应该有一个单独的迁移文件，该文件被标记为已在生产环境中应用。新的检出只会获得一个单独的迁移，使其达到生产数据库 schema 的状态。

生产数据库仍然在迁移表中包含已应用的迁移的历史记录。迁移文件夹和数据模型的历史记录也仍然在源代码控制中可用。