使用 Prisma Postgres 進行本地開發
Prisma Postgres 是一款生產等級的雲端原生資料庫，非常適合用於 Staging 和生產環境。為了進行快速迭代和隔離測試，您可以透過 prisma dev 指令執行一個本地的 Prisma Postgres 實例（由 PGlite 驅動）。本頁面說明如何安裝與啟動本地 Prisma Postgres 資料庫。
本地 Prisma Postgres 目前處於 預覽 (Preview) 階段，並正在積極開發中。
設定 Prisma Postgres 本地開發環境
請按照以下步驟設定本地 Prisma Postgres 以進行開發。
本地 Prisma Postgres 需要 Node.js v20 或更高版本。
1. 啟動本地 Prisma Postgres
進入您的專案目錄，並使用以下指令啟動本地 Prisma Postgres 伺服器
npx prisma dev
這將啟動一個本地 Prisma Postgres 伺服器，您可以使用 Prisma ORM 或其他工具連接至該伺服器。指令的輸出如下所示
$ npx prisma dev
✔ Great Success! 😉👍
Your prisma dev server default is ready and listening on ports 63567-63569.
╭──────────────────────────────╮
│[q]uit [h]ttp url [t]cp urls│
╰──────────────────────────────╯
現在按下
- q 退出
- h 查看可供 Prisma ORM 連接的連線 URL
- t 查看可供 任何工具 連接的連線 URL
如果您想透過 Prisma ORM 連接，請按下鍵盤上的 h，複製 DATABASE_URL 並將其存入您的 .env 檔案中。這將用於連接到本地 Prisma Postgres 伺服器。
DATABASE_URL="prisma+postgres://:51213/?api_key=__API_KEY__"
在您開發應用程式時，請保持本地 Prisma Postgres 伺服器在背景執行。
2. 執行遷移與植入資料
接著在另一個終端機分頁中，執行 prisma migrate dev 指令來建立資料庫並執行遷移
npx prisma migrate dev
在執行 prisma migrate dev 指令之前，請確保本地 Prisma Postgres 伺服器正在執行中。
如果您必須使用不同的連接埠，請附加 --port <number>（例如 npx prisma migrate dev --port 5422），並更新您的 DATABASE_URL（或其他連線設定）以進行匹配。
這將建立資料庫並執行遷移。
如果您有用於植入資料庫的腳本 (seeder script)，也應在此步驟中一併執行。
3. 在本地執行您的應用程式
啟動您應用程式的開發伺服器。現在您可以透過 Prisma ORM 對本地 Prisma Postgres 實例執行查詢。
若要轉移到生產環境，您只需更新 .env 檔案中的資料庫 URL 為 Prisma Postgres 的正式連線字串，無需更改任何額外的應用程式邏輯。
使用不同的本地 Prisma Postgres 實例
您可以透過 prisma dev 指令的 --name (-n) 選項來指定特定的本地 Prisma Postgres 實例，例如
npx prisma dev --name mydb1
每當您向 prisma dev 傳遞 --name mydb1 時，該指令將返回指向名為 mydb1 的本地實例的同一個連線字串。
停止 Prisma Postgres 實例
您可以使用此指令停止正在執行的 Prisma Postgres 實例
npx prisma dev stop <glob>
<glob> 是用於指定應停止哪些本地 Prisma Postgres 實例的 glob 模式佔位符，例如
npx prisma dev stop mydb # stops a DB called `mydb`
若要停止所有以 mydb 開頭的資料庫（例如 mydb-dev 和 mydb-prod），您可以使用 glob
npx prisma dev stop mydb* # stops all DBs starting with `mydb`
移除 Prisma Postgres 實例
Prisma Postgres 會將本地 Prisma Postgres 實例的資訊與資料儲存在您的檔案系統上。若要從不再使用的資料庫中移除任何痕跡，您可以執行以下指令
npx prisma dev rm <glob>
<glob> 是用於指定應移除哪些本地 Prisma Postgres 實例的 glob 模式佔位符，例如
npx prisma dev rm mydb # removes a DB called `mydb`
若要停止所有以 mydb 開頭的資料庫（例如 mydb-dev 和 mydb-prod），您可以使用 glob
npx prisma dev rm mydb* # removes all DBs starting with `mydb`
將本地 Prisma Postgres 與任何 ORM 搭配使用
本地 Prisma Postgres 支援 直接 TCP 連線，允許您透過任何工具連接它。
為了連接到您的本地 Prisma Postgres 實例，請使用 prisma dev 返回的 postgres:// 連線字串。
透過 Prisma VS Code 擴充功能管理本地 Prisma Postgres 實例
Prisma VS Code 擴充功能 具有用於管理 Prisma Postgres 實例的專屬 UI。
若要使用它，請安裝 VS Code 擴充功能並在 VS Code 編輯器的活動列中找到 Prisma logo。它支援以下工作流程
- 建立與刪除資料庫
- 啟動與停止特定資料庫的伺服器
- "push to cloud"（推送到雲端）：將資料庫從本地移動到遠端
以程式化方式管理本地 Prisma Postgres
您可以在不呼叫 CLI 的情況下，從 Node.js 啟動和停止本地 Prisma Postgres 伺服器。這使用了來自 @prisma/dev 的未記錄、不穩定的 API，可能會在沒有通知的情況下更改。請自行承擔風險使用。這對於需要為每個測試或套件提供臨時本地資料庫的整合測試特別有用。
這是一個完整的可執行範例，執行時會列印 [{abba: 1}]
import { Client } from 'pg'
import { unstable_startServer } from '@prisma/dev'
import { getPort } from 'get-port-please'
async function startLocalPrisma(name: string) {
const port = await getPort()
return await unstable_startServer({
name, // required, use a unique name if running tests in parallel
port, //optional, defaults to 51213
databasePort: port + 1, // optional, defaults to 51214
shadowDatabasePort: port + 2, // optional, defaults to 51215
persistenceMode: 'stateless' // optional, defaults to 'stateless'. Use 'stateful' to persist data between runs
})
}
// Usage in tests
const server = await startLocalPrisma(`my-tests-${Date.now()}`)
try {
const client = new Client({ connectionString: server.database.connectionString })
await client.connect()
const res = await client.query(`SELECT 1 as "abba"`)
console.log(res.rows)
client.end()
} finally {
await server.close!()
}
API 引數
unstable_startServer() 函式接受以下選項
| 參數 | 必填 | 描述 | 預設值 |
|---|---|---|---|
name | ✅ | 本地 Prisma Postgres 實例的唯一識別碼。如果同時執行多個伺服器，請使用不同的名稱。 | — |
port | ❌ | Prisma 引擎伺服器的連接埠。如果連接埠已被使用，則會拋出錯誤。 | 51213 |
databasePort | ❌ | 嵌入式 PostgreSQL 資料庫的連接埠。用於所有 Prisma ORM 連線。 | 51214 |
shadowDatabasePort | ❌ | 遷移期間使用的陰影資料庫 (shadow database) 連接埠。 | 51215 |
persistenceMode | ❌ | 定義資料如何持久化 • 'stateless' — 執行之間不保留任何資料• 'stateful' — 資料在本地持久化 | 'stateless' |
您可以使用像 get-port-please 這樣的程式庫動態選擇可用連接埠，以避免同時執行多個實例時發生衝突。
註解
- 並行執行測試時，請分配唯一的連接埠和
name值。 - 使用
server.database.connectionString連接 Postgres 客戶端或 ORM。 - 此模式非常適合執行需要本地資料庫的測試。
已知限制
快取在本地是模擬的
Prisma Postgres 快取在本地是被模擬的。查詢總是直接與本地 Prisma Postgres 實例互動，繞過快取設定。
const users = await prisma.user.findMany({
cache: { ttl: 60 },
});
當您在 Staging 和生產環境中使用 Prisma Postgres 時，快取功能將正常運作。
僅支援單一連線
本地 Prisma Postgres 資料庫伺服器一次僅接受一個連線。額外的連線嘗試將會排隊，直到活動連線關閉。對於大多數本地開發和測試場景而言，此限制已足夠。
不支援 HTTPS 連線
本地 Prisma Postgres 伺服器不使用 HTTPS。我們建議不要自行託管它。