2.3.15.1 Ndb Methods

2.3.15.1.1 Ndb Class Constructor
2.3.15.1.2 Ndb::closeTransaction()
2.3.15.1.3 Ndb::computeHash()
2.3.15.1.4 Ndb::createEventOperation()
2.3.15.1.5 Ndb::dropEventOperation()
2.3.15.1.6 Ndb::getDictionary()
2.3.15.1.7 Ndb::getDatabaseName()
2.3.15.1.8 Ndb::getDatabaseSchemaName()
2.3.15.1.9 Ndb::getGCIEventOperations()
2.3.15.1.10 Ndb::getNdbError()
2.3.15.1.11 Ndb::getNdbErrorDetail()
2.3.15.1.12 Ndb::getNdbObjectName()
2.3.15.1.13 Ndb::getReference()
2.3.15.1.14 Ndb::init()
2.3.15.1.15 Ndb::isConsistent()
2.3.15.1.16 Ndb::nextEvent()
2.3.15.1.17 Ndb::pollEvents()
2.3.15.1.18 Ndb::setDatabaseName()
2.3.15.1.19 Ndb::setDatabaseSchemaName()
2.3.15.1.20 Ndb::setNdbObjectName()
2.3.15.1.21 Ndb::startTransaction()

Abstract

The sections that follow discuss the public methods of the Ndb class.

2.3.15.1.1 Ndb Class Constructor

Description.  This creates an instance of Ndb, which represents a connection to the MySQL Cluster. All NDB API applications should begin with the creation of at least one Ndb object. This requires the creation of at least one instance of Ndb_cluster_connection, which serves as a container for a cluster connection string.

Signature. 

Ndb
    (
      Ndb_cluster_connection* ndb_cluster_connection,
      const char*                    catalogName = "",
      const char*                    schemaName = "def"
    )

Parameters.  The Ndb class constructor can take up to 3 parameters, of which only the first is required:

  • ndb_cluster_connection is an instance of Ndb_cluster_connection, which represents a cluster connection string. (See Section 2.3.16, “The Ndb_cluster_connection Class”.)

  • catalogName is an optional parameter providing a namespace for the tables and indexes created in any connection from the Ndb object.

    This is equivalent to what mysqld considers the database.

    The default value for this parameter is an empty string.

  • The optional schemaName provides an additional namespace for the tables and indexes created in a given catalog.

    The default value for this parameter is the string def.

Return value.  An Ndb object.

~Ndb() (Class Destructor).  The destructor for the Ndb class should be called in order to terminate an instance of Ndb. It requires no arguments, nor any special handling.

2.3.15.1.2 Ndb::closeTransaction()

Description.  This is one of two NDB API methods provided for closing a transaction (the other being NdbTransaction::close()). You must call one of these two methods to close the transaction once it has been completed, whether or not the transaction succeeded.

Important

If the transaction has not yet been committed, it is aborted when this method is called. See Section 2.3.15.1.21, “Ndb::startTransaction().

Signature. 

void closeTransaction
    (
      NdbTransaction *transaction
    )

Parameters.  This method takes a single argument, a pointer to the NdbTransaction to be closed.

Return value.  N/A.

2.3.15.1.3 Ndb::computeHash()

Description.  This method can be used to compute a distribution hash value, given a table and its keys.

Important

computeHash() can be used only for tables that use native NDB partitioning.

Signature. 

