故障排除
本指南介绍了如何在开发环境中解决Prisma Migrate的问题,这通常涉及到重置数据库。关于生产环境的故障排除,请参阅
处理迁移历史冲突
当文件系统中的迁移文件夹与数据库中的_prisma_migrations
表之间存在差异时,就会发生迁移历史冲突。
开发环境中迁移历史冲突的原因
- 已应用的迁移后来被修改
- 已应用的迁移在文件系统中缺失
在开发环境中,切换特性分支可能导致历史冲突,因为_prisma_migrations
表包含branch-1
的迁移,而切换到branch-2
可能导致其中一些迁移消失。
注意:你绝不应有意删除或编辑已应用的迁移,因为这可能导致开发环境和生产环境之间的差异。
修复开发环境中的迁移历史冲突
如果Prisma Migrate在你运行prisma migrate dev
时检测到迁移历史冲突,CLI会要求重置数据库并重新应用迁移历史。
Schema漂移
数据库schema漂移发生在你的数据库schema与迁移历史不同步时——数据库schema已经“偏离”了真理之源。
开发环境中schema漂移的原因
Schema漂移可能发生在以下情况:
- 数据库schema在未使用迁移的情况下被更改——例如,通过使用
prisma db push
或手动更改数据库schema。
注意:需要影子数据库来检测schema漂移,因此只能在开发环境中完成。
修复开发环境中的schema漂移
如果你对数据库进行了不想保留的手动更改,或者可以在Prisma schema中轻松复制这些更改,则可以:
-
重置你的数据库
npx prisma migrate reset
-
在Prisma schema中复制更改并生成新的迁移
npx prisma migrate dev
如果你对数据库进行了要保留的手动更改,则可以:
-
内省数据库
npx prisma db pull
Prisma将使用直接在数据库中进行的更改来更新你的schema。
-
生成新的迁移以将内省的更改包含在你的迁移历史中
npx prisma migrate dev --name introspected_change
Prisma Migrate将提示你重置,然后应用所有现有迁移和基于内省更改的新迁移。你的数据库和迁移历史现在已同步,包括你的手动更改。
失败的迁移
开发环境中迁移失败的原因
迁移可能失败,如果:
- 你在运行迁移之前修改了它并引入了语法错误
- 你向已包含数据的表中添加了一个强制性(
NOT NULL
)列 - 迁移过程意外停止
- 数据库在迁移过程中关闭
_prisma_migrations
表中的每个迁移都有一个logs
列,用于存储错误。
修复开发环境中失败的迁移
在开发环境中处理失败迁移最简单的方法是解决根本原因并重置数据库。例如:
-
如果你通过手动编辑数据库引入了SQL语法错误,请更新失败的
migration.sql
文件并重置数据库prisma migrate reset
-
如果你在Prisma schema中引入了无法应用于已包含数据的数据库的更改(例如,已包含数据的表中的强制列)
-
删除
migration.sql
文件。 -
修改schema——例如,为强制字段添加默认值。
-
执行迁移
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变通方法以获取更多信息和变通方法。