修补与热修复

修补或热修复数据库涉及到直接在生产环境中进行通常时间紧迫的更改。例如，你可能直接在生产数据库中添加索引来解决运行缓慢的查询问题。

直接修补生产数据库会导致schema 漂移：你的数据库 schema 已经“偏离”了真理来源，并且与你的迁移历史不同步。你可以使用 prisma migrate resolve 命令来协调你的迁移历史，而无需使用 prisma migrate deploy 删除并重新应用热修复。

警告

本指南不适用于 MongoDB。
对于 MongoDB，使用 db push 而不是 migrate dev。

使用补丁或热修复协调你的迁移历史

以下场景假设你在生产环境中进行了手动更改，并希望将该更改传播到你的迁移历史和其他数据库。

要在生产环境中协调你的迁移历史和数据库 schema

1. 在你 schema 中复制你在生产环境中进行的更改 - 例如，向特定模型添加 @@index。

2. 生成一个新的迁移，并记下完整的迁移名称，包括时间戳，该名称会写入 CLI：（20210316150542_retroactively_add_index）

   npx prisma migrate dev --name retroactively-add-index

   显示CLI结果

   migrations/
   └─ 20210316150542_retroactively_add_index/
   └─ migration.sql
   
   Your database is now in sync with your schema.
   
   ✔ Generated Prisma Client (2.19.0-dev.29) to .\node_modules\@prisma\client in 190ms

3. 将迁移推送到生产环境而不运行 migrate deploy。相反，将上一步中创建的迁移标记为“已应用”，以便 Prisma Migrate 不会尝试第二次应用你的热修复

   prisma migrate resolve --applied "20201127134938-retroactively-add-index"

   此命令将迁移添加到迁移历史表，而不运行实际的 SQL。

4. 对其他已修补的数据库重复上一步 - 例如，如果你将修补程序应用于暂存数据库。

5. 将迁移传播到其他未修补的数据库 - 例如，通过将迁移提交到源代码控制并允许你的 CI/CD 管道将其应用于所有数据库。

注意：迁移不会应用于已通过 prisma migrate resolve 命令标记为已应用的数据库。

迁移失败

如果出现以下情况，迁移可能会失败

• 你在运行迁移之前修改迁移并引入语法错误
• 你向已具有数据的表添加了强制性（NOT NULL）列
• 迁移过程意外停止
• 数据库在迁移过程中关闭

_prisma_migrations 表中的每个迁移都有一个 logs 列，用于存储错误。

在生产环境中处理失败的迁移有两种方法

• 回滚，选择性地修复问题，然后重新部署
• 手动完成迁移步骤并解析迁移

选项 1：将迁移标记为已回滚并重新部署

以下示例演示如何回滚迁移，选择性地进行更改以修复问题，然后重新部署

1. 将迁移标记为已回滚 - 这会更新 _prisma_migrations 表中的迁移记录，将其注册为已回滚，允许再次应用该迁移

   prisma migrate resolve --rolled-back "20201127134938_added_bio_index"

2. 如果迁移是部分运行的，你可以

   • 修改迁移以检查步骤是否已完成（例如：CREATE TABLE ... IF NOT EXISTS）或

   • 手动还原已完成的步骤（例如，删除创建的表）

   如果你修改了迁移，请确保将其复制回源代码控制，以确保你的生产数据库的状态在开发中得到准确反映。

3. 修复导致迁移失败的根本原因（如果相关） - 例如，如果迁移由于 SQL 脚本本身的问题而失败。请确保将任何已更改的迁移复制回源代码控制。

4. 重新部署迁移

   prisma migrate deploy

选项 2：手动完成迁移并解析为已应用

以下示例演示如何手动完成迁移的步骤并将该迁移标记为已应用。

1. 手动完成生产数据库上的迁移步骤。请确保任何手动步骤与迁移文件中的步骤完全匹配，并将任何更改复制回源代码控制。

2. 将迁移解析为已应用 - 这会告诉 Prisma Migrate 将迁移视为已成功应用

   prisma migrate resolve --applied "20201127134938_my_migration"

使用 migrate diff 和 db execute 修复失败的迁移

为了帮助修复失败的迁移，Prisma ORM 提供了以下用于创建和执行迁移文件的命令

• prisma migrate diff，它会比较两个数据库 schema 源，以创建一个将一个源迁移到第二个源状态的迁移。你可以输出差异的摘要或 sql 脚本。该脚本可以通过 > file_name.sql 输出到文件中，或通过管道传输到 db execute --stdin 命令。
• prisma db execute，它将 SQL 脚本应用于数据库，而无需与 Prisma 迁移表交互。

这些命令在版本 3.9.0 及更高版本中以预览形式提供（带有 --preview-feature CLI 标志），并在版本 3.13.0 及更高版本中普遍可用。

本节给出了一个迁移失败的示例场景，并解释了如何使用 migrate diff 和 db execute 来修复它。

迁移失败的示例

假设你在你的本地开发环境和你的生产环境中都有以下 User 模型

schema.prisma

