Documentation Home
MySQL NDB Cluster API Developer Guide
Related Documentation
MySQL NDB Cluster 8.1 Manual
MySQL NDB Cluster 8.0 Manual
NDB Cluster Internals Manual
Download this Manual
PDF (US Ltr) - 3.7Mb
PDF (A4) - 3.7Mb

2.3.25 The NdbTransaction Class

This section provides information about the NdbTransaction class.

NdbTransaction Class Overview

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.

Methods

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

Table 2.66 NdbTransaction class methods and descriptions

Name Description
close() Closes a transaction
commitStatus() Gets the transaction's commit status
deleteTuple() Delete a tuple using NdbRecord
execute() Executes a transaction
executePendingBlobOps() Executes a transaction in NoCommit mode if it includes any blob part operations of the specified types that are not yet executed.
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
setSchemaObjectOwnerChecks() Enable or disable schema object ownership checks
unlock() Create an unlock operation on the current transaction
updateTuple() Update a tuple using NdbRecord
writeTuple() Write a tuple using NdbRecord

The methods readTuple(), insertTuple(), updateTuple(), writeTuple(), deleteTuple(), scanTable(), and scanIndex() require the use of NdbRecord.

Types

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

Table 2.67 NdbTransaction class types and descriptions

Name Description
CommitStatusType() Describes the transaction's commit status
ExecType() Determines whether the transaction should be committed or rolled back

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.

    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.

NdbTransaction::close()

Description

This method closes a transaction. It is equivalent to calling Ndb::closeTransaction().

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

Signature 
void close
    (
      void
    )
Parameters

None.

Return value

None.

NdbTransaction::commitStatus()

Description

This method gets the transaction's commit status.

Signature 
CommitStatusType commitStatus
    (
      void
    )
Parameters

None.

Return value

The commit status of the transaction, a value of type CommitStatusType.

NdbTransaction::CommitStatusType

This section provides information about the CommitStatusType data type.

Description

This type is used to describe a transaction's commit status.

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.68 NdbTransaction::CommitStatusType values and descriptions

Name Description
NotStarted The transaction has not yet been started.
Started The transaction has started, but is not yet committed.
Committed The transaction has completed, and has been committed.
Aborted The transaction was aborted.
NeedAbort The transaction has encountered an error, but has not yet been aborted.

A transaction's commit status ca be read using commitStatus().

NdbTransaction::deleteTuple()

Description

Deletes a tuple using NdbRecord.

Signature 
const NdbOperation* deleteTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* result_rec,
      char* result_row,
      const unsigned char* result_mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the delete operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be deleted, and must remain valid until execute() is called.

  • The result_rec is the NdbRecord to be used.

  • The result_row can be NULL if no attributes are to be returned.

  • The result_mask, if not NULL, defines a subset of attributes to be read and returned to the client. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter provides backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

Return value

A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if necessary.

NdbTransaction::ExecType

This section provides information about the ExecType data type.

Description

This type sets the transaction's execution type; that is, whether it should execute, execute and commit, or abort. It is used as a parameter to the execute() method. (See NdbTransaction::execute().)

Enumeration values

Possible values are shown, along with descriptions, in the following table:

Table 2.69 NdbTransaction::ExecType values and descriptions

Name Description
NoCommit The transaction should execute, but not commit.
Commit The transaction should execute and be committed.
Rollback The transaction should be rolled back.

NdbTransaction::execute()

Description

This method is used to execute a transaction.

Signature 
int execute
    (
      ExecType execType,
      NdbOperation::AbortOption abortOption = NdbOperation::DefaultAbortOption,
      int force = 0
    )
Parameters

The execute() method takes the three parameters listed here:

Return value

Returns 0 on success, or -1 on failure. The fact that the transaction did not abort does not necessarily mean that each operation was successful; you must check each operation individually for errors.

This method reports a failure if and only if the transaction was aborted. The transaction's error information is set in such cases to reflect the actual error code and category.

In the case where a NoDataFound error is a possibility, you must check for it explicitly, as shown in this example: 

Ndb_cluster_connection myConnection;

if( myConnection.connect(4, 5, 1) )
{
  cout << "Unable to connect to cluster within 30 secs." << endl;
  exit(-1);
}

Ndb myNdb(&myConnection, "test");

//  define operations...

myTransaction = myNdb->startTransaction();

if(myTransaction->getNdbError().classification == NdbError:NoDataFound)
{
  cout << "No records found." << endl;
  //  ...
}

myNdb->closeTransaction(myTransaction);

You should be aware that a successful execute() call guarantees only that the scan request has been assembled and sent to the transaction coordinator without any errors; it does not wait for any signals to be sent in reply from the data nodes before returning.

