跳到主要內容

從 Early Access 版本升級

本指南說明如何將您的 Prisma Postgres Early Access (EA) 資料庫遷移到現在正式發布的 Prisma Postgres General Availability (GA) 資料庫。Prisma Postgres Early Access 的推出是為了讓早期採用者測試 Prisma 全新的託管 PostgreSQL 服務。隨著我們轉向 GA，安全地將資料從您的 EA 資料庫遷移到新的 GA 資料庫至關重要。

Prisma 將不會自動遷移您的資料，以確保其完整性。相反地，這個過程必須手動完成。您可以透過三個主要步驟完成此操作

  1. 透過 pg_dump 備份您的 EA 資料庫。
  2. 建立新的 GA 資料庫。
  3. 透過 pg_restore 將您的備份匯入 GA 資料庫。

我們將使用 @prisma/ppg-tunnel 套件來安全地連線到兩個資料庫。此工具設定了一個安全的代理通道，無需手動處理憑證。

您可以在此頁面上了解更多關於 Prisma Postgres 的資訊。

先決條件​

在您開始之前，請確保您已具備

  • 已安裝 Node.js (版本 16 或更高版本)。
  • PostgreSQL CLI 工具 (pg_dump、pg_restore)，用於建立和還原備份。
  • 您的 Prisma Postgres 資料庫的資料庫連線字串。

1. 備份 EA 資料庫​

1.1. 安裝 PostgreSQL 工具程式​

為了建立和還原備份，請確保您已安裝 PostgreSQL 命令列工具。根據您的作業系統執行以下命令

brew install postgresql@16
which pg_dump
which pg_restore
提示

如果您已安裝 PostgreSQL，但仍然看到 pg_dump 或 pg_restore 的 “command not found” 錯誤，請確保您的安裝目錄位於系統的 PATH 環境變數中。

注意

請確保您安裝的是 Postgresql 版本 16。其他版本可能會在備份和還原過程中導致錯誤。

1.2. 使用 @prisma/ppg-tunnel 直接連線到 EA 資料庫​

在您的終端機中，執行 npx @prisma/ppg-tunnel 以建立到您的 Early Access 資料庫的安全通道。

如果您目前的目錄中已經有一個設定了 DATABASE_URL 的 .env 檔案，通道 CLI 將會自動偵測到它 — 無需手動匯出。但是，如果您尚未設定 .env 檔案，您需要明確設定 DATABASE_URL 環境變數。

設定環境變數 (使用您實際的 EA 資料庫 URL)

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."
注意

如果您在終端機中明確設定了 DATABASE_URL，則該值將優先於 .env 檔案中的值。

執行通道

npx @prisma/ppg-tunnel --host 127.0.0.1  --port 5432

您應該會看到類似以下的輸出

Prisma Postgres auth proxy listening on 127.0.0.1:5432 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      5432
username:  <anything>
password:  <none>
==============================
注意

請注意，您在輸出中看到的埠號將是一個隨機分配的埠號，可能與此處提及的埠號不同。此外，保持此終端機視窗開啟，以便通道保持活動狀態！如果您關閉它，通道將會斷線。

  1. 從終端機輸出中複製埠號，您將在下一步的 pg_dump 命令中需要它。

1.3. 使用 pg_dump 建立備份​

在通道運作的情況下，您現在可以透過執行以下命令來傾印 EA 資料庫

PGSSLMODE=disable \
pg_dump \
  -h 127.0.0.1 \
  -p 5432 \
  -Fc \
  -v \
  -d postgres \
  -f ./mydatabase.bak \
&& echo "-complete-"

PGSSLMODE=disable 表示本地不需要 SSL，因為通道已經加密了連線。

`-h` is the host (127.0.0.1)
`-p` is the port, which should match the one from the tunnel output.
`-Fc` uses the custom format for backups, recommended for pg_restore.
`-d` postgres is the default database name used in Prisma Postgres.
`-f` ./mydatabase.bak specifies the backup file name and location.
`-v` runs pg_dump in verbose mode.

這應該會在目前目錄中建立名為 mydatabase.bak 的備份檔案。我們將在後續步驟中使用此備份檔案進行匯入。

2. 建立新的 GA 資料庫​

接下來，建立您的 GA (General Availability) 資料庫

  1. 造訪並登入 (或建立帳戶)。
  2. 在您選擇的區域中建立 Prisma Postgres 資料庫。
  3. 複製資料庫 URL 以供稍後使用。

Prisma Postgres GA 使用 PostgreSQL 17，因此您將把 EA 備份還原到這個新的環境中。

3. 將備份匯入 GA 資料庫​

3.1. 使用 @prisma/ppg-tunnel 連線到 GA 資料庫​

開啟新的終端機 (或停止先前的通道) 並連線到您的 GA 資料庫

設定新 GA 資料庫的環境變數

export DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=eyJhbGciOiJIUzI..."

執行通道

npx @prisma/ppg-tunnel --host 127.0.0.1 --port 5432

您應該會看到類似以下的輸出

Prisma Postgres auth proxy listening on 127.0.0.1:52604 🚀

Your connection is authenticated using your Prisma Postgres API key.
...

==============================
hostname:  127.0.0.1
port:      52604
username:  <anything>
password:  <none>
==============================
注意

同樣地，保持此通道程序運作以維持連線！

3.2. 使用 pg_restore 還原備份​

使用步驟 1 中的備份檔案，透過執行以下命令，使用 pg_restore 將資料還原到您的 GA 資料庫中

PGSSLMODE=disable \
pg_restore \
  -h 127.0.0.1 \
  -p 5432 \
  -v \
  -d postgres \
  ./mydatabase.bak \
&& echo "-complete-"

此外，在本例中，資料庫名稱為 postgres。您可以將其替換為您想要的資料庫名稱。您如何命名您的資料庫並不重要，因為您將能夠像平常一樣使用 Prisma Postgres。備份檔案名稱 (在我們的範例中為 mydatabase.bak) 應與您在步驟 1 中建立的名稱相符。

此命令將備份還原到 GA 資料庫中。如果成功，您應該會在終端機中看到 -complete-。

後續步驟​

使用您最愛的資料庫 IDE 或 Prisma Client 連線，以確認所有表格、列和結構描述都與您舊的 EA 環境相符。

恭喜！您已成功將您的 Prisma Postgres Early Access 資料庫遷移到 Prisma Postgres GA。如果您遇到任何問題，請聯絡我們的支援團隊。