Post-update steps

The tasks you must perform after you update SonarQube Server. This page is for SonarQube Server 2026.5.

Post-update checklist

Here’s a list of steps to perform after the update:

• Verify the SonarScanner version, see Verifying the installed SonarScanner version for more information.
• For an Oracle database: optionally clean up the database to reclaim disk space, see Cleaning up the Oracle database for more information.
• For a PostgreSQL database: clean up the database, see Cleaning up the PostgreSQL database for more information.
• For a Microsoft SQL database with Windows authentication: verify the JDBC driver version, see Verifying the Microsoft SQL JDBC driver version for more information.
• If using an external configuration to control SonarQube Server (through a script or running as a service): update the service to point to the new installation directory, see Updating a service to point to the new installation directory for more information.
• If SonarQube Server is running as a service on Linux with SystemD, then you must configure SonarQube Server to run as a service by updating the sonarqube.service file.
• If you use the Web API, check at some point the usage of deprecated Web API endpoints and parameters: see Monitoring API deprecation.
• (Recommended) Migrate existing security hotspots to vulnerabilities before updating to SonarQube Server 2027.1 (see below).

See the sections below for more details on each step.

If some projects fail to reindex after the update, see Reindexing a single project in Reindexing.

Verifying the installed SonarScanner version

When updating SonarQube Server, you should also make sure you’re using the latest versions of the SonarScanners to take advantage of features and fixes on the scanner side. Please check the documentation pages of the scanners you use for the most recent version compatible with SonarQube Server and your build tools:

• SonarScanner for Maven: SonarScanner for Maven
• SonarScanner for Gradle: SonarScanner for Gradle
• SonarScanner for .NET: Installing the scanner
• SonarScanner for NPM: Installing the scanner
• SonarScanner for Python: SonarScanner for Python

Cleaning up the Oracle database

On Oracle, the database columns to be dropped during an update are marked as UNUSED instead of being physically removed. This is intentional: Oracle performs the operation instantly and without locking the rows.

This cleanup is optional. Unused columns are invisible to all queries and have no impact on the functionality of SonarQube Server. Run the cleanup only if you want to reclaim disk space.

To list the tables that contain unused columns, run:

SELECT table_name FROM all_unused_col_tabs;

To reclaim the disk space, choose one of the following two options.

Option 1: Drop the unused columns directly

ALTER TABLE foo DROP UNUSED COLUMNS;

This operation rewrites every row on disk and holds an exclusive lock for its entire duration. On large tables, such as ISSUES or PROJECT_MEASURES, it can take several hours and makes SonarQube Server unavailable. Plan a maintenance window accordingly.

Option 2: Rebuild the table online

For large datasets, we recommend rebuilding the table online. This keeps the database accessible during the operation:

ALTER TABLE foo MOVE ONLINE;

With MOVE ONLINE, Oracle maintains all indexes automatically. They remain USABLE, and no rebuild is required.

MOVE ONLINE is an Oracle Enterprise Edition feature and is not available on Express Edition (XE). Even with ONLINE, Oracle acquires a short lock (a few seconds) at the end of the operation to apply the final delta. The operation also requires significant temporary disk space, roughly a second copy of the table, and I/O while it runs.

Choosing between the two options

Both options free the disk space taken by the unused columns. The difference is the trade-off between downtime, temporary disk space, and the Oracle edition you run:

	Option 1: DROP UNUSED COLUMNS	Option 2: MOVE ONLINE
Downtime	Full exclusive lock for the whole duration	Almost none (brief lock at the end)
Extra disk required	No (edits in place)	Yes (needs a second copy of the table)
Oracle edition	Any edition	Enterprise Edition only (not XE)

Cleaning up the PostgreSQL database

You can fix the table and index bloating by performing vacuuming in order to reclaim unused disk space. In some specific cases, a reindex is required afterward.

Verifying the Microsoft SQL JDBC driver version

If you use Microsoft SQL Server with Windows Authentication, make sure that you’re using a supported version of the Microsoft SQL JDBC Driver package. The minimum supported version is the one mentioned on the Installing database page.

Updating a service to point to the new installation directory

If you use an external configuration, such as a script or Windows Service to control your server, you’ll need to update it to point to the new value of installation directory (<newSonarQubeHome>).

For Linux it depends how you implemented the service.

For Windows, update your service by running the following commands:

sc delete SonarQube
<newSonarQubeHome>\bin\windows-x86-64\SonarService.bat install

Migrating security hotspots to vulnerabilities

Security hotspots are being removed from SonarQube Server. Built-in rules no longer raise hotspots, and all existing hotspot findings must be migrated to vulnerabilities or code smells (in Standard Experience), which appear as security issues or maintainability issues (in MQR Mode). In SonarQube Server 2027.1, this migration will be forced automatically during the update. If your instance has a large number of hotspots, migrate them in advance to avoid a long forced migration at the 2027.1 update.

These endpoints require the Administer System permission.

Checking the current status

Call GET /api/hotspots/migration_status to see how many hotspots remain to migrate. You can call this endpoint at any time, including while a migration is running. The complete field is true when no hotspots remain.

Example response:

{
  "remainingHotspots": 31668,
  "complete": false
}

Previewing the migration

Before running the migration, use dry-run mode to see how many hotspots would be migrated per project, without making any changes.

• Endpoint: POST /api/hotspots/migrate_to_issues?dryRun=true
• Optional parameter: project, the project key. If omitted, all projects are included in the preview.

Example response:

{
  "dryRun": true,
  "projects": [
    {
      "projectKey": "my-project",
      "migrated": 7917,
      "skipped": 0
    }
  ]
}

Running the migration

• Endpoint: POST /api/hotspots/migrate_to_issues
• Optional parameter: project, the project key.

If you omit the project parameter, all projects are migrated at once. On large instances, migrate project by project to avoid long-running processes and database load spikes. If the migration is started without any key and puts the database under too heavy load, the SonarQube Server instance must be restarted to stop the migration process.

Example response:

{
  "dryRun": false,
  "projects": [
    {
      "projectKey": "my-project",
      "migrated": 7917,
      "skipped": 0
    }
  ]
}

Handling skipped hotspots

Skipped hotspots belong to rules that have not yet been migrated to a vulnerability or code smell type, most likely from a custom plugin. Update the plugin to a version that no longer produces hotspots, then re-run the migration.

Resuming an interrupted migration

The migration is idempotent. If it’s interrupted by a server failure or restart, re-run the same endpoint. Already-migrated hotspots are not reprocessed, and the migration continues from where it left off. No manual cleanup is required.