Step 1: Upgrade MemSQL tools

While not strictly required, it is recommended that you upgrade to the latest version of memsql-toolbox as part of your upgrade process.

The install command will either install memsql-toolbox if it is not already installed, or upgrade an existing version of memsql-toolbox to the latest version.

RHEL/CentOS

sudo yum install memsql-toolbox -y

Debian

sudo apt install memsql-toolbox -y

Upgrade without Internet access

If your cluster does not have internet access, download either the RPM or Debian memsql-toolbox package to your local machine using one of the following buttons:

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

RHEL/CentOS

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

Debian

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

Now you are ready to upgrade MemSQL.

Step 2: Upgrade MemSQL

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.

Option 1: Offline upgrade

Note: This upgrade method is referred to as an “offline” upgrade because your existing MemSQL cluster will be shut down and restarted over the course of the upgrade. You do not need to shut down your cluster prior to starting the upgrade.

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.

   memsql-deploy upgrade --precheck-only
   

2. Upgrade your cluster.

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

   memsql-deploy upgrade --version 6.8
   

If you do not specify a patch version, your cluster will be upgraded to the latest patch version of MemSQL 6.8.

Note: You cannot downgrade from your current version.

If your cluster does not have internet access, download either the RPM or Debian memsql-server package to your local machine using one of the following buttons:

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

Run the memsql-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.

RHEL/CentOS

memsql-deploy upgrade --file-path /path/to/memsql-server.rpm

Debian

memsql-deploy upgrade --file-path /path/to/memsql-server.deb

For more information on the upgrade command, see the MemSQL tools reference documentation.

Once you have finished upgrading all of your nodes, see Post-upgrade considerations for any changes between versions that may impact your cluster.

Option 2: Online upgrade

Note: This upgrade method is referred to as an “online” upgrade as your existing MemSQL 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.

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.

   memsql-deploy upgrade --precheck-only
   

2. Upgrade your cluster.

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

   memsql-deploy upgrade --online --version 6.8
   

If you do not specify a patch version, your cluster will be upgraded to the latest patch version of MemSQL 6.8.

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 memsql-server package to a location accessible by your cluster:

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

Run the memsql-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.

RHEL/CentOS

memsql-deploy upgrade --online --file-path /path/to/memsql-server.rpm

Debian

memsql-deploy upgrade --online --file-path /path/to/memsql-server.deb

For more information on the upgrade command, see the MemSQL tools reference documentation.

Once you have finished upgrading all of your nodes, see Post-upgrade considerations for any changes between versions that may impact your cluster.

For more information on the upgrade command, see the MemSQL tools reference documentation

Step 1: Upgrade MemSQL Ops

If you are upgrading from Ops 6.0 or later, you can upgrade Ops to the latest version by running the agent-upgrade command without specifying a version number.

$ memsql-ops agent-upgrade

If you are currently running MemSQL Ops 5.7 or older, you must first upgrade Ops to 5.8 before proceeding.

$ memsql-ops agent-upgrade --version 5.8.4

Once you have upgraded to Ops 5.8, you can proceed to upgrade to the latest Ops 6.7 version. You must specify a version number when upgrading from Ops 5.8 to Ops 6.0 or later. If you omit the --version flag, you will not be able to successfully upgrade your Ops agents.

$ memsql-ops agent-upgrade --version 6.7.5

Upgrade without Internet access

If your cluster does not have internet access, find the latest available MemSQL Ops version number at http://versions.memsql.com/memsql-ops/latest-v6 and use the payload URL to download it to your local machine.

Then, run the agent-upgrade command using the --file-path argument.

sudo memsql-ops agent-upgrade --file-path /path/to/memsql-ops-XYZ.tar.gz

Now you are ready to upgrade MemSQL.

Step 2: Upgrade MemSQL

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.

Option 1: Offline upgrade

Note: This upgrade method is referred to as an “offline” upgrade because your existing MemSQL cluster will be shut down and restarted over the course of the upgrade. You do not need to shut down your cluster prior to starting the upgrade.

Execute the following command to start an offline upgrade:

$ memsql-ops memsql-upgrade --version 6.8

If you do not specify a patch version, your cluster will be upgraded to the latest patch version of MemSQL 6.8.

Note: You cannot downgrade from your current version.

