PostgreSQL

PostgreSQL 資料來源連接器將 Prisma ORM 連接到 PostgreSQL 資料庫伺服器。

預設情況下，PostgreSQL 連接器包含一個資料庫驅動程式，負責連線到您的資料庫。您可以使用驅動程式轉接器 (預覽) ，透過 Prisma Client 中的 JavaScript 資料庫驅動程式連線到您的資料庫。

資訊

昨天就需要 Postgres 實例？

透過 Prisma Postgres，您只需點擊三下即可在裸機上運行資料庫。所有功能皆包含連線池、即時事件和自動備份。立即開始使用。

想要更快速地開始使用 Prisma Postgres 嗎？只需在您的終端機中執行 npx prisma init --db。🚀

範例

若要連線到 PostgreSQL 資料庫伺服器，您需要在您的 Prisma schema 中設定 datasource 區塊

schema.prisma

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

傳遞到 datasource 區塊的欄位為

• provider：指定 postgresql 資料來源連接器。
• url：指定 PostgreSQL 資料庫伺服器的連線網址。在本例中，使用環境變數來提供連線網址。

使用 node-postgres 驅動程式

自 v5.4.0 起，您可以搭配 JavaScript 生態系統中的資料庫驅動程式使用 Prisma ORM (而非使用 Prisma ORM 的內建驅動程式)。您可以使用驅動程式轉接器來執行此操作。

對於 PostgreSQL，node-postgres (pg) 是 JavaScript 生態系統中最受歡迎的驅動程式之一。它可以與任何透過 TCP 存取的 PostgreSQL 資料庫一起使用。

本節說明如何將其與 Prisma ORM 和 @prisma/adapter-pg 驅動程式轉接器一起使用。

1. 啟用 driverAdapters 預覽功能標誌

由於驅動程式轉接器目前處於預覽階段，因此您需要在 Prisma schema 中的 datasource 區塊上啟用其功能標誌

// schema.prisma
generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["driverAdapters"]
}

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

將功能標誌新增至您的 schema 後，重新產生 Prisma Client

npx prisma generate

2. 安裝相依性

接下來，安裝 pg 套件和 Prisma ORM 的驅動程式轉接器

npm install pg
npm install @prisma/adapter-pg

3. 使用驅動程式轉接器實例化 Prisma Client

最後，當您實例化 Prisma Client 時，您需要將 Prisma ORM 驅動程式轉接器的實例傳遞給 PrismaClient 建構函式

import { Pool } from 'pg'
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '@prisma/client'

const connectionString = `${process.env.DATABASE_URL}`

const pool = new Pool({ connectionString })
const adapter = new PrismaPg(pool)
const prisma = new PrismaClient({ adapter })

請注意，此程式碼需要將 DATABASE_URL 環境變數設定為您的 PostgreSQL 連線字串。您可以在下方了解更多關於連線字串的資訊。

注意事項

指定 PostgreSQL schema

您可以透過在實例化 PrismaPg 時傳遞 schema 選項來指定 PostgreSQL schema

const adapter = new PrismaPg(pool, {
  schema: 'myPostgresSchema'
})

連線詳細資訊

連線網址

Prisma ORM 遵循 PostgreSQL 官方指南 指定的連線網址格式，但不支援所有引數，並且包含額外的引數，例如 schema。以下是 PostgreSQL 連線網址所需元件的概觀

基本網址和路徑

以下是使用大寫佔位符值的基本網址和路徑結構範例

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

以下元件構成您的資料庫基本網址，它們是始終必需的

名稱	佔位符	描述
主機	HOST	資料庫伺服器的 IP 位址/網域名稱，例如 localhost
連接埠	PORT	資料庫伺服器運行的連接埠，例如 5432
使用者	USER	您的資料庫使用者名稱，例如 janedoe
密碼	PASSWORD	您的資料庫使用者密碼
資料庫	DATABASE	您要使用的 資料庫 名稱，例如 mydb

資訊

您必須百分比編碼特殊字元。

引數

連線網址也可以接受引數。以下是與上方範例相同的範例，其中三個引數使用大寫佔位符值

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?KEY1=VALUE&KEY2=VALUE&KEY3=VALUE

可以使用以下引數

