Documentation Home
MySQL NDB Cluster API Developer Guide
Download this Manual

2.3.18 The NdbBlob Class


This class represents a handle to a BLOB column and provides read and write access to BLOB column values. This object has a number of different states and provides several modes of access to BLOB data; these are also described in this section.

Parent class.  None

Child classes.  None

Description.  This class has no public constructor. An instance of NdbBlob is created using the NdbOperation::getBlobHandle() method during the operation preparation phase. (See Section 2.3.25, “The NdbOperation Class”.) This object acts as a handle on a BLOB column.

BLOB Data Storage.  BLOB data is stored in 2 locations:

  • The header and inline bytes are stored in the blob attribute.

  • The blob's data segments are stored in a separate table named NDB$BLOB_tid_cid, where tid is the table ID, and cid is the blob column ID.

The inline and data segment sizes can be set using the appropriate Column methods when the table is created. See Section 2.3.2, “The Column Class”, for more information about these methods.

Data Access Types.  NdbBlob supports 3 types of data access: These data access types can be applied in combination, provided that they are used in the order given above.

  • In the preparation phase, the NdbBlob methods getValue() and setValue() are used to prepare a read or write of a BLOB value of known size.

  • Also in the preparation phase, setActiveHook() is used to define a routine which is invoked as soon as the handle becomes active.

  • In the active phase, readData() and writeData() are used to read and write BLOB values having arbitrary sizes.

BLOB Operations.  BLOB operations take effect when the next transaction is executed. In some cases, NdbBlob is forced to perform implicit execution. To avoid this, you should always operate on complete blob data segments.

Use NdbTransaction::executePendingBlobOps() to flush reads and writes, which avoids any execution penalty if no operations are pending. This is not necessary following execution of operations, or after the next scan result.

NdbBlob also supports reading post- or pre-blob data from events. The handle can be read after the next event on the main table has been retrieved. The data becomes available immediately. (See Section 2.3.21, “The NdbEventOperation Class”, for more information.)

BLOBs and NdbOperations.  NdbOperation methods acting on NdbBlob objects have the following characteristics:.

  • NdbOperation::insertTuple() must use NdbBlob::setValue() if the BLOB attribute is nonnullable.

  • NdbOperation::readTuple() used with any lock mode can read but not write blob values.

    When the LM_CommittedRead lock mode is used with readTuple(), the lock mode is automatically upgraded to LM_Read whenever blob attributes are accessed.

  • NdbOperation::updateTuple() can either overwrite an existing value using NdbBlob::setValue(), or update it during the active phase.

  • NdbOperation::writeTuple() always overwrites blob values, and must use NdbBlob::setValue() if the BLOB attribute is nonnullable.

  • NdbOperation::deleteTuple() creates implicit, nonaccessible BLOB handles.

  • A scan with any lock mode can use its blob handles to read blob values but not write them.

    A scan using the LM_Exclusive lock mode can update row and blob values using updateCurrentTuple(); the operation returned must explicitly create its own blob handle.

    A scan using the LM_Exclusive lock mode can delete row values (and therefore blob values) using deleteCurrentTuple(); this create implicit nonaccessible blob handles.

  • An operation which is returned by lockCurrentTuple() cannot update blob values.

Known Issues.  The following are known issues or limitations encountered when working with NdbBlob objects:

  • Too many pending BLOB operations can overflow the I/O buffers.

  • The table and its BLOB data segment tables are not created atomically.

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

Table 2.32 NdbBlob class methods and descrptions

Name Description
blobsFirstBlob() Gets the first blob in a list.
blobsNextBlob() Gets the next blob in a list
close() Release internal resources prior to commit or abort
getBlobEventName() Gets a blob event name
getBlobTableName() Gets a blob data segment's table name.
getColumn() Gets a blob column.
getLength() Gets the length of a blob, in bytes
getNdbError() Gets an error (an NdbError object)
getNdbOperation() Get a pointer to the operation (NdbOperation object) to which this NdbBlob object belonged when created.
getNull() Checks whether a blob value is NULL
getPos() Gets the current position for reading/writing
getState() Gets the state of an NdbBlob object
getValue() Prepares to read a blob value
getVersion() Checks whether a blob is statement-based or event-based
readData() Reads data from a blob
setActiveHook() Defines a callback for blob handle activation
setNull() Sets a blob to NULL
setPos() Sets the position at which to begin reading/writing
setValue() Prepares to insert or update a blob value
truncate() Truncates a blob to a given length
writeData() Writes blob data


getBlobTableName() and getBlobEventName() are static methods.


Most NdbBlob methods (nearly all of those whose return type is int) return 0 on success and -1 in the event of failure.

Types.  The public types defined by NdbBlob are shown here:

Table 2.33 NdbBlob types and descriptions

Name Description
ActiveHook() Callback for NdbBlob::setActiveHook()
State() Represents the states that may be assumed by the NdbBlob.