On this page
This is a generic guide for upgrading across versions of SonarQube. Carefully read the release upgrade notes of your target version and of any intermediate version(s).
Before upgrading, we recommend practicing your upgrade on a staging environment that's as similar to your production environment as possible. For more on this and other important upgrading concepts, read through the Before you upgrade page.
Before upgrading, back up your SonarQube database. Upgrade problems are rare, but you'll want the backup if anything does happen.
Database disk usage recommendations
During your upgrade, tables may be duplicated to speed up the migration process. This could cause your database disk usage to temporarily increase to as much as double the normal usage. Because of this, we recommend that your database disk usage is below 50% before starting a migration.
You can upgrade your SonarQube instance using the ZIP file, Docker image, or Helm Chart. To expand the upgrading instructions, click the option below that corresponds to your setup.
If your upgrade requires the rebuild of Elasticsearch indexes, your projects and applications will become available as they are reindexed. Portfolios won't be available until all projects are indexed.
Reverting to the previous version
If you need to revert to the previous version of SonarQube, the high-level rollback procedure for all deployments is as follows:
- Shutdown your SonarQube instance or cluster.
- Roll back your database to the backup you took before starting the upgrade.
- Switch back to the previous version of your SonarQube installation.
- Start your SonarQube instance or cluster.
Changing your edition
You can move to a different SonarQube edition (for example, moving from Community Edition to a commercial edition) while you're upgrading your version. Just use the appropriate edition file or Docker image tag in the upgrade instructions above.
If you want to move to a different edition without upgrading your SonarQube version, the steps are exactly the same as in the upgrading instructions above without needing to navigate to
http://yourSonarQubeServerURL/setup or reanalyze your projects.
Migrating from a ZIP file instance to a Docker instance
To migrate from the ZIP file to Docker:
- Configure your Docker instance to point to your existing database.
- Shut down your ZIP instance.
- Start your Docker instance.
Additional steps and information
Once you’ve finished a technical upgrade, you should rebuild database indexes and refresh database statistics before starting SonarQube and reanalyzing your projects.
There's an additional step you may want to perform if you're using Oracle. On Oracle, the database columns to be dropped are now marked as UNUSED and are not physically dropped anymore. To reclaim disk space, Oracle administrators must drop these unused columns manually. The SQL request is
ALTER TABLE foo DROP UNUSED COLUMNS. The relevant tables are listed in the system table
For PostgreSQL, that means executing three operations:
REINDEX DATABASE <db>
According to the PostgreSQL documentation:
When upgrading SonarQube, you should also make sure you’re using the latest versions of the SonarQube scanners to take advantage of features and fixes on the scanner side. Please check the documentation pages of the scanners you use for the most recent version compatible with SonarQube and your build tools.
See also this section for what might change after a software update.
SonarQube as Linux or Windows service
If you use an external configuration, such as a script or Windows Service to control your server, you'll need to update it to point to
- For Linux it depends how you implemented the service
- For Windows you can update your service by running:
If your upgrade requires the rebuild of Elasticsearch indexes, your projects and Applications will become available as they are reindexed. Portfolios won't be available until all projects are indexed.
Release upgrade notes
Usually, SonarQube releases come with some specific recommendations for upgrading from the previous version. You should read the upgrade notes for each version between your current version and the target version.
© 2008-2023, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.