跳至主要内容

使用 PgBouncer 配置 Prisma Client

像 PgBouncer 这样的外部连接池器会持有到数据库的连接池，并在 Prisma Client 和数据库之间充当代理，处理传入的客户端连接。这减少了数据库在任何给定时间需要处理的进程数量。

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

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

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

### Configure `max_prepared_statements` in PgBouncer to be greater than zero

Prisma uses prepared statements, and setting [`max_prepared_statements`](https://www.pgbouncer.org/config.html) to a value greater than `0` enables PgBouncer to use those prepared statements.

:::info
`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 and PgBouncer workaround

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:

```bash
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 连接池器。

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

不同数据库提供商的 PgBouncer​

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

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

Supabase Supavisor​

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

其他外部连接池器​

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