Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Administration

SonarQube Database, Backups, Housekeeping and Upgrades

Plan a production SonarQube: the database, sonar.properties, JVM memory, backups, housekeeping, and a safe upgrade path with the Long-Term Active release, plus a checklist stand-in.

A SonarQube server is three things working together: the web server (the UI and the API), the compute engine (a background worker that processes analysis reports) and search (Elasticsearch, bundled, which indexes issues and components). Everything permanent lives in the database. If you know where state lives, backups and upgrades become routine. The server itself cannot run on this site; commands here are for your own machine, and the TryIts are stand-ins.

The database

Use an external database in production. The embedded H2 database exists only for evaluation and cannot be upgraded or migrated. PostgreSQL is the database most installations use; other supported databases depend on the version and edition (SQL Server and Oracle have been supported in recent releases), so check the compatibility matrix for your version in the official documentation.

Setup outline for PostgreSQL:

  1. Create a dedicated database and user, for example sonarqube, with ownership of the schema.
  2. In conf/sonar.properties:
PROPERTIES
sonar.jdbc.username=sonarqube
sonar.jdbc.password=<from a secret store>
sonar.jdbc.url=jdbc:postgresql://db.example.com/sonarqube
  1. Use a UTF-8 database and a modern PostgreSQL release listed as supported.
  2. Keep the database close to the server (low latency); analyses write a lot of rows.

Configuration files and folders:

Path Content
conf/sonar.properties Main settings: JDBC, web port, JVM options
data/ Elasticsearch indexes; can be rebuilt from the database
extensions/plugins/ Installed plugins
logs/ sonar.log, web.log, ce.log, es.log, access.log
temp/ Scratch space

Memory is set through sonar.web.javaOpts, sonar.ce.javaOpts and sonar.search.javaOpts (for example -Xmx2G). Elasticsearch needs enough OS-level limits (vm.max_map_count, open file limits) on Linux, and the server logs a clear error at start-up if they are too low.

What to back up

  1. The database. It holds all projects, issues, history, users and settings. For PostgreSQL: pg_dump -Fc -U sonarqube sonarqube > sonarqube-2026-03-01.dump.
  2. conf/sonar.properties and any custom scripts or proxy configuration (secrets belong in a secret manager, not in the backup text).
  3. extensions/ (plugins), because the server only accepts plugins compatible with its version.

You do not need to back up data/ (Elasticsearch): after a restore, the server rebuilds the indexes from the database at start-up, which can take a while on large installations. Test the restore at least once; an untested backup is only a hope.

Restore outline: create an empty database, pg_restore the dump, deploy the same SonarQube version, restore conf and extensions, start the server, and let it reindex.

Housekeeping

Analyses accumulate history. Set retention in Administration > General Settings > Housekeeping:

  • Delete all but one analysis per day after a number of days.
  • Delete all but one analysis per week or month for older history.
  • Delete branches and pull requests inactive for a number of days (default values apply; the main branch is never deleted).
  • Delete closed issues after a number of days (default 30).

Retention keeps the database small and the UI fast. Make sure your reporting needs (trend charts) are covered before shortening it.

Monitoring

  • Administration > System shows health: web, compute engine, search status, and (when running a cluster) nodes.
  • /api/system/health and /api/system/status are good probes for load balancers (status UP). Health endpoints can require administrator rights, or a system pass code in some configurations.
  • Watch disk space (Elasticsearch stops accepting writes when the disk is almost full), CPU and the compute engine queue (Administration > Projects > Background Tasks).

Upgrades

SonarQube has two kinds of release: regular releases and Long-Term Active (LTA) releases, supported for longer and the usual target for production. The upgrade rule is: you can jump from an old release to the next LTA, then from there to the newest LTA, but you cannot skip arbitrarily across several LTAs. Read the upgrade guide for your path, and the release notes for removed features and changed defaults.

Upgrade checklist:

  1. Read the release notes, the upgrade path, and the list of compatible plugins (reinstall compatible versions or remove unused ones).
  2. Back up the database. Do this while the old server is stopped for a consistent copy.
  3. Stop the old server.
  4. Unzip (or pull) the new version into a new folder; copy your edited sonar.properties settings into the new conf/, and copy plugins.
  5. Start the new version.
  6. Open http://host:9000/setup in a browser and press Upgrade. The server migrates the schema; this can take minutes to hours on a large database.
  7. Wait for the reindex to complete, then log in and check the version on the System page and the background tasks.
  8. Update scanners and SonarQube for IDE connection; new server versions may require newer scanners.

If the migration fails, restore the backup and fix the cause. Do not run the new and old versions against the same database.

Stand-in: upgrade path checker

This stand-in checks whether a direct upgrade is allowed under a simplified model of "go to the next LTA first". It uses made-up version labels, not real release numbers, so consult the real upgrade guide for actual paths.

JS Stand-in: plan an upgrade through LTAs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: backup retention planner

A common policy is daily backups for a week, weekly for a month and monthly for a year. The block lists which dated backups to keep.

JS Stand-in: backups to keep

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Operations checklist

  • Database on a supported version, backups tested by restoring into a scratch environment.
  • Reverse proxy with TLS in front of port 9000; set the public URL (sonar.core.serverBaseURL).
  • Run as a dedicated non-root OS user, as a system service (systemd on Linux, a service wrapper on Windows).
  • Alerts on disk, memory, failing background tasks and certificate expiry.
  • A written upgrade runbook with rollback steps.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the only data store you must back up to recover projects, issues and history?

    Indexes are rebuilt from the database, which holds the permanent data.
  2. 2. Which page do you open after starting a new SonarQube version to migrate the schema?

    The /setup page starts the database migration for an upgrade.
  3. 3. Which database should you avoid in production?

    H2 is for evaluation only and cannot be upgraded.
  4. 4. What does a Long-Term Active release give you?

    LTA releases are supported longer than regular releases.

Summary

  • State lives in the database; back it up, and test the restore.
  • Configure JDBC, memory and proxy in sonar.properties; plugins live in extensions/.
  • Use housekeeping to control history size and monitor health, disk and background tasks.
  • Upgrade via the LTA path: back up, replace, open /setup, wait for reindex.

Next: Web API and automation