從搶先體驗版升級

本指南將向您展示如何將您的Prisma Postgres搶先體驗版 (EA) 資料庫遷移到現已正式釋出的Prisma Postgres通用版 (GA) 資料庫。Prisma Postgres搶先體驗版旨在讓早期採用者測試Prisma新的託管式PostgreSQL服務。隨著我們轉向通用版，安全地將資料從EA資料庫遷移到新的GA資料庫至關重要。

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

透過pg_dump備份您的EA資料庫。
建立一個新的GA資料庫。
透過pg_restore將您的備份匯入到GA資料庫中。

我們將使用@prisma/ppg-tunnel包來安全連線兩個資料庫。此工具建立了一個安全的代理隧道，無需手動處理憑證。

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

先決條件

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

已安裝Node.js（版本16或更高）。
用於建立和恢復備份的PostgreSQL CLI工具（pg_dump, pg_restore）。
您的Prisma Postgres資料庫的資料庫連線字串。

要建立和恢復備份，請確保您已安裝PostgreSQL命令列工具。根據您的作業系統執行以下命令：

macOS
Windows
Linux

brew install postgresql@16
which pg_dump
which pg_restore

# Download from the official PostgreSQL website:
# https://postgres.tw/download/windows/
# During installation, select "Command Line Tools".
# Then verify with:

where pg_dump
where pg_restore

sudo apt-get update
sudo apt-get install postgresql-client-16
which pg_dump
which pg_restore

提示

如果您已安裝PostgreSQL，但仍然看到pg_dump或pg_restore的“命令未找到”錯誤，請確保您的安裝目錄已新增到系統的PATH環境變數中。

注意

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

選項A：互動式方法

如果您喜歡引導式、一鍵式解決方案，推薦使用此方法。在此模式下，@prisma/ppg-tunnel CLI將：

提示您輸入搶先體驗版 (EA) 資料庫API金鑰（或DATABASE_URL）。
在後臺使用pg_dump將您的EA資料庫備份到當前目錄中的一個檔案。
提示您輸入新的GA資料庫URL或API金鑰。
使用pg_restore將備份檔案匯入到您的GA資料庫。

互動模式不接受任何CLI引數或從環境中讀取API金鑰。您必須以互動方式提供它們。

步驟

開啟終端並執行：

npx @prisma/ppg-tunnel migrate-from-ea

當提示時，貼上您的搶先體驗版資料庫金鑰或連線字串。CLI將在當前目錄中建立一個.bak檔案。
當再次提示時，貼上您的GA資料庫金鑰或連線字串。CLI將自動將.bak檔案恢復到新的GA資料庫中。
完成後，使用您喜歡的資料庫IDE連線以驗證GA資料庫中的資料。

選項B：手動備份和恢復方法

如果您喜歡或需要對遷移過程進行更精細的控制（或直接傳遞環境變數），請遵循以下手動步驟。遷移涉及三個主要部分：

透過pg_dump備份您的EA資料庫。
建立一個新的GA資料庫。
透過pg_restore將您的備份匯入到GA資料庫中。

我們仍將使用@prisma/ppg-tunnel包來安全連線這兩個資料庫。

1. 備份EA資料庫

1.1. 使用`@prisma/ppg-tunnel`直接連線EA資料庫

在您的終端中，執行npx @prisma/ppg-tunnel以建立與您的搶先體驗版資料庫的安全隧道。

如果您當前目錄中已有一個設定了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>
==============================

注意

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

從終端輸出中複製埠號，您在下一步的pg_dump命令中會用到它。

1.2. 使用`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（通用版）資料庫：

訪問並登入（或建立帳戶）。
在您選擇的區域建立一個Prisma Postgres資料庫。
複製資料庫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搶先體驗版資料庫遷移到Prisma Postgres通用版。如果您遇到任何問題，請聯絡我們的支援團隊。

先決條件​

選項A：互動式方法​

步驟​

選項B：手動備份和恢復方法​

1. 備份EA資料庫​

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

1.2. 使用pg_dump建立備份​

2. 建立新的GA資料庫​

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

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

3.2. 使用pg_restore恢復備份​

下一步​