使用 Atlas & Prisma ORM 進行進階資料庫結構描述管理

簡介

Atlas 是一個強大的資料塑模和遷移工具，可實現進階資料庫結構描述管理工作流程，例如 CI/CD 整合、結構描述監控、版本控制等等。

在本指南中，您將學習如何透過在現有的 Prisma ORM 專案中以 Atlas 取代 Prisma Migrate，來使用 Atlas 進階結構描述管理和遷移工作流程。

這樣一來，您仍然可以使用 Prisma ORM 直覺式的資料模型和型別安全的查詢功能，同時利用 Atlas 提供的強化遷移功能。

您可以在 GitHub 上找到本教學課程的範例儲存庫。此儲存庫有對應本指南每個步驟的分支。

為何使用 Atlas 而非 Prisma Migrate？

Prisma Migrate 是一個強大的遷移工具，涵蓋應用程式開發人員在管理其資料庫結構描述時遇到的大多數使用案例。它提供專為引導您從開發到生產以及考慮到團隊協作而設計的工作流程。

然而，為了獲得更多功能，您可以像 Atlas 這樣的專用工具來強化您在以下情境中的遷移工作流程

• 持續整合 (CI)：透過 Atlas，您可以透過強大的GitHub Actions、GitLab 和 CircleCI Orbs 整合在問題發生於生產環境之前就先找出。您也可以偵測風險遷移、測試資料遷移、資料庫函數等等。
• 持續交付 (CD)：Atlas 可以整合到您的管線中，以提供與您的部署機制 (例如 Kubernetes Operator、Terraform 等) 的原生整合。
• 結構描述監控：Atlas 可以監控您的資料庫結構描述，並在它偏離預期狀態時向您發出警示。
• 支援底層資料庫功能：自動遷移規劃適用於進階資料庫物件，例如視圖、預存程序、觸發程序、資料列層級安全性等等。

先決條件

若要成功完成本指南，您需要

• 現有的 Prisma ORM 專案 (已安裝 prisma 和 @prisma/client 套件)
• PostgreSQL 資料庫及其連線字串
• 您的電腦上已安裝 Docker (以管理 Atlas 的臨時開發資料庫)

為了本指南的目的，我們假設您的 Prisma 結構描述包含標準的 User 和 Post 模型，我們將其用作整個文件中的主要範例。如果您沒有 Prisma ORM 專案，可以使用 orm/script 範例來遵循本指南。

此步驟的起點是範例儲存庫中的 start 分支。

步驟 1：將 Atlas 新增至現有的 Prisma ORM 專案

若要開始本教學課程，請先安裝 Atlas CLI

如果您偏好不同的安裝方法 (例如 Docker 或 Homebrew)，可以在這裡找到。

接下來，導覽至使用 Prisma ORM 的專案根目錄，並建立主要的 Atlas 結構描述檔案，名為 atlas.hcl

現在，新增以下程式碼

若要取得 Atlas 結構描述檔案的語法醒目提示和其他便利功能，請安裝 Atlas VS Code 擴充功能。

在上面的程式碼片段中，您正在執行兩件事

• 透過 data 區塊定義名為 prisma 的 external_schema：Atlas 能夠整合來自各種來源的資料庫結構描述定義。在此情況下，來源是 prisma migrate diff 命令產生的 SQL，該命令透過 program 欄位指定。
• 使用 env 區塊指定有關您的環境 (名為 local) 的詳細資訊
  • dev：指向 陰影資料庫 (在 Atlas 中稱為開發資料庫)。與 Prisma Migrate 類似，Atlas 也使用陰影資料庫來「試執行」遷移。您在此處提供的連線與 Prisma 結構描述中的 shadowDatabaseUrl 類似。然而，為了方便起見，我們在此案例中使用 Docker 來管理這些臨時資料庫執行個體。
  • schema：指向 Prisma ORM 定位的資料庫的資料庫連線 URL (在大多數情況下，這會與 DATABASE_URL 環境變數相同)。
  • migration：指向您想要儲存 Atlas 遷移檔案的檔案系統目錄 (類似於 prisma/migrations 資料夾)。請注意，您也排除了 _prisma_migrations，使其不會在 Atlas 的遷移歷程記錄中追蹤。

除了陰影資料庫之外，Atlas 的遷移系統和 Prisma Migrate 還有另一個共同點：它們都使用資料庫中的專用資料表來追蹤已套用遷移的歷程記錄。在 Prisma Migrate 中，此資料表稱為 _prisma_migrations。在 Atlas 中，它稱為 atlas_schema_revisions。

為了告訴 Atlas 您的資料庫目前狀態 (包含所有現有資料表和其他資料庫物件) 應該是專案中追蹤遷移的起點，您需要執行初始基準遷移。

若要執行此作業，請先執行以下命令來建立 Atlas 的遷移目錄

此命令

1. 查看您 local 環境的目前狀態，並根據您的 Atlas 結構描述中定義的 external_schema 產生 SQL 遷移檔案。
2. 建立 atlas/migrations 資料夾，並將 SQL 遷移放入其中。

