MySQL Shell 8.0 (part of MySQL 8.0)
This section explains how to work with InnoDB Cluster, and how to handle common administration tasks.
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.
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 10.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 should only be used with
when you want to ignore any errors, for example unprocessed
transactions or an instance being
Cluster
.removeInstance(instance
)UNREACHABLE
, and do not plan to reuse the
instance with the cluster. Ignoring errors when removing an
instance from the cluster could result in an instance which
is not in synchrony with the cluster, preventing it from
rejoining the cluster at a later time. Only use the
force
option when you plan to no longer
use the instance with the cluster, in all other cases you
should always try to recover the instance and only remove it
when it is available and healthy, in other words with the
status ONLINE
.
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
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 UDFs 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 to become the new primary, use the
function, where Cluster
.setPrimaryInstance(instance
)instance
specifies
the connection to the instance which should become the new
primary. This enables you to configure the underlying Group
Replication group to choose a specific instance as the new
primary, bypassing the election process.
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).