Chapter 5 MySQL Cluster Manager Client Commands

Identifiers in client commands

Case-sensitivity rules for client commands

Options common to client commands

The sections in this chapter describe commands used in the MySQL Cluster Manager 8.4.1 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.

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:

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:

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:

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: