---

This topic describes how to upgrade MemSQL to 6.5. These steps can be used to upgrade from 5.8 to 6.5.x (e.g. 6.5.27). Also, any prior 6.5 beta releases can be upgraded to a supported GA release (6.5.9 or later) using the upgrade steps below.

It is recommended that you upgrade to the latest patch version of MemSQL 6.5.

Prior to upgrading

Taking a backup is recommended as a standard precautionary measure. See Backing Up and Restoring Data.

Step 1: Verify your cluster is ready for upgrade

From the master aggregator, run the following commands:

SHOW LEAVES;
SHOW AGGREGATORS;
SHOW CLUSTER STATUS;
EXPLAIN RESTORE REDUNDANCY;
EXPLAIN REBALANCE PARTITIONS;

With the output of these commands, confirm that the following are true:

• All leaves are online

• All aggregators are online

• There are no partitions with ‘Orphan’ role

• No Rebalance or restore redundancy is necessary

Step 2: Upgrade MemSQL Ops

After you have backed up your data and verified your cluster is ready, you are ready to upgrade MemSQL Ops to the latest Ops version using the agent-upgrade command.

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.5 version.

$ memsql-ops agent-upgrade --version 6.5.11

Note: Specifying a version number is required when upgrading from Ops 5.x to Ops 6.0 or later. If you omit the --version flag, you will not be able to successfully upgrade your Ops agents.

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 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 3: 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:

$ memsql-ops memsql-upgrade [--version <VERSION>]

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

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

In this procedure, you will upgrade individual nodes in the cluster while other nodes in the cluster are running to maintain cluster availability throughout the upgrade process. 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. 

```sql
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

After all nodes have been upgraded, restore the auto-cluster operations settings to their initial state by re-enabling auto-attach and failure detection.

Connect to the master aggregator and set the following variables:

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.

Step 4: Post-upgrade considerations

When upgrading from MemSQL 5.x or 6.0 to 6.5, you should be aware of the following changes to system behavior or default configuration settings.

Upgrading from 5.x

By default, automatic statistics for columnstore tables will be disabled on existing tables created prior to the upgrade, and enabled on tables created after the upgrade. In most cases, we recommend enabling autostats on existing columnstore tables created prior to the upgrade using ALTER TABLE table_name ENABLE AUTOSTATS. See autostats support upon upgrading MemSQL.

Also, columnar_segment_rows, which is now an alias for columnstore_segment_rows in 6.0 or later, keeps the old default value of 102,400 after upgrading minimize the performance impact on any existing workloads; however, if 6.0 or later is installed from scratch, the default value will be 1,024,000. If you want to change the columnstore_segment_rows value to the new default for 6.0 or later, run the following memsql-update-config command:

$ memsql-ops memsql-update-config --all --key columnstore_segment_rows --value 1024000 --set-global

This will write the columnstore_segment_rows = 1024000 key-value pair to all memsql.cnf files in the cluster and will run SET GLOBAL columnstore_segment_rows = 1024000 on all nodes in the cluster to enable the change at runtime without restarting any nodes.

Upgrading from 6.0

When upgrading from MemSQL 6.0 to 6.5, there is a new system variable, cardinality_estimation_level, which allows you to choose whether to use newer, more advanced histograms and algorithms to perform cardinality estimation, or use the previous histogram format. The default setting on newly installed 6.5 clusters is 6.5, which uses the new histograms. The default setting on clusters upgraded from 6.0 or earlier to 6.5 is 6.0, which uses the old histograms to minimize performance impact on any existing workloads.

You can change the setting cardinality_estimation_level by running SET GLOBAL cardinality_estimation_level = '6.5' on the master aggregator. (Changes will be synchronized to the other nodes in the cluster, and restarting MemSQL nodes is not required.) After changing the setting, you should re-run ANALYZE TABLE on all previously analyzed tables to collect up-to-date statistics.

AUTO_INCREMENT behavior changes

In addition to the post-upgrade considerations mentioned above, when upgrading to MemSQL 6.5, the behavior for AUTO_INCREMENT has changed. Specifically, a reserved set of values are now managed by each aggregator, which are then encoded with the aggregator’s ID whenever the aggregator performs an insert into a table that uses AUTO_INCREMENT. This range of values jumps each time the aggregator restarts. Having each aggregator manage its own set of AUTO_INCREMENT values prevents collisions after the aggregator is restarted.

The first observable result of these changes is that after upgrading to 6.5, the start value for the next insert post-upgrade will be much higher than the last value set before the upgrade to align with the new AUTO_INCREMENT behavior. For more information on these changes, see AUTO_INCREMENT behavior in the 6.5 version of CREATE TABLE.