model User {
  id   Int    @id
  name String
}

此时，你的 schema 是同步的，但两个环境中的数据是不同的。

然后你决定更改你的数据模型，添加另一个 Post 模型并使 User 上的 name 字段唯一

schema.prisma

model User {
  id    Int     @id
  name  String  @unique
  email String?
}

model Post {
  id    Int    @id
  title String
}

你使用命令 prisma migrate dev -n Unique 创建一个名为“Unique”的迁移，该迁移保存在你的本地迁移历史记录中。在你的开发环境中应用迁移成功，现在是发布到生产环境的时候了。

不幸的是，此迁移只能部分执行。创建 Post 模型并添加 email 列成功，但使 name 字段唯一失败，并出现以下错误

ERROR 1062 (23000): Duplicate entry 'paul' for key 'User_name_key'

这是因为你的生产数据库中存在非唯一数据（例如，两个用户具有相同的名称）。

你现在需要手动从部分执行的迁移中恢复。在你从失败状态恢复之前，不可能使用 prisma migrate deploy 进行进一步的迁移。

此时有两种选择，具体取决于你决定如何处理非唯一数据

• 你意识到非唯一数据是有效的，并且你无法继续你当前的工作。你想回滚完整的迁移。要执行此操作，请参阅向后移动并恢复所有更改
• 你的数据库中存在非唯一数据是无意的，你想修复它。修复后，你希望继续进行其余的迁移。要执行此操作，请参阅向前移动并应用缺失的更改

向后移动并恢复所有更改

在这种情况下，你需要创建一个迁移，将你的生产数据库带回到上次迁移之前你的数据模型的状态。

• 首先，你需要在失败的迁移之前的迁移历史记录。你可以从你的 git 历史记录中获取，或者在本地删除你的迁移历史记录中上次失败的迁移的文件夹。

• 你现在想将你的生产环境从当前失败的状态恢复到你的本地迁移历史记录中指定的状态

  • 运行以下 prisma migrate diff 命令

     npx prisma migrate diff \
      --from-url "$DATABASE_URL_PROD" \
      --to-migrations ./prisma/migrations \
      --shadow-database-url $SHADOW_DATABASE_URL \
      --script > backward.sql

    这将创建一个 SQL 脚本文件，其中包含将您的生产环境从当前失败状态恢复到由您的迁移历史定义的目标状态所需的所有更改。请注意，由于我们使用了 --to-migrations，该命令需要一个影子数据库。

  • 运行以下 prisma db execute 命令

     npx prisma db execute --url "$DATABASE_URL_PROD" --file backward.sql

    这将针对目标数据库应用 SQL 脚本中的更改，而不会与迁移表交互。

  • 运行以下 prisma migrate resolve 命令

     npx prisma migrate resolve --rolled-back Unique

    这会将生产环境中名为 'Unique' 的失败迁移在迁移表中标记为已回滚。

您本地的迁移历史现在产生的结果与您生产数据库的状态相同。您现在可以再次修改数据模型，创建一个适合您对正在开发的功能的新理解的迁移（使用非唯一名称）。

继续前进并应用缺失的更改

在这种情况下，您需要修复非唯一数据，然后按计划继续执行其余的迁移。

• 尝试将迁移部署到生产环境时出现的错误消息已经告诉您 name 列中存在重复数据。您需要修改或删除有问题的行。

• 继续应用剩余的失败迁移，以达到您的 schema.prisma 文件中定义的数据模型。

  • 运行以下 prisma migrate diff 命令

    
    npx prisma migrate diff --from-url "$DATABASE_URL_PROD" --to-schema-datamodel schema.prisma --script > forward.sql
    

    这将创建一个 SQL 脚本文件，其中包含将您的生产环境从当前失败状态恢复到 schema.prisma 文件中定义的目标状态所需的所有更改。

  • 运行以下 prisma db execute 命令

    npx prisma db execute --url "$DATABASE_URL_PROD" --file forward.sql

    这将针对目标数据库应用 SQL 脚本中的更改，而不会与迁移表交互。

  • 运行以下 prisma migrate resolve 命令

    npx prisma migrate resolve --applied Unique

    这会将生产环境中名为 'Unique' 的失败迁移在迁移表中标记为已应用。

您本地的迁移历史现在产生的结果与您生产环境的状态相同。您现在可以继续使用已经熟悉的 migrate dev /migrate deploy 工作流程。

迁移历史冲突

信息

这不适用于 3.12.0 及以上版本。

如果已编辑已应用的迁移，prisma migrate deploy 会发出警告 - 但是，它不会停止迁移过程。要删除警告，请从源代码管理中恢复原始迁移。

Prisma Migrate 和 PgBouncer

如果在使用 PgBouncer 进行连接池的环境中尝试运行 Prisma Migrate 命令，您可能会看到以下错误

Error: undefined: Database error
Error querying the database: db error: ERROR: prepared statement "s0" already exists

有关更多信息和解决方法，请参阅Prisma Migrate 和 PgBouncer 解决方法。请关注 GitHub issue #6485 获取更新。