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, including Read Replicas, 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. If a primary is unavailable, a connection is made to a secondary.