2.3.29 The NdbTransaction Class

2.3.29.1 NdbTransaction Types
2.3.29.2 NdbTransaction Methods

Abstract

This section describes the NdbTransaction class and its public members.

Parent class.  None

Child classes.  None

Description.  A transaction is represented in the NDB API by an NdbTransaction object, which belongs to an Ndb object and is created using Ndb::startTransaction(). A transaction consists of a list of operations represented by the NdbOperation class, or by one of its subclasses—NdbScanOperation, NdbIndexOperation, or NdbIndexScanOperation. Each operation access exactly one table.

Using Transactions.  After obtaining an NdbTransaction object, it is employed as follows:

  1. An operation is allocated to the transaction using any one of the following methods:

    • getNdbOperation()

    • getNdbScanOperation()

    • getNdbIndexOperation()

    • getNdbIndexScanOperation()

    Calling one of these methods defines the operation. Several operations can be defined on the same NdbTransaction object, in which case they are executed in parallel. When all operations are defined, the execute() method sends them to the NDB kernel for execution.

  2. The execute() method returns when the NDB kernel has completed execution of all operations previously defined.

    Important

    All allocated operations should be properly defined before calling the execute() method.

  3. execute() operates in one of the three modes listed here:

    • NdbTransaction::NoCommit: Executes operations without committing them.

    • NdbTransaction::Commit: Executes any remaining operation and then commits the complete transaction.

    • NdbTransaction::Rollback: Rolls back the entire transaction.

    execute() is also equipped with an extra error handling parameter, which provides the two alternatives listed here:

    • NdbOperation::AbortOnError: Any error causes the transaction to be aborted. This is the default behavior.

    • NdbOperation::AO_IgnoreError: The transaction continues to be executed even if one or more of the operations defined for that transaction fails.

    Note

    In MySQL 5.1.15 and earlier, these values were NdbTransaction::AbortOnError and NdbTransaction::AO_IgnoreError.

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

MethodPurpose / Use
close()Closes a transaction
commitStatus()Gets the transaction's commit status
deleteTuple()Delete a tuple using NdbRecord
execute()Executes a transaction
getGCI()Gets a transaction's global checkpoint ID (GCI)
getMaxPendingBlobReadBytes()Get the current BLOB read batch size
getMaxPendingBlobWriteBytes()Get the current BLOB write batch size
getNdbError()Gets the most recent error
getNdbErrorLine()Gets the line number where the most recent error occurred
getNdbErrorOperation()Gets the most recent operation which caused an error
getNextCompletedOperation()Gets operations that have been executed; used for finding errors
getNdbOperation()Gets an NdbOperation
getNdbScanOperation()Gets an NdbScanOperation
getNdbIndexOperation()Gets an NdbIndexOperation
getNdbIndexScanOperation()Gets an NdbIndexScanOperation
getTransactionId()Gets the transaction ID
insertTuple()Insert a tuple using NdbRecord
readTuple()Read a tuple using NdbRecord
refresh()Keeps a transaction from timing out
releaseLockHandle()Release an NdbLockHandle object once it is no longer needed
scanIndex()Perform an index scan using NdbRecord
scanTable()Perform a table scan using NdbRecord
setMaxPendingBlobReadBytes()Set the BLOB read batch size
setMaxPendingBlobWriteBytes()Set the BLOB write batch size
unlock()Create an unlock operation on the current transaction
updateTuple()Update a tuple using NdbRecord
writeTuple()Write a tuple using NdbRecord
Note

The methods readTuple(), insertTuple(), updateTuple(), writeTuple(), deleteTuple(), scanTable(), and scanIndex() require the use of NdbRecord, which is available beginning with MySQL Cluster NDB 6.2.3.

These methods were updated in MySQL Cluster NDB 6.2.15 and NDB 6.3.15, but remain backward-compatible with their older versions.

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

Types.  NdbTransaction defines 2 public types as shown in the following table:

TypePurpose / Use
CommitStatusType()Describes the transaction's commit status
ExecType()Determines whether the transaction should be committed or rolled back

For a discussion of each of these types, along with its possible values, see Section 2.3.29.1, “NdbTransaction Types”.

Class diagram.  This diagram shows all the available methods and enumerated types of the NdbTransaction class:

Public members of the NdbTransaction class.