Skip navigation links
3 MySQL Cluster Manager Client Commands »
Section Navigation      [Toggle]

2.7.2. Migrating a MySQL Cluster to MySQL Cluster Manager

MySQL Cluster Manager is designed primarily for managing MySQL Cluster deployments that are created by it, rather than introducing it into existing MySQL Cluster instances that are already in use. Currently, there is no integrated functionality for importing an existing MySQL Cluster into MySQL Cluster Manager, and it is not currently possible to perform this task without shutting down and restarting the cluster.

This section outlines a suggested procedure for importing an existing MySQL Cluster manually into MySQL Cluster Manager. It is in many ways similar to creating a new cluster in MySQL Cluster Manager, but differs in how initial configuration of the cluster is carried out. The importation procedure includes the following steps:

  • MySQL Cluster Manager agent installation and startup.  Deploy the MySQL Cluster Manager software distribution on the cluster hosts, perform any necessary agent configuration, then start the MySQL Cluster Manager agent, as described in Chapter 2, MySQL Cluster Manager Installation, Configuration, Cluster Setup. MySQL Cluster Manager agent processes must be running on all hosts where cluster processes are running before proceeding any further.

  • MySQL Cluster Manager client session startup.  Start a MySQL Cluster Manager client session; you can connect to a MySQL Cluster Manager agent process running on any of the cluster hosts (see Section 2.6, “Starting the MySQL Cluster Manager Client”).

  • Management site definition.  Define a MySQL Cluster Manager site that includes all hosts in the cluster, using the create site command. See Section 3.2.1, “The create site Command”, for syntax and other details.

  • MySQL Cluster software package registration.  Register a package referencing the location of the MySQL Cluster software on each cluster host using one or more add package commands (see Section 3.3.1, “The add package Command”). Be sure to specify the actual location of the MySQL Cluster software on each host.

  • Cluster definition.  Define a cluster in MySQL Cluster Manager using the create cluster command (see Section 3.4.1, “The create cluster Command”), making sure to reference all cluster processes and hosts when doing so.

    Important

    When creating a cluster, MySQL Cluster Manager automatically assigns sequential node IDs (beginning with 1) in the order specified by the process host list used in the create cluster command. If the node IDs in the existing cluster are not purely sequential (without any gaps between consecutive node IDs, or if the node IDs taken in order do not begin with 1), see Workaround for non-sequential node IDs, before executing create cluster.

  • Cluster configuration.  There is no facility in MySQL Cluster Manager 1.1.6 for importing configuration data from an existing cluster; therefore, this step must be performed manually. Consolidate all configuration information from the existing cluster; this includes parameters set in the cluster's config.ini file (or files), mysqld options set in my.cnf or my.ini files, and any arguments that were passed to MySQL Cluster executables on the command line when invoking them. For most attributes, you need to execute a set statement that is equivalent to a setting in a config.ini or my.cnf file. Suppose that the config.ini file contains an [ndbd default] setting such as this one: 

    DataMemory = 2400G

    In this case, you would need to execute this set command in the MySQL Cluster Manager client: 

    mcm> set DataMemory:ndbd = 2400G;

    More generally, if you have a my.cnf file entry in a [process_type default] section of config.ini where process_type is the name of a MySQL Cluster process (ndb_mgmd, ndbd, mysqld, or api) then you can use the following regular expression to derive an equivalent MySQL Cluster Manager client set statement from it. 

    s/(\w*)\s?=\s?(\w*)/set $1:process_type = $2;/

    In the case of [mysql] and [api] sections of the config.ini file, you also need to determine whether the eqivalent set statement should be applied using mysqld or ndbapi as the process_name.

    Important

    Some attributes such as HostName and Id are read-only (HostName is already defined by create site and create cluster; node IDs are determined by MySQL Cluster Manager and cannot be overridden).

    In addition, you should always keep in mind that MySQL Cluster and MySQL Cluster Manager do not always use the same default values for parameters and their corresponding attributes. This is crucial especially in the case of DataDirectory, since the data nodes must be able to read these following the importation to acess the cluster's data. See Migrating data directories.

    Migrating data directories.  Do not start the new cluster before making sure that you have configured all processes in the new cluster to use the same data directories used by all nodes in the original cluster. If the data nodes of the imported cluster are not configured to read the original data directories, the imported cluster will be unable to access the original cluster's data.

    Keep in mind that the default value used by MySQL Cluster Manager for the DataDirectory attribute (manager_directory/clusters/cluster_name/node_id/data) is not the same as the default set by MySQL Cluster or MySQL Server, as described here:

    For a management node or data node, MySQL Cluster uses the process working directory as the DataDirectory, which means that, if the DataDirectory was not set explicitly to an absolute path in the original cluster's config.ini file, the arguments with which which the cluster executable was invoked and the location it was started from may also affect this value. For a mysqld processes, the default location of the data directory depends on the method that was used to install the mysqld binary (see Installation Layouts, for more information); this value can also be overridden from the command line or in the mysqld's my.cnf file.

    Due to these many factors which can affect the locations of the nodes' data directories, you should always verify the true location of the original data directory for each node in the original cluster by inspection of the file system, then set DataDirectory (using MySQL Cluster Manager) for each node in the new cluster explicitly.

    For a config.ini setting that applies to a single process of type process_type and having node ID node_id, you can use the following regular expression to generate a set statement that applies the same setting to the same cluster process: 

    s/(\w*)\s?=\s?(\w*)/set $1:process_name:node_id = $2;/

  • Cluster shutdown and startup.  Once you have finished migrating the cluster configuration data, you are ready to restart the Cluster under control of MySQL Cluster Manager. This requires a system restart; that is, the cluster must be completely shut down, then restarted.

    Important

    Before proceding with this step, make certain that the configuration you have set up for the cluster in MySQL Cluster Manager is correct. In particular, make sure that the node ID and data directory are the same for each node, in both the original configuration and the new configuration you have just created using MySQL Cluster Manager. Also verify that you have set any attributes that cannot be changed once the cluster has been started for the first time.

    Shutting down the cluster consists of the following two steps:

    1. Issue an ndb_mgm SHUTDOWN command. You can do this either in an ndb_mgm client session, or by invoking ndb_mgm from the system shell, like this: 

      shell> ndb_mgm -e "SHUTDOWN"

      (Here, the quotation marks are optional.) For more information, see Commands in the MySQL Cluster Management Client.

    2. Stop all mysqld processes that were connected to the cluster. To do this, issue the following command on each host running an SQL node: 

      shell> mysqladmin -uroot shutdown

      If the MySQL root user password has been set, you can supply it when invoking the command, like this: 

      shell> mysqladmin -uroot -prootpassword shutdown

      If more than one mysqld process is running on the same host, each process must use a different port. In such cases, you must invoke mysqladmin separately for each mysqld process, specifying the port each time with the --port or -P option, similar to what is shown here: 

      shell> ./mysqladmin -uroot -P3306 shutdown
