SonarQube Upgrading

New releases bring faster analysis, fresh rules, security fixes, and support for newer language versions. Upgrading feels risky when a team depends on the server daily. A calm, repeatable process removes the stress and keeps surprises small.

The Moving Day Picture

Moving to a new house goes smoothly when you pack carefully, keep valuables safe, and unpack in order. An upgrade follows the same plan: prepare, protect, move, and verify.

 Plan ──► Back up ──► Stop ──► Install new ──► Migrate DB ──► Verify
  │          │         │           │               │            │
 notes    database   server     copy settings   /setup page   scans work

Know Your Release Types

Sonar publishes regular releases and Long-Term Active releases, often shortened to LTA. An LTA release receives fixes for a longer period, so many companies stay on LTA versions and upgrade from one LTA to the next. Pick the track that matches your tolerance for change.

Preparation Checklist

  1. Read the upgrade notes and release notes for the target version.
  2. Check that your Java version meets the new requirement.
  3. Check that your database version stays supported.
  4. Verify plugin compatibility. Remove or update plugins that lack support.
  5. Announce a maintenance window to your teams.

Back Up Everything

Create a database dump and copy the conf and extensions folders. Never upgrade without a restore point. The Backup and Restore topic covers the commands.

Upgrade a Standard Installation

  1. Stop the running SonarQube service.
  2. Unzip the new version into a fresh folder next to the old one.
  3. Copy your settings from the old conf/sonar.properties into the new file. Do not overwrite the new file with the old one.
  4. Copy custom plugins that remain compatible into the new extensions/plugins folder.
  5. Point the service or startup script to the new folder.
  6. Start SonarQube.
  7. Open http://your-server:9000/setup in a browser.
  8. Click the migration button and wait for the progress to finish.

The migration updates the database structure. Large databases need more time, so avoid closing the page or stopping the server during the process.

Upgrade a Docker Installation

  1. Back up the database and the volumes.
  2. Change the image tag in your compose file to the new version.
  3. Run docker compose pull and docker compose up -d.
  4. Open the /setup page and start the migration.

Keep the same volumes so plugins and settings carry over.

Verify After the Upgrade

  • Log in and check the version number in the page footer.
  • Open the Background Tasks page and confirm that no tasks failed.
  • Run a scan on a small project.
  • Check that quality gates and profiles still show the expected values.
  • Update scanners on build machines to a compatible version.

Expect Rule Changes

Newer versions add rules and refine old ones. A project may show new issues after an upgrade even though the code stayed the same. Quality profiles in the built-in Sonar way profile update automatically. Custom profiles keep their rule choices, so activate new rules manually when you want them.

Rolling Back

Database migrations do not reverse. A rollback means restoring the backup into the old version. This fact makes the backup step essential and the pre-upgrade test on a copy valuable.

Test on a Copy First

Restore last night's backup on a spare server, run the upgrade there, and record any warnings. The rehearsal shows the migration time and catches plugin problems before they affect real users.

Common Problems

  • Server will not start often traces back to an old plugin. Check the log for plugin names.
  • Setup page shows no migration button means the database already matches the version.
  • Scans fail after the upgrade usually point to outdated scanners.

Quick Recap

Read the notes, back up, install beside the old version, migrate through the setup page, and verify with a test scan. A rehearsal on a copy makes the real upgrade boring, which is the best outcome.

Previous lesson
Back to course
Next lesson