MySQL Shell 8.0  /  ...  /  Retrieving a Handler Object

6.1.6 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 be able 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 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:

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

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

mysql-js> myclusterset = dba.getClusterSet()

Note that 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 will 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:

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

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:

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

Remember that secondary instances have super_read_only=ON, so you cannot write changes to them.