從現有的 PostgreSQL 資料庫匯入資料

本指南提供將資料從現有的 PostgreSQL 資料庫匯入到 Prisma Postgres 的逐步說明。

您可以透過以下三個步驟完成此遷移：

1. 建立一個新的 Prisma Postgres 資料庫。
2. 透過 pg_dump 匯出您現有的資料。
3. 透過 pg_restore 將先前匯出的資料匯入到 Prisma Postgres。

在第三個步驟中，您將使用直接連線 (direct connection) 安全地連接到您的 Prisma Postgres 資料庫，以執行 pg_restore。

先決條件

• 現有 PostgreSQL 資料庫的連線 URL
• A帳號
• 已安裝 Node.js 18+
• 用於建立和還原備份的 PostgreSQL CLI 工具 (pg_dump, pg_restore)

請確保您的 PostgreSQL 工具版本與 Prisma Postgres 版本相符

Prisma Postgres 執行的是 PostgreSQL 17。您的 pg_dump 和 pg_restore 工具必須是 17 版本以確保相容性。您可以透過執行 pg_dump --version 或 pg_restore --version 來檢查您的版本。

1. 建立一個新的 Prisma Postgres 資料庫

請按照以下步驟建立一個新的 Prisma Postgres 資料庫

1. 登入並開啟主控台 (Console)。
2. 在您選擇的 工作區 (workspace) 中，點擊 New project (新增專案) 按鈕。
3. 在 Name (名稱) 欄位中輸入您的專案名稱，例如 hello-ppg。
4. 在 Prisma Postgres 區段中，點擊 Get started (開始使用) 按鈕。
5. 在 Region (區域) 下拉選單中，選擇離您目前位置最近的區域，例如 US East (N. Virginia)。
6. 點擊 Create project (建立專案) 按鈕。

資料庫配置完成後，取得您的直接連線字串 (direct connection string)

1. 導覽至您現有的 Prisma Postgres 實例。
2. 點擊專案側邊導覽列中的 API Keys 標籤。
3. 點擊 Create API key 按鈕。
4. 在彈出視窗中，為 API 金鑰提供一個 Name 並點擊 Create。
5. 複製以 postgres:// 開頭的連線字串，這就是您的直接連線字串。

儲存此連線字串，您將在步驟 3 中用到它。

2. 從現有資料庫匯出資料

在此步驟中，您將從現有的資料庫匯出資料，並將其儲存到本地機器上的 .bak 檔案中。

請確保已準備好現有資料庫的連線 URL，其結構應該如下所示

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

展開下方以獲取特定提供者的說明，協助您確認正確的連線字串

Neon

• 請務必透過關閉 Connection pooling 切換開關，選擇非連線池 (non-pooled) 的連線字串。
• sslmode 必須設定為 require 並附加到您的 Neon 資料庫 URL 後，指令才能正常運作。
• 連線 URL 應該看起來類似這樣

  postgresql://USER:PASSWORD@YOUR-NEON-HOST/DATABASE?sslmode=require

Supabase

• 請使用採用 Supavisor session 模式 的資料庫連線 URL。
• 連線 URL 應該看起來類似這樣

  postgres://postgres.apbkobhfnmcqqzqeeqss:[YOUR-PASSWORD]@aws-0-ca-central-1.pooler.supabase.com:5432/postgres

接下來，執行以下指令以匯出您的 PostgreSQL 資料庫資料（將 __DATABASE_URL__ 佔位符替換為您實際的資料庫連線 URL）

pg_dump \
  -Fc \
  -v \
  -d __DATABASE_URL__ \
  -n public \
  -f db_dump.bak

以下是此指令所使用 CLI 選項的簡要概述

• -Fc：針對備份使用自訂格式，推薦用於 pg_restore
• -v：以詳細模式 (verbose mode) 執行 pg_dump
• -d：指定資料庫連線字串
• -n：指定目標 PostgreSQL schema
• -f：指定備份檔案的輸出名稱

執行此指令將會建立一個名為 db_dump.bak 的備份檔案，您將在下一步中使用它將資料還原到您的 Prisma Postgres 資料庫。

3. 將資料匯入到 Prisma Postgres

在本節中，您將使用您的直接連線字串連接到您的 Prisma Postgres 執行個體，並透過 pg_restore 匯入資料。

您從步驟 1 取得的直接連線字串應該如下所示

postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require

使用 步驟 2 的備份檔案，透過執行此指令並使用 pg_restore 將資料還原到您的 Prisma Postgres 資料庫（將 __USER__ 和 __PASSWORD__ 替換為直接連線字串中的值）

pg_restore \
  -h db.prisma.io \
  -p 5432 \
  -U __USER__ \
  -d postgres \
  -v \
  ./db_dump.bak \
&& echo "-complete-"

當系統提示時，輸入您直接連線字串中的 __PASSWORD__。

提示

您也可以使用完整的連線字串格式

pg_restore \
  -d "postgres://USER:PASSWORD@db.prisma.io:5432/postgres?sslmode=require" \
  -v \
  ./db_dump.bak \
&& echo "-complete-"

指令執行完成後，您就已成功將資料從現有的 PostgreSQL 資料庫匯入到 Prisma Postgres 🎉

為了驗證匯入是否成功，您可以使用 Prisma Studio。您可以從以下方式開啟它：點擊專案左側導覽列中的 Studio 標籤，或執行此指令以在本地啟動 Prisma Studio

npx prisma studio

4. 更新您的應用程式程式碼以查詢 Prisma Postgres

情境 A：您已經在使用 Prisma ORM

如果您已經在使用 Prisma ORM，您需要更新您的資料庫連線 URL，使其指向您新的 Prisma Postgres 執行個體。

更新 .env 檔案中的 DATABASE_URL，使其符合您步驟 1 中的 Prisma Postgres 直接連線字串

.env

DATABASE_URL="postgres://USER:PASSWORD@db.prisma.io:5432/?sslmode=require"

然後，重新產生 Prisma Client，以便更新後的環境變數生效

npx prisma generate

完成後，執行您的應用程式，它應該可以如往常一樣運作。

提示

如需從零開始設定 Prisma ORM 與 Prisma Postgres 的完整指南（包括驅動程式配接器設定與最佳實踐），請參閱 Prisma ORM 與 Prisma Postgres 快速入門。

情境 B：您尚未在使用 Prisma ORM

如果您尚未在使用 Prisma ORM，您需要執行以下步驟來從您的應用程式中使用 Prisma Postgres

1. 在您的專案中安裝 Prisma CLI 與其他必要的相依套件
2. 對資料庫進行內省 (Introspect) 以產生 Prisma schema
3. 產生 Prisma Client
4. 更新應用程式中的查詢以使用 Prisma ORM

您可以在本指南中找到此過程的詳細逐步說明：將 Prisma ORM 新增至現有專案。