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"
}

datasource 块指定了 postgresql 数据源连接器。

在 Prisma ORM 7 中，数据库连接 URL 在 prisma.config.ts 中配置。

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 的内置驱动程序）一起使用。您可以通过使用 驱动程序适配器 来实现。

对于 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 所需组件的概述

Base URL 和路径

以下是使用大写占位符值的Base URL和路径结构的示例

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	连接池的最大大小（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	配置引擎以启用 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

Prisma ORM v7 连接池

在 Prisma ORM v7 中，驱动程序适配器是关系型数据库的默认选项。连接池由您提供的 Node.js 驱动程序（如 pg）处理，而不是由 Prisma 的连接 URL 参数处理。有关 v7 默认值和配置，请参阅连接池指南。

配置 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.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

通过 socket 连接

要通过 socket 连接到您的 PostgreSQL 数据库，您必须将 host 字段作为查询参数添加到连接 URL（而不是将其设置为 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
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 类型。
• 当创建迁移或原型化 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 中。
时间戳	✔️	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	暂不支持	不支持
cidr	暂不支持	不支持
macaddr	暂不支持	不支持
tsvector	暂不支持	不支持
tsquery	暂不支持	不支持
int4range	暂不支持	不支持
int8range	暂不支持	不支持
numrange	暂不支持	不支持
tsrange	暂不支持	不支持
tstzrange	暂不支持	不支持
daterange	暂不支持	不支持
point	暂不支持	不支持
line	暂不支持	不支持
lseg	暂不支持	不支持
box	暂不支持	不支持
path	暂不支持	不支持
polygon	暂不支持	不支持
circle	暂不支持	不支持
复合类型	暂不支持	不适用
Domain types	暂不支持	不适用

内省会添加目前不支持的原生数据库类型，作为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，则该连接的预编译语句缓存将自动禁用。