Author: paul
Date: 2006-02-01 00:38:29 +0100 (Wed, 01 Feb 2006)
New Revision: 1158
Log:
r7008@frost: paul | 2006-01-31 17:38:24 -0600
General revisions.
Modified:
trunk/
trunk/refman-4.1/ndbcluster.xml
trunk/refman-5.0/ndbcluster.xml
trunk/refman-5.1/ndbcluster.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:7004
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2749
+ b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:7008
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2749
Modified: trunk/refman-4.1/ndbcluster.xml
===================================================================
--- trunk/refman-4.1/ndbcluster.xml 2006-01-31 23:37:45 UTC (rev 1157)
+++ trunk/refman-4.1/ndbcluster.xml 2006-01-31 23:38:29 UTC (rev 1158)
@@ -254,9 +254,9 @@
Cluster, a client node is a traditional MySQL server that uses
the <literal>NDB Cluster</literal> storage engine. An SQL node
is typically started with the command <command>mysqld
- --ndbcluster</command> or simply by using
- <command>mysqld</command> with <literal>ndbcluster</literal>
- added to <filename>my.cnf</filename>.
+ --ndbcluster</command> or by using <command>mysqld</command>
+ with the <literal>ndbcluster</literal> option added to
+ <filename>my.cnf</filename>.
</para>
</listitem>
@@ -625,9 +625,9 @@
<emphasis role="bold">Note</emphasis>: In the interest of
simplicity (and reliability), this How-To uses only numeric IP
addresses. However, if DNS resolution is available on your
- network, then it is possible to use hostnames in lieu of IP
- addresses in configuring Cluster. Alternatively, you can also
- use the <filename>/etc/hosts</filename> file or your operating
+ network, it is possible to use hostnames in lieu of IP
+ addresses in configuring Cluster. Alternatively, you can use
+ the <filename>/etc/hosts</filename> file or your operating
system's equivalent for providing a means to do host lookup if
such is available.
</para>
@@ -1417,8 +1417,8 @@
<para>
This will need to be done for the definition of each table
that is to be part of the clustered database. The easiest
- way to accomplish this is simply to do a search-and-replace
- on the <filename>world.sql</filename> file and replace all
+ way to accomplish this is to do a search-and-replace on the
+ <filename>world.sql</filename> file and replace all
instances of <literal>TYPE=MyISAM</literal> with
<literal>ENGINE=NDBCLUSTER</literal>. If you do not want to
modify the file, you can also use <literal>ALTER
@@ -1449,7 +1449,7 @@
<para>
To create a copy of the <literal>world</literal> database on
the SQL node, save the file to
- <filename>/usr/local/mysql/data</filename>, then run
+ <filename>/usr/local/mysql/data</filename>, and then run
</para>
<programlisting>
@@ -1577,7 +1577,7 @@
<body>
<?php
# connect to SQL node:
- $link = new mysqli('192.168.0.20', 'root', '', 'world');
+ $link = new mysqli('192.168.0.20', 'root', '<replaceable>root_password</replaceable>', 'world');
# parameters for mysqli constructor are:
# host, user, password, database
@@ -1659,7 +1659,7 @@
<title>&title-multi-shutdown-restart;</title>
<para>
- To shut down the cluster simply enter the following in a shell
+ To shut down the cluster, enter the following command in a shell
on the machine hosting the MGM node:
</para>
@@ -1673,17 +1673,17 @@
</remark>
<para>
- This will cause the <command>ndb_mgm</command>,
- <command>ndb_mgmd</command>, and any <command>ndbd</command>
- processes to terminate gracefully. Any SQL nodes can be
- terminated using <command>mysqladmin shutdown</command> and
- other means. Note that the <option>-e</option> option here is
- used to pass a command to the <command>ndb_mgm</command> client
- from the shell. See <xref linkend="command-line-options"/>.
+ The <option>-e</option> option here is used to pass a command to
+ the <command>ndb_mgm</command> client from the shell. See
+ <xref linkend="command-line-options"/>. The command causes the
+ <command>ndb_mgm</command>, <command>ndb_mgmd</command>, and any
+ <command>ndbd</command> processes to terminate gracefully. Any
+ SQL nodes can be terminated using <command>mysqladmin
+ shutdown</command> and other means.
</para>
<para>
- To restart the cluster, simply run these commands:
+ To restart the cluster, run these commands:
</para>
<itemizedlist>
@@ -1691,7 +1691,7 @@
<listitem>
<para>
On the management host (<literal>192.168.0.10</literal> in
- our setup):
+ our example setup):
</para>
<programlisting>
@@ -1719,7 +1719,7 @@
<listitem>
<para>
- And on the SQL host (<literal>192.168.0.20</literal>):
+ On the SQL host (<literal>192.168.0.20</literal>):
</para>
<programlisting>
@@ -1729,6 +1729,11 @@
</itemizedlist>
+ <remark role="todo">
+ [pd] Hmm ... why are these three paragraphs _here_? (But where
+ would be more appropriate instead?)
+ </remark>
+
<para>
For information on making Cluster backups, see
<xref linkend="mysql-cluster-backup-using-management-server"/>.
@@ -1762,20 +1767,19 @@
</para>
<para>
- In order to avoid unnecessary allocation of resources, the server
- is configured by default with the <literal>NDB</literal> storage
- engine disabled. To enable <literal>NDB</literal>, you will need
- to modify the server's <filename>my.cnf</filename> configuration
- file, or start the server with the <option>--ndbcluster</option>
- option.
+ To avoid unnecessary allocation of resources, the server is
+ configured by default with the <literal>NDB</literal> storage
+ engine disabled. To enable <literal>NDB</literal>, you must modify
+ the server's <filename>my.cnf</filename> configuration file, or
+ start the server with the <option>--ndbcluster</option> option.
</para>
<para>
- The MySQL server is a part of the cluster, so it will also need to
- know how to access an MGM node to obtain the cluster configuration
+ The MySQL server is a part of the cluster, so it also must know
+ how to access an MGM node to obtain the cluster configuration
data. The default behavior is to look for the MGM node on
<literal>localhost</literal>. However, should you need to specify
- its location elsewhere, this can be done in
+ that its location is elsewhere, this can be done in
<filename>my.cnf</filename> or on the MySQL server command line.
Before the <literal>NDB</literal> storage engine can be used, at
least one MGM node must be operational, as well as any desired
@@ -1799,12 +1803,12 @@
<option>--with-ndbcluster</option> option when running
<command>configure</command>. You can also use the
<command>BUILD/compile-pentium-max</command> build script. Note
- that this script includes OpenSSL, so you must have or obtain
- OpenSSL to build successfully; otherwise you will need to modify
+ that this script includes OpenSSL, so you must either have or
+ obtain OpenSSL to build successfully, or else modify
<command>compile-pentium-max</command> to exclude this
requirement. Of course, you can also just follow the standard
- instructions for compiling your own binaries, then perform the
- usual tests and installation procedure. See
+ instructions for compiling your own binaries, and then perform
+ the usual tests and installation procedure. See
<xref linkend="installing-source-tree"/>.
</para>
@@ -1838,11 +1842,11 @@
<title>&title-mysql-cluster-quick;</title>
<para>
- In order to familiarize you with the basics, we will describe
- the simplest possible configuration for a functional MySQL
- Cluster. After this, you should be able to design your desired
- setup from the information provided in the other relevant
- sections of this chapter.
+ To familiarize you with the basics, we will describe the
+ simplest possible configuration for a functional MySQL Cluster.
+ After this, you should be able to design your desired setup from
+ the information provided in the other relevant sections of this
+ chapter.
</para>
<para>
@@ -1857,9 +1861,10 @@
<para>
In this directory, create a file named
- <filename>config.ini</filename> with the following information,
- substituting appropriate values for <literal>HostName</literal>
- and <literal>DataDir</literal> as necessary for your system.
+ <filename>config.ini</filename> that contains the following
+ information. Substitute appropriate values for
+ <literal>HostName</literal> and <literal>DataDir</literal> as
+ necessary for your system.
</para>
<programlisting>
@@ -1895,7 +1900,11 @@
</programlisting>
<para>
- You can now start the management server as follows:
+ You can now start the <command>ndb_mgmd</command> management
+ server. By default, it atttempts to read the
+ <filename>config.ini</filename> file in its current working
+ directory, so change location into the directory where the file
+ is located and then invoke <command>ndb_mgmd</command>:
</para>
<programlisting>
@@ -1916,7 +1925,7 @@
<para>
For subsequent <command>ndbd</command> starts, you will
- generally <emphasis role="bold">not</emphasis> want to use the
+ generally want to <emphasis>omit</emphasis> the
<option>--initial</option> option:
</para>
@@ -1925,11 +1934,14 @@
</programlisting>
<para>
- The reason for this is that the <option>--initial</option>
- option will delete all existing data and log files (as well as
- all table metadata) for this data node and create new ones. One
- exception to this rule is when restarting the cluster and
- restoring from backup after adding new data nodes.
+ The reason for omitting <option>--initial</option> on subsequent
+ restarts is that this option causes <command>ndbd</command> to
+ delete and re-create all existing data and log files (as well as
+ all table metadata) for this data node. One exception to this
+ rule about not using <option>--initial</option> except for the
+ first <command>ndbd</command> invocation is that you use it when
+ restarting the cluster and restoring from backup after adding
+ new data nodes.
</para>
<remark role="todo">
@@ -1937,7 +1949,7 @@
</remark>
<para>
- By default, <command>ndbd</command> will look for the management
+ By default, <command>ndbd</command> looks for the management
server at <literal>localhost</literal> on port 1186. (Prior to
MySQL 4.1.8, the default port was 2200.)
</para>
@@ -1951,7 +1963,7 @@
</para>
<para>
- Finally, go to the MySQL data directory (usually
+ Finally, change location to the MySQL data directory (usually
<filename>/var/lib/mysql</filename> or
<filename>/usr/local/mysql/data</filename>), and make sure that
the <filename>my.cnf</filename> file contains the option
@@ -1980,7 +1992,8 @@
<para>
If all has gone well so far, you now can start using the
- cluster:
+ cluster. Connect to the server and verify that the
+ <literal>NDBCLUSTER</literal> storage engine is enabled:
</para>
<programlisting>
@@ -1991,7 +2004,6 @@
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> <userinput>SHOW ENGINES\G</userinput>
-
...
*************************** 12. row ***************************
Engine: NDBCLUSTER
@@ -2005,18 +2017,17 @@
</programlisting>
<para>
- (Note that the row numbers shown in the preceding example output
- may be different from those shown on your system, depending upon
- the MySQL version being used and how it is configured.)
+ The row numbers shown in the preceding example output may be
+ different from those shown on your system, depending upon how
+ your server is configured.
</para>
+ <para>
+ Try to create an <literal>NDBCLUSTER</literal> table:
+ </para>
+
<programlisting>
shell> <userinput>mysql</userinput>
-Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 1 to server version: ¤t-version;-Max
-
-Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
-
mysql> <userinput>USE test;</userinput>
Database changed
@@ -2034,7 +2045,7 @@
<para>
To check that your nodes were set up properly, start the
- management client as shown:
+ management client:
</para>
<programlisting>
@@ -2042,9 +2053,8 @@
</programlisting>
<para>
- You can then use the <command>SHOW</command> statement from
- within the management client to obtain a report on the cluster's
- status:
+ Use the <command>SHOW</command> command from within the
+ management client to obtain a report on the cluster's status:
</para>
<programlisting>
@@ -2095,7 +2105,7 @@
<para>
<filename>config.ini</filename>: This file is read only by
the MySQL Cluster management server, which then distributes
- the information contained in this file to all processes
+ the information contained therein to all processes
participating in the cluster.
<filename>config.ini</filename> contains a description of
each node involved in the cluster. This includes
@@ -2112,10 +2122,9 @@
maintain backward compatibility, there may be times when
introduce an incompatible change. In such cases we will try to
let Cluster users know in advance if a change is not backward
- compatible. If you find such a change which we have not
- documented, please use our
- <ulink url="http://bugs.mysql.com/">Bugs Database</ulink> to
- report it.
+ compatible. If you find such a change and we have not documented
+ it, please report it in the MySQL bugs database using the
+ instructions given in <xref linkend="bug-reports"/>.
</para>
<section id="mysql-cluster-config-example">
@@ -2123,12 +2132,12 @@
<title>&title-mysql-cluster-config-example;</title>
<para>
- In order to support MySQL Cluster, you will need to update
+ To support MySQL Cluster, you will need to update
<filename>my.cnf</filename> as shown in the following example.
Note that the options shown here should not be confused with
- those occurring in <filename>config.ini</filename> files. You
- may also specify these parameters when invoking the
- executables from the command line.
+ those that are used in <filename>config.ini</filename> files.
+ You may also specify these parameters on the command line when
+ invoking the executables.
</para>
<para>
@@ -2186,8 +2195,8 @@
<para>
Starting with MySQL 4.1.8, you may also use a separate
<literal>[mysql_cluster]</literal> section in the cluster
- <filename>my.cnf</filename> for settings to be read by and
- affecting all executables:
+ <filename>my.cnf</filename> for settings to be read and used
+ by all executables:
</para>
<programlisting>
@@ -2201,44 +2210,48 @@
</remark>
<para>
- Currently, the configuration file is in INI format, and is
- named <filename>config.ini</filename> by default. It is read
- by <command>ndb_mgmd</command> at startup and can be placed
+ The configuration file is named
+ <filename>config.ini</filename> by default. It is read by
+ <command>ndb_mgmd</command> at startup and can be placed
anywhere. Its location and name are specified by using
- <option>--config-file=[<replaceable><path></replaceable>]<replaceable><filename></replaceable></option>
- on the command line with <command>ndb_mgmd</command>. If the
+ <option>--config-file=<replaceable>path_name</replaceable></option>
+ on the <command>ndb_mgmd</command> command line. If the
configuration file is not specified,
- <command>ndb_mgmd</command> by default tries to read a
- <filename>config.ini</filename> file located in the current
+ <command>ndb_mgmd</command> by default tries to read a file
+ named <filename>config.ini</filename> located in the current
working directory.
</para>
<para>
+ Currently, the configuration file is in INI format, which
+ consists of sections preceded by section headings (surrounded
+ by square brackets), followed by the appropriate parameter
+ names and values. One deviation from the standard INI format
+ is that the parameter name and value can be separated by a
+ colon (‘<literal>:</literal>’) as well as the
+ equals sign (‘<literal>=</literal>’). Another
+ deviation is that sections are not uniquely identified by
+ section name. Instead, unique sections (such as two different
+ nodes of the same type) are identified by a unique ID
+ specified as a parameter within the section.
+ </para>
+
+ <para>
Default values are defined for most parameters, and can also
be specified in <filename>config.ini</filename>. To create a
default value section, simply add the word
<literal>DEFAULT</literal> to the section name. For example,
- data nodes are configured using <literal>[NDBD]</literal>
- sections. If all data nodes use the same data memory size, and
- this is not the same as the default size, create an
- <literal>[NDBD DEFAULT]</literal> section containing a
- <literal>DataMemory</literal> line to specify the default data
- memory size for all data nodes.
+ an <literal>[NDBD]</literal> section contains parameters that
+ apply to a particular data node, whereas an <literal>[NDBD
+ DEFAULT]</literal> section contains parameters that apply to
+ all data nodes. Suppose that all data nodes should use the
+ same data memory size. To configure them all, create an
+ <literal>[NDBD DEFAULT]</literal> section that contains a
+ <literal>DataMemory</literal> line to specify the data memory
+ size.
</para>
<para>
- The INI format consists of sections preceded by section
- headings (surrounded by square brackets), followed by the
- appropriate parameter names and values. One deviation from the
- standard format is that the parameter name and value can be
- separated by a colon (‘<literal>:</literal>’) as
- well as the equals sign (‘<literal>=</literal>’);
- another is that sections are not uniquely identified by name.
- Instead, unique entries (such as two different nodes of the
- same type) are identified by a unique ID.
- </para>
-
- <para>
At a minimum, the configuration file must define the computers
and nodes involved in the cluster and on which computers these
nodes are located. An example of a simple configuration file
@@ -2248,10 +2261,10 @@
<programlisting>
# file "config.ini" - 2 data nodes and 2 SQL nodes
-# This file is placed in the startup directory of ndb_mgmd (the management
-# server)
-# The first MySQL Server can be started from any host. The second can be started
-# only on the host mysqld_5.mysql.com
+# This file is placed in the startup directory of ndb_mgmd (the
+# management server)
+# The first MySQL Server can be started from any host. The second
+# can be started only on the host mysqld_5.mysql.com
[NDBD DEFAULT]
NoOfReplicas= 2
@@ -2845,8 +2858,8 @@
specifying <literal>ExecuteOnComputer</literal>. It
defines the hostname of the computer the storage node on
which is to reside. Either this parameter or
- <literal>ExecuteOnComputer</literal> is required in order
- to specify a hostname other than
+ <literal>ExecuteOnComputer</literal> is required to
+ specify a hostname other than
<literal>localhost</literal>.
</para>
</listitem>
@@ -2943,8 +2956,8 @@
includes <filename>/var/lib/mysql-cluster</filename>,
under which a directory for the node's filesystem is
created. This subdirectory contains the node ID. For
- example, if the node ID is 2, then this subdirectory is
- named <filename>ndb_2_fs</filename>.
+ example, if the node ID is 2, this subdirectory is named
+ <filename>ndb_2_fs</filename>.
</para>
</listitem>
@@ -3177,9 +3190,9 @@
database size is the sum of all data memory and all index
memory for each node group. Each node group is used to
store replicated information, so if there are four nodes
- with 2 replicas, then there will be two node groups. Thus,
- the total data memory available is
- 2*<literal>DataMemory</literal> for each data node.
+ with two replicas, there will be two node groups. Thus,
+ the total data memory available is 2 ×
+ <literal>DataMemory</literal> for each data node.
</para>
<para>
@@ -3201,9 +3214,9 @@
memory space. Increasing these values should be
acceptable, but it is recommended that such upgrades are
performed in the same manner as a software upgrade,
- beginning with an update of the configuration file, then
- restarting the management server followed by restarting
- each data node in turn.
+ beginning with an update of the configuration file, and
+ then restarting the management server followed by
+ restarting each data node in turn.
</para>
<para>
@@ -3362,11 +3375,11 @@
involved in the transaction. However, the operation
records of the are spread over all 8 nodes. Thus, if it is
necessary to configure the system for one very large
- transaction, then it is a good idea to configure the two
- parts separately.
- <literal>MaxNoOfConcurrentOperations</literal> will always
- be used to calculate the number of operation records in
- the transaction coordinator portion of the node.
+ transaction, it is a good idea to configure the two parts
+ separately. <literal>MaxNoOfConcurrentOperations</literal>
+ will always be used to calculate the number of operation
+ records in the transaction coordinator portion of the
+ node.
</para>
<para>
@@ -3382,13 +3395,13 @@
</para>
<para>
- By default, this parameter is calculated as 1.1 *
+ By default, this parameter is calculated as 1.1 ×
<literal>MaxNoOfConcurrentOperations</literal> which fits
systems with many simultaneous transactions, none of them
being very large. If there is a need to handle one very
- large transaction at a time and there are many nodes, then
- it is a good idea to override the default value by
- explicitly specifying this parameter.
+ large transaction at a time and there are many nodes, it
+ is a good idea to override the default value by explicitly
+ specifying this parameter.
</para>
</listitem>
@@ -3680,7 +3693,7 @@
<para>
If the checkpointing is slow and there are so many writes
to the database that the log files are full and the log
- tail cannot be cut without jeopardizing recovery, then all
+ tail cannot be cut without jeopardizing recovery, all
updating transactions will be aborted with internal error
code 410, or <literal>Out of log file space
temporarily</literal>. This condition will prevail until a
@@ -3768,16 +3781,16 @@
<para>
When setting <literal>MaxNoOfAttributes</literal>, it is
important to prepare in advance for any <literal>ALTER
- TABLE</literal> statements that you might wish to perform
+ TABLE</literal> statements that you might want to perform
in future. This is due to the fact, during the execution
of <literal>ALTER TABLE</literal> on a Cluster table, 3
times the number of attributes as in the original table
are used. For example, if a table requires 100 attributes,
- and you wish to be able to alter it later, then you need
- to set the value of <literal>MaxNoOfAttributes</literal>
- to 300. A good rule of thumb is that, if you can create
- all desired tables without any problems, then add 2 times
- the number of attributes in the largest table to
+ and you want to be able to alter it later, you need to set
+ the value of <literal>MaxNoOfAttributes</literal> to 300.
+ A good rule of thumb is that, if you can create all
+ desired tables without any problems, add 2 times the
+ number of attributes in the largest table to
<literal>MaxNoOfAttributes</literal> to be sure. You
should also verify that this number is sufficient by
trying an actual <literal>ALTER TABLE</literal> after
@@ -4089,7 +4102,7 @@
<para>
If a data node has not completed its startup sequence
- within the time specified by this parameter, then the node
+ within the time specified by this parameter, the node
startup will fail. Setting this parameter to
<literal>0</literal> means that no data node timeout is
applied.
@@ -4238,8 +4251,8 @@
Timeout handling is performed by checking a timer on each
transaction once for every interval specified by this
parameter. Thus, if this parameter is set to 1000
- milliseconds, then every transaction will be checked for
- timing out once per second.
+ milliseconds, every transaction will be checked for timing
+ out once per second.
</para>
<para>
@@ -4441,7 +4454,7 @@
<para>
This parameter specifies the time that the data node will
wait for a response from the arbitrator to an arbitration
- message. If this is exceeded, then it is assumed that the
+ message. If this is exceeded, it is assumed that the
network has split.
</para>
@@ -4467,10 +4480,10 @@
<para>
These buffers are used as front ends to the file system when
writing log records to disk. If the node is running in
- diskless mode, then these parameters can be set to their
- minimum values without penalty due to the fact that disk
- writes are <quote>faked</quote> by the <literal>NDB</literal>
- storage engine's filesystem abstraction layer.
+ diskless mode, these parameters can be set to their minimum
+ values without penalty due to the fact that disk writes are
+ <quote>faked</quote> by the <literal>NDB</literal> storage
+ engine's filesystem abstraction layer.
</para>
<itemizedlist>
@@ -4484,7 +4497,7 @@
This buffer is used during local checkpoints. The
<literal>NDB</literal> storage engine uses a recovery
scheme based on checkpoint consistency in conjunction with
- an operational REDO log. In order to produce a consistent
+ an operational REDO log. To produce a consistent
checkpoint without blocking the entire system for writes,
UNDO logging is done while performing the local
checkpoint. UNDO logging is activated on a single table
@@ -4548,7 +4561,7 @@
<para>
It is rarely necessary to increase the size of this
- buffer. If there is such a need, then it is a good idea to
+ buffer. If there is such a need, it is a good idea to
check whether the disks can actually handle the load
caused by database update activity. A lack of sufficient
disk space cannot be overcome by increasing the size of
@@ -4863,7 +4876,7 @@
<filename>config.ini</filename> file define the behavior of
the MySQL servers (SQL nodes) used to access cluster data.
None of the parameters shown is required. If no computer or
- host name is provided, then any host can use this SQL node.
+ host name is provided, any host can use this SQL node.
</para>
<itemizedlist>
@@ -4979,10 +4992,10 @@
<para>
The batch size is the size of each batch sent from each
- data node. Most scans are performed in parallel in order
- to protect the MySQL Server from receiving too much data
- from many nodes in parallel; this parameter sets a limit
- to the total batch size over all nodes.
+ data node. Most scans are performed in parallel to protect
+ the MySQL Server from receiving too much data from many
+ nodes in parallel; this parameter sets a limit to the
+ total batch size over all nodes.
</para>
<para>
@@ -5064,11 +5077,10 @@
</para>
<para>
- In order to be able to retrace a distributed message
- diagram it is necessary to identify each message. When
- this parameter is set to <literal>Y</literal>, message IDs
- are transported over the network. This feature is disabled
- by default.
+ To be able to retrace a distributed message diagram it is
+ necessary to identify each message. When this parameter is
+ set to <literal>Y</literal>, message IDs are transported
+ over the network. This feature is disabled by default.
</para>
</listitem>
@@ -5263,8 +5275,8 @@
</para>
<para>
- In order to retrace the path of a distributed message, it
- is necessary to provide each message with a unique
+ To retrace the path of a distributed message, it is
+ necessary to provide each message with a unique
identifier. Setting this parameter to <literal>Y</literal>
causes these message IDs to be transported over the
network as well. This feature is disabled by default.
@@ -5426,10 +5438,10 @@
</para>
<para>
- In order to trace a distributed message it is necessary to
- identify each message uniquely. When this parameter is set
- to <literal>Y</literal>, message IDs are transported over
- the network. This feature is disabled by default.
+ To trace a distributed message it is necessary to identify
+ each message uniquely. When this parameter is set to
+ <literal>Y</literal>, message IDs are transported over the
+ network. This feature is disabled by default.
</para>
</listitem>
@@ -5533,33 +5545,33 @@
in this row (or if there is no such row displayed in the
output), you are not running an <literal>NDB</literal>-enabled
version of MySQL. If you see <literal>DISABLED</literal> in this
- row, then you need to enable it in either one of the two ways
- just described.
+ row, you need to enable it in either one of the two ways just
+ described.
</para>
<para>
- In order to read cluster configuration data, the MySQL server
- requires at a minimum 3 pieces of information:
+ To read cluster configuration data, the MySQL server requires at
+ a minimum three pieces of information:
</para>
<itemizedlist>
<listitem>
<para>
- The MySQL server's own cluster node ID.
+ The MySQL server's own cluster node ID
</para>
</listitem>
<listitem>
<para>
The hostname or IP address for the management server (MGM
- node).
+ node)
</para>
</listitem>
<listitem>
<para>
- The port on which it can connect to the management server.
+ The port on which it can connect to the management server
</para>
</listitem>
@@ -6261,8 +6273,8 @@
<para>
Instructs the management server as to which file it should
use for its configuration file. This option must be
- specified. The file name defaults to
- <literal>config.ini</literal>. The <option>-f</option>
+ specified. The filename defaults to
+ <filename>config.ini</filename>. The <option>-f</option>
shortcut is available beginning with MySQL Cluster 4.1.8.
</para>
</listitem>
@@ -6324,8 +6336,8 @@
</para>
<para>
- If the connection to the management server is broken, then
- the node tries to reconnect to it every 5 seconds until it
+ If the connection to the management server is broken, the
+ node tries to reconnect to it every 5 seconds until it
succeeds. By using this option, it is possible to limit
the number of attempts to
<replaceable>number</replaceable> before giving up and
@@ -6502,7 +6514,7 @@
</para>
<para>
- If this is a system restart, then the cluster determines the
+ If this is a system restart, the cluster determines the
latest restorable global checkpoint.
</para>
</listitem>
@@ -7104,10 +7116,10 @@
<para>
Event severity levels can be turned on or off. If a severity
- level is turned on, then all events with a priority less than
- or equal to the category thresholds are logged. If the
- severity level is turned off then no events belonging to that
- severity level are logged.
+ level is turned on, all events with a priority less than or
+ equal to the category thresholds are logged. If the severity
+ level is turned off then no events belonging to that severity
+ level are logged.
</para>
<remark role="todo">
@@ -8353,7 +8365,7 @@
</para>
<para>
- Any machines with which you wish to use SCI Sockets need to be
+ Any machines with which you wish to use SCI Sockets must be
equipped with SCI cards.
</para>
@@ -8464,8 +8476,8 @@
procesors. To build the libraries for Opteron CPUs using the
64-bit extensions, run
<command>make_PSB_66_X86_64_release</command> rather than
- <command>make_PSB_66_release</command>; if the build is made on
- an Itanium machine, then you should use
+ <command>make_PSB_66_release</command>. If the build is made on
+ an Itanium machine, you should use
<command>make_PSB_66_IA64_release</command>. The X86-64 variant
should work for Intel EM64T architectures but this has not yet
(to our knowledge) been tested.
@@ -8985,7 +8997,7 @@
<command>ndbd</command> process priority is set in such a way
that the process does not lose priority due to running for an
extended period of time, as can be done by locking processes to
- CPUs in Linux 2.6. If such a configuration is possible, then the
+ CPUs in Linux 2.6. If such a configuration is possible, the
<command>ndbd</command> process will benefit by 10-70% as
compared with using SCI sockets. (The larger figures will be
seen when performing updates and probably on parallel scan
@@ -9405,7 +9417,7 @@
<literal>CREATE INDEX</literal>, as the <literal>NDB
Cluster</literal> does not support autodiscovery of such
changes. (However, you can import or create a table that
- uses a different storage engine, then convert it to
+ uses a different storage engine, and then convert it to
<literal>NDB</literal> using <literal>ALTER TABLE
<replaceable>tbl_name</replaceable>
ENGINE=NDBCLUSTER</literal>. In such a case, you must
@@ -9535,14 +9547,13 @@
This means that if the master fails, it is possible that the
slave might not have recorded the last few transactions. If a
transaction-safe engine such as <literal>InnoDB</literal> is
- being used, then a transaction will either be complete on the
- slave or not applied at all, but replication does not
- guarantee that all data on the master and the slave will be
- consistent at all times. In MySQL Cluster, all data nodes are
- kept in synchrony, and a transaction committed by any one data
- node is committed for all data nodes. In the event of a data
- node failure, all remaining data nodes remain in a consistent
- state.
+ being used, a transaction will either be complete on the slave
+ or not applied at all, but replication does not guarantee that
+ all data on the master and the slave will be consistent at all
+ times. In MySQL Cluster, all data nodes are kept in synchrony,
+ and a transaction committed by any one data node is committed
+ for all data nodes. In the event of a data node failure, all
+ remaining data nodes remain in a consistent state.
</para>
<para>
@@ -9719,11 +9730,10 @@
<para>
Currently, Cluster is in-memory only. This means that all
table data (including indexes) is stored in RAM. Therefore, if
- your data takes up 1 gigabyte of space and you wish to
- replicate it once in the cluster, you need 2 gigabytes of
- memory to do so. This in addition to the memory required by
- the operating system and any applications running on the
- cluster computers.
+ your data takes up 1GB of space and you want to replicate it
+ once in the cluster, you need 2GB of memory to do so. This in
+ addition to the memory required by the operating system and
+ any applications running on the cluster computers.
</para>
<para>
@@ -10068,14 +10078,14 @@
separate machine. If you place multiple nodes on a single
machine and that machine fails, you lose all of those nodes.
Given that MySQL Cluster can be run on commodity hardware
- loaded with a low-cost (or even no-cost) operating system, it
- is well worth the expense of an extra machine or two in order
- to safeguard mission-critical data. It also worth noting that
- the requirements for a cluster host running a management node
- are minimal. This task can be accomplished with a 200 MHz
- Pentium CPU and sufficient RAM for the operating system plus a
- small amount of overhead for the <command>ndb_mgmd</command>
- and <command>ndb_mgm</command> processes.
+ loaded with a low-cost (or even no-cost) operating system, the
+ expense of an extra machine or two is well worth it to
+ safeguard mission-critical data. It also worth noting that the
+ requirements for a cluster host running a management node are
+ minimal. This task can be accomplished with a 200 MHz Pentium
+ CPU and sufficient RAM for the operating system plus a small
+ amount of overhead for the <command>ndb_mgmd</command> and
+ <command>ndb_mgm</command> processes.
</para>
</listitem>
@@ -10277,7 +10287,7 @@
<para>
When cluster nodes go down, there are two possibilities. If
more than 50% of the remaining nodes can communicate with each
- other, then we have what is sometimes called a <quote>majority
+ other, we have what is sometimes called a <quote>majority
rules</quote> situation, and this set of nodes is considered
to be the cluster. The arbitrator comes into play when there
is an even number of nodes: in such cases, the set of nodes to
@@ -10399,8 +10409,8 @@
</para>
<para>
- To shut down the cluster, enter the following in a shell on
- the machine hosting the MGM node:
+ To shut down the cluster, enter the following command in a
+ shell on the machine hosting the MGM node:
</para>
<programlisting>
@@ -10470,9 +10480,8 @@
<para>
Yes, it is possible to do this. In the case of multiple data
nodes, each node must use a different data directory. If you
- want to run multiple SQL nodes on one machine, then each
- instance of <command>mysqld</command> must use a different
- TCP/IP port.
+ want to run multiple SQL nodes on one machine, each instance
+ of <command>mysqld</command> must use a different TCP/IP port.
</para>
</listitem>
@@ -10964,12 +10973,12 @@
node's host computer. For each data node in the cluster, you
must have available an amount of RAM equal to the size of the
database times the number of replicas, divided by the number
- of data nodes. Thus, if the database takes up 1 gigabyte of
- memory, and you wish to set up the cluster with four replicas
- and eight data nodes, a minimum of 500MB memory will be
- required per node. Note that this is in addition to any
- requirements for the operating system and any other
- applications that might be running on the host.
+ of data nodes. Thus, if the database takes up 1GB of memory,
+ and you want to set up the cluster with four replicas and
+ eight data nodes, a minimum of 500MB memory will be required
+ per node. Note that this is in addition to any requirements
+ for the operating system and any other applications that might
+ be running on the host.
</para>
</listitem>
Modified: trunk/refman-5.0/ndbcluster.xml
===================================================================
--- trunk/refman-5.0/ndbcluster.xml 2006-01-31 23:37:45 UTC (rev 1157)
+++ trunk/refman-5.0/ndbcluster.xml 2006-01-31 23:38:29 UTC (rev 1158)
@@ -254,9 +254,9 @@
Cluster, a client node is a traditional MySQL server that uses
the <literal>NDB Cluster</literal> storage engine. An SQL node
is typically started with the command <command>mysqld
- --ndbcluster</command> or simply by using
- <command>mysqld</command> with <literal>ndbcluster</literal>
- added to <filename>my.cnf</filename>.
+ --ndbcluster</command> or by using <command>mysqld</command>
+ with the <literal>ndbcluster</literal> option added to
+ <filename>my.cnf</filename>.
</para>
</listitem>
@@ -625,9 +625,9 @@
<emphasis role="bold">Note</emphasis>: In the interest of
simplicity (and reliability), this How-To uses only numeric IP
addresses. However, if DNS resolution is available on your
- network, then it is possible to use hostnames in lieu of IP
- addresses in configuring Cluster. Alternatively, you can also
- use the <filename>/etc/hosts</filename> file or your operating
+ network, it is possible to use hostnames in lieu of IP
+ addresses in configuring Cluster. Alternatively, you can use
+ the <filename>/etc/hosts</filename> file or your operating
system's equivalent for providing a means to do host lookup if
such is available.
</para>
@@ -1417,8 +1417,8 @@
<para>
This will need to be done for the definition of each table
that is to be part of the clustered database. The easiest
- way to accomplish this is simply to do a search-and-replace
- on the <filename>world.sql</filename> file and replace all
+ way to accomplish this is to do a search-and-replace on the
+ <filename>world.sql</filename> file and replace all
instances of <literal>TYPE=MyISAM</literal> or
<literal>ENGINE=MyISAM</literal> with
<literal>ENGINE=NDBCLUSTER</literal>. If you do not want to
@@ -1450,7 +1450,7 @@
<para>
To create a copy of the <literal>world</literal> database on
the SQL node, save the file to
- <filename>/usr/local/mysql/data</filename>, then run
+ <filename>/usr/local/mysql/data</filename>, and then run
</para>
<programlisting>
@@ -1580,7 +1580,7 @@
<body>
<?php
# connect to SQL node:
- $link = new mysqli('192.168.0.20', 'root', '', 'world');
+ $link = new mysqli('192.168.0.20', 'root', '<replaceable>root_password</replaceable>', 'world');
# parameters for mysqli constructor are:
# host, user, password, database
@@ -1662,7 +1662,7 @@
<title>&title-multi-shutdown-restart;</title>
<para>
- To shut down the cluster simply enter the following in a shell
+ To shut down the cluster, enter the following command in a shell
on the machine hosting the MGM node:
</para>
@@ -1676,17 +1676,17 @@
</remark>
<para>
- This will cause the <command>ndb_mgm</command>,
- <command>ndb_mgmd</command>, and any <command>ndbd</command>
- processes to terminate gracefully. Any SQL nodes can be
- terminated using <command>mysqladmin shutdown</command> and
- other means. Note that the <option>-e</option> option here is
- used to pass a command to the <command>ndb_mgm</command> client
- from the shell. See <xref linkend="command-line-options"/>.
+ The <option>-e</option> option here is used to pass a command to
+ the <command>ndb_mgm</command> client from the shell. See
+ <xref linkend="command-line-options"/>. The command causes the
+ <command>ndb_mgm</command>, <command>ndb_mgmd</command>, and any
+ <command>ndbd</command> processes to terminate gracefully. Any
+ SQL nodes can be terminated using <command>mysqladmin
+ shutdown</command> and other means.
</para>
<para>
- To restart the cluster, simply run these commands:
+ To restart the cluster, run these commands:
</para>
<itemizedlist>
@@ -1694,7 +1694,7 @@
<listitem>
<para>
On the management host (<literal>192.168.0.10</literal> in
- our setup):
+ our example setup):
</para>
<programlisting>
@@ -1722,7 +1722,7 @@
<listitem>
<para>
- And on the SQL host (<literal>192.168.0.20</literal>):
+ On the SQL host (<literal>192.168.0.20</literal>):
</para>
<programlisting>
@@ -1732,6 +1732,11 @@
</itemizedlist>
+ <remark role="todo">
+ [pd] Hmm ... why are these three paragraphs _here_? (But where
+ would be more appropriate instead?)
+ </remark>
+
<para>
For information on making Cluster backups, see
<xref linkend="mysql-cluster-backup-using-management-server"/>.
@@ -1765,20 +1770,19 @@
</para>
<para>
- In order to avoid unnecessary allocation of resources, the server
- is configured by default with the <literal>NDB</literal> storage
- engine disabled. To enable <literal>NDB</literal>, you will need
- to modify the server's <filename>my.cnf</filename> configuration
- file, or start the server with the <option>--ndbcluster</option>
- option.
+ To avoid unnecessary allocation of resources, the server is
+ configured by default with the <literal>NDB</literal> storage
+ engine disabled. To enable <literal>NDB</literal>, you must modify
+ the server's <filename>my.cnf</filename> configuration file, or
+ start the server with the <option>--ndbcluster</option> option.
</para>
<para>
- The MySQL server is a part of the cluster, so it will also need to
- know how to access an MGM node to obtain the cluster configuration
+ The MySQL server is a part of the cluster, so it also must know
+ how to access an MGM node to obtain the cluster configuration
data. The default behavior is to look for the MGM node on
<literal>localhost</literal>. However, should you need to specify
- its location elsewhere, this can be done in
+ that its location is elsewhere, this can be done in
<filename>my.cnf</filename> or on the MySQL server command line.
Before the <literal>NDB</literal> storage engine can be used, at
least one MGM node must be operational, as well as any desired
@@ -1802,12 +1806,12 @@
<option>--with-ndbcluster</option> option when running
<command>configure</command>. You can also use the
<command>BUILD/compile-pentium-max</command> build script. Note
- that this script includes OpenSSL, so you must have or obtain
- OpenSSL to build successfully; otherwise you will need to modify
+ that this script includes OpenSSL, so you must either have or
+ obtain OpenSSL to build successfully, or else modify
<command>compile-pentium-max</command> to exclude this
requirement. Of course, you can also just follow the standard
- instructions for compiling your own binaries, then perform the
- usual tests and installation procedure. See
+ instructions for compiling your own binaries, and then perform
+ the usual tests and installation procedure. See
<xref linkend="installing-source-tree"/>.
</para>
@@ -1841,11 +1845,11 @@
<title>&title-mysql-cluster-quick;</title>
<para>
- In order to familiarize you with the basics, we will describe
- the simplest possible configuration for a functional MySQL
- Cluster. After this, you should be able to design your desired
- setup from the information provided in the other relevant
- sections of this chapter.
+ To familiarize you with the basics, we will describe the
+ simplest possible configuration for a functional MySQL Cluster.
+ After this, you should be able to design your desired setup from
+ the information provided in the other relevant sections of this
+ chapter.
</para>
<para>
@@ -1860,9 +1864,10 @@
<para>
In this directory, create a file named
- <filename>config.ini</filename> with the following information,
- substituting appropriate values for <literal>HostName</literal>
- and <literal>DataDir</literal> as necessary for your system.
+ <filename>config.ini</filename> that contains the following
+ information. Substitute appropriate values for
+ <literal>HostName</literal> and <literal>DataDir</literal> as
+ necessary for your system.
</para>
<programlisting>
@@ -1898,7 +1903,11 @@
</programlisting>
<para>
- You can now start the management server as follows:
+ You can now start the <command>ndb_mgmd</command> management
+ server. By default, it atttempts to read the
+ <filename>config.ini</filename> file in its current working
+ directory, so change location into the directory where the file
+ is located and then invoke <command>ndb_mgmd</command>:
</para>
<programlisting>
@@ -1919,7 +1928,7 @@
<para>
For subsequent <command>ndbd</command> starts, you will
- generally <emphasis role="bold">not</emphasis> want to use the
+ generally want to <emphasis>omit</emphasis> the
<option>--initial</option> option:
</para>
@@ -1928,11 +1937,14 @@
</programlisting>
<para>
- The reason for this is that the <option>--initial</option>
- option will delete all existing data and log files (as well as
- all table metadata) for this data node and create new ones. One
- exception to this rule is when restarting the cluster and
- restoring from backup after adding new data nodes.
+ The reason for omitting <option>--initial</option> on subsequent
+ restarts is that this option causes <command>ndbd</command> to
+ delete and re-create all existing data and log files (as well as
+ all table metadata) for this data node. One exception to this
+ rule about not using <option>--initial</option> except for the
+ first <command>ndbd</command> invocation is that you use it when
+ restarting the cluster and restoring from backup after adding
+ new data nodes.
</para>
<remark role="todo">
@@ -1940,7 +1952,7 @@
</remark>
<para>
- By default, <command>ndbd</command> will look for the management
+ By default, <command>ndbd</command> looks for the management
server at <literal>localhost</literal> on port 1186.
</para>
@@ -1953,7 +1965,7 @@
</para>
<para>
- Finally, go to the MySQL data directory (usually
+ Finally, change location to the MySQL data directory (usually
<filename>/var/lib/mysql</filename> or
<filename>/usr/local/mysql/data</filename>), and make sure that
the <filename>my.cnf</filename> file contains the option
@@ -1982,7 +1994,8 @@
<para>
If all has gone well so far, you now can start using the
- cluster:
+ cluster. Connect to the server and verify that the
+ <literal>NDBCLUSTER</literal> storage engine is enabled:
</para>
<programlisting>
@@ -1993,7 +2006,6 @@
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> <userinput>SHOW ENGINES\G</userinput>
-
...
*************************** 12. row ***************************
Engine: NDBCLUSTER
@@ -2007,18 +2019,17 @@
</programlisting>
<para>
- (Note that the row numbers shown in the preceding example output
- may be different from those shown on your system, depending upon
- the MySQL version being used and how it is configured.)
+ The row numbers shown in the preceding example output may be
+ different from those shown on your system, depending upon how
+ your server is configured.
</para>
+ <para>
+ Try to create an <literal>NDBCLUSTER</literal> table:
+ </para>
+
<programlisting>
shell> <userinput>mysql</userinput>
-Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 1 to server version: ¤t-version;-Max
-
-Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
-
mysql> <userinput>USE test;</userinput>
Database changed
@@ -2036,7 +2047,7 @@
<para>
To check that your nodes were set up properly, start the
- management client as shown:
+ management client:
</para>
<programlisting>
@@ -2044,9 +2055,8 @@
</programlisting>
<para>
- You can then use the <command>SHOW</command> statement from
- within the management client to obtain a report on the cluster's
- status:
+ Use the <command>SHOW</command> command from within the
+ management client to obtain a report on the cluster's status:
</para>
<programlisting>
@@ -2097,7 +2107,7 @@
<para>
<filename>config.ini</filename>: This file is read only by
the MySQL Cluster management server, which then distributes
- the information contained in this file to all processes
+ the information contained therein to all processes
participating in the cluster.
<filename>config.ini</filename> contains a description of
each node involved in the cluster. This includes
@@ -2114,10 +2124,9 @@
maintain backward compatibility, there may be times when
introduce an incompatible change. In such cases we will try to
let Cluster users know in advance if a change is not backward
- compatible. If you find such a change which we have not
- documented, please use our
- <ulink url="http://bugs.mysql.com/">Bugs Database</ulink> to
- report it.
+ compatible. If you find such a change and we have not documented
+ it, please report it in the MySQL bugs database using the
+ instructions given in <xref linkend="bug-reports"/>.
</para>
<section id="mysql-cluster-config-example">
@@ -2125,12 +2134,12 @@
<title>&title-mysql-cluster-config-example;</title>
<para>
- In order to support MySQL Cluster, you will need to update
+ To support MySQL Cluster, you will need to update
<filename>my.cnf</filename> as shown in the following example.
Note that the options shown here should not be confused with
- those occurring in <filename>config.ini</filename> files. You
- may also specify these parameters when invoking the
- executables from the command line.
+ those that are used in <filename>config.ini</filename> files.
+ You may also specify these parameters on the command line when
+ invoking the executables.
</para>
<programlisting>
@@ -2177,8 +2186,8 @@
<para>
You may also use a separate <literal>[mysql_cluster]</literal>
- section in the cluster <filename>my.cnf</filename> for
- settings to be read by and affecting all executables:
+ section in the cluster <filename>my.cnf</filename> file for
+ settings to be read and used by all executables:
</para>
<programlisting>
@@ -2192,44 +2201,48 @@
</remark>
<para>
- Currently, the configuration file is in INI format, and is
- named <filename>config.ini</filename> by default. It is read
- by <command>ndb_mgmd</command> at startup and can be placed
+ The configuration file is named
+ <filename>config.ini</filename> by default. It is read by
+ <command>ndb_mgmd</command> at startup and can be placed
anywhere. Its location and name are specified by using
- <option>--config-file=[<replaceable><path></replaceable>]<replaceable><filename></replaceable></option>
- on the command line with <command>ndb_mgmd</command>. If the
+ <option>--config-file=<replaceable>path_name</replaceable></option>
+ on the <command>ndb_mgmd</command> command line. If the
configuration file is not specified,
- <command>ndb_mgmd</command> by default tries to read a
- <filename>config.ini</filename> file located in the current
+ <command>ndb_mgmd</command> by default tries to read a file
+ named <filename>config.ini</filename> located in the current
working directory.
</para>
<para>
+ Currently, the configuration file is in INI format, which
+ consists of sections preceded by section headings (surrounded
+ by square brackets), followed by the appropriate parameter
+ names and values. One deviation from the standard INI format
+ is that the parameter name and value can be separated by a
+ colon (‘<literal>:</literal>’) as well as the
+ equals sign (‘<literal>=</literal>’). Another
+ deviation is that sections are not uniquely identified by
+ section name. Instead, unique sections (such as two different
+ nodes of the same type) are identified by a unique ID
+ specified as a parameter within the section.
+ </para>
+
+ <para>
Default values are defined for most parameters, and can also
be specified in <filename>config.ini</filename>. To create a
default value section, simply add the word
<literal>DEFAULT</literal> to the section name. For example,
- data nodes are configured using <literal>[NDBD]</literal>
- sections. If all data nodes use the same data memory size, and
- this is not the same as the default size, create an
- <literal>[NDBD DEFAULT]</literal> section containing a
- <literal>DataMemory</literal> line to specify the default data
- memory size for all data nodes.
+ an <literal>[NDBD]</literal> section contains parameters that
+ apply to a particular data node, whereas an <literal>[NDBD
+ DEFAULT]</literal> section contains parameters that apply to
+ all data nodes. Suppose that all data nodes should use the
+ same data memory size. To configure them all, create an
+ <literal>[NDBD DEFAULT]</literal> section that contains a
+ <literal>DataMemory</literal> line to specify the data memory
+ size.
</para>
<para>
- The INI format consists of sections preceded by section
- headings (surrounded by square brackets), followed by the
- appropriate parameter names and values. One deviation from the
- standard format is that the parameter name and value can be
- separated by a colon (‘<literal>:</literal>’) as
- well as the equals sign (‘<literal>=</literal>’);
- another is that sections are not uniquely identified by name.
- Instead, unique entries (such as two different nodes of the
- same type) are identified by a unique ID.
- </para>
-
- <para>
At a minimum, the configuration file must define the computers
and nodes involved in the cluster and on which computers these
nodes are located. An example of a simple configuration file
@@ -2239,10 +2252,10 @@
<programlisting>
# file "config.ini" - 2 data nodes and 2 SQL nodes
-# This file is placed in the startup directory of ndb_mgmd (the management
-# server)
-# The first MySQL Server can be started from any host. The second can be started
-# only on the host mysqld_5.mysql.com
+# This file is placed in the startup directory of ndb_mgmd (the
+# management server)
+# The first MySQL Server can be started from any host. The second
+# can be started only on the host mysqld_5.mysql.com
[NDBD DEFAULT]
NoOfReplicas= 2
@@ -2837,8 +2850,8 @@
specifying <literal>ExecuteOnComputer</literal>. It
defines the hostname of the computer the storage node on
which is to reside. Either this parameter or
- <literal>ExecuteOnComputer</literal> is required in order
- to specify a hostname other than
+ <literal>ExecuteOnComputer</literal> is required to
+ specify a hostname other than
<literal>localhost</literal>.
</para>
</listitem>
@@ -2935,8 +2948,8 @@
includes <filename>/var/lib/mysql-cluster</filename>,
under which a directory for the node's filesystem is
created. This subdirectory contains the node ID. For
- example, if the node ID is 2, then this subdirectory is
- named <filename>ndb_2_fs</filename>.
+ example, if the node ID is 2, this subdirectory is named
+ <filename>ndb_2_fs</filename>.
</para>
</listitem>
@@ -3177,9 +3190,9 @@
database size is the sum of all data memory and all index
memory for each node group. Each node group is used to
store replicated information, so if there are four nodes
- with 2 replicas, then there will be two node groups. Thus,
- the total data memory available is
- 2*<literal>DataMemory</literal> for each data node.
+ with two replicas, there will be two node groups. Thus,
+ the total data memory available is 2 ×
+ <literal>DataMemory</literal> for each data node.
</para>
<para>
@@ -3201,9 +3214,9 @@
memory space. Increasing these values should be
acceptable, but it is recommended that such upgrades are
performed in the same manner as a software upgrade,
- beginning with an update of the configuration file, then
- restarting the management server followed by restarting
- each data node in turn.
+ beginning with an update of the configuration file, and
+ then restarting the management server followed by
+ restarting each data node in turn.
</para>
<para>
@@ -3362,11 +3375,11 @@
involved in the transaction. However, the operation
records of the are spread over all 8 nodes. Thus, if it is
necessary to configure the system for one very large
- transaction, then it is a good idea to configure the two
- parts separately.
- <literal>MaxNoOfConcurrentOperations</literal> will always
- be used to calculate the number of operation records in
- the transaction coordinator portion of the node.
+ transaction, it is a good idea to configure the two parts
+ separately. <literal>MaxNoOfConcurrentOperations</literal>
+ will always be used to calculate the number of operation
+ records in the transaction coordinator portion of the
+ node.
</para>
<para>
@@ -3382,13 +3395,13 @@
</para>
<para>
- By default, this parameter is calculated as 1.1 *
+ By default, this parameter is calculated as 1.1 ×
<literal>MaxNoOfConcurrentOperations</literal> which fits
systems with many simultaneous transactions, none of them
being very large. If there is a need to handle one very
- large transaction at a time and there are many nodes, then
- it is a good idea to override the default value by
- explicitly specifying this parameter.
+ large transaction at a time and there are many nodes, it
+ is a good idea to override the default value by explicitly
+ specifying this parameter.
</para>
</listitem>
@@ -3684,7 +3697,7 @@
<para>
If the checkpointing is slow and there are so many writes
to the database that the log files are full and the log
- tail cannot be cut without jeopardizing recovery, then all
+ tail cannot be cut without jeopardizing recovery, all
updating transactions will be aborted with internal error
code 410, or <literal>Out of log file space
temporarily</literal>. This condition will prevail until a
@@ -3772,16 +3785,16 @@
<para>
When setting <literal>MaxNoOfAttributes</literal>, it is
important to prepare in advance for any <literal>ALTER
- TABLE</literal> statements that you might wish to perform
+ TABLE</literal> statements that you might want to perform
in future. This is due to the fact, during the execution
of <literal>ALTER TABLE</literal> on a Cluster table, 3
times the number of attributes as in the original table
are used. For example, if a table requires 100 attributes,
- and you wish to be able to alter it later, then you need
- to set the value of <literal>MaxNoOfAttributes</literal>
- to 300. A good rule of thumb is that, if you can create
- all desired tables without any problems, then add 2 times
- the number of attributes in the largest table to
+ and you want to be able to alter it later, you need to set
+ the value of <literal>MaxNoOfAttributes</literal> to 300.
+ A good rule of thumb is that, if you can create all
+ desired tables without any problems, add 2 times the
+ number of attributes in the largest table to
<literal>MaxNoOfAttributes</literal> to be sure. You
should also verify that this number is sufficient by
trying an actual <literal>ALTER TABLE</literal> after
@@ -4097,7 +4110,7 @@
<para>
If a data node has not completed its startup sequence
- within the time specified by this parameter, then the node
+ within the time specified by this parameter, the node
startup will fail. Setting this parameter to
<literal>0</literal> means that no data node timeout is
applied.
@@ -4246,8 +4259,8 @@
Timeout handling is performed by checking a timer on each
transaction once for every interval specified by this
parameter. Thus, if this parameter is set to 1000
- milliseconds, then every transaction will be checked for
- timing out once per second.
+ milliseconds, every transaction will be checked for timing
+ out once per second.
</para>
<para>
@@ -4449,7 +4462,7 @@
<para>
This parameter specifies the time that the data node will
wait for a response from the arbitrator to an arbitration
- message. If this is exceeded, then it is assumed that the
+ message. If this is exceeded, it is assumed that the
network has split.
</para>
@@ -4475,10 +4488,10 @@
<para>
These buffers are used as front ends to the file system when
writing log records to disk. If the node is running in
- diskless mode, then these parameters can be set to their
- minimum values without penalty due to the fact that disk
- writes are <quote>faked</quote> by the <literal>NDB</literal>
- storage engine's filesystem abstraction layer.
+ diskless mode, these parameters can be set to their minimum
+ values without penalty due to the fact that disk writes are
+ <quote>faked</quote> by the <literal>NDB</literal> storage
+ engine's filesystem abstraction layer.
</para>
<itemizedlist>
@@ -4492,7 +4505,7 @@
This buffer is used during local checkpoints. The
<literal>NDB</literal> storage engine uses a recovery
scheme based on checkpoint consistency in conjunction with
- an operational REDO log. In order to produce a consistent
+ an operational REDO log. To produce a consistent
checkpoint without blocking the entire system for writes,
UNDO logging is done while performing the local
checkpoint. UNDO logging is activated on a single table
@@ -4556,7 +4569,7 @@
<para>
It is rarely necessary to increase the size of this
- buffer. If there is such a need, then it is a good idea to
+ buffer. If there is such a need, it is a good idea to
check whether the disks can actually handle the load
caused by database update activity. A lack of sufficient
disk space cannot be overcome by increasing the size of
@@ -4871,7 +4884,7 @@
<filename>config.ini</filename> file define the behavior of
the MySQL servers (SQL nodes) used to access cluster data.
None of the parameters shown is required. If no computer or
- host name is provided, then any host can use this SQL node.
+ host name is provided, any host can use this SQL node.
</para>
<itemizedlist>
@@ -4987,10 +5000,10 @@
<para>
The batch size is the size of each batch sent from each
- data node. Most scans are performed in parallel in order
- to protect the MySQL Server from receiving too much data
- from many nodes in parallel; this parameter sets a limit
- to the total batch size over all nodes.
+ data node. Most scans are performed in parallel to protect
+ the MySQL Server from receiving too much data from many
+ nodes in parallel; this parameter sets a limit to the
+ total batch size over all nodes.
</para>
<para>
@@ -5072,11 +5085,10 @@
</para>
<para>
- In order to be able to retrace a distributed message
- diagram it is necessary to identify each message. When
- this parameter is set to <literal>Y</literal>, message IDs
- are transported over the network. This feature is disabled
- by default.
+ To be able to retrace a distributed message diagram it is
+ necessary to identify each message. When this parameter is
+ set to <literal>Y</literal>, message IDs are transported
+ over the network. This feature is disabled by default.
</para>
</listitem>
@@ -5272,8 +5284,8 @@
</para>
<para>
- In order to retrace the path of a distributed message, it
- is necessary to provide each message with a unique
+ To retrace the path of a distributed message, it is
+ necessary to provide each message with a unique
identifier. Setting this parameter to <literal>Y</literal>
causes these message IDs to be transported over the
network as well. This feature is disabled by default.
@@ -5435,10 +5447,10 @@
</para>
<para>
- In order to trace a distributed message it is necessary to
- identify each message uniquely. When this parameter is set
- to <literal>Y</literal>, message IDs are transported over
- the network. This feature is disabled by default.
+ To trace a distributed message it is necessary to identify
+ each message uniquely. When this parameter is set to
+ <literal>Y</literal>, message IDs are transported over the
+ network. This feature is disabled by default.
</para>
</listitem>
@@ -5541,33 +5553,33 @@
in this row (or if there is no such row displayed in the
output), you are not running an <literal>NDB</literal>-enabled
version of MySQL. If you see <literal>DISABLED</literal> in this
- row, then you need to enable it in either one of the two ways
- just described.
+ row, you need to enable it in either one of the two ways just
+ described.
</para>
<para>
- In order to read cluster configuration data, the MySQL server
- requires at a minimum 3 pieces of information:
+ To read cluster configuration data, the MySQL server requires at
+ a minimum three pieces of information:
</para>
<itemizedlist>
<listitem>
<para>
- The MySQL server's own cluster node ID.
+ The MySQL server's own cluster node ID
</para>
</listitem>
<listitem>
<para>
The hostname or IP address for the management server (MGM
- node).
+ node)
</para>
</listitem>
<listitem>
<para>
- The port on which it can connect to the management server.
+ The port on which it can connect to the management server
</para>
</listitem>
@@ -6231,16 +6243,16 @@
<para>
Instructs the management server as to which file it should
use for its configuration file. This option must be
- specified. The file name defaults to
- <literal>config.ini</literal>.
+ specified. The filename defaults to
+ <filename>config.ini</filename>.
</para>
<para>
<emphasis role="bold">Note</emphasis>: This option also
can be given as <option>-c
- <filename>file_name</filename></option>, but this shortcut
- is obsolete and should <emphasis>not</emphasis> be used in
- new installations.
+ <replaceable>file_name</replaceable></option>, but this
+ shortcut is obsolete and should <emphasis>not</emphasis>
+ be used in new installations.
</para>
</listitem>
@@ -6300,8 +6312,8 @@
</para>
<para>
- If the connection to the management server is broken, then
- the node tries to reconnect to it every 5 seconds until it
+ If the connection to the management server is broken, the
+ node tries to reconnect to it every 5 seconds until it
succeeds. By using this option, it is possible to limit
the number of attempts to
<replaceable>number</replaceable> before giving up and
@@ -6478,7 +6490,7 @@
</para>
<para>
- If this is a system restart, then the cluster determines the
+ If this is a system restart, the cluster determines the
latest restorable global checkpoint.
</para>
</listitem>
@@ -7080,10 +7092,10 @@
<para>
Event severity levels can be turned on or off. If a severity
- level is turned on, then all events with a priority less than
- or equal to the category thresholds are logged. If the
- severity level is turned off then no events belonging to that
- severity level are logged.
+ level is turned on, all events with a priority less than or
+ equal to the category thresholds are logged. If the severity
+ level is turned off then no events belonging to that severity
+ level are logged.
</para>
<remark role="todo">
@@ -8328,7 +8340,7 @@
</para>
<para>
- Any machines with which you wish to use SCI Sockets need to be
+ Any machines with which you wish to use SCI Sockets must be
equipped with SCI cards.
</para>
@@ -8439,8 +8451,8 @@
procesors. To build the libraries for Opteron CPUs using the
64-bit extensions, run
<command>make_PSB_66_X86_64_release</command> rather than
- <command>make_PSB_66_release</command>; if the build is made on
- an Itanium machine, then you should use
+ <command>make_PSB_66_release</command>. If the build is made on
+ an Itanium machine, you should use
<command>make_PSB_66_IA64_release</command>. The X86-64 variant
should work for Intel EM64T architectures but this has not yet
(to our knowledge) been tested.
@@ -8959,7 +8971,7 @@
<command>ndbd</command> process priority is set in such a way
that the process does not lose priority due to running for an
extended period of time, as can be done by locking processes to
- CPUs in Linux 2.6. If such a configuration is possible, then the
+ CPUs in Linux 2.6. If such a configuration is possible, the
<command>ndbd</command> process will benefit by 10-70% as
compared with using SCI sockets. (The larger figures will be
seen when performing updates and probably on parallel scan
@@ -9387,7 +9399,7 @@
<literal>CREATE INDEX</literal>, as the <literal>NDB
Cluster</literal> does not support autodiscovery of such
changes. (However, you can import or create a table that
- uses a different storage engine, then convert it to
+ uses a different storage engine, and then convert it to
<literal>NDB</literal> using <literal>ALTER TABLE
<replaceable>tbl_name</replaceable>
ENGINE=NDBCLUSTER</literal>. In such a case, you must
@@ -9814,14 +9826,13 @@
This means that if the master fails, it is possible that the
slave might not have recorded the last few transactions. If a
transaction-safe engine such as <literal>InnoDB</literal> is
- being used, then a transaction will either be complete on the
- slave or not applied at all, but replication does not
- guarantee that all data on the master and the slave will be
- consistent at all times. In MySQL Cluster, all data nodes are
- kept in synchrony, and a transaction committed by any one data
- node is committed for all data nodes. In the event of a data
- node failure, all remaining data nodes remain in a consistent
- state.
+ being used, a transaction will either be complete on the slave
+ or not applied at all, but replication does not guarantee that
+ all data on the master and the slave will be consistent at all
+ times. In MySQL Cluster, all data nodes are kept in synchrony,
+ and a transaction committed by any one data node is committed
+ for all data nodes. In the event of a data node failure, all
+ remaining data nodes remain in a consistent state.
</para>
<para>
@@ -9999,11 +10010,10 @@
<para>
Currently, Cluster is in-memory only. This means that all
table data (including indexes) is stored in RAM. Therefore, if
- your data takes up 1 gigabyte of space and you wish to
- replicate it once in the cluster, you need 2 gigabytes of
- memory to do so. This in addition to the memory required by
- the operating system and any applications running on the
- cluster computers.
+ your data takes up 1GB of space and you want to replicate it
+ once in the cluster, you need 2GB of memory to do so. This in
+ addition to the memory required by the operating system and
+ any applications running on the cluster computers.
</para>
<para>
@@ -10356,14 +10366,14 @@
separate machine. If you place multiple nodes on a single
machine and that machine fails, you lose all of those nodes.
Given that MySQL Cluster can be run on commodity hardware
- loaded with a low-cost (or even no-cost) operating system, it
- is well worth the expense of an extra machine or two in order
- to safeguard mission-critical data. It also worth noting that
- the requirements for a cluster host running a management node
- are minimal. This task can be accomplished with a 200 MHz
- Pentium CPU and sufficient RAM for the operating system plus a
- small amount of overhead for the <command>ndb_mgmd</command>
- and <command>ndb_mgm</command> processes.
+ loaded with a low-cost (or even no-cost) operating system, the
+ expense of an extra machine or two is well worth it to
+ safeguard mission-critical data. It also worth noting that the
+ requirements for a cluster host running a management node are
+ minimal. This task can be accomplished with a 200 MHz Pentium
+ CPU and sufficient RAM for the operating system plus a small
+ amount of overhead for the <command>ndb_mgmd</command> and
+ <command>ndb_mgm</command> processes.
</para>
</listitem>
@@ -10565,7 +10575,7 @@
<para>
When cluster nodes go down, there are two possibilities. If
more than 50% of the remaining nodes can communicate with each
- other, then we have what is sometimes called a <quote>majority
+ other, we have what is sometimes called a <quote>majority
rules</quote> situation, and this set of nodes is considered
to be the cluster. The arbitrator comes into play when there
is an even number of nodes: in such cases, the set of nodes to
@@ -10687,8 +10697,8 @@
</para>
<para>
- To shut down the cluster, enter the following in a shell on
- the machine hosting the MGM node:
+ To shut down the cluster, enter the following command in a
+ shell on the machine hosting the MGM node:
</para>
<programlisting>
@@ -10757,9 +10767,8 @@
<para>
Yes, it is possible to do this. In the case of multiple data
nodes, each node must use a different data directory. If you
- want to run multiple SQL nodes on one machine, then each
- instance of <command>mysqld</command> must use a different
- TCP/IP port.
+ want to run multiple SQL nodes on one machine, each instance
+ of <command>mysqld</command> must use a different TCP/IP port.
</para>
</listitem>
@@ -11251,12 +11260,12 @@
node's host computer. For each data node in the cluster, you
must have available an amount of RAM equal to the size of the
database times the number of replicas, divided by the number
- of data nodes. Thus, if the database takes up 1 gigabyte of
- memory, and you wish to set up the cluster with four replicas
- and eight data nodes, a minimum of 500MB memory will be
- required per node. Note that this is in addition to any
- requirements for the operating system and any other
- applications that might be running on the host.
+ of data nodes. Thus, if the database takes up 1GB of memory,
+ and you want to set up the cluster with four replicas and
+ eight data nodes, a minimum of 500MB memory will be required
+ per node. Note that this is in addition to any requirements
+ for the operating system and any other applications that might
+ be running on the host.
</para>
</listitem>
Modified: trunk/refman-5.1/ndbcluster.xml
===================================================================
--- trunk/refman-5.1/ndbcluster.xml 2006-01-31 23:37:45 UTC (rev 1157)
+++ trunk/refman-5.1/ndbcluster.xml 2006-01-31 23:38:29 UTC (rev 1158)
@@ -254,9 +254,9 @@
Cluster, a client node is a traditional MySQL server that uses
the <literal>NDB Cluster</literal> storage engine. An SQL node
is typically started with the command <command>mysqld
- --ndbcluster</command> or simply by using
- <command>mysqld</command> with <literal>ndbcluster</literal>
- added to <filename>my.cnf</filename>.
+ --ndbcluster</command> or by using <command>mysqld</command>
+ with the <literal>ndbcluster</literal> option added to
+ <filename>my.cnf</filename>.
</para>
</listitem>
@@ -625,9 +625,9 @@
<emphasis role="bold">Note</emphasis>: In the interest of
simplicity (and reliability), this How-To uses only numeric IP
addresses. However, if DNS resolution is available on your
- network, then it is possible to use hostnames in lieu of IP
- addresses in configuring Cluster. Alternatively, you can also
- use the <filename>/etc/hosts</filename> file or your operating
+ network, it is possible to use hostnames in lieu of IP
+ addresses in configuring Cluster. Alternatively, you can use
+ the <filename>/etc/hosts</filename> file or your operating
system's equivalent for providing a means to do host lookup if
such is available.
</para>
@@ -1417,8 +1417,8 @@
<para>
This will need to be done for the definition of each table
that is to be part of the clustered database. The easiest
- way to accomplish this is simply to do a search-and-replace
- on the <filename>world.sql</filename> file and replace all
+ way to accomplish this is to do a search-and-replace on the
+ <filename>world.sql</filename> file and replace all
instances of <literal>TYPE=MyISAM</literal> or
<literal>ENGINE=MyISAM</literal> with
<literal>ENGINE=NDBCLUSTER</literal>. If you do not want to
@@ -1450,7 +1450,7 @@
<para>
To create a copy of the <literal>world</literal> database on
the SQL node, save the file to
- <filename>/usr/local/mysql/data</filename>, then run
+ <filename>/usr/local/mysql/data</filename>, and then run
</para>
<programlisting>
@@ -1578,7 +1578,7 @@
<body>
<?php
# connect to SQL node:
- $link = new mysqli('192.168.0.20', 'root', '', 'world');
+ $link = new mysqli('192.168.0.20', 'root', '<replaceable>root_password</replaceable>', 'world');
# parameters for mysqli constructor are:
# host, user, password, database
@@ -1660,7 +1660,7 @@
<title>&title-multi-shutdown-restart;</title>
<para>
- To shut down the cluster simply enter the following in a shell
+ To shut down the cluster, enter the following command in a shell
on the machine hosting the MGM node:
</para>
@@ -1674,17 +1674,17 @@
</remark>
<para>
- This will cause the <command>ndb_mgm</command>,
- <command>ndb_mgmd</command>, and any <command>ndbd</command>
- processes to terminate gracefully. Any SQL nodes can be
- terminated using <command>mysqladmin shutdown</command> and
- other means. Note that the <option>-e</option> option here is
- used to pass a command to the <command>ndb_mgm</command> client
- from the shell. See <xref linkend="command-line-options"/>.
+ The <option>-e</option> option here is used to pass a command to
+ the <command>ndb_mgm</command> client from the shell. See
+ <xref linkend="command-line-options"/>. The command causes the
+ <command>ndb_mgm</command>, <command>ndb_mgmd</command>, and any
+ <command>ndbd</command> processes to terminate gracefully. Any
+ SQL nodes can be terminated using <command>mysqladmin
+ shutdown</command> and other means.
</para>
<para>
- To restart the cluster, simply run these commands:
+ To restart the cluster, run these commands:
</para>
<itemizedlist>
@@ -1692,7 +1692,7 @@
<listitem>
<para>
On the management host (<literal>192.168.0.10</literal> in
- our setup):
+ our example setup):
</para>
<programlisting>
@@ -1720,7 +1720,7 @@
<listitem>
<para>
- And on the SQL host (<literal>192.168.0.20</literal>):
+ On the SQL host (<literal>192.168.0.20</literal>):
</para>
<programlisting>
@@ -1730,6 +1730,11 @@
</itemizedlist>
+ <remark role="todo">
+ [pd] Hmm ... why are these three paragraphs _here_? (But where
+ would be more appropriate instead?)
+ </remark>
+
<para>
For information on making Cluster backups, see
<xref linkend="mysql-cluster-backup-using-management-server"/>.
@@ -1763,20 +1768,19 @@
</para>
<para>
- In order to avoid unnecessary allocation of resources, the server
- is configured by default with the <literal>NDB</literal> storage
- engine disabled. To enable <literal>NDB</literal>, you will need
- to modify the server's <filename>my.cnf</filename> configuration
- file, or start the server with the <option>--ndbcluster</option>
- option.
+ To avoid unnecessary allocation of resources, the server is
+ configured by default with the <literal>NDB</literal> storage
+ engine disabled. To enable <literal>NDB</literal>, you must modify
+ the server's <filename>my.cnf</filename> configuration file, or
+ start the server with the <option>--ndbcluster</option> option.
</para>
<para>
- The MySQL server is a part of the cluster, so it will also need to
- know how to access an MGM node to obtain the cluster configuration
+ The MySQL server is a part of the cluster, so it also must know
+ how to access an MGM node to obtain the cluster configuration
data. The default behavior is to look for the MGM node on
<literal>localhost</literal>. However, should you need to specify
- its location elsewhere, this can be done in
+ that its location is elsewhere, this can be done in
<filename>my.cnf</filename> or on the MySQL server command line.
Before the <literal>NDB</literal> storage engine can be used, at
least one MGM node must be operational, as well as any desired
@@ -1800,12 +1804,12 @@
<option>--with-ndbcluster</option> option when running
<command>configure</command>. You can also use the
<command>BUILD/compile-pentium-max</command> build script. Note
- that this script includes OpenSSL, so you must have or obtain
- OpenSSL to build successfully; otherwise you will need to modify
+ that this script includes OpenSSL, so you must either have or
+ obtain OpenSSL to build successfully, or else modify
<command>compile-pentium-max</command> to exclude this
requirement. Of course, you can also just follow the standard
- instructions for compiling your own binaries, then perform the
- usual tests and installation procedure. See
+ instructions for compiling your own binaries, and then perform
+ the usual tests and installation procedure. See
<xref linkend="installing-source-tree"/>.
</para>
@@ -1839,11 +1843,11 @@
<title>&title-mysql-cluster-quick;</title>
<para>
- In order to familiarize you with the basics, we will describe
- the simplest possible configuration for a functional MySQL
- Cluster. After this, you should be able to design your desired
- setup from the information provided in the other relevant
- sections of this chapter.
+ To familiarize you with the basics, we will describe the
+ simplest possible configuration for a functional MySQL Cluster.
+ After this, you should be able to design your desired setup from
+ the information provided in the other relevant sections of this
+ chapter.
</para>
<para>
@@ -1858,9 +1862,10 @@
<para>
In this directory, create a file named
- <filename>config.ini</filename> with the following information,
- substituting appropriate values for <literal>HostName</literal>
- and <literal>DataDir</literal> as necessary for your system.
+ <filename>config.ini</filename> that contains the following
+ information. Substitute appropriate values for
+ <literal>HostName</literal> and <literal>DataDir</literal> as
+ necessary for your system.
</para>
<programlisting>
@@ -1896,7 +1901,11 @@
</programlisting>
<para>
- You can now start the management server as follows:
+ You can now start the <command>ndb_mgmd</command> management
+ server. By default, it atttempts to read the
+ <filename>config.ini</filename> file in its current working
+ directory, so change location into the directory where the file
+ is located and then invoke <command>ndb_mgmd</command>:
</para>
<programlisting>
@@ -1917,7 +1926,7 @@
<para>
For subsequent <command>ndbd</command> starts, you will
- generally <emphasis role="bold">not</emphasis> want to use the
+ generally want to <emphasis>omit</emphasis> the
<option>--initial</option> option:
</para>
@@ -1926,11 +1935,14 @@
</programlisting>
<para>
- The reason for this is that the <option>--initial</option>
- option will delete all existing data and log files (as well as
- all table metadata) for this data node and create new ones. One
- exception to this rule is when restarting the cluster and
- restoring from backup after adding new data nodes.
+ The reason for omitting <option>--initial</option> on subsequent
+ restarts is that this option causes <command>ndbd</command> to
+ delete and re-create all existing data and log files (as well as
+ all table metadata) for this data node. One exception to this
+ rule about not using <option>--initial</option> except for the
+ first <command>ndbd</command> invocation is that you use it when
+ restarting the cluster and restoring from backup after adding
+ new data nodes.
</para>
<remark role="todo">
@@ -1938,7 +1950,7 @@
</remark>
<para>
- By default, <command>ndbd</command> will look for the management
+ By default, <command>ndbd</command> looks for the management
server at <literal>localhost</literal> on port 1186.
</para>
@@ -1951,7 +1963,7 @@
</para>
<para>
- Finally, go to the MySQL data directory (usually
+ Finally, change location to the MySQL data directory (usually
<filename>/var/lib/mysql</filename> or
<filename>/usr/local/mysql/data</filename>), and make sure that
the <filename>my.cnf</filename> file contains the option
@@ -1980,7 +1992,8 @@
<para>
If all has gone well so far, you now can start using the
- cluster:
+ cluster. Connect to the server and verify that the
+ <literal>NDBCLUSTER</literal> storage engine is enabled:
</para>
<programlisting>
@@ -1991,7 +2004,6 @@
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> <userinput>SHOW ENGINES\G</userinput>
-
...
*************************** 12. row ***************************
Engine: NDBCLUSTER
@@ -2005,18 +2017,17 @@
</programlisting>
<para>
- (Note that the row numbers shown in the preceding example output
- may be different from those shown on your system, depending upon
- the MySQL version being used and how it is configured.)
+ The row numbers shown in the preceding example output may be
+ different from those shown on your system, depending upon how
+ your server is configured.
</para>
+ <para>
+ Try to create an <literal>NDBCLUSTER</literal> table:
+ </para>
+
<programlisting>
shell> <userinput>mysql</userinput>
-Welcome to the MySQL monitor. Commands end with ; or \g.
-Your MySQL connection id is 1 to server version: ¤t-version;-Max
-
-Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
-
mysql> <userinput>USE test;</userinput>
Database changed
@@ -2034,7 +2045,7 @@
<para>
To check that your nodes were set up properly, start the
- management client as shown:
+ management client:
</para>
<programlisting>
@@ -2042,9 +2053,8 @@
</programlisting>
<para>
- You can then use the <command>SHOW</command> statement from
- within the management client to obtain a report on the cluster's
- status:
+ Use the <command>SHOW</command> command from within the
+ management client to obtain a report on the cluster's status:
</para>
<programlisting>
@@ -2095,7 +2105,7 @@
<para>
<filename>config.ini</filename>: This file is read only by
the MySQL Cluster management server, which then distributes
- the information contained in this file to all processes
+ the information contained therein to all processes
participating in the cluster.
<filename>config.ini</filename> contains a description of
each node involved in the cluster. This includes
@@ -2112,10 +2122,9 @@
maintain backward compatibility, there may be times when
introduce an incompatible change. In such cases we will try to
let Cluster users know in advance if a change is not backward
- compatible. If you find such a change which we have not
- documented, please use our
- <ulink url="http://bugs.mysql.com/">Bugs Database</ulink> to
- report it.
+ compatible. If you find such a change and we have not documented
+ it, please report it in the MySQL bugs database using the
+ instructions given in <xref linkend="bug-reports"/>.
</para>
<section id="mysql-cluster-config-example">
@@ -2123,12 +2132,12 @@
<title>&title-mysql-cluster-config-example;</title>
<para>
- In order to support MySQL Cluster, you will need to update
+ To support MySQL Cluster, you will need to update
<filename>my.cnf</filename> as shown in the following example.
Note that the options shown here should not be confused with
- those occurring in <filename>config.ini</filename> files. You
- may also specify these parameters when invoking the
- executables from the command line.
+ those that are used in <filename>config.ini</filename> files.
+ You may also specify these parameters on the command line when
+ invoking the executables.
</para>
<programlisting>
@@ -2175,8 +2184,8 @@
<para>
You may also use a separate <literal>[mysql_cluster]</literal>
- section in the cluster <filename>my.cnf</filename> for
- settings to be read by and affecting all executables:
+ section in the cluster <filename>my.cnf</filename> file for
+ settings to be read and used by all executables:
</para>
<programlisting>
@@ -2190,44 +2199,48 @@
</remark>
<para>
- Currently, the configuration file is in INI format, and is
- named <filename>config.ini</filename> by default. It is read
- by <command>ndb_mgmd</command> at startup and can be placed
+ The configuration file is named
+ <filename>config.ini</filename> by default. It is read by
+ <command>ndb_mgmd</command> at startup and can be placed
anywhere. Its location and name are specified by using
- <option>--config-file=[<replaceable><path></replaceable>]<replaceable><filename></replaceable></option>
- on the command line with <command>ndb_mgmd</command>. If the
+ <option>--config-file=<replaceable>path_name</replaceable></option>
+ on the <command>ndb_mgmd</command> command line. If the
configuration file is not specified,
- <command>ndb_mgmd</command> by default tries to read a
- <filename>config.ini</filename> file located in the current
+ <command>ndb_mgmd</command> by default tries to read a file
+ named <filename>config.ini</filename> located in the current
working directory.
</para>
<para>
+ Currently, the configuration file is in INI format, which
+ consists of sections preceded by section headings (surrounded
+ by square brackets), followed by the appropriate parameter
+ names and values. One deviation from the standard INI format
+ is that the parameter name and value can be separated by a
+ colon (‘<literal>:</literal>’) as well as the
+ equals sign (‘<literal>=</literal>’). Another
+ deviation is that sections are not uniquely identified by
+ section name. Instead, unique sections (such as two different
+ nodes of the same type) are identified by a unique ID
+ specified as a parameter within the section.
+ </para>
+
+ <para>
Default values are defined for most parameters, and can also
be specified in <filename>config.ini</filename>. To create a
default value section, simply add the word
<literal>DEFAULT</literal> to the section name. For example,
- data nodes are configured using <literal>[NDBD]</literal>
- sections. If all data nodes use the same data memory size, and
- this is not the same as the default size, create an
- <literal>[NDBD DEFAULT]</literal> section containing a
- <literal>DataMemory</literal> line to specify the default data
- memory size for all data nodes.
+ an <literal>[NDBD]</literal> section contains parameters that
+ apply to a particular data node, whereas an <literal>[NDBD
+ DEFAULT]</literal> section contains parameters that apply to
+ all data nodes. Suppose that all data nodes should use the
+ same data memory size. To configure them all, create an
+ <literal>[NDBD DEFAULT]</literal> section that contains a
+ <literal>DataMemory</literal> line to specify the data memory
+ size.
</para>
<para>
- The INI format consists of sections preceded by section
- headings (surrounded by square brackets), followed by the
- appropriate parameter names and values. One deviation from the
- standard format is that the parameter name and value can be
- separated by a colon (‘<literal>:</literal>’) as
- well as the equals sign (‘<literal>=</literal>’);
- another is that sections are not uniquely identified by name.
- Instead, unique entries (such as two different nodes of the
- same type) are identified by a unique ID.
- </para>
-
- <para>
At a minimum, the configuration file must define the computers
and nodes involved in the cluster and on which computers these
nodes are located. An example of a simple configuration file
@@ -2237,10 +2250,10 @@
<programlisting>
# file "config.ini" - 2 data nodes and 2 SQL nodes
-# This file is placed in the startup directory of ndb_mgmd (the management
-# server)
-# The first MySQL Server can be started from any host. The second can be started
-# only on the host mysqld_5.mysql.com
+# This file is placed in the startup directory of ndb_mgmd (the
+# management server)
+# The first MySQL Server can be started from any host. The second
+# can be started only on the host mysqld_5.mysql.com
[NDBD DEFAULT]
NoOfReplicas= 2
@@ -2835,8 +2848,8 @@
specifying <literal>ExecuteOnComputer</literal>. It
defines the hostname of the computer the storage node on
which is to reside. Either this parameter or
- <literal>ExecuteOnComputer</literal> is required in order
- to specify a hostname other than
+ <literal>ExecuteOnComputer</literal> is required to
+ specify a hostname other than
<literal>localhost</literal>.
</para>
</listitem>
@@ -2933,8 +2946,8 @@
includes <filename>/var/lib/mysql-cluster</filename>,
under which a directory for the node's filesystem is
created. This subdirectory contains the node ID. For
- example, if the node ID is 2, then this subdirectory is
- named <filename>ndb_2_fs</filename>.
+ example, if the node ID is 2, this subdirectory is named
+ <filename>ndb_2_fs</filename>.
</para>
</listitem>
@@ -3175,9 +3188,9 @@
database size is the sum of all data memory and all index
memory for each node group. Each node group is used to
store replicated information, so if there are four nodes
- with 2 replicas, then there will be two node groups. Thus,
- the total data memory available is
- 2*<literal>DataMemory</literal> for each data node.
+ with two replicas, there will be two node groups. Thus,
+ the total data memory available is 2 ×
+ <literal>DataMemory</literal> for each data node.
</para>
<para>
@@ -3199,9 +3212,9 @@
memory space. Increasing these values should be
acceptable, but it is recommended that such upgrades are
performed in the same manner as a software upgrade,
- beginning with an update of the configuration file, then
- restarting the management server followed by restarting
- each data node in turn.
+ beginning with an update of the configuration file, and
+ then restarting the management server followed by
+ restarting each data node in turn.
</para>
<para>
@@ -3360,11 +3373,11 @@
involved in the transaction. However, the operation
records of the are spread over all 8 nodes. Thus, if it is
necessary to configure the system for one very large
- transaction, then it is a good idea to configure the two
- parts separately.
- <literal>MaxNoOfConcurrentOperations</literal> will always
- be used to calculate the number of operation records in
- the transaction coordinator portion of the node.
+ transaction, it is a good idea to configure the two parts
+ separately. <literal>MaxNoOfConcurrentOperations</literal>
+ will always be used to calculate the number of operation
+ records in the transaction coordinator portion of the
+ node.
</para>
<para>
@@ -3380,13 +3393,13 @@
</para>
<para>
- By default, this parameter is calculated as 1.1 *
+ By default, this parameter is calculated as 1.1 ×
<literal>MaxNoOfConcurrentOperations</literal> which fits
systems with many simultaneous transactions, none of them
being very large. If there is a need to handle one very
- large transaction at a time and there are many nodes, then
- it is a good idea to override the default value by
- explicitly specifying this parameter.
+ large transaction at a time and there are many nodes, it
+ is a good idea to override the default value by explicitly
+ specifying this parameter.
</para>
</listitem>
@@ -3682,7 +3695,7 @@
<para>
If the checkpointing is slow and there are so many writes
to the database that the log files are full and the log
- tail cannot be cut without jeopardizing recovery, then all
+ tail cannot be cut without jeopardizing recovery, all
updating transactions will be aborted with internal error
code 410, or <literal>Out of log file space
temporarily</literal>. This condition will prevail until a
@@ -3770,16 +3783,16 @@
<para>
When setting <literal>MaxNoOfAttributes</literal>, it is
important to prepare in advance for any <literal>ALTER
- TABLE</literal> statements that you might wish to perform
+ TABLE</literal> statements that you might want to perform
in future. This is due to the fact, during the execution
of <literal>ALTER TABLE</literal> on a Cluster table, 3
times the number of attributes as in the original table
are used. For example, if a table requires 100 attributes,
- and you wish to be able to alter it later, then you need
- to set the value of <literal>MaxNoOfAttributes</literal>
- to 300. A good rule of thumb is that, if you can create
- all desired tables without any problems, then add 2 times
- the number of attributes in the largest table to
+ and you want to be able to alter it later, you need to set
+ the value of <literal>MaxNoOfAttributes</literal> to 300.
+ A good rule of thumb is that, if you can create all
+ desired tables without any problems, add 2 times the
+ number of attributes in the largest table to
<literal>MaxNoOfAttributes</literal> to be sure. You
should also verify that this number is sufficient by
trying an actual <literal>ALTER TABLE</literal> after
@@ -4095,7 +4108,7 @@
<para>
If a data node has not completed its startup sequence
- within the time specified by this parameter, then the node
+ within the time specified by this parameter, the node
startup will fail. Setting this parameter to
<literal>0</literal> means that no data node timeout is
applied.
@@ -4244,8 +4257,8 @@
Timeout handling is performed by checking a timer on each
transaction once for every interval specified by this
parameter. Thus, if this parameter is set to 1000
- milliseconds, then every transaction will be checked for
- timing out once per second.
+ milliseconds, every transaction will be checked for timing
+ out once per second.
</para>
<para>
@@ -4447,7 +4460,7 @@
<para>
This parameter specifies the time that the data node will
wait for a response from the arbitrator to an arbitration
- message. If this is exceeded, then it is assumed that the
+ message. If this is exceeded, it is assumed that the
network has split.
</para>
@@ -4473,10 +4486,10 @@
<para>
These buffers are used as front ends to the file system when
writing log records to disk. If the node is running in
- diskless mode, then these parameters can be set to their
- minimum values without penalty due to the fact that disk
- writes are <quote>faked</quote> by the <literal>NDB</literal>
- storage engine's filesystem abstraction layer.
+ diskless mode, these parameters can be set to their minimum
+ values without penalty due to the fact that disk writes are
+ <quote>faked</quote> by the <literal>NDB</literal> storage
+ engine's filesystem abstraction layer.
</para>
<itemizedlist>
@@ -4490,7 +4503,7 @@
This buffer is used during local checkpoints. The
<literal>NDB</literal> storage engine uses a recovery
scheme based on checkpoint consistency in conjunction with
- an operational REDO log. In order to produce a consistent
+ an operational REDO log. To produce a consistent
checkpoint without blocking the entire system for writes,
UNDO logging is done while performing the local
checkpoint. UNDO logging is activated on a single table
@@ -4554,7 +4567,7 @@
<para>
It is rarely necessary to increase the size of this
- buffer. If there is such a need, then it is a good idea to
+ buffer. If there is such a need, it is a good idea to
check whether the disks can actually handle the load
caused by database update activity. A lack of sufficient
disk space cannot be overcome by increasing the size of
@@ -4869,7 +4882,7 @@
<filename>config.ini</filename> file define the behavior of
the MySQL servers (SQL nodes) used to access cluster data.
None of the parameters shown is required. If no computer or
- host name is provided, then any host can use this SQL node.
+ host name is provided, any host can use this SQL node.
</para>
<itemizedlist>
@@ -4985,10 +4998,10 @@
<para>
The batch size is the size of each batch sent from each
- data node. Most scans are performed in parallel in order
- to protect the MySQL Server from receiving too much data
- from many nodes in parallel; this parameter sets a limit
- to the total batch size over all nodes.
+ data node. Most scans are performed in parallel to protect
+ the MySQL Server from receiving too much data from many
+ nodes in parallel; this parameter sets a limit to the
+ total batch size over all nodes.
</para>
<para>
@@ -5070,11 +5083,10 @@
</para>
<para>
- In order to be able to retrace a distributed message
- diagram it is necessary to identify each message. When
- this parameter is set to <literal>Y</literal>, message IDs
- are transported over the network. This feature is disabled
- by default.
+ To be able to retrace a distributed message diagram it is
+ necessary to identify each message. When this parameter is
+ set to <literal>Y</literal>, message IDs are transported
+ over the network. This feature is disabled by default.
</para>
</listitem>
@@ -5270,8 +5282,8 @@
</para>
<para>
- In order to retrace the path of a distributed message, it
- is necessary to provide each message with a unique
+ To retrace the path of a distributed message, it is
+ necessary to provide each message with a unique
identifier. Setting this parameter to <literal>Y</literal>
causes these message IDs to be transported over the
network as well. This feature is disabled by default.
@@ -5433,10 +5445,10 @@
</para>
<para>
- In order to trace a distributed message it is necessary to
- identify each message uniquely. When this parameter is set
- to <literal>Y</literal>, message IDs are transported over
- the network. This feature is disabled by default.
+ To trace a distributed message it is necessary to identify
+ each message uniquely. When this parameter is set to
+ <literal>Y</literal>, message IDs are transported over the
+ network. This feature is disabled by default.
</para>
</listitem>
@@ -5539,33 +5551,33 @@
in this row (or if there is no such row displayed in the
output), you are not running an <literal>NDB</literal>-enabled
version of MySQL. If you see <literal>DISABLED</literal> in this
- row, then you need to enable it in either one of the two ways
- just described.
+ row, you need to enable it in either one of the two ways just
+ described.
</para>
<para>
- In order to read cluster configuration data, the MySQL server
- requires at a minimum 3 pieces of information:
+ To read cluster configuration data, the MySQL server requires at
+ a minimum three pieces of information:
</para>
<itemizedlist>
<listitem>
<para>
- The MySQL server's own cluster node ID.
+ The MySQL server's own cluster node ID
</para>
</listitem>
<listitem>
<para>
The hostname or IP address for the management server (MGM
- node).
+ node)
</para>
</listitem>
<listitem>
<para>
- The port on which it can connect to the management server.
+ The port on which it can connect to the management server
</para>
</listitem>
@@ -6229,16 +6241,16 @@
<para>
Instructs the management server as to which file it should
use for its configuration file. This option must be
- specified. The file name defaults to
- <literal>config.ini</literal>.
+ specified. The filename defaults to
+ <filename>config.ini</filename>.
</para>
<para>
<emphasis role="bold">Note</emphasis>: This option also
can be given as <option>-c
- <filename>file_name</filename></option>, but this shortcut
- is obsolete and should <emphasis>not</emphasis> be used in
- new installations.
+ <replaceable>file_name</replaceable></option>, but this
+ shortcut is obsolete and should <emphasis>not</emphasis>
+ be used in new installations.
</para>
</listitem>
@@ -6298,8 +6310,8 @@
</para>
<para>
- If the connection to the management server is broken, then
- the node tries to reconnect to it every 5 seconds until it
+ If the connection to the management server is broken, the
+ node tries to reconnect to it every 5 seconds until it
succeeds. By using this option, it is possible to limit
the number of attempts to
<replaceable>number</replaceable> before giving up and
@@ -6476,7 +6488,7 @@
</para>
<para>
- If this is a system restart, then the cluster determines the
+ If this is a system restart, the cluster determines the
latest restorable global checkpoint.
</para>
</listitem>
@@ -7078,10 +7090,10 @@
<para>
Event severity levels can be turned on or off. If a severity
- level is turned on, then all events with a priority less than
- or equal to the category thresholds are logged. If the
- severity level is turned off then no events belonging to that
- severity level are logged.
+ level is turned on, all events with a priority less than or
+ equal to the category thresholds are logged. If the severity
+ level is turned off then no events belonging to that severity
+ level are logged.
</para>
<remark role="todo">
@@ -8277,13 +8289,14 @@
-->
<!--
-
- <section id="mysql-cluster-replication">
+
+ <section id="mysql-cluster-replication">
+
<title>&title-mysql-cluster-replication;</title>
-
+
<para>
Previous to MySQL 5.1, <firstterm>asynchronous
- replication</firstterm>, more usually referred to simply as
+ replication</firstterm>, more usually referred to simply as
<quote>replication,</quote> was not available when using MySQL
Cluster. This section explains how to set up and manage a
configuration wherein one group of computers operating as a MySQL
@@ -8292,77 +8305,75 @@
MySQL replication as discussed elsewhere in this Manual. (See
<xref linkend="replication"/>).
</para>
-
+
<para>
- Normal (non-clustered) replication involves a <quote>master</quote>
- server and a <quote>slave</quote> server, the master being the
- source of the operations and data to be replicated and the slave
- being the recipient of these. In MySQL Cluster, replication is
- conceptually very similar but can be more complex in practise, as it
- may be extended to cover a number of different configurations
- including replicating between two complete clusters. Although a MySQL
- Cluster itself depends on the <literal>NDB Cluster</literal> storage
- engine for clustering functionality, it is not necessary to use the
- Cluster storage engine on the slave. However, for maximum
- availability, it is possible to replicate from one MySQL Cluster to
- another, and it is this type of configuration that we discuss, as
- shown in the following figure:
- </para>
-
+ Normal (non-clustered) replication involves a
+ <quote>master</quote> server and a <quote>slave</quote> server,
+ the master being the source of the operations and data to be
+ replicated and the slave being the recipient of these. In MySQL
+ Cluster, replication is conceptually very similar but can be more
+ complex in practise, as it may be extended to cover a number of
+ different configurations including replicating between two
+ complete clusters. Although a MySQL Cluster itself depends on the
+ <literal>NDB Cluster</literal> storage engine for clustering
+ functionality, it is not necessary to use the Cluster storage
+ engine on the slave. However, for maximum availability, it is
+ possible to replicate from one MySQL Cluster to another, and it is
+ this type of configuration that we discuss, as shown in the
+ following figure:
+ </para>
+
<mediaobject>
<imageobject>
<imagedata fileref="images/cluster-replication-overview.png" format="PNG"/>
</imageobject>
<textobject>
<phrase lang="en">MySQL Cluster-to-Cluster Replication
- Layout</phrase>
+ Layout</phrase>
</textobject>
</mediaobject>
-
+
<para>
- In this scenario the replication process is one in which successive
- states of a master cluster are logged and saved to a slave cluster.
- This process is accomplished by a special thread known as the NDB
- binlog injector thread, which runs on each MySQL server and produces
- a binary log (<literal>binlog</literal>). This thread ensures that
- all changes in the cluster producing the binary log — and not
- just those changes that are effected via the MySQL Server —
- are inserted into the binary log with the correct serialization
- order. We refer to the MySQL replication master and replication
- slave servers as replication servers or replication nodes, and the
- data flow or line of communication between them as a
- <firstterm>replication channel</firstterm>.
+ In this scenario the replication process is one in which
+ successive states of a master cluster are logged and saved to a
+ slave cluster. This process is accomplished by a special thread
+ known as the NDB binlog injector thread, which runs on each MySQL
+ server and produces a binary log (<literal>binlog</literal>). This
+ thread ensures that all changes in the cluster producing the
+ binary log — and not just those changes that are effected
+ via the MySQL Server — are inserted into the binary log with
+ the correct serialization order. We refer to the MySQL replication
+ master and replication slave servers as replication servers or
+ replication nodes, and the data flow or line of communication
+ between them as a <firstterm>replication channel</firstterm>.
</para>
-
+
<section id="mysql-cluster-replication-abbreviations">
+
<title>&title-mysql-cluster-replication-abbreviations;</title>
-
+
<para>
Throughout this section, we use the following abbreviations or
symbols for referring to the master and slave clusters, and to
processes and commands run on the clusters or cluster nodes:
</para>
-
- <informaltable>
+
+ <informaltable>
<tgroup cols="2">
<colspec colwidth="25*"/>
<colspec colwidth="75*"/>
<tbody>
<row>
- <entry><emphasis role="bold">Symbol or
- Abbreviation</emphasis></entry>
- <entry><emphasis role="bold">Description (Refers
- to...)</emphasis></entry>
+ <entry><emphasis role="bold">Symbol or Abbreviation</emphasis></entry>
+ <entry><emphasis role="bold">Description (Refers to...)</emphasis></entry>
</row>
<row>
<entry><replaceable>M</replaceable></entry>
- <entry>The cluster serving as the (primary) replication
- master</entry>
+ <entry>The cluster serving as the (primary) replication master</entry>
</row>
<row>
<entry><replaceable>S</replaceable></entry>
- <entry>The cluster acting as the (primary) replication
- slave</entry>
+ <entry>The cluster acting as the (primary) replication slave</entry>
</row>
<row>
<entry><literal>shell<replaceable>M</replaceable>></literal></entry>
@@ -8370,13 +8381,13 @@
</row>
<row>
<entry><literal>mysql<replaceable>M</replaceable>></literal></entry>
- <entry>MySQL client command issued on a single MySQL server
- running as an SQL node on the master cluster</entry>
+ <entry>MySQL client command issued on a single MySQL server running as an SQL
+ node on the master cluster</entry>
</row>
<row>
<entry><literal>mysql<replaceable>M*</replaceable>></literal></entry>
- <entry>MySQL client command to be issued on all SQL nodes
- participating in the replication master cluster</entry>
+ <entry>MySQL client command to be issued on all SQL nodes participating in the
+ replication master cluster</entry>
</row>
<row>
<entry><literal>shell<replaceable>S</replaceable>></literal></entry>
@@ -8384,13 +8395,13 @@
</row>
<row>
<entry><literal>mysql<replaceable>S</replaceable>></literal></entry>
- <entry>MySQL client command issued on a single MySQL server
- running as an SQL node on the slave cluster</entry>
+ <entry>MySQL client command issued on a single MySQL server running as an SQL
+ node on the slave cluster</entry>
</row>
<row>
<entry><literal>mysql<replaceable>S*</replaceable>></literal></entry>
- <entry>MySQL client command to be issued on all SQL nodes
- participating in the replication slave cluster</entry>
+ <entry>MySQL client command to be issued on all SQL nodes participating in the
+ replication slave cluster</entry>
</row>
<row>
<entry><replaceable>C</replaceable></entry>
@@ -8409,129 +8420,136 @@
<entry>Secondary replication slave</entry>
</row>
</tbody>
- </tgroup>
+ </tgroup>
</informaltable>
-
+
</section>
-
+
<section id="mysql-cluster-replication-general">
+
<title>&title-mysql-cluster-replication-general;</title>
-
+
<para>
A replication channel requires two MySQL servers acting as
replication servers (one each for the master and slave). For
example, this means that in the case of a replication setup with
two replication channels (to provide an extra channel for
- redundancy), there will be a total of four replication nodes, two
- per cluster.
+ redundancy), there will be a total of four replication nodes,
+ two per cluster.
</para>
-
+
<para>
Each MySQL server used for replication in either cluster must be
uniquely identified among all the MySQL replication servers
participating in either cluster (you cannot have replication
servers on both the master and slave clusters sharing the same
ID). This can be done by starting each SQL node using the
- <option>&ddash;server-id=<replaceable>id</replaceable></option> option,
- where <replaceable>id</replaceable> is a unique integer. Although it is
- not strictly necessary, we will assume for purposes of this
- discussion that all MySQL installations are the same version.
+ <option>&ddash;server-id=<replaceable>id</replaceable></option>
+ option, where <replaceable>id</replaceable> is a unique integer.
+ Although it is not strictly necessary, we will assume for
+ purposes of this discussion that all MySQL installations are the
+ same version.
</para>
-
+
<para>
In any event, servers involved in replication must be compatible
with one another with respect to both the version of the
replication protocol used and the SQL feature sets which they
support; the simplest and easiest way to assure that this is the
case is to use the same MySQL version for all servers involved.
- Note that in many cases it is not possible to replicate to a slave
- running a version of MySQL with a lower version number than that
- of the master — see
+ Note that in many cases it is not possible to replicate to a
+ slave running a version of MySQL with a lower version number
+ than that of the master — see
<xref linkend="replication-compatibility"/>, for details.
</para>
-
+
<para>
We assume that the slave server or cluster is dedicated to
- replication of the master, and that no other data is being stored
- on it.
+ replication of the master, and that no other data is being
+ stored on it.
</para>
-
+
</section>
-
-
+
<section id="mysql-cluster-replication-issues">
+
<title>&title-mysql-cluster-replication-issues;</title>
-
+
<para>
- The following are known problems or issues when using replication
- with MySQL Cluster in MySQL 5.1:
+ The following are known problems or issues when using
+ replication with MySQL Cluster in MySQL 5.1:
</para>
-
+
<itemizedlist>
+
<listitem>
<para>
- The use of data definition statements, such as <literal>CREATE
- TABLE</literal>, <literal>DROP TABLE</literal>, and
- <literal>ALTER TABLE</literal>, are recorded in the binary
- log for only the MySQL server on which they are issued.
+ The use of data definition statements, such as
+ <literal>CREATE TABLE</literal>, <literal>DROP
+ TABLE</literal>, and <literal>ALTER TABLE</literal>, are
+ recorded in the binary log for only the MySQL server on
+ which they are issued.
</para>
</listitem>
-
+
<listitem>
<para>
A MySQL server involved in replication should be started or
- restarted after using <command>ndb_restore</command> in order
- to discover and setup replication of <literal>NDB
- Cluster</literal> tables. Alternatively, you can issue a
- <literal>SHOW TABLES</literal> statement on all databases in the
- cluster.
+ restarted after using <command>ndb_restore</command> to
+ discover and setup replication of <literal>NDB
+ Cluster</literal> tables. Alternatively, you can issue a
+ <literal>SHOW TABLES</literal> statement on all databases in
+ the cluster.
</para>
-
+
<para>
Similarly, when using <literal>CREATE SCHEMA</literal>, the
new database is not automatically discoverable by the MySQL
server. Thus, this statement must be issued on each MySQL
server participating in the cluster when creating a new
- database.
+ database.
</para>
</listitem>
-
+
<listitem>
<para>
- Restarting the cluster with the <option>&ddash;initial</option>
- option will cause the sequence of GCI and epoch numbers to
- start over from <literal>0</literal>. (This is generally true
- of MySQL Cluster and not limited to replication scenarios
- involving Cluster.) The MySQL servers involved in replication
- should in this case be replicated. After this, you should use
- the <literal>RESET MASTER</literal> and <literal>RESET
- SLAVE</literal> statements to clear the invalid
+ Restarting the cluster with the
+ <option>&ddash;initial</option> option will cause the
+ sequence of GCI and epoch numbers to start over from
+ <literal>0</literal>. (This is generally true of MySQL
+ Cluster and not limited to replication scenarios involving
+ Cluster.) The MySQL servers involved in replication should
+ in this case be replicated. After this, you should use the
+ <literal>RESET MASTER</literal> and <literal>RESET
+ SLAVE</literal> statements to clear the invalid
<literal>binlog_index</literal> and
<literal>apply_status</literal> tables. respectively.
</para>
</listitem>
-
+
</itemizedlist>
-
+
<para>
- See <xref linkend="mysql-cluster-replication-schema-discovery"/>,
+ See
+ <xref linkend="mysql-cluster-replication-schema-discovery"/>,
for more information about the first two items listed above, as
well as some examples illustrating how to handle applicable
situations.
</para>
-
+
</section>
-
+
<section id="mysql-cluster-replication-schema">
+
<title>&title-mysql-cluster-replication-schema;</title>
-
+
<para>
Replication in MySQL Cluster makes use of a number of dedicated
tables in a separate <literal>cluster_replication</literal>
database on each MySQL Server instance acting as an SQL node in
both the cluster being replicated and the replication slave
(whether the slave is a single server or a cluster). This
- database, which is created during the MySQL installation process
+ database, which is created during the MySQL installation process
by the <command>mysql_install_db</command> script, contains a
table for storing the binary log's indexing data. As the
binlog_index table is local to each MySQL server and does not
@@ -8540,7 +8558,7 @@
<command>mysqld</command> participating in the master cluster.
This table is defined as follows:
</para>
-
+
<programlisting>
CREATE TABLE `binlog_index` (
`Position` BIGINT(20) UNSIGNED NOT NULL,
@@ -8553,35 +8571,35 @@
PRIMARY KEY (`epoch`)
) ENGINE=MYISAM DEFAULT CHARSET=latin1;
</programlisting>
-
+
<para>
In the following figure, the relationship of the MySQL Cluster
replication master server, its binlog injector thread, and the
<literal>cluster_replication.binlog_index</literal> table are
shown.
</para>
-
+
<mediaobject>
<imageobject>
<imagedata fileref="images/cluster-replication-binlog-injector.png" format="PNG"/>
</imageobject>
<textobject>
<phrase lang="en">The replication master cluster, the
- binlog-injector thread, and the
- <literal>binlog_index</literal> table</phrase>
+ binlog-injector thread, and the
+ <literal>binlog_index</literal> table</phrase>
</textobject>
</mediaobject>
-
+
<para>
An additional table, named <literal>apply_status</literal>, is
- used to keep a record of the operations which have been replicated
- from the master to the slave. Unlike the case with
+ used to keep a record of the operations which have been
+ replicated from the master to the slave. Unlike the case with
<literal>binlog_index</literal>, the data in this table is not
- specific to any one SQL node in the (slave) cluster, and so
+ specific to any one SQL node in the (slave) cluster, and so
<literal>apply_status</literal> can use the <literal>NDB
- Cluster</literal> storage engine, as shown here:
+ Cluster</literal> storage engine, as shown here:
</para>
-
+
<programlisting>
CREATE TABLE `apply_status` (
`server_id` INT(10) UNSIGNED NOT NULL,
@@ -8589,7 +8607,7 @@
PRIMARY KEY USING HASH (`server_id`)
) ENGINE=NDBCLUSTER DEFAULT CHARSET=latin1;
</programlisting>
-
+
<para>
These tables are created in a separate database because they
should not be replicated. No user intervention is normally
@@ -8600,89 +8618,94 @@
process updated to changes performed by the NDB storage engine.
The NDB <firstterm>binlog injector thread</firstterm> receives
events directly from the NDB storage engine. The NDB injector is
- responsible for capturing all the data events within the cluster,
- and ensures that all events changing, inserting, or deleting data
- are recorded in the <literal>binlog_index</literal> table. The
- slave I/O thread will transfer the from the master's binary log to the slave's relay log.
+ responsible for capturing all the data events within the
+ cluster, and ensures that all events changing, inserting, or
+ deleting data are recorded in the
+ <literal>binlog_index</literal> table. The slave I/O thread will
+ transfer the from the master's binary log to the slave's relay
+ log.
</para>
-
+
<para>
- However, it is advisable to check for the existence and integrity
- of these tables as an initial step in preparing a MySQL Cluster
- for replication. It is possible to view event data recorded in the
- binary log by querying the
- <literal>cluster_replication.binlog_index</literal> table directly
- on the master. This can be also be accomplished using the
- <literal>SHOW BINLOG EVENTS</literal> statement on either the
- replication master or slave MySQL servers.
+ However, it is advisable to check for the existence and
+ integrity of these tables as an initial step in preparing a
+ MySQL Cluster for replication. It is possible to view event data
+ recorded in the binary log by querying the
+ <literal>cluster_replication.binlog_index</literal> table
+ directly on the master. This can be also be accomplished using
+ the <literal>SHOW BINLOG EVENTS</literal> statement on either
+ the replication master or slave MySQL servers.
</para>
-
+
</section>
-
+
<section id="mysql-cluster-replication-preparation">
+
<title>&title-mysql-cluster-replication-preparation;</title>
-
+
<para>
Preparing the MySQL Cluster for replication consists of the
following steps:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Check all MySQL servers for version compatibility (see
<xref linkend="mysql-cluster-replication-general"/>).
</para>
</listitem>
-
+
<listitem>
<para>
Create a slave account on the master Cluster with the
appropriate privileges:
</para>
-
+
<programlisting>
mysql<replaceable>M</replaceable>> <userinput>GRANT REPLICATION SLAVE</userinput>
-> <userinput>ON *.* TO '<replaceable>slave-user</replaceable>'@'<replaceable>slave-host</replaceable>'</userinput>
-> <userinput>IDENTIFIED BY '<replaceable>slave-password</replaceable>';</userinput>
</programlisting>
-
+
<para>
where <replaceable>slave-user</replaceable> is the slave
- account username, <replaceable>slave-host</replaceable> is the
- hostname or IP address of the replication slave, and
- <replaceable>slave-password</replaceable> is the password that
- you wish to assign to this account.
+ account username, <replaceable>slave-host</replaceable> is
+ the hostname or IP address of the replication slave, and
+ <replaceable>slave-password</replaceable> is the password to
+ assign to this account.
</para>
-
+
<para>
For example, to create a slave user account with the name
- <quote><literal>myslave</literal>,</quote> logging in from the
- host named <quote><literal>rep-slave</literal>,</quote> and
- using the password <quote><literal>53cr37</literal>,</quote>
- you would use the following <literal>GRANT</literal> statement:
+ <quote><literal>myslave</literal>,</quote> logging in from
+ the host named <quote><literal>rep-slave</literal>,</quote>
+ and using the password
+ <quote><literal>53cr37</literal>,</quote> you would use the
+ following <literal>GRANT</literal> statement:
</para>
-
+
<programlisting>
mysql<replaceable>M</replaceable>> <userinput>GRANT REPLICATION SLAVE</userinput>
-> <userinput>ON *.* TO 'myslave'@'rep-slave'</userinput>
-> <userinput>IDENTIFIED BY '53cr37';</userinput>
</programlisting>
-
+
<para>
For security reasons, it is preferable to use a unique user
- account — not employed for any other purpose — for
- the replication slave account.
+ account — not employed for any other purpose —
+ for the replication slave account.
</para>
</listitem>
-
+
<listitem>
<para>
Configure the slave to use the master. Using the MySQL
Monitor, this can be accomplished with the <literal>CHANGE
- MASTER TO</literal> statement:
+ MASTER TO</literal> statement:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>CHANGE MASTER TO</userinput>
-> <userinput>MASTER_HOST='<replaceable>master-host</replaceable>',</userinput>
@@ -8690,7 +8713,7 @@
-> <userinput>MASTER_USER='<replaceable>slave-user</replaceable>',</userinput>
-> <userinput>MASTER_PASSWORD='<replaceable>slave-password</replaceable>';</userinput>
</programlisting>
-
+
<para>
where <replaceable>master-host</replaceable> is the hostname
or IP address of the replication master,
@@ -8698,10 +8721,10 @@
slave to use for connecting to the master,
<replaceable>slave-user</replaceable> is the username set up
for the slave on the master, and
- <replaceable>slave-password</replaceable> is the password set
- for that user account in the previous step.
+ <replaceable>slave-password</replaceable> is the password
+ set for that user account in the previous step.
</para>
-
+
<para>
For example, to tell the slave to replicate from the MySQL
server whose hostname is
@@ -8709,7 +8732,7 @@
replication slave account created in the previous step, you
would use the following statement:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>CHANGE MASTER TO</userinput>
-> <userinput>MASTER_HOST='rep-master'</userinput>
@@ -8717,22 +8740,22 @@
-> <userinput>MASTER_USER='myslave'</userinput>
-> <userinput>MASTER_PASSWORD='53cr37';</userinput>
</programlisting>
-
+
<para>
(For a complete list of clauses that can be used with this
statement, see <xref linkend="change-master-to"/>.)
</para>
-
+
<para>
- You can also configure the slave to use the master by setting
- the corresponding startup options in the slave server's
- <filename>my.cnf</filename> file. To configure the slave in
- the same way as the preceding example <literal>CHANGE MASTER
- TO</literal> statement, the following information would
- need to be included in the slave's <filename>my.cnf</filename>
- file:
+ You can also configure the slave to use the master by
+ setting the corresponding startup options in the slave
+ server's <filename>my.cnf</filename> file. To configure the
+ slave in the same way as the preceding example
+ <literal>CHANGE MASTER TO</literal> statement, the following
+ information would need to be included in the slave's
+ <filename>my.cnf</filename> file:
</para>
-
+
<programlisting>
[mysqld]
master-host=rep-master
@@ -8740,224 +8763,236 @@
master-user=myslave
master-password=53cr37
</programlisting>
-
+
<para>
See <xref linkend="replication-options"/>, for additional
options that can be set in <filename>my.cnf</filename> for
replication slaves.
</para>
-
+
<para>
- <emphasis role="bold">Note</emphasis>: To provide replication
- backup capability, you will also need to add an
+ <emphasis role="bold">Note</emphasis>: To provide
+ replication backup capability, you will also need to add an
<option>ndb-connectstring</option> option to the slave's
<filename>my.cnf</filename> file prior to starting the
- replication process. See
+ replication process. See
<xref linkend="mysql-cluster-replication-backups"/>, for
details.
</para>
</listitem>
-
+
<listitem>
<para>
If the master cluster is already in use, you can create a
- backup of the master and load this onto the slave to
- cut down on the amount of time required for the slave to
+ backup of the master and load this onto the slave to cut
+ down on the amount of time required for the slave to
synchronize itself with the master. If the slave is also
running MySQL Cluster, this can be accomplished using the
- backup and restore procedure described in
+ backup and restore procedure described in
<xref linkend="mysql-cluster-replication-backups"/>.
</para>
-
+
<programlisting>
ndb-connectstring=<replaceable>management-host</replaceable>[:<replaceable>port</replaceable>]
</programlisting>
-
+
<para>
- In the event that you are <emphasis>not</emphasis> using MySQL
- Cluster on the replication slave, you can create a backup with
- this command on the replication master:
+ In the event that you are <emphasis>not</emphasis> using
+ MySQL Cluster on the replication slave, you can create a
+ backup with this command on the replication master:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>mysqldump &ddash;master-data=1</userinput>
</programlisting>
-
+
<para>
- Then import the resulting data dump onto the slave by copying
- the dump file over to the slave. After this, you can use the
- <command>mysql</command> client to import the data from the
- dumpfile into the slave database as shown here, where
- <filename>dump_file</filename> is the name of the file that
- was generated using <command>mysqldump</command> on the
+ Then import the resulting data dump onto the slave by
+ copying the dump file over to the slave. After this, you can
+ use the <command>mysql</command> client to import the data
+ from the dumpfile into the slave database as shown here,
+ where <filename>dump_file</filename> is the name of the file
+ that was generated using <command>mysqldump</command> on the
master, and <literal>database-name</literal> is the name of
the database to be replicated:
</para>
-
+
<programlisting>
shell<replaceable>S</replaceable>> <userinput>mysql -u root -p database-name < dump_file</userinput>
</programlisting>
-
+
<para>
For a complete list of options to use with
- <command>mysqldump</command>, see <xref linkend="mysqldump"/>.
+ <command>mysqldump</command>, see
+ <xref linkend="mysqldump"/>.
</para>
-
+
<para>
Note that if you copy the data to the slave in this fashion,
you should make sure that the slave is started with the
- <option>&ddash;skip-slave-start</option> option on the command
- line, or else include <literal>skip-slave-start</literal> in
- the slave's <filename>my.cnf</filename> file to keep
- it from trying to connect to the master to begin replicating
- before all the data has been loaded. Once the loading of data
- has completed, follow the additional steps outlined in the
- next two sections.
+ <option>&ddash;skip-slave-start</option> option on the
+ command line, or else include
+ <literal>skip-slave-start</literal> in the slave's
+ <filename>my.cnf</filename> file to keep it from trying to
+ connect to the master to begin replicating before all the
+ data has been loaded. Once the loading of data has
+ completed, follow the additional steps outlined in the next
+ two sections.
</para>
</listitem>
-
+
<listitem>
<remark role="todo">
[js] Note that the xref in the second sentence of the next
para points to the Row-Based Replication section, and must
be commented out until that section is uncommented.
</remark>
-
+
<para>
Ensure that each MySQL server acting as a replication master
- is configured with a unique server ID, and with binary logging
- enabled, using the row format. (See
- <xref linkend="replication-row-based"/>.) These options can be
- set either in the master server's <filename>my.cnf</filename>
- file, or on the command line when starting the master
- <command>mysqld</command> process. See
- <xref linkend="mysql-cluster-replication-starting"/>, for
- information regarding the latter option.
+ is configured with a unique server ID, and with binary
+ logging enabled, using the row format. (See
+ <xref linkend="replication-row-based"/>.) These options can
+ be set either in the master server's
+ <filename>my.cnf</filename> file, or on the command line
+ when starting the master <command>mysqld</command> process.
+ See <xref linkend="mysql-cluster-replication-starting"/>,
+ for information regarding the latter option.
</para>
</listitem>
+
</orderedlist>
-
+
</section>
-
+
<section id="mysql-cluster-replication-starting">
+
<title>&title-mysql-cluster-replication-starting;</title>
-
+
<para>
This section outlines the procedure for starting MySQL CLuster
replication using a single replication channel.
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Start the MySQL replication master server by issuing this
command:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>mysqld &ddash;nbdcluster &ddash;server-id=<replaceable>id</replaceable> \</userinput>
<userinput>&ddash;log-bin &ddash;binlog-format=row &</userinput>
</programlisting>
-
+
<para>
- where <replaceable>id</replaceable> is this server's unique ID
- (see <xref linkend="mysql-cluster-replication-general"/>).
- This starts the server's <command>mysqld</command> process
- with binary logging enabled using the proper logging format.
+ where <replaceable>id</replaceable> is this server's unique
+ ID (see
+ <xref linkend="mysql-cluster-replication-general"/>). This
+ starts the server's <command>mysqld</command> process with
+ binary logging enabled using the proper logging format.
</para>
</listitem>
-
+
<listitem>
<para>
Start the MySQL replication slave server as shown here:
</para>
-
+
<programlisting>
shell<replaceable>S</replaceable>> <userinput>mysqld &ddash;ndbcluster &ddash;server-id=<replaceable>id</replaceable> &</userinput>
</programlisting>
-
+
<para>
where <replaceable>id</replaceable> is the slave server's
unique ID. It is not necessary to enable logging on the
replication slave.
</para>
-
- <para>Note that you should use the
- <option>&ddash;skip-slave-start</option> option with this command
- or else you should include <literal>skip-slave-start</literal>
- in the slave server's <filename>my.cnf</filename> file, unless
- you wish for replication to begin immediately. With the use of
- this option, the start of replication will be delayed until
- the appropriate <literal>START SLAVE</literal> statement has
+
+ <para>
+ Note that you should use the
+ <option>&ddash;skip-slave-start</option> option with this
+ command or else you should include
+ <literal>skip-slave-start</literal> in the slave server's
+ <filename>my.cnf</filename> file, unless you want
+ replication to begin immediately. With the use of this
+ option, the start of replication will be delayed until the
+ appropriate <literal>START SLAVE</literal> statement has
been issued, as explained in Step 4 below.
</para>
</listitem>
-
+
<listitem>
<para>
It is necessary to synchronize the slave server with the
- master server's replication binlog. If binary logging has not
- previously been running on the master, then run the following
- query on the slave:
+ master server's replication binlog. If binary logging has
+ not previously been running on the master, run the following
+ statement on the slave:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>CHANGE MASTER TO</userinput>
-> <userinput>MASTER_LOG_FILE='',</userinput>
-> <userinput>MASTER_LOG_POS=4;</userinput>
</programlisting>
-
+
<para>
This will instruct the slave to begin reading the master's
binary log from the log's starting point. Otherwise —
that is, if you are loading data from the master using a
- backup mdash; see
+ backup mdash; see
<xref linkend="mysql-cluster-replication-failover"/>, for
information on how to obtain the correct values to use for
<literal>MASTER_LOG_FILE</literal> and
<literal>MASTER_LOG_POS</literal> in such cases.
</para>
</listitem>
-
+
<listitem>
<para>
Finally, you must instruct the slave to begin applying
replication by issuing this command from the
<command>mysql</command> client on the replication slave:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>START SLAVE;</userinput>
</programlisting>
-
+
<para>
- This also initiates the transmission of replication data from
- the master to the slave.
+ This also initiates the transmission of replication data
+ from the master to the slave.
</para>
</listitem>
- </orderedlist>
-
- <para>It is also possible to use two replication channels, in a
- manner simlar to the procedure described in the next section; the differences
- between this and using a single replication channel are covered in
+
+ </orderedlist>
+
+ <para>
+ It is also possible to use two replication channels, in a manner
+ simlar to the procedure described in the next section; the
+ differences between this and using a single replication channel
+ are covered in
<xref linkend="mysql-cluster-replication-two-channels"/>.
- </para>
-
+ </para>
+
</section>
-
+
<section id="mysql-cluster-replication-two-channels">
+
<title>&title-mysql-cluster-replication-two-channels;</title>
-
+
<para>
In a more complete example scenario, we envision two replication
channels to provide redundancy and thereby guard against
- possible failure of a single replication channel. This requires a
- total of 4 replication servers, two masters for the master cluster
- and two slave servers for the slave cluster. For purposes of the
- discussion that follows, we assume that unique identifiers are
- assigned as shown here:
+ possible failure of a single replication channel. This requires
+ a total of 4 replication servers, two masters for the master
+ cluster and two slave servers for the slave cluster. For
+ purposes of the discussion that follows, we assume that unique
+ identifiers are assigned as shown here:
</para>
-
+
<informaltable>
<tgroup cols="2">
<colspec colwidth="20*"/>
@@ -8986,117 +9021,121 @@
</tbody>
</tgroup>
</informaltable>
-
+
<para>
Setting up replication with two channels is not radically
- different than setting up a single replication channel. First, the
- <command>mysqld</command> processes for the primary and secondary
- replication masters must be started, followed by those for the
- primary and secondary slaves. Then the replication processes may
- be initiated by issuing the <literal>START SLAVE</literal> statement
- on each of the slaves. The commands and the order in which they
- need to be issued are shown here:
+ different than setting up a single replication channel. First,
+ the <command>mysqld</command> processes for the primary and
+ secondary replication masters must be started, followed by those
+ for the primary and secondary slaves. Then the replication
+ processes may be initiated by issuing the <literal>START
+ SLAVE</literal> statement on each of the slaves. The commands
+ and the order in which they need to be issued are shown here:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Start the primary replication master:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>mysqld &ddash;ndbcluster &ddash;server-id=1 \</userinput>
<userinput>&ddash;log-bin &ddash;binlog-format=row &</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Start the secondary replication master:
</para>
-
+
<programlisting>
shell<replaceable>M'</replaceable>> <userinput>mysqld &ddash;ndbcluster &ddash;server-id=2 \</userinput>
<userinput>&ddash;log-bin &ddash;binlog-format=row &</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Start the primary replication slave server:
</para>
-
+
<programlisting>
shell<replaceable>S</replaceable>> <userinput>mysqld &ddash;ndbcluster &ddash;server-id=3 \</userinput>
<userinput>&ddash;skip-slave-start &</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Start the secondary replication slave:
</para>
-
+
<programlisting>
shell<replaceable>S'</replaceable>> <userinput>mysqld &ddash;ndbcluster &ddash;server-id=4 \</userinput>
<userinput>&ddash;skip-slave-start &</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Finally, commence replication on the primary channel by
- executing the <literal>START SLAVE</literal> statement on the
- primary slave as shown here:
+ executing the <literal>START SLAVE</literal> statement on
+ the primary slave as shown here:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>START SLAVE;</userinput>
</programlisting>
</listitem>
+
</orderedlist>
-
+
<para>
- Note that — as mentioned previously — is not necessary
- to enable binary logging on replication slaves.
+ Note that — as mentioned previously — is not
+ necessary to enable binary logging on replication slaves.
</para>
-
+
</section>
-
+
<section id="mysql-cluster-replication-failover">
+
<title>&title-mysql-cluster-replication-failover;</title>
-
+
<para>
In the event that the primary Cluster replication process fails,
it is possible to switch over to the secondary replication
channel. We describe in this section the steps required to
accomplish this.
</para>
-
+
<orderedlist>
+
<listitem>
<para>
First, you must obtain the time of the most recent global
checkpoint (GCP). That is, you need to determine the most
- recent epoch from the <literal>apply_status</literal> table on
- the slave cluster, which can be found using the following
+ recent epoch from the <literal>apply_status</literal> table
+ on the slave cluster, which can be found using the following
query:
</para>
-
+
<programlisting>
mysql<replaceable>S'</replaceable>> <userinput>SELECT @latest:=MAX(epoch)</userinput>
<userinput>FROM cluster_replication.apply_status;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
- Using the information obtained from the query shown in Step 1,
- you can obtain the corresponding records from the
- <literal>binlog_index</literal> table on the master cluster as
- shown here:
+ Using the information obtained from the query shown in Step
+ 1, you can obtain the corresponding records from the
+ <literal>binlog_index</literal> table on the master cluster
+ as shown here:
</para>
-
+
<programlisting>
mysqlM'> <userinput>SELECT</userinput>
-> <userinput>@file:=SUBSTRING_INDEX(File, '/', -1),</userinput>
@@ -9105,145 +9144,152 @@
-> <userinput>WHERE epoch > @latest</userinput>
-> <userinput>ORDER BY epoch ASC LIMIT 1;</userinput>
</programlisting>
-
+
<para>
- These are the records saved on the master since the failure of
- the primary replication channel. We have employed a user
+ These are the records saved on the master since the failure
+ of the primary replication channel. We have employed a user
variable <literal>@latest</literal> here to represent the
value obtained in Step 1. Of course, it is not possible for
one <command>mysqld</command> instance to access user
- variables set on another server instance directly; this value
- will need to be <quote>plugged in</quote> to the second query
- manually or in application code.
+ variables set on another server instance directly; this
+ value will need to be <quote>plugged in</quote> to the
+ second query manually or in application code.
</para>
</listitem>
-
+
<listitem>
<para>
Now it is possible to synchronize the secondary channel by
running the following query on the secondary slave server:
- </para>
-
+ </para>
+
<programlisting>
mysql<replaceable>S'</replaceable>> <userinput>CHANGE MASTER TO</userinput>
-> <userinput>MASTER_LOG_FILE='@file',</userinput>
-> <userinput>MASTER_LOG_POS=@pos;</userinput>
</programlisting>
-
+
<para>
Again we have employed user variables (in this case
- <literal>@file</literal> and <literal>@pos</literal>) in order
- to represent the values obtained in Step 2 and applied in Step
- 3; in practice these values must be inserted manually or using
- application code that can access both of the servers involved.
+ <literal>@file</literal> and <literal>@pos</literal>) to
+ represent the values obtained in Step 2 and applied in Step
+ 3; in practice these values must be inserted manually or
+ using application code that can access both of the servers
+ involved.
</para>
-
+
<para>
Note that <literal>@file</literal> is a string value such as
<literal>'/var/log/mysql/replication-master-bin.00001'</literal>
and so must be quoted when used in SQL or application code.
- However, the value represented by <literal>@pos</literal> must
- <emphasis>not</emphasis> be quoted; while MySQL normally
- attempts to convert strings to numbers, this case is an
- exception.
+ However, the value represented by <literal>@pos</literal>
+ must <emphasis>not</emphasis> be quoted; while MySQL
+ normally attempts to convert strings to numbers, this case
+ is an exception.
</para>
</listitem>
-
+
<listitem>
<para>
You can now initiate replication on the secondary channel by
issuing the appropriate command on the secondary slave
<command>mysqld</command>:
</para>
-
+
<programlisting>
mysql<replaceable>S'</replaceable>> <userinput>START SLAVE;</userinput>
</programlisting>
</listitem>
+
</orderedlist>
-
+
<para>
Once the secondary replication channel is active, you can
investigate the failure of the primary and effect repairs. The
precise actions required to do this will depend upon the reasons
for which the primary channel failed.
</para>
-
+
<para>
If the failure is limited to a single server, it should (in
- theory) be possible to replicate from <replaceable>M</replaceable>
- to <replaceable>S'</replaceable>, or from
- <replaceable>M'</replaceable> to <replaceable>S</replaceable>;
- however, this has not yet been tested.
+ theory) be possible to replicate from
+ <replaceable>M</replaceable> to <replaceable>S'</replaceable>,
+ or from <replaceable>M'</replaceable> to
+ <replaceable>S</replaceable>; however, this has not yet been
+ tested.
</para>
-
+
</section>
-
+
<section id="mysql-cluster-replication-backups">
+
<title>&title-mysql-cluster-replication-backups;</title>
-
+
<para>
- This discussion discusses making beackups and restoring from them
- using MySQL Cluster replication. We assume that the replication
- servers have already been configured as covered previously (see
+ This discussion discusses making beackups and restoring from
+ them using MySQL Cluster replication. We assume that the
+ replication servers have already been configured as covered
+ previously (see
<xref linkend="mysql-cluster-replication-preparation"/>, and the
sections immediately following). This having been done, the
procedure for making a backup and then restoring from it is as
- follows:
+ follows:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
There are two different methods by which the backup may be
started.
</para>
-
+
<itemizedlist>
+
<listitem>
<para>
<emphasis role="bold">Method A</emphasis>:
</para>
-
+
<para>
This method requires that the cluster backup process was
- previously enabled on the master server, prior to starting
- the replication process. This can be done by including the
- line
+ previously enabled on the master server, prior to
+ starting the replication process. This can be done by
+ including the line
</para>
-
+
<programlisting>
ndb-connectstring=<replaceable>management-host</replaceable>[:<replaceable>port</replaceable>]
</programlisting>
-
+
<para>
in a <literal>[MYSQL_CLUSTER]</literal> section in the
<filename>my.cnf file</filename>, where
<replaceable>management-host</replaceable> is the IP
address or hostname of the NDB management server for the
- master cluster, and <replaceable>port</replaceable> is the
- management server's port number. Note that the port number
- needs to be specified only if the default port (1186) is
- not being used. (See <xref linkend="multi-config"/>, for
- more information about ports and port allocation in MySQL
- Cluster.)
+ master cluster, and <replaceable>port</replaceable> is
+ the management server's port number. Note that the port
+ number needs to be specified only if the default port
+ (1186) is not being used. (See
+ <xref linkend="multi-config"/>, for more information
+ about ports and port allocation in MySQL Cluster.)
</para>
-
+
<para>
- In this case, the backup can be started by executing this
- statement on the replication master:
+ In this case, the backup can be started by executing
+ this statement on the replication master:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>ndb_mgm -e "START BACKUP"</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
<emphasis role="bold">Method B</emphasis>:
</para>
-
+
<para>
If the <filename>my.cnf</filename> file does not spacify
where to find the management host, you can start the
@@ -9251,94 +9297,94 @@
<literal>NDB</literal> management client as part of the
<literal>START BACKUP</literal> command, like this:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>ndb_mgm management-host:port -e "START BACKUP"</userinput>
</programlisting>
-
+
<para>
where <replaceable>management-host</replaceable> and
- <replaceable>port</replaceable> are the hostname and port
- number of the management server. In our scenario as
- outlined earliuer in this section (see
+ <replaceable>port</replaceable> are the hostname and
+ port number of the management server. In our scenario as
+ outlined earliuer in this section (see
<xref linkend="mysql-cluster-replication-preparation"/>),
this would be executed as follows:
</para>
-
+
<programlisting>
shell<replaceable>M</replaceable>> <userinput>ndb_mgm rep-master:1186 -e "START BACKUP"</userinput>
</programlisting>
-
</listitem>
+
</itemizedlist>
-
+
<para>
In either case, it is highly advisable to allow any pending
- transactions to be completed before beginning the backup, and
- then not to permit any new transactions to begin during the
- backup process.
- </para>
+ transactions to be completed before beginning the backup,
+ and then not to permit any new transactions to begin during
+ the backup process.
+ </para>
</listitem>
-
+
<listitem>
<para>
Copy the cluster backup files to the slave that is being
brought on line. Each system running an
<command>ndbd</command> process for the master cluster will
have cluster backup files located on it, and
- <emphasis>all</emphasis> of these files must be copied to the
- slave to ensure a successful restore. The backup
- files can be copied into any directory on the computer where
- the slave management host resides, so long as the MySQL and
- NDB binaries have read permissions in that directory. In this
+ <emphasis>all</emphasis> of these files must be copied to
+ the slave to ensure a successful restore. The backup files
+ can be copied into any directory on the computer where the
+ slave management host resides, so long as the MySQL and NDB
+ binaries have read permissions in that directory. In this
case, we will assume that these files have been copied into
the directory <filename>/var/BACKUPS/BACKUP-1</filename>.
</para>
-
+
<para>
It is not necessary that the slave cluster have the same
number of <command>ndbd</command> processes (data nodes) as
the master; however, it is highly recommended this number be
- the same. It <emphasis>is</emphasis> necessary that the slave
- be started with the <option>&ddash;skip-slave-start
- option</option>, to prevent premature startup of
- the replication process.
+ the same. It <emphasis>is</emphasis> necessary that the
+ slave be started with the <option>&ddash;skip-slave-start
+ option</option>, to prevent premature startup of the
+ replication process.
</para>
</listitem>
-
+
<listitem>
<para>
- Create any databases on the slave cluster that are present on
- the master cluster that are to be replicated to the slave.
- <emphasis role="bold">Important</emphasis>: A <literal>CREATE
- SCHEMA</literal> statement corresponding to each database to
- be replicated must be executed on each data node in the slave
- cluster.
+ Create any databases on the slave cluster that are present
+ on the master cluster that are to be replicated to the
+ slave. <emphasis role="bold">Important</emphasis>: A
+ <literal>CREATE SCHEMA</literal> statement corresponding to
+ each database to be replicated must be executed on each data
+ node in the slave cluster.
</para>
</listitem>
-
+
<listitem>
<para>
Reset the slave cluster using this statement in the MySQL
Monitor:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>RESET SLAVE;</userinput>
</programlisting>
-
+
<para>
It is important that you make sure that the slave's
apply_status table does not contain any records prior to
running the restore process. You can accomplish this by
- running this SQL statement on the slave:
+ running this SQL statement on the slave:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>DELETE FROM cluster_replication.apply_status;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
You can now start the cluster restoration process on the
@@ -9347,31 +9393,31 @@
it is necessary to include the <option>-m</option> option in
order to restore the cluster metadata:
</para>
-
+
<programlisting>
shell<replaceable>S</replaceable>> <userinput>ndb_restore -c <replaceable>slave-host</replaceable>:<replaceable>port</replaceable> -n <replaceable>node-id</replaceable> \</userinput>
<userinput>-b <replaceable>backup-id</replaceable> -m -r <replaceable>dir</replaceable></userinput>
</programlisting>
-
+
<para>
where <replaceable>dir</replaceable> is the path to the
directory where the backup files have been placed on the
replication slave. For the <command>ndb_restore</command>
commands corresponding to the remaining backup files, the
- <option>-m</option> option should <emphasis>not</emphasis> be
- used.
+ <option>-m</option> option should <emphasis>not</emphasis>
+ be used.
</para>
-
+
<para>
For restoring from a master cluster with four data nodes (as
- shown in the figure in
- <xref linkend="mysql-cluster-replication"/>) where the backup
- files have been copied to the directory
+ shown in the figure in
+ <xref linkend="mysql-cluster-replication"/>) where the
+ backup files have been copied to the directory
<filename>/var/BACKUPS/BACKUP-1</filename>, the proper
sequence of commands to be executed on the slave might look
like this:
</para>
-
+
<programlisting>
shell<replaceable>S</replaceable>> <userinput>ndb_restore -c rep-slave:1186 -n 2 -b 1 -m \</userinput>
<userinput>-r ./VAR/BACKUPS/BACKUP-1</userinput>
@@ -9382,14 +9428,14 @@
shell<replaceable>S</replaceable>> <userinput>ndb_restore -c rep-slave:1186 -n 5 -b 1 \</userinput>
<userinput>-r ./VAR/BACKUPS/BACKUP-1</userinput>
</programlisting>
-
+
<para>
- This sequence of commands causes the most recent epoch records
- to be written to the slave's <literal>apply_status</literal>
- table.
+ This sequence of commands causes the most recent epoch
+ records to be written to the slave's
+ <literal>apply_status</literal> table.
</para>
</listitem>
-
+
<listitem>
<para>
Next, it is necessary to make all nodes in the slave cluster
@@ -9399,47 +9445,47 @@
<xref linkend="mysql-cluster-replication-schema-discovery"/>).
You can accomplish this using the commands
</para>
-
+
<programlisting>
mysql<replaceable>S*</replaceable>> <userinput>USE <replaceable>database</replaceable>;</userinput>
mysql<replaceable>S*</replaceable>> <userinput>SHOW TABLES;</userinput>
</programlisting>
-
+
<para>
where <replaceable>database</replaceable> is the name of the
database which was backed up and restored. Where multiple
databases have been backed up and then restored, it is
- necessary to issue the <literal>USE</literal> and
- <literal>SHOW</literal> statements for each database in turn.
- Note also that these commands must be issued on each host
- acting as a data node in the slave cluster.
+ necessary to issue the <literal>USE</literal> and
+ <literal>SHOW</literal> statements for each database in
+ turn. Note also that these commands must be issued on each
+ host acting as a data node in the slave cluster.
</para>
</listitem>
-
+
<listitem>
<para>
Now you need to obtain the most recent epoch from the
<literal>binlog_index</literal> table on the slave, as
- discussed elsewhere (see
+ discussed elsewhere (see
<xref linkend="mysql-cluster-replication-failover"/>):
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>SELECT @latest:=MAX(epoch)</userinput>
<userinput>FROM cluster_replication.apply_status;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Using <literal>@latest</literal> as the epoch value obtained
in the previous step, you can obtain the correct starting
- position <literal>@pos</literal> in the correct binary logfile
- <literal>@file</literal> from the master's
+ position <literal>@pos</literal> in the correct binary
+ logfile <literal>@file</literal> from the master's
<literal>cluster_replication.binlog_index table</literal>
using the query shown here:
</para>
-
+
<programlisting>
mysql<replaceable>M</replaceable>> <userinput>SELECT</userinput>
-> <userinput>@file:=SUBSTRING_INDEX(File, '/', -1),</userinput>
@@ -9449,60 +9495,62 @@
-> <userinput>ORDER BY epoch ASC LIMIT 1;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Using the values obtained in the previous step, you can now
issue the appropriate <literal>CHANGE MASTER TO</literal>
statement in the slave's <command>mysql</command> client:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>CHANGE MASTER TO</userinput>
-> <userinput>MASTER_LOG_FILE='@file',</userinput>
-> <userinput>MASTER_LOG_POS=@pos;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Now that the slave <quote>knows</quote> from what point in
which <literal>binlog</literal> file to start reading data
- from the master, you can cause the slave to begin replicating
- with this standard MySQL statement:
+ from the master, you can cause the slave to begin
+ replicating with this standard MySQL statement:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>START SLAVE;</userinput>
</programlisting>
</listitem>
+
</orderedlist>
-
+
<para>
- In order to perform a backup and restore on a second replication
- channel, it is necessary only to repeat these steps, substituting
- the hostnames and IDs of the secondary master and slave for those
- of the primary master and slave replication servers where
- appropriate, and running the preceding statements on them.
+ To perform a backup and restore on a second replication channel,
+ it is necessary only to repeat these steps, substituting the
+ hostnames and IDs of the secondary master and slave for those of
+ the primary master and slave replication servers where
+ appropriate, and running the preceding statements on them.
</para>
-
+
<para>
For additional information on performing Cluster backups and
- restoring Cluster from backups, see
+ restoring Cluster from backups, see
<xref linkend="mysql-cluster-backup"/>.
</para>
-
+
<section id="mysql-cluster-replication-auto-sync">
+
<title>&title-mysql-cluster-replication-auto-sync;</title>
-
+
<para>
- It is possible to automate much of the process described in the
- previous section (see
+ It is possible to automate much of the process described in
+ the previous section (see
<xref linkend="mysql-cluster-replication-backups"/>). The
- following Perl script <filename>reset-slave.pl</filename> serves
- as an example of how you can do this.
+ following Perl script <filename>reset-slave.pl</filename>
+ serves as an example of how you can do this.
</para>
-
+
<programlisting>
#!/user/bin/perl -w
@@ -9684,204 +9732,212 @@
# end reset-slave.pl
</programlisting>
-
+
</section>
-
+
<section id="mysql-cluster-replication-schema-discovery">
+
<title>&title-mysql-cluster-replication-schema-discovery;</title>
-
+
<para>
- The NDB Cluster storage engine does not at present automatically
- detect structural changes in databases or tables. When a
- database or table is created or dropped, or when a table is
- altered using <literal>ALTER TABLE</literal>, the cluster must
- be made aware of the change. When a database is created or
- dropped, the appropriate <literal>CREATE SCHEMA</literal> or
- <literal>DROP SCHEMA</literal> statement should be issued on each
- storage node in the cluster in order induce discovery of the
- change, that is:
+ The NDB Cluster storage engine does not at present
+ automatically detect structural changes in databases or
+ tables. When a database or table is created or dropped, or
+ when a table is altered using <literal>ALTER TABLE</literal>,
+ the cluster must be made aware of the change. When a database
+ is created or dropped, the appropriate <literal>CREATE
+ SCHEMA</literal> or <literal>DROP SCHEMA</literal> statement
+ should be issued on each storage node in the cluster to induce
+ discovery of the change, that is:
</para>
-
+
<programlisting>
mysql<replaceable>S*</replaceable>> <userinput>CREATE SCHEMA <replaceable>db-name</replaceable>;</userinput>
mysql<replaceable>S*</replaceable>> <userinput>DROP SCHEMA <replaceable>db-name</replaceable>;</userinput>
</programlisting>
-
+
<para>
<emphasis role="bold">Dropping Tables</emphasis>:
</para>
-
+
<para>
When dropping a table that uses the <literal>NDB
- Cluster</literal> storage engine, it is necessary to allow any
+ Cluster</literal> storage engine, it is necessary to allow any
unfinished transactions to be completed and then not to begin
- any new transactions before performing the DROP operation:
+ any new transactions before performing the DROP operation:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Stop performing transactions on the slave.
</para>
</listitem>
-
+
<listitem>
<para>
Drop the table:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>& <userinput>DROP TABLE [<replaceable>db-name</replaceable>.]<replaceable>table-name</replaceable>;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
- Make all slave <command>mysqld</command> processes aware of
- the drop:
+ Make all slave <command>mysqld</command> processes aware
+ of the drop:
</para>
-
+
<programlisting>
mysql<replaceable>S*</replaceable>> <userinput>SHOW TABLES [FROM <replaceable>db-name</replaceable>];</userinput>
</programlisting>
</listitem>
+
</orderedlist>
-
+
<para>
All of the MySQL slave servers can now <quote>see</quote> that
the table has been dropped from the database.
</para>
-
+
<para>
<emphasis role="bold">Creating Tables</emphasis>
</para>
-
+
<para>
When creating a new table, you should perform the following
steps:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Create the table:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>CREATE TABLE [<replaceable>db-name</replaceable>.]<replaceable>table-name</replaceable> (</userinput>
<userinput><replaceable># column and index definitions...</replaceable></userinput>
<userinput>) ENGINE=NDB;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Make all SQL nodes in the slave cluster aware of the new
table:
</para>
-
+
<programlisting>
mysql<replaceable>S*</replaceable>> <userinput>SHOW TABLES [FROM <replaceable>db-name</replaceable>];</userinput>
</programlisting>
-
+
<para>
- You can now start using the table as normal. When creating a
- new table, note that — unlike the case when dropping
- tables —, it is <emphasis>not</emphasis> necessary to
- stop performing any transactions beforehand.
+ You can now start using the table as normal. When creating
+ a new table, note that — unlike the case when
+ dropping tables —, it is <emphasis>not</emphasis>
+ necessary to stop performing any transactions beforehand.
</para>
</listitem>
+
</orderedlist>
-
+
<para>
<emphasis role="bold">Altering tables</emphasis>
</para>
-
+
<para>
- When altering tables, you should perform the following steps in
- the order shown:
+ When altering tables, you should perform the following steps
+ in the order shown:
</para>
-
+
<orderedlist>
+
<listitem>
<para>
Ensure that all pending transactions have been completed,
and do not initiate any new transactions at this time.
</para>
</listitem>
-
+
<listitem>
<para>
- Issue any desired <literal>ALTER TABLE</literal> statements
- that add or remove columns to or from an existing table,
- for example:
+ Issue any desired <literal>ALTER TABLE</literal>
+ statements that add or remove columns to or from an
+ existing table, for example:
</para>
-
+
<programlisting>
mysql<replaceable>S</replaceable>> <userinput>ALTER TABLE table-name /* <replaceable>column-definition(s)...</replaceable> */;</userinput>
</programlisting>
</listitem>
-
+
<listitem>
<para>
Force all slave SQL nodes to become aware of the changed
table definition. The recommended way to do this is by
issuing a <quote>throwaway</quote> <literal>SHOW
- TABLES</literal> statement on each slave
+ TABLES</literal> statement on each slave
<command>mysqld</command>:
</para>
-
+
<programlisting>
mysql<replaceable>S*</replaceable>> <userinput>SHOW TABLES;</userinput>
</programlisting>
-
+
<para>
You may now resume normal operations. These include
transactions involving records in the changed table.
</para>
</listitem>
+
</orderedlist>
-
+
<para>
Note that when you create a new <literal>NDB Cluster</literal>
table on the master cluster, if you do so using the
<command>mysqld</command> that acts as the replication master,
- you must execute a <literal>SHOW TABLES</literal>, also on
- the master <command>mysqld</command>, to initiate
- discovery properly. Otherwise, the new table and any data it
- contains cannot be seen by the replication master
+ you must execute a <literal>SHOW TABLES</literal>, also on the
+ master <command>mysqld</command>, to initiate discovery
+ properly. Otherwise, the new table and any data it contains
+ cannot be seen by the replication master
<command>mysqld</command>, nor by the slave (that is, neither
the new table nor its data is replicated). If the table is
- created on a <command>mysqld</command> that is not acting as the
- replication master, then it does not matter which
+ created on a <command>mysqld</command> that is not acting as
+ the replication master, it does not matter which
<command>mysqld</command> issues the <literal>SHOW
- TABLES</literal>.
+ TABLES</literal>.
</para>
-
+
<para>
It is also possible to force discovery by issuing a
<quote>dummy</quote> <literal>SELECT</literal> statement using
the new or altered table in the statement's
- <literal>FROM</literal> clause. Although the statement fails, it
- causes the change to be recognized by the cluster. However,
- issuing a <literal>SHOW TABLES</literal> is the preferred method.
+ <literal>FROM</literal> clause. Although the statement fails,
+ it causes the change to be recognized by the cluster. However,
+ issuing a <literal>SHOW TABLES</literal> is the preferred
+ method.
</para>
-
+
<para>
We are working to implement automatic discovery of schema
- changes in a future MySQL Cluster release. For more information
- about this and other Cluster issues, see
+ changes in a future MySQL Cluster release. For more
+ information about this and other Cluster issues, see
<xref linkend="mysql-cluster-limitations"/>.
</para>
-
- </section>
-
+
+ </section>
+
</section>
-
+
</section>
-
- -->
+-->
+
<section id="mysql-cluster-interconnects">
<title>&title-mysql-cluster-interconnects;</title>
@@ -9938,7 +9994,7 @@
</para>
<para>
- Any machines with which you wish to use SCI Sockets need to be
+ Any machines with which you wish to use SCI Sockets must be
equipped with SCI cards.
</para>
@@ -10049,8 +10105,8 @@
procesors. To build the libraries for Opteron CPUs using the
64-bit extensions, run
<command>make_PSB_66_X86_64_release</command> rather than
- <command>make_PSB_66_release</command>; if the build is made on
- an Itanium machine, then you should use
+ <command>make_PSB_66_release</command>. If the build is made on
+ an Itanium machine, you should use
<command>make_PSB_66_IA64_release</command>. The X86-64 variant
should work for Intel EM64T architectures but this has not yet
(to our knowledge) been tested.
@@ -10569,7 +10625,7 @@
<command>ndbd</command> process priority is set in such a way
that the process does not lose priority due to running for an
extended period of time, as can be done by locking processes to
- CPUs in Linux 2.6. If such a configuration is possible, then the
+ CPUs in Linux 2.6. If such a configuration is possible, the
<command>ndbd</command> process will benefit by 10-70% as
compared with using SCI sockets. (The larger figures will be
seen when performing updates and probably on parallel scan
@@ -10682,10 +10738,10 @@
As of MySQL 5.1.6, all Cluster tables are by default
partitioned by <literal>KEY</literal> using the table's
primary key as the partitioning key. If no primary key is
- explicitly set for the table, then the
- <quote>hidden</quote> primary key automatically created by
- the <literal>NDB</literal> storage engine is used instead.
- For additional discussion of these and related issues, see
+ explicitly set for the table, the <quote>hidden</quote>
+ primary key automatically created by the
+ <literal>NDB</literal> storage engine is used instead. For
+ additional discussion of these and related issues, see
<xref linkend="partitioning-key"/>.
</para>
</listitem>
@@ -11030,7 +11086,7 @@
<literal>CREATE INDEX</literal>, as the <literal>NDB
Cluster</literal> does not support autodiscovery of such
changes. (However, you can import or create a table that
- uses a different storage engine, then convert it to
+ uses a different storage engine, and then convert it to
<literal>NDB</literal> using <literal>ALTER TABLE
<replaceable>tbl_name</replaceable>
ENGINE=NDBCLUSTER</literal>. In such a case, you must
@@ -11428,14 +11484,13 @@
This means that if the master fails, it is possible that the
slave might not have recorded the last few transactions. If a
transaction-safe engine such as <literal>InnoDB</literal> is
- being used, then a transaction will either be complete on the
- slave or not applied at all, but replication does not
- guarantee that all data on the master and the slave will be
- consistent at all times. In MySQL Cluster, all data nodes are
- kept in synchrony, and a transaction committed by any one data
- node is committed for all data nodes. In the event of a data
- node failure, all remaining data nodes remain in a consistent
- state.
+ being used, a transaction will either be complete on the slave
+ or not applied at all, but replication does not guarantee that
+ all data on the master and the slave will be consistent at all
+ times. In MySQL Cluster, all data nodes are kept in synchrony,
+ and a transaction committed by any one data node is committed
+ for all data nodes. In the event of a data node failure, all
+ remaining data nodes remain in a consistent state.
</para>
<para>
@@ -11613,11 +11668,10 @@
<para>
Currently, Cluster is in-memory only. This means that all
table data (including indexes) is stored in RAM. Therefore, if
- your data takes up 1 gigabyte of space and you wish to
- replicate it once in the cluster, you need 2 gigabytes of
- memory to do so. This in addition to the memory required by
- the operating system and any applications running on the
- cluster computers.
+ your data takes up 1GB of space and you want to replicate it
+ once in the cluster, you need 2GB of memory to do so. This in
+ addition to the memory required by the operating system and
+ any applications running on the cluster computers.
</para>
<para>
@@ -11970,14 +12024,14 @@
separate machine. If you place multiple nodes on a single
machine and that machine fails, you lose all of those nodes.
Given that MySQL Cluster can be run on commodity hardware
- loaded with a low-cost (or even no-cost) operating system, it
- is well worth the expense of an extra machine or two in order
- to safeguard mission-critical data. It also worth noting that
- the requirements for a cluster host running a management node
- are minimal. This task can be accomplished with a 200 MHz
- Pentium CPU and sufficient RAM for the operating system plus a
- small amount of overhead for the <command>ndb_mgmd</command>
- and <command>ndb_mgm</command> processes.
+ loaded with a low-cost (or even no-cost) operating system, the
+ expense of an extra machine or two is well worth it to
+ safeguard mission-critical data. It also worth noting that the
+ requirements for a cluster host running a management node are
+ minimal. This task can be accomplished with a 200 MHz Pentium
+ CPU and sufficient RAM for the operating system plus a small
+ amount of overhead for the <command>ndb_mgmd</command> and
+ <command>ndb_mgm</command> processes.
</para>
</listitem>
@@ -12179,7 +12233,7 @@
<para>
When cluster nodes go down, there are two possibilities. If
more than 50% of the remaining nodes can communicate with each
- other, then we have what is sometimes called a <quote>majority
+ other, we have what is sometimes called a <quote>majority
rules</quote> situation, and this set of nodes is considered
to be the cluster. The arbitrator comes into play when there
is an even number of nodes: in such cases, the set of nodes to
@@ -12301,8 +12355,8 @@
</para>
<para>
- To shut down the cluster, enter the following in a shell on
- the machine hosting the MGM node:
+ To shut down the cluster, enter the following command in a
+ shell on the machine hosting the MGM node:
</para>
<programlisting>
@@ -12371,9 +12425,8 @@
<para>
Yes, it is possible to do this. In the case of multiple data
nodes, each node must use a different data directory. If you
- want to run multiple SQL nodes on one machine, then each
- instance of <command>mysqld</command> must use a different
- TCP/IP port.
+ want to run multiple SQL nodes on one machine, each instance
+ of <command>mysqld</command> must use a different TCP/IP port.
</para>
</listitem>
@@ -12865,12 +12918,12 @@
node's host computer. For each data node in the cluster, you
must have available an amount of RAM equal to the size of the
database times the number of replicas, divided by the number
- of data nodes. Thus, if the database takes up 1 gigabyte of
- memory, and you wish to set up the cluster with four replicas
- and eight data nodes, a minimum of 500MB memory will be
- required per node. Note that this is in addition to any
- requirements for the operating system and any other
- applications that might be running on the host.
+ of data nodes. Thus, if the database takes up 1GB of memory,
+ and you want to set up the cluster with four replicas and
+ eight data nodes, a minimum of 500MB memory will be required
+ per node. Note that this is in addition to any requirements
+ for the operating system and any other applications that might
+ be running on the host.
</para>
</listitem>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r1158 - in trunk: . refman-4.1 refman-5.0 refman-5.1 | paul | 1 Feb |
