Blog post

SonarQube LTS Upgrade Checklist

Brian Cipollone photo

Brian Cipollone

Sales Engineer

5 min read

  • SonarQube
  • Clean as You Code
  • Clean Code
  • SonarLint

The wait is over! The latest and greatest long-term support (LTS) version of SonarQube is available.  You can learn about all the new features and enhancements on the announcement page.

As a SonarQube administrator, you are probably thinking about how to upgrade your organization's instance to this version. This checklist will help ensure you've covered all the bases for a smooth upgrade.

Before You Start

There are a few resources to review and items to evaluate in your instance before you begin:


  • Read the upgrade guides:  The "Before You Upgrade" and "Upgrade guide" documentation will provide you with an overview and general technical steps you'll be doing during the upgrade.
  • Review the release notes: We've collected all of the critical functional changes from the last several months of updates in one place.  Ensure you carefully review, as requirements (e.g., Node.js and Java versions) may have changed for your SonarQube server or the supporting software. A more detailed list is available as well.
  • Review your plugins:  If you use third-party plugins, review them to ensure they still provide value and will not cause problems after your upgrade. If your instance has incompatible plugins (see the plugin compatibility matrix) or plugins that are no longer in use, you should remove them from your installation before your upgrade.
  • Review API usage:  If you use the Web API for reporting or automation, review the release notes as some functions have been changed, deprecated, or removed.
  • Download the LTS:  You can find the download for the LTS on the SonarQube Downloads page.  You should always choose the latest release of SonarQube LTS, as it contains important security and bug fixes that older versions will no longer receive.


Upgrade Test

The following steps will help you set up a testing environment that you can use to practice your upgrade:


  • Copy production database: Any SonarQube upgrade will alter the database. You should back up your current production database and restore it to an environment where you can practice the upgrade process. It's a good idea to take note of the duration of the backup and restore to help with your production upgrade timeline.
  • Setup your test environment: Your test environment should have specs as close as possible to the production environment so you can get a good idea of how long the upgrade will take. Start with the same version of SonarQube that you are using in production.  If you plan on introducing other changes to your production environment during the upgrade process, try them out in your test environment.  For example, changing your authentication provider or migrating to a cloud environment can increase the steps needed to get your new system up and running.
  • Request a test license: A license is not required to start and upgrade a commercial edition of SonarQube. However, installing one allows you to run analyses to validate that everything is running as expected. If you are running Enterprise Edition or have a support contract, you are entitled to licenses for testing purposes. Contact your Sales Representative to obtain a test license and apply to the test environment before proceeding.
  • Run the test: Now that your test environment is running, you're ready to perform the upgrade. In addition to rehearsing your process, keep notes on how long the process takes to complete.
  • Performance tuning: If you'd like to decrease the time needed to execute the upgrade, you can make some adjustments to improve performance. An excellent place to start is your database. The upgrade process temporarily consumes database resources beyond what you see during day-to-day SonarQube operation, and poorly tuned databases often create issues during upgrades.  Reference the "Additional database maintenance" section of the Upgrade Guide for tips applicable to your specific DBMS.   If you are running the Enterprise or Data Center Edition, temporarily increasing the number of Compute Engine workers can also speed up the upgrade process.  See the Compute Engine performance documentation for more information.
  • Execute test scans: It's a good practice to perform a few analyses with key projects against your test environment to ensure everything is running as expected.  All SonarQube releases feature new rules, improved detection, and bug fixes that enhance results from previous versions. Therefore, expect new findings to be discovered in scans after the upgrade.


During the Upgrade


  • Notify Your Users: Make sure your developers know about the upgrade and what to expect. In addition to setting expectations, this is a great way to inform users that new SonarQube features are coming. 
  • Update Scanners: Your scanner clients should be updated to the latest versions to ensure compatibility with all of the features SonarQube offers. You can find download links on the documentation page for each scanner we provide
  • Run the Upgrade: You've prepared and run your test; now it's time to execute. Remember to take one final backup of your production database.


After the Upgrade


  • Review Your Quality Gates: We've added recommendations to help your organization follow "Clean as You Code" practices.  You can find these alongside your Quality Gates in SonarQube, where you can make adjustments to guide your developers in writing Clean Code


Need Help?


If you need assistance during your upgrade process, the Sonar community is here to help. We've created a dedicated space where you can find solutions to your LTS upgrade questions. And if you have a commercial support contract with SonarSource, we will be happy to assist you in getting maximum value from this new SonarQube LTS.