As of version 8.0.33, AdminAPI extends the locking mechanism introduced for InnoDB ReplicaSet in 8.0.20 to InnoDB Cluster and InnoDB ClusterSet.
Previously, different instances of MySQL Shell could connect and
process AdminAPI operations simultaneously on the same resource.
This could lead to inconsistent states and errors, for example, if
and
Cluster
.addInstance()
were processed in parallel.
Cluster
.setPrimaryInstance()
AdminAPI uses the MySQL Locking Service to provide the following locking types:
Read or shared lock: allows concurrent execution of some operations while blocking exclusive operations. If an operation attempts to acquire a shared lock, but cannot, due to the presence of an exclusive lock, the operation is aborted without making any changes. If the current operation has a shared lock, and the new operation requires a shared lock, the new operation is allowed access.
Write or exclusive lock: blocks execution of all other operations until the current operation is complete and the exclusive lock is released. If an operation attempts to acquire an exclusive lock, but cannot, due to the presence of an existing lock, the operation is aborted without making any changes.
See The Locking Service for more information.
The following tables list the locking per AdminAPI operation:
DBA Locking: lists the locks for
dba.
operations.operationName
Cluster Locking: lists the locks for
operations.Cluster
.operationName
ClusterSet Locking: lists the locks for
operations.ClusterSet
.operationName
InnoDB ReplicaSet Locking: lists the locks for
operations.ReplicaSet
.operationName
Operations which do not require locks are not listed.
In practice, if you try to perform an operation while another operation that cannot be performed concurrently is still running, you get an error indicating that a lock on a needed resource could not be acquired. In this case, you should wait for the running operation which holds the lock to complete, and only then try to process the next operation. For example:
mysql-js> rs.addInstance("admin@rs2:3306");
ERROR: The operation cannot be executed because it failed to acquire the lock on
instance 'rs1:3306'. Another operation requiring exclusive access to the
instance is still in progress, please wait for it to finish and try again.
ReplicaSet.addInstance: Failed to acquire lock on instance 'rs1:3306' (MYSQLSH
51400)
In this example,
failed because a lock on the primary instance
(ReplicaSet
.addInstance()rs1:3306
) could not be acquired, because a
operation (or other similar operation) was still running.
ReplicaSet
.setPrimaryInstance()
If an instance restarts as part of a clone operation or a requested restart, the lock is released. As a result, there is a short period, measured in milliseconds, when another Shell session could gain access to the instance on restart and lock it. However, the original locks on Cluster and/or ClusterSet remain, so a new command which could lock the newly restarted instance cannot request Cluster or ClusterSet locks.
This section lists the locks for
operations.
dba
.operationName
Table 6.1 DBA Operation Locks
Operation | Lock Type |
---|---|
|
Exclusive on the target instance |
|
Exclusive on the target instance |
|
Exclusive on the target instance |
|
Exclusive on all contactable cluster members.
If the cluster is a replica cluster, and part of a
ClusterSet, it is also rejoined to the ClusterSet as
part of the operation. In this scenario, the operation
also acquires the same locks as
|
|
|
|
Exclusive lock on the target instance. |
|
Exclusive lock on the target instance. |
|
Exclusive lock on the ClusterSet and primary cluster, if the topology is a ClusterSet, or on the Cluster, if the topology is a standalone cluster, and on the target instance. |
This section lists the locks for
operations.
cluster
.operationName
Table 6.2 Cluster Operation Locks
Operation | Cluster Lock Type | Target Instance Lock Type |
---|---|---|
|
Exclusive |
Exclusive |
|
Exclusive |
|
|
Exclusive |
|
|
Exclusive |
|
|
Exclusive |
|
|
Exclusive |
|
|
Shared |
Exclusive |
|
Exclusive |
Exclusive |
|
Exclusive |
|
|
Exclusive |
|
|
Exclusive
Except for the options |
|
|
Exclusive
Except for the options |
|
|
Exclusive |
|
|
Shared |
|
|
Shared |
|
|
Exclusive |
|
|
Exclusive |
|
|
Exclusive |
This section lists the locks for
operations.
clusterSet
.operationName
Table 6.3 ClusterSet Operation Locks
Operation | ClusterSet Lock Type | Primary Cluster Lock Type | Target Cluster Lock Type |
---|---|---|---|
|
Shared |
Exclusive on the instance used to create the new replica cluster. |
|
|
Exclusive on all replica clusters. |
||
|
Shared |
Shared | Exclusive |
|
Exclusive. |
Exclusive |
Exclusive |
|
Exclusive |
Exclusive
(only if |
|
|
Exclusive |
Exclusive |
This section lists the locks for
operations.
replicaSet
.operationName
Table 6.4 ReplicaSet Operation Locks
Operation | Primary Instance Lock Type | Target Instance Lock Type |
---|---|---|
|
Exclusive on target instance and on all contactable members of the ReplicaSet at the time of the operation. |
|
|
Exclusive |
Exclusive on target instance and on all contactable members of the ReplicaSet at the time of the operation. |
|
Shared |
Exclusive |
|
Shared | Exclusive |
|
Shared |
Exclusive |
|
Shared |