prisma-postgres-setup

Prisma Postgres 設定

此程序性技能會引導您透過 Management API 佈建新的 Prisma Postgres 資料庫，並將其連接到本機專案。

何時使用

請在以下情況使用此技能：

• 為專案設定新的 Prisma Postgres 資料庫
• 建立 Prisma Postgres 專案並在本機連接
• 取得 Prisma Postgres 的連線字串
• 透過 Management API（而非 Console UI）佈建資料庫

請勿在以下情況使用此技能：

• 設定 CI/CD 預覽資料庫 — 請使用 prisma-postgres-cicd
• 在應用程式中建立多租戶資料庫佈建 — 請使用 prisma-postgres-integrator
• 處理已存在且已連線的資料庫（綱要/遷移任務為標準 Prisma CLI）

先決條件

• Node.js 18+
• Prisma Postgres 工作區（若無，請在 https://console.prisma.io 建立）
• 工作區服務權杖（請參閱 references/auth.md）

UX 指南

當向使用者呈現選擇時（區域選擇、專案刪除等），請使用您平台的互動式選取機制（例如 Claude Code 中的 ask 工具，或其他代理程式中的結構化提示）。請勿列印靜態表格並要求使用者輸入值 — 請提供可選取的選項，讓使用者能以最少操作進行選取。

工作流程

請依序執行以下步驟。每個步驟都包含要進行的 API 呼叫以及如何處理回應。

步驟 1：驗證

您需要一個服務權杖。請依序嘗試以下方法：

1a. 使用者提示中的權杖

檢查使用者是否在初始訊息中包含了服務權杖（例如「使用權杖 eyJ... 設定 Prisma Postgres」）。如果是，請完全按照提供的內容使用 — 請勿截斷、重新編碼或透過檔案來回傳遞。將其儲存在 shell 變數中以供後續呼叫使用。

1b. 環境變數中的權杖

檢查環境變數或 .env 檔案中是否有 PRISMA_SERVICE_TOKEN。

1c. 要求使用者建立權杖

如果沒有可用的權杖，請指示使用者：

在 Prisma Console → 工作區設定 → 服務權杖中建立服務權杖。
複製權杖並貼到此處。

請參閱 references/auth.md 以了解服務權杖建立的詳細資訊。

取得權杖後，將其儲存在 shell 變數（PRISMA_SERVICE_TOKEN）中，並用於所有後續的 API 呼叫。

步驟 2：列出可用區域

擷取可用的 Prisma Postgres 區域清單，讓使用者選擇部署位置。

curl -s -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  https://api.prisma.io/v1/regions/postgres

回應包含一個區域陣列，每個區域有 id、name 和 status。僅呈現 status 為 available 的區域。

將區域呈現為互動式選單 — 讓使用者從選項中選取，而非手動輸入區域 ID。

請參閱 references/endpoints.md 以了解完整的回應結構。

步驟 3：建立包含資料庫的專案

curl -s -X POST https://api.prisma.io/v1/projects \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<project-name>",
    "region": "<region-id>",
    "createDatabase": true
  }'

預設使用目前目錄名稱作為專案名稱。

回應包裝在 { "data": { ... } } 中。請擷取：

• data.id — 專案 ID（前綴為 proj_）
• data.database.id — 資料庫 ID（前綴為 db_）
• data.database.connections[0].endpoints.direct.connectionString — 直接 PostgreSQL 連線字串

請使用直接連線字串（endpoints.direct.connectionString）。請勿使用 pooled 或 accelerate 端點 — 這些適用於舊版 Accelerate 設定，新專案不需要。

如果回應狀態為 provisioning，請等待幾秒鐘並輪詢 GET /v1/databases/<database-id>，直到 status 變為 ready。

如果因資料庫限制而建立失敗，請列出使用者現有的專案，並以互動式選單呈現供刪除。使用者選取後，刪除該專案並重試。

請參閱 references/endpoints.md 以了解完整的請求/回應結構。

步驟 4：建立具名連線（選用）

如果您需要專用連線（例如每個開發者或每個環境），請建立一個：

curl -s -X POST https://api.prisma.io/v1/databases/<database-id>/connections \
  -H "Authorization: Bearer $PRISMA_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "dev" }'

從 data.endpoints.direct.connectionString 擷取直接連線字串。

步驟 5：設定本機專案

1. 安裝相依套件：

npm install prisma @prisma/client @prisma/adapter-pg pg dotenv

需要全部五個套件：

• prisma — 用於遷移、綱要推送、用戶端產生的 CLI
• @prisma/client — 產生的查詢用戶端
• @prisma/adapter-pg — Prisma 7 驅動程式適配器，用於直接 PostgreSQL 連線
• pg — Node.js PostgreSQL 驅動程式（由適配器使用）
• dotenv — 載入 .env 變數供 prisma.config.ts 使用

2. 將直接連線字串寫入 .env。附加到檔案（如果已存在）— 請勿覆寫現有項目：

DATABASE_URL="<direct-connection-string>"

