PostgreSQL
PostgreSQL 数据源连接器将 Prisma ORM 连接到 PostgreSQL 数据库服务器。
默认情况下，PostgreSQL 连接器包含一个负责连接到数据库的数据库驱动。你可以使用驱动适配器（预览）通过 Prisma Client 使用 JavaScript 数据库驱动连接到数据库。
昨天就需要 Postgres 实例？
通过 Prisma Postgres，你只需点击三下即可在裸机上运行数据库。连接池、查询缓存和自动备份均包含在内。立即开始。
想更快地开始使用 Prisma Postgres 吗？只需在终端中运行 npx prisma init --db。🚀
示例
要连接到 PostgreSQL 数据库服务器，你需要在 Prisma schema 中配置一个 datasource 块
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
传递给 datasource 块的字段有：
使用 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 块上启用其功能标志
generator client {
provider = "prisma-client-js"
previewFeatures = ["driverAdapters"]
}
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}
将功能标志添加到 schema 后，重新生成 Prisma Client
npx prisma generate
2. 安装依赖
接下来，安装 Prisma ORM 的 pg 驱动适配器
npm install @prisma/adapter-pg
3. 使用驱动适配器实例化 Prisma Client
最后，当你实例化 Prisma Client 时，你需要将 Prisma ORM 驱动适配器的一个实例传递给 PrismaClient 构造函数
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from '@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 和路径
以下是使用大写占位符值的基础 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 folder解析 | |
sslrootcert | 否 | 根证书路径。证书路径相对于./prisma folder解析 | |
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
配置 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.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
通过 sockets 连接
要通过 sockets 连接到 PostgreSQL 数据库，你必须在连接 URL 中添加一个 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 |
|---|---|
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 | 不适用 | |
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字段
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，该连接的预处理语句缓存会自动禁用。