MySQL NDB Cluster API Developer Guide
This section provides information about the
Dictionary
class.
This is used for defining and retrieving data object metadata. It also includes methods for creating and dropping database objects.
The following table lists the public methods of this class and the purpose or use of each method:
Table 2.11 Dictionary class methods and descriptions
Name | Description |
---|---|
Dictionary() |
Class constructor method |
~Dictionary() |
Destructor method |
beginSchemaTrans() |
Begins a schema transaction |
createDatafile() |
Creates a data file |
createEvent() |
Creates an event |
createForeignKey() |
Creates a foreign key |
createHashMap() |
Creates a hash map |
createIndex() |
Creates an index |
createLogfileGroup() |
Creates a log file group |
createRecord() |
Creates an Ndbrecord object |
createTable() |
Creates a table |
createTablespace() |
Creates a tablespace |
createUndofile() |
Creates an undo file |
dropDatafile() |
Drops a data file |
dropEvent() |
Drops an event |
dropForeignKey() |
Drops a foreign key |
dropIndex() |
Drops an index |
dropLogfileGroup() |
Drops a log file group |
dropTable() |
Drops a table |
dropTablespace() |
Drops a tablespace |
dropUndofile() |
Drops an undo file |
endSchemaTrans() |
Ends (commits and closes) a schema transaction |
getDatafile() |
Gets the data file having the given name |
getDefaultHashMap() |
Gets a table's default hash map |
getEvent() |
Gets the event having the given name |
getForeignKey() |
Gets the foreign key having the given name or reference |
getHashMap() |
Gets the hash map given its name or associated table |
getIndex() |
Gets the index having the given name |
getLogfileGroup() |
Gets the log file group having the given name |
getNdbError() |
Retrieves the latest error |
getTable() |
Gets the table having the given name |
getTablespace() |
Gets the tablespace having the given name |
getUndofile() |
Gets the undo file having the given name |
hasSchemaTrans() |
Tells whether a schema transaction currently exists |
initDefaultHashMap() |
Initializes a atble' default hash map |
invalidateTable() |
Invalidates a table object |
listObjects() |
Fetches a list of the objects in the dictionary |
listIndexes() |
Fetches a list of the indexes defined on a given table |
listEvents() |
Fetches a list of the events defined in the dictionary |
prepareHashMap() |
Creates or retrieves a hash map that can be updated |
removeCachedTable() |
Removes a table from the local cache |
removeCachedIndex() |
Removes an index from the local cache |
Database objects such as tables and indexes created using
the
Dictionary::create
methods cannot be seen by the MySQL Server. This means that
they cannot be accessed by MySQL clients, and that they
cannot be replicated. For these reasons, it is often
preferable to avoid working with them.
*
()
The Dictionary
class does not have any
methods for working directly with columns. You must use
Column
class methods for
this purpose—see Section 2.3.1, “The Column Class”, for
details.
See Section 2.3.10, “The List Class”, and Section 2.3.4, “The Element Structure”.
This method creates a new instance of the
Dictionary
class.
Both the constructor and destructor for this class are protected methods, rather than public.
protected Dictionary
(
Ndb& ndb
)
An Ndb
object.
A Dictionary
object.
The destructor takes no parameters and returns nothing:
protected ~Dictionary ( void )
Starts a schema transaction. An error occurs if a
transaction is already active, or if the kernel metadata is
locked. You can determine whether a schema transaction
already exists using the
hasSchemaTrans()
method.
A metadata operation occurs whenever data objects are created, altered, or dropped; such an operation can create additional suboperations in the NDB kernel.
The Ndb
object and its
associated Dictionary
support one schema transaction at a time. By default, each
metadata operation is executed separately; that is, for each
operation, a schema transaction is started implicitly, the
operation (including any suboperations) is executed, and the
transaction is closed.
It is also possible to begin and end a schema transaction explicitly, and execute a set of user-defined operations atomically within its boundaries. In this case, all operations within the schema transaction either succeed, or are aborted and rolled back, as a unit. This is done by following the steps listed here:
To begin the schema transaction, call
beginSchemaTrans()
.
Execute the desired operations (such as
createTable()
).
End the schema transaction by calling
endSchemaTrans
.
Each operation is sent to the NDB kernel, which parses and saves it. A parse failure results in a rollback to the previous user operation before returning, at which point the user can either continue with or abort the entire transaction.
After all operations have been submitted,
endSchemaTrans()
processes and commits
them. In the event of an error, the transaction is
immediately aborted.
If the user exits before calling
endSchemaTrans()
, the NDB kernel aborts
the transaction. If the user exits before the call to
endSchemaTrans()
returns, the kernel
continues with the request, and its completion status is
reported in the cluster log.
int beginSchemaTrans ( void )
None.
Returns 0 on success, -1 on error.
Creates an event, given a reference to an
Event
object.
You should keep in mind that the NDB API does not track
allocated event objects, which means that the user must
delete the Event
that was
obtained using createEvent()
, after this
object is no longer required.
int createEvent
(
const Event& event
)
A reference event
to an
Event
object.
0
on success, -1
on
failure.
Creates a ForeignKey
object, given a reference to this object and an
Object
ID.
int createForeignKey
(
const ForeignKey&,
ObjectId* = 0,
int flags
= 0
)
A reference to the
ForeignKey
object, and an
Object
ID. An optional
value flags
, if used, allows the
creation of the foreign key without performing any foreign
key checks. If set, its value must be
CreateFK_NoVerify
(1).
0
on success.
Creates a HashMap
.
int createHashMap ( const HashMap&hashmap
, ObjectId*id
= 0 )
A reference to the hash map, and, optionally, an ID to be assigned to it.
Returns 0 on success; on failure, returns -1 and sets an error.
This method creates a new log file group, given an instance
of LogfileGroup
.
int createLogfileGroup
(
const LogfileGroup& lGroup
)
A single argument, a reference to a
LogfileGroup
object, is
required.
0
on success, -1
on
failure.
This method is used to create an
NdbRecord
object for use in
table or index scanning operations.
The signature of this method depends on whether the resulting NdbRecord is to be used in table or index operations:
To create an NdbRecord
for
use in table operations, use the following:
NdbRecord* createRecord ( const Table*table
, const RecordSpecification*recSpec
, Uint32length
, Uint32elSize
)
To create an NdbRecord
for
use in index operations, you can use either of the
following:
NdbRecord* createRecord ( const Index*index
, const Table*table
, const RecordSpecification*recSpec
, Uint32length
, Uint32elSize
)
or
NdbRecord* createRecord ( const Index*index
, const RecordSpecification*recSpec
, Uint32length
, Uint32elSize
)
Dictionary::createRecord()
takes the
following parameters:
If this NdbRecord
is to
be used with an index, a pointer to the corresponding
Index
object. If the
NdbRecord
is to be used
with a table, this parameter is omitted. (See
Section 2.3.8, “The Index Class”.)
A pointer to a Table
object representing the table to be scanned. If the
Ndbrecord
produced is
to be used with an index, then this optionally specifies
the table containing that index. (See
Section 2.3.27, “The Table Class”.)
A
RecordSpecification
used to describe a column.
The length
of the record.
The size of the elements making up this record.
An NdbRecord
for use in
operations involving the given table or index.
Creates a table given an instance of
Table
.
Tables created using this method cannot be seen by the MySQL Server, cannot be updated by MySQL clients, and cannot be replicated.
int createTable
(
const Table& table
)
An instance of Table
. See
Section 2.3.27, “The Table Class”, for more information.
0
on success, -1
on
failure.
This method creates a new tablespace, given a
Tablespace
object.
int createTablespace
(
const Tablespace& tSpace
)
This method requires a single argument—a reference to
an instance of Tablespace
.
0
on success, -1
on
failure.
This method drops an event, given a reference to an
Event
object.
int dropEvent ( const char*name
, intforce
= 0 )
This method takes two parameters:
The name
of the event to be
dropped, as a string.
By default, dropEvent()
fails if the
event specified does not exist. You can override this
behavior by passing any nonzero value for the (optional)
force
argument; in this case
no check is made as to whether there actually is such an
event, and an error is returned only if the event exists
but it was for whatever reason not possible to drop it.
0
on success, -1
on
failure.
This method drops a foreign key, given a reference to an
ForeignKey
object to be
dropped.
int dropForeignKey ( const ForeignKey& )
A reference to the ForeignKey
to be
dropped.
0
on success.
This method drops an index given an instance of
Index
, and possibly an
optional instance of Table
.
int dropIndex
(
const Index& index
)
int dropIndex ( const Index&index
, const Table&table
)
This method takes two parameters, one of which is optional:
0
on success, -1
on
failure.
Given an instance of
LogfileGroup
, this method
drops the corresponding log file group.
int dropLogfileGroup
(
const LogfileGroup& lGroup
)
A single argument, a reference to a
LogfileGroup
object, is
required.
0
on success, -1
on
failure.
Drops a table given an instance of
Table
.
In NDB 7.3.5 and later, this method drops all foreign key
constraints on the table
that is
being dropped, whether the dropped table acts as a parent
table, child table, or both. (Bug #18069680)
Prior to NDB 8.0.17, an NDB
table dropped
using this method persisted in the MySQL data dictionary but
could not be dropped using DROP
TABLE
in the mysql client. In
NDB 8.0.17 and later, such “orphan” tables can
be dropped using DROP TABLE
. (Bug
#29125206, Bug #93672)
int dropTable
(
const Table& table
)
An instance of Table
. See
Section 2.3.27, “The Table Class”, for more information.
0
on success, -1
on
failure.
This method drops a tablespace, given a
Tablespace
object.
int dropTablespace
(
const Tablespace& tSpace
)
This method requires a single argument—a reference to
an instance of Tablespace
.
0
on success, -1
on
failure.
Ends a schema transaction begun with
beginSchemaTrans()
;
causes operations to be processed and either committed, or
aborted and rolled back. This method combines transaction
execution and closing; separate methods for these tasks are
not required (or implemented). This method may be called
successfully even if no schema transaction is currently
active.
As with many other NDB API methods, it is entirely possible
for endSchemaTrans()
to overwrite any
current error code. For this reason, you should first check
for and save any error code that may have resulted from a
previous, failed operation.
int endSchemaTrans
(
Uint32 flags
= 0
)
The flags determines how the completed transaction is handled. The default is 0, which causes the transaction to be committed.
Dictionary::SchemaTransFlag.
You can also use with endSchemaTrans()
either of the SchemaTransFlag
values
shown here:
SchemaTransAbort
(= 1): Causes the
transaction to be aborted
SchemaTransBackground
(= 2): Causes
the transaction to execute in the background; the result
is written to the cluster log, while the application
continues without waiting for a response.
Returns 0 on success; in the event of an error, returns -1
and sets an NdbError
error
code.
This method is used to retrieve a
Datafile
object, given the
node ID of the data node where a data file is located and
the path to the data file on that node's file system.
Datafile getDatafile ( Uint32nodeId
, const char*path
)
This method must be invoked using two arguments, as shown here:
The 32-bit unsigned integer
nodeId
of the data node where
the data file is located
The path
to the data file on
the node's file system (string as character
pointer)
A Datafile
object—see
Section 2.3.2, “The Datafile Class”, for details.
Get a table's default hash map.
int getDefaultHashMap ( HashMap&dst
, Uint32fragments
)
or
int getDefaultHashMap ( HashMap&dst
, Uint32buckets
, Uint32fragments
)
Returns 0 on success; on failure, returns -1 and sets an error.
This method is used to obtain a new
Event
object representing
an event, given the event's name.
getEvent()
allocates memory each time it
is successfully called. You should keep in mind that
successive invocations of this method using the same event
name return multiple, distinct objects.
The NDB API does not track allocated event objects, which
means that the user must delete each
Event
created using
getEvent()
, after the object is no longer
required.
const Event* getEvent
(
const char* eventName
)
The eventName
, a string
(character pointer).
A pointer to an Event
object. See Section 2.3.5, “The Event Class”, for more
information.
This method is used to obtain a new
ForeignKey
object
representing an event, given a reference to the foreign key
and its name.
int getForeignKey ( ForeignKey&dst
, const char*name
)
A reference to the foreign key and its
name
, a string (character
pointer).
A pointer to a ForeignKey
object.
Gets a hash map by name or by table.
int getHashMap ( HashMap&dst
, const char*name
)
or
int getHashMap ( HashMap&dst
, const Table*table
)
A reference to the hash map and either a name or a
Table
.
Returns 0 on success; on failure, returns -1 and sets an error.
This method retrieves a pointer to an index, given the name of the index and the name of the table to which the table belongs.
const Index* getIndex ( const char*iName
, const char*tName
) const
Two parameters are required:
The name of the index (iName
)
The name of the table to which the index belongs
(tName
)
Both of these are string values, represented by character pointers.
A pointer to an Index
. See
Section 2.3.8, “The Index Class”, for information about this
object.
This method gets a
LogfileGroup
object, given
the name of the log file group.
LogfileGroup getLogfileGroup
(
const char* name
)
The name
of the log file group.
An instance of
LogfileGroup
; see
Section 2.3.9, “The LogfileGroup Class”, for more information.
This method can be used to access a
Table
whose name is already
known.
const Table* getTable
(
const char* name
) const
The name
of the table.
A pointer to the table, or NULL
if there
is no table with the name
supplied.
Given either the name or ID of a tablespace, this method
returns the corresponding
Tablespace
object.
This method can be invoked in either of the following two ways:
Using the tablespace name:
Tablespace getTablespace
(
const char* name
)
Using the tablespace ID:
Tablespace getTablespace
(
Uint32 id
)
Either one of the following:
The name
of the tablespace, a
string (as a character pointer)
The unsigned 32-bit integer
id
of the tablespace
A Tablespace
object, as
discussed in Section 2.3.28, “The Tablespace Class”.
This method gets an
Undofile
object, given the
ID of the node where an undo file is located and the file
system path to the file.
Undofile getUndofile ( Uint32nodeId
, const char*path
)
This method requires the following two arguments:
The nodeId
of the data node
where the undo file is located; this value is passed as
a 32-bit unsigned integer
The path
to the undo file on
the node's file system (string as character
pointer)
An instance of Undofile
.
For more information, see Section 2.3.29, “The Undofile Class”.
Tells whether an NDB API schema transaction is ongoing.
bool hasSchemaTrans ( void ) const
None.
Returns boolean TRUE
if a schema
transaction is in progress, otherwise
FALSE
.
Initialize a default hash map for a table.
int initDefaultHashMap ( HashMap& dst, Uint32 fragments )
or
int initDefaultHashMap ( HashMap& dst, Uint32 buckets, Uint32 fragments )
A reference to the hash map and the number of fragments. Optionally the number of buckets.
Returns 0 on success; on failure, returns -1 and sets an error.
This method is used to invalidate a cached index object.
The index invalidated by this method can be referenced
either as an Index
object
(using a pointer), or by index name and table name, as shown
here:
void invalidateIndex ( const char*indexName
, const char*tableName
) void invalidateIndex ( const Index*index
)
The names of the index to be removed from the cache and the
table to which it belongs
(indexName
and
tableName
, respectively), or a
pointer to the corresponding
Index
object.
None.
This method is used to invalidate a cached table object.
void invalidateTable
(
const char* name
)
It is also possibloe to use a
Table
object rather than
the name of the table, as shown here:
void invalidateTable
(
const Table* table
)
The name
of the table to be
removed from the table cache, or a pointer to the
corresponding Table
object.
None.
This method returns a list of all events defined within the dictionary.
int listEvents
(
List& list
)
A reference to a List
object. (See Section 2.3.10, “The List Class”.)
0
on success; -1
on
failure.
This method is used to obtain a
List
of all the indexes on
a table, given the table's name. (See
Section 2.3.10, “The List Class”.)
int listIndexes ( List&list
, const char*table
) const
listIndexes()
takes two arguments, both
of which are required:
A reference to the List
that contains the indexes following the call to the
method
The name of the table
whose
indexes are to be listed
0
on success, -1
on
failure.
This method is used to obtain a list of objects in the dictionary. It is possible to get all of the objects in the dictionary, or to restrict the list to objects of a single type.
This method has two signatures:
int listObjects ( List&list
, Object::Typetype
= Object::TypeUndefined ) const
and
int listObjects ( List&list
, Object::Typetype
, boolfullyQualified
) const
A reference to a List
object is required—this is the list that contains the
dictionary's objects after
listObjects()
is called. (See
Section 2.3.10, “The List Class”.) An optional second argument
type
may be used to restrict the
list to only those objects of the given type—that is,
of the specified
Object::Type
. (See
Object::Type.) If
type
is not given, then the list
contains all of the dictionary's objects.
You can also specify whether or not the object names in the
list
are fully qualified (that
is, whether the object name includes the database, schema,
and possibly the table name). If you specify
fullyQualified
, then you must
also specify the type
.
Setting fullyQualified
to
false
causes
listObjects()
to return objects that
use fully qualified names.
0
on success, -1
on
failure.
Creates or retrieves a hash map suitable for alteration. Requires a schema transaction to be in progress; see Dictionary::beginSchemaTrans(), for more information.
Either of the following:
int prepareHashMap ( const Table&oldTable
, Table&newTable
)
int prepareHashMap ( const Table&oldTable
, Table&newTable
, Uint32buckets
)
References to the old and new tables. Optionally, a number of buckets.
Returns 0 on success; on failure, returns -1 and sets an error.
This method removes the table, specified by name, from the local cache.
void removeCachedTable
(
const char* table
)
The name of the table
to be
removed from the cache.
None.
This method removes the specified index from the local cache, given the name of the index and that of the table in which it is contained.
void removeCachedIndex ( const char*index
, const char*table
)
The removeCachedIndex()
method requires
two arguments:
The name of the index
to be
removed from the cache
The name of the table
in
which the index is found
None.