MySQL Shell 8.0
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.
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
function, where
Cluster
.setPrimaryInstance(instance
[,
options
)instance
specifies the connection to
the instance which should become the new primary. From
MySQL Shell 8.0.29, 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:
,
which switches the cluster to multi-primary mode. All
instances become primaries.
Cluster
.switchToMultiPrimaryMode()
,
which switches the cluster to single-primary mode. If
Cluster
.switchToSinglePrimaryMode([instance
])instance
is specified, it becomes
the primary and all the other instances become secondaries.
If instance
is 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
method, as in the following example:
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.
You can optionally pass in the interactive
option to control whether you are prompted to confirm the
removal of the instance from the cluster. In interactive mode,
you are prompted to continue with the removal of the instance
(or not) in case it is not reachable. The
operation ensures that the instance is removed from the metadata
of all the cluster members which are 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.
The force
option of
forces removal of the instance from the Cluster's
metadata. This is useful if the instance is no longer a
member, but is still registered as part of the Cluster. This
option has no effect on healthy, contactable instances, and
affects only unreachable instances or instances which are
otherwise unable to synchronize with the Cluster.
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
command. This removes all metadata and configuration associated
with the cluster, and disables Group Replication on the
instances. Any data that was replicated between the instances is
not removed.
Cluster
.dissolve()
There is no way to undo the dissolving of a cluster. To create
it again use dba.createCluster()
.
The
operation can only configure instances which are
Cluster
.dissolve()ONLINE
or reachable. If members of a cluster
cannot be reached by the member where you issued the
command you have to decide how the dissolve operation should
proceed. If there is any chance you want to rejoin any instances
that are identified as missing from the cluster, it is strongly
recommended to cancel the dissolve operation and first bring the
missing instances back online, before proceeding with a dissolve
operation. This ensures that all instances can have their
metadata updated correctly, and that there is no chance of a
split-brain situation. However, if the instances from the
cluster which cannot be reached have permanently left the
cluster there could be no choice but to force the dissolve
operation, which means that the missing instances are ignored
and only online instances are affected by the operation.
Cluster
.dissolve()
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
operation using 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.
You can also use the interactive
option with
the
operation to override the mode which MySQL Shell is running in,
for example to make the interactive prompt appear when running a
batch script. For example:
Cluster
.dissolve()
mysql-js> Cluster
.dissolve({interactive: true})
The dba.gtidWaitTimeout
MySQL Shell option
configures how long the
operation waits for cluster transactions to be applied before
removing a target instance from the cluster, but only if the
target instance is 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.
After issuing cluster.dissolve()
, any
variable assigned to the
object
is no longer valid.
Cluster