SonarQube Upgrade process is automated, and below 5.2 you can upgrade from any version to any version. But starting from SonarQube 5.2, the migration scripts are only available from the nearest LTS.
That means that if you want to move from an version prior to SonarQube 4.5 to 5.2, 5.3, 5.x, you must first migrate to at least SonarQube 4.5.x LTS.
- If you are running SonarQube 3.7 LTS, your migration path will be: 3.7 > 4.5.x > 5.2 (with x>0)
- If you are running SonarQube 4.2, your migration path will be: 4.2 > 4.5.x > 5.2 (with x>0)
- If you are running SonarQube 4.5, your migration path will be: 4.5 > 4.5.x > 5.2 (with x>0)
- If you are running SonarQube 4.5.x, your migration path will be: 4.5.x > 5.2 (with x>0)
- If you are running SonarQube 5.0, your migration path will be: 5.0 > 5.2
How to Upgrade
It is very important that you backup your database (step #7 in the guideline below) in case anything unexpected happens during the migration.
- Read the upgrade notes below for each version
Stop the SonarQube server
- Download and unzip the new SonarQube distribution in a fresh directory, let's say NEW_SONARQUBE_HOME.
- Update the content of the sonar.properties 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.
- Copy the OLD_SONARQUBE_HOME/extensions/plugins directory into NEW_SONARQUBE_HOME/extensions/plugins.
Check the Compatibility Matrix for plugins compatibility and manually upgrade the plugins if necessary: .
- If a custom JDBC driver is used, copy it into NEW_SONARQUBE_HOME/extensions/jdbc-driver/<dialect>.
- Back up your database.
- If an es directory exists under data, remove the es directory (such a directory should not exist if step 3, above, was followed).
Start the web server
- Browse to http://localhost:9000/setup (replace "localhost:9000" by your own URL) and follow the setup instructions.
- 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:
- Restoring your backed up database
- Updating the OLD_SONARQUBE_HOME/conf/sonar.properties configuration file to link to the restored database
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.