8.10.1 InnoDB Cluster Upgrade

Upgrade MySQL Router.

To upgrade MySQL Router, complete the following steps:

Stop MySQL Router.
On a Unix system, if you used the optional --directory bootstrap option, a self-contained installation is created with all generated directories and files at the location you selected when you bootstrapped the router. These files include stop.sh. Navigate to this directory and issue the following command:
```
./stop.sh
```
On Microsoft Windows, if you used the optional --directory bootstrap option, a self-contained installation is created with all generated directories and files at the location you selected when you bootstrapped the router. These files include stop.ps1. Navigate to this directory and issue the following command:
```
.\stop.ps1
```
Or on a Linux system using systemd, stop the MySQL Router service by issuing the following command:
```
systemctl stop mysqlrouter.service
```
Otherwise, kill the process ID (PID) of the associated mysqlrouter process.
Obtain and install the latest version of MySQL Router.
Start MySQL Router.
On a Unix system, if you used the optional --directory bootstrap option, a self-contained installation is created with all generated directories and files at the location you selected. These files include start.sh. Navigate to the directory and issue the following command:
```
./start.sh
```
If the path to the new router has changed, you must update the start.sh shell script to reflect the path.
```
#!/bin/bash
basedir=/tmp/myrouter
ROUTER_PID=$basedir/mysqlrouter.pid /usr/bin/mysqlrouter -c $basedir/mysqlrouter.conf &
disown %-
```
If you upgrade MySQL Router manually, opposed to using package management, you can update the basedir=. If you bootstrap the router again the start.sh shell script is regenerated.
Or on a Linux system using systemd, start the MySQL Router service by issuing:
```
systemctl start mysqlrouter.service
```
On Microsoft Windows, if you used the optional --directory bootstrap option, a self-contained installation is created with all generated directories and files at the location you selected. These files include start.ps1. Navigate to the directory and issue the following command:
```
.\start.ps1
```
On starting MySQL Router using the new router binaries, check the version of the router is upgraded by issuing the following command:
```
mysqlrouter --version
```

Upgrade MySQL Shell

Upgrade MySQL Shell by installing the new binaries, and stopping and starting MySQL Shell:

Obtain and install the latest version of MySQL Shell.
Stop and quit MySQL Shell by issuing:
```
\q
```
Restart MySQL Shell from the command line, by issuing:
```
mysqlsh
```
Upgrade the InnoDB Cluster Metadata:
- To upgrade an InnoDB Cluster's metadata, connect MySQL Shell's global session to your cluster and use the dba.upgradeMetadata() operation to upgrade the cluster's metadata to the new metadata.
Metadata Upgrade
The Metadata Upgrade may do nothing if the Cluster already uses the latest version.

Upgrade MySQL Server

Upgrade MySQL Server by upgrading all secondary instances before upgrading the primary instance.

Upgrading MySQL Server is optional

Upgrading MySQL Server is optional. Server upgrades can have a greater impact than upgrading MySQL Shell and MySQL Router. Also, you should always keep MySQL Shell and MySQL Router at the latest version, even if the server is not; this is true for InnoDB Clusters and ReplicaSets.

Stop MySQL Server by issuing one of the following commands:
- If MySQL Server is using systemd issue:
```
systemctl stop mysqld
```
- If MySQL Server is using init.d issue:
```
/etc/init.d/mysql stop
```
- If MySQL Server is using service issue:
```
service mysql stop
```
- If you deployed MySQL Server on Microsoft Windows issue:
```
mysqladmin -u root -p shutdown
```
Obtain and install the latest version of MySQL Server.
Start MySQL Server by issuing one of the following commands:
- If MySQL Server is using systemd issue:
```
systemctl start mysqld
```
- If MySQL Server is using init.d issue:
```
/etc/init.d/mysql start
```
- If MySQL Server is using service issue:
```
service mysql start
```
- If you deployed MySQL Server on Microsoft Windows issue:
```
mysqld
```
When all the secondary instances are upgraded, upgrade the primary instance to complete the upgrade process.

Post Upgrade Status Check

After upgrading MySQL Router, MySQL Shell, and MySQL Servers are upgraded:

Check the Cluster by issuing <Cluster>.status(). For more information about <Cluster>.status(), see Checking a Cluster's Status with Cluster.status().
Resolve any clusterErrors and statusText returned by the <Cluster>.status() operation.

These commands allow you to check that the upgrade has been successful or if you need to complete any additional steps.

Note

The additional steps depend; on how many versions you are skipping, what version you are upgrading, and from what version you are coming.

Check the status of each InnoDB Cluster, by issuing <Cluster>.status().

In the following example, <Cluster>.status({extended: true}), used to provide more detailed information about the status of the Cluster, returns two issues:

      
    mysqlsh> <Cluster>.status({extended: true});   
    {
        "clusterName": "MyCluster",
        "defaultReplicaSet": {
            "GRProtocolVersion": "8.0.16",
            "groupName": "459ec434-8926-11ec-b8c3-02001707f44a",
            "groupViewChangeUuid": "AUTOMATIC",
            "groupViewId": "16443558036060755:13",
            "name": "default",
            "ssl": "REQUIRED",
            "status": "OK",
            "statusText": "Cluster is ONLINE and can tolerate up to ONE failure.",
            "topology": {
                "example-el7-1644251369:33311": {
                    "address": "example-el7-1644251369:33311",
                    "applierWorkerThreads": 4,
                    "fenceSysVars": [],
                    "instanceErrors": [
                        "NOTE: instance server_id is not registered in the metadata. 
                               Use cluster.rescan() to update the metadata.",
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureInstance() to fix it."
                    ],
                    "memberId": "247131ab-8926-11ec-850b-02001707f44a",
                    "memberRole": "PRIMARY",
                    "memberState": "ONLINE",
                    "mode": "R/W",
                    "readReplicas": {},
                    "replicationLag": null,
                    "role": "HA",
                    "status": "ONLINE",
                    "version": "8.0.28"
                },
                "example-el7-1644251369:33314": {
                    "address": "example-el7-1644251369:33314",
                    "applierWorkerThreads": 4,
                    "fenceSysVars": [],
                    "instanceErrors": [
                        "NOTE: instance server_id is not registered in the metadata. 
                               Use cluster.rescan() to update the metadata.",
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureInstance() to fix it."
                    ],
                    "memberId": "303dcfa7-8926-11ec-a6e5-02001707f44a",
                    "memberRole": "PRIMARY",
                    "memberState": "ONLINE",
                    "mode": "R/W",
                    "readReplicas": {},
                    "replicationLag": null,
                    "role": "HA",
                    "status": "ONLINE",
                    "version": "8.0.28"
                },
                "example-el7-1644251369:33317": {
                    "address": "example-el7-1644251369:33317",
                    "applierWorkerThreads": 4,
                    "fenceSysVars": [],
                    "instanceErrors": [
                        "NOTE: instance server_id is not registered in the metadata. 
                               Use cluster.rescan() to update the metadata.",
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureInstance() to fix it."
                    ],
                    "memberId": "3bb2592e-8926-11ec-8b6f-02001707f44a",
                    "memberRole": "PRIMARY",
                    "memberState": "ONLINE",
                    "mode": "R/W",
                    "readReplicas": {},
                    "replicationLag": null,
                    "role": "HA",
                    "status": "ONLINE",
                    "version": "8.0.28"
                }
            },
            "topologyMode": "Multi-Primary"
        },
        "groupInformationSourceMember": "example-el7-1644251369:33311",
        "metadataVersion": "2.1.0"
    }

<Cluster>.status({extended: true}) displays more detailed information about the Cluster. In this example, we use the Boolean value true, which is equivalent to <Cluster>.status({'extended':1}). For more information, see Checking a Cluster's Status with Cluster.status().

Resolve any errors returned by the <Cluster>.status({extended:1}) operation.

In this example, the instanceErrors suggest that in this upgrade, we should issue <Cluster>.rescan() and dba.configureInstance() on each member in the Cluster:

...
"NOTE: instance server_id is not registered in the
metadata. Use <Cluster>.rescan() to update the metadata.",
"NOTE: The required parallel-appliers settings are not
enabled on the instance. Use dba.configureInstance() to fix it."
...

The <Cluster>.rescan() operation enables you to rescan the Cluster for new and obsolete Group Replication instances, as well as changes in the used topology mode. For more information, see Rescanning a Cluster.

mysqlsh> <Cluster>.rescan();
Rescanning the cluster...

Result of the rescanning operation for the 'MyCluster1' cluster:
{
    "name": "MyCluster1",
    "newTopologyMode": null,
    "newlyDiscoveredInstances": [],
    "unavailableInstances": [],
    "updatedInstances": []
}

The dba.configureInstance() function checks all of the settings required to enable the instance to be used for InnoDB Cluster usage. For more information, see Configuring Production Instances for InnoDB Cluster Usage.

In this example, we issue dba.configureInstance() on each member in the InnoDB Cluster, to ensure required the parallel-appliers settings are enabled on the instance:

  mysqlsh> dba.configureInstance('cladmin:cladminpw@localhost:33311')
    The instance 'example-el7-1644251369:33311' belongs to an InnoDB Cluster.
    Configuring local MySQL instance listening at port 33311 for use in an InnoDB cluster...

    This instance reports its own address as ^[[1mexample-el7-1644251369:33311^[[0m
    Clients and other cluster members will communicate with it through this address by default. 
    If this is not correct, the report_host MySQL system variable should be changed.

    applierWorkerThreads will be set to the default value of 4.

    ^[[36mNOTE: ^[[0mSome configuration options need to be fixed:
    +----------------------------------------+---------------+----------------+----------------------------+
    | Variable                               | Current Value | Required Value | Note                       |
    +----------------------------------------+---------------+----------------+----------------------------+
    | binlog_transaction_dependency_tracking | COMMIT_ORDER  | WRITESET       | Update the server variable |
    +----------------------------------------+---------------+----------------+----------------------------+

    Configuring instance...
    The instance 'example-el7-1644251369:33311' was configured to be used in an InnoDB cluster.

For information on troubleshooting Cluster Upgrades, see Troubleshooting InnoDB Cluster Upgrades.