If your cluster does not have internet access, download the MemSQL binary from the following locations before running the memsql-upgrade command with the --file-path argument:

• For the latest version, the download link is: http://download.memsql.com/releases/latest/memsqlbin_amd64.tar.gz

• For any other version, the download link format is: http://download.memsql.com/releases/version/X.Y.Z/memsqlbin_amd64.tar.gz

$ sudo memsql-ops memsql-upgrade --file-path /path/to/memsqlbin_amd64.tar.gz

For more information on the memsql-upgrade command, see the CLI reference documentation.

Once you have finished upgrading all of your nodes, see Post-upgrade considerations for any changes between versions that may impact your cluster.

Option 2: Online 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.

In this procedure, you will upgrade individual nodes in the cluster while other nodes in the cluster are running. It is very important that you follow the upgrade sequence exactly as described in this section: leaf nodes first, then child aggregator nodes, and finally the master aggregator. Unless you require zero downtime, the offline upgrade process is simpler and less error prone.

Part 1: Prepare for upgrade

1. Log into any node and ensure your cluster is running with High Availability (Redundancy Level 2). The redundancy_level variable should be 2.

   SHOW VARIABLES LIKE 'redundancy_level';
   +------------------+-------+
   | Variable_name    | Value |
   +------------------+-------+
   | redundancy_level | 2     |
   +------------------+-------+
   

2. Ensure your cluster is healthy, and in particular ensure that all nodes are online and there is both a primary and secondary for each partition; otherwise, you will be unable to keep the cluster available throughout the upgrade procedure. Run SHOW CLUSTER STATUS to retrieve the current state of your cluster.

3. (Recommended but optional) Prior to upgrading, you may run SNAPSHOT DATABASE on any or all databases, which compacts the transaction logs, reducing database recovery time on startup.

   SNAPSHOT DATABASE database;
   

4. On the master aggregator, disable auto-attach and leaf failure detection:

   SET GLOBAL auto_attach = OFF;
   SET GLOBAL leaf_failure_detection = OFF;
   

5. Now you must disable aggregator_failure_detection. If you are upgrading from MemSQL 5.8 or earlier, the easiest way to do that is by running the memsql-upgrade-config command from any aggregator, as shown below.

   $ memsql-ops memsql-list -q -r aggregator master | xargs -L 1 memsql-ops memsql-update-config --key aggregator_failure_detection --value off --set-global
   

   If you are upgrading from MemSQL 6.0 or later, the aggregator_failure_detection variable is a sync variable, so any changes are propagated across the cluster and do not require running the memsql-upgrade-config command. Disable detection by setting the aggregator_failure_detection to OFF on the master aggregator.

   SET GLOBAL aggregator_failure_detection = OFF;
   

Part 2: Upgrade leaf nodes

Assume we have the following cluster configuration, with 8 leaf nodes in running in high availability mode (i.e. redundancy_level set to 2):

The cluster has two availability groups:

• Leaves L1 - L4 are in Availability Group 1
• Leaves L5 - L8 are in Availability Group 2

There are four pairs of leaf nodes:

• L1 and L5
• L2 and L6
• L3 and L7
• L4 and L8

The simplest way to upgrade the leaf nodes is to upgrade all leaves in Availability Group 1, then all leaves in Availability Group 2. The simple instructions for this method are below, and more complex instructions for alternative options are discussed later in the section Upgrading leaf nodes in parallel.

Upgrade all leaves in Availability Group 1 by following these steps for each leaf node. You can upgrade them all at the same time, which is fastest, but you can also upgrade one or a few at a time if desired.

1. Run SHOW LEAVES to list the host IP and port values for your leaves.

2. Copy the IP address for a leaf in Availability Group 1, and if a port other than the default port (i.e. 3306) is used, copy the port number as well.

3. Run DETACH LEAF from the Master Aggregator to detach the leaf from the cluster using the IP address and optional port value from the previous step.

   memsql> DETACH LEAF 'host'[:port];
   

4. List out all of the nodes running MemSQL with memsql-list. Then, select the detached leaf and copy its ID from the output.

   $ memsql-ops memsql-list
   

5. Stop MemSQL on the leaf node.

   $ memsql-ops memsql-stop MEMSQL_ID
   

