SonarQube Database 설치 가이드

원문: Installing the database

1. 개요

SonarQube Server를 운영 환경에 설치할 때는 내장형 H2 데이터베이스 대신 외부 데이터베이스를 사용하는 것이 권장됩니다.

운영 환경에서는 특히 SonarQube 서버 호스트와 데이터베이스 호스트를 물리적으로 분리하고, 두 시스템 간 지연 시간이 낮도록 구성하는 것이 좋습니다. 

지원되는 외부 데이터베이스는 PostgreSQL, Microsoft SQL Server, Oracle입니다. 데이터베이스별 지원 버전과 필수 설정이 다르므로, 사용하는 엔진에 맞춰 사전 준비를 해야 합니다. 

2. 지원 데이터베이스

Microsoft SQL Server는 Express Edition도 지원하며, Windows 인증과 SQL Server 인증 모두 사용할 수 있습니다.

Oracle은 thin mode만 지원하고, ojdbc14.jar는 지원되지 않으며, MAX_STRING_SIZE=STANDARD만 허용됩니다.

또한 Oracle 데이터베이스는 반드시 UTF-8 계열 문자셋으로 구성되어야 합니다. Source

3. 운영 환경에서 H2를 피해야 하는 이유

SonarQube Server에는 내장형 H2 데이터베이스가 포함되어 있지만, 이는 운영 환경용으로는 권장되지 않습니다.

H2는 설치가 가볍기 때문에 개발/테스트, 프로토타이핑, CI/CD 파이프라인 검증, 또는 평가용 설치에는 유용할 수 있습니다. 

하지만 운영 환경에서는 H2가 적합하지 않습니다. 이유는 다음과 같습니다.

• 대규모 트랜잭션과 동시 접속 처리 한계
• 메모리/파일 모드에서의 데이터 안정성 부족
• 동시성 문제로 인한 성능 저하 및 데드락 가능성
• 복제, 고가용성, 고급 보안, 백업 기능 부족
• 실제 운영용 DBMS와 SQL 동작 차이 가능성

즉, 운영 환경에서는 PostgreSQL, Oracle, MS SQL 중 하나를 사용해야 안정성과 확장성을 확보할 수 있습니다.

4. 공통 설치 절차

SonarQube용 데이터베이스를 준비할 때는 아래 순서로 진행하면 됩니다.

4.1 빈 스키마 준비

SonarQube가 테이블과 객체를 생성할 수 있도록 비어 있는 스키마를 새로 만들거나 기존 빈 스키마를 사용합니다. 

4.2 전용 사용자 생성

sonarqube 전용 사용자를 만들고, 해당 사용자에게 그 스키마에서 create, update, delete 권한을 부여합니다. 운영 환경에서는 SonarQube 전용 계정을 별도로 두는 것이 관리와 보안 측면에서 유리합니다. 

4.3 DB 엔진별 추가 설정

이후에는 사용 중인 DBMS가 PostgreSQL인지, MS SQL Server인지, Oracle인지에 따라 추가 구성을 진행합니다. 아래 섹션에서 각각의 필수 조건을 정리했습니다. 

5. Microsoft SQL Server 설치 가이드

5.1 필수 조건

MS SQL Server를 사용할 경우, SonarQube 데이터베이스의 Collation은 반드시 대소문자 구분(CS) + 악센트 구분(AS) 이어야 합니다.

또한 데이터베이스에서 READ_COMMITTED_SNAPSHOT 옵션이 반드시 활성화되어 있어야 합니다.

이 설정은 높은 부하 상황에서 SonarQube가 공유 락 전략 때문에 겪을 수 있는 데드락 문제를 줄이는 데 중요합니다. 

5.2 READ_COMMITTED_SNAPSHOT 확인

아래 쿼리로 현재 설정 여부를 확인할 수 있습니다.

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

5.3 READ_COMMITTED_SNAPSHOT 활성화

필요 시 다음 쿼리로 활성화합니다.

ALTER DATABASE YourSonarQubeDatabase 
SET READ_COMMITTED_SNAPSHOT ON 
WITH ROLLBACK IMMEDIATE;

이 설정은 SonarQube의 런타임 안정성을 높이기 위한 필수 항목입니다. Source

5.4 암호화 관련 설정

MS SQL Server가 암호화를 지원하지 않는 경우, JDBC URL에 다음 옵션을 추가해야 합니다.

encrypt=false

반대로, SQL Server가 암호화를 요구하지만 인증서를 SonarQube가 검증하지 않도록 하려면, JDBC URL에 아래 옵션을 추가합니다.

