MySQL Shell 8.0  /  MySQL AdminAPI  /  Locking Mechanism for AdminAPI Operations

6.12 Locking Mechanism for AdminAPI Operations

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 Cluster.addInstance() and Cluster.setPrimaryInstance() were processed in parallel.

Locking Types

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:

Note

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, ReplicaSet.addInstance() failed because a lock on the primary instance (rs1:3306) could not be acquired, because a ReplicaSet.setPrimaryInstance() operation (or other similar operation) was still running.

Note

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.

DBA Locking

This section lists the locks for dba.operationName operations.

Table 6.1 DBA Operation Locks

Operation Lock Type

configureInstance()

Exclusive on the target instance

configureLocalInstance()

Exclusive on the target instance

createCluster()

Exclusive on the target instance

rebootClusterFromCompleteOutage()

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 clusterset.rejoinCluster().

upgradeMetadata()

  • Cluster: Exclusive lock on the Cluster and on the target instance.

  • ClusterSet: Exclusive lock on the ClusterSet, primary Cluster, and the target instance.

createReplicaSet()

Exclusive lock on the target instance.

configureReplicaSetInstance()

Exclusive lock on the target instance.

upgradeMetadata()

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.


Cluster Locking

This section lists the locks for cluster.operationName operations.

Table 6.2 Cluster Operation Locks

Operation Cluster Lock Type Target Instance Lock Type

addInstance()

Exclusive

Exclusive

createClusterSet()

Exclusive

dissolve()

Exclusive

fenceAllTraffic()

Exclusive

fenceWrites()

Exclusive

forceQuorum()

Exclusive

rejoinInstance()

Shared

Exclusive

removeInstance()

Exclusive

Exclusive

rescan()

Exclusive

resetRecoveryAccountsPassword()

Exclusive

setInstanceOption()

Exclusive

Except for the options tag and clusterName.

setOption()

Exclusive

Except for the options tag and clusterName.

setPrimaryInstance()

Exclusive

setupAdminAccount()

Shared

setupRouterAccount()

Shared

switchToMultiPrimaryMode()

Exclusive

switchToSinglePrimaryMode()

Exclusive

unfenceWrites()

Exclusive


ClusterSet Locking

This section lists the locks for clusterSet.operationName operations.

Table 6.3 ClusterSet Operation Locks

Operation ClusterSet Lock Type Primary Cluster Lock Type Target Cluster Lock Type

createReplicaCluster()

Shared

Exclusive on the instance used to create the new replica cluster.

forcePrimaryCluster()

Exclusive on all replica clusters.

rejoinCluster()

Shared

Shared

Exclusive

removeCluster()

Exclusive.

Exclusive

Exclusive

setOption()

Exclusive

Exclusive

(only if replicationAllowedHost is set)

setPrimaryCluster()

Exclusive

Exclusive


InnoDB ReplicaSet Locking

This section lists the locks for replicaSet.operationName operations.

Table 6.4 ReplicaSet Operation Locks

Operation Primary Instance Lock Type Target Instance Lock Type

forcePrimaryInstance()

Exclusive on target instance and on all contactable members of the ReplicaSet at the time of the operation.

setPrimaryInstance()

Exclusive

Exclusive on target instance and on all contactable members of the ReplicaSet at the time of the operation.

addInstance()

Shared

Exclusive

rejoinInstance()

Shared

Exclusive

removeInstance()

Shared

Exclusive

removeRouterMetadata()

Shared