合并迁移

本指南介绍如何将多个 迁移文件 合并到单个迁移中。

关于合并迁移

有时将某些或所有迁移文件合并到单个迁移中会很有用。本指南将介绍可能需要执行此操作的两种场景

• 通过合并本地迁移到一个文件来从开发环境干净地迁移
• 通过将所有迁移合并到一个文件中在生产环境中创建干净的历史记录

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

从开发环境干净地迁移

在使用基于分支的工作流进行开发时，合并迁移可能很有用。在功能分支上的大型本地开发工作期间，您可能会使用 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 文件中描述的本地功能的状态
   • 并将此输出到新目录（使用 --name 标志指定）中以 squashed_migrations 结尾的新 migration.sql 文件中

现在可以使用 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. 创建一个单个迁移，它将您带到

   • 从空数据库
   • 到 ./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

您现在应该拥有一个已标记为已应用于生产环境的单个迁移文件。新的检出仅获得一个将它们带到生产数据库模式状态的单个迁移。

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