You work with an InnoDB ReplicaSet in much the same way as you
would work with an InnoDB cluster. For example as seen in
Adding Instances to a ReplicaSet, you assign a
ReplicaSet object to a variable and call
operations that administer the replica set, such as
to add instances, which is the equivalent of
in InnoDB cluster. Thus, much of the documentation at
Section 21.5, “Working with InnoDB Cluster” also
applies to InnoDB ReplicaSet. The following operations are
You get online help for
ReplicaSetobjects, and the AdminAPI, using
dba.help(). See Using AdminAPI.
You can quickly check the name of a
ReplicaSetobject using either
. For example the following are equivalent:
mysql-js> rs.name example mysql-js> rs.getName() example
You check information about a replica set using the
operation, which supports the
extendedoption to get different levels of detail. For example:
the default for
extendedis 0, a regular level of details. Only basic information about the status of the instance and replication is included, in addition to non-default or unexpected replication settings and status.
extendedto 1 includes Metadata Version, server UUID and the raw information used to derive the status of the instance, size of the applier queue, value of system variables that protect against unexpected writes and so on.
extendedto 2 includes important replication related configuration settings, such as SSL, worker threads, replication delay and heartbeat delay.
You change the instances being used for a replica set using the
operations. See Adding Instances to a ReplicaSet, and Removing Instances from the InnoDB Cluster.
In the event of an instance leaving the replica set, for example due to an unexpected halt, use the
operation. See Rejoining a Cluster.
You work with the MySQL Router instances which have been bootstrapped against a replica set in exactly the same way as with InnoDB cluster. See Working with a Cluster's Routers for information on
. For specific information on using MySQL Router with InnoDB ReplicaSet see Section 21.6.6, “Using Replica Sets with MySQL Router”.
For more information, see the linked InnoDB cluster sections.
The following operations are specific to InnoDB ReplicaSet and
can only be called against a
operation to safely perform a change of the primary of a
replica set 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 which have been bootstrapped
against the replica set automatically start redirecting
read-write clients to the new primary.
For a safe change of the primary to be possible, all replica
set instances must be reachable by MySQL Shell and have
GTID_EXECUTED sets. If the
primary is not available, and there is no way to restore it, a
forced failover might be the only option instead, see
Forcing the Primary Instance in a Replica Set.
During a change of primary, the promoted instance is synchronized with the old primary, ensuring that all transactions present on the primary are applied before the topology change is committed. If this synchronization step takes too long or is not possible on any of the secondary instances, the operation is aborted. In such a situation, these problematic secondary instances must be either repaired or removed from the replica set for the fail over to be possible.
Unlike InnoDB cluster, which supports automatic failover in
the event of an unexpected failure of the primary,
InnoDB ReplicaSet does not have automatic failure detection
or a consensus based protocol such as that provided by Group
Replication. If the primary is not available, a manual
failover is required. An InnoDB ReplicaSet which has lost
its primary is effectively read-only, and for any write
changes to be possible a new primary must be chosen. In the
event that you cannot connect to the primary, and you cannot
to safely perform a switchover to a new primary as described
at Planned Changes of the Replica Set Primary, use the
operation to perform a forced failover of the primary. This is
a last resort operation that must only be used in a disaster
type scenario where the current primary is unavailable and
cannot be restored in any way.
A forced failover is a potentially destructive action and must be used with caution.
If a target instance is not given (or is null), the most
up-to-date instance is automatically selected and promoted to
be the new primary. If a target instance is provided, it is
promoted to a primary, while other reachable secondary
instances are switched to replicate from the new primary. The
target instance must have the most up-to-date
GTID_EXECUTED set among reachable
instances, otherwise the operation fails.
A failover is different from a planned primary change because it promotes a secondary instance without synchronizing with or updating the old primary. That has the following major consequences:
Any transactions that had not yet been applied by a secondary primary to a secondary at the time the old primary failed are lost.
If the old primary is actually still running and processing transactions, there is a split-brain and the datasets of the old and new primaries diverge.
If the last known primary is still reachable, the
operation fails, to reduce the risk of split-brain situations.
But it is the administrator's responsibility to ensure that
the old primary it is not reachable by the other instances to
prevent or minimize such scenarios.
After a forced failover, the old primary is considered invalid by the new primary and can no longer be part of the replica set. If at a later date you find a way to recover the instance, it must be removed from the replica set and re-added as a new instance. If there were any secondary instances that could not be switched to the new primary during the failover, they are also considered invalid.
Data loss is possible after a failover, because the old primary might have had transactions that were not yet replicated to the secondary being promoted. Moreover, if the instance that was presumed to have failed is still able to process transactions, for example because the network where it is located is still functioning but unreachable from MySQL Shell, it continues diverging from the promoted instances. Recovering once transaction sets on instances have diverged requires manual intervention and could not be possible in some situations, even if the failed instances can be recovered. In many cases, the fastest and simplest way to recover from a disaster that required a forced failover is by discarding such diverged transactions and re-provisioning a new instance from the newly promoted primary.