SonarQube Server upgrade process is automated, you have nothing to manually change in the SonarQube Database.
Nevertheless, if in your migration path you have a 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.
- Read the upgrade notes below for each version
Stop the old SonarQube server
- Download and unzip the new SonarQube distribution in a fresh directory, let's say NEW_SONARQUBE_HOME.
- Start it using the default H2 database and use the update center to install the plugins you need.
- Manually install any custom plugins.
- Stop the new server.
- 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.
- If a custom JDBC driver is used, copy it into NEW_SONARQUBE_HOME/extensions/jdbc-driver/<dialect>.
- Back up your database.
- Remove the data/es directory.
Start the new 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.
Database Statistics / Indices
It is strongly recommended to refresh your database's statistics and rebuild your database's indices once the technical upgrade is done (just before the step 13).
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.
In case you used the InstallNTService.bat to install SonarQube as a Windows Service, run the OLD_SONARQUBE_HOME/bin/.../UninstallNTService.bat before running the InstallNTService.bat of the 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.