110919 12:41:26 mysqld_safe mysqld from pid file /usr/local/mysql/data/m1.pid ended
[1]+  Done  ./mysqld_safe --port=3306 --pid-file=/usr/local/mysql/data/m1.pid

shell> ./mysqladmin -uroot -P3307 shutdown
110919 12:41:26 mysqld_safe mysqld from pid file /usr/local/mysql/data/m2.pid ended
[1]+  Done  ./mysqld_safe --port=3307 --pid-file=/usr/local/mysql/data/m2.pid

      See mysqladmin — Client for Administering a MySQL Server, for more information.

    Once all cluster processes have stopped, you can start the cluster using MySQL Cluster Manager. Start the MySQL Cluster Manager agent and a MySQL Cluster Manager client session if these are not already running, then issue a start cluster command in the MySQL Cluster Manager client (substituting the name of the imported cluster for mycluster): 

    mcm> start cluster mycluster;

    Once the cluster has started successfully, the importation process is complete, and you should be able from this point onwards to manage the cluster as if you had actually created it using MySQL Cluster Manager.

Workaround for non-sequential node IDs.  If the node IDs in the existing cluster are not strictly consecutive, beginning with 1, this causes problems when trying to import it into MySQL Cluster Manager because MySQL Cluster Manager's internal representation of the cluster requires them to be. One way to surmount this issue is to insert “dummy” ndbapi entries into the process hosts list used in the create cluster statement. The following example illustrates how this can be done.

Suppose the original cluster has 8 nodes that use the process types, the node IDs, and hosts shown in the following table:

Process type Node ID Host
ndb_mgmd 2 192.168.10.2
ndb_mgmd 4 192.168.10.4
ndbd 5 192.168.10.10
ndbd 6 192.168.10.11
ndbd 7 192.168.10.10
ndbd 8 192.168.10.11
mysqld 10 192.168.10.20
mysqld 12 192.168.10.21

Assuming that a package named mypackage has already been registered, a cluster named mycluster having the preceding distribution of nodes on hosts can be created in the mcm client like this: 

mcm> create cluster -P mypackage -R 
  -> ndb_mgmd@192.168.10.2,ndb_mgmd@192.168.10.4, 
  -> ndbd@192.168.10.10,ndbd@192.168.10.11,  
  -> ndbd@192.168.10.10,ndbd@192.168.10.11, 
  -> mysqld@192.168.10.20,mysqld@192.168.10.21 
  -> mycluster;

However, the node IDs generated by this statement are the numbers 1, 2, 3, ..., 8. In order to preserve the original numbering, we need to account for the numbers 1, 3, 9, and 11. The following version of the command has been modified such that “dummy” ndbapi process entries have been inserted into the list of processes on hosts; the “extra” entries are shown in a contrasting style: 

mcm> create cluster -P mypackage -R 
  -> ndbapi@196.168.0.2,ndb_mgmd@192.168.10.2,
  -> ndbapi@196.168.0.4,ndb_mgmd@192.168.10.4, 
  -> ndbd@192.168.10.10,ndbd@192.168.10.10  
  -> ndbd@192.168.10.11,ndbd@192.168.10.11,
  -> ndbapi@196.168.0.11,mysqld@192.168.10.20,
  -> ndbapi@196.168.0.20,mysqld@192.168.10.21 
  -> mycluster;

Since MySQL Cluster Manager does not expect to execute ndbapi processes itself, the host names used with these “dummy” items are arbitrary; the only requirement for these is that they are names of hosts belonging to the cluster.

Copyright © 2009, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices