Chapter 4 MySQL Cluster Manager Client Commands

Table of Contents

4.1 Online Help and Information Commands
4.2 MySQL Cluster Manager Site and Agent Commands
4.2.1 The add hosts Command
4.2.2 The change log-level Command
4.2.3 The create site Command
4.2.4 The delete site Command
4.2.5 The list sites Command
4.2.6 The list hosts Command
4.2.7 The stop agents Command
4.2.8 The version Command
4.3 MySQL Cluster Manager Package Commands
4.3.1 The add package Command
4.3.2 The delete package Command
4.3.3 The list packages Command
4.4 MySQL Cluster Manager Cluster Commands
4.4.1 The create cluster Command
4.4.2 The delete cluster Command
4.4.3 The list clusters Command
4.4.4 The restart cluster Command
4.4.5 The show status Command
4.4.6 The start cluster Command
4.4.7 The stop cluster Command
4.4.8 The upgrade cluster Command
4.5 MySQL Cluster Manager Configuration Commands
4.5.1 The get Command
4.5.2 The reset Command
4.5.3 The set Command
4.6 MySQL Cluster Manager Process Commands
4.6.1 The add process Command
4.6.2 The change process Command
4.6.3 The list processes Command
4.6.4 The start process Command
4.6.5 The stop process Command
4.7 MySQL Cluster Manager Backup and Restore Commands
4.7.1 The abort backup Command
4.7.2 The backup cluster Command
4.7.3 The list backups Command
4.7.4 The restore cluster Command

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 1.2.4 client for tasks such as defining sites, packages, and MySQL Cluster instances (clusters); configuring a MySQL Cluster; and getting the status of a running MySQL Cluster. These commands are issued to the management agent using the mysql client program included with the MySQL Cluster distribution (for information about the mysql client not specific to using MySQL Cluster Manager, see mysql — The MySQL Command-Line Tool). 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] [...]

For example, consider the following MySQL Cluster Manager command, which starts a MySQL Cluster named mycluster and backgrounds the deletion process so that the client can be used to execute other commands in the meantime, without having to wait on the start cluster command to complete:

start cluster --background mycluster;

In this example, the command contains a delete site instruction. An instruction consists of one or two keywords, such as set, or show status. This instruction is modified by the --background option which follows it; however, this option assigns no values.

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

delete site -B mysite;

The long form of an option must be preceded by a double dash (--), and is case insensitive (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 4.2.3, “The create site Command”.)

Changes in client commands in version 1.2.4.  An additional --verbose option has been added in MySQL Cluster Manager 1.2.4 to the create cluster and add process commands. In both cases, using the option causes the command to return a list of the MySQL 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:

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/7.3 (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/7.3' 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 4.2.3, “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:

  1. --help (short form: -?): Common to all client commands. Provides help output specific to the given command. See Section 4.1, “Online Help and Information Commands”, for more information about this option.

  2. --force (short form -f): Causes any safety checks to be bypassed when excuting the command. For example, delete cluster mycluster normally fails if any of the MySQL Cluster processes in the MySQL 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 all MySQL Cluster Manager 1.2.4 client commands with the exception of add hosts.

  3. --background (short form -B): Rather than waiting for the command to complete, the MySQL Cluster Manager client immediately returns the command prompt, allowing you to perform addition tasks in the client while that command continues to execute in the background. This can be useful when executing commands that might require some time to complete (such as starting a cluster with a great many nodes).

    This option is supported by all client commands except for create site, delete site, add hosts, add package, and delete package.