TRY NOW
book meeting
BACK TO KB LIST

How to Install and Configure PgBouncer for Veeam Backup for Microsoft 365

KB ID: 4728
Product: Veeam Backup for Microsoft 365 | 8.1 | 8.2 | 8.3 | 8.4 | 8.5
Published: 2025-07-18
Last Modified: 2026-07-16
mailbox
Get weekly article updates
By subscribing, you are agreeing to have your personal information managed in accordance with the terms of Veeam's Privacy Notice.

Cheers for trusting us with the spot in your mailbox!

Now you’re less likely to miss what’s been brewing in our knowledge base with this weekly digest

error icon

Oops! Something went wrong.

Please, try again later.

PgBouncer must not be deployed on the machine where Veeam Backup for Microsoft 365 is installed.

This article is intended only for deployments where the PostgreSQL Instance used by Veeam Backup for Microsoft 365 is hosted on its own dedicated server.

For deployments of Veeam Backup for Microsoft 365 where the PostgreSQL instance is installed on the same machine as Veeam Backup for Microsoft 365, PgBouncer must not be deployed.

Review KB4758: PostgreSQL and PgBouncer Sizing and Configuration Guide for advice on whether the PostgreSQL instance should be deployed on its own dedicated server based on the Veeam Backup for Microsoft 365 deployment size. If the guidance in that article indicates that PostgreSQL should be hosted on a dedicated server, consider migration (review: KB4676: How to Migrate the Configuration and Repository Cache Databases).

Purpose

This article provides step-by-step instructions for installing and configuring PgBouncer for use with Veeam Backup for Microsoft 365. PgBouncer is a lightweight connection pooler for PostgreSQL, and this guide is intended to help users integrate it with Veeam Backup for Microsoft 365 environments to improve database connection efficiency and performance.

Cause

Why should you deploy PgBouncer?

Each proxy and repository must connect to the PostgreSQL database when using Veeam Backup for Microsoft 365. This can quickly create thousands of separate database connections in larger environments, overloading the PostgreSQL server’s resources and network, causing performance issues.

PgBouncer helps by pooling those connections. Instead of every proxy making its own connection, PgBouncer groups them and reuses connections efficiently. This dramatically reduces the total number of database connections and lowers the strain on the PostgreSQL server, making the system more stable and reliable.

Solution

Follow the steps below to install PgBouncer, configure it for use with PostgreSQL, and integrate it with Veeam Backup for Microsoft 365.

Depending on the number of proxies or repositories, you may require more precise configuration tunings for PostgreSQL and PgBouncer parameters.

KB4758: PostgreSQL and PgBouncer Sizing and Configuration Guide

Part 1: Prepare PostgreSQL Configuration

  1. Using pgAdmin, or the PostgreSQL DB management tool of your choosing, create a dedicated user within the PostgreSQL instance for PgBouncer to use.

CREATE USER pgbouncer WITH LOGIN;
-- Update pgbouncerpass with the actual password you want to assign to the pgbouncer account.
ALTER USER pgbouncer WITH PASSWORD 'pgbouncerpass';
  1. Using the Query Tool, and making sure the 'postgres' db is targeted, create a user lookup function to allow PgBouncer to authenticate users via PostgreSQL:
CREATE OR REPLACE FUNCTION user_search(uname TEXT) 
RETURNS TABLE (usename name, passwd text) AS 
$$ 
  SELECT usename, passwd FROM pg_shadow WHERE usename = $1; 
$$ 
LANGUAGE sql SECURITY DEFINER;
  1. Open the pg_hba.confFound in: C:\Program Files\PostgreSQL\16\data\ file and verify that it contains rules to accept local connections. 
    # TYPE   DATABASE        USER           ADDRESS                METHOD
local    all             all                                   scram-sha-256
host     all             all            127.0.0.1/32           scram-sha-256
host     all             all            ::1/128                scram-sha-256
  2. If any changes were made to the pg_hba.conf file, then restart the PostgreSQL service.

Part 2: Install and Configure PgBouncer

Since PgBouncer must be installed on the same machine as the existing PostgreSQL instance, the instructions depend on the OS of the machine where PostgreSQL is installed.

Expand the appropriate section.

