PgBouncer in Azure Database for PostgreSQL - Flexible Server

Article
04/18/2024

APPLIES TO: Azure Database for PostgreSQL - Flexible Server

Azure Database for PostgreSQL flexible server offers PgBouncer as a built-in connection pooling solution. PgBouncer is an optional feature that you can enable on a per-database-server basis. It's supported on General Purpose and Memory Optimized compute tiers in both public access and private access networks.

PgBouncer runs on the same virtual machine (VM) as the database server for Azure Database for PostgreSQL flexible server. Postgres uses a process-based model for connections, so maintaining many idle connections is expensive. Postgres runs into resource constraints when the server runs more than a few thousand connections. The primary benefit of PgBouncer is to improve idle connections and short-lived connections at the database server.

PgBouncer uses a lightweight model that utilizes asynchronous I/O. It uses Postgres connections only when needed--that is, when inside an open transaction or when a query is active. This model allows scaling to up to 10,000 connections with low overhead.

PgBouncer runs on port 6432 on your database server. You can change your application's database connection configuration to use the same host name, but change the port to 6432 to start using PgBouncer and benefit from improved scaling of idle connections.

PgBouncer in Azure Database for PostgreSQL flexible server supports Microsoft Entra authentication.

Enabling and configuring PgBouncer

To enable PgBouncer, go to the Server parameters pane in the Azure portal, search for PgBouncer, and change the pgbouncer.enabled setting to true. There's no need to restart the server.

You can configure PgBouncer settings by using these parameters.

Note

The following list of PgBouncer server parameters is visible on the Server parameters pane only if the pgbouncer.enabled server parameter is set to true. Otherwise, they're deliberately hidden.

Parameter name	Description	Default
pgbouncer.default_pool_size	Set this parameter value to the number of connections per user/database pair.	50
pgbouncer.ignore_startup_parameters	Enter a comma-separated list of parameters that PgBouncer can ignore. For example, you can let PgBouncer ignore the `extra_float_digits` parameter. Some parameters are allowed; all others raise an error. This ability is needed to tolerate overenthusiastic Java Database Connectivity (JDBC) wanting to unconditionally set `extra_float_digits=2` in startup packets. Use this option if the library that you use reports errors such as `pq: unsupported startup parameter: extra_float_digits`.
pgbouncer.max_client_conn	Set this parameter value to the highest number of client connections to PgBouncer that you want to support.	5000
pgbouncer.max_prepared_statements	When this is set to a non-zero value PgBouncer tracks protocol-level named prepared statements related commands sent by the client in transaction and statement pooling mode.	0
pgbouncer.min_pool_size	Add more server connections to pool if below this number.	0
pgbouncer.pool_mode	Set this parameter value to TRANSACTION for transaction pooling (which is the recommended setting for most workloads).	transaction
pgbouncer.query_wait_timeout	Maximum time (in seconds) queries are allowed to spend waiting for execution. If the query is not assigned to a server during that time, the client is disconnected.	120
pgbouncer.server_idle_timeout	If a server connection has been idle more than this many seconds it will be dropped. If 0 then timeout is disabled.	600
pgbouncer.stats_users	Comma-separated list of database users that are allowed to connect and run read-only queries on the pgBouncer console.

For more information about PgBouncer configurations, see the pgbouncer.ini documentation.

The following table shows the versions of PgBouncer currently deployed, together with each major version of PostgreSQL:

PostgreSQL 16	PostgreSQL 15	PostgreSQL 14	PostgreSQL 13	PostgreSQL 12	PostgreSQL 11
1.22.1	1.22.1	1.22.1	1.22.1	1.22.1	1.22.1

Benefits

By using the built-in PgBouncer feature with Azure Database for PostgreSQL flexible server, you can get these benefits:

Convenience of simplified configuration: Because PgBouncer is integrated with Azure Database for PostgreSQL flexible server, there's no need for a separate installation or complex setup. You can configure it directly from the server parameters.
Reliability of a managed service: PgBouncer offers the advantages of Azure managed services. For example, Azure manages updates of PgBouncer. Automatic updates eliminate the need for manual maintenance and ensure that PgBouncer stays up to date with the latest features and security patches.
Support for various connection types: PgBouncer in Azure Database for PostgreSQL flexible server provides support for both public and private connections. You can use it to establish secure connections over private networks or connect externally, depending on your specific requirements.
High availability in failover scenarios: If a standby server is promoted to the primary role during a failover, PgBouncer seamlessly restarts on the newly promoted standby. You don't need to make any changes to the application connection string. This ability helps ensure continuous availability and minimizes disruption to the application's connection pool.

Monitoring PgBouncer

Metrics

Azure Database for PostgreSQL flexible server provides six metrics for monitoring PgBouncer connection pooling:

