Connection pooling

PostgreSQL connection limits

Each PostgreSQL connection creates a new process in the operating system, which consumes resources. For this reason, PostgreSQL limits the number of open connections. Neon permits 100 simultaneous PostgreSQL connections by default with a max_connections=100 setting, which is the typical default for this parameter. In Neon, a small number of those connections are reserved for administrative purposes. A connection limit of 100 may not be sufficient for some applications. To increase the number of connections that Neon supports, you can enable connection pooling for the endpoint compute instance you use to connect to your database.

Connection pooling

Some applications open numerous connections, with most eventually becoming inactive. This behavior can often be attributed to database driver limitations or to running many instances of an application. With regular PostgreSQL, new connections are rejected when reaching the max_connections limit. To overcome this limitation, Neon supports connection pooling using PgBouncer.

PgBouncer is an open-source connection pooler for PostgreSQL. When an application needs to connect to a database, PgBouncer provides a connection from the pool. Connections in the pool are routed to a smaller number of actual PostgreSQL connections. When a connection is no longer required, it is returned to the pool and is available to be used again. Maintaining a pool of available connections improves performance by reducing the number of connections that need to be created and torn down to service incoming requests. Connection pooling also helps avoid rejected connections. When all connections in the pool are being used, PgBouncer queues a new request until a connection from the pool becomes available.

With connection pooling enabled, Neon can handle up to 1000 concurrent connections. Neon uses PgBouncer in transaction mode. For limitations associated with transaction mode, see Connection pooling notes and limitations. For more information about PgBouncer, refer to https://www.pgbouncer.org/.

Enable connection pooling

In Neon, connection pooling is configured for individual endpoint compute instances. It is disabled by default. You can enable connection pooling when creating or editing an endpoint.

To enable connection pooling for an existing endpoint:

1. Navigate to the Neon console.
2. On the Dashboard, select Endpoints.
3. Find the endpoint you want to enable pooling for, click the kebab menu in the Endpoints table, and select Edit.
4. Toggle Pooler enabled to the on position.
5. Click Save.

You can also enable connection pooling when creating an endpoint. See Create an endpoint.

Connection pooling notes and limitations

Neon uses PgBouncer in transaction mode, which does not support PostgreSQL features such as prepared statements or LISTEN/NOTIFY. For a complete list of limitations, refer to the "SQL feature map for pooling modes" section in the pgbouncer.org Features documentation.

Some clients and applications may require connection pooling. For example, using Prisma Client with PgBouncer from a serverless function requires connection pooling. To ensure that connection pooling is enabled for clients and applications that require it, you can add the ?pgbouncer=true flag to your Neon connection string, as shown in the following example:

postgres://casey:<password>@ep-square-sea-260584.us-east-2.aws.neon.tech:5432/neondb?pgbouncer=true"

Prisma Migrate, however, requires a direct connection to the database, and currently does not support connection pooling with PgBouncer. Attempting to run Prisma Migrate commands in any environment that enables PgBouncer for connection pooling results in the following error:

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

You may encounter this error with other applications that require a direct connection to PostgreSQL or applications that are not compatible with PgBouncer in transaction mode. In these cases, do not enable connection pooling in Neon.

For more information about using Prisma in a PgBouncer-enabled environment, refer to the Prisma documentation.

PostgreSQL features such as prepared statements and LISTEN/NOTIFY are not supported with connection pooling. For a complete list of limitations, refer to the "SQL feature map for pooling modes" section, in the pgbouncer.org Features documentation.

Need help?

Send a request to support@neon.tech, or join the Neon community forum.