7.8.2 Create and Activate Routing Guidelines

Create Routing Guidelines using the following command:

object.create_routing_guideline(name[, json[, options]])

• object: the Cluster, ClusterSet, or Replicaset to which the routing guideline is associated.

• name: the name of the Routing Guideline.

• json: (optional) JSON document defining the Routing Guideline. If a JSON document is not provided, a default Routing Guideline is generated according to the topology type. If a JSON document is provided, the content of the document is used to define the Routing Guideline. The name parameter of the operation overrides the name defined in the document.

  See Creating a Default Routing Guideline for InnoDB Cluster.

• options: it is possible to overwrite an existing Routing Guideline with the specified name, using the force option.

Note

Routing Guidelines are not set active on the topology by default. To set a Routing Guideline as active on a topology, you must do so manually. See Setting a Routing Guideline as Active.

• Creating a Default Routing Guideline for InnoDB Cluster

• Setting a Routing Guideline as Active

• Retrieving the Active Routing Guideline

• Remove Routing Guidelines

Creating a Default Routing Guideline for InnoDB Cluster

To create a default Routing Guideline for a three-member InnoDB Cluster, connect to the primary of the cluster and run the following commands:

1. Retrieve the cluster object:

   cluster = dba.get_cluster()

2. Create a Routing Guideline, named default:

   rg = cluster.create_routing_guideline("default")

A default Routing Guideline is defined for the cluster and stored in the metadata schema. The default schema contains the following values:

{
    "destinations": [
        {
            "match": "$.server.memberRole = PRIMARY",
            "name": "Primary"
        },
        {
            "match": "$.server.memberRole = SECONDARY",
            "name": "Secondary"
        },
        {
            "match": "$.server.memberRole = READ_REPLICA",
            "name": "ReadReplica"
        }
    ],
    "name": "default",
    "routes": [
        {
            "connectionSharingAllowed": true,
            "destinations": [
                {
                    "classes": [
                        "Primary"
                    ],
                    "priority": 0,
                    "strategy": "round-robin"
                }
            ],
            "enabled": true,
            "match": "$.session.targetPort = $.router.port.rw",
            "name": "rw"
        },
        {
            "connectionSharingAllowed": true,
            "destinations": [
                {
                    "classes": [
                        "Secondary"
                    ],
                    "priority": 0,
                    "strategy": "round-robin"
                },
                {
                    "classes": [
                        "Primary"
                    ],
                    "priority": 1,
                    "strategy": "round-robin"
                }
            ],
            "enabled": true,
            "match": "$.session.targetPort = $.router.port.ro",
            "name": "ro"
        }
    ],
    "version": "1.0"
}

Setting a Routing Guideline as Active

To set a Routing Guideline as the active guideline for a Cluster, use the following:

• cluster.set_routing_option("guideline","nameOfRoutingGuideline")

For example, for a guideline named RG1:

cluster.set_routing_option("guideline","RG1")

The guideline is validated against the routers associated with the Cluster. If any router is incompatible with the new guideline, an error is returned listing the incompatible routers. If the routers are using an active guideline which overrides the topology-level guideline.

If the router option is defined, the guideline is activated for the named router, only. Any other router connected to the topology continues to use the topology-level guideline, if it exists.

To confirm the router is configured to use the Routing Guideline, run cluster.list_routers() to view the currentRoutingGuideline value. This also returns the targetCluster and supportedRoutingGuidelinesVersion.

Retrieving the Active Routing Guideline

To retrieve the active Routing Guideline on the topology, use the following:

• object.router_options(): to check which Routing Guideline is currently active on the topology.

• object.get_routing_guideline(): to retrieve the guideline.

Remove Routing Guidelines

Routing Guidelines can be removed from the topology using the following:

• object.remove_routing_guideline("name")

The following example removes a Routing Guideline named RG1 from a Cluster:

cluster.remove_routing_guideline("RG1")