Display name	Metric ID	Unit	description	Dimension	Default enabled
Active client connections (preview)	`client_connections_active`	Count	Connections from clients that are associated with an Azure Database for PostgreSQL flexible server connection	`DatabaseName`	No
Waiting client connections (preview)	`client_connections_waiting`	Count	Connections from clients that are waiting for an Azure Database for PostgreSQL flexible server connection to service them	`DatabaseName`	No
Active server connections (preview)	`server_connections_active`	Count	Connections to Azure Database for PostgreSQL flexible server that a client connection is using	`DatabaseName`	No
Idle server connections (preview)	`server_connections_idle`	Count	Connections to Azure Database for PostgreSQL flexible server that are idle and ready to service a new client connection	`DatabaseName`	No
Total pooled connections (preview)	`total_pooled_connections`	Count	Current number of pooled connections	`DatabaseName`	No
Number of connection pools (preview)	`num_pools`	Count	Total number of connection pools	`DatabaseName`	No

To learn more, see PgBouncer metrics.

Admin console

PgBouncer also provides an internal database called pgbouncer. When you connect to that database, you can run SHOW commands that provide information on the current state of PgBouncer.

To connect to the pgbouncer database:

Set the pgBouncer.stats_users parameter to the name of an existing user (for example, myUser), and apply the changes.

Connect to the pgbouncer database as this user and set the port as 6432:

psql "host=myPgServer.postgres.database.azure.com port=6432 dbname=pgbouncer user=myUser password=myPassword sslmode=require"

After you're connected to the database, use SHOW commands to view PgBouncer statistics:

SHOW HELP: List all the available SHOW commands.
SHOW POOLS: Show the number of connections in each state for each pool.
SHOW DATABASES: Show the current applied connection limits for each database.
SHOW STATS: Show statistics on requests and traffic for every database.

For more information on the PgBouncer SHOW commands, see Admin console.

Switching your application to use PgBouncer

To start using PgBouncer, follow these steps:

Connect to your database server, but use port 6432 instead of the regular port 5432. Verify that this connection works.

psql "host=myPgServer.postgres.database.azure.com port=6432 dbname=postgres user=myUser password=myPassword sslmode=require"

Test your application in a QA environment against PgBouncer, to make sure you don't have any compatibility problems. The PgBouncer project provides a compatibility matrix, and we recommend transaction pooling for most users.
Change your production application to connect to port 6432 instead of 5432. Monitor for any application-side errors that might point to compatibility issues.

PgBouncer in zone-redundant high availability

In zone-redundant, high-availability (HA) servers, the primary server runs PgBouncer. You can connect to PgBouncer on the primary server over port 6432. After a failover, PgBouncer is restarted on the newly promoted standby, which is now the primary server. So your application connection string remains the same after failover.

Using PgBouncer with other connection pools

In some cases, you might already have an application-side connection pool or have PgBouncer set up on your application side (for example, an Azure Kubernetes Service sidecar). In these cases, the built-in PgBouncer feature can still be useful because it provides the benefits of idle connection scaling.

Using an application-side pool together with PgBouncer on the database server can be beneficial. Here, the application-side pool brings the benefit of reduced initial connection latency (because the roundtrip to initialize the connection is much faster), and the database-side PgBouncer provides idle connection scaling.

Limitations

The PgBouncer feature is currently not supported with the Burstable server compute tier. If you change the compute tier from General Purpose or Memory Optimized to Burstable, you lose the built-in PgBouncer capability.
Whenever the server is restarted during scale operations, HA failover, or a restart, PgBouncer and the VM are also restarted. You then have to re-establish the existing connections.
The portal doesn't show all PgBouncer parameters. After you enable PgBouncer and save the parameters, you have to close the Server parameters pane (for example, select Overview) and then go back to the Server parameters pane.
You can't use transaction and statement pool modes along with prepared statements. To check other limitations of your chosen pool mode, refer to the PgBouncer documentation.
If PgBouncer is deployed as a feature, it becomes a potential single point of failure. If the PgBouncer feature is down, it can disrupt the entire database connection pool and cause downtime for the application. To mitigate the single point of failure, you can set up multiple PgBouncer instances behind a load balancer for high availability on Azure VMs.
PgBouncer is a lightweight application that uses a single-threaded architecture. This design is great for most application workloads. But in applications that create a large number of short-lived connections, this design might affect pgBouncer performance and limit your ability to scale your application. You might need to try one of these approaches:
- Distribute the connection load across multiple PgBouncer instances on Azure VMs.
- Consider alternative solutions, including multithreaded solutions like PgCat, on Azure VMs.

Important

The parameter pgbouncer.client_tls_sslmode for the built-in PgBouncer feature has been deprecated in Azure Database for PostgreSQL flexible server.

When TLS/SSL for connections to Azure Database for PostgreSQL flexible server is enforced via setting the require_secure_transport server parameter to ON, TLS/SSL is automatically enforced for connections to the built-in PgBouncer feature. This setting is on by default when you create a new Azure Database for PostgreSQL flexible server instance and enable the built-in PgBouncer feature. For more information, see Networking overview for Azure Database for PostgreSQL - Flexible Server with private access.

For customers who want simplified management, built-in high availability, easy connectivity with containerized applications, and the ability to use the most popular configuration parameters, the built-in PgBouncer feature is a good choice. For customers who want multithreaded scalability, full control of all parameters, and a debugging experience, setting up PgBouncer on Azure VMs might be an alternative.

Next steps

Learn about network concepts.
Get an overview of Azure Database for PostgreSQL flexible server.