跳到主要内容

配置带有 PgBouncer 的 Prisma Client

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

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

信息

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

准备好开始了吗？点击即可开始使用 Prisma Accelerate.

PgBouncer​

将 PgBouncer 设置为事务模式​

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

事务模式为每个事务提供一个连接——这是 Prisma Client 与 PgBouncer 一起工作的必要条件。

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

警告

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

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

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。要实现这一点，您可以使用 directUrl 字段在您的 datasource 块中。

例如，考虑以下 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 连接池管理器。

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

PgBouncer 与不同的数据库提供商​

有时，根据托管数据库的提供商，直接连接到 Postgres 数据库的方式会存在细微差异。

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

Supabase Supavisor​

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

其他外部连接池管理器​

虽然 Prisma ORM 没有对其他连接池管理器的显式支持，但如果限制与 PgBouncer 的限制类似，您通常也可以在连接字符串中使用 pgbouncer=true，使 Prisma ORM 进入可以与它们一起工作的模式。