4.4.1 The create cluster Command

create cluster {--package=|-P }package_name
    {--processhosts=|-R }process_host_list cluster_name
    [(--import|-m) cluster_name] [--verbose | -v]

process_host_list:
    process_name[:node_id]@host[,process_name@host[,...]]

process_name:
    {ndb_mgmd|ndbd|ndbmtd|mysqld|ndbapi}

This command creates a cluster to be managed by the MySQL Cluster Manager. However, it does not start the cluster (see Section 4.4.7, “The start cluster Command”).

This command can also be used to create a cluster earmarked specifically as a target for importing another cluster that is not already under MySQL Cluster Manager control, as described later in this section, by employing the --import option. See also Section 3.5, “Importing MySQL NDB Clusters into MySQL Cluster Manager”.

create cluster requires the following arguments:

• A package_name, supplied as the value of the --package option (short form: -P). This must be the name of a package previously registered using add package.

• A list (process_host_list) of MySQL NDB Cluster processes, the hosts on which they are to run, and—optionally—their node IDs, supplied as the value of the --processhosts option (short form: -R), with list items separated by commas. As with other lists passed as option values in MySQL Cluster Manager commands, you must not use spaces before or after the commas.

  Each item in the process_host_list consists of the name of a MySQL NDB Cluster process—possibly suffixed with a colon (:) character followed by the process node ID—joined with the name of the host on which it is located using an amphora (@) sign (also sometimes known as the “at” sign). Permitted values for processes are ndb_mgmd, ndbd, and mysqld. When the cluster employs MySQL NDB Cluster 7.0 or later, you can also use ndbmtd as process name; in other words, a valid process name is the name of a MySQL NDB Cluster process daemon binary. If node IDs are specified, they must be within the allowed range for the type of node defined.

  To support running your own NDB API applications with a cluster under MySQL Cluster Manager, it is also possible to use ndbapi as a process type. Such applications can be connected to a managed cluster. Currently, MySQL Cluster Manager recognises only that an NDB API application is connected to the cluster; the NDB API application itself must be started, stopped, and configured manually.

  It is also possible to specify one or more “free” mysqld and ndbapi processes without any hosts. To do this, simply use the wildcard * (asterisk character) in place of the hostname or IP address, as shown below:

  • “Free” mysqld process: mysqld@*

  • “Free” ndbapi process: ndbapi@*

  It is also possible to specify a node ID for a “free” process. (If this is not specified, MySQL Cluster Manager assigns a suitable node ID automatically.)

  A mysqld process or ndbapi process that is specified without a host in this fashion is permitted to connect to the cluster from any host that can access the cluster over the network. Otherwise, the process may connect to the cluster only from the specified host.

  By convention, items in the process_host_list are listed according to the process type, in the following order:

  1. Management node processes (ndb_mgmd)

  2. Data node processes (MySQL NDB Cluster 6.3: ndbd; MySQL NDB Cluster 7.0 and later: ndbd, ndbmtd)

  3. SQL node processes (mysqld)

  4. Custom NDB API applications (ndbapi)

     For information about writing your own NDB API applications, see The NDB API, in the MySQL NDB Cluster API Developer Guide.

  While the order in which the items are listed does not affect whether the create cluster command succeeds, we suggest that you follow this convention for readability, as well as compatibility with other MySQL NDB Cluster management tools such as ndb_mgm.

  create cluster causes cluster node IDs to be assigned consecutively, in the order that the nodes are specified in the process_host_list, with node IDs for data node processes starting with 1, and node IDs for processes other than data node processes starting with 49. For MySQL Cluster Manager 1.3.3 and earlier, trying to manually assign node IDs less than 49 for ndb_mgmd, mysqld, or ndbapi fails with an error; the restriction, however, has been totally lifted for MySQL Cluster Manager 1.3.4 and later. Nevertheless, you are still recommended to follow the best practice of reserving node ID 1 to 48 for data nodes.

  Note

  NDB 8.0 supports up to 144 data nodes (for release 8.0.18 and later). Therefore, create cluster assigns node IDs for data node processes starting with 1, and node IDs for processes other than data node processes starting with 145. When manually assigning node IDs for an NDB 8.0 cluster, you are recommended to follow the best practice of reserving node ID 1 to 144 for data nodes.

  Each host referenced in the list must be part of the site for which the package used in create cluster is defined.

  For processes of types mysqld and ndbapi, the hostname is required, but not enforced in the running cluster. In other words, an [api] section is created in the cluster config.ini file, but no HostName parameter is specified; thus, the mysqld or ndbapi can connect from any host. (Currently, there is no way using MySQL Cluster Manager to specify that a mysqld or ndbapi process is restricted to connecting from a single host.)

