Skip to main content
PgBouncer
Last update:

PgBouncer

In PostgreSQL, a separate process is created to handle each client connection. The greater the number of connections, the more processes that utilize RAM. The maximum number of connections to a PostgreSQL process is defined by parameter max_connections.

To optimize resource consumption, you can use a connection pooler. Clients do not connect directly to PostgreSQL, but to a connection pooler. This supports a small number of connections between the pooler and the PostgreSQL server — the pooler creates a new connection or reuses one of the existing ones. The number of connections between the pooler and the database on each node in the cluster is determined by pool-size (pool_size parameter).

PostgreSQL cloud database clusters utilize the PgBouncer connection pooler. Available three PgBouncer pooling modes. For more information about the connection pooler, see the PgBouncer documentation.

Maximum number of connections to PostgreSQL process (max_connections)⁠

The PostgreSQL DBMS parameter max_connections defines the maximum number of simultaneous connections to the PostgreSQL process. The default value is set to 100 connections.

You can change the value of the parameter in the DBMS settings in the control panel to the value of the maximum number of connections under load. Keep in mind that each connection consumes RAM resources.

Changing the max_connections value causes the PostgreSQL cluster nodes to reload.

Pool size (pool_size)⁠

Pool size (pool_size parameter) is the maximum number of connections between the connection pooler and each PostgreSQL database on each of the cluster nodes.

Pool size can be selected at cluster creation and change-pool-size in the created cluster. The available values range from 1 to 500.

Pooling modes⁠

Pooling mode is a strategy for connecting the client to PostgreSQL. PostgreSQL cloud database clusters utilize the PgBouncer connection pooler. For more information about the connection pooler, see the PgBouncer documentation.

PgBouncer supports three modes:

By default, cloud databases use the transaction mode.

Pooling mode can be selected at cluster creation and change mode in the created cluster.

Transaction mode (transaction)⁠

The connection to PostgreSQL is maintained until the transaction completes. When the transaction completes, the pooler returns the connection to the pool. This connection can later be reused by the same client for other connections or by another client.

The total number of client connections to PgBouncer can be as high as 10,000, but the number of active transactions determines the size of the pool. For example, if the pool size is 30, there will be 30 active transactions.

The number of connections between the connection pooler and each PostgreSQL database on each cluster node is also determined by the size of the pool.

A client can simultaneously execute multiple transactions on different connections. In this case, each connection between the connection pooler and the PostgreSQL server can execute transactions of different clients during its lifecycle.

Transaction mode reduces the load on DBMS resources if there are a large number of low-load client connections.

Limitations of transaction mode⁠

Transaction mode breaks some PostgreSQL mechanisms. Select a different mode if customers use these options. Some connection flags may be distributed among different clients — this can lead to unpredictable behavior and incorrect results.

They don't work in transaction mode:

Read more about incompatible options in the PgBouncer documentation.

Session mode (session)⁠

In session mode, the client can continue sending queries as long as the session continues — the connection between the connection pooler and the PostgreSQL server will be maintained until the client disconnects from the database.

The number of connections between the connection pooler and the PostgreSQL server is determined by pool-size. For each client connection, the connection between the pooler and the PostgreSQL server is used. The connection is returned to the pool and can be reused only after disconnecting the previous client from the database.

Unlike transaction mode, this mode is safe, replicates a direct connection to PostgreSQL, supports all mechanisms and is suitable for all PostgreSQL clients. When using this mode, the load on resources is not reduced.

This connection mode is useful for clients that have many short-lived database connections, because this mode increases the DBMS connection speed.

Operator mode (statement)⁠

The pooler will return the connection to the pool as soon as the first request is processed — transactions with multiple statements will abort, the pooler will return an error.

This mode allows more client connections than in transaction mode. The mode is suitable if it is known that each transaction is limited to only one request (AUTOCOMMIT is enabled).

Change pooling mode⁠

For your information

If you select transaction mode, please see the limitations of this mode.

  1. In Control Panel, go to Cloud Platform → Databases.
  2. Open the cluster page → Settings tab.
  3. In the Connection Pooler box, click Change and select the pooling mode.
  4. Click Save.

Change pool size⁠

  1. In Control Panel, go to Cloud Platform → Databases.
  2. Open the cluster page → Settings tab.
  3. In the Connection Pooler block, click Modify and change the pool size.
  4. Click Save.