static int computeHash
    (
      Uint32*                     hashvalueptr,
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

Parameters.  This method takes the following parameters:

  • If the method call is successful, hashvalueptr is set to the computed hash value.

  • A pointer to a table (see Section 2.3.36, “The Table Class”).

  • keyData is a null-terminated array of pointers to the key parts that are part of the table's distribution key. The length of each key part is read from metadata and checked against the passed value (see Section 2.3.14, “The Key_part_ptr Structure”).

  • xfrmbuf is a pointer to temporary buffer used to calculate the hash value.

  • xfrmbuflen is the length of this buffer.

    Note

    If xfrmbuf is NULL (the default), then a call to malloc() or free() is made automatically, as appropriate. computeHash() fails if xfrmbuf is not NULL and xfrmbuflen is too small.

    Previously, it was assumed that the memory returned by the malloc() call would always be suitably aligned, which is not always the case. Beginning with MySQL Cluster NDB versions 7.0.38, 7.1.27, 7.2.13, and 7.3.2, when malloc() provides a buffer to this method, the buffer is explicitly aligned after it is allocated, and before it is actually used. (Bug #16484617)

Return value.  0 on success, an error code on failure. (If the method call succeeds, the computed hash value is made available via hashvalueptr.)

2.3.15.1.4 Ndb::createEventOperation()

Description.  This method creates a subscription to a database event.

Note

NDB API event subscriptions do not persist after a MySQL Cluster has been restored using ndb_restore; in such cases, all of the subscriptions must be recreated explicitly.

Signature. 

NdbEventOperation* createEventOperation
    (
      const char *eventName
    )

Parameters.  This method takes a single argument, the unique eventName identifying the event to which you wish to subscribe.

Return value.  A pointer to an NdbEventOperation object (or NULL, in the event of failure). See Section 2.3.20, “The NdbEventOperation Class”.

2.3.15.1.5 Ndb::dropEventOperation()

Description.  This method drops a subscription to a database event represented by an NdbEventOperation object.

Signature. 

int dropEventOperation
    (
      NdbEventOperation *eventOp
    )

Parameters.  This method requires a single input parameter, a pointer to an instance of NdbEventOperation.

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

2.3.15.1.6 Ndb::getDictionary()

Description.  This method is used to obtain an object for retrieving or manipulating database schema information. This Dictionary object contains meta-information about all tables in the cluster.

Note

The dictionary returned by this method operates independently of any transaction. See Section 2.3.4, “The Dictionary Class”, for more information.

Signature. 

NdbDictionary::Dictionary* getDictionary
    (
      void
    ) const

Parameters.  None.

Return value.  An instance of the Dictionary class.

2.3.15.1.7 Ndb::getDatabaseName()

Description.  This method can be used to obtain the name of the current database.

Signature. 

const char* getDatabaseName
    (
      void
    )

Parameters.  None.

Return value.  The name of the current database.

2.3.15.1.8 Ndb::getDatabaseSchemaName()

Description.  This method can be used to obtain the current database schema name.

Signature. 

const char* getDatabaseSchemaName
    (
      void
    )

Parameters.  None.

Return value.  The name of the current database schema.

2.3.15.1.9 Ndb::getGCIEventOperations()

Description.  Iterates over distinct event operations which are part of the current GCI, becoming valid after calling nextEvent(). You can use this method to obtain summary information for the epoch (such as a list of all tables) before processing the event data.

Signature. 


const NdbEventOperation* getGCIEventOperations
    (
      Uint32* iter, 
      Uint32* event_types
    )

Parameters.  An iterator and a mask of event types. Set *iter=0 to start.

Return value.  The next event operation; returns NULL when there are no more event operations. If event_types is not NULL, then after calling the method it contains a bitmask of the event types received. .

2.3.15.1.10 Ndb::getNdbError()

Description.  This method provides you with two different ways to obtain an NdbError object representing an error condition. For more detailed information about error handling in the NDB API, see Chapter 7, MySQL Cluster API Errors.

Signature.  The getNdbError() method actually has two variants.

The first of these simply gets the most recent error to have occurred:

const NdbError& getNdbError
    (
      void
    )

The second variant returns the error corresponding to a given error code:

const NdbError& getNdbError
    (
      int errorCode
    )

Regardless of which version of the method is used, the NdbError object returned persists until the next NDB API method is invoked.

Parameters.  To obtain the most recent error, simply call getNdbError() without any parameters. To obtain the error matching a specific errorCode, invoke the method passing the code (an int) to it as a parameter. For a listing of NDB API error codes and corresponding error messages, see Section 7.2, “NDB API Errors and Error Handling”.

Return value.  An NdbError object containing information about the error, including its type and, where applicable, contextual information as to how the error arose. See Section 2.3.19, “The NdbError Structure”, for details.

2.3.15.1.11 Ndb::getNdbErrorDetail()

Description.  This method, introduced in MySQL Cluster NDB 6.2.19, MySQL Cluster NDB 6.3.29, and MySQL Cluster NDB 7.0.10, provides an easier and safer way to access any extra information about an error. Formerly, it was necessary to read these extra details from the NdbError object's details property, which is now deprecated in favor of getNdbErrorDetail() (Bug #48851). This method enables storage of such details in a user-supplied buffer, returning a pointer to the beginning of this buffer. In the event that the string containing the details exceeds the length of the buffer, it is truncated to fit.

getErrorDetail() makes it much simpler to determine the source of an error than reading NdbError.details, because this method provides the information in the form of a string. For example, in the case of a unique constraint violation (error 893), this string supplies the fully qualified name of the index where the problem originated, in the format database-name/schema-name/table-name/index-name, (NdbError.details, on the other hand, supplies only an index ID, and it is often not readily apparent to which table this index belongs.) Regardless of the type of error and details concerning this error, the string retrieved by getErrorDetail() is always null-terminated.

Signature.  The getNdbErrorDetail() method has the following signature:

const char* getNdbErrorDetail
            (
              const NdbError& error,
              char*           buffer,
              Uint32          bufferLength
            ) const

Parameters.  To obtain detailed information about an error, call getNdbErrorDetail() with a reference to the corresponding NdbError object, a buffer, and the length of this buffer (expressed as an unsigned 32-bit integer).

Return value.  When extra details about the error are available, this method returns a pointer to the beginning of the buffer supplied. As stated previously, if the string containing the details is longer than bufferLength, the string is truncated to fit. In the event that no addition details are available, getNdbErrorDetail() returns NULL.

2.3.15.1.12 Ndb::getNdbObjectName()

Description.  If a name was set for the Ndb object prior to its initialization, you can retrieve it using this method. Used for debugging.

Signature. 

const char* getNdbObjectName
    (
      void
    ) const

Parameters.  None.

Return value.  The Ndb object name, if one has been set using setNdbObjectName(). Otherwise, this method returns 0.

This method was added in MySQL Cluster NDB 7.1.32, MySQL Cluster NDB 7.2.17, and MySQL Cluster NDB 7.3.6. (Bug #18419907)

2.3.15.1.13 Ndb::getReference()

Description.  This method can be used to obtain a reference to a given Ndb object. This is the same value that is returned for a given operation corresponding to this object in the output of DUMP 2350. (See Section 8.2.3.9, “DUMP 2350, for an example.)

Signature. 

Uint32 getReference
    (
      void
    )

Parameters.  None.

Return value.  A 32-bit unsigned integer.

2.3.15.1.14 Ndb::init()

Description.  This method is used to initialize an Ndb object.

Signature. 

int init
    (
      int maxNoOfTransactions = 4
    )

Parameters.  The init() method takes a single parameter maxNoOfTransactions of type integer. This parameter specifies the maximum number of parallel NdbTransaction objects that can be handled by this instance of Ndb. The maximum permitted value for maxNoOfTransactions is 1024; if not specified, it defaults to 4.

Note

Each scan or index operation uses an extra NdbTransaction object.

Return value.  This method returns an int, which can be either of the following two values:

  • 0: indicates that the Ndb object was initialized successfully.

  • -1: indicates failure.

2.3.15.1.15 Ndb::isConsistent()

Description.  If a node failure occurs when resources are exhausted, events may be lost and the delivered event data might thus be incomplete. This method makes it possible to determine if this is the case by checking whether all events in a GCI are consistent.

Signature. 

bool isConsistentGCI
    (
      Uint64 gci
    )

or

bool isConsistentGCI
    (
      Uint64& gci
    )

Parameters.  A global checkpoint index (or a reference to one)..

Return value.  true if GCI is consistent; false indicates that the GCI may be possible inconsistent.

2.3.15.1.16 Ndb::nextEvent()

Description.  Returns the next event operation having data from a subscription queue.

Signature. 

NdbEventOperation* nextEvent
    (
      void
    )

Parameters.  None.

Return value.  This method returns an NdbEventOperation object representing the next event in a subscription queue, if there is such an event. If there is no event in the queue, it returns NULL instead. (See Section 2.3.20, “The NdbEventOperation Class”.)

Beginning with MySQL Cluster NDB 7.1.32, MySQL Cluster NDB 7.2.17, and MySQL Cluster NDB 7.3.6, this method clears inconsistent data events from the event queue when processing them. In order to able to clear all such events in these and later versions, applications must call this method even in cases when pollEvents() has already returned 0. (Bug #18716991)

2.3.15.1.17 Ndb::pollEvents()

Description.  This method waits for a GCP to complete. It is used to determine whether any events are available in the subscription queue.

Beginning with MySQL Cluster NDB 6.2.5, this method waits for the next epoch, rather than the next GCP. See Section 2.3.20, “The NdbEventOperation Class”, for more information about the differences in event handling for this and later MySQL Cluster NDB 6.X and 7.X releases. releases.

Signature. 

int pollEvents
    (
      int     maxTimeToWait,
      Uint64* latestGCI = 0
    )

Parameters.  This method takes the two parameters listed here:

  • The maximum time to wait, in milliseconds, before giving up and reporting that no events were available (that is, before the method automatically returns 0).

  • The index of the most recent global checkpoint. Normally, this may safely be permitted to assume its default value, which is 0.

Return value.  pollEvents() returns a value of type int, which may be interpreted as follows:

  • > 0: There are events available in the queue.

  • 0: There are no events available.

  • < 0: Indicates failure (possible error).

2.3.15.1.18 Ndb::setDatabaseName()

Description.  This method is used to set the name of the current database.

Signature. 

void setDatabaseName
    (
      const char *databaseName
    )

Parameters.  setDatabaseName() takes a single, required parameter, the name of the new database to be set as the current database.

Return value.  N/A.

2.3.15.1.19 Ndb::setDatabaseSchemaName()

Description.  This method sets the name of the current database schema.

Signature. 

void setDatabaseSchemaName
    (
      const char *databaseSchemaName
    )

Parameters.  The name of the database schema.

Return value.  N/A.

2.3.15.1.20 Ndb::setNdbObjectName()

Description.  Starting with MySQL Cluster NDB 7.1.32, MySQL Cluster NDB 7.2.17, and MySQL Cluster NDB 7.3.6, you can set an arbitrary, human-readable name to identify an Ndb object for debugging purposes. This name can then be retrieved using getNdbObjectName(). (Bug #18419907) This must be done prior to calling init() for this object; trying to set a name after initialization fails with an error.

You can set a name only once for a given Ndb object; subsequent attempts after the name has already been set fail with an error.

Signature. 

int setNdbObjectName
    (
      const char* name
    )

Parameters.  A name that is intended to be human-readable.

Return value.  0 on success.

2.3.15.1.21 Ndb::startTransaction()

Description.  This method is used to begin a new transaction. There are three variants, the simplest of these using a table and a partition key or partition ID to specify the transaction coordinator (TC). The third variant makes it possible for you to specify the TC by means of a pointer to the data of the key.

Important

When the transaction is completed it must be closed using NdbTransaction::close() or Ndb::closeTransaction(). Failure to do so aborts the transaction. This must be done regardless of the transaction's final outcome, even if it fails due to an error.

See Section 2.3.15.1.2, “Ndb::closeTransaction(), and Section 2.3.29.2.1, “NdbTransaction::close(), for more information.

Signature. 

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table = 0,
      const char* keyData = 0,
      Uint32* keyLen = 0
    )

Parameters.  This method takes the following three parameters:

  • table: A pointer to a Table object. This is used to determine on which node the transaction coordinator should run.

  • keyData: A pointer to a partition key corresponding to table.

  • keyLen: The length of the partition key, expressed in bytes.

Distribution-aware forms of startTransaction() Beginning with MySQL Cluster NDB 6.1.4, it is possible to employ distribution awareness with this method; that is, to suggest which node should act as the transaction coordinator.

Signature. 

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      const struct Key_part_ptr*  keyData,
      void*                       xfrmbuf = 0,
      Uint32                      xfrmbuflen = 0
    )

Parameters.  When specifying the transaction coordinator, this method takes the four parameters listed here:

  • A pointer to a table (Table object) used for deciding which node should act as the transaction coordinator.

  • A null-terminated array of pointers to the values of the distribution key columns. The length of the key part is read from metadata and checked against the passed value.

    A Key_part_ptr is defined as shown in Section 2.3.14, “The Key_part_ptr Structure”.

  • A pointer to a temporary buffer, used to calculate the hash value.

  • The length of the buffer.

If xfrmbuf is NULL (the default), then a call to malloc() or free() is made automatically, as appropriate. startTransaction() fails if xfrmbuf is not NULL and xfrmbuflen is too small.

Example.  Suppose that the table's partition key is a single BIGINT column. Then you would declare the distribution key array as shown here:

Key_part_ptr distkey[2];

The value of the distribution key would be defined as shown here:

unsigned long long distkeyValue= 23;

The pointer to the distribution key array would be set as follows:

distkey[0].ptr= (const void*) &distkeyValue;

The length of this pointer would be set accordingly:

distkey[0].len= sizeof(distkeyValue);

The distribution key array must terminate with a NULL element. This is necessary to avoid to having an additional parameter providing the number of columns in the distribution key:

distkey[1].ptr= NULL;
distkey[1].len= NULL;

Setting the buffer to NULL permits startTransaction() to allocate and free memory automatically:

xfrmbuf= NULL;
xfrmbuflen= 0;
Note

You can also specify a buffer to save having to make explicit malloc() and free() calls, but calculating an appropriate size for this buffer is not a simple matter; if the buffer is not NULL but its length is too short, then the startTransaction() call fails. However, if you choose to specify the buffer, 1 MB is usually a sufficient size.

Now, when you start the transaction, you can access the node that contains the desired information directly.

In MySQL Cluster NDB 6.2 and later, another distribution-aware version of this method is available. This variant makes it possible for you to specify a table and partition (using the partition ID) as a hint for selecting the transaction coordinator, and is defined as shown here:

NdbTransaction* startTransaction
    (
      const NdbDictionary::Table* table,
      Uint32 partitionId
    )

In the event that the cluster has the same number of data nodes as it has replicas, specifying the transaction coordinator gains no improvement in performance, since each data node contains the entire database. However, where the number of data nodes is greater than the number of replicas (for example, where NoOfReplicas is set equal to 2 in a cluster with 4 data nodes), you should see a marked improvement in performance by using the distribution-aware version of this method.

It is still possible to use this method as before, without specifying the transaction coordinator. In either case, you must still explicitly close the transaction, whether or not the call to startTransaction() was successful.

Return value.  On success, an NdbTransaction object. In the event of failure, NULL is returned.