引數名稱	必要	預設值	描述
schema	是	public	您要使用的 schema 名稱，例如 myschema
connection_limit	否	num_cpus * 2 + 1	連線池的最大大小
connect_timeout	否	5	等待開啟新連線的最大秒數，0 表示沒有逾時
pool_timeout	否	10	從池中等待新連線的最大秒數，0 表示沒有逾時
sslmode	否	prefer	設定是否使用 TLS。可能的值：prefer、disable、require
sslcert	否		伺服器憑證的路徑。憑證路徑是相對於 ./prisma folder 解析
sslrootcert	否		根憑證的路徑。憑證路徑是相對於 ./prisma folder 解析
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 起：指定每個連線快取的預先處理語句數量
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，您可以將各種參數新增至連線網址。以下是可能參數的概觀

• sslmode=(disable|prefer|require):
  • prefer (預設)：盡可能偏好 TLS，接受純文字連線。
  • disable：不使用 TLS。
  • require：需要 TLS，否則會失敗。
• sslcert=<PATH>：伺服器憑證的路徑。這是資料庫伺服器用來簽署用戶端憑證的根憑證。如果憑證不存在於您系統的受信任憑證儲存區中，則需要提供此憑證。對於 Google Cloud，這很可能是 server-ca.pem。憑證路徑是相對於 ./prisma folder 解析
• sslidentity=<PATH>：從用戶端憑證和金鑰建立的 PKCS12 憑證資料庫路徑。這是 PKCS12 格式的 SSL 識別檔案，您將使用用戶端金鑰和用戶端憑證產生。它將這兩個檔案合併為單一檔案，並透過密碼保護 (請參閱下一個參數)。您可以使用用戶端金鑰和用戶端憑證，透過使用以下命令 (使用 openssl) 來建立此檔案

  openssl pkcs12 -export -out client-identity.p12 -inkey client-key.pem -in client-cert.pem
• sslpassword=<PASSWORD>：用於保護 PKCS12 檔案的密碼。先前步驟中列出的 openssl 命令將在建立 PKCS12 檔案時要求輸入密碼，您需要在此處提供完全相同的密碼。
• sslaccept=(strict|accept_invalid_certs):
  • strict：憑證中任何缺少的值都會導致錯誤。對於 Google Cloud，尤其是當資料庫沒有網域名稱時，憑證可能會遺失網域/IP 位址，從而在連線時造成錯誤。
  • accept_invalid_certs (預設)：略過此檢查。請注意此設定的安全性後果。

您的資料庫連線網址將如下所示

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslidentity=client-identity.p12&sslpassword=mypassword&sslcert=rootca.cert

透過 Socket 連線

若要透過 Socket 連線到您的 PostgreSQL 資料庫，您必須將 host 欄位作為查詢參數新增至連線網址 (而不是將其設定為 URI 的 host 部分)。然後，此參數的值必須指向包含 socket 的目錄，例如：postgresql://USER:PASSWORD@localhost/database?host=/var/run/postgresql/

請注意，localhost 是必要的，值本身會被忽略且可以是任何值。

注意：您可以在此 GitHub issue 中找到更多背景資訊。

PostgreSQL 與 Prisma schema 之間的類型映射

以下兩個表格顯示 PostgreSQL 和 Prisma schema 之間的類型映射。首先，Prisma ORM 純量類型如何轉換為 PostgreSQL 資料庫欄位類型，然後，PostgreSQL 資料庫欄位類型如何與 Prisma ORM 純量和原生類型相關。

或者，請參閱 Prisma schema 參考，以取得依 Prisma 類型組織的類型映射。

Prisma ORM 純量類型與 PostgreSQL 資料庫欄位類型之間的映射

PostgreSQL 連接器將 Prisma ORM 資料模型中的 純量類型 映射到資料庫欄位類型，如下所示

Prisma ORM	PostgreSQL
字串	text
布林值	boolean
整數	integer
BigInt	bigint
浮點數	double precision
小數	decimal(65,30)
日期時間	timestamp(3)
Json	jsonb
位元組	bytea

PostgreSQL 資料庫欄位類型與 Prisma ORM 純量和原生類型之間的映射

• 當內省 PostgreSQL 資料庫時，資料庫類型會根據下表映射到 Prisma ORM 類型。
• 當建立遷移或原型化您的 schema 時，也會使用此表格 - 反之亦然。

