6.10.7 Working with a Cluster's Routers

You can bootstrap multiple instances of MySQL Router against InnoDB Cluster or InnoDB ReplicaSet. To show a list of all registered MySQL Router instances, issue:

Cluster.listRouters()

The result provides information about each registered MySQL Router instance, such as its name in the metadata, the hostname, ports, and so on. For example, issue the following JavaScript command:

mysql-js> Cluster.listRouters()
{
    "clusterName": "example",
    "routers": {
        "ic-1:3306": {
            "hostname": "ic-1:3306",
            "lastCheckIn": "2020-01-16 11:43:45",
            "roPort": 6447,
            "roXPort": 64470,
            "rwPort": 6446,
            "rwXPort": 64460,
            "version": "8.0.19"
        }
    }
}

Or issue the following Python command:

mysql-py> Cluster.list_routers()
{
    "clusterName": "example",
    "routers": {
        "ic-1:3306": {
            "hostname": "ic-1:3306",
            "lastCheckIn": "2020-01-16 11:43:45",
            "roPort": 6447,
            "roXPort": 64470,
            "rwPort": 6446,
            "rwXPort": 64460,
            "rwSplitPort": 6450,
            "version": "8.0.19"
        }
    }
}

The returned information shows:

• The name of the MySQL Router instance.

• Last check-in timestamp, which is generated by a periodic ping from the MySQL Router stored in the metadata.

• Hostname where the MySQL Router instance is running.

• Read-Only (roPort) and Read-Write (rwPort) ports, which the MySQL Router publishes for classic MySQL protocol connections.

• Read-Only (roXPort) and Read-Write (rwXPort) ports, which the MySQL Router publishes for X Protocol connections.

• Read-Write splitting (rwSplitPort) ports, which the MySQL Router publishes for split classic MySQL protocol connections.

  See Read/Write Splitting.

• Version of this MySQL Router instance. If this operation is run against an version of MySQL Router earlier than 8.0.19, the version field is null.

Additionally, the Cluster.listRouters() operation can show a list of instances that do not support the metadata version supported by MySQL Shell. Use the onlyUpgradeRequired option. For example, by issuing Cluster.listRouters({'onlyUpgradeRequired':'true'}).

The returned list shows only the MySQL Router instances registered with the Cluster, which require an upgrade of their metadata. For more information, see Section 6.11, “Upgrade Metadata Schema”.

MySQL Router instances are not automatically removed from the metadata, so for example as you bootstrap more instances the InnoDB Cluster metadata contains a growing number of references to instances. To remove a registered MySQL Router instance from a cluster's metadata, use the Cluster.removeRouterMetadata(router) operation.

Use the Cluster.listRouters() operation to get the name of the MySQL Router instance you want to remove, and pass it in as router. For example, suppose the MySQL Router instances registered with a cluster were:

mysql-js> Cluster.listRouters(){

    "clusterName": "testCluster",
    "routers": {
        "myRouter1": {
            "hostname": "example1.com",
            "lastCheckIn": null,
            "roPort": "6447",
            "rwPort": "6446"
            "version": null
        },
        "myRouter2": {
            "hostname": "example2.com",
            "lastCheckIn": "2019-11-27 16:25:00",
            "roPort": "6447",
            "rwPort": "6446"
            "version": "8.0.19"
        }
    }
}

Based on the fact that the instance named “myRouter1” has null for “lastCheckIn” and “version”. Remove this old instance from the metadata by issuing the following JavaScript command:

mysql-js> cluster.removeRouterMetadata('myRouter1')

Or, by issuing the following Python command:

mysql-py> cluster.remove_router_metadata('myRouter1')

The MySQL Router instance specified is unregistered from the cluster by removing it from the InnoDB Cluster metadata.

Viewing Router Configurations with MySQL Shell

As of MySQL Router 8.4.0, routers bootstrapped against a cluster expose their configuration in the InnoDB Cluster Metadata Schema of the clusters they are connected to. This configuration can be retrieved using the .routerOptions() operation, which is available on the Cluster, ClusterSet. and ReplicaSet objects.

Note

If your existing router accounts do not have the required permissions, the configuration information can not be written to the metadata schema. MySQL Shell detects this and generates a warning. You must ensure your router accounts have the correct privileges with setupRouterAccount() and bootstrap again if necessary .

By default, .routerOptions() enables you to retrieve the global configuration in place for the target topology. It lists the global dynamic configurations which can be configured by MySQL Shell. See Section 6.10.4, “Routing Options”. Routers configured with a different configuration value than the corresponding global one are also listed.

.routerOptions() has the following syntax:

          cluster.routerOptions({options})

The following options are available:

• router: routerName

• extended: 0 | 1 | 2:

  • 0: Default. Returns the dynamic MySQL Router configuration parameters.

  • 1: Returns all global parameters for the connected routers and a per-router listing of parameters whose values differ from the global value.

  • 2: Returns all configuration parameters for all routers connected to the cluster.

The following is an example of the default option used against a Cluster named Cluster1, with a single router, version 8.4.0, named router_test:

$> cluster.routerOptions()
     {
          "clusterName": "Cluster1",
          "configuration": {
            "routing_rules": {
              "invalidated_cluster_policy": "drop_all",
              "read_only_targets": "secondaries",
              "stats_updates_frequency": -1,
              "tags": {},
              "unreachable_quorum_allowed_traffic": "none",
              "use_replica_primary_as_rw": false
            }
        },
        "routers": {
            "host1::router_test": {
                "configuration": {
                }
            }
        }
    }

The operation returns a JSON object with the target topology's name, the retrieved global configuration, and a list of the Routers belonging to that topology and the configuration of each.