PgBouncer on Windows Instructions

 

  1. Download and extract the latest Windows build of PgBouncer.
    1. Download the Windows package for PgBouncer v1.25.2.
      https://github.com/pgbouncer/pgbouncer/releases/download/pgbouncer_1_25_2/pgbouncer-1.25.2-windows-x86_64.zip
      The version listed above is tested and approved to be supported for use with Veeam Backup for Microsoft 365.
    2. Extract the contents of the folder within the archive to a directory; this guide recommends: C:\Program Files\pgbouncer\
      If a different folder is used, update the pgbouncer.ini file appropriately.
  2. Edit the pgbouncer.ini file in the PgBouncer install directory. 
    C:\Program Files\pgbouncer\pgbouncer.ini
    Below is the recommended pgbouncer.ini file configuration. For more details, see this article.
Configuration Notes
  • The contents of the example below can be used to replace the entire default contents of the C:\Program Files\pgbouncer\pgbouncer.ini file.
  • The configuration contains an entry that specifies the Veeam Backup for Microsoft 365 configuration DB name as VeeamBackup365, which is the default name. The database name can be confirmed by reviewing the ControllerPostgres section within the %Programdata%\Veeam\Backup365\Config.xml file on the Veeam Backup for Microsoft 365 server.
  • The PostgreSQL option max_connections should be configured based on the following formula:
    max_connections(postgresql.auto.conf) = max_user_connections(pgbouncer.ini) * 1.10
  • The parameter default_pool_size should be increased in some cases.
    If the value is too low, errors like the following will be seen:
    • Error: [EFCoreLogging]: An error occurred using the connection to database 'cache_*' on server 'tcp://SERVERNAME:6432'

    • Retry transient error after 00:00:00: NpgsqlException: The connection pool has been exhausted, either raise 'Max Pool Size'

 

;;;
;;; PgBouncer configuration file
;;;
[databases]
* = host=127.0.0.1 port=5432 auth_user=pgbouncer 
VeeamBackup365 = host=127.0.0.1 port=5432 auth_user=pgbouncer dbname=VeeamBackup365 pool_size=200

;; Configuration section
[pgbouncer]

;;;
;;; Administrative settings
;;;
logfile = C:\Program Files\pgbouncer\pgbouncer.log
pidfile = C:\Program Files\pgbouncer\pgbouncer.pid

;;;
;;; Where to wait for clients
;;;
listen_addr = *
listen_port = 6432

;;;
;;; Authentication settings
;;;
auth_type = hba
auth_file = C:\Program Files\pgbouncer\userlist.txt

;; HBA configuration file to use when auth_type is hba.
auth_hba_file = C:\Program Files\pgbouncer\pgbouncer_hba.conf

;; Query to use to fetch password from database. Result
auth_query = SELECT usename, passwd FROM user_search($1)
auth_dbname = postgres

;;;
;;; Users allowed into database 'pgbouncer'
;;;
admin_users = pgbouncer, postgres, root
stats_users = pgbouncer, postgres, root, stats

;;;
;;; Pooler personality questions
;;;
pool_mode = transaction
ignore_startup_parameters = extra_float_digits,application_name

;;;
;;; Connection limits
;;;
; total number of clients that can connect
max_client_conn = 10000
max_user_connections = 1300
default_pool_size = 20

;;;
;;; Logging
;;;
log_connections = 0
log_disconnections = 0
stats_period = 180
verbose = 0

;;;
;;; Timeouts
;;;
server_idle_timeout = 60
server_connect_timeout = 120
query_wait_timeout = 55

;;; 
;;; Random stuff 
;;; 
service_name = pgbouncer

If TLS encryption has been enabled for the PostgreSQL instance used by Veeam Backup for Microsoft 365 (v8.4 and later), TLS must also be enabled on PgBouncer. For instructions on enabling TLS on the PostgreSQL instance, see Enabling TLS Encryption on PostgreSQL Instance.

Add the following to the [pgbouncer] section of the pgbouncer.ini file:

; TLS for client connections (Veeam Backup for Microsoft 365 to PgBouncer)
client_tls_sslmode = allow
client_tls_key_file = C:\Program Files\PostgreSQL\16\data\server.key
client_tls_cert_file = C:\Program Files\PostgreSQL\16\data\server.crt

