Table of Contents
Abstract
This chapter discusses the MySQL Cluster Management API, a C language API that is used for administrative tasks such as starting and stopping Cluster nodes, backups, and logging. It also covers MGM concepts, programming constructs, and event types.
Each MGM API function needs a management server handle of type
NdbMgmHandle. This handle is created by calling
the function ndb_mgm_create_handle() and freed
by calling ndb_mgm_destroy_handle().
See Section 5.2.3.1, “ndb_mgm_create_handle()”, and
Section 5.2.3.3, “ndb_mgm_destroy_handle()”, for more information
about these two functions.
You should not share an NdbMgmHandle between
threads. While it is possible to do so (if you implement your
own locks), this is not recommended, and each thread should use
its own management server handle.
A function can return any of the following:
An integer value, with a value of -1
indicating an error.
A non-constant pointer value. A NULL value
indicates an error; otherwise, the return value must be freed
by the programmer.
A constant pointer value, with a NULL value
indicating an error. The returned value should not be freed.
Error conditions can be identified by using the appropriate
error-reporting functions
ndb_mgm_get_latest_error() and
ndb_mgm_error().
Here is an example using the MGM API (without error handling for brevity's sake):
NdbMgmHandle handle= ndb_mgm_create_handle();
ndb_mgm_connect(handle,0,0,0);
struct ndb_mgm_cluster_state *state= ndb_mgm_get_status(handle);
for(int i=0; i > state->no_of_nodes; i++)
{
struct ndb_mgm_node_state *node_state= &state->node_states[i];
printf("node with ID=%d ", node_state->node_id);
if(node_state->version != 0)
printf("connected\n");
else
printf("not connected\n");
}
free((void*)state);
ndb_mgm_destroy_handle(&handle);
Data nodes and management servers regularly and on specific
occasions report on various log events that occur in the
cluster. These log events are written to the cluster log.
Optionally an MGM API client may listen to these events using
the method ndb_mgm_listen_event(). Each log
event belongs to a category
ndb_mgm_event_category) and has a severity
ndb_mgm_event_severity associated with it.
Each log event also has a level (0-15) associated with it.
Which log events that come out is controlled with
ndb_mgm_listen_event(),
ndb_mgm_set_clusterlog_loglevel(), and
ndb_mgm_set_clusterlog_severity_filter().
This is an example showing how to listen to events related to backup:
int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
int fd = ndb_mgm_listen_event(handle, filter);
The following steps are involved:
Create an NdbEventLogHandle using
ndb_mgm_create_logevent_handle().
Wait for and store log events using
ndb_logevent_get_next().
The log event data is available in the structure
ndb_logevent. The data which is specific
to a particular event is stored in a union between
structures; use ndb_logevent::type to
decide which structure is valid.
The following sample code demonstrates listening to events related to backups:
int filter[] = { 15, NDB_MGM_EVENT_CATEGORY_BACKUP, 0 };
NdbEventLogHandle le_handle= ndb_mgm_create_logevent_handle(handle, filter);
struct ndb_logevent le;
int r= ndb_logevent_get_next(le_handle, &le, 0);
if(r < 0)
/* error */
else if(r == 0)
/* no event */
switch(le.type)
{
case NDB_LE_BackupStarted:
... le.BackupStarted.starting_node;
... le.BackupStarted.backup_id;
break;
case NDB_LE_BackupFailedToStart:
... le.BackupFailedToStart.error;
break;
case NDB_LE_BackupCompleted:
... le.BackupCompleted.stop_gci;
break;
case NDB_LE_BackupAborted:
... le.BackupStarted.backup_id;
break;
default:
break;
}
For more information, see Section 5.2.1, “Log Event Functions”.
Available log event types are listed in
Section 5.3.4, “The Ndb_logevent_type Type”, as well as in the file
/storage/ndb/include/mgmapi/ndb_logevent.h
in the MySQL 5.1 sources.
Abstract
This section covers the structures and functions used in the MGM API. Listings are grouped by purpose or use.
Abstract
This section discusses functions that are used for listening to log events.
Description. This function is used to listen to log events, which are read from the return file descriptor. Events use a text-based format, the same as in the cluster log.
Signature.
int ndb_mgm_listen_event
(
NdbMgmHandle handle,
const int filter[]
)
Parameters. This function takes two arguments:
An NdbMgmHandle
handle.
A filter which consists of
a series of {level,
ndb_mgm_event_category} pairs (in a single
array) that are pushed to a file descriptor. Use
0 for the level to terminate the
list.
Return Value. The file descriptor from which events are to be read.
Description. This function is used to create a log event handle.
Signature.
NdbLogEventHandle ndb_mgm_create_logevent_handle
(
NdbMgmHandle handle,
const int filter[]
)
Parameters. This function takes two arguments:
An NdbMgmHandle
handle.
A filter which consists of
a series of {level,
ndb_mgm_event_category} pairs (in a single
array) that are pushed to a file descriptor. Use
0 for the level to terminate the
list.
Return Value. A log event handle.
Description. Use this function to destroy a log event handle when there is no further need for it.
Signature.
void ndb_mgm_destroy_logevent_handle
(
NdbLogEventHandle* handle
)
Parameters.
A pointer to a log event handle.
Return Value. None.
Description.
This function is used to retrieve the next log event, using
the event's data to fill in the supplied
ndb_logevent structure.
Signature.
int ndb_logevent_get_next
(
const NdbLogEventHandle handle,
struct ndb_logevent* logevent,
unsigned timeout
)
Parameters. Three parameters are expected by this functions:
An NdbLogEventHandle
A pointer to an ndb_logevent data
structure
The number of milliseconds to wait for the event before timing out
Return Value. The value returned by this function is interpreted as follows:
> 0: The event exists, and it
data was retrieved into the
logevent
0: A timeout occurred while waiting
for the event (more than
timeout milliseconds
elapsed)
< 0: An error occurred.
If the return value is less than or equal to zero, then the
logevent is not altered or
affected in any way.
Description. This function retrieves the error code from the most recent error.
You may prefer to use
ndb_logevent_get_latest_error_msg()
instead. See
Section 5.2.1.6, “ndb_logevent_get_latest_error_msg()”
Signature.
int ndb_logevent_get_latest_error
(
const NdbLogEventHandle handle
)
Parameters. A log event handle.
Return Value. An error code.
Abstract
The MGM API used for Error handling are discussed in this section.
Each MGM API error is characterised by an error code and an error message. There may also be an error description that may provide additional information about the error. The API provides functions to obtain this information in the event of an error.
Description. This function is used to get the latest error code associated with a given management server handle.
Signature.
int ndb_mgm_get_latest_error
(
const NdbMgmHandle handle
)
Parameters.
An NdbMgMHandle.
Return Value.
An error code corresponding to an
ndb_mgm_error value; see
Section 5.3.3, “The ndb_mgm_error Type”. You can obtain the related
error message using
ndb_mgm_get_latest_error_msg(); see
Section 5.2.2.2, “ndb_mgm_get_latest_error_msg()”.
Description.
This function is used to obtain the latest general error
message associated with an NdbMgmHandle.
Signature.
const char* ndb_mgm_get_latest_error_msg
(
const NdbMgmHandle handle
)
Parameters.
An NdbMgmHandle.
Return Value.
The error message text. More specific information can be
obtained using
ndb_mgm_get_latest_error_desc(); see
Section 5.2.2.3, “ndb_mgm_get_latest_error_desc()”, for
details.
Description.
Get the most recent error description associated with an
NdbMgmHandle; this description provides
additional information regarding the error message.
Signature.
const char* ndb_mgm_get_latest_error_desc
(
const NdbMgmHandle handle
)
Parameters.
An NdbMgmHandle.
Return Value. The error description text.
Abstract
This section contains information about the MGM API functions used to create and destroy management server handles.
Description. This function is used to create a handle to a management server.
Signature.
NdbMgmHandle ndb_mgm_create_handle
(
void
)
Parameters. None.
Return Value.
An NdbMgmHandle.
Description. This function can be used to set a name for the management server handle, which is then reported in the Cluster log.
Signature.
void ndb_mgm_set_name
(
NdbMgmHandle handle,
const char* name
)
Parameters. This function takes two arguments:
A management server handle.
The desired name for the
handle.
Return Value. None.
ndb_mgm_get_connectstring()ndb_mgm_get_configuration_nodeid()ndb_mgm_get_connected_port()ndb_mgm_get_connected_host()ndb_mgm_is_connected()ndb_mgm_set_connectstring()ndb_mgm_set_configuration_nodeid()ndb_mgm_connect()ndb_mgm_disconnect()Abstract
This section discusses MGM API functions that are used to
initiate, configure, and terminate connections to an
NDB management server.
Description. This function retrieves the connectstring used for a connection.
This function returns the default connectstring if no call
to ndb_mgm_set_connectstring() has been
performed. In addition, the returned connectstring may be
formatted slightly differently than the original in that it
may contain specifiers not present in the original.
The connectstring format is the same as that discussed for
Section 5.2.4.6, “ndb_mgm_set_connectstring()”.
Signature.
const char* ndb_mgm_get_connectstring
(
NdbMgmHandle handle,
char* buffer,
int size
)
Parameters. This function takes three arguments:
An NdbMgmHandle.
A pointer to a buffer in
which to place the result.
The size of the buffer.
Return Value.
The connectstring — this is the same value that is
pushed to the buffer.
Description. This function gets the ID of the node to which the connection is being (or was) made.
Signature.
int ndb_mgm_get_configuration_nodeid
(
NdbMgmHandle handle
)
Parameters. A management server handle.
Return Value. A node ID.
Description. This function retrieves the number of the port used by the connection.
Signature.
int ndb_mgm_get_connected_port
(
NdbMgmHandle handle
)
Parameters.
An NdbMgmHandle.
Return Value. A port number.
Description. This function is used to obtain the name of the host to which the connection is made.
Signature.
const char* ndb_mgm_get_connected_host
(
NdbMgmHandle handle
)
Parameters.
A management server handle.
Return Value. A hostname.
Description. Used to determine whether a connection has been established.
Signature.
int ndb_mgm_is_connected
(
NdbMgmHandle handle
)
Parameters.
A management server handle.
Return Value. This function returns an integer, whose value is interpreted as follows:
0: Not connected to the management
node.
Any non-zero value: A connection has been established with the management node.
Description. This function is used to set the connectstring for a management server connection to a node.
Signature.
int ndb_mgm_set_connectstring
(
NdbMgmHandle handle,
const char* connectstring
)
Parameters.
ndb_mgm_set_connectstring() takes two
parameters:
A management server handle.
A connectstring whose
format is shown here:
connectstring:= [nodeid-specification,]host-specification[,host-specification]
(It is possible to establish connections with multiple management servers using a single connectstring.)
nodeid-specification:= nodeid=idhost-specification:=host[:port]
id,
port, and
host are defined as
follows:
id: An integer
greater than 0 identifying a
node in config.ini.
port: An integer
referring to a standard Unix port.
host: A string
containing a valid network host address.
Section 5.2.4.1, “ndb_mgm_get_connectstring()” also uses this
format for connectstrings.
Return Value.
This function returns -1 in the event of
failure.
Description. This function sets the connection node ID.
Signature.
int ndb_mgm_set_configuration_nodeid
(
NdbMgmHandle handle,
int id
)
Parameters. This function requires two parameters:
An NdbMgmHandle.
The id of the node to connect to.
Return Value.
This function returns -1 in the event of
failure.
Description.
This function establishes a connection to a management
server specified by the connectstring set by
Section 5.2.4.6, “ndb_mgm_set_connectstring()”.
Signature.
int ndb_mgm_connect
(
NdbMgmHandle handle,
int retries,
int delay,
int verbose
)
Parameters. This function takes 4 arguments:
A management server handle.
The number of retries to make when
attempting to connect. 0 for this
value means that one connection attempt is made.
The number of seconds to
delay between connection
attempts.
If verbose is 1, then a message is
printed for each connection attempt.
Return Value.
This function returns -1 in the event of
failure.
Abstract
This section discusses how to obtain the status of
NDB Cluster nodes.
Description.
This function is used to obtain the status of the nodes in
an NDB Cluster.
The caller must free the pointer returned by this function.
Signature.
struct ndb_mgm_cluster_state* ndb_mgm_get_status
(
NdbMgmHandle handle
)
Parameters.
This function takes a single parameter — a management
server handle.
Return Value.
A pointer to an ndb_mgm_cluster_state
data structure. See
Section 5.4.3, “The ndb_mgm_cluster_state Structure”, for more
information.
Abstract
The MGM API provides several functions which can be used to start, stop, and restart one or more Cluster data nodes. These functions are discussed in this section.
Starting, Stopping, and Restarting Nodes. You can start, stop, and restart Cluster nodes using the following functions:
Starting Nodes.
Use ndb_mgm_start().
Stopping Nodes.
Use ndb_mgm_stop(),
ndb_mgm_stop2(), or
ndb_mgm_stop3().
Restarting Nodes.
Use ndb_mgm_restart(),
ndb_mgm_restart2(), or
ndb_mgm_restart3().
These functions are detailed in the next few sections.
Description.
This function can be used to start one or more Cluster
nodes. The nodes to be started must have been started with
the no-start option (-n), meaning that the
data node binary was started and is waiting for a
START management command which actually
enables the node.
Signature.
int ndb_mgm_start
(
NdbMgmHandle handle,
int number,
const int* list
)
Parameters. ndb_mgm_start() takes 3 parameters:
An NdbMgmHandle.
A number of nodes to be
started. Use 0 to start all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be started.
Return Value.
The number of nodes actually started; in the event of
failure, -1 is returned.
Description. This function stops one or more data nodes.
Signature.
int ndb_mgm_stop
(
NdbMgmHandle handle,
int number,
const int* list
)
Parameters. ndb_mgm_stop() takes 3 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
Calling this function is equivalent to calling
ndb_mgm_stop2(. See
Section 5.2.6.3, “handle,
number,
list, 0)ndb_mgm_stop2()”.
Return Value.
The number of nodes actually stopped; in the event of
failure, -1 is returned.
Description.
Like ndb_mgm_stop(), this function stops
one or more data nodes. However, it offers the ability to
specify whether or not the nodes shut down gracefully.
Signature.
int ndb_mgm_stop2
(
NdbMgmHandle handle,
int number,
const int* list,
int abort
)
Parameters. ndb_mgm_stop2() takes 4 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
The value of abort
determines how the nodes will be shut down.
1 indicates the nodes will shut
down immediately; 0 indicates that
the nodes will stop gracefully.
Return Value.
The number of nodes actually stopped; in the event of
failure, -1 is returned.
Description.
Like ndb_mgm_stop() and
ndb_mgm_stop2(), this function stops one
or more data nodes. Like ndb_mgm_stop2(),
it offers the ability to specify whether the nodes should
shut down gracefully. In addition, it provides for a way to
check to see whether disconnection is required prior to
stopping a node.
Signature.
int ndb_mgm_stop2
(
NdbMgmHandle handle,
int number,
const int* list,
int abort,
int* disconnect
)
Parameters. ndb_mgm_stop3() takes 5 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
The value of abort
determines how the nodes will be shut down.
1 indicates the nodes will shut
down immediately; 0 indicates that
the nodes will stop gracefully.
If disconnect returns
1 (true), this
means the you must disconnect before you can apply the
command to stop. For example, disconnecting is
required when stopping the management server to which
the handle is connected.
Return Value.
The number of nodes actually stopped; in the event of
failure, -1 is returned.
Description. This function can be used to restart one or more Cluster data nodes.
Signature.
int ndb_mgm_restart
(
NdbMgmHandle handle,
int number,
const int* list
)
Parameters. ndb_mgm_restart() takes 3 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
Calling this function is equivalent to calling
ndb_mgm_restart2(handle,number,list, 0, 0, 0);
See Section 5.2.6.6, “ndb_mgm_restart2()”, for more
information.
Return Value.
The number of nodes actually restarted;
-1 on failure.
Description.
Like ndb_mgm_restart(), this function can
be used to restart one or more Cluster data nodes. However,
ndb_mgm_restart2() provides additional
restart options, including initial restart, waiting start,
and immediate (forced) restart.
Signature.
int ndb_mgm_restart2
(
NdbMgmHandle handle,
int number,
const int* list,
int initial
int nostart,
int abort
)
Parameters. ndb_mgm_restart2() takes 6 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
If initial is true
(1), then each node undergoes an
initial restart — that is, its filesystem is
removed.
If nostart is true, then the nodes
are not actually started, but instead are left ready
for a start command.
If abort is true, then the
nodes are restarted immediately, bypassing any
graceful restart.
Return Value.
The number of nodes actually restarted;
-1 on failure.
Description.
Like ndb_mgm_restart2(), this function
can be used to cause an initial restart, waiting restart,
and immediate (forced) restart on one or more Cluster data
nodes. However, ndb_mgm_restart3()
provides additional the additional options of checking
whether disconnection is required prior to the restart.
Signature.
int ndb_mgm_restart3
(
NdbMgmHandle handle,
int number,
const int* list,
int initial
int nostart,
int abort,
int* disconnect
)
Parameters. ndb_mgm_restart() takes 7 parameters:
An NdbMgmHandle.
The number of nodes to be
stopped. Use 0 to stop all of the
data nodes in the cluster.
A list of the node IDs of
the nodes to be stopped.
If initial is true
(1), then each node undergoes an
initial restart — that is, its filesystem is
removed.
If nostart is true, then the nodes
are not actually started, but instead are left ready
for a start command.
If abort is true, then the
nodes are forced to restart immediately without
performing a graceful restart.
If disconnect returns
1 (true), this
means the you must disconnect before you can apply the
command to restart. For example, disconnecting is
required when stopping the management server to which
the handle is connected.
Return Value.
The number of nodes actually restarted;
-1 on failure.
Abstract
This section covers the functions available in the MGM API for controlling the output of the cluster log.
Description. This function is used to retrieve the cluster log severity filter currently in force.
Signature.
const unsigned int* ndb_mgm_get_clusterlog_severity_filter
(
NdbMgmHandle handle
)
Parameters.
An NdbMgmHandle.
Return Value.
A severity filter, which is a vector
containing 7 elements. Each element equals
1 if the corresponding severity indicator
is enabled, and 0 if it is not. A
severity level is stored at position
ndb_mgm_clusterlog_level —
for example, the “error” level is stored at
position NDB_MGM_EVENT_SEVERITY_ERROR.
The first element in the vector
(NDB_MGM_EVENT_SEVERITY_ON) signals
whether the cluster log is enabled or disabled.
Description. This function is used to set a cluster log severity filter.
Signature.
int ndb_mgm_set_clusterlog_severity_filter
(
NdbMgmHandle handle,
enum ndb_mgm_event_severity severity,
int enable,
struct ndb_mgm_reply* reply
)
Parameters. This function takes 4 parameters:
A management server handle.
A cluster log severity to
filter.
A flag to enable or disable
the filter; 1 enables and
0 disables the filter.
A pointer to an ndb_mgm_reply
structure for a reply message. See
Section 5.4.4, “The ndb_mgm_reply Structure”.
Return Value.
The function returns -1 in the event of
failure.
Description. This function is used to set the log category and levels for the cluster log.
Signature.
int ndb_mgm_set_clusterlog_loglevel
(
NdbMgmHandle handle,
int id,
enum ndb_mgm_event_category category,
int level,
struct ndb_mgm_reply* reply)
Parameters. This function takes 5 parameters:
An NdbMgmHandle.
The id of the node
affected.
An event category —
this is one of the values listed in
Section 5.3.7, “The ndb_mgm_event_category Type” .
A logging level.
A pointer to an ndb_mgm_reply
structure for the reply
message. (See Section 5.4.4, “The ndb_mgm_reply Structure”.)
Return Value.
In the event of an error, this function returns
-1.
Abstract
This section covers the functions provided in the MGM API for starting and stopping backups.
Description. This function is used to initiate a backup of a MySQL Cluster.
Signature.
int ndb_mgm_start_backup
(
NdbMgmHandle handle,
int wait,
unsigned int* id,
struct ndb_mgm_reply* reply
)
Parameters. This function requires 4 parameters:
A management server handle
(an NdbMgmHandle).
A wait flag, with the
following possible values:
0: Do not wait for
confirmation of the backup.
1: Wait for the backup to be
started.
2: Wait for the backup to be
completed.
A backup id to be returned
by the function.
No backup id is returned
if wait is set equal to
0.
A pointer to an ndb_mgm_reply
structure to accommodate a
reply. See
Section 5.4.4, “The ndb_mgm_reply Structure”.
Return Value.
In the event of failure, the function returns
-1.
Description. This function is used to stop a Cluster backup.
Signature.
int ndb_mgm_abort_backup
(
NdbMgmHandle handle,
unsigned int id,
struct ndb_mgm_reply* reply)
Parameters. This function takes 3 parameters:
An NdbMgmHandle.
The id of the backup to be
aborted.
A pointer to an ndb_mgm_reply
structure.
Return Value.
In case an error, this function returns
-1.
Abstract
The MGM API allows the programmer to put the cluster into single-user mode — and to return it to normal mode again — from within an application. This section covers the functions that are used for these operations.
Description. This function is used to enter single-user mode on a given node.
Signature.
int ndb_mgm_enter_single_user
(
NdbMgmHandle handle,
unsigned int id,
struct ndb_mgm_reply* reply
)
Parameters. This function takes 3 parameters:
An NdbMgmHandle.
The id of the node to be
used in single-user mode.
A pointer to an ndb_mgm_reply
structure, used for a reply
message.
Return Value.
Returns -1 in the event of failure.
Description. This function is used to exit single-user mode and to return to normal operation.
Signature.
int ndb_mgm_exit_single_user
(
NdbMgmHandle handle,
struct ndb_mgm_reply* reply
)
Parameters. This function requires 2 arguments:
An NdbMgmHandle.
A pointer to an ndb_mgm_reply.
Return Value.
Returns -1 in case of an error.
Abstract
This section discusses the datatypes defined by the MGM API.
The types described in this section are all defined in the file
/storage/ndb/include/mgmapi/mgmapi.h, with
the exception of Ndb_logevent_type,
ndb_mgm_event_severity,
ndb_mgm_logevent_handle_error, and
ndb_mgm_event_category, which are defined in
/storage/ndb/include/mgmapi/ndb_logevent.h.
Description. This is used to classify the different types of nodes in a MySQL Cluster.
Enumeration Values.
| Value | Description |
|---|---|
NDB_MGM_NODE_TYPE_UNKNOWN | Unknown |
NDB_MGM_NODE_TYPE_API | API Node (SQL node) |
NDB_MGM_NODE_TYPE_NDB | Data node |
NDB_MGM_NODE_TYPE_MGM | Management node |
Description. This type describes a Cluster node's status.
Enumeration Values.
| Value | Description |
|---|---|
NDB_MGM_NODE_STATUS_UNKNOWN | The node's status is not known |
NDB_MGM_NODE_STATUS_NO_CONTACT | The node cannot be contacted |
NDB_MGM_NODE_STATUS_NOT_STARTED | The node has not yet executed the startup protocol |
NDB_MGM_NODE_STATUS_STARTING | The node is executing the startup protocol |
NDB_MGM_NODE_STATUS_STARTED | The node is running |
NDB_MGM_NODE_STATUS_SHUTTING_DOWN | The node is shutting down |
NDB_MGM_NODE_STATUS_RESTARTING | The node is restarting |
NDB_MGM_NODE_STATUS_SINGLEUSER | The node is running in single-user (maintenance) mode |
NDB_MGM_NODE_STATUS_RESUME | The node is in resume mode |
Description. The values for this type are the error codes that may be generated by MGM API functions.
Enumeration Values.
| Type | Value | Description |
|---|---|---|
| Service Request Errors | ||
NDB_MGM_ILLEGAL_CONNECT_STRING | Invalid connectstring | |
NDB_MGM_ILLEGAL_SERVER_HANDLE | Invalid management server handle | |
NDB_MGM_ILLEGAL_SERVER_REPLY | Invalid response from management server | |
NDB_MGM_ILLEGAL_NUMBER_OF_NODES | Invalid number of nodes | |
NDB_MGM_ILLEGAL_NODE_STATUS | Invalid node status | |
NDB_MGM_OUT_OF_MEMORY | Memory allocation error | |
NDB_MGM_SERVER_NOT_CONNECTED | Management server not connected | |
NDB_MGM_COULD_NOT_CONNECT_TO_SOCKET | Not able to connect to socket | |
| Node ID Allocation Errors | ||
NDB_MGM_ALLOCID_ERROR | Generic error; may be possible to retry and recover | |
NDB_MGM_ALLOCID_CONFIG_MISMATCH | Non-recoverable generic error | |
| Service Errors | (Failure of a node or cluster to start, shut down, or restart | |
NDB_MGM_START_FAILED | Startup failure | |
NDB_MGM_STOP_FAILED | Shutdown failure | |
NDB_MGM_RESTART_FAILED | Restart failure | |
| Backup Service Errors | ||
NDB_MGM_COULD_NOT_START_BACKUP | Unable to initiate backup | |
NDB_MGM_COULD_NOT_ABORT_BACKUP | Unable to abort backup | |
| Single-User Mode Service Errors | ||
NDB_MGM_COULD_NOT_ENTER_SINGLE_USER_MODE | Unable to enter single-user mode | |
NDB_MGM_COULD_NOT_EXIT_SINGLE_USER_MODE | Unable to exit single-user mode | |
| Usage Errors | ||
NDB_MGM_USAGE_ERROR | General usage error |
Description.
These are the types of log event events available in the MGM
API, grouped by event category. (See
Section 5.3.7, “The ndb_mgm_event_category Type”.)
Enumeration Values.
| Category | Type | Description |
|---|---|---|
NDB_MGM_EVENT_CATEGORY_CONNECTION | ||
NDB_LE_Connected | ||
NDB_LE_Disconnected | ||
NDB_LE_CommunicationClosed | ||
NDB_LE_CommunicationOpened | ||
NDB_LE_ConnectedApiVersion | ||
NDB_MGM_EVENT_CATEGORY_CHECKPOINT | ||
NDB_LE_GlobalCheckpointStarted | ||
NDB_LE_GlobalCheckpointCompleted | ||
NDB_LE_LocalCheckpointStarted | ||
NDB_LE_LocalCheckpointCompleted | ||
NDB_LE_LCPStoppedInCalcKeepGci | ||
NDB_LE_LCPFragmentCompleted | ||
NDB_MGM_EVENT_CATEGORY_STARTUP | ||
NDB_LE_NDBStartStarted | ||
NDB_LE_NDBStartCompleted | ||
NDB_LE_STTORRYRecieved | ||
NDB_LE_StartPhaseCompleted | ||
NDB_LE_CM_REGCONF | ||
NDB_LE_CM_REGREF | ||
NDB_LE_FIND_NEIGHBOURS | ||
NDB_LE_NDBStopStarted | ||
NDB_LE_NDBStopCompleted | ||
NDB_LE_NDBStopForced | ||
NDB_LE_NDBStopAborted | ||
NDB_LE_StartREDOLog | ||
NDB_LE_StartLog | ||
NDB_LE_UNDORecordsExecuted | ||
NDB_LE_StartReport | ||
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | ||
NDB_LE_NR_CopyDict | ||
NDB_LE_NR_CopyDistr | ||
NDB_LE_NR_CopyFragsStarted | ||
NDB_LE_NR_CopyFragDone | ||
NDB_LE_NR_CopyFragsCompleted | ||
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | ||
NDB_LE_NodeFailCompleted | ||
NDB_LE_NODE_FAILREP | ||
NDB_LE_ArbitState | ||
NDB_LE_ArbitResult | ||
NDB_LE_GCP_TakeoverStarted | ||
NDB_LE_GCP_TakeoverCompleted | ||
NDB_LE_LCP_TakeoverStarted | ||
NDB_LE_LCP_TakeoverCompleted | ||
NDB_MGM_EVENT_CATEGORY_STATISTIC | ||
NDB_LE_TransReportCounters | ||
NDB_LE_OperationReportCounters | ||
NDB_LE_TableCreated | ||
NDB_LE_UndoLogBlocked | ||
NDB_LE_JobStatistic | ||
NDB_LE_SendBytesStatistic | ||
NDB_LE_ReceiveBytesStatistic | ||
NDB_LE_MemoryUsage | ||
NDB_MGM_EVENT_CATEGORY_ERROR | ||
NDB_LE_TransporterError | ||
NDB_LE_TransporterWarning | ||
NDB_LE_MissedHeartbeat | ||
NDB_LE_DeadDueToHeartbeat | ||
NDB_LE_WarningEvent | ||
NDB_MGM_EVENT_CATEGORY_INFO | ||
NDB_LE_SentHeartbeat | ||
NDB_LE_CreateLogBytes | ||
NDB_LE_InfoEvent | ||
| [Single-User Mode] | NDB_LE_SingleUser | |
NDB_LE_EventBufferStatus | ||
NDB_MGM_EVENT_CATEGORY_BACKUP | ||
NDB_LE_BackupStarted | ||
NDB_LE_BackupFailedToStart | ||
NDB_LE_BackupCompleted | ||
NDB_LE_BackupAborted |
Description.
These are the log event severities used to filter the cluster
log by
ndb_mgm_set_clusterlog_severity_filter(),
and to filter listening to events by
ndb_mgm_listen_event().
Enumeration Values.
| Value | Description |
|---|---|
NDB_MGM_ILLEGAL_EVENT_SEVERITY | Invalid event severity specified |
NDB_MGM_EVENT_SEVERITY_ON | Cluster logging is enabled |
NDB_MGM_EVENT_SEVERITY_DEBUG | Used for MySQL Cluster development only |
NDB_MGM_EVENT_SEVERITY_INFO | Informational messages |
NDB_MGM_EVENT_SEVERITY_WARNING | Conditions that are not errors as such, but that might require special handling |
NDB_MGM_EVENT_SEVERITY_ERROR | Non-fatal error conditions that should be corrected |
NDB_MGM_EVENT_SEVERITY_CRITICAL | Critical conditions such as device errors or out of memory errors |
NDB_MGM_EVENT_SEVERITY_ALERT | Conditions that require immediate attention, such as corruption of the cluster |
NDB_MGM_EVENT_SEVERITY_ALL | All severity levels |
See Section 5.2.7.2, “ndb_mgm_set_clusterlog_severity_filter()”,
and Section 5.2.1.1, “ndb_mgm_listen_event()”, for information on
how this type is used by those functions.
Description. This type is used to describe log event errors.
Enumeration Values.
| Value | Description |
|---|---|
NDB_LEH_NO_ERROR | No error |
NDB_LEH_READ_ERROR | Read error |
NDB_LEH_MISSING_EVENT_SPECIFIER | Invalid, incomplete, or missing log event specification |
NDB_LEH_UNKNOWN_EVENT_TYPE | Unknown log event type |
NDB_LEH_UNKNOWN_EVENT_VARIABLE | Unknown log event variable |
NDB_LEH_INTERNAL_ERROR | Internal error |
Description.
These are the log event categories referenced in
Section 5.3.4, “The Ndb_logevent_type Type”. They are also used by the
MGM API functions
ndb_mgm_set_clusterlog_loglevel() and
ndb_mgm_listen_event().
Enumeration Values.
| Value | Description |
|---|---|
NDB_MGM_ILLEGAL_EVENT_CATEGORY | Invalid log event category |
NDB_MGM_EVENT_CATEGORY_STARTUP | Log events occurring during startup |
NDB_MGM_EVENT_CATEGORY_SHUTDOWN | Log events occurring during shutdown |
NDB_MGM_EVENT_CATEGORY_STATISTIC | Statistics log events |
NDB_MGM_EVENT_CATEGORY_CHECKPOINT | Log events related to checkpoints |
NDB_MGM_EVENT_CATEGORY_NODE_RESTART | Log events occurring during node restart |
NDB_MGM_EVENT_CATEGORY_CONNECTION | Log events relating to connections between cluster nodes |
NDB_MGM_EVENT_CATEGORY_BACKUP | Log events relating to backups |
NDB_MGM_EVENT_CATEGORY_CONGESTION | Log events relating to congestion |
NDB_MGM_EVENT_CATEGORY_INFO | Uncategorised log events (severity level INFO) |
NDB_MGM_EVENT_CATEGORY_ERROR | Uncategorised log events (severity level WARNING,
ERROR,
CRITICAL, or
ALERT) |
See Section 5.2.7.3, “ndb_mgm_set_clusterlog_loglevel()”, and
Section 5.2.1.1, “ndb_mgm_listen_event()”, for more information.
Abstract
This section covers the programming structures available in the MGM API.
Description. This structure models a Cluster log event, and is used for storing and retrieving log event information.
Definition.
ndb_logevent has 8 members, the first 7 of
which are shown in the following list:
void*
: An
handleNdbLogEventHandle, set by
ndb_logevent_get_next(). This handle
is used only for purposes of comparison.
enum Ndb_logevent_type
: Tells which
type of event this is.
type
See Section 5.3.4, “The Ndb_logevent_type Type”, for possible
values.
unsigned
: The time at
which the log event was registered with the management
server.
time
enum ndb_mgm_event_category
: The log
event category.
category
See Section 5.3.7, “The ndb_mgm_event_category Type”, for
possible values.
enum ndb_mgm_event_severity
: The log
event severity.
severity
See Section 5.3.5, “The ndb_mgm_event_severity Type”, for
possible values.
unsigned
: The log
event level. This is a value in the range of 0 to 15,
inclusive.
level
unsigned
: The
node ID of the node that reported this event.
source_nodeid
The 8th member of this structure
contains data specific to the log event, and is dependent on
its type. It is defined as the union of a number of data
structures, each corresponding to a log event type. Which
structure to use is determined by the value of
type, and is shown in the following
table:
Ndb_logevent_type Value | Structure |
|---|---|
NDB_LE_Connected | Connected:
unsigned |
NDB_LE_Disconnected | Disconnected:
unsigned |
NDB_LE_CommunicationClosed | CommunicationClosed:
unsigned |
NDB_LE_CommunicationOpened | CommunicationOpened:
unsigned |
NDB_LE_ConnectedApiVersion | ConnectedApiVersion:
unsigned |
NDB_LE_GlobalCheckpointStarted | GlobalCheckpointStarted:
unsigned |
NDB_LE_GlobalCheckpointCompleted | GlobalCheckpointCompleted:
unsigned |
NDB_LE_LocalCheckpointStarted | LocalCheckpointStarted:
unsigned |
NDB_LE_LocalCheckpointCompleted | LocalCheckpointCompleted:
unsigned |
NDB_LE_LCPStoppedInCalcKeepGci | LCPStoppedInCalcKeepGci:
unsigned |
NDB_LE_LCPFragmentCompleted | LCPFragmentCompleted:
unsigned |
NDB_LE_UndoLogBlocked | UndoLogBlocked:
unsigned |
NDB_LE_NDBStartStarted | NDBStartStarted:
unsigned |
NDB_LE_NDBStartCompleted | NDBStartCompleted:
unsigned |
NDB_LE_STTORRYRecieved | STTORRYRecieved:
[NONE]
|
NDB_LE_StartPhaseCompleted | StartPhaseCompleted:
unsigned |
NDB_LE_CM_REGCONF | CM_REGCONF:
unsigned |
NDB_LE_CM_REGREF | CM_REGREF:
unsigned |
NDB_LE_FIND_NEIGHBOURS | FIND_NEIGHBOURS:
unsigned |
NDB_LE_NDBStopStarted | NDBStopStarted:
unsigned |
NDB_LE_NDBStopCompleted | NDBStopCompleted:
unsigned |
NDB_LE_NDBStopForced | NDBStopForced:
unsigned |
NDB_LE_NDBStopAborted | NDBStopAborted:
[NONE]
|
NDB_LE_StartREDOLog | StartREDOLog:
unsigned |
NDB_LE_StartLog | StartLog:
unsigned |
NDB_LE_UNDORecordsExecuted | UNDORecordsExecuted:
unsigned |
NDB_LE_NR_CopyDict | NR_CopyDict:
[NONE]
|
NDB_LE_NR_CopyDistr | NR_CopyDistr:
[NONE]
|
NDB_LE_NR_CopyFragsStarted | NR_CopyFragsStarted:
unsigned |
NDB_LE_NR_CopyFragDone | NR_CopyFragDone:
unsigned |
NDB_LE_NR_CopyFragsCompleted | NR_CopyFragsCompleted:
unsigned |
NDB_LE_NodeFailCompleted | NodeFailCompleted:
unsigned(For block and
completing_node,
0 is interpreted as
“all”.) |
NDB_LE_NODE_FAILREP | NODE_FAILREP:
unsigned |
NDB_LE_ArbitState | ArbitState:
unsigned |
NDB_LE_ArbitResult | ArbitResult:
unsigned |
NDB_LE_GCP_TakeoverStarted | GCP_TakeoverStarted:
[NONE]
|
NDB_LE_GCP_TakeoverCompleted | GCP_TakeoverCompleted:
[NONE]
|
NDB_LE_LCP_TakeoverStarted | LCP_TakeoverStarted:
[NONE]
|
NDB_LE_TransReportCounters | TransReportCounters:
unsigned |
NDB_LE_OperationReportCounters | OperationReportCounters:
unsigned |
NDB_LE_TableCreated | TableCreated:
unsigned |
NDB_LE_JobStatistic | JobStatistic:
unsigned |
NDB_LE_SendBytesStatistic | SendBytesStatistic:
unsigned |
NDB_LE_ReceiveBytesStatistic | ReceiveBytesStatistic:
unsigned |
NDB_LE_MemoryUsage | MemoryUsage:
int |
NDB_LE_TransporterError | TransporterError:
unsigned |
NDB_LE_TransporterWarning | TransporterWarning:
unsigned |
NDB_LE_MissedHeartbeat | MissedHeartbeat:
unsigned |
NDB_LE_DeadDueToHeartbeat | DeadDueToHeartbeat:
unsigned |
NDB_LE_WarningEvent | WarningEvent:
[NOT YET IMPLEMENTED]
|
NDB_LE_SentHeartbeat | SentHeartbeat:
unsigned |
NDB_LE_CreateLogBytes | CreateLogBytes:
unsigned |
NDB_LE_InfoEvent | InfoEvent:
[NOT YET IMPLEMENTED]
|
NDB_LE_EventBufferStatus | EventBufferStatus:
unsigned |
NDB_LE_BackupStarted | BackupStarted:
unsigned |
NDB_LE_BackupFailedToStart | BackupFailedToStart:
unsigned |
NDB_LE_BackupCompleted | BackupCompleted:
unsigned |
NDB_LE_BackupAborted | BackupAborted:
unsigned |
NDB_LE_SingleUser | SingleUser:
unsigned |
NDB_LE_StartReport | StartReport:
unsigned |
Description. Provides information on the status of a Cluster node.
Definition. This structure contains the following members:
int
: The
cluster node's node ID.
node_id
enum ndb_mgm_node_type
: The node
type.
node_type
See Section 5.3.1, “The ndb_mgm_node_type Type”, for permitted
values.
enum ndb_mgm_node_status
: The
node's status.
node_status
See Section 5.3.2, “The ndb_mgm_node_status Type”, for permitted
values.
int
: The
start phase.
start_phase
This is valid only if the
node_type is
NDB_MGM_NODE_TYPE_NDB and the
node_status is
NDB_MGM_NODE_STATUS_STARTING.
int
: The ID
for heartbeats and master takeover.
dynamic_id
Valid only for data (ndbd) nodes.
int
: The
node group to which the node belongs.
node_group
Valid only for data (ndbd) nodes.
int
: Internal
version number.
version
int
: The
number of times this node has connected to or
disconnected from the management server.
connect_count
char
:
The IP address of the node when it connected to the
management server.
connect_address[]
This value will be empty if the management server has been restarted since the node last connected.
Description.
Provides information on the status of all Cluster nodes. This
structure is returned by
ndb_mgm_get_status().
Definition. This structure has the following two members;
int
: The
number of elements in the
no_of_nodesnode_states array.
struct ndb_mgm_node_state
: An
array containing the states of the nodes.
node_states[]
Each element of this array is an
ndb_mgm_node_state structure. For
more information, see
Section 5.4.2, “The ndb_mgm_node_state Structure”.
Description. Contains response information, consisting of a response code and a corresponding message, from the management server.
Definition. This structure contains two members, as shown here:
int
: For a
successful operation, this value is
return_code0; otherwise, it contains an error
code.
For error codes, see Section 5.3.3, “The ndb_mgm_error Type”.
char
:
contains the text of the response or error message.
message[256]
See Section 5.2.2.1, “ndb_mgm_get_latest_error()”, and
Section 5.2.2.2, “ndb_mgm_get_latest_error_msg()”.