跳到主要內容

疑難排解

本指南說明如何在開發環境中解決 Prisma Migrate 的問題，這通常涉及重置資料庫。關於以生產環境為中心的疑難排解，請參閱

警告

本指南不適用於 MongoDB。
對於 MongoDB，使用 db push 而不是 migrate dev。

處理遷移歷史衝突​

當檔案系統中的 migrations 資料夾與資料庫中的 _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 中輕鬆複製的變更

  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 變通方案，以取得更多資訊和變通方案。