6. Upgrade the leaf using the memsql-upgrade command. This process will upgrade the node and restart it automatically. Specifying a version number is optional.

   $ memsql-ops memsql-upgrade --skip-snapshot --memsql-id MEMSQL_ID --no-prompt [--version VERSION]
   

   Wait for the MemSQL node to start and recover. You can check whether it is recovering by running SHOW DATABASES EXTENDED; and seeing if any row has State = 'recovering'.

7. Re-attach the leaf back to the cluster by running ATTACH LEAF ... NO REBALANCE from the Master Aggregator.

   ATTACH LEAF 'host'[:port] NO REBALANCE;
   

   Wait for the attach to complete and the leaf to move to the online status. This may take some time. All leaf nodes must be attached and online before proceeding with the upgrade procedure, i.e. the next RESTORE REDUNDANCY or REBALANCE PARTITIONS command.

8. Perform steps one through seven for the rest of the leaf nodes in Availability Group 1. As an alterative workflow, you can also detach all leaves, upgrade MemSQL on all of the nodes, and then re-attach the leaves as separate steps, if you wish.

9. Run RESTORE REDUNDANCY on every database.

   RESTORE REDUNDANCY ON database;
   

10. Perform the same steps for all of the leaf nodes in Availability Group 2.

11. Run RESTORE REDUNDANCY on every database after all leaves are re-attached.

    RESTORE REDUNDANCY ON database;
    

12. After you have finished upgrading all the nodes in Availability Groups 1 and 2, run REBALANCE PARTITIONS on every database.

    REBALANCE PARTITIONS ON database;
    

Part 3: Upgrade child aggregator nodes

1. List out all of the nodes running MemSQL with memsql-list. Then, select the child aggregator you want to upgrade and copy its ID from the output.

   $ memsql-ops memsql-list
   

2. Stop MemSQL on the child aggregator.

   $ memsql-ops memsql-stop MEMSQL_ID
   

3. Upgrade the node using the memsql-upgrade command. This process will upgrade it and restart it automatically. Specifying a version number is optional.

   $ memsql-ops memsql-upgrade --skip-snapshot --memsql-id MEMSQL_ID --no-prompt [--version VERSION]
   

Wait for the MemSQL node to start and recover. You can check whether it is recovering by running SHOW DATABASES EXTENDED; and seeing if any row has State = 'recovering'.

You may upgrade child aggregators in parallel as desired. Keep enough aggregators online at any given time to continue running client queries smoothly.

Part 4: Upgrade the master aggregator node

1. List out all of the nodes running MemSQL with memsql-list. Then, select the master aggregator and copy its ID from the output.

   $ memsql-ops memsql-list
   

2. Stop MemSQL on the master aggregator.

   $ memsql-ops memsql-stop MEMSQL_ID
   

3. Upgrade the node using the memsql-upgrade command. This process will upgrade it and restart it automatically. Specifying a version number is optional.

   $ memsql-ops memsql-upgrade --skip-snapshot --memsql-id MEMSQL_ID --no-prompt [--version VERSION]
   

Wait for the MemSQL node to start and recover. You can check whether it is recovering by running SHOW DATABASES EXTENDED; and seeing if any row has State = 'recovering'.

Part 5: Re-enable auto cluster operations

Restore the auto-cluster operations settings to their initial state.

1. On the master aggregator, re-enable auto-attach and leaf failure detection:

   SET GLOBAL auto_attach = ON;
   SET GLOBAL leaf_failure_detection = ON;
   SET GLOBAL aggregator_failure_detection = ON;
   

Upgrading leaf nodes in parallel

To keep the cluster online, at least one leaf in each leaf pair must be online at any given time, so you must upgrade the two nodes in a leaf pair at different times. But upgrading nodes in different leaf pairs may be done in parallel.

The simplest and generally fastest procedure to achieve this is to upgrade all the leaves in one availability group, then the other availability group, as described above. But you can also upgrade leaf nodes in a different order - you do not have to upgrade all nodes in one availability group before the other - as long as you ensure at least one leaf node in each pair is online at all times.

You may split all leaf nodes into multiple groups of leaf nodes, and upgrade group 1, then group 2, and so on, as long as the two leaves in each leaf pair are in different groups. Run RESTORE REDUNDANCY on every database in after each group of upgrades, and run REBALANCE PARTITIONS on every database at the end.