Veeam Support Knowledge Base
How to Migrate the Configuration and Repository Cache Databases

How to Migrate the Configuration and Repository Cache Databases

KB ID:	4676
Product:	Veeam Backup for Microsoft 365 \| 8 \| 8.1 \| 8.2 \| 8.3 \| 8.4 \| 8.5
Published:	2024-11-14
Last Modified:	2026-08-04

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

Oops! Something went wrong.

Please, try again later.

Article Applicability

This article is intended for use in environments where Veeam Backup for Microsoft 365 8 is already installed. The information provided in this article outlines the process for migrating the Configuration and Cache Databases from one PostgreSQL instance to another, including situations involving migrating the databases to a newer version of PostgreSQL.

For information about upgrading to Veeam Backup for Microsoft 365 version 8 from an older version, please review: Upgrading Veeam Backup for Microsoft 365

Purpose

This article documents the procedure for migrating the Configuration and Cache Databases of Veeam Backup for Microsoft 365 verison 8 from one PostgreSQL instance to another, including migrating those databases to a newer supported version of PostgreSQL.

Solution

Note: This procedure is 56 steps long. It will require experience and knowledge of operating pgAdmin and basic PostgreSQL administration. Customers are advised not to undertake this process unless necessary.

Please review each section's steps to understand what will be done, then go back and perform that section's steps. To the best of our ability, we have written this to document every step a customer must perform. If you find a step unclear, please highlight the step and press Ctrl+Enter to open the typo report form (this form is not for technical assistance).

Prepare for Migration

Ensure all jobs and restore tasks are completed, stopped, and disabled.
On the primary Veeam Backup for Microsoft 365 server (aka controller) and all associated Proxies, stop the Veeam Backup for Microsoft 365 services:
- Veeam Backup for Microsoft 365 Server
  
  Veeam Backup for Microsoft 365 Proxy Service
```
Get-Service Veeam.Archiver.Proxy | Stop-Service
```
  Veeam Backup for Microsoft 365 Service
```
Get-Service Veeam.Archiver.Service | Stop-Service
```
- Veeam Backup for Microsoft 365 Windows Proxy
  
  Veeam Backup for Microsoft 365 Proxy Service
```
Get-Service Veeam.Archiver.Proxy | Stop-Service
```
- Veeam Backup for Microsoft 365 Linux Proxy
  
  Veeam.Archiver.Proxy
```
systemctl stop Veeam.Archiver.Proxy
```
Review the Veeam Backup for Microsoft 365 configuration to identify the current database connection information.
1. On the machine where Veeam Backup for Microsoft 365 is installed open the following file in a text editor:
  C:\ProgramData\Veeam\Backup365\Config.xml
2. Look for the node named ControllerPostgres. On that line will be the current database connection information.
  - Example 1: Using VB365 Installer-deployed PostgreSQL Instance
```
<ControllerPostgres ControllerConnectionString="host=vb365srv;port=5432;database=VeeamBackup365;username=postgres;maxpoolsize=100;connectionidlelifetime=10" />
```
    In this example, we can see that the PostgreSQL server is named vb365srv, the configuration database is named VeeamBackup365, and we can tell that SSPI authentication is being used because there is no password= parameter.
  - Example 2: Using Remote Dedicated PostgreSQL Instance
```
<ControllerPostgres ControllerConnectionString="host=pgsqlsrv;port=5432;database=VeeamBackup365;username=veeam365svc;password=AQAAANCMnd8BFdERjHoAwE%2FCl%2BsBAAAAnyPJ1ttvw06By6Ldd2NKOkEHjdXl7buhzxlW4MjXMBBqLZQGWWjXHgyM%3D;maxpoolsize=100;connectionidlelifetime=10;PasswordEncrypted=True" />
```
    In this example, we can see that the PostgreSQL server is named pgsqlsrv, the configuration database is named VeeamBackup365, the user is named veeam365svc, and native password-based authentication is in use because there is a passsword= parameter configured.

Prepare pgAdmin

