MySQL Cluster Management API

The MySQL Cluster Management API (MGM API) is a C language API that is used for:

General Concepts

Each MGM API function needs a management server handle of type NdbMgmHandle. This handle is created by calling the function function ndb_mgm_create_handle() and freed by calling ndb_mgm_destroy_handle().

A function can return any of the following:

  1. An integer value, with a value of -1 indicating an error.
  2. A non-constant pointer value. A NULL value indicates an error; otherwise, the return value must be freed by the programmer
  3. 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);

Log Events

The database nodes and management server(s) regularly and on specific occations report on various log events that occurs in the cluster. These log events are written to the cluster log. Optionally a mgmapi client may listen to these events by 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().

Below is an example of 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);

Structured Log Events

The following steps are involved:

Sample code for listening to Backup related events. The availaable log events are listed in ndb_logevent::h

   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;
   }

Documentation generated Mon Sep 29 08:17:53 2008 from mysql source files.
© 2003-2004 MySQL AB