trustServerCertificate=true


즉, 실제 SQL Server의 TLS/암호화 정책에 맞게 JDBC 연결 문자열을 조정해야 합니다. Source

5.5 Windows 통합 인증 사용 시

Windows 통합 인증을 사용하려면 다음 작업이 필요합니다.

1. Microsoft SQL JDBC Auth 13.4.0 패키지를 다운로드합니다.
2. mssql-jdbc_auth-13.4.0.x64.dll 파일을 SonarQube 서버 호스트의 PATH 환경 변수에 포함된 폴더로 복사합니다.
3. SonarQube를 Windows 서비스로 실행한다면, 해당 서비스 계정이 SQL Server에 접속할 권한을 가져야 합니다. Source

6. Oracle 설치 가이드

Oracle 사용 시에는 몇 가지 제약이 있습니다.

SonarQube는 thin mode만 지원하며, OCI는 지원되지 않습니다. 또한 ojdbc14.jar는 사용할 수 없고, MAX_STRING_SIZE=STANDARD만 허용됩니다.

문자셋은 반드시 UTF8 계열이어야 합니다. Oracle JDBC 드라이버는 최신 버전 사용이 권장되며, 특히 12.1.0.1 및 12.1.0.2 버전은 주요 버그가 있어 권장되지 않습니다. 

추가로, 동일한 Oracle 인스턴스 안에 SonarQube 스키마가 2개 이상 존재하고, 특히 서로 다른 SonarQube 버전용 스키마가 함께 있을 경우 SonarQube가 잘못된 스키마를 선택할 수 있습니다.

이를 피하려면 다음 중 하나를 고려해야 합니다.

• SonarQube Oracle 사용자에게 부여한 권한을 더 제한적으로 조정
• Oracle 측에서 세션 연결 시 자동으로 현재 스키마를 변경하는 트리거 구성

문서에는 세션 스키마를 명시적으로 설정하는 예시로 아래 구문이 제시됩니다.

ALTER SESSION SET current_schema="MY_SONARQUBE_SCHEMA"

운영 중 여러 SonarQube 인스턴스나 스키마를 함께 운용하는 경우 특히 주의가 필요합니다. Source

7. PostgreSQL 설치 가이드

PostgreSQL은 SonarQube에서 많이 사용하는 선택지 중 하나이며, 인스턴스는 반드시 UTF-8 문자셋을 사용하도록 구성되어야 합니다. SonarSource 문서에는 psql 기준 예시 명령이 제공되어 있습니다. Source

7.1 사용자 및 데이터베이스 생성 예시

postgres=# CREATE USER mySonarUser WITH ENCRYPTED PASSWORD 'myPassword';
CREATE ROLE

postgres=# CREATE DATABASE sonarqube WITH OWNER mySonarUser ENCODING 'UTF8';
CREATE DATABASE

이 경우 JDBC URL 예시는 다음과 같습니다.

jdbc:postgresql://<HOSTNAME>/sonarqube

즉, SonarQube 전용 사용자와 UTF8 데이터베이스를 만든 뒤, 해당 데이터베이스를 JDBC URL로 연결하면 됩니다. Source

7.2 public이 아닌 별도 스키마를 사용할 때

기본 public 스키마 대신 별도 스키마를 사용하려면 데이터베이스에 접속한 뒤 추가 작업이 필요합니다.

postgres=# \c sonarqube;
psql (17.4, server 15.12 (Homebrew))
You are now connected to database "sonarqube" as user "postgres".

sonarqube=# CREATE SCHEMA mySonarQubeSchema;
CREATE SCHEMA

sonarqube=# GRANT ALL ON SCHEMA mySonarQubeSchema TO mySonarUser;
GRANT

sonarqube=# ALTER USER mySonarUser SET search_path TO mySonarQubeSchema;
ALTER ROLE

이 경우 JDBC URL은 아래처럼 바뀝니다.

jdbc:postgresql://<HOSTNAME>/sonarqube?currentSchema=mySonarQubeSchema

즉, SonarQube가 특정 커스텀 스키마를 사용하게 하려면 스키마 생성, 권한 부여, search_path 설정, 그리고 JDBC URL에 currentSchema 지정까지 함께 적용해야 합니다. Source

8. 실무용 권장 체크리스트

아래 항목을 기준으로 점검하면 설치 실수를 줄일 수 있습니다.

이 체크리스트는 SonarQube 설치 전에 DBA와 함께 검토하면 좋습니다. Source