TL;DR overview
- The SonarQube LTS upgrade checklist provides a step-by-step framework for administrators planning a major version upgrade, covering pre-upgrade validation, database backup, plugin compatibility review, and post-upgrade verification.
- Key pre-upgrade steps include reviewing deprecated APIs, checking plugin compatibility matrices, verifying database engine support, and confirming that the SonarQube for IDE version in use supports the target server version.
- The checklist recommends upgrading in a staging environment first and validating analysis results for a representative set of projects before migrating production instances.
- Teams upgrading between non-consecutive LTS versions (such as from 8.9 to 2025.1) must follow a multi-hop path, upgrading to intermediate supported versions in sequence to ensure database migrations complete correctly.
The wait is over! The latest and greatest long-term support (LTS) version of SonarQube Server is available. You can learn about all the new features and enhancements on the announcement page.
As a SonarQube Server 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 Server Downloads page. You should always choose the latest release of SonarQube Server 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 Server 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 Server 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 Server. 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 Server 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 Server 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 Server features are coming.
- Update Scanners: Your scanner clients should be updated to the latest versions to ensure compatibility with all of the features SonarQube Server 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 Server, where you can make adjustments to guide your developers in writing Code Quality.
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 Server LTS.