MySQL InnoDB Cluster and MySQL Router: Building High Availability Without External Tools

1. What InnoDB Cluster is: three components working together

InnoDB Cluster is not a standalone replication protocol, it is an orchestration layer built on top of three existing building blocks. Group Replication handles the actual data replication between nodes through a Paxos-based group communication protocol. The MySQL Shell's AdminAPI sits above that as a declarative management layer, offering cluster configuration, metadata management, and instance management as consistent object methods instead of setting individual server variables by hand.

MySQL Router, finally, sits as a lightweight proxy between the application and the cluster and automatically routes connections to the current primary or to readable secondary nodes depending on their role. Together these three components deliver a setup where an application only ever needs to know one single, stable connection address pointing at the router, regardless of which physical node currently acts as primary.

2. The difference from a manual Group Replication setup

A manual Group Replication setup requires setting variables like group_replication_group_name, group_replication_local_address, and group_replication_group_seeds consistently on every node before the group can even bootstrap. Mistakes in this manual coordination, such as a wrong seed address or a mismatched group UUID, lead to hard-to-diagnose split-brain situations that often only surface at the very first failover.

The AdminAPI encapsulates exactly that source of error: dba.createCluster() computes the necessary Group Replication variables itself, sets up a metadata schema that consistently tracks topology, instance roles, and router registrations, and actively checks whether a new instance is configured compatibly with every addInstance() call. These upfront checks, covering things like a matching server_id, enabled GTIDs, or correct character sets, prevent many mistakes that only surface in production under manual configuration.

3. Prerequisites: GTID, InnoDB, and server configuration

InnoDB Cluster mandates GTID-based replication, since the AdminAPI internally relies on SOURCE_AUTO_POSITION for automatic topology management. All participating tables also need to use the InnoDB engine with a primary key, because Group Replication depends on row-based certification for conflict detection, which does not work reliably without a primary key.

Further mandatory prerequisites are a unique server_id per node, binary logging enabled with row format, and a correctly set report_host so nodes can reach each other under the right address on the network. The MySQL Shell offers dba.checkInstanceConfiguration() as a dedicated diagnostic tool that checks exactly these prerequisites before the actual cluster build, and can automatically fix gaps through dba.configureInstance() when needed.

# Check an instance for InnoDB Cluster readiness and auto-configure if needed
mysqlsh -- dba checkInstanceConfiguration root@db1.internal:3306
mysqlsh -- dba configureInstance root@db1.internal:3306 --restart=true

4. Building the cluster with the MySQL Shell AdminAPI

The actual build happens interactively or scripted through the MySQL Shell's JavaScript or Python console. dba.createCluster() initializes the first instance as a seed node, creates the metadata schema, and bootstraps Group Replication with automatically computed variables. Every additional instance gets added through cluster.addInstance(), and the AdminAPI automatically decides whether an incremental data sync via the clone plugin or a full recovery is needed.

That recovery decision is a practical advantage over manual setup: instead of manually restoring a backup and reconciling the position by hand, the clone plugin mechanism handles a consistent data transfer in the background, while the AdminAPI tracks progress and only marks the instance as an active member once the data is fully synchronized.

// Inside the MySQL Shell (mysqlsh --js)
shell.connect('root@db1.internal:3306');
var cluster = dba.createCluster('productionCluster');

cluster.addInstance('root@db2.internal:3306', {recoveryMethod: 'clone'});
cluster.addInstance('root@db3.internal:3306', {recoveryMethod: 'clone'});

5. MySQL Router: automatic port selection and bootstrap

MySQL Router is initialized against any cluster instance through the bootstrap command and automatically reads the topology from the metadata schema, with no manual listing of every node required. By default the bootstrap process sets up two ports: port 6446 for read and write access, always routed to the current primary, and port 6447 for read-only access, distributed across the available secondary nodes on a round-robin basis.

For applications, this means connection strings, once InnoDB Cluster is in place, no longer point at concrete database servers but exclusively at the router, usually installed multiple times right next to the application itself, to avoid an extra network hop of latency and to keep the router from becoming a single point of failure in its own right.

mysqlrouter --bootstrap root@db1.internal:3306 --user=mysqlrouter --force
mysqlrouter --config /etc/mysqlrouter/mysqlrouter.conf &

# The application now connects exclusively to the router:
# Read/write access:   db-app-host:6446
# Read-only access:    db-app-host:6447

6. Failover behavior and the router's role during a primary change

If the current primary fails, Group Replication automatically elects a new primary from the remaining online members through an internal consensus process, usually within a few seconds. The router picks up on that change because it continuously polls the metadata schema across all cluster nodes, and automatically routes new connections on port 6446 to the new primary, without the application noticing anything beyond a brief connection interruption.

Existing, already open connections to the old primary are not migrated automatically, they simply drop and need to be reestablished by the application. For that reason, application code should always carry robust connection retry logic, regardless of whether InnoDB Cluster or another HA mechanism is in use.

7. Monitoring cluster status: status() and describe()

The AdminAPI provides cluster.status() as a compact snapshot of the current cluster state, including each node's role, its Group Replication status, and any ongoing recovery operations. cluster.describe() complements that with the pure topology structure, independent of current operational status, which works well for automated consistency checks inside monitoring scripts.

For deeper diagnostics, a direct look at performance_schema.replication_group_members still pays off, since the AdminAPI commands internally query the same tables but partially aggregate them. Anyone building their own monitoring pipeline should combine both sources: the AdminAPI for readable status reports during operations, the performance schema tables for granular metrics over time.

var cluster = dba.getCluster();
cluster.status();
cluster.describe();

8. Scaling: addInstance, removeInstance, and rejoin after a failure

New nodes can be added at any time via cluster.addInstance() without interrupting production, while cluster.removeInstance() cleanly removes a node from both Group Replication and the metadata schema. If a node temporarily fails, say through a network partition, and comes back later, the AdminAPI detects that and offers a targeted reconnection through cluster.rejoinInstance() without a full resync, provided the backlog is small enough.

For a larger backlog, the AdminAPI automatically opts for a full clone-based resync instead of an incremental rejoin, which costs operational time in practice but reliably rules out data inconsistencies. This automatic tradeoff between incremental rejoin and full rebuild is one of the areas where the AdminAPI makes operational decisions that manual Group Replication operation would leave entirely up to the DBA team.

9. Limits of InnoDB Cluster and when the approach does not fit

InnoDB Cluster is primarily designed for environments with low network latency between nodes, since Group Replication needs a certification round trip across all members for every single transaction. Across sites with noticeable WAN latency, write throughput suffers noticeably, which is why genuinely multi-region setups should generally lean on asynchronous read replicas as an additional layer rather than spanning the whole cluster across multiple regions.

In multi-primary mode, where several nodes accept write access at the same time, the risk of certification conflicts on concurrent writes to the same row also rises, requiring application code with matching retry logic. For teams that have already built ProxySQL or their own orchestration solution around a manual Group Replication setup, migrating to InnoDB Cluster usually only pays off if the existing solution causes noticeable maintenance overhead that the integrated AdminAPI would genuinely reduce.

10. Summary

11. FAQ: InnoDB Cluster: Key Facts at a Glance