跳到主要内容

配置 Prisma Client 与 PgBouncer

像 PgBouncer 这样的外部连接池器维护一个到数据库的连接池，并通过位于 Prisma Client 和数据库之间来代理传入的客户端连接。这减少了数据库在任何给定时间必须处理的进程数量。

通常，这是透明工作的，但一些连接池器只支持有限的功能集。一个常见的外部连接池器不支持的功能是 Prisma ORM 使用的命名预处理语句。对于这些情况，可以配置 Prisma ORM 以不同的方式运行。

信息

正在寻找一个简单、无需基础设施的解决方案？试试 Prisma Accelerate！它几乎不需要设置，并且与 Prisma ORM 支持的所有数据库无缝协作。

准备好开始了吗？点击这里开始使用 Prisma Accelerate：.

PgBouncer​

将 PgBouncer 设置为事务模式​

为了使 Prisma Client 可靠工作，PgBouncer 必须运行在 事务模式 (Transaction mode)下。

事务模式为每个事务提供一个连接——这是 Prisma Client 与 PgBouncer 配合工作的要求。

对于低于 1.21.0 的 PgBouncer 版本，添加 pgbouncer=true​

警告

如果您使用的是 PgBouncer 1.21.0 或更高版本，我们建议不要在数据库连接字符串中设置 pgbouncer=true。

要将 Prisma Client 与 PgBouncer 一起使用，请在 PostgreSQL 连接 URL 中添加 ?pgbouncer=true 标志

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true
信息

为 PgBouncer 池指定的 PORT 有时与默认的 5432 端口不同。请查看您的数据库提供商文档以获取正确的端口号。

在 PgBouncer 中配置 max_prepared_statements 大于零​

Prisma 使用预处理语句，将 max_prepared_statements 设置为大于 0 的值可使 PgBouncer 使用这些预处理语句。

信息

为 PgBouncer 池指定的 PORT 有时与默认的 5432 端口不同。请查看您的数据库提供商文档以获取正确的端口号。

Prisma Migrate 和 PgBouncer 变通方案​

Prisma Migrate 使用数据库事务来检查数据库和迁移表的当前状态。然而，Schema Engine 设计为使用单一连接到数据库，并且不支持与 PgBouncer 的连接池。如果您尝试在任何使用 PgBouncer 进行连接池的环境中运行 Prisma Migrate 命令，您可能会看到以下错误：

Error: undefined: Database error
Error querying the database: db error: ERROR: prepared statement "s0" already exists

为了解决这个问题，您必须直接连接到数据库，而不是通过 PgBouncer。为此，您可以在 datasource 块中使用 directUrl 字段。

例如，考虑以下 datasource 块：

datasource db {
  provider  = "postgresql"
  url       = "postgres://USER:PASSWORD@HOST:PORT/DATABASE?pgbouncer=true"
  directUrl = "postgres://USER:PASSWORD@HOST:PORT/DATABASE"
}

上面的块使用 PgBouncer 连接字符串作为主要 URL（使用 url 字段），允许 Prisma Client 利用 PgBouncer 连接池器。

它还提供了一个直接连接到数据库的连接字符串（不经过 PgBouncer），使用 directUrl 字段。当调用需要单一连接到数据库的命令（如 prisma migrate dev 或 prisma db push）时，将使用此连接字符串。

Prisma Migrate 和 PgBouncer 变通方案​

有时，直接连接到 Postgres 数据库的方式会因托管数据库的提供商而略有不同。

以下是关于如何与本文档未涵盖设置步骤的提供商建立这些连接的信息链接：

Supabase Supavisor​

Supabase 的 Supavisor 的行为类似于 PgBouncer。您可以在通过 Supabase 数据库设置 获得的连接池连接字符串中添加 ?pgbouncer=true。

其他外部连接池器​

尽管 Prisma ORM 没有明确支持其他连接池器，但如果限制与 PgBouncer 相似，您通常也可以在连接字符串中使用 pgbouncer=true，使 Prisma ORM 进入一个可以与它们协作的模式。