# Performing the upgrade

Now that you have determined your upgrade path and tested your upgrade, you can perform your upgrade.

## Before you start <a href="#before-you-start" id="before-you-start"></a>

Consider the following before starting your upgrade:

* SonarQube releases come with some specific recommendations for upgrading from the previous version. You should read the [release-upgrade-notes](https://docs.sonarsource.com/sonarqube-server/10.4/setup-and-upgrade/release-upgrade-notes "mention") for each version between your current version and the target version.
* Database disk usage recommendations: During your upgrade, tables may be duplicated to speed up the migration process. This could cause your database disk usage to temporarily increase to as much as double the normal usage. Because of this, we recommend that your database disk usage is below 50% before starting a migration.

## Upgrading a ZIP file instance <a href="#zip-instance" id="zip-instance"></a>

Before you upgrade, make sure you know how to [installing-sonarqube-from-zip-file](https://docs.sonarsource.com/sonarqube-server/10.4/setup-and-upgrade/install-the-server/installing-sonarqube-from-zip-file "mention") from the ZIP file and check that your environment [prerequisites-and-overview](https://docs.sonarsource.com/sonarqube-server/10.4/requirements/prerequisites-and-overview "mention") of the version you’re upgrading to.

To upgrade from the ZIP file:

1. Download and unzip the SonarQube distribution of your edition in a fresh directory, let’s say `<newSonarqubeHome>`.
2. If you’re using third-party plugins, Manually install plugins that are compatible with your version of SonarQube. Use the [plugin-version-matrix](https://docs.sonarsource.com/sonarqube-server/10.4/instance-administration/plugin-version-matrix "mention") to ensure that the versions you install are compatible with your server version. Simply copying plugins from the old server to the new is not recommended; incompatible or duplicate plugins could cause startup errors. Analysis of all languages provided by your edition is available by default without plugins.
3. Update the contents of `sonar.properties` file (in `<newSonarqubeHome>/conf`) with the settings in the `<oldSonarqubeHome>/conf` directory (web server URL, database, ldap settings, etc.). Do not copy-paste the old files. If you are using the Oracle DB, copy its JDBC driver into `<newSonarqubeHome>/extensions/jdbc-driver/oracle`.
4. Stop your old SonarQube Server.
5. Start your new SonarQube Server.
6. Browse to `http://yourSonarQubeServerURL/setup` and follow the setup instructions.
7. Reanalyze your projects to get fresh data.

## Upgrading a Docker image instance <a href="#docker-instance" id="docker-instance"></a>

{% hint style="info" %}

* If you’re upgrading with an Oracle database or you’re using plugins, you can reuse your extensions volume from the previous version to avoid moving plugins or drivers. Use the [Broken link](https://docs.sonarsource.com/sonarqube-server/10.4/setup-and-upgrade/upgrade-the-server/broken-reference "mention") to ensure that your plugins are compatible with your version. Analysis of all languages provided by your edition is available by default without plugins.
* If upgrading from 8.9.x LTS to 9.9.x LTS: Please note that the `lts` tag on Docker images is replaced with every new LTS release. If you want to avoid an automatic major upgrade, we recommend using the corresponding `9.9-<edition>` tag instead of relying on the `lts-<edition>` tag.
* Unless you intend to delete the database and start new when running your image, be careful not to use `-v` to `docker-compose down` and, be careful when running commands like `docker system prune` or `docker volume prune`; regardless if you use an `external: true` parameter, your database volumes will not persist beyond the initial startup and shutdown of SonarQube.
  {% endhint %}

To upgrade SonarQube using the Docker image:

1. Stop and remove the existing SonarQube container (a restart from the UI is not enough as the environment variables are only evaluated during the first run, not during a restart):

```css-79elbk
$ docker stop <container_id>
$ docker rm <container_id>
```

2\. Run Docker.

```css-79elbk
$> docker run -d --name sonarqube \
    -p 9000:9000 \
    -e SONAR_JDBC_URL=... \
    -e SONAR_JDBC_USERNAME=... \
    -e SONAR_JDBC_PASSWORD=... \
    -v sonarqube_data:/opt/sonarqube/data \
    -v sonarqube_extensions:/opt/sonarqube/extensions \
    -v sonarqube_logs:/opt/sonarqube/logs \
    <image_name>
```

3\. Go to `http://yourSonarQubeServerURL/setup` and follow the setup instructions.

4\. Reanalyze your projects to get fresh data.

## Upgrading a Helm chart instance <a href="#helm-chart-instance" id="helm-chart-instance"></a>

{% hint style="info" %}
If you’re upgrading with an Oracle database or you’re using plugins, you can reuse your extensions PVC from the previous version to avoid moving plugins or drivers. Use the [plugin-version-matrix](https://docs.sonarsource.com/sonarqube-server/10.4/instance-administration/plugin-version-matrix "mention") to ensure that your plugins are compatible with your version. Analysis of all languages provided by your edition is available by default without plugins.
{% endhint %}

{% hint style="warning" %}
Please verify that any custom configurations or custom `values.yaml` files contain *only parameters that are still compatible with the targeted chart*, and adjust them if needed. Some default parameters may have changed between versions of the chart.
{% endhint %}

<details>

<summary>Standard procedure</summary>

1. Change the SonarQube version on your `values.yaml`.
2. Redeploy SonarQube with the same helm chart:

```css-79elbk
helm upgrade --install -f values.yaml -n <your namespace> <your release name> <path to sonarqube helm chart>
```

3\. If you’re upgrading a Data Center Edition: after SonarQube search pods are running and ready, only one application (app) replica will be running and ready. You can confirm that it’s because of the ongoing upgrade by inspecting the logs of the pod for this text: `The database must be manually upgraded. Please backup the database and browse /setup`.

4\. Go to `http://yourSonarQubeServerURL/setup` and follow the setup instructions.

5\. Reanalyze your projects to get fresh data.

</details>

<details>

<summary>If upgrading from 8.9.x LTS to 9.9.x LTS</summary>

**Upgrade from 8.9.x LTS to 9.9.x LTS**

To install SonarQube 9.9 LTS, use the [sonarqube](https://artifacthub.io/packages/helm/sonarqube/sonarqube) Helm chart. The [sonarqube-lts](https://artifacthub.io/packages/helm/sonarqube/sonarqube-lts) Helm chart is no longer maintained and cannot be used to install the new LTS.

* For SonarQube 9.9 LTS Community, Developer, and Enterprise Editions, the [Helm chart ](https://artifacthub.io/packages/helm/sonarqube/sonarqube)version to use is `8.x.x` . See [`sonarqube` ArtifactHub](https://artifacthub.io/packages/helm/sonarqube/sonarqube#installing-the-sonarqube-9-9-lts-chart) for more information.
* For SonarQube 9.9 LTS Data Center Edition, the [Helm chart ](https://artifacthub.io/packages/helm/sonarqube/sonarqube)version to use is `7.x.x` . See [`sonarqube-dce` ArtifactHub](https://artifacthub.io/packages/helm/sonarqube/sonarqube-dce#installing-the-sonarqube-9-9-lts-chart) for more information.

As SonarQube only requires to persist the database, the general upgrade process will consist of uninstalling your instance before installing the new LTS.

If you are using an external database, you don’t have any persistent data inside kubernetes. Therefore, there is no action required.

Instead, if you rely on the embedded PostgreSQL chart (**not recommended**), uninstalling the chart will keep the PVC alive. The PVC can then be reused either:

* by specifying `postgresql.existingClaim` in the `values.yaml` file
* by not changing parameter values, but making sure you install the new chart in the same namespace (auto-generated name will be the same).

</details>

## Upgrading from a ZIP file instance to a Docker instance <a href="#from-zip-to-docker" id="from-zip-to-docker"></a>

To migrate from the ZIP file to Docker:

1. Configure your Docker instance to point to your existing database.
2. Shut down your ZIP instance.
3. Start your Docker instance.