Author: jstephens
Date: 2007-08-17 18:07:04 +0200 (Fri, 17 Aug 2007)
New Revision: 7467
Log:
Cluster chapter/Cluster FAQ: --initial not actually required for
first-time start of Cluster (Thanks, Geert & cluster@lists
participants!)
Various small fixes & harmonisation between RefMan versions.
Modified:
trunk/refman-4.1/mysql-cluster.xml
trunk/refman-5.0/faqs.xml
trunk/refman-5.0/mysql-cluster.xml
trunk/refman-5.1/faqs.xml
trunk/refman-5.1/mysql-cluster.xml
trunk/refman-5.2/faqs.xml
trunk/refman-5.2/mysql-cluster.xml
Modified: trunk/refman-4.1/mysql-cluster.xml
===================================================================
--- trunk/refman-4.1/mysql-cluster.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-4.1/mysql-cluster.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 14, Lines Added: 53, Lines Deleted: 152; 10432 bytes
@@ -52,86 +52,10 @@
</indexterm>
<para>
- MySQL Cluster is currently available and supported on the following
- platforms:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <emphasis role="bold">Linux</emphasis>: x86, AMD64, EMT64,
- s/390, PPC, Alpha, SPARC, UltraSparc
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">Solaris</emphasis>: SPARC, UltraSparc,
- x86, AMD64, EMT64
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">BSD</emphasis> (FreeBSD, NetBSD, OpenBSD):
- x86, AMD64, EMT64, PPC
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">Mac OS X</emphasis>: PPC
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">HP-UX</emphasis>: PA-RISC
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">Tru64</emphasis>: Alpha
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">OpenVMS</emphasis>: Alpha
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">IRIX</emphasis>: MIPS
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">Novell Netware</emphasis>: x86
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">QNX Neutrino</emphasis>: x86
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis role="bold">SCO OpenServer, OpenUnix,
- UnixWare</emphasis>: x86
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- For exact levels of support available for MySQL Cluster on specific
+ MySQL ¤t-series; is currently available and supported on a
+ number of platforms, including Linux, Solaris, Mac OS X, BSD, HP-UX,
+ and many other Unix-style operating systems on a variety of
+ hardware. For exact levels of support available for on specific
combinations of operating system versions, operating system
distributions, and hardware platforms, please refer to the
<ulink url="http://www.mysql.com/support/supportedplatforms/cluster.html">Cluster
@@ -1783,7 +1707,7 @@
<listitem>
<para>
On the management host, issue the following command from the
- system shell to start the MGM node process:
+ system shell to start the management node process:
</para>
<remark role="todo">
@@ -1806,25 +1730,12 @@
<listitem>
<para>
On each of the data node hosts, run this command to start
- the <command>ndbd</command> process for the first time:
+ the <command>ndbd</command> process:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
+shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Note that it is very important to use the
- <option>--initial</option> parameter
- <emphasis>only</emphasis> when starting
- <command>ndbd</command> for the first time, or when
- restarting after a backup/restore operation or a
- configuration change. This is because the
- <option>--initial</option> option causes the node to delete
- any files created by earlier <command>ndbd</command>
- instances that are needed for recovery, including the
- recovery log files.
- </para>
</listitem>
<listitem>
@@ -2266,7 +2177,7 @@
<para>
To shut down the cluster, enter the following command in a shell
- on the machine hosting the MGM node:
+ on the machine hosting the management node:
</para>
<programlisting>
@@ -2315,12 +2226,6 @@
<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Remember <emphasis>not</emphasis> to invoke this command
- with the <option>--initial</option> option when restarting
- an NDBD node normally.
- </para>
</listitem>
<listitem>
@@ -2482,7 +2387,7 @@
<indexterm>
<primary>MySQL Cluster</primary>
- <secondary>starting with <option>--initial</option></secondary>
+ <secondary>starting</secondary>
</indexterm>
<para>
@@ -2558,36 +2463,13 @@
<para>
Then start a single data node by running
- <command>ndbd</command>. When starting <command>ndbd</command>
- for a given data node for the very first time, you should use
- the <option>--initial</option> option as shown here:
+ <command>ndbd</command>:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
-</programlisting>
-
- <para>
- For subsequent <command>ndbd</command> starts, you will
- generally want to <emphasis>omit</emphasis> the
- <option>--initial</option> option:
- </para>
-
-<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
- <para>
- 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">
[js] xref here to startup options.
</remark>
@@ -6097,6 +5979,10 @@
This parameter specifies the default size of messages
written to disk by the backup log and backup data buffers.
</para>
+
+ <para>
+ The default value is 32KB.
+ </para>
</listitem>
<listitem>
@@ -9962,11 +9848,13 @@
</para>
<para>
- An <option>--initial</option> start is to be used only the
- very first time that the <command>ndbd</command> process
- is started because it removes all files from the Cluster
- filesystem and re-creates all REDO log files. The
- exceptions to this rule are:
+ An <option>--initial</option> start is to be used
+ <emphasis>only</emphasis> when starting the
+ <command>ndbd</command> process under very special
+ circumstances; this is because this option causes all
+ files to be removed from the Cluster filesystem and all
+ redo log files to be re-created. These circumstances are
+ listed here:
</para>
<itemizedlist>
@@ -10020,6 +9908,15 @@
<option>-i</option> for this option. This shortcut was
removed to prevent this option from being used by mistake.
</para>
+
+ <note>
+ <para>
+ It is permissible to use this option when starting the
+ cluster for the very first time (that is, before any
+ data node files have been created); however, it is not
+ necessary to do so.
+ </para>
+ </note>
</listitem>
<listitem>
@@ -10307,15 +10204,8 @@
<para>
The cluster starts with a clean filesystem on all data
nodes. This occurs either when the cluster started for
- the very first time, or when it is restarted using the
- <option>&ddash;initial</option> option.
-
- <note>
- <para>
- Disk Data files are not removed when restarting a
- node using <option>&ddash;initial</option>.
- </para>
- </note>
+ the very first time, or when it all data nodes are
+ restarted using the <option>--initial</option> option.
</para>
</formalpara>
@@ -10468,7 +10358,7 @@
<literal>NDBCNTR</literal> blocks start (see
<xref linkend="ndb-internals-kernel-blocks"/>). The
cluster filesystem is cleared, if the cluster was
- started with the <option>&ddash;initial</option> option.
+ started with the <option>--initial</option> option.
</para>
</formalpara>
@@ -13470,15 +13360,16 @@
<secondary>errors</secondary>
</indexterm>
- <para>
- <emphasis role="bold">Note</emphasis>:
- <command>ndb_restore</command> reports both temporary and
- permanent errors. In the case of temporary errors, it may
- able to recover from them. Beginning with MySQL 4.1.22, it
- reports <literal>Restore successful, but encountered
- temporary error, please look at configuration</literal> in
- such cases.
- </para>
+ <note>
+ <para>
+ <command>ndb_restore</command> reports both temporary and
+ permanent errors. In the case of temporary errors, it may
+ able to recover from them. Beginning with MySQL 4.1.22 , it
+ reports <literal>Restore successful, but encountered
+ temporary error, please look at configuration</literal> in
+ such cases.
+ </para>
+ </note>
</refsection>
@@ -19568,6 +19459,16 @@
Restart the cluster, using the <option>--initial</option>
startup option.
</para>
+
+ <warning>
+ <para>
+ Never use the <option>--initial</option> when starting
+ <command>ndbd</command> except when necessary to clear
+ the data node filesystem. See
+ <xref linkend="mysql-cluster-ndbd-command-options"/>,
+ for information about when this is required.
+ </para>
+ </warning>
</listitem>
<listitem>
Modified: trunk/refman-5.0/faqs.xml
===================================================================
--- trunk/refman-5.0/faqs.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.0/faqs.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 2, Lines Added: 11, Lines Deleted: 1; 1076 bytes
@@ -1763,7 +1763,7 @@
<question>
<para>
- Where can I find documentation for MySQL Views?
+ Where can I find documentation covering MySQL Views?
</para>
</question>
@@ -4210,6 +4210,16 @@
Restart the cluster, using the
<option>--initial</option> startup option.
</para>
+
+ <warning>
+ <para>
+ Never use the <option>--initial</option> when starting
+ <command>ndbd</command> except when necessary to clear
+ the data node filesystem. See
+ <xref linkend="mysql-cluster-ndbd-command-options"/>,
+ for information about when this is required.
+ </para>
+ </warning>
</listitem>
<listitem>
Modified: trunk/refman-5.0/mysql-cluster.xml
===================================================================
--- trunk/refman-5.0/mysql-cluster.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.0/mysql-cluster.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 23, Lines Added: 61, Lines Deleted: 99; 13785 bytes
@@ -1743,25 +1743,12 @@
<listitem>
<para>
On each of the data node hosts, run this command to start
- the <command>ndbd</command> process for the first time:
+ the <command>ndbd</command> process:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
+shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Note that it is very important to use the
- <option>--initial</option> parameter
- <emphasis>only</emphasis> when starting
- <command>ndbd</command> for the first time, or when
- restarting after a backup/restore operation or a
- configuration change. This is because the
- <option>--initial</option> option causes the node to delete
- any files created by earlier <command>ndbd</command>
- instances that are needed for recovery, including the
- recovery log files.
- </para>
</listitem>
<listitem>
@@ -1935,9 +1922,9 @@
</programlisting>
<para>
- You will need to make sure that MySQL uses the NDB storage
- engine for this table. There are two ways that this can be
- accomplished. One of these is to modify the table definition
+ You need to make sure that MySQL uses the <literal>NDB</literal>
+ storage engine for this table. There are two ways that this can
+ be accomplished. One of these is to modify the table definition
<emphasis>before</emphasis> importing it into the Cluster
database. Using the <literal>City</literal> table as an example,
modify the <literal>ENGINE</literal> option of the definition as
@@ -1953,7 +1940,7 @@
`District` char(20) NOT NULL default '',
`Population` int(11) NOT NULL default '0',
PRIMARY KEY (`ID`)
-) ENGINE=NDBCLUSTER DEFAULT CHARSET=latin1;
+) <emphasis role="bold">ENGINE=NDBCLUSTER</emphasis> DEFAULT CHARSET=latin1;
INSERT INTO `City` VALUES (1,'Kabul','AFG','Kabol',1780000);
INSERT INTO `City` VALUES (2,'Qandahar','AFG','Qandahar',237500);
@@ -2057,11 +2044,12 @@
</para>
<para>
- It is worth taking into account that Cluster nodes do not make
- use of the MySQL privilege system when accessing one another.
- Setting or changing MySQL user accounts (including the
- <literal>root</literal> account) effects only applications that
- access the SQL node, not interaction between nodes.
+ It is worth taking into account that Cluster nodes do
+ <emphasis>not</emphasis> make use of the MySQL privilege system
+ when accessing one another. Setting or changing MySQL user
+ accounts (including the <literal>root</literal> account) effects
+ only applications that access the SQL node, not interaction
+ between nodes.
</para>
<para>
@@ -2105,12 +2093,12 @@
<para>
Applications that use MySQL can employ standard APIs to access
- NDB tables. It is important to remember that your application
- must access the SQL node, and not the MGM or data nodes. This
- brief example shows how we might execute the
- <literal>SELECT</literal> statement just shown by using PHP 5's
- <literal>mysqli</literal> extension running on a Web server
- elsewhere on the network:
+ <literal>NDB</literal> tables. It is important to remember that
+ your application must access the SQL node, and not the
+ management or data nodes. This brief example shows how we might
+ execute the <literal>SELECT</literal> statement just shown by
+ using the PHP 5.X <literal>mysqli</literal> extension running on
+ a Web server elsewhere on the network:
</para>
<programlisting>
@@ -2250,12 +2238,6 @@
<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Remember <emphasis>not</emphasis> to invoke this command
- with the <option>--initial</option> option when restarting
- an NDBD node normally.
- </para>
</listitem>
<listitem>
@@ -2426,7 +2408,7 @@
<indexterm>
<primary>MySQL Cluster</primary>
- <secondary>starting with <option>--initial</option></secondary>
+ <secondary>starting</secondary>
</indexterm>
<para>
@@ -2502,36 +2484,13 @@
<para>
Then start a single data node by running
- <command>ndbd</command>. When starting <command>ndbd</command>
- for a given data node for the very first time, you should use
- the <option>--initial</option> option as shown here:
+ <command>ndbd</command>:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
-</programlisting>
-
- <para>
- For subsequent <command>ndbd</command> starts, you will
- generally want to <emphasis>omit</emphasis> the
- <option>--initial</option> option:
- </para>
-
-<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
- <para>
- 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">
[js] xref here to startup options.
</remark>
@@ -4637,13 +4596,15 @@
forward.
</para>
- <para>
- <emphasis role="bold">Important</emphasis>: This parameter
- cannot be changed <quote>on the fly</quote>; you must
- restart the node using <option>--initial</option>. If you
- wish to change this value for a running cluster, you can
- do so via a rolling node restart.
- </para>
+ <important>
+ <para>
+ This parameter cannot be changed <quote>on the
+ fly</quote>; you must restart the node using
+ <option>--initial</option>. If you wish to change this
+ value for a running cluster, you can do so via a rolling
+ node restart.
+ </para>
+ </important>
</listitem>
<listitem>
@@ -5400,7 +5361,7 @@
coordinator waits for query execution by another node
before aborting the transaction, and is important for both
node failure handling and deadlock detection. In MySQL
- 5.1.20 and earlier versions, setting it too high could
+ 5.0.20 and earlier versions, setting it too high could
cause undesirable behavior in situations involving
deadlocks and node failure. Beginning with MySQL 5.0.21,
active transactions occurring during node failures are
@@ -5417,8 +5378,7 @@
<listitem>
<indexterm>
- <primary><literal>NoOfDiskPagesToDiskAfterRestartTUP</literal> (MySQL Cluster
- configuration parameter)</primary>
+ <primary><literal>NoOfDiskPagesToDiskAfterRestartTUP</literal></primary>
</indexterm>
<para id="mysql-cluster-param-ndbd-definition-noofdiskpagestodiskafterrestarttup">
@@ -5469,8 +5429,7 @@
<listitem>
<indexterm>
- <primary><literal>NoOfDiskPagesToDiskAfterRestartACC</literal> (MySQL Cluster
- configuration parameter)</primary>
+ <primary><literal>NoOfDiskPagesToDiskAfterRestartACC</literal></primary>
</indexterm>
<para id="mysql-cluster-param-ndbd-definition-noofdiskpagestodiskafterrestartacc">
@@ -5492,8 +5451,7 @@
<listitem>
<indexterm>
- <primary><literal>NoOfDiskPagesToDiskDuringRestartTUP</literal> (MySQL Cluster
- configuration parameter)</primary>
+ <primary><literal>NoOfDiskPagesToDiskDuringRestartTUP</literal></primary>
</indexterm>
<para id="mysql-cluster-param-ndbd-definition-noofdiskpagestodiskduringrestarttup">
@@ -5523,8 +5481,7 @@
<listitem>
<indexterm>
- <primary><literal>NoOfDiskPagesToDiskDuringRestartACC</literal> (MySQL Cluster
- configuration parameter)</primary>
+ <primary><literal>NoOfDiskPagesToDiskDuringRestartACC</literal></primary>
</indexterm>
<para id="mysql-cluster-param-ndbd-definition-noofdiskpagestodiskduringrestartacc">
@@ -5552,8 +5509,7 @@
<listitem>
<indexterm>
- <primary><literal>ArbitrationTimeout</literal> (MySQL Cluster configuration
- parameter)</primary>
+ <primary><literal>ArbitrationTimeout</literal></primary>
</indexterm>
<para id="mysql-cluster-param-ndbd-definition-arbitrationtimeout">
@@ -9608,9 +9564,9 @@
All MySQL Cluster executables (except for
<command>mysqld</command>) take the options described in this
section. Users of earlier MySQL Cluster versions should note
- that some of these options have been changed from those in MySQL
- 4.1 Cluster to make them consistent with one another as well as
- with <command>mysqld</command>. You can use the
+ that some of these options have been changed to make them
+ consistent with one another as well as with
+ <command>mysqld</command>. You can use the
<option>--help</option> option with any MySQL Cluster executable
to view a list of the options which it supports.
</para>
@@ -9920,11 +9876,13 @@
</para>
<para>
- An <option>--initial</option> start is to be used only the
- very first time that the <command>ndbd</command> process
- is started because it removes all files from the Cluster
- filesystem and re-creates all REDO log files. The
- exceptions to this rule are:
+ An <option>--initial</option> start is to be used
+ <emphasis>only</emphasis> when starting the
+ <command>ndbd</command> process under very special
+ circumstances; this is because this option causes all
+ files to be removed from the Cluster filesystem and all
+ redo log files to be re-created. These circumstances are
+ listed here:
</para>
<itemizedlist>
@@ -9972,6 +9930,15 @@
to use the <option>--initial</option> option. This may be
useful when scripting Cluster administrative tasks.
</para>
+
+ <note>
+ <para>
+ It is permissible to use this option when starting the
+ cluster for the very first time (that is, before any
+ data node files have been created); however, it is not
+ necessary to do so.
+ </para>
+ </note>
</listitem>
<listitem>
@@ -10340,13 +10307,13 @@
<para>
The cluster starts with a clean filesystem on all data
nodes. This occurs either when the cluster started for
- the very first time, or when it is restarted using the
- <option>&ddash;initial</option> option.
+ the very first time, or when all data nodes are
+ restarted using the <option>--initial</option> option.
<note>
<para>
Disk Data files are not removed when restarting a
- node using <option>&ddash;initial</option>.
+ node using <option>--initial</option>.
</para>
</note>
</para>
@@ -10501,7 +10468,7 @@
<literal>NDBCNTR</literal> blocks start (see
<xref linkend="ndb-internals-kernel-blocks"/>). The
cluster filesystem is cleared, if the cluster was
- started with the <option>&ddash;initial</option> option.
+ started with the <option>--initial</option> option.
</para>
</formalpara>
@@ -13810,11 +13777,6 @@
while the restore is in progress.
</para>
- <remark role="todo">
- [js] This is awfully short - either write some additional
- material for this section, or fold it into another section?
- </remark>
-
<formalpara role="mnmas-kb">
<title>MySQL Enterprise</title>
@@ -13935,7 +13897,7 @@
<listitem>
<para>
<command>ndb_config</command>: Retrieves Cluster configuration
- options.
+ option values.
</para>
</listitem>
@@ -17969,8 +17931,8 @@
<listitem>
<para>
The maximum number of metadata objects in
- MySQL 5.0 Cluster 20320. This limit is
- hard-coded.
+ MySQL ¤t-series; Cluster is 20320.
+ This limit is hard-coded.
</para>
</listitem>
Modified: trunk/refman-5.1/faqs.xml
===================================================================
--- trunk/refman-5.1/faqs.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.1/faqs.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 3, Lines Added: 12, Lines Deleted: 2; 1490 bytes
@@ -104,7 +104,7 @@
<answer>
<para>
- Yes. The Query Cache operates on the server level, caching
+ Yes. The query cache operates on the server level, caching
complete result sets matched with the original query string.
If an exactly identical query is made (which often happens,
particularly in web applications), no parsing or execution
@@ -1362,7 +1362,7 @@
<question>
<para>
- What will MySQL do to correct the aforementioned
+ What is being done to correct the aforementioned
limitations?
</para>
@@ -4236,6 +4236,16 @@
Restart the cluster, using the
<option>--initial</option> startup option.
</para>
+
+ <warning>
+ <para>
+ Never use the <option>--initial</option> when starting
+ <command>ndbd</command> except when necessary to clear
+ the data node filesystem. See
+ <xref linkend="mysql-cluster-ndbd-command-options"/>,
+ for information about when this is required.
+ </para>
+ </warning>
</listitem>
<listitem>
Modified: trunk/refman-5.1/mysql-cluster.xml
===================================================================
--- trunk/refman-5.1/mysql-cluster.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.1/mysql-cluster.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 17, Lines Added: 46, Lines Deleted: 111; 11023 bytes
@@ -2501,32 +2501,12 @@
<listitem>
<para>
On each of the data node hosts, run this command to start
- the <command>ndbd</command> process for the first time:
+ the <command>ndbd</command> process:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
+shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Note that it is very important to use the
- <option>--initial</option> parameter
- <emphasis>only</emphasis> when starting
- <command>ndbd</command> for the first time, or when
- restarting after a backup/restore operation or a
- configuration change. This is because the
- <option>--initial</option> option causes the node to delete
- any files created by earlier <command>ndbd</command>
- instances that are needed for recovery, including the
- recovery log files.
- </para>
-
- <para>
- An exception to this is that <option>--initial</option> does
- not delete Disk Data files. If you do need to perform an
- initial restart of the cluster, you must delete any existing
- Disk Data log files and data files manually.
- </para>
</listitem>
<listitem>
@@ -3018,12 +2998,6 @@
<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Remember <emphasis>not</emphasis> to invoke this command
- with the <option>--initial</option> option when restarting
- an NDBD node normally.
- </para>
</listitem>
<listitem>
@@ -3125,9 +3099,9 @@
¤t-series; BitKeeper tree, be sure to use the
<option>--with-ndbcluster</option> option when running
<command>configure</command>. You can also use the
- <command>BUILD/compile-pentium-max</command> build script. This
- script includes OpenSSL, so you must either have or obtain
- OpenSSL to build successfully, or else modify
+ <command>BUILD/compile-pentium-max</command> build script. Note
+ 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, and then perform
@@ -3229,7 +3203,7 @@
<indexterm>
<primary>MySQL Cluster</primary>
- <secondary>starting with <option>--initial</option></secondary>
+ <secondary>starting</secondary>
</indexterm>
<para>
@@ -3305,36 +3279,13 @@
<para>
Then start a single data node by running
- <command>ndbd</command>. When starting <command>ndbd</command>
- for a given data node for the very first time, you should use
- the <option>--initial</option> option as shown here:
+ <command>ndbd</command>:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
-</programlisting>
-
- <para>
- For subsequent <command>ndbd</command> starts, you will
- generally want to <emphasis>omit</emphasis> the
- <option>--initial</option> option:
- </para>
-
-<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
- <para>
- 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">
[js] xref here to startup options.
</remark>
@@ -5509,13 +5460,15 @@
forward.
</para>
- <para>
- <emphasis role="bold">Important</emphasis>: This parameter
- cannot be changed <quote>on the fly</quote>; you must
- restart the node using <option>--initial</option>. If you
- wish to change this value for a running cluster, you can
- do so via a rolling node restart.
- </para>
+ <important>
+ <para>
+ This parameter cannot be changed <quote>on the
+ fly</quote>; you must restart the node using
+ <option>--initial</option>. If you wish to change this
+ value for a running cluster, you can do so via a rolling
+ node restart.
+ </para>
+ </important>
</listitem>
<listitem>
@@ -11296,11 +11249,13 @@
</para>
<para>
- An <option>--initial</option> start is to be used only the
- very first time that the <command>ndbd</command> process
- is started because it removes all files from the Cluster
- filesystem and re-creates all REDO log files. The
- exceptions to this rule are:
+ An <option>--initial</option> start is to be used
+ <emphasis>only</emphasis> when starting the
+ <command>ndbd</command> process under very special
+ circumstances; this is because this option causes all
+ files to be removed from the Cluster filesystem and all
+ redo log files to be re-created. These circumstances are
+ listed here:
</para>
<itemizedlist>
@@ -11366,6 +11321,15 @@
to use the <option>--initial</option> option. This may be
useful when scripting Cluster administrative tasks.
</para>
+
+ <note>
+ <para>
+ It is permissible to use this option when starting the
+ cluster for the very first time (that is, before any
+ data node files have been created); however, it is not
+ necessary to do so.
+ </para>
+ </note>
</listitem>
<listitem>
@@ -11742,13 +11706,13 @@
<para>
The cluster starts with a clean filesystem on all data
nodes. This occurs either when the cluster started for
- the very first time, or when it is restarted using the
- <option>&ddash;initial</option> option.
+ the very first time, or when all data nodes are
+ restarted using the <option>--initial</option> option.
<note>
<para>
Disk Data files are not removed when restarting a
- node using <option>&ddash;initial</option>.
+ node using <option>--initial</option>.
</para>
</note>
</para>
@@ -11903,7 +11867,7 @@
<literal>NDBCNTR</literal> blocks start (see
<xref linkend="ndb-internals-kernel-blocks"/>). The
cluster filesystem is cleared, if the cluster was
- started with the <option>&ddash;initial</option> option.
+ started with the <option>--initial</option> option.
</para>
</formalpara>
@@ -15292,15 +15256,16 @@
<secondary>errors</secondary>
</indexterm>
- <para>
- <emphasis role="bold">Note</emphasis>:
- <command>ndb_restore</command> reports both temporary and
- permanent errors. In the case of temporary errors, it may
- able to recover from them. Beginning with MySQL 5.1.12, it
- reports <literal>Restore successful, but encountered
- temporary error, please look at configuration</literal> in
- such cases.
- </para>
+ <note>
+ <para>
+ <command>ndb_restore</command> reports both temporary and
+ permanent errors. In the case of temporary errors, it may
+ able to recover from them. Beginning with MySQL 5.1.12, it
+ reports <literal>Restore successful, but encountered
+ temporary error, please look at configuration</literal> in
+ such cases.
+ </para>
+ </note>
</refsection>
@@ -15487,11 +15452,6 @@
</formalpara>
- <remark role="todo">
- [js] This is awfully short - either write some additional
- material for this section, or fold it into another section?
- </remark>
-
</section>
</section>
@@ -15574,10 +15534,6 @@
server be connected to the cluster).
</para>
- <remark role="todo">
- [js] Fix path to tools directory for RefMan 5.0 and 4.1.
- </remark>
-
<para>
These utilities can also serve as examples for writing your own
applications using the <literal>NDB</literal> API. The source code
@@ -15752,8 +15708,6 @@
</itemizedlist>
-<!-- MERGED THROUGH HERE -->
-
<para>
Most of these utilities need to connect to a Cluster management
server in order to function. The exceptions are
@@ -17630,11 +17584,6 @@
<listitem>
<remark role="todo">
- [js] Remove this parameter from the 4.1 and 5.0
- versions, since it applies only to Disk Data tables.
- </remark>
-
- <remark role="todo">
[js] Add more info and link to cluster filesystem
documentation when that appears in the Manual.
</remark>
@@ -17964,11 +17913,6 @@
<title>Description</title>
- <remark role="todo">
- [js] Remove references to Disk Data objects from the
- following narrative for the 4.1 and 5.0 versions.
- </remark>
-
<para>
<command>ndb_show_tables</command> displays a list of all
<literal>NDB</literal> database objects in the cluster. By
@@ -23461,15 +23405,6 @@
<title>Temporary errors</title>
<para>
- <remark>
- We need to add visual markup (CSS etc.) for the
- errortext element. /SH
-
- <remark>
- [js] Sent MC an email asking for help with this.
- </remark>
- </remark>
-
When first starting a node, it is possible that you may
see Error 1204 <errortext>Temporary failure,
distribution changed</errortext> and similar temporary
Modified: trunk/refman-5.2/faqs.xml
===================================================================
--- trunk/refman-5.2/faqs.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.2/faqs.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 4, Lines Added: 14, Lines Deleted: 4; 1792 bytes
@@ -104,7 +104,7 @@
<answer>
<para>
- Yes. The Query Cache operates on the server level, caching
+ Yes. The query cache operates on the server level, caching
complete result sets matched with the original query string.
If an exactly identical query is made (which often happens,
particularly in web applications), no parsing or execution
@@ -1362,7 +1362,7 @@
<question>
<para>
- What will MySQL do to correct the aforementioned
+ What is being done to correct the aforementioned
limitations?
</para>
@@ -3511,8 +3511,8 @@
</indexterm>
<para>
- <emphasis>How much RAM do I need? Is it possible to use disk
- memory at all?</emphasis>
+ How much RAM do I need? Is it possible to use disk memory at
+ all?
</para>
</question>
@@ -4236,6 +4236,16 @@
Restart the cluster, using the
<option>--initial</option> startup option.
</para>
+
+ <warning>
+ <para>
+ Never use the <option>--initial</option> when starting
+ <command>ndbd</command> except when necessary to clear
+ the data node filesystem. See
+ <xref linkend="mysql-cluster-ndbd-command-options"/>,
+ for information about when this is required.
+ </para>
+ </warning>
</listitem>
<listitem>
Modified: trunk/refman-5.2/mysql-cluster.xml
===================================================================
--- trunk/refman-5.2/mysql-cluster.xml 2007-08-17 12:04:08 UTC (rev 7466)
+++ trunk/refman-5.2/mysql-cluster.xml 2007-08-17 16:07:04 UTC (rev 7467)
Changed blocks: 16, Lines Added: 45, Lines Deleted: 106; 10728 bytes
@@ -2485,32 +2485,12 @@
<listitem>
<para>
On each of the data node hosts, run this command to start
- the <command>ndbd</command> process for the first time:
+ the <command>ndbd</command> process:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
+shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Note that it is very important to use the
- <option>--initial</option> parameter
- <emphasis>only</emphasis> when starting
- <command>ndbd</command> for the first time, or when
- restarting after a backup/restore operation or a
- configuration change. This is because the
- <option>--initial</option> option causes the node to delete
- any files created by earlier <command>ndbd</command>
- instances that are needed for recovery, including the
- recovery log files.
- </para>
-
- <para>
- An exception to this is that <option>--initial</option> does
- not delete Disk Data files. If you do need to perform an
- initial restart of the cluster, you must delete any existing
- Disk Data log files and data files manually.
- </para>
</listitem>
<listitem>
@@ -3002,12 +2982,6 @@
<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
-
- <para>
- Remember <emphasis>not</emphasis> to invoke this command
- with the <option>--initial</option> option when restarting
- an NDBD node normally.
- </para>
</listitem>
<listitem>
@@ -3109,9 +3083,9 @@
¤t-series; BitKeeper tree, be sure to use the
<option>--with-ndbcluster</option> option when running
<command>configure</command>. You can also use the
- <command>BUILD/compile-pentium-max</command> build script. This
- script includes OpenSSL, so you must either have or obtain
- OpenSSL to build successfully, or else modify
+ <command>BUILD/compile-pentium-max</command> build script. Note
+ 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, and then perform
@@ -3213,7 +3187,7 @@
<indexterm>
<primary>MySQL Cluster</primary>
- <secondary>starting with <option>--initial</option></secondary>
+ <secondary>starting</secondary>
</indexterm>
<para>
@@ -3289,36 +3263,13 @@
<para>
Then start a single data node by running
- <command>ndbd</command>. When starting <command>ndbd</command>
- for a given data node for the very first time, you should use
- the <option>--initial</option> option as shown here:
+ <command>ndbd</command>:
</para>
<programlisting>
-shell> <userinput>ndbd --initial</userinput>
-</programlisting>
-
- <para>
- For subsequent <command>ndbd</command> starts, you will
- generally want to <emphasis>omit</emphasis> the
- <option>--initial</option> option:
- </para>
-
-<programlisting>
shell> <userinput>ndbd</userinput>
</programlisting>
- <para>
- 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">
[js] xref here to startup options.
</remark>
@@ -5487,13 +5438,15 @@
forward.
</para>
- <para>
- <emphasis role="bold">Important</emphasis>: This parameter
- cannot be changed <quote>on the fly</quote>; you must
- restart the node using <option>--initial</option>. If you
- wish to change this value for a running cluster, you can
- do so via a rolling node restart.
- </para>
+ <important>
+ <para>
+ This parameter cannot be changed <quote>on the
+ fly</quote>; you must restart the node using
+ <option>--initial</option>. If you wish to change this
+ value for a running cluster, you can do so via a rolling
+ node restart.
+ </para>
+ </important>
</listitem>
<listitem>
@@ -11248,11 +11201,13 @@
</para>
<para>
- An <option>--initial</option> start is to be used only the
- very first time that the <command>ndbd</command> process
- is started because it removes all files from the Cluster
- filesystem and re-creates all REDO log files. The
- exceptions to this rule are:
+ An <option>--initial</option> start is to be used
+ <emphasis>only</emphasis> when starting the
+ <command>ndbd</command> process under very special
+ circumstances; this is because this option causes all
+ files to be removed from the Cluster filesystem and all
+ redo log files to be re-created. These circumstances are
+ listed here:
</para>
<itemizedlist>
@@ -11318,6 +11273,15 @@
to use the <option>--initial</option> option. This may be
useful when scripting Cluster administrative tasks.
</para>
+
+ <note>
+ <para>
+ It is permissible to use this option when starting the
+ cluster for the very first time (that is, before any
+ data node files have been created); however, it is not
+ necessary to do so.
+ </para>
+ </note>
</listitem>
<listitem>
@@ -11694,13 +11658,13 @@
<para>
The cluster starts with a clean filesystem on all data
nodes. This occurs either when the cluster started for
- the very first time, or when it is restarted using the
- <option>&ddash;initial</option> option.
+ the very first time, or when all data nodes are
+ restarted using the <option>--initial</option> option.
<note>
<para>
Disk Data files are not removed when restarting a
- node using <option>&ddash;initial</option>.
+ node using <option>--initial</option>.
</para>
</note>
</para>
@@ -11855,7 +11819,7 @@
<literal>NDBCNTR</literal> blocks start (see
<xref linkend="ndb-internals-kernel-blocks"/>). The
cluster filesystem is cleared, if the cluster was
- started with the <option>&ddash;initial</option> option.
+ started with the <option>--initial</option> option.
</para>
</formalpara>
@@ -15235,15 +15199,15 @@
<secondary>errors</secondary>
</indexterm>
- <para>
- <emphasis role="bold">Note</emphasis>:
- <command>ndb_restore</command> reports both temporary and
- permanent errors. In the case of temporary errors, it may
- able to recover from them. Beginning with MySQL 5.1.12, it
- reports <literal>Restore successful, but encountered
- temporary error, please look at configuration</literal> in
- such cases.
- </para>
+ <note>
+ <para>
+ <command>ndb_restore</command> reports both temporary and
+ permanent errors. In the case of temporary errors, it may
+ able to recover from them. In such cases, it reports
+ <literal>Restore successful, but encountered temporary
+ error, please look at configuration</literal>.
+ </para>
+ </note>
</refsection>
@@ -15501,10 +15465,6 @@
server be connected to the cluster).
</para>
- <remark role="todo">
- [js] Fix path to tools directory for RefMan 5.0 and 4.1.
- </remark>
-
<para>
These utilities can also serve as examples for writing your own
applications using the <literal>NDB</literal> API. The source code
@@ -15679,8 +15639,6 @@
</itemizedlist>
-<!-- MERGED THROUGH HERE -->
-
<para>
Most of these utilities need to connect to a Cluster management
server in order to function. The exceptions are
@@ -17557,11 +17515,6 @@
<listitem>
<remark role="todo">
- [js] Remove this parameter from the 4.1 and 5.0
- versions, since it applies only to Disk Data tables.
- </remark>
-
- <remark role="todo">
[js] Add more info and link to cluster filesystem
documentation when that appears in the Manual.
</remark>
@@ -17891,11 +17844,6 @@
<title>Description</title>
- <remark role="todo">
- [js] Remove references to Disk Data objects from the
- following narrative for the 4.1 and 5.0 versions.
- </remark>
-
<para>
<command>ndb_show_tables</command> displays a list of all
<literal>NDB</literal> database objects in the cluster. By
@@ -23299,15 +23247,6 @@
<title>Temporary errors</title>
<para>
- <remark>
- We need to add visual markup (CSS etc.) for the
- errortext element. /SH
-
- <remark>
- [js] Sent MC an email asking for help with this.
- </remark>
- </remark>
-
When first starting a node, it is possible that you may
see Error 1204 <errortext>Temporary failure,
distribution changed</errortext> and similar temporary
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r7467 - in trunk: refman-4.1 refman-5.0 refman-5.1 refman-5.2 | jon | 17 Aug |
