Upgrade to SingleStore 8.7

Backups

MemSQL 6.8 and earlier backups cannot be restored in SingleStore 7.8 or later.

If you need to keep older backups for an extended period of time, consider implementing one of the following recommendations:

1. Maintain a 7.5 or earlier installation in a test or pre-production environment to be used in case you ever need to restore 6.8 and earlier backups.

2. Upgrade the backups by restoring them into a 7.0 to 7.5 test or pre-production environment, then backing up the data again. Validate the new backups by restoring them. After that discard the older release backups.

Plancache

Plans in the plancache are dependent upon the specific SingleStore patch version, so when you upgrade to a new SingleStore version, all previously compiled plans will be invalidated. This means that any queries run against the upgraded cluster will force a one-time plan compilation, which results in slower query times the first time those queries are run. After the plans have been recompiled, they will be stored again in the plancache and query latency will return to nominal values.

Non-Sync Variables

By default, convert_nonunique_hash_to_skiplist is set to TRUE as of SingleStore 7.3. This means that any non-unique hash index will be recovered as a skiplist index, any newly created table will also have its non-unique hash indexes created as skiplists. For more information about this engine variable see the Non-Sync Variables List.

Secure Connections

As of SingleStore 8.1, OpenSSL 3.0 is now used to establish secure connections to SingleStore. As a consequence, a client certificate that uses SHA or MD5 hash functions in its signature must be replaced with a certificate that uses SHA256 at a minimum, or a secure connection to SingleStore cannot be established. While SingleStore supports TLS v1, TLS v1.1, and TLS v1.2, using TLS v1.2 is recommended. When FIPS is enabled, only TLS v1.2 is supported. Refer to Troubleshoot OpenSSL 3.0 Connections for more information.

Upgrade Versions and Methods

The tables below depict which versions of SingleStore can be upgraded to SingleStore 8.7 and the method by which the cluster can be upgraded.

• Offline upgrade: Your SingleStore cluster will be shut down and restarted over the course of the upgrade

• Online upgrade: Your SingleStore cluster will not be shut down over the course of the upgrade

Step 1: Upgrade SingleStore Toolbox

To upgrade to SingleStore 8.7, you must have Toolbox 1.15.3 or later installed prior to the SingleStore upgrade process. SingleStore recommends that you use the latest version of Toolbox when upgrading your cluster.

Run the install command to either install 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.

   Shell

   Copy

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

   Without using apt-key:

   Shell

   Copy

   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.

   Shell

   Copy

   sudo apt install singlestoredb-toolbox -y

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

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

Step 2: Upgrade SingleStore

The simplest and preferred upgrade option is an offline cluster upgrade. It is the least error-prone and easiest to perform; 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.

Select an option below to upgrade your cluster.

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

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

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

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

Collect Event Traces

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 for more information on how to fully enable this feature.

Run the following command to restart monitoring and collect event traces.

HTTP Connections

sdb-admin start-monitoring \
  --database-name metrics \
  --collect-event-traces \
  --exporter-host <exporter-hostname-or-IP-address> \
  --user root \
  --password <secure-password> \
  --retention-period 10

HTTPS Connections

sdb-admin start-monitoring \
  --database-name metrics \
  --collect-event-traces \
  --exporter-host=<exporter-hostname-or-IP-address> \
  --user root \
  --password=<secure-password> \
  --retention-period 10 \
  --ssl-ca=/path/to/ca-cert.pem      --or-- 
  --ssl-capath=/ca-directory/including/path

System Behavior

When upgrading to SingleStore 8.7, you should be aware of the following changes to system behavior or default configuration settings. The behavior of a cluster upgraded from an earlier version to SingleStore 8.7 may differ compared to a newly installed cluster on SingleStore 8.7 as described below. Most of the changes fall into two categories:

• In some versions, the default value for a configuration variable was changed compared to previous versions, but clusters upgraded from earlier versions retain their previous setting, both if it was set to a specific value or if it was not explicitly set and hence using the previous default. In some of these cases, SingleStore recommends to update your configuration to the new default if you were previously using the old default, after appropriate testing.

• Some new features are automatically enabled by default on newly installed SingleStore 8.7 clusters but not automatically enabled on clusters upgraded from an earlier version to 8.7. In some of these cases, SingleStore recommends to enable the new features, after appropriate testing.

Upgrades to 8.7

• To reduce your total cost of ownership (TCO), you may be able store data in Universal Storage instead of rowstores. This is because rowstores store their data in RAM, which can be costly. Universal Storage now supports upserts, which were previously only supported in rowstores.

• You may want to run the command REBALANCE ALL DATABASES. This command rebalances each database in the cluster, in alphabetical order of the database name. When a rebalance runs on a database d, it first considers the placement of the partitions of the other databases in the cluster before rebalancing the partitions of d.

• You may want to set the cardinality_estimation_level engine variable to '7.3'. This setting uses sampling and histograms together (when both are available) to improve selectivity estimation. The default setting is '7.1'.

• Changing the value of the data_conversion_compatibility_level engine variable can change the behavior of expressions in computed columns. Refer to the Data Type Conversion section of Data Types for more information.

• sp_query_dynamic_param should be turned off if an application breaks post-upgrade due to a change in type conversion behavior. See the Example: Changes in Type Conversion Behavior for more information.

• Upgrading the cluster, with json_extract_string_collation set to auto (default setting), changes the collation settings for JSON_EXTRACT_STRING from json to server. Refer to In-Depth Variable Definitions for information on json_extract_string_collation settings.