NdbTransaction::executePendingBlobOps()

Description

This method executes the transaction with ExecType equal to NoCommit if there remain any blob part operations of the given types which have not yet been executed.

Signature 
int executePendingBlobOps
  (
    Uint8 flags = 0xFF
  )
Parameters

The flags argument is the result of a bitwise OR, equal to 1 << optype, where optype is an NdbOperation::Type. The default corresponds to NdbOperation::Type::PrimaryKeyAccess.

Return value

Returns 0 on success, or -1 on failure. The fact that the transaction did not abort does not necessarily mean that each operation was successful; you must check each operation individually for errors.

NdbTransaction::getGCI()

Description

This method retrieves the transaction's global checkpoint ID (GCI).

Each committed transaction belongs to a GCI. The log for the committed transaction is saved on disk when a global checkpoint occurs.

By comparing the GCI of a transaction with the value of the latest GCI restored in a restarted NDB Cluster, you can determine whether or not the transaction was restored.

Whether or not the global checkpoint with this GCI has been saved on disk cannot be determined by this method.

The GCI for a scan transaction is undefined, since no updates are performed in scan transactions.

No GCI is available until execute() has been called with ExecType::Commit.

Signature 
int getGCI
    (
      void
    )
Parameters

None.

Return value

The transaction's GCI, or -1 if none is available.

NdbTransaction::getMaxPendingBlobReadBytes()

Description

Gets the current batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.

Signature 
Uint32 getMaxPendingBlobReadBytes
    (
      void
    ) const
Parameters

None.

Return value

The current blob read batch size, in bytes. See NdbTransaction::setMaxPendingBlobReadBytes(), for more information.

NdbTransaction::getMaxPendingBlobWriteBytes()

Description

Gets the current batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.

Signature 
Uint32 getMaxPendingBlobWriteBytes
    (
      void
    ) const
Parameters

None.

Return value

The current blob write batch size, in bytes. See NdbTransaction::setMaxPendingBlobWriteBytes(), for more information.

NdbTransaction::getNdbError()

Description

This method is used to obtain the most recent error (NdbError).

Signature 
const NdbError& getNdbError
    (
      void
    ) const
Parameters

None.

Return value

A reference to an NdbError object.

For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.

NdbTransaction::getNdbErrorLine()

Description

This method return the line number where the most recent error occurred.

Signature 
int getNdbErrorLine
    (
      void
    )
Parameters

None.

Return value

The line number of the most recent error.

For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.

NdbTransaction::getNdbErrorOperation()

Description

This method retrieves the operation that caused an error.

To obtain more information about the actual error, use the NdbOperation::getNdbError() method of the NdbOperation object returned by getNdbErrorOperation().

Signature 
NdbOperation* getNdbErrorOperation
    (
      void
    )
Parameters

None.

Return value

A pointer to an NdbOperation.

For additional information about handling errors in transactions, see Section 1.4.2.3.6, “Error Handling”.

NdbTransaction::getNdbIndexOperation()

Description

This method is used to create an NdbIndexOperation associated with a given table.

All index operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature 
NdbIndexOperation* getNdbIndexOperation
    (
      const NdbDictionary::Index* index
    )
Parameters

The Index object on which the operation is to be performed.

Return value

A pointer to the new NdbIndexOperation.

NdbTransaction::getNdbIndexScanOperation()

Description

This method is used to create an NdbIndexScanOperation associated with a given table.

All index scan operations within the same transaction must be initialised with this method. Operations must be defined before they are executed.

Signature 
NdbIndexScanOperation* getNdbIndexScanOperation
    (
      const NdbDictionary::Index* index
    )
Parameters

The Index object on which the operation is to be performed.

Return value

A pointer to the new NdbIndexScanOperation.

NdbTransaction::getNdbOperation()

Description

This method is used to create an NdbOperation associated with a given table.

All operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.

Signature 
NdbOperation* getNdbOperation
    (
      const NdbDictionary::Table* table
    )
Parameters

The Table object on which the operation is to be performed.

Return value

A pointer to the new NdbOperation.

NdbTransaction::getNdbScanOperation()

Description

This method is used to create an NdbScanOperation associated with a given table.

All scan operations within the same transaction must be initialized with this method. Operations must be defined before they are executed.

Signature 
NdbScanOperation* getNdbScanOperation
    (
      const NdbDictionary::Table* table
    )
Parameters

The Table object on which the operation is to be performed.

Return value

A pointer to the new NdbScanOperation.

NdbTransaction::getNextCompletedOperation()

Description

