Upgrade SingleStore

Note

SingleStore betas and release candidates cannot be upgraded unless explicitly stated in the release notes.

SingleStore cannot be upgraded via tarball if it was initially installed/deployed using a package manager and vice versa.

Upgrade Paths

Here are the version requirements for upgrading SingleStore:

Upgrade to...

Version Requirements

Version 7.5 and later

Upgrading from version 7.0 and later is fully supported.

Upgrading directly from version 6.x is not supported. Upgrade from 6.x to 7.0, 7.1, or 7.3 first.

Version 7.0 - 7.3

Must upgrade from version 6.5 or later.

Online upgrade from version 7.x is fully supported.

Online upgrade from version 6.x is supported with some restrictions.

Offline upgrade is supported from version 6.5 and up.

Warning

Critical cluster operations such as an upgrade should be not interrupted.

If an SSH connection to a server is interrupted or lost during an upgrade, it can leave a cluster in a non-standard state.

Therefore, it is recommended to use terminal multiplexers such as tmux or screen to run an upgrade session. This would make upgrade (or any other operation) not dependent on the connected SSH session and allow you to reattach back to a running session.

Step 1: Upgrade SingleStore Toolbox

To upgrade your existing SingleStore cluster, SingleStore recommends upgrading Toolbox to 1.11.3 or later prior to upgrading SingleStore.

Run the install command to either install singlestoredb-toolbox if it is not already installed, or upgrade an existing version of Toolbox to the latest version of the package.

Red Hat

sudo yum install singlestoredb-toolbox -y

Debian

  1. SingleStore packages are signed to ensure integrity, so the GPG key needs to be added to this host. When done, verify that the SingleStore signing key has been added using apt-key list.

    wget -O - 'https://release.memsql.com/release-aug2018.gpg' 2>/dev/null | sudo apt-key add - && apt-key list

    Without using apt-key:

    wget -q -O - 'https://release.memsql.com/release-aug2018.gpg' | sudo tee /etc/apt/trusted.gpg.d/memsql.asc 1>/dev/null
  2. Upgrade Toolbox.

    sudo apt install singlestoredb-toolbox -y

Upgrade without Internet access

If your cluster does not have internet access, use one of the following buttons to download either the latest RPM or Debian singlestoredb-toolbox package to a location accessible by your cluster:

singlestoredb-toolbox

singletoredb-toolbox

Then, run the install command for the installed package manager and specify the path to the package.

Red Hat

sudo yum install /path/to/singlestoredb-toolbox.rpm -y

Debian

sudo apt install /path/to/singlestoredb-toolbox.deb -y

Now you are ready to upgrade SingleStore.

Step 2: Upgrade SingleStore

Note

When upgrading the cluster to SingleStore 8.1.26 and later, the exporter process may fail to start with the following message:

memsql_exporter.go:1001 failed reading ini file: open /etc/memsql/memsql_exporter.cnf: permission denied

This is due to the root user owning the memsql_exporter.cnf file whereas Toolbox commands run as the memsql user. Changing the ownership of the memsql_exporter.cnf file to the memsql:memsql user will properly configure monitoring and allow the exporter process to start.

The simplest and preferred upgrade option is an offline cluster upgrade. It is the least error-prone and easiest to execute; however, it requires downtime as all of the nodes in the cluster will be upgraded at the same time, shutting down the entire cluster for the duration of the upgrade.

If the cluster is running with High Availability, you also have the option to perform an incremental online cluster upgrade, which maintains cluster availability throughout the upgrade process. See the instructions in the online upgrade section for more details.

Prior to upgrading your cluster, it is recommended that you take a backup as a standard precautionary measure. See Back Up and Restore Data.

Option 1: Offline Upgrade

Note: Using this method to upgrade SingleStore is referred to as an offline upgrade as your SingleStore cluster will be shut down and restarted over the course of the upgrade. Do not shut down your cluster prior to starting the upgrade. If the cluster or individual nodes are offline when the upgrade is started, the upgrade will fail.

Execute the following command to start an offline upgrade.

  1. Confirm that the cluster can be upgraded. The cluster will not be upgraded when running this command.

    sdb-deploy upgrade --precheck-only
  2. Upgrade your cluster.

    Note: sdb-deploy upgrade will perform a snapshot of all databases prior to upgrade.

    sdb-deploy upgrade --version 7.8

