Documentation Home
MySQL NDB Cluster API Developer Guide
Download this Manual 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.


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, “Ndb::closeTransaction()”, and Section, “NdbTransaction::close()”, for more information.


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().  It is also possible to employ distribution awareness with this method; that is, to suggest which node should act as the transaction coordinator.


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.15, “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;

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.

Another distribution-aware version of this method 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.