This method is used to retrieve a transaction's completed operations. It is typically used to fetch all operations belonging to a given transaction to check for errors.

NdbTransaction::getNextCompletedOperation(NULL) returns the transaction's first NdbOperation object; NdbTransaction::getNextCompletedOperation(myOp) returns the NdbOperation object defined after NdbOperation myOp.

This method should only be used after the transaction has been executed, but before the transaction has been closed.

Signature 
const NdbOperation* getNextCompletedOperation
    (
      const NdbOperation* op
    ) const
Parameters

This method requires a single parameter op, which is an operation (NdbOperation object), or NULL.

Return value

The operation following op, or the first operation defined for the transaction if getNextCompletedOperation() was called using NULL.

NdbTransaction::getTransactionId()

Description

This method is used to obtain the transaction ID.

Signature 
Uint64 getTransactionId
    (
      void
    )
Parameters

None.

Return value

The transaction ID, as an unsigned 64-bit integer.

NdbTransaction::insertTuple()

Description

Inserts a tuple using NdbRecord.

Signatures 
const NdbOperation* insertTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* attr_rec,
      const char* attr_row,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
const NdbOperation* insertTuple
    (
      const NdbRecord* combined_rec,
      const char* combined_row,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

insertTuple() takes the following parameters:

  • A pointer to an NdbRecord indicating the record (key_rec) to be inserted.

    This method can also be called using a single NdbRecord pointer and single char pointer (combined_rec, combined_row) where the single NdbRecord represents record and attribute and data.

  • A row (key_row) of data to be inserted.

  • A pointer to an NdbRecord indicating an attribute (attr_rec) to be inserted.

  • A row (attr_row) of data to be inserted as the attribute.

  • A mask which can be used to filter the columns to be inserted.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

Return value

A const pointer to the NdbOperation representing this insert operation.

NdbTransaction::readTuple()

Description

This method reads a tuple using NdbRecord objects.

Signature 
const NdbOperation* readTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* result_rec,
      char* result_row,
      NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
      const unsigned char* result_mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

    The mask, if not NULL, defines a subset of attributes to read, update, or insert. Only if (mask[attrId >> 3] & (1<<(attrId & 7))) is set is the column affected. The mask is copied by the methods, so need not remain valid after the call returns.

  • result_rec is a pointer to an NdbRecord used to hold the result

  • result_row defines a buffer for the result data.

  • lock_mode specifies the lock mode in effect for the operation. See NdbOperation::LockMode, for permitted values and other information.

  • result_mask defines a subset of attributes to read. Only if mask[attrId >> 3] & (1<<(attrId & 7)) is set is the column affected. The mask is copied, and so need not remain valid after the method call returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; the options supported for each type of operation are shown in the following table:

    Table 2.70 Operation types for NdbTransaction::readTuple() OperationOptions (opts) parameter, with operation options supported by each type

    Operation type (Method) OperationOptions Flags Supported
    readTuple() OO_ABORTOPTION, OO_GETVALUE, OO_PARTITION_ID, OO_INTERPRETED
    insertTuple() OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_ANYVALUE
    updateTuple() OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_INTERPRETED, OO_ANYVALUE
    writeTuple() OO_ABORTOPTION, OO_SETVALUE, OO_PARTITION_ID, OO_ANYVALUE
    deleteTuple() OO_ABORTOPTION, OO_GETVALUE, OO_PARTITION_ID, OO_INTERPRETED, OO_ANYVALUE

  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

Return value

A pointer to the NdbOperation representing this read operation (this can be used to check for errors).

NdbTransaction::refresh()

Description

This method updates the transaction's timeout counter, and thus avoids aborting due to transaction timeout.

It is not advisable to take a lock on a record and maintain it for a extended time since this can impact other transactions.

Signature 
int refresh
    (
      void
    )
Parameters

None.

Return value

Returns 0 on success, -1 on failure.

NdbTransaction::releaseLockHandle()

Description

This method is used to release a lock handle (see NdbOperation::getLockHandle) when it is no longer required. For NdbRecord primary key read operations, this cannot be called until the associated read operation has been executed.

All lock handles associated with a given transaction are released when that transaction is closed.

Signature 
int releaseLockHandle
    (
      const NdbLockHandle* lockHandle
    )
Parameters

The NdbLockHandle object to be released.

Return value

0 on success.

NdbTransaction::scanIndex()

Description

Perform an index range scan of a table, with optional ordering.

Signature 
NdbIndexScanOperation* scanIndex
    (
      const NdbRecord* key_record,
      const NdbRecord* result_record,
      NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
      const unsigned char* result_mask = 0,
      const NdbIndexScanOperation::IndexBound* bound = 0,
      const NdbScanOperation::ScanOptions* options = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

  • The key_record describes the index to be scanned. It must be a key record for the index; that is, it must specify, at a minimum, all of the key columns of the index. The key_record must be created from the index to be scanned (and not from the underlying table).

  • The result_record describes the rows to be returned from the scan. For an ordered index scan, result_record must be a key record for the index to be scanned; that is, it must include (at a minimum) all of the columns in the index (the full index key is needed by the NDB API for merge-sorting the ordered rows returned from each fragment).

    Like the key_record, the result_record must be created from the underlying table, and not from the index to be scanned. Both the key_record and result_record NdbRecord structures must stay in place until the scan operation is closed.

  • The result_mask pointer is optional. If it is present, only those columns for which the corresponding bits (by attribute ID order) in result_mask are set are actually retrieved in the scan. The result_mask is copied internally, so in contrast to result_record it need not be valid when execute() is invoked.

  • A single IndexBound can be specified either in this call or in a separate call to NdbIndexScanOperation::setBound(). To perform a multi-range read, the scan_flags in the ScanOptions structure must include SF_MULTIRANGE. Additional bounds can be added using successive calls to NdbIndexScanOperation::setBound().

    To specify an equals bound, use the same row pointer for the low_key and high_key with the low and high inclusive bits set.

    For multi-range scans, the low_key and high_key pointers must be unique. In other words, it is not permissible to reuse the same row buffer for several different range bounds within a single scan. However, it is permissible to use the same row pointer as low_key and high_key in order to specify an equals bound; it is also permissible to reuse the rows after the scanIndex() method returns—that is, they need not remain valid until execute() time (unlike the NdbRecord pointers).

  • To specify additional options, pass a ScanOptions structure.

  • The sizeOfOptions exists to enable backward compatability for this interface. This parameter indicates the size of the ScanOptions structure at the time the client was compiled, and enables detection of the use of an old-style ScanOptions structure. If this functionality is not required, this argument can be left set to 0.

Return value

The current NdbIndexScanOperation, which can be used for error checking.

NdbTransaction::scanTable()

Description

This method performs a table scan, using an NdbRecord object to read out column data.

Signature 
NdbScanOperation* scanTable
    (
      const NdbRecord* result_record,
      NdbOperation::LockMode lock_mode = NdbOperation::LM_Read,
      const unsigned char* result_mask = 0,
      Uint32 scan_flags = 0,
      Uint32 parallel = 0,
      Uint32 batch = 0
    )
Parameters

The scanTable() method takes the following parameters:

  • A pointer to an NdbRecord for storing the result. This result_record must remain valid until after the execute() call has been made.

  • The lock_mode in effect for the operation. See NdbOperation::LockMode, for permitted values and other information.

  • The result_mask pointer is optional. If it is present, only those columns for which the corresponding bits (by attribute ID order) in result_mask are set are actually retrieved in the scan. The result_mask is copied internally, so in contrast to result_record it need not be valid when execute() is invoked.

  • scan_flags can be used to impose ordering and sorting conditions for scans. See NdbScanOperation::ScanFlag, for a list of permitted values.

  • The parallel argument is the desired parallelism, or 0 for maximum parallelism (receiving rows from all fragments in parallel), which is the default.

  • batch determines whether batching is employed. The default is 0 (off).

Return value

A pointer to the NdbScanOperation representing this scan. The operation can be checked for errors if necessary.

NdbTransaction::setMaxPendingBlobReadBytes()

Description

Sets the batch size in bytes for blob read operations. When the volume of blob data to be read within a given transaction exceeds this amount, all of the transaction's pending blob read operations are executed.

Signature 
void setMaxPendingBlobReadBytes
    (
      Uint32 bytes
    )
Parameters

The batch size, as the number of bytes. Using 0 causes blob read batching to be disabled, which is the default behavior (for backward compatibility).

Return value

None.

Note

blob read batching can also be controlled in the mysql client and other MySQL client application using the MySQL Server's --ndb-blob-read-batch-bytes option and its associated MySQL Server system variables.

NdbTransaction::setMaxPendingBlobWriteBytes()

Description

Sets the batch size in bytes for blob write operations. When the volume of blob data to be written within a given transaction exceeds this amount, all of the transaction's pending blob write operations are executed.

Signature 
void setMaxPendingBlobWriteBytes
    (
      Uint32 bytes
    )
Parameters

The batch size, as the number of bytes. Using 0 causes blob write batching to be disabled, which is the default behavior (for backward compatibility).

Return value

None.

Note

Blob write batching can also be controlled in the mysql client and other MySQL client applications in NDB 8.0.30 and later by setting the MySQL Server's ndb_replica_blob_write_batch_bytes server system variable to an appropriate value. You should be aware that, when ndb_replica_blob_write_batch_bytes​is not set,​the effective blob batch size (that is, the maximum number of pending bytes to write for blob columns) is determined by the maximum of the default value of ndb_replica_blob_write_batch_bytes and the value set for the --ndb-blob-write-batch-bytes MySQL server option. For this reason, you should use ndb_replica_blob_write_batch_bytes rather than --ndb-blob-write-batch-bytes.

Prior to NDB 8.0.30, you must use the --ndb-blob-write-batch-bytes option, or one of its associated MySQL Server system variables, to set the blob batch size from mysql or another MySQL client program.

NdbTransaction::setSchemaObjectOwnerChecks()

Description

Enables or disables a schema object ownership check when multiple Ndb_cluster_connection objects are in use. When this check is enabled, objects used by this transaction are checked to make sure that they belong to the NdbDictionary owned by this connection. This is done by acquiring the schema objects of the same names from the connection and comparing these with the schema objects passed to the transaction. If they do not match, an error is returned.

This method is available for debugging purposes. (Bug #19875977) You should be aware that enabling this check carries a performance penalty and for this reason you should avoid doing so in a production setting.

Signature 
void setSchemaObjOwnerChecks
    (
      bool runChecks
    )
Parameters

A single parameter runChecks. Use true to enable ownership checks, false to disable them.

Return value

None.

NdbTransaction::unlock()

Description

This method creates an unlock operation on the current transaction; when executed, the unlock operation removes the lock referenced by the NdbLockHandle (see NdbOperation::getLockHandle) passed to the method.

Signature 
const NdbOperation* unlock
    (
      const NdbLockHandle* lockHandle,
      NdbOperation::AbortOption ao = NdbOperation::DefaultAbortOption
    )
Parameters

A pointer to a lock handle; in addition, optionally, an AbortOption value ao.

In the event that the unlock operation fails—for example, due to the row already being unlocked—the AbortOption specifies how this is handled, the default being that errors cause transactions to abort.

Return value

A pointer to an NdbOperation (the unlock operation created).

NdbTransaction::updateTuple()

Description

Updates a tuple using an NdbRecord object.

Signature 
const NdbOperation* updateTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* attr_rec,
      const char* attr_row,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

updateTuple() takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the affected tuple, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be updated.

    Note

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data for the update.

  • The mask, if not NULL, defines a subset of attributes to be updated. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to preserve backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

Return value

The NdbOperation representing this operation (can be used to check for errors).

NdbTransaction::writeTuple()

Description

This method is used with NdbRecord to write a tuple of data.

Signature 
const NdbOperation* writeTuple
    (
      const NdbRecord* key_rec,
      const char* key_row,
      const NdbRecord* attr_rec,
      const char* attr_row,
      const unsigned char* mask = 0,
      const NdbOperation::OperationOptions* opts = 0,
      Uint32 sizeOfOptions = 0
    )
Parameters

This method takes the following parameters:

  • key_rec is a pointer to an NdbRecord for either a table or an index. If on a table, then the operation uses a primary key; if on an index, then the operation uses a unique key. In either case, the key_rec must include all columns of the key.

  • The key_row passed to this method defines the primary or unique key of the tuple to be written, and must remain valid until execute() is called.

  • attr_rec is an NdbRecord referencing the attribute to be written.

    For unique index operations, the attr_rec must refer to the underlying table of the index, not to the index itself.

  • attr_row is a buffer containing the new data.

  • The mask, if not NULL, defines a subset of attributes to be written. The mask is copied, and so does not need to remain valid after the call to this method returns.

  • OperationOptions (opts) can be used to provide more finely-grained control of operation definitions. An OperationOptions structure is passed with flags indicating which operation definition options are present. Not all operation types support all operation options; for the options supported by each type of operation, see NdbTransaction::readTuple().

  • The optional sizeOfOptions parameter is used to provide backward compatibility of this interface with previous definitions of the OperationOptions structure. If an unusual size is detected by the interface implementation, it can use this to determine how to interpret the passed OperationOptions structure. To enable this functionality, the caller should pass sizeof(NdbOperation::OperationOptions) for the value of this argument.

Return value

A const pointer to the NdbOperation representing this write operation. The operation can be checked for errors if and as necessary.


PREV   HOME   UP   NEXT
Related Documentation
MySQL NDB Cluster 8.1 Manual
MySQL NDB Cluster 8.0 Manual
NDB Cluster Internals Manual
Download this Manual
PDF (US Ltr) - 3.7Mb
PDF (A4) - 3.7Mb