; TLS for server connections (PgBouncer to PostgreSQL)
server_tls_sslmode = allow
server_tls_key_file = C:\Program Files\PostgreSQL\16\data\server.key
server_tls_cert_file = C:\Program Files\PostgreSQL\16\data\server.crt
  1. Update the PgBouncer userlist.txt file to list which users should have access to connect through PgBouncer.
    Default location: C:\Program Files\pgbouncer\userlist.txt 
    "pgbouncer" "pgbouncerpass"
    The username and password should be the same as the ones created in Part 1 - Step 1.
    For a more secure way to configure the userlist.txt, please review the PgBouncer documentation.
  2. Within the PgBouncer install folder, create a new file named pgbouncer_hba.conf that mimics the pg_hba.conf file used by PostgreSQL for access control. To do this, simply copy the rules from the existing pg_hba.conf file found in C:\Program Files\PostgreSQL\16\data to the new C:\Program Files\pgbouncer\pgbouncer_hba.conf file.

Example:

# Allow all users to connect over Unix socket using SCRAM-SHA-256 authentication
local all all scram-sha-256

# Allow all users to connect from any IPv4 address using SCRAM-SHA-256 authentication
host all all 0.0.0.0/0 scram-sha-256

# Allow all users to connect from any IPv6 address using SCRAM-SHA-256 authentication
host all all ::/0 scram-sha-256
  1. Register PgBouncer as a Windows Service. 
    1. Open a Command Prompt as Administrator.
    2. Navigate to the PgBouncer directory. (C:\Program Files\pgbouncer\)
    3. Run the following command:
pgbouncer.exe -regservice pgbouncer.ini
  1. In a Command Prompt, run the sc.exe command below and confirm that the BINARY_PATH_NAME appears as follows: 
    C:\Program Files\pgbouncer\pgbouncer.exe --service "C:\Program Files\pgbouncer\pgbouncer.ini"

sc.exe qc pgbouncer
  1. Update the failure recovery settings for the pgbouncer service to "Restart the service" on First Failure and Second Failure.

    This can be done via the Service control panel or by running the following command in a Command Prompt:
sc failure pgbouncer reset=1 actions=restart/60000/restart/60000//10000
  1. Start the pgbouncer service.
  2. From the Windows machine where Veeam Backup for Microsoft 365 is installed, run the following PowerShell command to test port connectivity to the PgBouncer service:
Test-NetConnection -ComputerName %PG_SERVER_NAME% -Port 6432
PgBouncer on Linux Instructions
  1. Install PgBouncer release version 1.25.2 from source.
    The version listed above is tested and approved to be supported for use with Veeam Backup for Microsoft 365.
  2. Edit /etc/pgbouncer/pgbouncer.ini and replace the contents with the following:
Configuration Notes
  • Full documentation of the PgBouncer config can be found here:
    https://www.pgbouncer.org/config.html
  • The provided configuration utilizes a local unix-socket for communication between PgBouncer and the local PostgreSQL instance. The unix_socket configuration section included is the recommended defaults from Veeam. However, some distros and versions may require additional adjustments.
  • The configuration contains an entry that specifies the Veeam Backup for Microsoft 365 configuration DB name as VeeamBackup365, which is the default name. The database name can be confirmed by reviewing the ControllerPostgres section within the %Programdata%\Veeam\Backup365\Config.xml file on the Veeam Backup for Microsoft 365 server.
  • The PostgreSQL option max_connections should be configured based on the following formula:
    max_connections(postgresql.auto.conf) = max_user_connections(pgbouncer.ini) * 1.10
  • The parameter default_pool_size should be increased in some cases.
    If the value is too low, errors like the following will be seen:
    • Error: [EFCoreLogging]: An error occurred using the connection to database 'cache_*' on server 'tcp://SERVERNAME:6432'

    • Retry transient error after 00:00:00: NpgsqlException: The connection pool has been exhausted, either raise 'Max Pool Size'

 

;;;
;;; PgBouncer configuration file
;;;
[databases]
* = host=/var/run/postgresql auth_user=pgbouncer
VeeamBackup365 = host=/var/run/postgresql auth_user=pgbouncer dbname=VeeamBackup365 pool_size=200

;; User-specific configuration
[users]

;; Configuration section
[pgbouncer]
logfile = /var/log/postgresql/pgbouncer.log
pidfile = /var/run/postgresql/pgbouncer.pid

