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

KB ID:	4728
Product:	Veeam Backup for Microsoft 365 \| 8.1
Published:	2025-07-18
Last Modified:	2025-07-18

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.

Part 1: Prepare PostgreSQL Configuration

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';

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;

Open the pg_hba.confFound in: C:\Program Files\PostgreSQL\15\data\ file and verify that it contains rules to accept local connections.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

If any changes were made to the ph_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.

Download and extract the latest Windows build of PgBouncer.
1. Download the Windows package for PgBouncer v1.24.1.
  https://github.com/pgbouncer/pgbouncer/releases/download/pgbouncer_1_24_1/pgbouncer-1.24.1-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.
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 = (max_user_connections + pool_size) * 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 = 800
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

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

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 Step 1.
For a more secure way to configure the userlist.txt, please review the PgBouncer documentation.
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\15\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

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

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

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

Start the pgbouncer service.

Install PgBouncer release version 1.24.1 from source.
Edit /etc/pgbouncer/pgbouncer.ini and replace the contents with the following:

Configuration Notes

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 = (max_user_connections + pool_size) * 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

;; 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 = 800
default_pool_size = 20

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

;;;
;;; Timeouts
;;;
server_idle_timeout = 60
server_connect_timeout = 120

;;; 
;;; 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

Update the PgBouncer /etc/pgbouncer/userlist.txt file to list the account that was created in Step 1.
```
"pgbouncer" "pgbouncerpass"
```
For a more secure way to configure the userlist.txt, please review the PgBouncer documentation.
Navigate to the PgBouncer configuration folder: /etc/pgbouncer/
Create a new file named pgbouncer_hba.conf
Copy the access rules from the pg_hba.conf file used by PostgreSQL to new pgboucer_hba.conf file.
To do this, simply copy the rules from the existing pg_hba.conf file found in /etc/postgresql/15/main/data 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

Restart the pgbouncer service:

sudo systemctl restart pgbouncer.service

Run the following command to confirm that the service is running:

sudo systemctl status pgbouncer.service

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.

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 we accepted and implemented.}
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.

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.

Veeam

via Veeam Support Knowledge Base https://ift.tt/w24vxmF

July 18, 2025 at 03:42PM
Veeam Backup for Microsoft 365

Stack IT News

Collecting news

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

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

Purpose

Cause

Why should you deploy PgBouncer?

Solution

Part 1: Prepare PostgreSQL Configuration

Part 2: Install and Configure PgBouncer

Part 3: Configure Veeam Backup for Microsoft 365

Related