關於遷移歷史

本頁說明 Prisma ORM 如何使用遷移歷史來追蹤您 schema 的變更。

遷移歷史

您的遷移歷史是資料模型變更的歷程記錄，並由以下項目表示：

一個 prisma/migrations 資料夾，其中包含子資料夾和每個遷移的 migration.sql 檔案
```
migrations/
  └─ 20210313140442_init/
    └─ migration.sql
  └─ 20210313140442_added_job_title/
    └─ migration.sql
```
migrations 資料夾是資料模型歷史記錄的事實來源。
資料庫中的 _prisma_migrations 表格，用於檢查
- 遷移是否已針對資料庫執行
- 已套用的遷移是否已刪除
- 已套用的遷移是否已變更
如果您變更或刪除遷移（不建議），則後續步驟取決於您是否處於開發環境（因此使用 migrate dev）或生產/測試環境（因此使用 migrate deploy）。

請勿編輯或刪除已套用的遷移

一般來說，您不應編輯或刪除已套用的遷移。這樣做可能會導致開發和生產環境遷移歷史記錄之間的不一致，這可能會產生無法預見的後果 — 即使變更一開始看起來沒有破壞任何東西。

以下情境模擬了一個變更，該變更建立了一個看似無害的不一致性

修改已套用在開發環境中的現有遷移，方法是將 VARCHAR(550) 的值變更為 VARCHAR(560)
./prisma/migrations/20210310143435_default_value/migrations.sql
```
  -- AlterTable
 ALTER TABLE "Post" ALTER COLUMN "content" SET DATA TYPE VARCHAR(560);
```
在進行此變更後，遷移歷史記錄的最終狀態不再與 Prisma schema 匹配，後者仍然具有 @db.VarChar(550)。

執行 prisma migrate dev - Prisma Migrate 偵測到遷移已變更，並要求 reset 資料庫

? The migration `20210310143435_change_type` was modified after it was applied.

 We need to reset the PostgreSQL database "migrate-example" at "localhost:5432".
 Do you want to continue? All data will be lost. » (y/N)

如果您接受重置，Prisma Migrate 將重置資料庫並重新執行所有遷移，包括您編輯的遷移。
在套用所有現有遷移後，Prisma Migrate 會將遷移歷史記錄的最終狀態與 Prisma schema 進行比較，並偵測到差異
- Prisma schema 具有 @db.VarChar(550)
- 資料庫 schema 具有 VARCHAR(560)
Prisma Migrate 產生新的遷移以將值改回 550，因為遷移歷史記錄的最終狀態應與 Prisma schema 匹配。
從現在開始，當您使用 prisma migrate deploy 將遷移部署到生產和測試環境時，Prisma Migrate 將始終警告您遷移歷史記錄不匹配（並在每次執行命令時繼續警告您）- 即使 schema 最終狀態匹配
```
6 migrations found in prisma/migrations
WARNING The following migrations have been modified since they were applied:
20210310143435_change_type
```

在 migrate reset 後，一個看似沒有破壞任何東西的變更可能會隱藏問題 - 您最終可能會在生產環境中遇到無法在開發環境中重現的錯誤，反之亦然 - 特別是如果變更涉及高度客製化的遷移。

如果 Prisma Migrate 報告遺失或編輯了已套用的遷移，我們建議修復根本原因（還原檔案或還原變更），而不是重置。

資訊

在某些情況下，手動變更您的遷移歷史記錄實際上不會改變資料庫 schema，例如在產生的 SQL 遷移中新增註解。在這些情況下，您可以按照本教學中的說明，避免重置資料庫。

將遷移歷史記錄提交到原始碼控制

您必須將整個 prisma/migrations 資料夾提交到原始碼控制。這包括 prisma/migrations/migration_lock.toml 檔案，該檔案用於偵測您是否嘗試變更提供者。

僅原始碼控制 schema.prisma 檔案是不夠的 - 您必須包含您的遷移歷史記錄。這是因為

當您開始自訂遷移時，您的遷移歷史記錄包含無法在 Prisma schema 中表示的資訊。例如，您可以自訂遷移以減輕由重大變更引起的資料遺失。
prisma migrate deploy 命令用於將變更部署到預備、測試和生產環境，僅執行遷移檔案。它不使用 Prisma schema 來獲取模型。

遷移歷史​

請勿編輯或刪除已套用的遷移​

將遷移歷史記錄提交到原始碼控制​

遷移歷史

請勿編輯或刪除已套用的遷移

將遷移歷史記錄提交到原始碼控制