The sections in this chapter describe commands used in the MySQL Cluster Manager 8.4.3 client for tasks such as defining sites, packages, and MySQL NDB Cluster instances (“clusters”); configuring a MySQL NDB Cluster; and getting the status of a running MySQL NDB Cluster. These commands are issued to the management agent using the mysql client program included with the MySQL NDB Cluster distribution (for information about the mysql client not specific to using MySQL Cluster Manager, see mysql — The MySQL Command-Line Client). Each MySQL Cluster Manager client command takes the form shown here:

instruction [options] [arguments]

options:
    option [option] [...]

option:
        --option-long-name[=value-list]
    |   -option-short-name [value-list]

value-list:
    value[,value[,...]]

arguments:
    argument [argument] [...]

Consider the following MySQL Cluster Manager command, which adds a host named torsk to the site mysite:

add hosts --hosts=torsk mysite;

In this example, the command contains a add hosts instruction. An instruction consists of one or two keywords, such as set, or show status.

Most command options have short forms, consisting of single letters, in addition to their long forms. Using the short form of the --hosts option, the previous example could also be written like this:

add hosts -h torsk mysite;

The long form of an option must be preceded by a double dash (--), and is not case-sensitive (lower case being the canonical form). The short form of an option must be preceded by a single dash (-), and is case-sensitive. In either case, the dash character or characters must come immediately before the option name, and there must be no space characters between them. Otherwise, the MySQL Cluster Manager client cannot parse the command correctly. More information about long and short forms of options is given later in this section.

Important

Do not confuse options given to MySQL Cluster Manager client commands with mysql client options. A MySQL Cluster Manager client command option is always employed as part of a MySQL Cluster Manager client command; it is not passed to the mysql client when invoking it.

In addition, you cannot issue queries or other SQL statements in the MySQL Cluster Manager client. These are not recognized by the client, and are rejected with an error. The converse of this is also true: MySQL Cluster Manager client commands are not recognized by the standard mysql client.

The instruction just shown takes the argument mysite. The argument is usually an identifier that names the object to be effected; in this case, the command deletes the site whose name matches the argument. (For more information, see Section 5.2.6, “The create site Command”.)

An additional --verbose option can be used for the create cluster ,add process, and list hosts commands. In both cases, using the option causes the command to return a list of the MySQL NDB Cluster processes affected by the command; this includes their node IDs, process types, and the hosts where they are located.

Identifiers in client commands. A legal MySQL Cluster Manager identifier consists of any sequence of characters from among the following:

The letters a through z and A through Z
The digits 0 through 9
The dash (-), period (.), and underscore (_) characters

A MySQL Cluster Manager identifier must begin with a letter or digit.

Case-sensitivity rules for client commands. The rules for case-sensitivity of MySQL Cluster Manager identifiers, commands, command options, process names, and configuration attributes are as follows:

Identifiers are case-sensitive. For example, delete site mycluster cannot be used to delete a site named myCluster.
Command keywords and the long forms of command options are case-insensitive. For example, any of the three commands delete cluster mycluster, DELETE CLUSTER mycluster, and DeLeTe cLuStEr mycluster works to delete the MySQL NDB Cluster instance named mycluster.
In this manual, we show command keywords and the long forms of command options in lowercase, but you are not required to follow this convention if you do not wish to do so.
The short forms of command options are case-sensitive. For example, for the restore cluster command, the -p (lowercase) is the short form of the --parallelism option, but -P (uppercase) is the short form of the --privilege-tables option.
Names of MySQL NDB Cluster processes are case-insensitive. For example, either of the commands get --include-defaults DataMemory:ndbd mycluster or get --include-defaults datamemory:NDBD mycluster reports the data memory allocated for each ndbd process in the cluster named mycluster.
In this manual, we show names of MySQL NDB Cluster processes in lowercase. You are not required to follow this convention if you do not wish to do so; however, since the corresponding executables are named and must be invoked in lowercase, we suggest that you use lowercase.
Configuration attribute names are case-insensitive. For example, either of the commands get --include-defaults DataMemory:ndbd mycluster or get --include-defaults datamemory:ndbd mycluster returns the data memory allocated for each ndbd process in the cluster named mycluster; either of the commands set engine-condition-pushdown:mysqld:4=0 mycluster or set Engine-Condition-Pushdown:mysqld:4=0 mycluster disables the condition pushdown optimization in the mysqld process having the node ID 4 in the MySQL NDB Cluster named mycluster.

Note

Configuration attributes in the MySQL Cluster Manager derive from two different sources: MySQL NDB Cluster configuration parameters, and MySQL Server options. MySQL NDB Cluster configuration parameters are case-insensitive, but their canonical forms use upper camelcase (that is, medial capitalization including the first letter). This means that whether you set a value for data memory using the MySQL Cluster Manager client or in the config.ini file, you can refer to it as DataMemory, datamemory, or dATAmEMORY without any negative impact. However, MySQL Server command-line options are case-sensitive and use only lowercase. This means that, for example, set Engine-Condition-Pushdown:mysqld:4=0 mycluster in the MySQL Cluster Manager client works to disable condition pushdown in the indicated mysqld process, but if you invoke the mysqld executable from a system prompt using --Engine-Condition-Pushdown=0, mysqld fails to start.

In this manual, for easy recognition, we show configuration attribute names as having the same lettercase used in other MySQL documentation; thus, we always refer to DataMemory, rather than datamemory or DATAMEMORY, and engine-condition-pushdown, rather than Engine-Condition-Pushdown or ENGINE-CONDITION-PUSHDOWN. While you are not required to do this when using MySQL Cluster Manager, we suggest that you also follow this convention.

