5.4.10 The upgrade cluster Command

upgrade cluster {--package=|-P }package_name
 [{--nodeid|-n }node_id_list] [--force|-f]
 [--retry|-L] [--set=attribute_assignment_list] cluster_name

node_id_list:
    node_id[, node_id[, ...]]

attribute_assignment_list:
    attribute_assignment[,attribute_assignment][,...]

attribute_assignment:
    attribute_name:process_name[=value]

This command upgrades the cluster named cluster_name to the software package package_name specified with the --package. It finishes an upgrade by performing a rolling restart for the cluster, in which data nodes are restarted with the --initial option to have their data file systems rebuilt.

The new package must be registered using add package before you can use it for an upgrade; otherwise, upgrade cluster fails with an error.

To use the command to perform an upgrade on a cluster, unless some special options are used (see explanations on the --force, --retry, and --nodeid options below), the cluster must be in the fully operational status (you can check that using the command show status --cluster cluster_name). A cluster created for import cannot be upgraded until the import has been completed. See Section 5.4.1, “The create cluster Command”, and Section 4.5, “Importing MySQL NDB Clusters into MySQL Cluster Manager”, for more information.

Suppose mycluster is using MySQL NDB Cluster 7.5.22, and the binaries are registered with a package named 7.5.22, as shown by this list clusters command:

mcm> list clusters mysite;
+-----------+---------+
| Cluster   | Package |
+-----------+---------+
| mycluster | 7.5.22  |
+-----------+---------+
1 row in set (1.80 sec)

Now you wish to upgrade mycluster to MySQL NDB Cluster. Assuming that you have placed the NDB 8.0.40 binaries in the same directory on each host, the add package command to create a new package named 8.0.40 that contains these binaries might look something like this:

mcm> add package --basedir=/usr/local/ndb-8.0.40 8.0.40;
+----------------------------+
| Command result             |
+----------------------------+
| Package added successfully |
+----------------------------+
1 row in set (0.88 sec)

Note

On Windows, you must replace any backslash (\) characters in the path used for the add package command's --basedir option with forward slashes (/). See Section 5.3.1, “The add package Command”, for additional information and examples.

Both packages should now be listed in the output of the command list packages mysite. To perform the upgrade to the 8.0.40 package, use the upgrade cluster command as shown here:

mcm> upgrade cluster --package=8.0.40 mycluster;
+--------------------------------------+
| Command result                       |
+--------------------------------------+
| Cluster version changed successfully |
+--------------------------------------+
1 row in set (3 min 17.00 sec)

Once the upgrade cluster command has been successfully executed, you can verify that mycluster is now using the 8.0.40 package from the output of the appropriate list clusters command:

mcm> list clusters mysite;
+-----------+---------+
| Cluster   | Package |
+-----------+---------+
| mycluster | 8.0.40  |
+-----------+---------+
1 row in set (1.80 sec)

The command can perform major as well as minor series upgrades. Despite the name of this command, upgrade cluster can also be used to perform MySQL NDB Cluster downgrades.

Not all upgrades and downgrades between different versions of MySQL NDB Cluster are supported by the command. Three criteria must be met:

• The upgrade or downgrade must be supported by the MySQL NDB Cluster versions involved. See the following sections in the MySQL NDB Cluster manuals for lists of allowed upgrades and downgrades:

  • For MySQL NDB Cluster 8.0: See Upgrading and Downgrading NDB Cluster.

  • For MySQL NDB Cluster 7.5 and 7.6: See Upgrading and Downgrading NDB Cluster.

• Both the versions you upgrade or downgrade to and from must be supported by the version of MySQL Cluster Manager you are using (for example, upgrade from MySQL NDB Cluster 7.4 to 8.0 must be performed manually, because MySQL Cluster Manager no longer supports MySQL NDB Cluster 7.4).

When using the upgrade cluster command, you can use the --set option to reconfigure your MySQL NDB Cluster at the same time. This is particularly helpful when the upgrade requires configuration changes to your cluster. This option takes as its argument an attribute assignment list similar in format to that used with the get and set commands; see description of the set command on the proper way to formulate an attribute assignment list. For example: if you want to change the memory assigned to each data node for storing database records to 750M, specify that with the --set option in your upgrade cluster command:

mcm> upgrade cluster --package=8.0.40 --set=DataMemory:ndbd=750M  mycluster;
+--------------------------------------+
| Command result                       |
+--------------------------------------+
| Cluster version changed successfully |
+--------------------------------------+
1 row in set (3 min 17.04 sec)

Note

Unlike the way you use the set command, an equal sign (=) immediately following the --set option is required.

Options for dealing with failed upgrades

The --force option (-f for short) should be used when you want to run the upgrade cluster command again after a failed upgrade attempt that ends up with any failed management or data nodes. Without the --force option, the upgrade cluster command only runs when the cluster is in the fully operational status.

The --retry option (-L for short) should be used when you want to retry the upgrade cluster command after a failed attempt that ends up with some nodes being upgraded, and some not. Without the --retry option, the upgrade cluster command cannot be run on the same cluster twice using the same package.

In the case of a failed or incomplete upgrade, instead of using the --force and --retry option, you can also choose to retry the upgrade only on the failed nodes by specifying them using the --nodeid option (-n in short). Check for any failed nodes after a failed upgrade:

mcm> upgrade cluster -P next mycluster;
ERROR 7006 (00MGR): Process error: <reason of failure>
mcm> show status --process mycluster;
+--------+----------+----------+---------+-----------+-----------+
| NodeId | Process  | Host     | Status  | Nodegroup | Package   |
+--------+----------+----------+---------+-----------+-----------+
| 49     | ndb_mgmd | thinkpad | running |           | next      |
| 1      | ndbmtd   | thinkpad | running | 0         | next      |
| 2      | ndbmtd   | thinkpad | running | 0         | next      |
| 50     | mysqld   | thinkpad | running |           | next      |
| 51     | mysqld   | thinkpad | failed  |           | next      |
| 52     | ndbapi   | *        | added   |           |           |
+--------+----------+----------+---------+-----------+-----------+
6 rows in set (0.03 sec)

Then, issue the command again, specifying the failed node with the --nodeid option:

mcm> upgrade cluster --nodeid=51 -P next mycluster;
+--------------------------------------+
| Command result                       |
+--------------------------------------+
| Cluster version changed successfully |
+--------------------------------------+
1 row in set (26.03 sec)

Warning

Using the --nodeid option inappropriately with the upgrade cluster command may result in a partial upgrade. Use it only when a previous attempt to upgrade failed, and only with guidance from the proper support personnel.