跳到主要内容

故障排除

本指南描述了如何在开发环境中解决 Prisma Migrate 的问题，这通常涉及重置数据库。有关面向生产环境的故障排除，请参阅

警告

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

处理迁移历史冲突​

当文件系统中的 migrations 文件夹与数据库中的 _prisma_migrations 表之间存在差异时，会发生迁移历史冲突。

开发环境中迁移历史冲突的原因​

  • 已应用的迁移稍后被修改
  • 已应用的迁移在文件系统中丢失

在开发环境中，在功能分支之间切换可能会导致历史冲突，因为 _prisma_migrations 表包含来自 branch-1 的迁移，而切换到 branch-2 可能会导致其中一些迁移消失。

注意：您应该永远不要有意删除或编辑已应用的迁移，因为这可能会导致开发环境和生产环境之间出现差异。

修复开发环境中的迁移历史冲突​

如果您运行 prisma migrate dev 时 Prisma Migrate 检测到迁移历史冲突，CLI 将要求重置数据库并重新应用迁移历史。

Schema 漂移​

数据库 schema 漂移发生在您的数据库 schema 与您的迁移历史记录不同步时 - 数据库 schema 已“偏离”了真理来源。

开发环境中 Schema 漂移的原因​

如果发生以下情况，则可能发生 Schema 漂移

  • 数据库 schema 在没有使用迁移的情况下被更改 - 例如，通过使用 prisma db push 或手动更改数据库 schema。

注意：影子数据库是检测 schema 漂移所必需的，因此只能在开发环境中完成。

修复开发环境中的 Schema 漂移​

如果您对数据库进行了手动更改，而您不想保留这些更改，或者可以在 Prisma schema 中轻松复制这些更改

  1. 重置您的数据库

    npx prisma migrate reset

  2. 在 Prisma schema 中复制更改并生成新的迁移

    npx prisma migrate dev

如果您对数据库进行了手动更改，并且想要保留这些更改，您可以

  1. 内省数据库

    npx prisma db pull

    Prisma 将使用直接在数据库中所做的更改来更新您的 schema。

  2. 生成新的迁移以将内省的更改包含在您的迁移历史记录中

    npx prisma migrate dev --name introspected_change

    Prisma Migrate 将提示您重置，然后应用所有现有迁移以及基于内省更改的新迁移。您的数据库和迁移历史记录现在已同步，包括您的手动更改。

失败的迁移​

开发环境中失败的迁移的原因​

如果发生以下情况，迁移可能会失败

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

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

修复开发环境中失败的迁移​

在开发环境中处理失败的迁移的最简单方法是解决根本原因并重置数据库。例如

  • 如果您通过手动编辑数据库引入了 SQL 语法错误，请更新失败的 migration.sql 文件并重置数据库

    prisma migrate reset

  • 如果您在 Prisma schema 中引入了无法应用于包含数据的数据库的更改（例如，包含数据的表中的强制性列）

    1. 删除 migration.sql 文件。

    2. 修改 schema - 例如，向强制性字段添加默认值。

    3. 迁移

      prisma migrate dev

      Prisma Migrate 将提示您重置数据库并重新应用所有迁移。

  • 如果某些原因中断了迁移过程，请重置数据库

    prisma migrate reset

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 解决方法。