Note

Values that contain space characters must be quoted using single quote (') characters. For example, if you wish to define a package named mypackage for a site named mysite using /usr/local/mysql cluster/8.4 (where a space occurs between mysql and cluster) as the path to the base directory on all hosts, the correct command would be add package --basedir='/usr/local/mysql cluster/8.4' mypackage.

To decrease the possibility of errors in reading and entering MySQL Cluster Manager commands, we recommend avoiding the use of space characters whenever possible.

Each command must end with a terminator character. By default, this is the semicolon (;) character. However, the sequences \g and \G are also supported as command terminators. The \G terminator causes the output to be vertically formatted (the same as in the standard mysql client), as shown in this example:

mcm> get DataMemory mycluster\G
*************************** 1. row ***************************
    Name: DataMemory
   Value: 500M
Process1: ndbd
     Id1: 2
Process2:
     Id2:
   Level: Process
 Comment:
*************************** 2. row ***************************
    Name: DataMemory
   Value: 500M
Process1: ndbd
     Id1: 3
Process2:
     Id2:
   Level: Process
 Comment:
2 rows in set (0.22 sec)

By convention (for reasons of readability), we do not normally include the command terminator when showing the syntax for a command in Backus-Naur format or when including a MySQL Cluster Manager command inline in this text. However, if you do not use a statement terminator when you enter the command in the MySQL Cluster Manager client, the client displays a special “waiting...” prompt -> until you supply a terminator, as shown here:

mcm> list sites
  ->
  ->
  ->
  -> ;
Empty set (1.50 sec)

(The is the same as the behavior of the mysql client when you fail to end a statement with a terminator.)

A command option can also in many cases accept (or even require) a set of one or more values. The next example includes such an option, and also demonstrates setting of multiple values in a single option by passing them to the option as a comma-separated list:

mcm> create site --hosts=tonfisk,flundra mysite;
+---------------------------+
| Command result            |
+---------------------------+
| Site created successfully |
+---------------------------+
1 row in set (7.41 sec)

The command just shown creates a site named mysite, consisting of two hosts named tonfisk and flundra. (See Section 5.2.6, “The create site Command”, for more information about this command.) Since we used the long form of the --hosts option, we were required to use an equals sign (=) to mark the end of the option name and the beginning of the values list. You must not insert any space characters before or after the equal sign; doing so causes an error, as shown here:

mcm> create site --hosts =grindval,haj yoursite;
ERROR 7 (00MGR): Option --hosts requires a value
mcm> create site --hosts= grindval,haj yoursite;
ERROR 7 (00MGR): Option --hosts requires a value

The short form of an option does not use an equal sign. Instead, the value-list is separated from the option by a space. Using the -h option, which is the short form of the --hosts option, the previous create site command can be entered and executed like this:

mcm> create site -h tonfisk,flundra mysite;
+---------------------------+
| Command result            |
+---------------------------+
| Site created successfully |
+---------------------------+
1 row in set (7.41 sec)

The short forms of options actually accept multiple spaces between the option name and the values list; however, a single space is sufficient. If you omit the space, or try to use an equal sign, the command fails with an error, as shown here:

mcm> create site -htonfisk,flundra mysite;
ERROR 6 (00MGR): Illegal number of operands
mcm> create site -h=tonfisk,flundra mysite;
ERROR 3 (00MGR): Illegal syntax

Any option value containing one or more whitespace characters, one or more dash characters (-), or both, must be quoted using single quotation marks. Multiple values should be separated by commas only; do not insert spaces before or after any of the commas. Using spaces before or after the commas in a list of values causes the command to fail with an error, as shown here:

mcm> create site --hosts=tonfisk, flundra mysite;
ERROR 6 (00MGR): Illegal number of operands

As you can see from the examples just shown, a MySQL Cluster Manager client command returns a result set, just as an SQL statement does in the standard mysql client. The result set returned by a MySQL Cluster Manager client command consists of one of the following:

A single row that contains a message indicating the outcome of the command. The create site command in the last example returned the result Site created successfully, to inform the user that the command succeeded.

One or more rows listing requested objects or properties. An example of such a command is list processes, as shown here:

mcm> list processes mycluster;
+--------+----------+----------+
| NodeId | Name     | Host     |
+--------+----------+----------+
| 49     | ndb_mgmd | flundra  |
| 1      | ndbd     | tonfisk  |
| 2      | ndbd     | grindval |
| 50     | mysqld   | haj      |
| 51     | mysqld   | torsk    |
| 52     | ndbapi   | *        |
+--------+----------+----------+
6 rows in set (0.03 sec)

In the case of list processes, each row in the result contains the ID and type of a node in the MySQL NDB Cluster named mycluster, together with the name of the host on which the process is running.

An empty result set. This can occur with one of the list commands when there is nothing to report, such as when list sites is used before any sites have been created:
```
mcm> list sites;
Empty set (0.72 sec)
```

Each command must be entered separately; it is not possible to combine multiple commands on a single line.

Options common to client commands. The following three options are common to most MySQL Cluster Manager client commands:

--help (short form: -?): Common to all client commands. Provides help output specific to the given command. See Section 5.1, “Online Help and Information Commands”, for more information about this option.
--force (short form -f): Causes any safety checks to be bypassed when executing the command. For example, delete cluster mycluster normally fails if any of the MySQL NDB Cluster processes in the MySQL NDB Cluster named mycluster are running; however, delete cluster --force mycluster forces the shutdown of mycluster, followed by the deletion of mycluster from MySQL Cluster Manager's inventory.
The --force option is supported for the following MySQL Cluster Manager client commands:

PREV HOME UP NEXT