PDF (US Ltr)
- 2.5Mb
PDF (A4)
- 2.5Mb
This section explains how to change an InnoDB Cluster from single-primary to multi-primary mode or the other way around, how to remove server instances from an InnoDB Cluster, and how to dissolve an InnoDB Cluster that you no longer need.
By default, an InnoDB Cluster runs in single-primary mode, where the cluster has one primary server that accepts read and write queries (R/W), and all of the remaining instances in the cluster accept only read queries (R/O). When you configure a cluster to run in multi-primary mode, all of the instances in the cluster are primaries, which means that they accept both read and write queries (R/W). If a cluster has all of its instances running MySQL server version 8.0.15 or later, you can make changes to the topology of the cluster while the cluster is online. In previous versions it was necessary to completely dissolve and re-create the cluster to make the configuration changes. This uses the group action coordinator exposed through the functions described at Configuring an Online Group, and as such you should observe the rules for configuring online groups.
Note
Multi-primary mode is considered an advanced mode.
Usually a single-primary cluster elects a new primary when the
current primary leaves the cluster unexpectedly, for example due
to an unexpected halt. The election process is normally used to
choose which of the current secondaries becomes the new primary.
To override the election process and force a specific server
instance in the underlying Group Replication group to become the
new primary, use the
Cluster.setPrimaryInstance(instance[,
options)instance specifies the connection to
the instance which should become the new primary. You can use
the runningTransactionsTimeout option to add
a timeout between 0 and 3600 seconds for transactions that are
running when you use the function. When you set a timeout,
incoming transactions after the command is issued are rejected.
You can change the mode (sometimes described as the topology) which a cluster is running in between single-primary and multi-primary using the following operations:
Cluster.switchToMultiPrimaryMode()Cluster.switchToSinglePrimaryMode([instance])instanceis specified, it becomes the primary and all the other instances become secondaries. Ifinstanceis not specified, the new primary is the instance with the highest member weight (and the lowest UUID in case of a tie on member weight).
You can remove an instance from a cluster at any time should you
wish to do so. This can be done with the
Cluster.removeInstance(instance)
mysql-js> cluster.removeInstance('root@localhost:3310')
The instance will be removed from the InnoDB cluster. Depending on the instance
being the Seed or not, the Metadata session might become invalid. If so, please
start a new session to the Metadata Storage R/W instance.
Attempting to leave from the Group Replication group...
The instance 'localhost:3310' was successfully removed from the cluster.
The
cluster.removeInstance()ONLINE,
and the instance itself. The last instance that remains in
ONLINE status in an InnoDB Cluster cannot
be removed using this operation.
When the instance being removed has transactions which still
need to be applied, AdminAPI waits for up to the number of
seconds configured by the MySQL Shell
dba.gtidWaitTimeout option for transactions
(GTIDs) to be applied. The MySQL Shell
dba.gtidWaitTimeout option has a default
value of 60 seconds, see
Section 13.4, “Configuring MySQL Shell Options” for
information on changing the default. If the timeout value
defined by dba.gtidWaitTimeout is reached
when waiting for transactions to be applied and the
force option is false (or
not defined) then an error is issued and the remove operation is
aborted. If the timeout value defined by
dba.gtidWaitTimeout is reached when waiting
for transactions to be applied and the force
option is set to true then the operation
continues without an error and removes the instance from the
cluster.
Note
The force option of
Cluster.removeInstance(instance)
To dissolve an InnoDB Cluster you connect to a read-write
instance, for example the primary in a single-primary cluster,
and use the
Cluster.dissolve()
Important
There is no way to undo the dissolving of a cluster. To create
it again use dba.createCluster().
The
Cluster.dissolve()ONLINE or reachable. If members of a cluster
cannot be reached by the member where you issued the
Cluster.dissolve()
Warning
Forcing the dissolve operation to ignore cluster instances can result in instances which could not be reached during the dissolve operation continuing to operate, creating the risk of a split-brain situation. Only ever force a dissolve operation to ignore missing instances if you are sure there is no chance of the instance coming online again.
In interactive mode, if members of a cluster are not reachable during a dissolve operation then an interactive prompt is displayed, for example:
mysql-js> Cluster.dissolve()
The cluster still has the following registered instances:
{
"clusterName": "testCluster",
"defaultReplicaSet": {
"name": "default",
"topology": [
{
"address": "ic-1:3306",
"label": "ic-1:3306",
"role": "HA"
},
{
"address": "ic-2:3306",
"label": "ic-2:3306",
"role": "HA"
},
{
"address": "ic-3:3306",
"label": "ic-3:3306",
"role": "HA"
}
]
}
}
WARNING: You are about to dissolve the whole cluster and lose the high
availability features provided by it. This operation cannot be reverted. All
members will be removed from the cluster and replication will be stopped,
internal recovery user accounts and the cluster metadata will be dropped. User
data will be maintained intact in all instances.
Are you sure you want to dissolve the cluster? [y/N]: y
ERROR: The instance 'ic-2:3306' cannot be removed because it is on a '(MISSING)'
state. Please bring the instance back ONLINE and try to dissolve the cluster
again. If the instance is permanently not reachable, then you can choose to
proceed with the operation and only remove the instance from the Cluster
Metadata.
Do you want to continue anyway (only the instance metadata will be removed)?
[y/N]: y
Instance 'ic-3:3306' is attempting to leave the cluster... Instance 'ic-1:3306'
is attempting to leave the cluster...
WARNING: The cluster was successfully dissolved, but the following instance was
skipped: 'ic-2:3306'. Please make sure this instance is permanently unavailable
or take any necessary manual action to ensure the cluster is fully dissolved.
In this example, the cluster consisted of three instances, one
of which was offline when dissolve was issued. The error is
caught, and you are given the choice how to proceed. In this
case the missing ic-2 instance is ignored and
the reachable members have their metadata updated.
When MySQL Shell is running in non-interactive mode, for
example when running a batch file, you can configure the
behavior of the
Cluster.dissolve()force option. To force
the dissolve operation to ignore any instances which are
unreachable, issue:
mysql-js> Cluster.dissolve({force: true})Any instances which can be reached are removed from the cluster, and any unreachable instances are ignored. The warnings in this section about forcing the removal of missing instances from a cluster apply equally to this technique of forcing the dissolve operation.
The dba.gtidWaitTimeout MySQL Shell option
configures how long the
Cluster.dissolve()ONLINE. An error is issued
if the timeout is reached when waiting for cluster transactions
to be applied on any of the instances being removed, except if
force: true is used, which skips the error in that case.
Note
After issuing cluster.dissolve(), any
variable assigned to the
Cluster