Skip to end of metadata
Go to start of metadata

Table of Contents

SonarQube Server upgrade process is automated, you have nothing to manually change in the SonarQube Database.
Nevertheless, if in your migration path you have an LTS version, you must first migrate to this LTS and then migrate to your expected version.

Example 1 : 4.2 -> 5.3, migration path is 4.2 -> LTS -> 5.3
Example 2 : 5.1 -> 5.4, migration path is 5.1 -> 5.4

How to Upgrade

Please backup your database before upgrading

It is very important that you backup your database (step #9 in the guideline below) in case anything unexpected happens during the migration.


  1. Read the upgrade notes below for each version
  2. Stop the old SonarQube server

  3. Download and unzip the new SonarQube distribution in a fresh directory, let's say NEW_SONARQUBE_HOME.
  4. Start it using the default H2 database and use the update center to install the plugins you need.
  5. Manually install any custom plugins.
  6. Stop the new server.
  7. Update the content of the and wrapper.conf files located in the NEW_SONARQUBE_HOME/conf directory with the content of the related files in the OLD_SONARQUBE_HOME/conf directory (web server URL, database settings, etc.). Do not copy-paste the old files.
  8. If a custom JDBC driver is used, copy it into NEW_SONARQUBE_HOME/extensions/jdbc-driver/<dialect>.
  9. (warning) Back up your database.
  10. (warning) Remove the data/es directory.
  11. Start the new web server

  12. Browse to http://localhost:9000/setup (replace "localhost:9000" by your own URL) and follow the setup instructions.
  13. Analyze your projects to get fresh measures.



If you use external configuration, such as a script or Windows Service to control your server, you'll need to update it to point to NEW_SONARQUBE_HOME.


The time to complete an upgrade will vary based on the size of the projects portfolio.

From 5.0 forward, upgrade time can be significantly impacted by the recreation of the Elasticsearch indices, which could take one or more hours, again depending on the size of the projects portfolio.

You can monitor the progress of both the database upgrade and the ES index creation by watching the server log: NEW_SONARQUBE_HOME/logs/sonar.log

An upgrade is complete when an analysis has been run on a project. Only then will you see the new functionality.

How to Roll Back

If, for some reasons, your upgrade failed, you can roll back by:

  1. Restoring your backed up database
  2. Updating the OLD_SONARQUBE_HOME/conf/ configuration file to link to the restored database
  3. Restarting the previous version of the web server

Release Upgrade Notes

Usually the SonarQube releases come with some specific recommendations for upgrading from the previous version. You have to read the upgrade notes for all versions between your current version and the target version.

  • No labels