The migration procedure documented in this article utilizes pgAdmin, a third-party management tool for PostgreSQL.
When managing the PostgreSQL instance included with Veeam Backup for Microsoft 365, it is recommend to deploy pgAdmin using the PostgreSQL installer from the Redistr folder on the Veeam Backup for Microsoft 365 installer ISO. This ensures compatibility between pgAdmin and the PostgreSQL instance.
The most common cause of errors when restoring the configuration database using pgAdmin is an incompatibility between the PostgreSQL binaries that pgAdmin attempts to use and those associated with the PostgreSQL instance. Therefore, customers are encouraged to ensure that pgAdmin uses binaries that are compatible with the PostgreSQL instance being accessed.
As pgAdmin is a third-party application, Veeam Support can only provide best-effort assistance with troubleshooting errors or issues that may arise when utilizing pgAdmin.

Export from Source

Using pgAdmin, connect to the PostgreSQL server where the Veeam Backup for Microsoft 365 configuration database is located and export the following (the sections that follow explain in detail how to export these):

SQL Script files to recreate:
- Group Role: proxy_role_<config_db_name>
  Example Export Filename: proxyrole.sql
- User: proxy_dbuser_<config_db_name>
  Example Export Filename: proxyuser.sql
Database Backup Files
- Configuration Database: VeeamBackup365
  Example Export Filename: VeeamBackup365.backup
- Cache Database(s): cache_<guid>
  Example Export Filename: cache_<guid>.backup

Note: When connecting to the default included PostgreSQL instance, the default authentication method for the postgres user is SSPI, and you may see the error "SSPI authentication failed for user." If this occurs, review KB4542. If prompted to specify a password after connecting, click OK with the password field empty.

Export the Proxy Group Role

Under Login/Group Roles, identify the Group Role named proxy_role_veeambackup365
Right-click on that Group Role and select CREATE script.

A query tool window will appear with an SQL query to recreate the Group Role.
In the Query Tool Toolbar, click the Save icon and save the SQL script as proxyrole.sql for use later in the migration.

Export the Proxy User

Under Login/Group Roles, identify the User named proxy_dbuser_veeambackup365
Right-click on that Group Role and select CREATE script.

A query tool window will appear with an SQL query to recreate the Proxy user.
In the Query Tool Toolbar, click the Save icon and save the SQL script as proxyuser.sql for use later in the migration.

Export Configuration Database

Expand the Databases node.
Right-click on the Veeam Backup for Microsoft 365 Configuration Database, by default, named VeeamBackup365.
Select Backup...

In the Backup dialog window that appears, provide a path where the database backup will be created, ensure that the format is set to Custom, and then click Backup.

Export Cache Databases

If any database(s) are present named cache_<guid>, back them up.
_{Tip: If you right-click on the cache database and select Properties, you can copy the database name to the clipboard so that you can save the .backup file with the database name to make it easier to recreate and restore the database with the correct name during the Import portion of the migration.}

Tip

If Veeam Backup for Microsoft 365 was using the included local PostgreSQL deployment, and that PostgreSQL instance will not be used by any other software, stop and disable the postgresql service. This will prevent the software from mistakenly connecting to the old PostgreSQL instance if the configuration file is not updated correctly during the finalization stage of the migration.

Import to Destination

Notes:

The destination PostgreSQL instance can be hosted on either Windows or Linux.
When migrating the Configuration Database to a remote PostgreSQL instance, the authentication method Veeam Backup for Microsoft 365 uses to connect to the PostgreSQL instance must be switched to native password-based authentication.
Due to the variability of possible PostgreSQL configurations, this guide cannot account for all possible custom configurations that may occur when a PostgreSQL instance is already in use by other third-party software. This guide instead aims to document the configuration changes required to modify a default new deployment of PostgreSQL to allow it to host the Veeam Backup for Microsoft 365 Configuration and Cache databases.
Ensure that the destination PostgreSQL instance is running a version supported by Veeam Backup for Microsoft 365.

Copy Generated Files to Destination

Copy the generated .sql and .backup files to the new PostgreSQL server.

Recreate the Proxy Group Role

Using pgAdmin, connect to the destination PostgreSQL instance.
Right-click on any database and select Query Tool.

