Configure Prisma Client with PgBouncer

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. PgBouncer passes on a limited number of connections to the database and queues additional connections for delivery when space becomes available.

Add pgbouncer to the connection URL

To use Prisma Client with PgBouncer from a serverless function, add the ?pgbouncer=true flag to the PostgreSQL connection URL:

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

Note: PORT specified for PgBouncer pooling sometimes different from the default 5432 port. Check database provider docs for the exact port number, otherwise adding ?pgbouncer=true won't work.

Set PgBouncer to transaction mode

Additionally, for Prisma Client to work reliably, PgBouncer must run in Transaction mode.

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

  • Prisma cleans up already present prepared statements in the connection by running DEALLOCATE ALL before preparing and executing Prisma Client queries.
  • Prisma opens a transaction for every query case – even when just reading data, allowing Prisma to use prepared statements.

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

To work around this issue, you must connect directly to the database rather than going through PgBouncer. How to achieve this depends on your setup or provider:

Edit this page on GitHub