SonarQube Backup and Restore
Hardware fails, upgrades go wrong, and people make mistakes. A tested backup turns those moments into a short delay instead of a lost history. SonarQube keeps nearly everything in one database, so a good backup plan stays simple.
The Photo Album Picture
Think of your quality history as a family photo album. Keeping a copy in another house costs little and saves everything after a flood. A backup is that second copy.
Production Backup Storage ┌───────────────┐ nightly ┌─────────────────────┐ │ Database │ ──────────► │ database dump │ │ conf files │ ──────────► │ config copy │ │ plugins │ ──────────► │ plugin folder copy │ └───────────────┘ └─────────────────────┘
What to Back Up
| Item | Location | Priority |
|---|---|---|
| Database | PostgreSQL server | Essential |
| Settings file | conf/sonar.properties | Essential |
| Custom plugins | extensions/plugins | Important |
| Search index | data/es folder | Not needed |
The search index rebuilds automatically from the database, so skip that folder and save space.
Back Up the Database
PostgreSQL provides the pg_dump tool. Run it while SonarQube stays online, since PostgreSQL creates a consistent snapshot.
pg_dump -U sonar -F c -f sonarqube_2026-11-09.backup sonarqube
The flag -F c creates a compressed custom format. Add the date to each file name so older copies stay available.
Back Up Files
Copy the configuration file and the plugin folder with a normal file backup tool or a simple script.
cp conf/sonar.properties /backups/conf/ cp -r extensions/plugins /backups/plugins/
Store passwords carefully. The properties file contains database credentials, so protect the backup storage with access control.
Automate the Job
- Write the commands into a script.
- Schedule the script with cron on Linux or Task Scheduler on Windows.
- Copy the output to a different machine or cloud storage.
- Delete copies older than your retention period, such as 30 days.
Follow the 3-2-1 Habit
- Keep three copies of the data.
- Store them on two different kinds of media.
- Place one copy at a different location.
Restore Procedure
- Install the same SonarQube version that produced the backup.
- Stop SonarQube if it runs.
- Create an empty database and user.
- Load the dump into the empty database.
- Restore the settings file and plugin folder.
- Start SonarQube and watch the logs.
pg_restore -U sonar -d sonarqube --no-owner sonarqube_2026-11-09.backup
SonarQube rebuilds the search index on the first start. Large installations need several minutes for this step.
Version Matching
Restore a backup into the same SonarQube version that created it. A different version may refuse to start or may change the schema. Upgrade after the restore succeeds, following the upgrade steps.
Test Your Restore
A backup that never gets tested remains a hope. Run a restore drill every quarter on a spare server. Confirm that you can log in, see projects, and open a recent analysis. Record the time the drill takes, so everyone knows what recovery costs.
Projects You Can Export
Some editions include project export and import features that move one project between servers. Use them for migration tasks. A project export never replaces a full database backup.
Common Problems
- Backup file is empty usually means wrong credentials. Check the script output.
- Restore fails on ownership errors improve with the no-owner flag.
- Server starts but shows no projects signals a restore into the wrong database name.
A Recovery Story
A disk fails on the SonarQube server during a busy week. The team provisions a new machine, installs the matching version, and restores last night's dump. Index rebuilding takes fifteen minutes, and developers resume scanning the same afternoon. Because the backups were tested before, nobody guesses or panics. The cost of the failure stays at a few lost hours instead of years of recorded history.
Quick Recap
Back up the database and the configuration, automate the schedule, store copies off-site, and practice restoring. Confidence comes from testing.