SonarQube Database Configuration
The database is the long-term memory of SonarQube. Every project, rule setting, user, issue, and history point lives there. A reliable database setup protects years of quality data and keeps the dashboard responsive as your team grows.
The Filing Cabinet Picture
The SonarQube application acts as the office clerk, and the database acts as the filing cabinet. The clerk can change, but the cabinet must stay safe, organized, and large enough for new folders.
┌──────────────────┐ JDBC connection ┌──────────────────────┐ │ SonarQube Server │ ──────────────────► │ PostgreSQL Database │ │ (Compute Engine, │ ◄────────────────── │ schema: sonarqube │ │ Web Server) │ results │ user: sonar │ └──────────────────┘ └──────────────────────┘
Embedded Database vs Production Database
A fresh installation uses an embedded H2 database so beginners can start with zero setup. This database suits learning only. It lacks support for upgrades, performs poorly under load, and risks data loss during crashes. Production servers need an external database.
Choosing a Database
PostgreSQL is the most common choice and the easiest path for new installations. Sonar publishes a compatibility matrix that lists supported database types and versions for each release. Check that page before you install, because support changes between versions.
Prepare PostgreSQL
- Install a supported PostgreSQL version on a separate server or container.
- Create a dedicated user for SonarQube.
- Create an empty database with UTF-8 encoding.
- Grant the user full rights on that database.
CREATE USER sonar WITH ENCRYPTED PASSWORD 'change_this_password'; CREATE DATABASE sonarqube OWNER sonar ENCODING 'UTF8';
Use a strong, unique password. Avoid sharing this account with other applications.
Connect SonarQube
Open conf/sonar.properties inside the SonarQube folder and set three values.
sonar.jdbc.username=sonar sonar.jdbc.password=change_this_password sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube
Replace localhost with the database server address if it runs elsewhere. Add a port number after the address when you use a non-standard port.
First Start Behavior
SonarQube connects, finds the database empty, and creates all tables automatically. The first startup takes longer than later ones. The log shows progress messages, and the web page becomes available when setup completes.
Connection Pool Settings
SonarQube keeps a pool of open connections for speed. The defaults suit most teams. Large installations adjust two properties.
| Property | Purpose |
|---|---|
| sonar.jdbc.maxActive | Maximum simultaneous connections |
| sonar.jdbc.minIdle | Connections kept ready |
| sonar.jdbc.maxWait | Time to wait for a free connection |
Raise the maximum only after you confirm that the database server can handle extra load.
Network and Location
- Place the database close to the application server to keep delays low.
- Restrict database access to the SonarQube server address.
- Use encrypted connections when traffic crosses untrusted networks.
Care and Feeding
Regular Backups
Schedule automatic backups and test restores on a spare machine. The Backup and Restore topic explains the details.
Maintenance
PostgreSQL benefits from routine vacuum and statistics updates. Autovacuum handles this task in most setups.
Disk Space
History grows with every analysis. Housekeeping settings under Administration remove old snapshots automatically, which keeps the size predictable.
Troubleshooting
- Connection refused means the database is down or the address is wrong.
- Password authentication failed means the property values differ from the database user.
- Wrong encoding errors appear when the database was created without UTF-8.
- Slow pages often point to an overloaded database server or slow disk.
Sizing Guidance
Small teams run happily on a modest database server with a few gigabytes of memory. Growth shows up as more projects, more branches, and longer history. Watch the database size every month and plan disk space ahead of need. Add memory to the database server when dashboard queries slow down at busy hours. Planning early costs less than rescuing a full disk during a busy release week.
Security Basics
Store the database password only in the configuration file with strict file permissions. Rotate it on a schedule, and restart SonarQube after each change. Disable remote access for the database administrator account.
Quick Recap
Use PostgreSQL for real work, create a dedicated user and UTF-8 database, set three properties, and protect the server with backups. A healthy database keeps SonarQube fast and trustworthy.