TL;DR overview
- This guide walks SonarQube Server administrators through upgrading to the 8.9 LTS from earlier versions, covering prerequisite checks, database migration steps, and plugin compatibility verification.
- Key upgrade considerations include reviewing deprecated APIs, ensuring database engine compatibility (PostgreSQL, Oracle, or SQL Server), and updating any custom plugins to versions that support 8.9.
- The guide recommends a staged approach—upgrading in a non-production environment first, running the migration wizard, and validating analysis results before rolling out to production.
- For teams still on 8.9 LTS, the recommended next upgrade path is to 9.9 LTS and then to the 2025.1 LTA, following the documented multi-hop upgrade checklist.
The new Long-Term Support (LTS) version of SonarQube Server is here! If you haven’t already, check out the version 8.9 announcement page to learn about all of the new features and improvements. If you are the administrator of a large deployment of SonarQube Server, you’ll have a lot of developers excited to get their hands on the new functionality. This guide provides tips and recommendations to help minimize downtime and remove surprises during your upgrade.
To get started, reference the following resources to prepare for your upgrade:
- The Upgrade Guide provides the technical steps to follow during the upgrade process
- The LTS Upgrade release notes highlight functional changes that you should be aware of when moving between LTS versions
- Get the latest LTS version from the Download page. Always choose the latest version of SonarQube Server LTS as it will contain critical bug and security fixes. Pre-LTS versions will no longer receive these updates.
Practice First!
To avoid disrupting your production environment, use a backup of your production database to set up a separate instance of your current version of SonarQube Server. Use this staging environment to test the upgrade, observing the time it takes to back up/restore systems and complete the process. Your staging environment should have identical specs to your production system - or as similar as possible to ensure you get an accurate picture.
If you are planning on introducing any changes to your SonarQube Server installation while migrating to the new LTS, e.g.
- Changing your authentication provider
- Upgrading server specs or OS version
- Database software upgrade or change
- Migrating to a cloud provider
You should make sure all these changes are applied in this staging environment first, so you can detect any potential problems.
While you do not need a license to test the upgrade of a commercial edition of SonarQube Server in a separate environment, installing one allows you to run test scans to validate that everything is running as expected. If you have a support contract, you are entitled to licenses for testing purposes. Contact your Sales representative to obtain a staging license.
Tune for Performance
A SonarQube Server upgrade temporarily requires additional resources which will be released upon completion. If you observe that your upgrade trial runs are running longer than expected:
- The upgrade process consumes database resources (i.e. CPU, RAM, disk space) beyond what is used during normal operation and poorly tuned databases may significantly extend the time required to perform the upgrade. Consult with your database administrator to ensure the database is prepared and adjust based on your observations during trial upgrades. Reference the “Additional Information” section of the Upgrade Guide for tips applicable to your specific DBMS.
- Review and Update your memory settings can help speed the upgrade process. Adding additional resources to SonarQube Server’s Web and Search processes can help improve performance.
- Make sure you have reasonable settings configured for your housekeeping parameters. You may have increased or modified your housekeeping parameters in the past. You should ensure these settings do not result in SonarQube Server storing closed issues, analysis snapshots and stale branches long past their value to developers. We recommend following default settings. Note that subsequent cleanup will not occur until after an analysis, so changes would need to happen prior to upgrade in your current production system.
Refresh Integrations
While you’re upgrading your SonarQube Server, take the time to make sure supporting software is up to date so your users can take advantage of the latest improvements.
Ensure that you have the latest version of the analysis scanners installed in your CI environment.
- If you are using the scanner for Maven or Gradle, the version you are using may be fixed in your pom.xml or build.gradle file. Update these or notify Project owners that they should modify to use the latest version.
- If you are using the scanner for Jenkins, in addition to updating the plugin itself, modify the Global Tool Configuration to add the newest versions of the SonarScanner and/or SonarScanner for MSBuild.
We’ve added and improved our integrations with many code repository platforms and CI tools. Check out the “ALM Integration” section of the SonarQube Server documentation to see what’s new and how to take advantage of these.
If you are using third-party plugins, review them to make sure they are still providing value and will not cause problems after your upgrade. When evaluating, consider:
- Is this plugin compatible with the new version? The plugin compatibility matrix is a great resource for this.
- Is my organization still using this functionality? Many plugins may have been installed but never used or restricted to a small number of Projects
- Does this plugin provide functionality that is not provided by SonarQube Server out of the box? We’ve added a lot of great integrations and rules to our language analyzers. Consider using SonarQube Server-native features to ensure the best compatibility.
If the answer to any of the above is "no", consider removing these plugins from your installation.
Finally, if you are using the Web API for reporting and/or automation, review the release notes as some functions have been changed and deprecated APIs may have been removed.
We’re Here to Help
Keeping your SonarQube Server instance up to date helps your developers stay on the road to cleaner and safer code. The new functionality in the SonarQube Server 8 series makes a difference in code quality and code security all along dev teams’ workflow. Rehearsing your upgrade and preparing your instance for peak performance will make sure this journey continues smoothly. You’re in this with the entire SonarQube Server community, who’s openly sharing best-practices and helping each other on our Community Forum. Feel free to join us there! And if you have a commercial support contract with SonarSource, do not hesitate to engage with us, we will be happy to guide you in getting maximum value from this new SonarQube Server LTS.