使用 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 中稱為 _dev database_）。與 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 可用於增強您的模式管理和遷移工作流。

如果您想快速檢視本教程的最終結果，請檢視示例倉庫。