Upgrading Your SonarQube

Upgrading a SonarQube instance requires careful planning and preparation to ensure a smooth transition with minimal disruption. Before beginning any upgrade process, administrators should understand the version release cycle, plan their migration path carefully, and review relevant documentation. SonarQube follows a structured release schedule with Long-Term Support (LTS) versions released approximately every 18 months, complemented by incremental latest versions released every 2-3 months. Understanding this cadence helps organizations make informed decisions about which version to target and when to perform upgrades.

Pre-Upgrade Preparation

The first critical step is deciding on a target version. SonarQube recommends maintaining at least the latest LTS version to stay current with product features and bug fixes. A grace period of six months follows each LTS release, after which older versions no longer receive support. Organizations should also map out their migration path by identifying all intermediate LTS releases between their current and target versions. For example, upgrading from version 7.9 LTS to 9.9 LTS requires an intermediate upgrade to 8.9 LTS first, ensuring database schemas are applied in the correct order. Additionally, administrators should review release notes, check scanner and build wrapper version compatibility, and practice the upgrade process on staging licenses before deploying to production. For Enterprise and Data Center editions with third-party plugins, compatibility verification using the plugin version matrix is essential.

Performing the Upgrade

The actual upgrade process depends on how SonarQube is deployed. For Docker deployments, administrators need to stop and remove the existing container, then run a new container pointing to the target image version. Organizations using Helm charts only need to update the SonarQube version in their values.yaml file and redeploy. For manual zip file upgrades, administrators must download the target version, extract it to a fresh directory, and carefully migrate the sonar.properties file—copying the old file directly is not recommended since configuration options may have changed. Regardless of deployment method, the SonarQube startup process may require several minutes as the application applies database schema migrations.

Post-Upgrade Steps

Once the upgraded SonarQube instance is running, administrators must navigate to the setup page at the sonarQube URL and complete database migration instructions specific to their database system. It is recommended to trigger analysis of all projects again to ensure updated data reflects any new rules or features introduced in the target version. Finally, administrators should rebuild database indices to refresh database statistics following the documentation guidelines for their chosen database platform. These post-upgrade steps ensure the instance operates at optimal performance with accurate code quality data.

Key Takeaways

• Plan your migration path carefully by upgrading through each intermediate LTS version between your current and target versions to ensure proper database schema application
• Review release notes, plugin compatibility matrices, and test upgrades on staging licenses before production deployment
• Choose between upgrading to LTS versions for stability or latest versions for incremental features, but always maintain at least the current LTS for support
• Follow deployment-specific upgrade procedures (Docker, Helm, or zip file) and properly migrate configuration settings rather than copying old files directly
• Complete post-upgrade tasks including database migration setup, project re-analysis, and database index rebuilding to ensure optimal performance