PostgreSQL (類型 | 別名)	支援	Prisma ORM	原生資料庫類型屬性	注意事項
bigint | int8	✔️	BigInt	@db.BigInt*	*BigInt 的預設映射 - 沒有新增至 schema 的類型屬性。
boolean | bool	✔️	Bool	@db.Boolean*	*Bool 的預設映射 - 沒有新增至 schema 的類型屬性。
timestamp with time zone | timestamptz	✔️	日期時間	@db.Timestamptz(x)
time without time zone | time	✔️	日期時間	@db.Time(x)
time with time zone | timetz	✔️	日期時間	@db.Timetz(x)
numeric(p,s) | decimal(p,s)	✔️	小數	@db.Decimal(x, y)
real | float, float4	✔️	浮點數	@db.Real
double precision | float8	✔️	浮點數	@db.DoublePrecision*	*Float 的預設映射 - 沒有新增至 schema 的類型屬性。
smallint | int2	✔️	整數	@db.SmallInt
integer | int, int4	✔️	整數	@db.Int*	*Int 的預設映射 - 沒有新增至 schema 的類型屬性。
smallserial | serial2	✔️	整數	@db.SmallInt @default(autoincrement())
serial | serial4	✔️	整數	@db.Int @default(autoincrement())
bigserial | serial8	✔️	整數	@db.BigInt @default(autoincrement()
character(n) | char(n)	✔️	字串	@db.Char(x)
character varying(n) | varchar(n)	✔️	字串	@db.VarChar(x)
money	✔️	小數	@db.Money
text	✔️	字串	@db.Text*	*String 的預設映射 - 沒有新增至 schema 的類型屬性。
timestamp	✔️	日期時間	@db.TimeStamp*	*DateTime 的預設映射 - 沒有新增至 schema 的類型屬性。
date	✔️	日期時間	@db.Date
enum	✔️	Enum	不適用
inet	✔️	字串	@db.Inet
bit(n)	✔️	字串	@Bit(x)
bit varying(n)	✔️	字串	@VarBit
oid	✔️	整數	@db.Oid
uuid	✔️	字串	@db.Uuid
json	✔️	Json	@db.Json
jsonb	✔️	Json	@db.JsonB*	*Json 的預設映射 - 沒有新增至 schema 的類型屬性。
bytea	✔️	位元組	@db.ByteA*	*Bytes 的預設映射 - 沒有新增至 schema 的類型屬性。
xml	✔️	字串	@db.Xml
陣列類型	✔️	[]
citext	✔️*	字串	@db.Citext	* 僅在啟用 Citext 擴充功能時可用。
interval	尚未	不支援
cidr	尚未	不支援
macaddr	尚未	不支援
tsvector	尚未	不支援
tsquery	尚未	不支援
int4range	尚未	不支援
int8range	尚未	不支援
numrange	尚未	不支援
tsrange	尚未	不支援
tstzrange	尚未	不支援
daterange	尚未	不支援
point	尚未	不支援
line	尚未	不支援
lseg	尚未	不支援
box	尚未	不支援
path	尚未	不支援
polygon	尚未	不支援
circle	尚未	不支援
複合類型	尚未	不適用
網域類型	尚未	不適用

內省新增了尚不支援的原生資料庫類型作為Unsupported 欄位

schema.prisma

model Device {
  id   Int                   @id @default(autoincrement())
  name String
  data Unsupported("circle")
}

預先處理語句快取

預先處理語句 是一項可用於最佳化效能的功能。預先處理語句僅會被解析、編譯和最佳化一次，然後可以直接多次執行，而無需再次解析查詢的額外負擔。

透過快取預先處理語句，Prisma Client 的查詢引擎不會重複編譯相同的查詢，從而減少資料庫 CPU 使用率和查詢延遲。

例如，以下是 Prisma Client 產生的兩個不同查詢的產生 SQL

SELECT * FROM user WHERE name = "John";
SELECT * FROM user WHERE name = "Brenda";

參數化後的兩個查詢將會相同，第二個查詢可以跳過準備步驟，從而節省資料庫 CPU 和額外一次往返資料庫的時間。參數化後的查詢

SELECT * FROM user WHERE name = $1

Prisma Client 維護的每個資料庫連線都有一個單獨的快取，用於儲存預先處理語句。可以使用連線字串中的 statement_cache_size 參數調整此快取的大小。預設情況下，Prisma Client 每個連線快取 100 個語句。

由於 pgBouncer 的性質，如果 pgbouncer 參數設定為 true，則會自動停用該連線的預先處理語句快取。