2.3.16.1 Ndb_cluster_connection Methods

2.3.16.1.1 Ndb_cluster_connection Class Constructor
2.3.16.1.2 Ndb_cluster_connection::connect()
2.3.16.1.3 Ndb_cluster_connection::get_auto_reconnect()
2.3.16.1.4 Ndb_cluster_connection::get_latest_error()
2.3.16.1.5 Ndb_cluster_connection::get_latest_error_msg()
2.3.16.1.6 ndb_cluster_connection::get_next_ndb_object()
2.3.16.1.7 ndb_cluster_connection::lock_ndb_objects()
2.3.16.1.8 Ndb_cluster_connection::set_auto_reconnect()
2.3.16.1.9 Ndb_cluster_connection::set_name()
2.3.16.1.10 Ndb_cluster_connection::set_optimized_node_selection()
2.3.16.1.11 Ndb_cluster_connection::set_timeout()
2.3.16.1.12 ndb_cluster_connection::unlock_ndb_objects()
2.3.16.1.13 Ndb_cluster_connection::wait_until_ready()

This section describes the methods belonging to the Ndb_cluster_connection class.

2.3.16.1.1 Ndb_cluster_connection Class Constructor

Description.  This method creates a connection to a MySQL cluster, that is, to a cluster of data nodes. The object returned by this method is required in order to instantiate an Ndb object. (See Section 2.3.15, “The Ndb Class”.) Thus, every NDB API application requires the use of an Ndb_cluster_connection.

Prior to MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, Ndb_cluster_connection had a single constructor, whose signature is shown here:

Signature. 

Ndb_cluster_connection
    (
      const char* connection_string = 0
    )

Parameters.  This version of the constructor requires a single connection_string parameter, pointing to the location of the management server.

Beginning with MySQL Cluster NDB 7.0.15 and MySQL Cluster NDB 7.1.4, a second constructor is provided which takes a node ID in addition to the connection string argument. Its signature and parameters are shown here:

Signature. 

Ndb_cluster_connection
    (
      const char* connection_string, 
      int force_api_nodeid
    )

Parameters.  This version of the constructor takes two arguments, a connection_string and the node ID (force_api_nodeid) to be used by this API node. This node ID overrides any node ID value set in the connection_string argument.

Return value.  (Both versions:) An instance of Ndb_cluster_connection.

2.3.16.1.2 Ndb_cluster_connection::connect()

Description.  This method connects to a cluster management server.

Signature. 

int connect
    (
      int retries = 30,
      int delay   = 1,
      int verbose = 0
    )

Parameters.  This method takes three parameters, all of which are optional:

  • retries specifies the number of times to retry the connection in the event of failure. Beginning with MySQL Cluster NDB 7.0.27 and MySQL Cluster NDB 7.1.6, the default value is 30. (Previously the default was 0.)

    0 means that no additional attempts to connect are made in the event of failure; using a negative value for retries results in the connection attempt being repeated indefinitely.

  • The delay represents the number of seconds between reconnect attempts; the default is 1 second.

  • verbose indicates whether the method should output a report of its progress, with 1 causing this reporting to be enabled; the default is 0 (reporting disabled).

Return value.  This method returns an int, which can have one of the following 3 values:

  • 0: The connection attempt was successful.

  • 1: Indicates a recoverable error.

  • -1: Indicates an unrecoverable error.

2.3.16.1.3 Ndb_cluster_connection::get_auto_reconnect()

Description.  Introduced in MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7, this method retrieves the current AutoReconnect setting for a given Ndb_cluster_connection. For more detailed information, see Section 2.3.16.1.8, “Ndb_cluster_connection::set_auto_reconnect()”.

Signature. 

int get_auto_reconnect
    (
      void
    )

Parameters.  None.

Return value.  An integer value 0 or 1, corresponding to the current AutoReconnect setting in effect for for this connection. 0 forces API nodes to use new connections to the cluster, while 1 enables API nodes to re-use existing connections.

2.3.16.1.4 Ndb_cluster_connection::get_latest_error()

Description.  This method was introduced in MySQL Cluster NDB 6.3.20 and MySQL Cluster NDB 6.4.0. It can be used to determine whether or not the most recent connect() attempt made by this Ndb_cluster_connection succeeded . If the connection succeeded, get_latest_error() returns 0; otherwise, it returns 1. If the connection attempt failed, use Ndb_cluster_connection::get_latest_error_msg() to obtain an error message giving the reason for the failure.

Signature. 

int get_latest_error
    (
      void
    ) const

Parameters.  None.

Return value.  1 or 0. A return value of 1 indicates that the latest attempt to connect failed; if the attempt succeeded, a 0 is returned.

2.3.16.1.5 Ndb_cluster_connection::get_latest_error_msg()

Description.  If the most recent connection attempt by this Ndb_cluster_connection failed (as determined by calling get_latest_error()), this method provides an error message supplying information about the reason for the failure.

Signature. 

const char* get_latest_error_msg
    (
      void
    ) const

Parameters.  None.

Return value.  A string containing an error message describing a failure by Ndb_cluster_connection::connect(). If the most recent connection attempt succeeded, an empty string is returned.

2.3.16.1.6 ndb_cluster_connection::get_next_ndb_object()

