# Perform an Upgrade

Upgrades include either upgrading the Operator, or upgrading the SingleStore YAML configuration files.

As new versions of the Kubernetes API are released, some of these object manifests will need to be updated to match the updates to the Kubernetes API. When upgrading the Kubernetes version and the Operator, SingleStore recommends updating all of these object definitions to ensure that they are utilizing the proper Kubernetes API version for these objects.

SingleStore recommends using the latest [object definition files](https://docs.singlestore.com/db/v9.1/deploy/kubernetes/create-the-object-definition-files.md) when performing an upgrade and upgrading one component at a time.

## Version Compatibility

Before performing an upgrade, verify that the Operator version is compatible with the target engine version. Always upgrade the Operator before upgrading the engine.

## Operator and Engine Compatibility Matrix

| Engine Version | Minimum Operator Version | Recommended Operator Version |
| -------------- | ------------------------ | ---------------------------- |
| 9.0.x – 9.1.x  | 4.14.0                   | Latest version               |
| 8.9.x          | 3.258.0                  | Latest version               |

> **📝 Note**: SingleStore recommends always using the latest Operator version.

## Upgrade the Operator

> **📝 Note**: Please [confirm that the cluster is stable](https://docs.singlestore.com/db/v9.1/reference/singlestore-operator-reference/verify-cluster-stability.md) before performing the upgrade.

Typically, upgrading the Operator will cause the cluster to restart.

1. Edit the [sdb-operator.yaml](https://docs.singlestore.com/db/v9.1/deploy/kubernetes/create-the-object-definition-files/sdb-operator-yaml.md) file and update `spec.template.spec.containers[0].image` with a later version of Operator image.

   **Note**: When upgrading from Operator 1.2.5 or earlier, be sure to include the required `--cluster-id` field and a value to this file. Refer to the [sdb-operator.yaml](https://docs.singlestore.com/db/v9.1/deploy/kubernetes/create-the-object-definition-files/sdb-operator-yaml.md) file for additional information.

2. Apply the upgrade.
   ```shell
   kubectl apply -f sdb-operator.yaml

   ```

## Upgrade the SingleStore Engine

> **📝 Note**: To upgrade to SingleStore version 8.1 and later, you must first upgrade the Operator to version 3.40.3 or later.Please [confirm that the cluster is stable](https://docs.singlestore.com/db/v9.1/reference/singlestore-operator-reference/verify-cluster-stability.md) before performing the upgrade. Reviewing the Operator log to confirm that there are no general Operator operations in progress is recommended.

1. Edit the [sdb-cluster.yaml](https://docs.singlestore.com/db/v9.1/deploy/kubernetes/create-the-object-definition-files/sdb-cluster-yaml.md) file and replace `spec.nodeImage.repository` and `spec.nodeImage.tag` with a later version of the node image.

2. Apply the upgrade.
   ```shell
   kubectl apply -f sdb-cluster.yaml

   ```

Should an upgrade to SingleStore version 8.1 either stall or fail:

1. Update `spec.template.spec.containers[0].image` to `singlestore/operator:3.40.3-d2c54262`.

2. Delete the `leaf-ag1` StatefulSet.

> **⚠️ Warning**: It is only possible to upgrade to a later SingleStore engine image. The engine upgrade cannot be rolled back.

> **📝 Note**: Existing cluster monitoring instances can be configured to collect event traces after upgrading a cluster to SingleStore v8.5 or later. Refer to [Query History](https://docs.singlestore.com/db/v9.1/query-data/query-tuning/query-history.md) for more information on how to fully enable this feature.1) Add `--collect-event-traces` to your existing `start-monitoring-job.yaml` file.
>
>    **HTTP Connections**
>    ```yaml
>    [...]
>            command: ["sdb-admin",
>                      "start-monitoring-kube",
>                      "--user=<database-user>",
>                      "--password=<database-user-password>",
>                      "--collect-event-traces",
>                      "--exporter-host=<exporter-hostname>",
>                      "--yes"
>    		<other options…>
>                      ]
>    [...]
>
>    ```
>    **HTTPS Connections**
>    ```yaml
>    [...]
>            command: ["sdb-admin",
>                      "start-monitoring-kube",
>                      "--user=<database-user>",
>                      "--password=<database-user-password>",
>                      "--collect-event-traces",
>                      "--exporter-host=<exporter-hostname>",
>                      "--ssl-ca=/etc/memsql/extra-secret/ssl-ca",
>                      "--yes"
>    		<other options…>
>                      ]
>    [...]
>    ```
>
> 2) Restart monitoring.
>    ```shell
>    kubectl apply -f start-monitoring-job.yaml
>    ```

## Upgrade Best Practices

## Upgrade Order

1. Verify that the cluster is stable before starting the upgrade.

2. Back up all databases.

3. Upgrade the Operator to a version that is compatible with the target engine version.

4. Verify that the Operator is reconciling successfully by checking the Operator logs. Refer to [View the Operator Logs](https://docs.singlestore.com/db/v9.1/reference/singlestore-operator-reference/view-the-operator-logs.md) for more information.

5. Upgrade the engine by updating the `nodeImage` fields in the CR file and applying it.

## Rollback

* Operator: Revert `sdb-operator.yaml` to the previous image and reapply it.
* Engine: Engine downgrades are not supported. Restore from a backup if necessary. A backup can only be restored to the same engine version or a later version.

***

Modified at: June 22, 2026

Source: [/db/v9.1/reference/singlestore-operator-reference/perform-an-upgrade/](https://docs.singlestore.com/db/v9.1/reference/singlestore-operator-reference/perform-an-upgrade/)

(An index of the documentation is available at /llms.txt)