6.12 Locking Mechanism for AdminAPI Operations

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:

• DBA Locking: lists the locks for dba.operationName operations.

• InnoDB Cluster Locking: lists the locks for Cluster.operationName operations.

• InnoDB ClusterSet Locking: lists the locks for ClusterSet.operationName operations.

• InnoDB ReplicaSet Locking: lists the locks for ReplicaSet.operationName operations.

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
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.

InnoDB 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
execute()	Shared
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

InnoDB 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.
execute()	Shared	Shared	Shared on all replica clusters.
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	ReplicaSet Lock Type	Primary Instance Lock Type	Target Instance Lock Type
addInstance()	Exclusive		Exclusive
dissolve()	Exclusive
execute()	Shared
forcePrimaryInstance()	Exclusive
rejoinInstance()	Shared		Exclusive
removeInstance()	Exclusive		Exclusive
removeRouterMetadata()		Shared
rescan()	Exclusive
setInstanceOption()			Exclusive
setOption()	Exclusive
setPrimaryInstance()	Exclusive
setupAdminAccount()	Shared
setupRouterAccount()	Shared