In the Query Tool Toolbar, click the Open button.

Open the exported Proxy Group Role SQL script, proxyrole.sql.
With the query now open in the Query Tool, click Execute script in the Query Tool Toolbar to recreate the Proxy Group Role.

Recreate the Proxy User

With the Query Tool still open from adding the Proxy Group Role, click the Open button again.

Open the exported Proxy User SQL script, proxyuser.sql.
Click Execute to recreate the Proxy User.

Recreate and Restore the Configuration Database

Right-click on the Databases node, and highlight Create>, then click Database...

Name the database after the Configuration Database that was backed up.

Right-click on the new database and select Restore...

Select the .backup file created from the Configuration Database and click Restore.

Recreate and Restore Cache Databases

If any databases named cache_<guid> were backed up from the original PostgreSQL instance:

Create new cache_<guid> database(s) with their original names.
Use the .backup file from each cache_ database to restore the cache database(s).

Configure PostgreSQL Authentication

When the Veeam Backup for Microsoft 365 Configuration Database is hosted on a remote PostgreSQL Instance, you must configure authentication within the PostgreSQL configuration to allow Veeam Backup for Microsoft 365 to access the restored Configuration Database.

Create a PostgreSQL User for Veeam Backup for Microsoft 365

Using pgAdmin, connect to the new PostgreSQL instance.
Open the Query Tool.
^{Right-click on a database and select Query Tool.}
Paste the following query (don't execute it, after pasting read the next step for details on updating it).

CREATE ROLE "vb365svc" WITH
	LOGIN
	SUPERUSER
	CREATEDB
	CREATEROLE
	INHERIT
	REPLICATION
	BYPASSRLS
	CONNECTION LIMIT -1
	PASSWORD 'pa55word';
                
            

Update the role name (vb365svc) and password (pa55word) values in the query and Execute it.

Tip: Remember which role name and password you specified, as you'll need that when reconfiguring Veeam Backup for Microsoft 365.

Note: The password must not contain the following characters:
- &
- @
- <
- >
- '
- "

Update PostgreSQL Configuration Files to Allow Authentication

Open pg_hba.conf in a text editor.
^{Note: If file exetnsions are disabled you won't see the '.conf' portion of the filename.}
- Windows default location: C:\Program Files\PostgreSQL\15\data\pg_hba.conf
- Linux conf file location will depend on the distro and the method used to install PostgreSQL.
Add the following lines to the bottom of the pg_hba.conf file:
_{This will enable access to the PostgreSQL Instance from any source and require sha-256 authentication.}

# Allow remote access using Password-based authentication.
host    all    all         0.0.0.0/0   scram-sha-256
host    all    all         ::/0        scram-sha-256
                
            

Save the pg_hba.conf file.
Restart the PostgreSQL service.

**Reconfigure Veeam Backup for Microsoft 365 and Proxies**

In this section you'll update the PostgreSQL connection settings on the Veeam Backup for Microsoft 365 machine and any associated Proxies.

Configuration Formatting

All parameters within the discussed configuration files (Config.xml and Proxy.xml) are separated by a semicolon ( ; ) symbol. Ensure that the format of the xml file is preserved and that parameters are correctly separated using that semicolon. Any malformation in the configuration file may cause the service to fail to start.

**Update Connection Settings on Veeam Backup for Microsoft 365 Machine**

On the machine where Veeam Backup for Microsoft 365 is installed, navigate to:
C:\ProgramData\Veeam\Backup365\
Make a copy of Config.xml and Proxy.xml, just in case changes need to be reverted or a misconfiguration occurs.

Update Config.xml

Open Config.xml in a text editor.
On the line starting with <ControllerPostgres, review and update each parameter as needed:
1. host= — Hostname of the new PostgreSQL machine.
2. port= — Port to connect to the PostgreSQL instance.
3. database= — Configuration Database name. (This should not have changed if you followed the steps in this guide.)
4. username= — Set the username= parameter to use the new user role you created in the previous section.
5. password= — This value should be configured as follows:
  ^{For more information on updating the password used by Veeam Backup for Microsoft 365 to connect to PostgreSQL, review KB4669.}
  - If the password= parameter is not present:
    1. Add ;password=<password> with the password in plaintext after the username parameter.
      ^{Note: Once the service is started, the plaintext password in the file will be replaced with an encrypted value.}
      Example:
```
<ControllerPostgres ControllerConnectionString="host=pgsql;port=5432;database=VeeamBackup365;username=veeam365svc;password=pa55word;maxpoolsize=100;connectionidlelifetime=10" />
```
  - If the ;password= parameter is present:
    1. Replace the encrypted password value with the new password in plaintext.
      ^{Note: Once the service is started, the plaintext password in the file will be replaced with an encrypted value.}
    2. Remove the ;PasswordEncrypted=True parameter from the end of the same line.
Using the formatting explanation from step 43, look for the line starting with <RemoteProxyDeploymentSettings, and review each parameter and update as needed.

Note: Only the host and port values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance.
Save the updated Config.xml

Update Proxy.xml

Open Proxy.xml in a text editor.
Using the formatting explanation from step 43, look for the line starting with <ProxyPostgres, review each parameter and update as needed.

Note: Only the host and port values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance.
On any line(s) starting with <PersistentCachePostgres, review and update each parameter as needed.

Note: Only the host and port values should need to be checked to make sure they are correct.
Save the updated Proxy.xml

Update Connection Settings on the Proxies

On each Veeam Backup for Microsoft 365 Proxy, navigate to:
- Windows: C:\ProgramData\Veeam\Backup365\
- Linux: /etc/veeam/backup365
Make a copy of Proxy.xml, just in case changes need to be reverted or a misconfiguration occurs.

Update Proxy.xml

Open Proxy.xml in a text editor.
On the line starting with <ProxyPostgres, review and update each parameter as needed.

Note: Only the host and port values should need to be checked to make sure they are correct. Neither the username nor password should need to be updated since the proxy user role was exported and imported into the new PostgreSQL instance.
On any line(s) starting with <PersistentCachePostgres, review and update each parameter as needed.

Note: Only the host and port values should need to be checked to make sure they are correct.
Save the updated Proxy.xml

Finalize Migration

On the primary Veeam Backup for Microsoft 365 server (aka controller) and all associated Proxies, start the Veeam Backup for Microsoft 365 services:
- Veeam Backup for Microsoft 365 Server
```
Get-Service Veeam.Archiver.Proxy | Start-Service
Get-Service Veeam.Archiver.Service | Start-Service
```
- Veeam Backup for Microsoft 365 Windows Proxy
```
Get-Service Veeam.Archiver.Proxy | Start-Service
```
- Veeam Backup for Microsoft 365 Linux Proxy
```
systemctl start Veeam.Archiver.Proxy
```

More Information

Should any issues occur during the migration, please create a Veeam Support case. To help expedite the investigation, please include a zip of the contents of C:\ProgramData\Veeam\Backup365\Logs\.

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.

How to Migrate the Configuration and Repository Cache Databases

Cheers for trusting us with the spot in your mailbox!

Oops! Something went wrong.

Purpose

Solution

Prepare for Migration

Prepare pgAdmin

Export from Source

Export the Proxy Group Role

Export the Proxy User

Export Configuration Database

Export Cache Databases

Import to Destination

Notes:

Copy Generated Files to Destination

Recreate the Proxy Group Role

Recreate the Proxy User

Recreate and Restore the Configuration Database

Recreate and Restore Cache Databases

Configure PostgreSQL Authentication

Create a PostgreSQL User for Veeam Backup for Microsoft 365

Update PostgreSQL Configuration Files to Allow Authentication

**Reconfigure Veeam Backup for Microsoft 365 and Proxies**

**Update Connection Settings on Veeam Backup for Microsoft 365 Machine**

Update Config.xml

Update Proxy.xml

Update Connection Settings on the Proxies

Update Proxy.xml

Finalize Migration

More Information

Spelling error in text

Thank you!

Oops! Something went wrong.

You have selected too large block!

KB Feedback/Suggestion

Thank you!