PgBouncer
In PostgreSQL TimescaleDB, a separate process is created to handle each client connection. The higher the number of connections, the more processes that use RAM. The maximum number of connections to a PostgreSQL TimescaleDB process is defined as follows parameter max_connections.
To optimize resource consumption, you can use a connection pooler. Clients do not connect directly to PostgreSQL TimescaleDB, but to the connection pooler. A small number of connections between the pooler and the PostgreSQL TimescaleDB server is supported — 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 of the cluster is determined by pool size (parameter pool_size).
PostgreSQL TimescaleDB cloud database clusters use the PgBouncer connection pooler. Available three PgBouncer pooling modes. More information about the connection pooler in the documentation PgBouncer.
Maximum number of connections to PostgreSQL process (max_connections)
PostgreSQL TimescaleDB DBMS parameter max_connections specifies the maximum number of simultaneous connections to the PostgreSQL TimescaleDB process. The default value is 100 connections.
You can change the value of the parameter in the DBMS settings in the control panel to set the maximum number of connections under load. Note that each connection consumes RAM resources.
Value change max_connections causes the PostgreSQL TimescaleDB cluster nodes to reboot.
Pool size (pool_size)
Pool size (parameter pool_size) is the maximum number of connections between the connection pooler and each PostgreSQL TimescaleDB database on each node in the cluster.
The size of the pool can be selected at cluster creation and resize in the created cluster. Available values are from 1 to 500.
Pooling modes
Pooling mode is the client's connection strategy to PostgreSQL TimescaleDB. PostgreSQL TimescaleDB cloud database clusters use the PgBouncer connection pooler. Read more about the connection pooler in the documentation PgBouncer.
PgBouncer supports three modes:
By default, cloud databases use the transaction mode.
Pooling mode can be selected when cluster creation and change mode in the created cluster.
Transaction mode (transaction)
The connection to PostgreSQL TimescaleDB 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 up to 10,000, but the number of active transactions determines the pool size. 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 TimescaleDB database on each of the cluster nodes is also determined by the size of the pool.
A client can simultaneously execute multiple transactions on different connections. Each connection between the connection pooler and PostgreSQL TimescaleDB 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 the transaction mode
Transaction mode disrupts some PostgreSQL TimescaleDB mechanisms. Choose a different mode if clients use these options. Some connection flags may be distributed among different clients — this may lead to unpredictable behavior and incorrect results.
They do not work in transaction mode:
- teams SET/RESET and LISTEN/NOTIFY;
- WITH HOLD CURSOR;
- PRESERVE/DELETE ROWS in the time tables;
- prepared statements: protocol-level prepared plans, PREPARE, DEALLOCATE;
- operator LOAD;
- advisory locks Session-level advisory locks.
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 TimescaleDB server will be maintained until the client disconnects from the database.
The number of connections between the connection pooler and the PostgreSQL TimescaleDB server is determined by pool size. For each client connection, a connection between the pooler and the PostgreSQL TimescaleDB server is used. The connection is returned to the pooler 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 TimescaleDB, supports all mechanisms and is suitable for all PostgreSQL TimescaleDB 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 you to use more client connections than in transaction mode. This mode is suitable if it is known that each transaction is limited to only one request (AUTOCOMMIT enabled).
Change the pooling mode
If you select transaction mode, please refer to the following the limitations of this regime.
- In control panel go to Cloud platform → Databases.
- Open the cluster page → tab Settings.
- In the block Connection Pooler click Modify and select the pooling mode.
- Click Save.
Change pool size
- In control panel go to Cloud platform → Databases.
- Open the cluster page → tab Settings.
- In the block Connection Pooler click Modify and resize the pool.
- Click Save.