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 数据库服务器的连接 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. 启用 `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 所需组件的概述

Structure of the PostgreSQL connection URL

基本 URL 和路径

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

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

以下组件构成数据库的 基本 URL，它们始终是必需的

名称	占位符	描述
主机	`HOST`	你的数据库服务器的 IP 地址/域名，例如 `localhost`
端口	`PORT`	你的数据库服务器正在运行的端口，例如 `5432`
用户	`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`	连接池的最大大小
`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`	配置 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，你可以向连接 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

通过套接字连接

要通过套接字连接到你的 PostgreSQL 数据库，你必须添加 host 字段作为连接 URL 的 查询参数 （而不是将其设置为 URI 的 host 部分）。然后，此参数的值必须指向包含套接字的目录，例如：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 中没有添加类型属性。
`timestamp`	✔️	`DateTime`	`@db.TimeStamp`*	*`DateTime` 的默认映射 - schema 中没有添加类型属性。
`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` 的默认映射 - schema 中没有添加类型属性。
`bytea`	✔️	`Bytes`	`@db.ByteA`*	*`Bytes` 的默认映射 - schema 中没有添加类型属性。
`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`	暂不支持	`不支持`
复合类型	暂不支持	不适用
域类型	暂不支持	不适用

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

示例​

使用 node-postgres 驱动程序​

1. 启用 driverAdapters 预览功能标志​

2. 安装依赖项​

3. 使用驱动程序适配器实例化 Prisma Client​

注释​

指定 PostgreSQL schema​

连接详情​

连接 URL​

基本 URL 和路径​

参数​

配置 SSL 连接​

通过套接字连接​

PostgreSQL 和 Prisma schema 之间的类型映射​

Prisma ORM 标量类型和 PostgreSQL 数据库列类型之间的映射​

PostgreSQL 数据库列类型与 Prisma ORM 标量和原生类型之间的映射​

预处理语句缓存​

示例