• A name for the cluster. Once the cluster has been created, this name is used to refer to it in other cluster management commands such as delete cluster, start cluster, and stop cluster. Like other object names used with MySQL Cluster Manager, the cluster_name must be valid according to the rules given elsewhere in this document for identifiers (see Chapter 4, MySQL Cluster Manager Client Commands).

An additional --verbose option for this command causes create cluster to output extra information as it is executed, as shown later in this section.

The --import option flags the cluster as being created as a target for importing a cluster created outside MySQL Cluster Manager. This option causes the cluster's status to appear as import in the output of show status, as shown here:

mcm> show status --process newcluster;
+--------+----------+-------+--------+-----------+--------------+
| NodeId | Process  | Host  | Status | Nodegroup | Package      |
+--------+----------+-------+--------+-----------+--------------+
| 1      | ndb_mgmd | alpha | import |           | newpackage   |
| 5      | ndbd     | beta  | import | n/a       | newpackage   |
| 6      | ndbd     | gamma | import | n/a       | newpackage   |
| 10     | mysqld   | delta | import |           | newpackage   |
| 11     | ndbapi   | *     | import |           |              |
+--------+----------+-------+--------+-----------+--------------+
6 rows in set (0.04 sec)

Having the import status causes any of the commands start cluster, restart cluster, start process, and stop process to fail if they are executed before an import cluster command has been executed against this cluster. It is also not possible to execute upgrade cluster on a cluster having processes with import status. Other operations on this cluster continue to be performed normally.

Caution

While it is possible to import into a cluster that was created without this option, it is not advisable, since the cluster is not protected against accidentally performing any of the operations listed previously, which may result in confusing or misleading errors, and possibly other problems. For this reason, it is strongly recommended that you always use the --import option for creating the cluster in such cases.

For more information about importing clusters into MySQL Cluster Manager, including examples, see Section 3.5, “Importing MySQL NDB Clusters into MySQL Cluster Manager”.

Example

Consider the following command issued in the MySQL Cluster Manager client, which creates a cluster named mycluster:

mcm> create cluster --package=mypackage
  -> --processhosts=ndb_mgmd@flundra,ndbd@tonfisk,ndbd@grindval,mysqld@flundra
  -> mycluster;
+------------------------------+
| Command result               |
+------------------------------+
| Cluster created successfully |
+------------------------------+
1 row in set (7.71 sec)

As defined by the command just shown, mycluster consists of four nodes: a management node on host flundra; two data nodes—one on each of the hosts tonfisk and grindval; and one SQL node, also on host flundra.

Using the --verbose option causes the command to print output similar to that produced by the list processes command, as shown here:

mcm> create cluster --verbose --package=mypackage
  -> --processhosts=ndb_mgmd@flundra,ndbd@tonfisk,ndbd@grindval,mysqld@flundra
  -> mycluster;
+--------+----------+----------+
| NodeId | Name     | Host     |
+--------+----------+----------+
| 49     | ndb_mgmd | flundra  |
| 1      | ndbd     | tonfisk  |
| 2      | ndbd     | grindval |
| 50     | mysqld   | flundra  |
+--------+----------+----------+
4 rows in set (0.32 sec)

You can also create this cluster in such a way that the mysqld process is permitted to connect to the cluster from any host able to reach the other cluster hosts over the network as shown here:

mcm> create cluster --package=mypackage
  -> --processhosts=ndb_mgmd@flundra,ndbd@tonfisk,ndbd@grindval,mysqld@*
  -> mycluster;
+------------------------------+
| Command result               |
+------------------------------+
| Cluster created successfully |
+------------------------------+
1 row in set (7.71 sec)

Note

In the case of a “free” ndbapi process, it is not necessary to have the MySQL Cluster Manager software installed on the host where the ndbapi process is running.

Configuration changes to the newly-created cluster can be made using the set command prior to starting the cluster. This is often preferable to doing after the cluster has been started, since set commands used to make configuration changes in a running cluster can require a rolling restart, and rolling restarts of clusters having many nodes or large quantities of data (or both) may take a great deal of time to complete.

Note

When creating a cluster having more than one mysqld process on the same host machine, MySQL Cluster Manager assigns the MySQL default port (3306) to each of them. Therefore, you must assign a unique port for each mysqld process in the cluster.