從現有資料庫匯入

PostgreSQL

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

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

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

在第三個步驟中，您將使用 TCP 通道，以便在執行 pg_restore 期間安全地連線到您的 Prisma Postgres 資料庫。

先決條件

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

1. 建立新的 Prisma Postgres 資料庫

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

登入到並開啟控制台。
在您選擇的工作區中，點擊 New project（新增專案）按鈕。
在 Name（名稱）欄位中輸入您的專案名稱，例如 hello-ppg。
在 Prisma Postgres 區塊中，點擊 Get started（開始使用）按鈕。
在 Region（區域）下拉式選單中，選取離您目前位置最近的區域，例如 US East (N. Virginia)（美國東部 (維吉尼亞北部)）。
點擊 Create project（建立專案）按鈕。

一旦您的資料庫完成佈建，請在 Set up database access（設定資料庫存取權限）區塊中找到您的 Prisma Postgres 連線 URL 並儲存起來以供稍後使用，您將在步驟 3 中需要它。

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

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

請確保您已準備好現有資料庫的連線 URL，其結構應類似於這樣

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

展開下方以取得供應商特定的指示，以協助您判斷正確的連線字串

Neon

請務必關閉 Connection pooling（連線池）切換按鈕，以選取非集區連線字串。
sslmode 必須設定為 require 並附加到您的 Neon 資料庫 URL，此命令才能運作。

連線 URL 應類似於這樣

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

Supabase

使用使用 Supavisor 工作階段模式的資料庫連線 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：以詳細模式執行 pg_dump
-d：指定資料庫連線字串
-n：指定目標 PostgreSQL 結構描述
-f：指定備份檔案的輸出名稱

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

3. 將資料匯入到 Prisma Postgres

在此步驟中，您將使用 TCP 通道連線到您的 Prisma Postgres 執行個體，並透過 pg_restore 匯入資料。

您還需要步驟 1 中的 Prisma Postgres 連線 URL，它應該看起來類似於這樣

prisma+postgres://accelerate.prisma-data.net/?api_key=ey...

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

若要設定環境變數，請開啟您的終端機並將 DATABASE_URL 環境變數設定為您的 Prisma Postgres 資料庫 URL 的值（將 __API_KEY__ 預留位置替換為您實際資料庫連線 URL 的 API 金鑰）

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

注意

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

接下來，啟動 TCP 通道

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

顯示CLI結果

Prisma Postgres auth proxy listening on 127.0.0.1:5433 🚀

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

==============================
hostname:  127.0.0.1
port:      5433
username:  <anything>
password:  <none>
==============================

注意

保持您目前的終端機視窗或分頁開啟，以便通道程序繼續執行且連線保持開啟。

現在，使用上一步中的 db_dump.bak 備份檔案，透過 pg_restore 命令將資料還原到您的 Prisma Postgres 資料庫中

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

注意

您不需要為此命令提供使用者名稱和密碼憑證，因為 TCP 通道已透過您的 Prisma Postgres 連線 URL 中的 API 金鑰驗證您的身分。

您現在已成功將資料從您現有的 PostgreSQL 資料庫匯入到 Prisma Postgres 🎉

為了驗證匯入是否成功，您可以使用 Prisma Studio。您可以透過點擊專案左側導覽列中的 Studio 分頁開啟它，或執行此命令在本機啟動 Prisma Studio

npx prisma studio

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

情境 A：您已在使用 Prisma ORM

如果您已在使用 Prisma ORM，您唯一需要做的是

將 Prisma Accelerate 擴充功能新增到您的專案
更新資料庫連線 URL 並重新產生 Prisma Client

4.A.1. 新增 Prisma Accelerate 擴充功能

當使用 Prisma Postgres 時，Th Prisma Accelerate 擴充功能是必要的。如果您目前未使用 Prisma Accelerate 與 Prisma ORM，請完成以下步驟，使 Prisma ORM 能夠與 Prisma Postgres 搭配運作。

首先，在您的專案中安裝 @prisma/extension-accelerate 套件

npm install @prisma/extension-accelerate

然後，將擴充功能新增到您的 Prisma Client 執行個體

import { withAccelerate } from '@prisma/extension-accelerate'

const prisma = new PrismaClient().$extends(withAccelerate())

4.A.2. 更新資料庫連線 URL

資料庫連線 URL 是透過 schema.prisma 檔案中 datasource 區塊的 url 設定的。最常見的情況是透過名為 DATABASE_URL 的環境變數設定。

schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

下一步假設您使用 .env 檔案來設定 DATABASE_URL 環境變數（如果情況並非如此，您可以使用您偏好的方式設定環境變數）。

開啟 .env 並更新 DATABASE_URL 環境變數的值，使其與您的 Prisma Postgres 連線 URL 相符，看起來類似於這樣

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

最後一步，您需要重新產生 Prisma Client，以便更新後的環境變數生效，並且您的查詢在未來可以連線到 Prisma Postgres

npx prisma generate --no-engine

完成此操作後，您可以執行您的應用程式，它應該可以像以前一樣運作。

情境 B：您尚未使用 Prisma ORM

如果您尚未使用 Prisma ORM，您需要完成以下步驟，才能從您的應用程式使用 Prisma Postgres

在您的專案中安裝 Prisma CLI
內省資料庫以產生 Prisma 結構描述
產生 Prisma Client
更新您的應用程式中的查詢以使用 Prisma ORM

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

先決條件​

1. 建立新的 Prisma Postgres 資料庫​

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

3. 將資料匯入到 Prisma Postgres​

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

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

4.A.1. 新增 Prisma Accelerate 擴充功能​

4.A.2. 更新資料庫連線 URL​

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