跳到主要內容

心智模型

本指南概念性地概述了在使用關聯式資料庫時，如何使用 Prisma Migrate 進行資料庫遷移。內容涵蓋：資料庫遷移是什麼、其價值，以及 Prisma Migrate 是什麼，以及如何在不同環境中使用 Prisma Migrate 演進您的資料庫結構描述。

如果您使用 MongoDB，請使用 prisma db push 來演進您的結構描述。

什麼是資料庫遷移？​

資料庫遷移是一組受控的變更，可修改和演進您的資料庫結構描述的結構。遷移可協助您將資料庫結構描述從一個狀態轉換到另一個狀態。例如，在遷移中，您可以建立或移除表格和資料行、分割表格中的欄位，或將類型和約束新增至您的資料庫。

演進資料庫結構描述的模式​

本節說明演進資料庫結構描述的一般結構描述遷移模式。

主要的兩種結構描述遷移模式為

  • 模型/實體優先遷移： 使用此模式，您可以使用程式碼定義資料庫結構描述的結構，然後使用遷移工具產生 SQL，例如，用於同步您的應用程式和資料庫結構描述。

Model-first migration flow

  • 資料庫優先遷移： 使用此模式，您可以定義資料庫的結構，並使用 SQL 將其套用至您的資料庫。然後，您內省資料庫以產生描述資料庫結構的程式碼，以同步您的應用程式和資料庫結構描述。

Database-first migration flow

資訊

注意

為了簡化起見，我們選擇上述術語來描述演進資料庫結構描述的不同模式。其他工具和程式庫可能會使用不同的術語來描述不同的模式。

遷移檔案 (SQL) 應理想地與您的應用程式程式碼一起儲存。它們也應在版本控制中追蹤，並與團隊中其他負責應用程式開發的成員共用。

遷移提供狀態管理，可協助您追蹤資料庫的狀態。

遷移也允許您在特定時間點複製資料庫的狀態，這在與團隊的其他成員協作時非常有用，例如在不同分支之間切換。

有關資料庫遷移的更多資訊，請參閱 Prisma 資料指南。

什麼是 Prisma Migrate？​

Prisma Migrate 是一種資料庫遷移工具，支援模型/實體優先遷移模式，以管理您本機環境和生產環境中的資料庫結構描述。

在您的專案中使用 Prisma Migrate 的工作流程將是迭代式的，看起來像這樣

本機開發環境（功能分支）

  1. 演進您的 Prisma 結構描述
  2. 使用 prisma migrate dev 或 prisma db push 將您的 Prisma 結構描述與本機開發資料庫的資料庫結構描述同步

預覽/預備環境（功能提取請求）

  1. 將您的變更推送至功能提取請求
  2. 使用 CI 系統（例如 GitHub Actions）使用 prisma migrate deploy 將您的 Prisma 結構描述和遷移歷史記錄與您的預覽資料庫同步

生產環境（主要分支）

  1. 將您的應用程式程式碼從功能分支合併到您的主要分支
  2. 使用 CI 系統（例如 GitHub Actions）使用 prisma migrate deploy 將您的 Prisma 結構描述和遷移歷史記錄與您的生產資料庫同步

Prisma Migrate workflow

Prisma Migrate 如何追蹤遷移狀態​

Prisma Migrate 使用以下狀態片段來追蹤您的資料庫結構描述的狀態

  • Prisma 結構描述：您的真理來源，定義資料庫結構描述的結構。
  • 遷移歷史記錄：prisma/migrations 資料夾中的 SQL 檔案，代表對您的資料庫結構描述所做的變更歷史記錄。
  • 遷移表格：資料庫中的 prisma_migrations 表格，儲存已套用至資料庫的遷移的中繼資料。
  • 資料庫結構描述：資料庫的狀態。

Prisma Migrate "state management"

使用 Prisma Migrate 時的需求​

  • 理想情況下，您應該每個環境使用一個資料庫。例如，您可能會為開發、預覽和生產環境使用不同的資料庫。
  • 您在開發環境中使用的資料庫是可拋棄式的 — 您可以輕鬆地按需建立、使用和刪除資料庫。
  • 每個環境中使用的資料庫配置應保持一致。這對於確保跨工作流程移動的特定遷移對資料庫產生相同的變更非常重要。
  • Prisma 結構描述作為真理來源 — 描述您的 資料庫結構描述的形狀。

使用 Prisma Migrate 演進您的資料庫結構描述​

本節說明如何在不同環境（開發、預備和生產）中使用 Prisma Migrate 演進您的資料庫結構描述。

開發環境 (本機) 中的 Prisma Migrate​

使用 prisma migrate dev 追蹤您的遷移歷史記錄​

