跳到主要内容

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. 安装依赖项​

接下来，安装 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 所需组件的概览

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

通过 sockets 连接​

要通过 sockets 连接到您的 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 ORMPostgreSQL
Stringtext
Booleanboolean
Intinteger
BigIntbigint
Floatdouble precision
Decimaldecimal(65,30)
DateTimetimestamp(3)
Jsonjsonb
Bytesbytea

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

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字段

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，则该连接的预备语句缓存将自动禁用。