6.3 Retrieving a Handler Object

When you are working with AdminAPI, you use a handler object which represents the InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet. You assign this object to a variable, and then use the operations available to monitor and administer the InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet.

To retrieve the handler object, you establish a connection to one of the active instances which belong to the InnoDB Cluster, InnoDB ClusterSet, or InnoDB ReplicaSet. For example, when you create a cluster using dba.createCluster(), the operation returns a Cluster object which can be assigned to a variable. You use this handler object to work with the cluster. For example, to add instances or check the cluster's status. If you want to retrieve a Cluster object again at a later date, for example after restarting MySQL Shell, use the dba.getCluster([name],[options]) function. For example, using JavaScript:

mysql-js> var cluster1 = dba.getCluster()

Or using Python:

mysql-py> cluster1 = dba.get_cluster()

To retrieve the ClusterSet object representing an InnoDB ClusterSet deployment, use the dba.getClusterSet() or cluster.getClusterSet() function. For example, using JavaScript:

mysql-js> myclusterset = dba.getClusterSet()

Or using Python:

mysql-py> myclusterset = dba.get_cluster_set()

Note

When you use a ClusterSet object, the server instance from which you got it must still be online in the InnoDB ClusterSet. If that server instance goes offline, the object no longer works, and you need to get it again from a server that is still online in the InnoDB ClusterSet.

Use the dba.getReplicaSet() operation to retrieve a ReplicaSet object. For example, using JavaScript:

mysql-js> var replicaset1 = dba.getReplicaSet()

Or using Python:

mysql-py> replicaset1 = dba.get_replica_set()

If you do not specify a name then the default object is returned. The returned object uses a new session, independent from MySQL Shell's global session. This ensures that if you change the MySQL Shell global session, the Cluster, ClusterSet, or ReplicaSet object maintains its session to the server instance.

By default MySQL Shell attempts to connect to the primary instance when you retrieve a handler. Set the connectToPrimary option to configure this behavior.

• If connectToPrimary is true and the active global MySQL Shell session is not to a primary instance, MySQL Shell queries for the primary instance. If there is no quorum in a cluster, the operation fails.

• If connectToPrimary is false, the retrieved object uses the server instance specified for the active session, in other words the same instance as MySQL Shell's current global session.

• If connectToPrimary is not specified, MySQL Shell treats connectToPrimary as true, and falls back to connectToPrimary being false.

To force connecting to a secondary, establish a connection to the secondary instance and use the connectToPrimary option by issuing the following in JavaScript:

mysql-js> shell.connect(secondary_member)
mysql-js> var cluster1 = dba.getCluster(testCluster, {connectToPrimary:false})

WARNING: You are connected to an instance in state 'Read Only'
Write operations on the InnoDB cluster will not be allowed.

<Cluster:testCluster>

Or, by issuing the following in Python:

mysql-py> shell.connect(secondary_member)	
mysql-py> cluster1 = dba.get_cluster(testCluster, connectToPrimary='false')

WARNING: You are connected to an instance in state 'Read Only'
Write operations on the InnoDB cluster will not be allowed.

<Cluster:testCluster>

Note

Secondary instances have super_read_only=ON, so you cannot write changes to them.