prisma migrate dev 命令可讓您追蹤對資料庫所做的變更。prisma migrate dev 命令會自動產生 SQL 遷移檔案（儲存在 /prisma/migrations 中）並將其套用至資料庫。當遷移套用至資料庫時，資料庫中的遷移表格 (_prisma_migrations) 也會更新。

Prisma Migrate dev flow

prisma migrate dev 命令使用以下狀態片段追蹤資料庫的狀態

  • Prisma 結構描述
  • 遷移歷史記錄
  • 遷移表格
  • 資料庫結構描述

注意：用於追蹤遷移狀態的狀態片段與 Prisma Migrate 如何追蹤遷移狀態 章節中描述的片段相同。

您可以使用 --create-only 旗標在將遷移套用至資料庫之前自訂遷移。例如，如果您想要重新命名資料行而不造成任何資料遺失，或載入資料庫擴充功能 (在 PostgreSQL 中) 和資料庫檢視 (目前不支援)，您可能會想要編輯遷移。

在底層，Prisma Migrate 使用 影子資料庫 來偵測 結構描述漂移 並產生新的遷移。

注意：prisma migrate dev 僅適用於搭配可拋棄式資料庫的開發環境。

如果 prisma migrate dev 偵測到結構描述漂移或遷移歷史記錄衝突，系統將提示您重設（捨棄並重新建立您的資料庫）您的資料庫，以同步遷移歷史記錄和資料庫結構描述。

展開以查看使用卡通說明的影子資料庫

A cartoon that shows how the shadow database works.

解決結構描述漂移​

當預期的資料庫結構描述與遷移歷史記錄中的結構描述不同時，就會發生結構描述漂移。例如，當您手動更新資料庫結構描述，但未同時更新 Prisma 結構描述和 prisma/migrations 時，可能會發生這種情況。

對於這種情況，您可以使用 prisma migrate diff 命令來比較您的遷移歷史記錄並還原對您的資料庫結構描述所做的變更。

Revert database schema with migrate diff

您可以使用 migrate diff 來產生 SQL，以執行以下操作

  • 還原在資料庫結構描述中所做的變更，以使其與目前的 Prisma 結構描述同步
  • 向前移動您的資料庫結構描述，以套用 Prisma 結構描述和 /migrations 中遺失的變更

然後，您可以使用 prisma db execute 命令將變更套用至您的資料庫。

原型化您的結構描述​

prisma db push 命令可讓您同步您的 Prisma 結構描述和資料庫結構描述，而無需持久化遷移 (/prisma/migrations)。prisma db push 命令使用以下狀態片段追蹤資料庫的狀態

  • Prisma 結構描述
  • 資料庫結構描述

prisma db push development flow

在以下情況下，prisma db push 命令很有用

  • 您想要快速原型化和迭代本機結構描述設計，而無需將這些變更部署到其他環境，例如其他開發人員，或預備和生產環境。
  • 您優先考慮達到所需的最終狀態，而不是為達到該最終狀態而執行的變更或步驟（無法預覽 prisma db push 所做的變更）
  • 您不需要控制結構描述變更如何影響資料。沒有方法可以協調結構描述和資料遷移 - 如果 prisma db push 預期變更會導致資料遺失，您可以接受具有 --accept-data-loss 選項的資料遺失，或停止程序 - 無法自訂變更。

如果 prisma db push 命令偵測到對您的資料庫結構描述的破壞性變更，它會提示您重設您的資料庫。例如，當您將必要欄位新增至具有現有內容的表格，但未提供預設值時，就會發生這種情況。

結構描述漂移發生在您的資料庫結構描述與您的遷移歷史記錄和遷移表格不同步時。

預備和生產環境中的 Prisma Migrate​

同步您的遷移歷史記錄​

prisma migrate deploy 命令可讓您將開發環境中的遷移歷史記錄與預備或生產環境中的資料庫同步。

在底層，migrate deploy 命令會執行以下操作

  1. 比較已套用的遷移（擷取的 _prisma_migrations）和遷移歷史記錄 (/prisma/migrations)
  2. 套用待處理的遷移
  3. 使用新的遷移更新 _prisma_migrations 表格

Workflow of Prisma Migrate

該命令應在自動化的 CI/CD 環境中執行，例如 GitHub Actions。

如果您沒有遷移歷史記錄 (/migrations)，即使用 prisma db push，您將必須繼續在您的預備和生產環境中使用 prisma db push。請注意套用至資料庫結構描述的變更，因為其中一些變更可能具有破壞性。例如，prisma db push 無法判斷您何時執行資料行重新命名。它會提示資料庫重設（捨棄並重新建立）。