6.10.4 Routing Options

The setRoutingOption method enables you to change a routing option globally or for individual routers.

The routing options are as follows:

• "target_cluster", "primary" | "clusterName"

  Available for ClusterSet only.

  • "primary":

    With this setting, MySQL Router directs traffic from client applications to the cluster in the InnoDB ClusterSet deployment that is currently the primary cluster. A primary cluster can accept both read and write traffic. Follow the primary mode is the default for the global policy and for individual MySQL Router instances.

  • "clusterName"

    With this setting, MySQL Router directs traffic from applications to the specified cluster in the InnoDB ClusterSet deployment, whether it is currently in the role of the primary cluster or a replica cluster. If the target cluster is currently the primary cluster, MySQL Router opens the write port and applications can write to the instance. If the target cluster is currently a read-only replica cluster, MySQL Router allows only read traffic, and denies write traffic. If this situation changes due to a switchover or failover to or from the target cluster, MySQL Router changes the permitted request types accordingly. This mode is useful if an application makes only read requests, which can be made on a replica cluster, and you want to keep that traffic routed to a local cluster. Note that the cluster name is case sensitive.

  See Section 8.5, “Integrating MySQL Router With InnoDB ClusterSet”.

• "invalidated_cluster_policy", "drop_all" | "accept_ro"

  Available for Cluster and ClusterSet only.

  • "drop_all": With this setting, when a cluster is marked as INVALIDATED, MySQL Router disallows both read and write traffic to it from applications. A cluster in this state is not currently functioning at all as part of the InnoDB ClusterSet deployment, and cannot receive writes. It might be a former primary cluster that was marked as invalidated during an emergency failover process, or a replica cluster that was marked as invalidated because it was unreachable or unavailable at the time of a failover or during a controlled switchover. This setting is the default for the global policy and for individual MySQL Router instances.

  • "accept_ro": With this setting, when a cluster is marked as INVALIDATED, MySQL Router allows read traffic to it from applications but drops write traffic. Although an invalidated cluster does not necessarily have any technical issues, the data is becoming stale, so this setting means that stale reads will take place unless the issue is resolved soon. However, this setting can provide higher availability in cases where stale reads are not a high priority.

  See Section 8.5, “Integrating MySQL Router With InnoDB ClusterSet”.

• "stats_updates_frequency", "numberOfSeconds"

  This option defines, in seconds, the interval between MySQL Router check-in updates.

  If set to 0 (default), no periodic updates are done. MySQL Router rounds up the value to a multiple of its TTL. For example:

  • If lower than TTL it gets rounded up to TTL. For example: if TTL=30 and stats_updates_frequency=1, the effective frequency is 30 seconds.

  • If not a multiple of TTL, it is rounded up and adjusted according to the TTL. For example, if TTL=5 and stats_updates_frequency=11, the effective frequency is 15 seconds, or if TTL=5 and stats_updates_frequency=13, the effective frequency is 15 seconds.

  If the value is null, the option value is cleared and the default value takes effect.

• "unreachable_quorum_allowed_traffic", [ read | all | none ]

  Available for Cluster only.

  Defines MySQL Router's routing policy in the event of a loss of quorum on the only reachable Cluster partition.

  Important

  Changing this option is not advised. Consequences include breaking the consistency guarantees of InnoDB Cluster, data returned can be stale or simply incorrect. Different routers may be accessing different partitions and could return different data. Different routers may have different behaviors, some providing read-only traffic, and others providing read-write traffic.

  • read: MySQL Router continues using the remaining online members as read-only destinations. Read-only and Read-Write split ports remain open for reads, but write traffic is blocked.

  • all: MySQL Router uses all remaining online destinations as Read-Write destinations. All ports remain open.

  • none: (Default) All current connections are disconnected and new connections are refused.

  This option has no effect if group_replication_unreachable_majority_timeout is set to a positive value and group_replication_exit_state_action is either OFFLINE_MODE or ABORT_SERVER.

• "use_replica_primary_as_rw", [true | false]

  Available for ClusterSet only.

  This option instructs MySQL Router to open or close a read-write (R/W) port on a router targeting a specific Cluster (where target_cluster is not set to primary), enabling you to use a R/W port on a ReplicaCluster. The ReplicaCluster continues to only accept R/O traffic. In the event of a switchover or failover, the R/W port remains unchanged.

  If set to true, MySQL Router R/W port in ReplicaClusters.

  If set to false (default), the router's behavior is unchanged and the R/W port is closed in ReplicaClusters.

• tags

  Arbitrary key-value pairs in JSON format. For example:

  cluster.setRoutingOption("tags", "name:value")

• "read_only_targets", "all" | "read_replicas" | "secondaries"

  Available for Cluster and ClusterSet only.

  • all: all Read Replicas and Secondary Cluster members are used for read-only traffic.

  • read_replicas: only Read Replicas are used for read-only traffic.

  • secondaries: only Secondary Cluster members are used for read-only traffic.

  The following example sets the read-only routing policy for a router named machine1::router1 to Read Replicas only:

          Cluster.setRoutingOption("machine1::router1", "read_only_targets", "read_replicas")

  See Section 7.11, “MySQL InnoDB Cluster Read Replicas”.

To clear a routing option, set it to null.