Description.  This method is used to iterate over a set of Ndb objects, retrieving them one at a time.

Signature. 

const Ndb* get_next_ndb_object
    (
      const Ndb* p
    )

Parameters.  This method takes a single parameter, a pointer to the last Ndb object to have been retrieved or NULL.

Return value.  Returns the next Ndb object, or NULL if no more Ndb objects are available.

Iterating over Ndb objects.  To retrieve all existing Ndb objects, perform the following three steps:

  1. Invoke the lock_ndb_objects() method. This prevents the creation of any new instances of Ndb until the unlock_ndb_objects() method is called.

  2. Retrieve the first available Ndb object by passing NULL to get_next_ndb_object(). You can retrieve the second Ndb object by passing the pointer retrieved by the first call to the next get_next_ndb_object() call, and so on. When a pointer to the last available Ndb instance is used, the method returns NULL.

  3. After you have retrieved all desired Ndb objects, you should re-enable Ndb object creation by calling the unlock_ndb_objects() method.

2.3.16.1.7 ndb_cluster_connection::lock_ndb_objects()

Description.  Calling this method prevents the creation of new instances of the Ndb class. This method must be called prior to iterating over multiple Ndb objects using get_next_ndb_object().

Signature. 

void lock_ndb_objects
    (
      void
    )

Parameters.  None.

Return value.  None.

This method was added in MySQL Cluster NDB 6.1.4. For more information, see Section 2.3.16.1.6, “ndb_cluster_connection::get_next_ndb_object()”.

2.3.16.1.8 Ndb_cluster_connection::set_auto_reconnect()

Description.  Prior to MySQL Cluster NDB 6.3.26 and MySQL Cluster NDB 7.0.7, an API node that was disconnected from the cluster tried to re-use an existing Ndb_cluster_connection object when reconnecting; however, it was discovered that permitting this also sometimes made it possible for multiple API nodes to try to connect using the same node ID during a restart of the cluster. (Bug #45921) Beginning with these versions, API nodes are instead forced to use a new connection object, unless this behavior is overridden by setting AutoReconnect = 1 in the config.ini file or calling this method with 1 as the input value. Calling the method with 0 for the value has the same effect as setting the AutoReconnect configuration parameter (also introduced in those MySQL Cluster versions) to 0; that is, API nodes are forced to create new connections.

Important

When called, this method overrides any setting for AutoReconnect made in the config.ini file.

For more information, see Defining SQL and Other API Nodes in a MySQL Cluster.

Signature. 

void set_auto_reconnect
    (
      int value
    )

Parameters.  A value of 0 or 1 which determines API node reconnection behavior. 0 forces API nodes to use new connections (Ndb_cluster_connection objects); 1 permits API nodes to re-use existing connections to the cluster.

Return value.  None.

2.3.16.1.9 Ndb_cluster_connection::set_name()

Description.  Sets a name for the connection. If the name is specified, it is reported in the cluster log.

Signature. 

void set_name
    (
      const char* name
    )

Parameters.  The name to be used as an identifier for the connection.

Return value.  None.

2.3.16.1.10 Ndb_cluster_connection::set_optimized_node_selection()

Description.  This method can be used to override the connect() method's default behavior as regards which node should be connected to first.

Signature. 

void set_optimized_node_selection
    (
      int value
    )

Parameters.  An integer value.

Return value.  None.

2.3.16.1.11 Ndb_cluster_connection::set_timeout()

Description.  Used to set a timeout for the connection, to limit the amount of time that we may block when connecting.

This method is actually a wrapper for the function ndb_mgm_set_timeout(). For more information, see Section 3.2.4.12, “ndb_mgm_set_timeout()”.

Signature. 

int set_timeout
    (
      int timeout_ms
    )

Parameters.  The length of the timeout, in milliseconds (timeout_ms). Currently, only multiples of 1000 are accepted.

Return value.  0 on success; any other value indicates failure.

2.3.16.1.12 ndb_cluster_connection::unlock_ndb_objects()

Description.  This method undoes the effects of the lock_ndb_objects() method, making it possible to create new instances of Ndb. unlock_ndb_objects() should be called after you have finished retrieving Ndb objects using the get_next_ndb_object() method.

Signature. 

void unlock_ndb_objects
    (
      void
    )

Parameters.  None.

Return value.  None.

For more information, see Section 2.3.16.1.6, “ndb_cluster_connection::get_next_ndb_object()”.

2.3.16.1.13 Ndb_cluster_connection::wait_until_ready()

Description.  This method waits until the requested connection with one or more data nodes is successful.

Signature. 

int wait_until_ready
    (
      int timeoutBefore,
      int timeoutAfter
    )

Parameters.  This method takes two parameters:

  • timeoutBefore determines the number of seconds to wait until the first live node is detected. If this amount of time is exceeded with no live nodes detected, then the method immediately returns a negative value.

  • timeoutAfter determines the number of seconds to wait after the first live node is detected for all nodes to become active. If this amount of time is exceeded without all nodes becoming active, then the method immediately returns a value greater than zero.

If this method returns 0, then all nodes are live.

Return value.  wait_until_ready() returns an int, whose value is interpreted as follows:

  • = 0: All nodes are live.

  • > 0: At least one node is live (however, it is not known whether all nodes are live).

  • < 0: An error occurred.