PostgreSQL

PostgreSQL 数据源连接器将 Prisma ORM 连接到 PostgreSQL 数据库服务器。

默认情况下，PostgreSQL 连接器包含一个负责连接到数据库的数据库驱动程序。您可以使用 驱动程序适配器（预览版），使用 Prisma Client 中的 JavaScript 数据库驱动程序连接到您的数据库。

示例

要连接到 PostgreSQL 数据库服务器，您需要在您的 Prisma schema 中配置一个 datasource 代码块

schema.prisma

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

传递给 datasource 代码块的字段是

• provider: 指定 postgresql 数据源连接器。
• url: 指定 PostgreSQL 数据库服务器的连接 URL。 在这种情况下，使用环境变量来提供连接 URL。

使用 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'
})

连接详细信息

连接 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	数据库用户的名称，例如 janedoe
密码	PASSWORD	数据库用户的密码
数据库	DATABASE	您要使用的数据库的名称，例如 mydb

信息

您必须百分比编码特殊字符。

参数

连接 URL 也可以采用参数。 以下是上面相同的示例，其中三个 _arguments_ 的占位符值使用大写字母

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 文件夹解析
sslrootcert	否		根证书的路径。证书路径会相对于 ./prisma 文件夹解析
sslidentity	否		PKCS12 证书的路径
sslpassword	否		用于保护 PKCS12 文件的密码
sslaccept	否	accept_invalid_certs	配置是否检查证书中缺失的值。可能的值：accept_invalid_certs、strict
host	否		指向包含用于连接的套接字的目录
socket_timeout	否		等待单个查询终止的最长秒数
pgbouncer	否	false	配置引擎以启用 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 的模式，将连接池大小设置为 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 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（默认）：绕过此检查。请注意此设置的安全后果。

您的数据库连接 URL 将类似于这样

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

通过套接字连接

要通过套接字连接到 PostgreSQL 数据库，必须将 host 字段作为*查询参数*添加到连接 URL（而不是将其设置为 URI 的 host 部分）。然后，此参数的值必须指向包含套接字的目录，例如：postgresql://USER:PASSWORD@localhost/database?host=/var/run/postgresql/

请注意，localhost 是必需的，该值本身将被忽略，可以是任何值。

注意：您可以在此 GitHub 问题中找到更多上下文。

PostgreSQL 和 Prisma 模式之间的类型映射

这两个表显示了 PostgreSQL 和 Prisma 模式之间的类型映射。首先是Prisma ORM 标量类型如何转换为 PostgreSQL 数据库列类型，然后是PostgreSQL 数据库列类型如何与 Prisma ORM 标量和本机类型相关。

或者，请参阅Prisma 模式参考，以了解按 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 标量和本机类型之间的映射

• 当内省 PostgreSQL 数据库时，数据库类型将根据下表映射到 Prisma ORM 类型。
• 当创建迁移或原型化模式时，也会使用该表 - 在另一个方向上。

PostgreSQL（类型 | 别名）	支持	Prisma ORM	本机数据库类型属性	备注
bigint | int8	✔️	BigInt	@db.BigInt*	*BigInt 的默认映射 - 没有类型属性添加到模式。
boolean | bool	✔️	Bool	@db.Boolean*	*Bool 的默认映射 - 没有类型属性添加到模式。
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 的默认映射 - 没有类型属性添加到模式。
smallint | int2	✔️	Int	@db.SmallInt
integer | int, int4	✔️	Int	@db.Int*	*Int 的默认映射 - 没有类型属性添加到模式。
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 的默认映射 - 没有类型属性添加到模式。
timestamp	✔️	DateTime	@db.TimeStamp*	*DateTime 的默认映射 - 没有类型属性添加到模式。
date	✔️	DateTime	@db.Date
enum	✔️	Enum	N/A
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 的默认映射 - 没有类型属性添加到模式。
bytea	✔️	Bytes	@db.ByteA*	*Bytes 的默认映射 - 没有类型属性添加到模式。
xml	✔️	String	@db.Xml
数组类型	✔️	[]
citext	✔️*	String	@db.Citext	* 仅在启用 Citext 扩展时可用。
interval	尚未	不支持
cidr	尚未	不支持
macaddr	尚未	不支持
tsvector	尚未	不支持
tsquery	尚未	不支持
int4range	尚未	不支持
int8range	尚未	不支持
numrange	尚未	不支持
tsrange	尚未	不支持
tstzrange	尚未	不支持
daterange	尚未	不支持
point	尚未	不支持
line	尚未	不支持
lseg	尚未	不支持
box	尚未	不支持
path	尚未	不支持
polygon	尚未	不支持
circle	尚未	不支持
复合类型	尚未	n/a
域类型	尚未	n/a

内省添加了 尚未支持的本机数据库类型，作为 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，则会自动禁用该连接的预处理语句缓存。