Skip to main content

故障排除

本指南介绍如何解决开发环境中的 Prisma Migrate 问题，这通常涉及重置数据库。对于以生产为中心的故障排除，请参阅：

¥This guide describes how to resolve issues with Prisma Migrate in a development environment, which often involves resetting your database. For production-focused troubleshooting, see:

warning

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

¥This guide does not apply for MongoDB.
Instead of migrate dev, db push is used for MongoDB.

处理迁移历史冲突​

¥Handling migration history conflicts

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

¥A migration history conflict occurs when there are discrepancies between the migrations folder in the file system and the _prisma_migrations table in the database.

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

¥Causes of migration history conflict in a development environment

  • 已应用的迁移稍后会被修改

    ¥A migration that has already been applied is later modified

  • 文件系统中缺少已应用的迁移

    ¥A migration that has already been applied is missing from the file system

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

¥In a development environment, switching between feature branches can result in a history conflict because the _prisma_migrations table contains migrations from branch-1, and switching to branch-2 might cause some of those migrations to disappear.

注意：你应该 切勿故意删除或编辑迁移，因为这可能会导致开发和生产之间的差异。

¥Note: You should never purposefully delete or edit a migration, as this might result in discrepancies between development and production.

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

¥Fixing a migration history conflict in a development environment

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

¥If Prisma Migrate detects a migration history conflict when you run prisma migrate dev, the CLI will ask to reset the database and reapply the migration history.

模式漂移​

¥Schema drift

当你的数据库架构与迁移历史记录不同步时，就会发生数据库架构漂移 - 数据库模式具有来自真实来源的 '渐行渐远'。

¥Database schema drift occurs when your database schema is out of sync with your migration history - the database schema has 'drifted away' from the source of truth.

开发环境中架构漂移的原因​

¥Causes of schema drift in a development environment

如果出现以下情况，可能会发生架构漂移：

¥Schema drift can occur if:

  • 数据库架构已更改但未使用迁移 - 例如，通过使用 prisma db push 或手动更改数据库架构。

    ¥The database schema was changed without using migrations - for example, by using prisma db push or manually changing the database schema.

注意：影子数据库 需要检测模式漂移，因此只能在开发环境中完成。

¥Note: The shadow database is required to detect schema drift, and can therefore only be done in a development environment.

修复开发环境中的架构漂移​

¥Fixing schema drift in a development environment

如果你对不想保留的数据库进行了手动更改，或者可以在 Prisma 模式中轻松复制：

¥If you made manual changes to the database that you do not want to keep, or can easily replicate in the Prisma schema:

  1. 重置你的数据库：

    ¥Reset your database:

    npx prisma migrate reset

  2. 复制 Prisma 架构中的更改并生成新的迁移：

    ¥Replicate the changes in the Prisma schema and generate a new migration:

    npx prisma migrate dev

如果你对要保留的数据库进行了手动更改，你可以：

¥If you made manual changes to the database that you want to keep, you can:

  1. 检查数据库：

    ¥Introspect the database:

    npx prisma db pull

    Prisma 将使用直接在数据库中所做的更改来更新你的架构。

    ¥Prisma will update your schema with the changes made directly in the database.

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

    ¥Generate a new migration to include the introspected changes in your migration history:

    npx prisma migrate dev --name introspected_change

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

    ¥Prisma Migrate will prompt you to reset, then applies all existing migrations and a new migration based on the introspected changes. Your database and migration history are now in sync, including your manual changes.

迁移失败​

¥Failed migrations

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

¥Causes of failed migrations in a development environment

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

¥A migration might fail if:

  • 你 在运行之前修改迁移 并引入了语法错误

    ¥You modify a migration before running it and introduce a syntax error

  • 你向已有数据的表添加强制 (NOT NULL) 列

    ¥You add a mandatory (NOT NULL) column to a table that already has data

  • 迁移过程意外停止

    ¥The migration process stopped unexpectedly

  • 数据库在迁移过程中关闭

    ¥The database shut down in the middle of the migration process

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

¥Each migration in the _prisma_migrations table has a logs column that stores the error.

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

¥Fixing failed migrations in a development environment

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

¥The easiest way to handle a failed migration in a developer environment is to address the root cause and reset the database. For example:

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

    ¥If you introduced a SQL syntax error by manually editing the database, update the migration.sql file that failed and reset the database:

    prisma migrate reset

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

    ¥If you introduced a change in the Prisma schema that cannot be applied to a database with data (for example, a mandatory column in a table with data):

    1. 删除 migration.sql 文件。

      ¥Delete the migration.sql file.

    2. 修改架构 - 例如，向必填字段添加默认值。

      ¥Modify the schema - for example, add a default value to the mandatory field.

    3. 迁移：

      ¥Migrate:

      prisma migrate dev

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

      ¥Prisma Migrate will prompt you to reset the database and re-apply all migrations.

  • 如果迁移过程中断，请重置数据库：

    ¥If something interrupted the migration process, reset the database:

    prisma migrate reset

Prisma Migrate 和 PgBouncer​

¥Prisma Migrate and PgBouncer

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

¥You might see the following error if you attempt to run Prisma Migrate commands in an environment that uses PgBouncer for connection pooling:

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

请参阅 Prisma Migrate 和 PgBouncer 解决方法 了解更多信息和解决方法。

¥See Prisma Migrate and PgBouncer workaround for further information and a workaround.