PostgreSQL
PostgreSQL 資料來源連接器將 Prisma ORM 連接到 PostgreSQL 資料庫伺服器。
預設情況下，PostgreSQL 連接器包含一個負責連接到您的資料庫的資料庫驅動程式。您可以透過 驅動程式轉接器 (driver adapter)（預覽版）使用來自 Prisma Client 的 JavaScript 資料庫驅動程式來連接到您的資料庫。
急需一個 Postgres 實例嗎？
透過 Prisma Postgres，您可以在三次點擊內讓資料庫在裸機上執行。包含連線池 (connection pooling)、查詢快取 (query caching) 和自動備份功能。立即開始。
想要以更快的速度開始使用 Prisma Postgres？只需在終端機中執行 npx prisma init --db 即可。🚀
範例
若要連接到 PostgreSQL 資料庫伺服器，您需要在 Prisma Schema 中設定 datasource 區塊。
datasource db {
provider = "postgresql"
}
datasource 區塊指定了 postgresql 資料來源連接器。
在 Prisma ORM 7 中，資料庫連線 URL 設定於 prisma.config.ts。
import { defineConfig, env } from 'prisma/config'
import 'dotenv/config'
export default defineConfig({
schema: 'prisma/schema.prisma',
datasource: {
url: env('DATABASE_URL'),
},
})
此設定使用 環境變數 來提供資料庫連線 URL。
使用 node-postgres 驅動程式
自 v5.4.0 起，您可以將 Prisma ORM 與來自 JavaScript 生態系統的資料庫驅動程式搭配使用（而不是使用 Prisma ORM 內建的驅動程式）。您可以透過使用 驅動程式轉接器 (driver adapter) 來達成此目的。
對於 PostgreSQL，node-postgres (pg) 是 JavaScript 生態系統中最受歡迎的驅動程式之一。它可以用於任何透過 TCP 存取的 PostgreSQL 資料庫。
本節說明如何將其與 Prisma ORM 和 @prisma/adapter-pg 驅動程式轉接器搭配使用。
1. 安裝相依套件
首先，安裝 Prisma ORM 用於 pg 的驅動程式轉接器
npm install @prisma/adapter-pg
2. 使用驅動程式轉接器實例化 Prisma Client
現在，當您實例化 Prisma Client 時，您需要將 Prisma ORM 驅動程式轉接器的實例傳遞給 PrismaClient 建構函式。
import 'dotenv/config'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '../generated/prisma/client'
const connectionString = `${process.env.DATABASE_URL}`
const adapter = new PrismaPg({ connectionString })
const prisma = new PrismaClient({ adapter })
請注意，此程式碼要求 DATABASE_URL 環境變數必須設定為您的 PostgreSQL 連線字串。您可以在下方了解更多關於連線字串的資訊。
注意事項
指定 PostgreSQL Schema
您可以透過在實例化 PrismaPg 時傳入 schema 選項來指定 PostgreSQL schema。
const adapter = new PrismaPg(
{ connectionString },
{ schema: 'myPostgresSchema' }
)
連接詳情
連接 URL
Prisma ORM 遵循 PostgreSQL 官方準則 所指定的連線 URL 格式，但不支援所有參數，並包含如 schema 等額外參數。以下是 PostgreSQL 連線 URL 所需元件的總覽。
基礎 URL 和路徑
以下是使用大寫字母預留位置的 base URL 和 path 結構範例。
postgresql://USER:PASSWORD@HOST:PORT/DATABASE
以下元件組成了資料庫的 base URL，它們皆為必要項目：
| 名稱 | 佔位符 | 描述 |
|---|---|---|
| 主機 | HOST | 資料庫伺服器的 IP 位址/網域，例如 localhost |
| 連接埠 | PORT | 資料庫伺服器運行的連接埠，例如 5432 |
| User | USER | 您的資料庫使用者名稱，例如 janedoe |
| 密碼 | PASSWORD | 您的資料庫使用者密碼 |
| 資料庫 | DATABASE | 您想要使用的 資料庫名稱，例如 mydb |
引數
連線 URL 也可以帶有參數。以下是上述同一個範例，其中三個 參數 使用了大寫字母的預留位置。
postgresql://USER:PASSWORD@HOST:PORT/DATABASE?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE
可以使用以下參數：
| 參數名稱 | 必填 | 預設值 | 描述 |
|---|---|---|---|
schema | 是 | public | 您想要使用的 schema 名稱，例如 myschema |
connection_limit | 否 | num_cpus * 2 + 1 | 連線池 (connection pool) 的最大大小（Prisma ORM v6 及更早版本） |
connect_timeout | 否 | 5 | 等待開啟新連線的最長秒數，0 表示無逾時 |
pool_timeout | 否 | 10 | 從連線池等待新連線的最長秒數，0 表示無逾時 |
sslmode | 否 | prefer | 設定是否使用 TLS。可能的值：prefer、disable、require |
sslcert | 否 | 伺服器憑證的路徑。憑證路徑會 相對於 ./prisma 資料夾解析 | |
sslrootcert | 否 | 根憑證的路徑。憑證路徑會 相對於 ./prisma 資料夾解析 | |
sslidentity | 否 | PKCS12 憑證的路徑 | |
sslpassword | 否 | 用於保護 PKCS12 檔案的密碼 | |
sslaccept | 否 | accept_invalid_certs | 設定是否檢查憑證中遺失的值。可能的值：accept_invalid_certs、strict |
host | 否 | 指向包含用於連線的 Socket 之目錄 | |
socket_timeout | 否 | 等待單一查詢終止的最長秒數 | |
pgbouncer | 否 | false | 設定 Engine 以 啟用 PgBouncer 相容模式 |
statement_cache_size | 否 | 100 | 自 2.1.0 起：指定每個連線快取的 預備語句 (prepared statements) 數量 |
application_name | 否 | 自 3.3.0 起：指定 application_name 設定參數的值 | |
channel_binding | 否 | prefer | 自 4.8.0 起：指定 channel_binding 設定參數的值 |
options | 否 | 自 3.8.0 起：指定在連線開始時傳送給伺服器的命令列選項 |
舉例來說，如果您想連接到名為 myschema 的 schema，將連線池大小設定為 5，並將查詢逾時設定為 3 秒。您可以使用以下參數
postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=myschema&connection_limit=5&socket_timeout=3
設定 SSL 連線
如果您的資料庫伺服器使用 SSL，您可以在連線 URL 中加入各種參數。以下是可用參數的總覽：
sslmode=(disable|prefer|require):prefer（預設）：若可能則優先使用 TLS，接受純文字連線。disable：不使用 TLS。require：要求 TLS，若不可行則連線失敗。
sslcert=<PATH>：伺服器憑證的路徑。這是資料庫伺服器用於簽署用戶端憑證的根憑證。如果您的系統受信任憑證存放區中不存在此憑證，則需要提供此路徑。對於 Google Cloud，這很可能是server-ca.pem。憑證路徑會 相對於./prisma資料夾解析。sslidentity=<PATH>：由用戶端憑證和金鑰建立的 PKCS12 憑證資料庫路徑。這是以 PKCS12 格式儲存的 SSL 身分檔案，您將使用用戶端金鑰和用戶端憑證產生此檔案。它將這兩個檔案合併成單一檔案，並透過密碼（見下一個參數）保護它們。您可以使用openssl命令透過您的用戶端金鑰和憑證建立此檔案。openssl pkcs12 -export -out client-identity.p12 -inkey client-key.pem -in client-cert.pemsslpassword=<PASSWORD>：用於保護 PKCS12 檔案的密碼。上一步列出的openssl命令在建立 PKCS12 檔案時會要求輸入密碼，您需要在此處提供完全相同的密碼。sslaccept=(strict|accept_invalid_certs):strict：憑證中的任何遺失值都會導致錯誤。對於 Google Cloud，特別是如果資料庫沒有網域名稱，憑證可能會遺失網域/IP 位址，導致連線時發生錯誤。accept_invalid_certs（預設）：繞過此檢查。請注意此設定帶來的安全性後果。
您的資料庫連線 URL 將類似於：
postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpassword=mypassword&sslcert=rootca.cert
透過 Socket 連線
若要透過 Socket 連線至您的 PostgreSQL 資料庫，您必須將 host 欄位作為 查詢參數 (query parameter) 新增至連線 URL（而非將其設定為 URI 的 host 部分）。此參數的值必須指向包含 Socket 的目錄，例如：postgresql://USER:PASSWORD@localhost/database?host=/var/run/postgresql/
請注意，localhost 是必需的，該值本身會被忽略，可以是任何內容。
注意：您可以在此 GitHub issue 中找到更多背景資訊。
PostgreSQL 與 Prisma Schema 之間的型別對應
這兩個表格展示了 PostgreSQL 與 Prisma Schema 之間的型別對應。首先是 Prisma ORM 純量型別 (scalar types) 如何轉換為 PostgreSQL 資料庫欄位型別，接著是 PostgreSQL 資料庫欄位型別如何對應至 Prisma ORM 純量與原生型別。
或者，請參閱 Prisma Schema 參考資料，了解按 Prisma 型別整理的對應關係。
Prisma ORM 純量型別與 PostgreSQL 資料庫欄位型別之間的對應
PostgreSQL 連接器將來自 Prisma ORM 資料模型 的 純量型別 映射至資料庫欄位型別如下：
| Prisma ORM | PostgreSQL |
|---|---|
String | text |
Boolean | boolean |
Int | integer |
BigInt | bigint |
Float | double precision |
Decimal | decimal(65,30) |
DateTime | timestamp(3) |
Json | jsonb |
Bytes | bytea |
PostgreSQL 資料庫欄位型別與 Prisma ORM 純量和原生型別之間的對應
- 當 偵測 (introspecting) PostgreSQL 資料庫時，資料庫型別會根據下表映射到 Prisma ORM 型別。
- 當 建立遷移 (migration) 或 建立 Schema 原型 時，也會使用此表格（反向對應）。
| PostgreSQL (型別 | 別名) | 支援 | Prisma ORM | 原生資料庫類型屬性 | 註解 |
|---|---|---|---|---|
bigint | int8 | ✔️ | BigInt | @db.BigInt* | * BigInt 的預設對應 - Schema 中未加入型別屬性。 |
boolean | bool | ✔️ | Bool | @db.Boolean* | * Bool 的預設對應 - Schema 中未加入型別屬性。 |
timestamp with time zone | timestamptz | ✔️ | DateTime | @db.Timestamptz(x) | |
time without time zone | time | ✔️ | DateTime | @db.Time(x) | |
time with time zone | timetz | ✔️ | DateTime | @db.Timetz(x) | |
numeric(p,s) | decimal(p,s) | ✔️ | Decimal | @db.Decimal(x, y) | |
real | float, float4 | ✔️ | Float | @db.Real | |
double precision | float8 | ✔️ | Float | @db.DoublePrecision* | * Float 的預設對應 - Schema 中未加入型別屬性。 |
smallint | int2 | ✔️ | Int | @db.SmallInt | |
integer | int, int4 | ✔️ | Int | @db.Int* | * Int 的預設對應 - Schema 中未加入型別屬性。 |
smallserial | serial2 | ✔️ | Int | @db.SmallInt @default(autoincrement()) | |
serial | serial4 | ✔️ | Int | @db.Int @default(autoincrement()) | |
bigserial | serial8 | ✔️ | Int | @db.BigInt @default(autoincrement() | |
character(n) | char(n) | ✔️ | String | @db.Char(x) | |
character varying(n) | varchar(n) | ✔️ | String | @db.VarChar(x) | |
money | ✔️ | Decimal | @db.Money | |
text | ✔️ | String | @db.Text* | * String 的預設對應 - Schema 中未加入型別屬性。 |
timestamp | ✔️ | DateTime | @db.TimeStamp* | * DateTime 的預設對應 - Schema 中未加入型別屬性。 |
date | ✔️ | DateTime | @db.Date | |
enum | ✔️ | Enum | 不適用 | |
inet | ✔️ | String | @db.Inet | |
bit(n) | ✔️ | String | @Bit(x) | |
bit varying(n) | ✔️ | String | @VarBit | |
oid | ✔️ | Int | @db.Oid | |
uuid | ✔️ | String | @db.Uuid | |
json | ✔️ | Json | @db.Json | |
jsonb | ✔️ | Json | @db.JsonB* | * Json 的預設對應 - Schema 中未加入型別屬性。 |
bytea | ✔️ | Bytes | @db.ByteA* | * Bytes 的預設對應 - Schema 中未加入型別屬性。 |
xml | ✔️ | String | @db.Xml | |
| 陣列型別 (Array types) | ✔️ | [] | ||
citext | ✔️* | String | @db.Citext | * 僅在 啟用 Citext 擴充功能 時可用。 |
interval | 尚未支援 | Unsupported | ||
cidr | 尚未支援 | Unsupported | ||
macaddr | 尚未支援 | Unsupported | ||
tsvector | 尚未支援 | Unsupported | ||
tsquery | 尚未支援 | Unsupported | ||
int4range | 尚未支援 | Unsupported | ||
int8range | 尚未支援 | Unsupported | ||
numrange | 尚未支援 | Unsupported | ||
tsrange | 尚未支援 | Unsupported | ||
tstzrange | 尚未支援 | Unsupported | ||
daterange | 尚未支援 | Unsupported | ||
point | 尚未支援 | Unsupported | ||
line | 尚未支援 | Unsupported | ||
lseg | 尚未支援 | Unsupported | ||
box | 尚未支援 | Unsupported | ||
path | 尚未支援 | Unsupported | ||
polygon (多邊形) | 尚未支援 | Unsupported | ||
circle | 尚未支援 | Unsupported | ||
| 複合類型 (Composite types) | 尚未支援 | 不適用 | ||
| 網域型別 (Domain types) | 尚未支援 | 不適用 |
內省 (Introspection) 會將尚未支援的原生資料庫類型添加為 Unsupported 欄位
model Device {
id Int @id @default(autoincrement())
name String
data Unsupported("circle")
}
預備語句快取 (Prepared statement caching)
預備語句 (Prepared statement) 是一種可用於最佳化效能的功能。預備語句只需解析、編譯並最佳化一次，之後即可直接執行多次，無需再次解析查詢，從而減少開銷。
透過快取預備語句，Prisma Client 的 查詢引擎 (query engine) 不會重複編譯相同的查詢，這減少了資料庫 CPU 使用率與查詢延遲。
例如，以下是 Prisma Client 發出的兩個不同查詢所產生的 SQL：
SELECT * FROM user WHERE name = "John";
SELECT * FROM user WHERE name = "Brenda";
參數化之後的這兩個查詢會是相同的，第二個查詢可以跳過預備步驟，節省資料庫 CPU 並減少一次往返 (roundtrip) 的開銷。參數化後的查詢：
SELECT * FROM user WHERE name = $1
Prisma Client 維護的每個資料庫連線都有一個獨立的快取，用於儲存預備語句。此快取的大小可以透過連線字串中的 statement_cache_size 參數進行調整。預設情況下，Prisma Client 每個連線會快取 100 個語句。
由於 pgBouncer 的特性，如果 pgbouncer 參數設定為 true，則該連線的預備語句快取會自動停用。