Documentation Home
MySQL Cluster Manager 8.0 User Manual
Related Documentation Download this Manual
PDF (US Ltr) - 1.3Mb
PDF (A4) - 1.3Mb


5.4.1 Thecreate cluster Command

create cluster {--package=|-P }package_name    {--processhosts=|-R }process_host_listcluster_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 (seeSection 5.4.7, “Thestart 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 alsoSection 4.5, “Importing MySQL NDB Clusters into MySQL Cluster Manager”.

create cluster requires the following arguments:

  • Apackage_name, supplied as the value of the--package option (short form:-P). This must be the name of a package previously registered usingadd 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 theprocess_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 arendb_mgmd,ndbd, andmysqld. You can also usendbmtd 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 usendbapi 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 andndbapi 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.)

    Amysqld process orndbapi 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 theprocess_host_list are listed according to the process type, in the following order:

    1. Management node processes (ndb_mgmd)

    2. Data node processes (ndbd,ndbmtd)

    3. SQL node processes (mysqld)

    4. Custom NDB API applications (ndbapi)

      For information about writing your own NDB API applications, seeThe NDB API, in theMySQL NDB Cluster API Developer Guide.

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

    create cluster causes cluster node IDs to be assigned consecutively, in the order that the nodes are specified in theprocess_host_list, with node IDs for data node processes starting with 1, and node IDs for processes other than data node processes starting with 145. 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 increate cluster is defined.

    For processes of typesmysqld andndbapi, the hostname is required, but not enforced in the running cluster. In other words, an[api] section is created in the clusterconfig.ini file, but noHostName parameter is specified; thus, themysqld orndbapi can connect from any host. (Currently, there is no way using MySQL Cluster Manager to specify that amysqld orndbapi 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 asdelete cluster,start cluster, andstop cluster. Like other object names used with MySQL Cluster Manager, thecluster_name must be valid according to the rules given elsewhere in this document for identifiers (seeChapter 5,MySQL Cluster Manager Client Commands).

An additional--verbose option for this command causescreate 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 asimport in the output ofshow 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 theimport status causes any of the commandsstart cluster,restart cluster,start process, andstop process to fail if they are executed before animport cluster command has been executed against this cluster. It is also not possible to executeupgrade cluster on a cluster having processes withimport 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, seeSection 4.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 namedmycluster:

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 hostflundra; two data nodes—one on each of the hoststonfisk andgrindval; and one SQL node, also on hostflundra.

Using the--verbose option causes the command to print output similar to that produced by thelist 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 themysqld 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 thendbapi process is running.

Configuration changes to the newly-created cluster can be made using theset command prior to starting the cluster. This is often preferable to doing after the cluster has been started, sinceset 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 onemysqld 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 eachmysqld process in the cluster.