執行後，您的資料夾結構應如下所示

此時，Atlas 尚未對您的資料庫執行任何動作 — 它只在您的本機電腦上建立檔案。

現在，您需要套用產生的遷移，以告知 Atlas 這應該是其遷移歷程記錄的開始。若要執行此作業，請執行 atlas migrate apply 命令，但這次提供 --baseline __TIMESTAMP__ 選項。

從 Atlas 在 atlas/migrations 內建立的檔案名稱複製時間戳記，並使用它來取代下一個程式碼片段中的 __TIMESTAMP__ 預留位置值。同樣地，將 __DATABASE_URL__ 預留位置取代為您的資料庫連線字串

假設產生的遷移檔案名為 20241210094213.sql，而您的資料庫在 postgresql://johndoe:mypassword42@localhost:5432/example-db?search_path=public&sslmode=disable 執行，則命令應如下所示

命令輸出將顯示以下內容

如果您現在檢查您的資料庫，您會看到已建立 atlas_schema_revisions 資料表，其中包含兩個項目，指定 Atlas 遷移歷程記錄的開始。

您的專案現在應處於與範例儲存庫的 step-1 分支類似的狀態。

步驟 2：使用 Atlas 執行遷移

接下來，您將學習如何編輯您的 Prisma 結構描述，並使用 Atlas 遷移來反映資料庫中的變更。在高階層級，此流程將如下所示

1. 變更 Prisma 結構描述
2. 執行 atlas migrate diff 以建立遷移檔案
3. 執行 atlas migrate apply 以針對您的資料庫執行遷移檔案
4. 執行 prisma generate 以更新您的 Prisma Client
5. 透過 Prisma Client 在您的應用程式程式碼中存取修改後的結構描述

為了本教學課程的目的，我們將使用與 Post 模型具有多對多關係的 Tag 模型來擴充 Prisma 結構描述

進行變更後，現在執行命令以在本機電腦上建立遷移檔案

與之前一樣，這會在 atlas/migrations 資料夾內建立新檔案，例如 20241210132739.sql，其中包含反映您的資料模型變更的 SQL 程式碼。在我們的上述變更案例中，它看起來會像這樣

接下來，您可以使用與之前相同的 atlas migrate apply 命令來套用遷移，這次減去 --baseline 選項 (請記住取代 __DATABASE_URL__ 預留位置)

您的資料庫結構描述現在已更新，但您在 node_modules/@prisma/client 內產生的 Prisma Client 尚未意識到結構描述變更。這就是為何您需要使用 Prisma CLI 重新產生它的原因

現在，您可以進入您的應用程式程式碼，並針對更新後的結構描述執行查詢。在我們的案例中，這會是涉及新 Tag 模型的查詢，例如

您的專案現在應處於與範例儲存庫的 step-2 分支類似的狀態。

步驟 3：將部分索引新增至資料庫結構描述

在本節中，您將學習如何使用 Prisma 結構描述中不支援的功能來擴充您的資料庫結構描述。作為範例，我們將使用部分索引。

達成此目的的工作流程如下所示

1. 在 atlas 目錄內建立 SQL 檔案，以反映所需的變更
2. 更新 atlas.hcl 以包含該 SQL 檔案，以便 Atlas 知道它
3. 執行 atlas migrate diff 以建立遷移檔案
4. 執行 atlas migrate apply 以針對您的資料庫執行遷移檔案

這次，您不需要重新產生 Prisma Client，因為您沒有對 Prisma 結構描述檔案進行任何手動編輯。

讓我們繼續新增部分索引！

首先，在 atlas 目錄內建立名為 published_posts_index.sql 的檔案

然後，將以下程式碼新增至其中

這會在 Post 記錄上建立索引，這些記錄的 published 欄位設定為 true。當您查詢這些已發佈的貼文時，此查詢很有用，例如

您現在需要調整 atlas.hcl 檔案，以確保它知道結構描述的新 SQL 片段。您可以使用 composite_schema 方法來執行此作業。如下所示調整您的 atlas.hcl 檔案

請注意，composite_schema 僅透過 Atlas Pro 方案提供，並且需要您透過 atlas login 進行驗證。

Atlas 現在知道結構描述變更，因此您可以繼續並與之前一樣產生遷移檔案

您會再次看到 atlas/migrations 目錄內的新檔案。繼續並使用與之前相同的命令執行遷移 (以您自己的連線字串取代 __DATABASE_URL__)

恭喜！您的資料庫現在已使用部分索引更新，這將使您對已發佈貼文的查詢更快。

您的專案現在應處於與範例儲存庫的 step-3 分支類似的狀態。

結論

在本教學課程中，您學習了如何將 Atlas 整合到現有的 Prisma ORM 專案中。當使用 Prisma ORM 時，Atlas 可用於強化您的結構描述管理和遷移工作流程。

如果您想快速查看本教學課程的最終結果，請查看範例儲存庫。