Skip to main content

使用 PgBouncer 配置 Prisma 客户端

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

¥An external connection pooler like PgBouncer holds a connection pool to the database, and proxies incoming client connections by sitting between Prisma Client and the database. This reduces the number of processes a database has to handle at any given time.

通常，这是透明地工作的，但某些连接池仅支持一组有限的功能。外部连接池不支持的一项常见功能是 Prisma ORM 使用的命名准备语句。对于这些情况，Prisma ORM 可以配置为不同的行为。

¥Usually, this works transparently, but some connection poolers only support a limited set of functionality. One common feature that external connection poolers do not support are named prepared statements, which Prisma ORM uses. For these cases, Prisma ORM can be configured to behave differently.

信息

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

¥Looking for an easy, infrastructure-free solution? Try Prisma Accelerate! It requires little to no setup and works seamlessly with all databases supported by Prisma ORM.

准备开始了吗？单击 开始使用 Prisma Accelerate。

¥Ready to begin? Get started with Prisma Accelerate by clicking .

PgBouncer​

将 PgBouncer 设置为事务模式​

¥Set PgBouncer to transaction mode

为了使 Prisma 客户端可靠工作，PgBouncer 必须在 事务方式 中运行。

¥For Prisma Client to work reliably, PgBouncer must run in Transaction mode.

事务模式为每笔事务提供一个连接 - 这是 Prisma 客户端与 PgBouncer 配合使用的要求。

¥Transaction mode offers a connection for every transaction – a requirement for the Prisma Client to work with PgBouncer.

为 1.21.0 以下的 PgBouncer 版本添加 pgbouncer=true​

¥Add pgbouncer=true for PgBouncer versions below 1.21.0

警告

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

¥We recommend not setting pgbouncer=true in the database connection string if you're using PgBouncer 1.21.0 or later.

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

¥To use Prisma Client with PgBouncer, add the ?pgbouncer=true flag to the PostgreSQL connection URL:

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

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

¥PORT specified for PgBouncer pooling is sometimes different from the default 5432 port. Check your database provider docs for the correct port number.

将 PgBouncer 中的 max_prepared_statements 配置为大于零​

¥Configure max_prepared_statements in PgBouncer to be greater than zero

Prisma 使用准备好的语句，将 max_prepared_statements 设置为大于 0 的值可使 PgBouncer 使用这些准备好的语句。

¥Prisma uses prepared statements, and setting max_prepared_statements to a value greater than 0 enables PgBouncer to use those prepared statements.

信息

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

¥PORT specified for PgBouncer pooling is sometimes different from the default 5432 port. Check your database provider docs for the correct port number.

Prisma Migrate 和 PgBouncer 解决方法​

¥Prisma Migrate and PgBouncer workaround

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

¥Prisma Migrate uses database transactions to check out the current state of the database and the migrations table. However, the Schema Engine is designed to use a single connection to the database, and does not support connection pooling with PgBouncer. If you attempt to run Prisma Migrate commands in any environment that uses PgBouncer for connection pooling, you might see the following error:

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

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

¥To work around this issue, you must connect directly to the database rather than going through PgBouncer. To achieve this, you can use the directUrl field in your datasource block.

例如，考虑以下 datasource 块：

¥For example, consider the following datasource block:

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

上面的块使用 PgBouncer 连接字符串作为使用 url 的主 URL，允许 Prisma 客户端利用 PgBouncer 连接池。

¥The block above uses a PgBouncer connection string as the primary URL using url, allowing Prisma Client to take advantage of the PgBouncer connection pooler.

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

¥It also provides a connection string directly to the database, without PgBouncer, using the directUrl field. This connection string will be used when commands that require a single connection to the database, such as prisma migrate dev or prisma db push, are invoked.

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

¥PgBouncer with different database providers

有时，如何直接连接到 Postgres 数据库会存在细微差别，具体取决于托管数据库的提供商。

¥There are sometimes minor differences in how to connect directly to a Postgres database that depend on the provider hosting the database.

以下是有关如何与提供商建立这些连接的信息链接，这些提供商的设置步骤未在我们的文档中介绍：

¥Below are links to information on how to set up these connections with providers who have setup steps not covered here in our documentation:

Supabase 监督员​

¥Supabase Supavisor

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

¥Supabase's Supavisor behaves similarly to PgBouncer. You can add ?pgbouncer=true to your connection pooled connection string available via your Supabase database settings.

其他外部连接池​

¥Other external connection poolers

尽管 Prisma ORM 没有明确支持其他连接池，但如果限制与 PgBouncer 的限制类似，你通常也可以在连接字符串中使用 pgbouncer=true，将 Prisma ORM 置于也可以使用它们的模式。

¥Although Prisma ORM does not have explicit support for other connection poolers, if the limitations are similar to the ones of PgBouncer you can usually also use pgbouncer=true in your connection string to put Prisma ORM in a mode that works with them as well.