Documentation Home
MySQL Cluster API Developer Guide
Download this Manual
PDF (US Ltr) - 4.8Mb
PDF (A4) - 4.8Mb
EPUB - 1.9Mb
HTML Download (TGZ) - 1.8Mb
HTML Download (Zip) - 1.9Mb

MySQL Cluster API Developer Guide  /  ...  /  The Ndb_cluster_connection Class

2.3.17 The Ndb_cluster_connection Class


This class represents a connection to a cluster of data nodes.

Parent class. None

Child classes. None

Description. An NDB application program should begin with the creation of a single Ndb_cluster_connection object, and typically makes use of a single Ndb_cluster_connection. The application connects to a cluster management server when this object's connect() method is called. By using the wait_until_ready() method it is possible to wait for the connection to reach one or more data nodes.


An instance of Ndb_cluster_connection used to create an Ndb object. Prior to MySQL Cluster 7.3.8 and MySQL Cluster NDB 7.4.3, it was possible to delete the Ndb_cluster_connection used to create a given instance of Ndb without first deleting the dependent Ndb object. (Bug #19999242)

Application-level partitioning. There is no restriction against instantiating multiple Ndb_cluster_connection objects representing connections to different management servers in a single application, nor against using these for creating multiple instances of the Ndb class. Such Ndb_cluster_connection objects (and the Ndb instances based on them) are not required even to connect to the same cluster.

For example, it is entirely possible to perform application-level partitioning of data in such a manner that data meeting one set of criteria are handed off to one cluster using an Ndb object that makes use of an Ndb_cluster_connection object representing a connection to that cluster, while data not meeting those criteria (or perhaps a different set of criteria) can be sent to a different cluster through a different instance of Ndb that makes use of an Ndb_cluster_connection pointing to the second cluster.

It is possible to extend this scenario to develop a single application that accesses an arbitrary number of clusters. However, in doing so, the following conditions and requirements must be kept in mind:

  • A cluster management server (ndb_mgmd) can connect to one and only one cluster without being restarted and reconfigured, as it must read the data telling it which data nodes make up the cluster from a configuration file (config.ini).

  • An Ndb_cluster_connection object belongs to a single management server whose host name or IP address is used in instantiating this object (passed as the connection_string argument to its constructor); once the object is created, it cannot be used to initiate a connection to a different management server.

    (See Section, “Ndb_cluster_connection Class Constructor”.)

  • An Ndb object making use of this connection (Ndb_cluster_connection) cannot be re-used to connect to a different cluster management server (and thus to a different collection of data nodes making up a cluster). Any given instance of Ndb is bound to a specific Ndb_cluster_connection when created, and that Ndb_cluster_connection is in turn bound to a single and unique management server when it is instantiated.

    (See Section, “Ndb Class Constructor”.)

  • The bindings described above persist for the lifetimes of the Ndb and Ndb_cluster_connection objects in question.

Therefore, it is imperative in designing and implementing any application that accesses multiple clusters in a single session, that a separate set of Ndb_cluster_connection and Ndb objects be instantiated for connecting to each cluster management server, and that no confusion arises as to which of these is used to access which MySQL Cluster.

It is also important to keep in mind that no direct sharing of data or data nodes between different clusters is possible. A data node can belong to one and only one cluster, and any movement of data between clusters must be accomplished on the application level.

For examples demonstrating how connections to two different clusters can be made and used in a single application, see Section 2.4.2, “NDB API Example Using Synchronous Transactions and Multiple Clusters”, and Section 3.5.2, “MGM API Event Handling with Multiple Clusters”.

Methods. The following table lists the public methods of this class and the purpose or use of each method:

Method Purpose / Use
Ndb_cluster_connection() Constructor; creates a connection to a cluster of data nodes.
connect() Connects to a cluster management server.

Gets the auto-reconnection setting for API nodes using this Ndb_cluster_connection.


Whether or not the most recent attempt to connect succeeded.


If the most recent attempt to connect failed, provides the reason.


Used to iterate through multiple Ndb objects.


Disables the creation of new Ndb objects.


Enables or disables auto-reconnection of API nodes using this Ndb_cluster_connection.

set_name() Provides a name for the connection
set_optimized_node_selection() Used to control node-selection behavior.
set_timeout() Sets a connection timeout

Enables the creation of new Ndb objects.

wait_until_ready() Waits until a connection with one or more data nodes is successful.

For detailed descriptions, signatures, and examples of use for each of these methods, see Section, “Ndb_cluster_connection Methods”.

Class diagram. This diagram shows all the available methods of the Ndb_cluster_connection class:

Figure 2.12 Ndb_cluster_connection

Public methods of the Ndb_cluster_connection class.

Download this Manual
PDF (US Ltr) - 4.8Mb
PDF (A4) - 4.8Mb
EPUB - 1.9Mb
HTML Download (TGZ) - 1.8Mb
HTML Download (Zip) - 1.9Mb
User Comments
Sign Up Login You must be logged in to post a comment.