Start Free
SonarQube Community Build | Server installation and setup | Installing database

Installing the SonarQube Community Build database

On this page

Database requirements Creating database instance Setup on MS SQL Server Setup on Oracle Setup on PostgreSQL 

Database requirements

Several external database engines are supported. 

Database engineRequirement
PostgreSQLVersion: 13 to 17
Microsoft SQL Server

Version: 

  • 2022 (MSSQL Server 16.0); 2019 (MSSQL Server 15.0); 2017 (MSSQL Server 14.0); 2016 (MSSQL Server 13.0).
  • With bundled Microsoft JDBC driver.

Notes: 

  • Express Edition is supported.
  • Windows and SQL Server authentication are both supported.
Oracle

Version: 23ai, 21C, 19C, XE Editions.

Recommendation: Use the latest Oracle JDBC driver.

Notes:

  • The driver ojdbc14.jar is not supported.
  • Only the thin mode is supported, not OCI.
  • Only MAX_STRING_SIZE=STANDARD parameter is supported, not EXTENDED.
  • Must be configured to use a UTF8-family charset (see the NLS_CHARACTERSET).
  • The Oracle JDBC driver versions 12.1.0.1 and 12.1.0.2 have major bugs, and are not recommended for use with SonarQube  (see more details).
H2

Recommendation: Use the H2 embedded database for non-production use cases:

  • Development/Testing: H2 is ideal for quick prototypes, unit or integration tests, or CI/CD pipelines due to its lightweight setup.
  • Trials: H2 allows users to try SonarQube without configuring a full database setup like PostgreSQL, Oracle, or MS SQL.

Why avoid H2 in production:

  • Scalability Limits: H2 cannot handle high transaction volumes or concurrent users.
  • Data Risks: In-memory mode risks data loss; file-based mode lacks robust durability.
  • Concurrency Issues: H2 struggles with heavy concurrent access, which could cause slowdowns or deadlocks.
  • Limited Features: H2 lacks replication, high availability, advanced security, or robust backups.
  • SQL Compatibility: H2 may differ from production databases, risking transition issues.

Use PostgreSQL, Oracle, or MS SQL for production to ensure reliability and scalability. Limit H2 to development, testing, or trials.

Creating a new database instance for SonarQube

  1. Create an empty schema for SonarQube to populate.
  2. Create a sonarqube user. Grant this sonarqube user permissions to create, update, and delete objects for this schema. 
  3. Perform the setup as described below depending on your database type.

Setup if using an MS SQL Server database

This page describes operations to be performed on your MS SQL Server instance for SonarQube.

Set collation to CS and AS

Collation MUST be case-sensitive (CS) and accent-sensitive (AS).

Enable READ_COMMITTED_SNAPSHOT

READ_COMMITTED_SNAPSHOT MUST be set on the SonarQube database.

MS SQL database's shared lock strategy may impact SonarQube Server runtime. Making sure that is_read_committed_snapshot_on is set to true will prevent SonarQube from facing potential deadlocks under heavy loads.

To check is_read_committed_snapshot_on, you may use the following query:

SELECT is_read_committed_snapshot_on FROM sys.databases WHERE name='YourSonarQubeDatabase';

To update is_read_committed_snapshot_on, you may use the following query:

ALTER DATABASE YourSonarQubeDatabase SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE;

Encryption-related setup

If your Microsoft SQL Server doesn't support encryption, you must add encrypt=false to the JDBC URL connection string.

If your Microsoft SQL Server requires encryption but you don't want SonarQube to validate the certificate, you must add trustServerCertificate=true to the JDBC URL connection string.

Using integrated security

To use integrated security:

  1. Download the Microsoft SQL JDBC Auth 12.10.0 package and copy mssql-jdbc_auth-12.10.0.x64.dll to a folder location set in the PATH environment variable on SonarQube Server host.
  2. If you're running SonarQube as a Windows service, make sure the Windows account under which the service is running has permission to connect your SQL server. 

If using an Oracle database

If there are two SonarQube schemas on the same Oracle instance, especially if they are for two different versions, SonarQube gets confused and picks the first it finds. To avoid this issue:

  • Either privileges associated to the SonarQube's Oracle user should be decreased.
  • Or a trigger should be defined on the Oracle side to automatically alter the SonarQube's Oracle user session when establishing a new connection: ALTER SESSION SET current_schema="MY_SONARQUBE_SCHEMA".

Setup if using a PostgreSQL database

Your PostgreSQL instance for SonarQube:

  • Must be configured to use UTF-8 charset.
  • If you want to use a custom schema and not the default "public" one: the PostgreSQL search_path property must be set:
ALTER USER mySonarUser SET search_path to mySonarQubeSchema

Was this page helpful?

© 2008-2025 SonarSource SA. All rights reserved.

Creative Commons License