3. 確認 .gitignore 包含 .env。如果 .gitignore 不存在，請建立。如果 .env 未加入 gitignore，請警告使用者。

4. 確保 package.json 已設定 "type": "module"（Prisma 7 產生 ESM 輸出）。

5. 如果 prisma/schema.prisma 不存在，請執行 npx prisma init 來建立專案結構。這會同時建立 prisma/schema.prisma 和 prisma.config.ts。

6. 確保 schema.prisma 的資料來源區塊中使用了 postgresql 提供者，且沒有 url 或 directUrl（Prisma 7 在 prisma.config.ts 中管理連線 URL，而非在綱要中）：

datasource db {
  provider = "postgresql"
}

7. 確保 prisma.config.ts 從環境變數載入連線 URL：

import path from 'node:path'
import { defineConfig } from 'prisma/config'
import 'dotenv/config'

export default defineConfig({
  earlyAccess: true,
  schema: path.join(import.meta.dirname, 'prisma', 'schema.prisma'),
  datasource: {
    url: process.env.DATABASE_URL!,
  },
})

重要的 Prisma 7 注意事項：

• 連線 URL 放在 prisma.config.ts 中，絕對不要放在 schema.prisma 中
• schema.prisma 中的提供者必須是 "postgresql"（而非 "prismaPostgres"）
• 必須在 prisma.config.ts 中匯入 dotenv/config 以載入 .env 變數

步驟 6：定義綱要並推送

如果綱要已有模型，請跳到推送。否則，將這些選項呈現為互動式選單：

1. 「我會手動定義綱要」 — 告訴使用者編輯 prisma/schema.prisma，準備好後再回來。等待使用者完成後再繼續。
2. 「給我一個入門綱要」 — 將 Blog 入門綱要（User、Post、Comment 及其關聯）加入 prisma/schema.prisma。向使用者顯示已加入的內容，並詢問是否要在推送前進行調整。
3. 「我會描述我需要的內容」 — 要求使用者以自然語言描述其資料模型（例如「我正在建立一個包含專案、任務和團隊成員的任務管理器」）。根據描述產生綱要，顯示給使用者，並在推送前要求確認。

一旦綱要包含模型且使用者準備就緒，請建立遷移並產生用戶端：

npx prisma migrate dev --name init

這會同時在 prisma/migrations/ 中建立遷移檔案並產生用戶端。遷移歷史記錄對於 CI/CD 工作流程（prisma migrate deploy）和生產部署至關重要。

僅在使用者明確要求僅限原型模式（無遷移歷史記錄）時，才使用 npx prisma db push。在這種情況下，請接著執行 npx prisma generate。

步驟 7：驗證連線

產生用戶端後，建立並執行一個快速驗證指令碼，以確認一切正常運作。這至關重要 — 請勿跳過此步驟。

建立名為 test-connection.ts 的檔案：

import 'dotenv/config'
import pg from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.js'

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

const result = await prisma.$queryRawUnsafe('SELECT 1 as connected')
console.log('Connected to Prisma Postgres:', result)

await prisma.$disconnect()
await pool.end()

執行它：

npx tsx test-connection.ts

Prisma 7 用戶端實例化規則：

• 從 ./generated/prisma/client.js 匯入（而非 ./generated/prisma）
• 使用 DATABASE_URL 連線字串建立 pg.Pool
• 將其包裝在 PrismaPg 適配器中
• 將 { adapter } 傳遞給 PrismaClient 建構函式
• 請勿使用 datasourceUrl — 該選項在 Prisma 7 中不存在
• 請勿使用不帶引數的 new PrismaClient() — 這會擲出錯誤

驗證成功後，刪除 test-connection.ts。

然後分享連結，讓使用者探索其資料庫：

• Prisma Studio（CLI）： npx prisma studio — 在本機開啟視覺化資料瀏覽器
• Console： https://console.prisma.io/<workspaceId>/<projectId>/<databaseId>/dashboard — 從步驟 3 傳回的 ID 中移除前綴（wksp_、proj_、db_）以建立此 URL

請參閱 references/prisma7-client.md 以取得完整的用戶端實例化參考。

錯誤處理

請參閱 references/api-basics.md 以取得完整的錯誤參考。關鍵的自我修正模式：

HTTP 狀態	錯誤代碼	動作
401	authentication-failed	服務權杖無效或已過期。要求使用者在 Console → 工作區設定 → 服務權杖中建立新的權杖。
404	resource-not-found	檢查資源 ID 是否包含正確的前綴（proj_、db_、con_）。
422	validation-error	根據端點綱要檢查請求主體。常見問題：缺少 name、無效的 region。
429	rate-limit-exceeded	退避並在幾秒後重試。

參考檔案

詳細的 API 和使用資訊位於：

references/auth.md             — 服務權杖的建立與使用
references/api-basics.md       — 基礎 URL、信封、ID、錯誤、分頁
references/endpoints.md        — 專案、資料庫、連線、區域的端點詳細資訊
references/prisma7-client.md   — Prisma 7 用戶端實例化與使用模式