跳到主要内容

故障排除

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

警告

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

处理迁移历史冲突​

迁移历史冲突发生时，表示**文件系统中的 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 解决方法，了解更多信息和变通方法。