How to Seamlessly Upgrade SonarQube from V7 to V10.7 for JDK8‑JDK21 Support

Background

Java has progressed to JDK 21, but the internal SonarQube V7 platform and its Ali‑P3C plugin could not analyze code compiled with newer JDKs, limiting quality monitoring. Upgrading to SonarQube V10.7 was chosen because it supports Java 8‑24, offers better performance, newer rule sets, and a richer plugin ecosystem.

Upgrade Value

Static analysis covers JDK 8‑24.

Improved scanning speed and accuracy.

All internal services (JDK 8‑21) become scan‑able, reducing hidden production risk.

Upgrade Challenges

Large version gap (V7 → V10) requires multi‑step migration.

Complex data migration (projects, quality gates, permissions).

Plugin and API compatibility risks.

Code‑scan jobs must remain uninterrupted.

Upgrade Strategy

Adopt an incremental path V7 → V8 → V9 → V10, testing each intermediate version in isolation, backing up all data, and preparing rollback mechanisms. Perform production upgrades on weekends.

Technical Implementation

Version Requirements

V8: SonarQube and SonarScanner require JDK 11+.

V9: Require JDK 17+.

V10: Require JDK 17+.

From V8 onward, SonarSource recommends the auto‑JRE bundled SonarScanner to avoid JDK mismatches.

Pre‑Upgrade Checklist

Backup PostgreSQL database and SonarQube configuration.

Download and verify compatibility of third‑party plugins.

General Upgrade Steps

# Backup DB
pg_dump -U sonar sonarqube > sonarqube_v7_backup_$(date +%Y%m%d).sql
# Backup config
cp -r /opt/sonarqube/conf /opt/sonarqube/conf_backup
# Backup data dir
tar -czf sonarqube_data_backup.tar.gz /opt/sonarqube/data

# Stop old service
systemctl stop sonarqube
# Download & unzip new version
wget https://binaries.sonarsource.com/Distribution/sonarqube/sonarqube-10.7.zip
unzip sonarqube-10.7.zip -d /your_path/
# Migrate config
cp /your_path/sonarqube-7/conf/sonar.properties /your_path/sonarqube-10/conf/
# Adjust system limits (vm.max_map_count >= 524288, fs.file-max >= 131072)
# Start new version
/your_path/sonarqube-10/bin/linux-x86-64/sonar.sh start
# Run DB migration via web UI

Key Points per Version

V7 → V8 : Upgrade PostgreSQL to 11, ensure plugins have V8‑compatible versions, run on JDK 11.

V8 → V9 : Switch to JDK 17, redesign Quality Gates, adapt to API changes.

V9 → V10 : Continue on JDK 17+, configure built‑in GitLab OAuth, migrate user authentication.

Verification Checklist

Service starts and reports correct version.

All projects appear with complete data.

Run a full scan on a small project.

Validate API endpoints.

Confirm plugin compatibility and use a SonarScanner matching the server JDK.

Verify JDK 21 code can be scanned.

Issues and Solutions

Multiple JDK Services

Scanning JDK 8 code with a JDK 17 scanner caused class‑not‑found errors.

Solution: Separate build and scan JDKs. Build JDK 8 projects with JDK 8, but invoke the SonarScanner with JDK 17 and pass the JDK 8 tools.jar via -Djdk.tools.jar.

if [ "$JDK_VERSION" = "JDK1.8" ]; then
  BUILD_CMD="mvn package -Dmaven.test.skip=true -Dmaven.compiler.source=1.8 -Dmaven.compiler.target=1.8"
  SONAR_JAVA_HOME="/opt/soft/jdk/jdk17"
  TOOLS_JAR="$JDK8_HOME/lib/tools.jar"
  SONAR_ADDITIONAL_PARAMS="-Djdk.tools.jar=$TOOLS_JAR"
elif [ "$JDK_VERSION" = "JDK17" ]; then
  BUILD_CMD="JAVA_HOME=/opt/soft/jdk/jdk17 mvn package -Dmaven.test.skip=true"
  SONAR_JAVA_HOME="/opt/soft/jdk/jdk17"
  SONAR_ADDITIONAL_PARAMS=""
elif [ "$JDK_VERSION" = "JDK21" ]; then
  BUILD_CMD="JAVA_HOME=/opt/soft/jdk/jdk21 mvn package -Dmaven.test.skip=true"
  SONAR_JAVA_HOME="/opt/soft/jdk/jdk21"
  SONAR_ADDITIONAL_PARAMS=""
else
  echo "Unsupported JDK version: $JDK_VERSION"
  exit 1
fi

SONAR_CMD="JAVA_HOME=$SONAR_JAVA_HOME mvn $SONAR_PARAMS $SONAR_ADDITIONAL_PARAMS"

User Login Problem

Legacy GitHub‑based login plugin used in V7 was incompatible with V10, which now provides built‑in GitLab OAuth.

Solution: Use SonarQube’s delegated authentication. After SSO validates the user, inject user info into HTTP headers; SonarQube reads the headers for authentication. Update the database to change historic user source tags from GITLAB to SONARQUBE to avoid mismatches.

Reference Branch Feature

V10 introduced “Reference Branch”, allowing incremental scans against a baseline branch without custom GitDiff logic.

Ali‑P3C Plugin Compatibility

The original Ali‑P3C plugin stopped at PMD‑V6 and could not parse JDK 21 code.

Solutions evaluated:

Adopt the community sonar-pmd-plugin, which supports P3C rules and silently handles JDK 21.

Fork PMD‑V7 and develop a custom P3C plugin (deferred due to higher effort).

Results

Successful migration from SonarQube V7.9.6 to V10.7.

100% data migration accuracy; 3,961 projects retained.

Static analysis now covers JDK 8‑JDK 21 services.

Login, JDK compatibility, and plugin issues resolved.

Reduced hidden production risk for JDK 21 projects.

Key Takeaways

Assess version differences and known issues before upgrading.

Use a phased upgrade path (V7→V8→V9→V10) with isolated testing.

Back up all data layers and prepare rapid rollback procedures.

Validate core functionalities (login, scanning, quality gates) in a staging environment.

Future Outlook

Phase out P3C rules in favor of Sonar’s native rules and FindBugs.

Research and adopt scanners for Kotlin, Python, C++, etc., leveraging SonarQube’s plugin ecosystem.

These practices provide a reusable blueprint for large‑scale system migrations, emphasizing data safety, incremental testing, and comprehensive validation.

Reference links:

Upgrade guide: https://docs.sonarsource.com/sonarqube-server/10.7/server-upgrade-and-maintenance/upgrade/upgrade-the-server/determine-path
Auto‑JRE scanner: https://docs.sonarsource.com/sonarqube-server/10.7/analyzing-source-code/scanners/scanner-environment/general-requirements
GitLab auth plugin: https://github.com/SonarSource/sonar-auth-github
Reference branch docs: https://docs.sonarsource.com/sonarqube-server/9.8/project-administration/defining-new-code
P3C plugin: https://github.com/wuweiit/sonar-pmd-p3c