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:
Note:
PORTspecified for PgBouncer pooling sometimes different from the default5432port. Check database provider docs for the exact port number, otherwise adding?pgbouncer=truewon'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 ALLbefore 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:
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:
