MySQL Shell 8.0  /  MySQL InnoDB ReplicaSet  /  Upgrade InnoDB ReplicaSet

9.5 Upgrade InnoDB ReplicaSet

To upgrade the instances in an InnoDB ReplicaSet, complete the following steps:

Check the versions of the installed binaries:

  • mysqlrouter --version: Checks the version of MySQL Router installed.

  • mysqlsh --version: Checks the version of MySQL Shell installed.

  • mysqld --version: Checks the version of MySQL Server installed.

Upgrade MySQL Router.

To upgrade MySQL Router, complete the following steps:

  1. 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 this 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 this command:

    .\stop.ps1

    Or on a Linux system using systemd, stop the MySQL Router service by issuing:

    systemctl stop mysqlrouter.service

    Otherwise, kill the process ID (PID) of the associated mysqlrouter process.

  2. Obtain and install the latest version of MySQL Router.

  3. 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 this 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=. Bootstrapping the router again also regenerates the start.sh shell script.

    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 this command:

    .\start.ps1

    On starting MySQL Router using the new router binaries, the version of the router is upgraded:

    mysqlrouter --version

Upgrade MySQL Shell

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

  1. Obtain and install the latest version of MySQL Shell.

  2. Stop and quit MySQL Shell by issuing:

    \q
  3. Restart MySQL Shell from the command line, by issuing:

    mysqlsh
  4. Upgrade the InnoDB ReplicaSet Metadata:

    • To upgrade an InnoDB ReplicaSet, connect MySQL Shell's global session to your ReplicaSet and use the dba.upgradeMetadata() operation to upgrade the ReplicaSet's metadata to the new metadata.

      The dba.upgradeMetadata() function compares the version of the installed metadata schema with the version of the metadata schema supported by this Shell. If the installed metadata version is lower, an upgrade process is started.

    Metadata Upgrade

    The Metadata Upgrade may do nothing if the ReplicaSet 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.

  1. 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
  2. Obtain and install the latest version of MySQL Server.

  3. 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
  4. When you have upgraded all the secondary instances, upgrade the primary instance to complete the upgrade process.

    There is no automatic primary switching in InnoDB ReplicaSet. You need to set the primary instance to a member you have upgraded already before upgrading the primary instance.

    Set an upgraded secondary instance to be the primary instance:

    <ReplicaSet>.setPrimaryInstance('<host>:<port>')

    Use the <ReplicaSet>.setPrimaryInstance() operation to safely perform a change of the primary of a ReplicaSet to another instance. The current primary is demoted to a secondary and made read-only, while the promoted instance becomes the new primary and is made read-write. All other secondary instances are updated to replicate from the new primary. MySQL Router instances that you have bootstrapped against the ReplicaSet automatically start redirecting read-write clients to the new primary.

    Upgrade the old primary instance. Once upgraded, you can use <ReplicaSet>.setPrimaryInstance() to restore this upgraded instance back to being primary. For more information, see Working with ReplicaSets.

Post Upgrade Status Check

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

  • Check the status of the ReplicaSet by issuing <ReplicaSet>.status(). In the following example, <ReplicaSet>.status() returns an instanceErrors:

      mysqlsh> <ReplicaSet>.status();
    {
        "replicaSet": {
            "name": "myReplicaSet",
            "primary": "example-el7-1644251369:30014",
            "status": "AVAILABLE",
            "statusText": "All instances available.",
            "topology": {
                "example-el7-1644251369:30011": {
                    "address": "example-el7-1644251369:30011",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                },
                "example-el7-1644251369:30014": {
                    "address": "example-el7-1644251369:30014",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "PRIMARY",
                    "mode": "R/W",
                    "status": "ONLINE"
                },
                "example-el7-1644251369:30017": {
                    "address": "example-el7-1644251369:30017",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                },
                "example-el7-1644251369:30021": {
                    "address": "example-el7-1644251369:30021",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                }
            },
            "type": "ASYNC"
        }
    }

    The instanceError tells us to issue dba.configureReplicaSetInstance() to fix the error.

    dba.configureReplicaSetInstance(instance) configures each instance you want to use in the ReplicaSet. MySQL Shell can either connect to an instance and then configure it, or you can pass in an instance name to configure a specific remote instance. For more information, see Section 6.1.5, “Persisting Settings”.

    The following example shows the output of <ReplicaSet>.status() if the PRIMARY member has read_only or super_read_only set to ON:

    mysqlsh > <ReplicaSet>.status();
    replicaset.status();
    {
        "replicaSet": {
            "name": "myReplicaSet",
            "primary": "example-el7-1644251369:30014",
            "status": "UNAVAILABLE",
            "statusText": "PRIMARY instance is not available, but there is at least one SECONDARY 
                           that could be force-promoted.",
            "topology": {
                "example-el7-1644251369:30011": {
                    "address": "example-el7-1644251369:30011",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                },
                "example-el7-1644251369:30014": {
                    "address": "example-el7-1644251369:30014",
                    "fenced": true,
                    "instanceErrors": [
                        "ERROR: Instance is a PRIMARY but is READ-ONLY: read_only=ON, super_read_only=ON",
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "PRIMARY",
                    "mode": "R/O",
                    "status": "ERROR"
                },
                "example-el7-1644251369:30017": {
                    "address": "example-el7-1644251369:30017",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                },
                "example-el7-1644251369:30021": {
                    "address": "example-el7-1644251369:30021",
                    "instanceErrors": [
                        "NOTE: The required parallel-appliers settings are not enabled on the instance. 
                               Use dba.configureReplicaSetInstance() to fix it."
                    ],
                    "instanceRole": "SECONDARY",
                    "mode": "R/O",
                    "replication": {
                        "applierStatus": "APPLIED_ALL",
                        "applierThreadState": "Waiting for an event from Coordinator",
                        "applierWorkerThreads": 4,
                        "receiverStatus": "ON",
                        "receiverThreadState": "Waiting for source to send event",
                        "replicationLag": null
                    },
                    "status": "ONLINE"
                }
            },
            "type": "ASYNC"
        }
    }

    For more information, see Working with ReplicaSets.