If you do not specify a patch version, your cluster will be upgraded to the latest patch release of the SingleStore version specified. Refer to SingleStore release notes for available patch versions.

Note: You cannot downgrade from your current version.

If your cluster does not have internet access, use one of the following buttons to download either the latest RPM or Debian singlestoredb-server package to a location accessible by your cluster:

singlestoredb-server (.rpm)

singlestoredb-server (.deb)

The singlestoredb-server package contains both the SingleStore binary and the low-level management tool, memsqlctl.

Run the sdb-deploy upgrade command and reference the appropriate package in the --file-path argument. Running upgrade (as opposed to simply upgrading the package via the package manager) will perform an offline restart of all the nodes to make sure the cluster is using the new version.

Red Hat

sdb-deploy upgrade --file-path /path/to/singlestoredb-server.rpm

Debian

sdb-deploy upgrade --file-path /path/to/singlestoredb-server.deb

Refer to sdb-deploy upgrade for more information.

Option 2: Online Upgrade

This upgrade method is referred to as an online upgrade as your SingleStore cluster will not be shut down over the course of the upgrade. Nodes will be restarted in a specific sequence to ensure that DML-based workloads will still function. Do not shut down your cluster prior to starting the upgrade. If the cluster or individual nodes are offline when the upgrade is started, the upgrade will fail.

Note

An online upgrade may fail if a long-running workload that writes to the database, or a workload that manipulates SingleStore files (such as an automated backup or maintenance script), is running on the target cluster. SingleStore recommends performing an online upgrade only after these workloads have completed.

Toolbox 1.11.7 and later provide the option to retry a failed online upgrade. Should the online upgrade ultimately fail, an offline upgrade will be attempted. Note that the cluster will be shut down and restarted over the course of an offline upgrade.

Execute the following command to start an online upgrade.

  1. Confirm that the cluster can be upgraded. The cluster will not be upgraded when running this command.

    sdb-deploy upgrade --precheck-only
  2. Upgrade your cluster.

    Note: sdb-deploy upgrade will perform a snapshot of all databases prior to upgrade.

    sdb-deploy upgrade --online --version 7.8

By specifying --version, your cluster will be upgraded to the latest patch version of the SingleStore version specified. Refer to SingleStore release notes for available patch versions.

Note: You cannot downgrade from your current version.

If your cluster does not have internet access, use one of the following buttons to download either the latest RPM or Debian singlestoredb-server package to a location accessible by your cluster:

singlestoredb-server (.rpm)

singlestoredb-server (.deb)

The singlestoredb-server package contains both the SingleStore binary and the low-level management tool, memsqlctl.

Run the sdb-deploy upgrade --online command and reference the appropriate package in the --file-path argument. Running upgrade (as opposed to simply upgrading the package via the package manager) will perform an offline restart of all the nodes to make sure the cluster is using the new version.

Red Hat

sdb-deploy upgrade --online --file-path /path/to/singlestoredb-server.rpm

Debian

sdb-deploy upgrade --online --file-path /path/to/singlestoredb-server.deb

Refer to sdb-deploy upgrade for more information.

Roll Back from a Failed Upgrade

Currently, SingleStore does not support downgrading directly. Use the following steps to roll back to an earlier version of SingleStore using the backup made at the beginning of this upgrade guide.

Note that a backup created from a given version of the SingleStore engine can only be restored to the same engine version or later.

  1. Make a backup of the cluster configuration.

    sdb-deploy generate-cluster-file
  2. Delete all of the nodes in the cluster.

    sdb-admin delete-node --stop --all
  3. Use the following command to roll back to an earlier version of the SingleStore engine by removing the engine version(s) you do not want.

    For example, if upgrading to SingleStore 8.0 fails, remove 8.0.

    sdb-deploy uninstall --version 8.0
  4. Unregister all hosts in the cluster.

    sdb-toolbox-config unregister-host --all
  5. Recreate the cluster using the cluster configuration captured in the cluster file. Note that the cluster file may contain the engine version, so be sure to update the cluster file with the engine version you wish to restore.

    sdb-deploy setup-cluster --cluster-file /path/to/cluster/file
  6. Restore the cluster's data from the backup that was made earlier. Refer to Backing Up and Restoring Data for more information.

Last modified: December 6, 2023

Was this article helpful?