Migrating to an external database

  • Last updated: September 14, 2023

  • Read time: 3 Minutes

If you are using Burp Suite Enterprise Edition's bundled H2 database, you can migrate to an external one at any time.

The migration process involves the following phases:

  1. Preparing for the migration
  2. Migrating your data
  3. Restarting the Burp Suite Enterprise Edition services


The database_transfer tool only migrates data from Burp Suite Enterprise Edition's embedded H2 database to a supported external database. It cannot migrate data from one external database to another.

For a list of supported external databases, see System requirements for your external database.

Preparing for the migration

  1. Set up your new database. Keep a note of the credentials that you create.
  2. Stop all scans.
  3. On each scanning machine, stop the burpsuiteenterpriseedition_agent services.
  4. Perform a backup of the bundled database. You can do this from the Burp Suite Enterprise Edition web UI in the database backup settings.
  5. On the Enterprise server, stop the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
  6. Create a copy of the enterprise-server.config file, in case you need to revert to using the original database.

Prerequisite steps for Oracle databases

To migrate to an Oracle database, you need to perform some additional steps before you begin transferring your data.

On the machine on which you installed the Enterprise server and web server:

  1. Download the required driver (ojdbc8.jar) from the Oracle website.

  2. Copy the downloaded file to both of the following locations:

    <installation-directory>/databaseServer/<version>/lib/ojdbc8.jar <installation-directory>/enterpriseServer/<version>/lib/ojdbc8.jar
  3. To make sure that the drivers are installed as part of any future updates, create the following empty marker files:

    <installation-directory>/enterpriseServer/.oracle <installation-directory>/webServer/.oracle
  4. Make sure that the ownership and permissions of the newly created files match those of the other files in their respective directories. This should mean that the files are readable by all users.

If you've already deployed any external scanning machines, you also need to perform the following steps on each machine:

  1. Install the driver by adding the downloaded ojdbc8.jar file to the following location:

  2. Create an empty marker file in the following location:

  3. Make sure that the permissions for the marker file match the other files in the directory.

When these steps are complete on all of your machines, you can proceed with the rest of the migration process.

Prerequisite steps for PostgreSQL databases

To migrate to a PostgreSQL database, you need to temporarily assign superuser access to Burp Suite. This enables Burp to disable foreign key constraints that will otherwise prevent it importing data.

Assign the superuser role to burp_enterprise by running:

alter user burp_enterprise with superuser;

When you've completed the migration, revoke this permission by running:

alter user burp_enterprise with nosuperuser;

Migrating your data

  1. Restart your database server.
  2. On the Enterprise server machine, open a command prompt.
  3. From the installation directory, run database_transfer as either the burpsuite user or root. If you don't have the database_transfer tool, see Running the database transfer command manually.
  4. Provide the JDBC URL and credentials for the new external database.

Data is transferred table by table and progress is reported in the console. Once the migration is complete, a summary of the rows transferred per table is reported. The enterprise-server.config file is updated with the new database connection details.

Running the database transfer command manually

For most users, the database_transfer tool is automatically installed as part of the main Burp Suite Enterprise Edition installation process. However, if your first ever version of Burp Suite Enterprise Edition was 2020.1-2902 or earlier, you need to run the database transfer command manually:

  1. From a command prompt, navigate to your Burp Suite Enterprise Edition installation directory.
  2. Enter the following command, replacing the variables with the appropriate values:
sudo ./jre/bin/java -cp "databaseServer/<version>/lib/*" net.portswigger.enterprise.database.transfer.DatabaseTransferMain <installation-directory> <data-directory>/data


  • <version> is the version number of your current Burp Suite Enterprise Edition installation, for example, 2020.6.
  • <installation-directory> is the directory where Burp Suite Enterprise Edition is installed.
  • <data-directory> is the directory where your Burp Suite Enterprise Edition data is stored. You specified this directory during the installation process.

The resulting command would look something like this:

cd /opt/burpsuite_enterprise/ sudo ./jre/bin/java -cp "databaseServer/2020.6/lib/*" net.portswigger.enterprise.database.transfer.DatabaseTransferMain /opt/burpsuite_enterprise/ /var/lib/BurpSuiteEnterpriseEdition/data

Restarting the Burp Suite Enterprise Edition services

  1. On the Enterprise server machine, restart the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
  2. On each of your scanning machines, restart the burpsuiteenterpriseedition_agent services.

Was this article helpful?