Migrating to an external database

  • Last updated: May 17, 2022

  • Read time: 3 Minutes

During the initial installation of Burp Suite Enterprise Edition, you can choose whether to use the bundled database or an external database. If you choose to use the bundled database, you can migrate to an external one at any time.

The migration process involves the following phases.

Installing the database transfer tool


If your first ever version of Burp Suite Enterprise Edition was 2020.1-2902 or later, you can skip this section and go straight to preparing for the migration.

For most users, the database transfer tool will automatically be 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 will need to install this tool manually.

From a command prompt, navigate to your Burp Suite Enterprise Edition installation directory. Then, 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_DIR} ${DATA_DIR}/data


  • ${VERSION} is the version number of your current Burp Suite Enterprise Edition installation, for example, 2020.6.
  • ${INSTALLATION_DIR} is the directory where Burp Suite Enterprise Edition is installed.
  • ${DATA_DIR} is the directory where your Burp Suite Enterprise Edition data is stored. You specified this directory during the installation process.

For example, 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

Preparing for migration

  1. Perform the required setup for your new external database. Keep a note of the credentials that you create for the external database.
  2. Stop all scans.
  3. On scanning machines, stop the burpsuiteenterpriseedition_agent services.
  4. Perform a backup of the bundled database. This can be done from the Burp Suite Enterprise Edition web UI in the database backup settings.
  5. On the Enterprise server machine, stop the burpsuiteenterpriseedition_enterpriseserver and burpsuiteenterpriseedition_webserver services.
  6. Create a copy of the enterprise-server.config file in case it is necessary to revert to using the original database.

Prerequisite steps for Oracle databases

When migrating to an Oracle database, there are some additional steps that you need to perform 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-number>/lib/ojdbc8.jar <installation-directory>/enterpriseServer/<version-number>/lib/ojdbc8.jar
  3. Create the following empty files. These are just marker files to make sure the drivers are installed as part of any future updates:

    <installation-directory>/enterpriseServer/.oracle <installation-directory>/webServer/.oracle
  4. Make sure 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 another empty marker file in the following location:

  3. As with the files you created on the main machine, make sure the permissions for the marker file match the other files in the directory.

Once you have performed these steps on all of your machines, you can proceed with rest of the migration process.

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.
  4. Provide the JDBC URL and credentials for the new external database.
  5. Data will be transferred table by table and progress is reported in the console.
  6. Once the migration has completed, a summary of the rows transferred per table is reported and the enterprise-server.config file will have been updated with the new database connection details.

Restarting 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.