;; IP address or * which means all IPs
listen_addr = *
listen_port = 6432

; unix socket is also used for -R.
; On debian it should be /var/run/postgresql
unix_socket_dir = /tmp
unix_socket_mode = 0755
unix_socket_group = postgres

;;;
;;; Authentication settings
;;;
auth_type = hba
auth_file = /etc/pgbouncer/userlist.txt

;; HBA configuration file to use when auth_type is hba.
auth_hba_file = /etc/pgbouncer/pgbouncer_hba.conf

;; Query to use to fetch password from database.
auth_query = SELECT usename, passwd FROM user_search($1)
auth_dbname = postgres

;;;
;;; Users allowed into database 'pgbouncer'
;;;
admin_users = pgbouncer, postgres, root
stats_users = pgbouncer, postgres, root, stats

;;;
;;; Pooler personality questions
;;;
pool_mode = transaction
ignore_startup_parameters = extra_float_digits,application_name

;;;
;;; Connection limits
;;;
max_client_conn = 10000
max_user_connections = 1300
default_pool_size = 20

;;;
;;; Logging
;;;
log_connections = 0
log_disconnections = 0
stats_period = 180

;;;
;;; Timeouts
;;;
server_idle_timeout = 60
server_connect_timeout = 120
query_wait_timeout = 55

;;; 
;;; Network settings 
;;; 
;; networking options, for info: man 7 tcp
tcp_defer_accept = 45

;; following options are Linux-specific.
tcp_keepcnt = 0
tcp_keepidle = 0
tcp_keepintvl = 0

If TLS encryption has been enabled for the PostgreSQL instance used by Veeam Backup for Microsoft 365 (v8.4 and later), TLS must also be enabled on PgBouncer. For instructions on enabling TLS on the PostgreSQL instance, see Enabling TLS Encryption on PostgreSQL Instance.

Add the following to the [pgbouncer] section of the /etc/pgbouncer/pgbouncer.ini file:

; TLS for client connections (Veeam Backup for Microsoft 365 to PgBouncer)
client_tls_sslmode = allow
client_tls_key_file = /var/lib/postgresql/16/main/server.key
client_tls_cert_file = /var/lib/postgresql/16/main/server.crt

; TLS for server connections (PgBouncer to PostgreSQL)
server_tls_sslmode = allow
server_tls_key_file = /var/lib/postgresql/16/main/server.key
server_tls_cert_file = /var/lib/postgresql/16/main/server.crt
  1. Update the PgBouncer /etc/pgbouncer/userlist.txt file to list the account that was created in Part 1 - Step 1. 
    "pgbouncer" "pgbouncerpass"
    For a more secure way to configure the userlist.txt, please review the PgBouncer documentation.
  2. Navigate to the PgBouncer configuration folder: /etc/pgbouncer/
  3. Create a new file named pgbouncer_hba.conf
  4. Copy the access rules from the pg_hba.conf file used by PostgreSQL to a new pgbouncer_hba.conf file.
    To do this, simply copy the rules from the existing pg_hba.conf file found in /etc/postgresql/16/main/ to the new /etc/pgbouncer/pgbouncer_hba.conf file.

Example:

# Allow all users to connect over Unix socket using SCRAM-SHA-256 authentication
local all all scram-sha-256

# Allow all users to connect from any IPv4 address using SCRAM-SHA-256 authentication
host all all 0.0.0.0/0 scram-sha-256

# Allow all users to connect from any IPv6 address using SCRAM-SHA-256 authentication
host all all ::/0 scram-sha-256
  1. Restart the pgbouncer service:
sudo systemctl restart pgbouncer.service
  1. Run the following command to confirm that the service is running:
sudo systemctl status pgbouncer.service
  1. From the Windows machine where Veeam Backup for Microsoft 365 is installed, run the following PowerShell command to test port connectivity to the PgBouncer service:
Test-NetConnection -ComputerName %PG_SERVER_NAME% -Port 6432
PgBouncer on Azure Database for PostgreSQL flexible server Instructions

  1. Review the Microsoft Azure documentation for enabling PgBouncer in Azure Database for PostgreSQL.

Veeam recommends the following settings:

Parameter NameValueDescription
metrics.pgbouncer_diagnosticsON/OFFEnables metrics collection for PgBouncer if you plan to use Azure Monitor to build dashboards for monitoring purposes.
pgbouncer.default_pool_size100How many server connections to allow per user/database pair.
pgbouncer.enabledTRUEDenotes if the PgBouncer service is enabled.
pgbouncer.ignore_startup_parametersleave emptyComma-separated list of parameters that PgBouncer can ignore because they are going to be handled by the admin.
pgbouncer.max_client_conn10000Maximum number of client connections allowed.
pgbouncer.max_prepared_statements0When 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.
pgbouncer.min_pool_size0Add more server connections to the pool if below this number.
pgbouncer.pool_modeTRANSACTIONSpecifies when a server connection can be reused by other clients.
pgbouncer.query_wait_timeout55The 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.
pgbouncer.server_idle_timeout60If a server connection has been idle for more than this many seconds, it will be dropped. If 0, then the timeout is disabled.
pgbouncer.stats_usersleave empty
 		Leave empty if you don't plan to monitor pgbouncer stats live.
Comma-separated list of database users that are allowed to connect and run read-only queries on the pgBouncer console.
Swipe to show more of the table
  1. From the Windows machine where Veeam Backup for Microsoft 365 is installed, run the following PowerShell command to test port connectivity to the PgBouncer service:
Test-NetConnection -ComputerName %PG_SERVER_NAME% -Port 6432

Part 3: Configure Veeam Backup for Microsoft 365

In the Veeam Backup for Microsoft 365 settings, change the port used to connect to PostgreSQL to the one used by PgBouncer.

  1. Perform the following steps on the VB365 server machine:
    1. Ensure no backup or restore tasks are running.
    2. Stop the Veeam.Archiver.Service and the Veeam.Archiver.Proxy services.
    3. Navigate to: 
      C:\ProgramData\Veeam\Backup365\
    4. Make a copy of Config.xml and Proxy.xml in case changes need to be reverted or a misconfiguration occurs.
    5. Open the Config.xml file, and within the <Archiver> section, change the port= value to 6432 for the following sections: 
      • <ControllerPostgres ControllerConnectionString="host=VB365;port=5432

      • <RemoteProxyDeploymentSettings ControllerConnectionStringForProxy="host=VB365;port=5432

      • PersistentCacheConnectionStringTemplate="host=VB365;port=5432
        This entry is on the same line as "<RemoteProxyDeploymentSettings"
    6. Open the Proxy.xml file, and within the <Archiver> section, change the port= value to 6432 for the following sections: 
      • <ProxyPostgres ControllerConnectionString="host=testvm;port=5432

      • <PersistentCachePostgres PersistentCacheConnectionString="host=testvm;port=5432
    7. Save the updated Config.xml and Proxy.xml files.
    8. Start the Veeam.Archiver.Service and the Veeam.Archiver.Proxy services.
    9. Reopen the Config.xml and Proxy.xml files and confirm that all port values you set to 6432 are still set that way.
      The Veeam.Archiver.Service will attempt to repair the xml files if it detects a misconfiguration, so the recheck is to make sure the changes were accepted and implemented.
  2. Update the configuration of all remote backup proxies:
    1. Open the Veeam Backup for Microsoft 365 console.
    2. Switch to the Backup Infrastructure node.
    3. Select all proxies and click the Upgrade button.

More Information

Related Articles

If this KB article did not resolve your issue or you need further assistance with Veeam software, please create a Veeam Support Case.

To submit feedback regarding this article, please click this link: Send Article Feedback
To report a typo on this page, highlight the typo with your mouse and press CTRL + Enter.

Spelling error in text

Thank you!

Thank you!

Your feedback has been received and will be reviewed.

Oops! Something went wrong.

Please, try again later.

You have selected too large block!

Please try select less.

KB Feedback/Suggestion

This form is only for KB Feedback/Suggestions, if you need help with the software open a support case
By submitting, you are agreeing to have your personal information managed in accordance with the terms of Veeam's Privacy Notice.
Verify your email to continue your product download
We've sent a verification code to:
  • Incorrect verification code. Please try again.
An email with a verification code was just sent to
Didn't receive the code? Click to resend in sec
Didn't receive the code? Click to resend
Start using Veeam:
Download the product
&
Activate the license key
Thank you!

Thank you!

Your feedback has been received and will be reviewed.

error icon

Oops! Something went wrong.

Please, try again later.