List:Commits« Previous MessageNext Message »
From:paul Date:January 30 2006 12:03am
Subject:svn commit - mysqldoc@docsrva: r1113 - in trunk: . refman-4.1 refman-5.0 refman-5.1
View as plain text  
Author: paul
Date: 2006-01-30 01:03:51 +0100 (Mon, 30 Jan 2006)
New Revision: 1113

Log:
 r6880@frost:  paul | 2006-01-29 18:03:39 -0600
 General revisions.


Modified:
   trunk/
   trunk/refman-4.1/replication.xml
   trunk/refman-5.0/replication.xml
   trunk/refman-5.1/replication.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6876
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6880
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588

Modified: trunk/refman-4.1/replication.xml
===================================================================
--- trunk/refman-4.1/replication.xml	2006-01-29 22:55:04 UTC (rev 1112)
+++ trunk/refman-4.1/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
@@ -1744,21 +1744,23 @@
           <listitem>
             <para>
               If the master is older than MySQL 4.1.3, the character set
-              of the session should never be made different from its
-              global value (in other words, do not use <literal>SET
-              NAMES</literal>, <literal>SET CHARACTER SET</literal>, and
-              so on) because this character set change is not known to
-              the slave. If both the master and the slave are 4.1.3 or
-              newer, the session can freely set local values for
-              character set variables (such as <literal>NAMES</literal>,
-              <literal>CHARACTER SET</literal>,
-              <literal>COLLATION_CLIENT</literal>, and
-              <literal>COLLATION_SERVER</literal>) as these settings are
-              written to the binary log and so known to the slave.
-              However, the session is prevented from changing the
-              <emphasis role="bold">global</emphasis> value of these; as
-              stated previously, the master and slave must always have
-              identical global character set values.
+              of any client should never be made different from its
+              global value because this character set change is not
+              known to the slave. In other words, clients should not use
+              <literal>SET NAMES</literal>, <literal>SET CHARACTER
+              SET</literal>, and so forth. If both the master and the
+              slave are 4.1.3 or newer, clients can freely set session
+              values for character set variables because these settings
+              are written to the binary log and so are known to the
+              slave. That is, clients can use <literal>SET
+              NAMES</literal> or <literal>SET CHARACTER SET</literal> or
+              can set variables such as
+              <literal>COLLATION_CLIENT</literal> or
+              <literal>COLLATION_SERVER</literal>. However, clients are
+              prevented from changing the <emphasis>global</emphasis>
+              value of these variables; as stated previously, the master
+              and slave must always have identical global character set
+              values.
             </para>
           </listitem>
 
@@ -1787,11 +1789,12 @@
 
       <listitem>
         <para>
-          For both master and slave the same system time zone should be
-          set. Otherwise some statements, for example statements using
+          The same system time zone should be set for both master and
+          slave. Otherwise some statements will not be replicated
+          properly, such as statements that use the
           <literal>NOW()</literal> or <literal>FROM_UNIXTIME()</literal>
-          functions, won't be replicated properly. One could set the
-          time zone in which MySQL server runs by using the
+          functions. You can set the time zone in which MySQL server
+          runs by using the
           <option>--timezone=<replaceable>timezone_name</replaceable></option>
           option of the <filename>mysqld_safe</filename> script or by
           setting the <literal>TZ</literal> environment variable. Also
@@ -1824,13 +1827,17 @@
           Check on the restart issue...
         </remark>
 
+        <remark role="todo">
+          [pd] Is this a promise we want to make?
+        </remark>
+
         <para>
           It is possible to replicate transactional tables on the master
           using non-transactional tables on the slave. For example, you
           can replicate an <literal>InnoDB</literal> master table as a
           <literal>MyISAM</literal> slave table. However, if you do
           this, there are problems if the slave is stopped in the middle
-          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block,
+          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block
           because the slave restarts at the beginning of the
           <literal>BEGIN</literal> block. This issue is on our TODO and
           will be fixed in the near future.
@@ -1839,8 +1846,8 @@
 
       <listitem>
         <para>
-          Update statements that refer to user variables (that is,
-          variables of the form
+          Update statements that refer to user-defined variables (that
+          is, variables of the form
           <literal>@<replaceable>var_name</replaceable></literal>) are
           badly replicated in 3.23 and 4.0. This is fixed in 4.1.
         </para>
@@ -1858,16 +1865,16 @@
           Starting from MySQL 4.1.11, there is a global system variable
           <literal>slave_transaction_retries</literal>: If the
           replication slave SQL thread fails to execute a transaction
-          because of an <literal>InnoDB</literal> deadlock or exceeded
-          <literal>InnoDB</literal>'s
-          <literal>innodb_lock_wait_timeout</literal> or NDBCluster's
+          because of an <literal>InnoDB</literal> deadlock or because it
+          exceeded the <literal>InnoDB</literal>
+          <literal>innodb_lock_wait_timeout</literal> or the NDBCluster
           <literal>TransactionDeadlockDetectionTimeout</literal> or
-          <literal>TransactionInactiveTimeout</literal>, it
-          automatically retries
+          <literal>TransactionInactiveTimeout</literal> value, the
+          transaction automatically retries
           <literal>slave_transaction_retries</literal> times before
           stopping with an error. The default value is 0 in MySQL 4.1.
-          Starting from MySQL 4.1.11, the total count of retries can be
-          seen in <literal>SHOW STATUS</literal>; see
+          Starting from MySQL 4.1.11, the total retry count can be seen
+          in <literal>SHOW STATUS</literal>; see
           <xref linkend="server-status-variables"/>.
         </para>
       </listitem>
@@ -1875,18 +1882,19 @@
       <listitem>
         <para>
           If a <literal>DATA DIRECTORY</literal> or <literal>INDEX
-          DIRECTORY</literal> clause is used in a <literal>CREATE
-          TABLE</literal> statement on the master server, the clause is
-          also used on the slave. This can cause problems if no
-          corresponding directory exists in the slave host filesystem or
-          exists but is not accessible to the slave server. Starting
-          from MySQL 4.0.15, there is a <literal>sql_mode</literal>
+          DIRECTORY</literal> table option is used in a <literal>CREATE
+          TABLE</literal> statement on the master server, the table
+          option is also used on the slave. This can cause problems if
+          no corresponding directory exists in the slave host filesystem
+          or if it exists but is not accessible to the slave server. As
+          of MySQL 4.0.15, there is an <literal>sql_mode</literal>
           option called <literal>NO_DIR_IN_CREATE</literal>. If the
-          slave server is run with its SQL mode set to include this
-          option, it ignores the clauses before replicating the
-          <literal>CREATE TABLE</literal> statement. The result is that
-          the <literal>MyISAM</literal> data and index files are created
-          in the table's database directory.
+          slave server is run with this SQL mode enabled, it ignores the
+          <literal>DATA DIRECTORY</literal> and <literal>INDEX
+          DIRECTORY</literal> table options when replicating
+          <literal>CREATE TABLE</literal> statements. The result is that
+          <literal>MyISAM</literal> data and index files are created in
+          the table's database directory.
         </para>
       </listitem>
 
@@ -1917,30 +1925,30 @@
 
       <listitem>
         <para>
-          Before MySQL 4.1.1, <literal>FLUSH</literal>, <literal>ANALYZE
-          TABLE</literal>, <literal>OPTIMIZE TABLE</literal>, and
-          <literal>REPAIR TABLE</literal> statements are not written to
-          the binary log and thus are not replicated to the slaves. This
-          is not normally a problem because these statements do not
-          modify table data. However, it can cause difficulties under
-          certain circumstances. If you replicate the privilege tables
-          in the <literal>mysql</literal> database and update those
-          tables directly without using the <literal>GRANT</literal>
-          statement, you must issue a <literal>FLUSH
-          PRIVILEGES</literal> statement on your slaves to put the new
-          privileges into effect. Also if you use <literal>FLUSH
-          TABLES</literal> when renaming a <literal>MyISAM</literal>
-          table that is part of a <literal>MERGE</literal> table, you
-          have to issue <literal>FLUSH TABLES</literal> manually on the
-          slaves. As of MySQL 4.1.1, these statements are written to the
-          binary log (unless you specify
-          <literal>NO_WRITE_TO_BINLOG</literal>, or its alias
-          <literal>LOCAL</literal>). Exceptions are that <literal>FLUSH
-          LOGS</literal>, <literal>FLUSH MASTER</literal>,
-          <literal>FLUSH SLAVE</literal>, and <literal>FLUSH TABLES WITH
-          READ LOCK</literal> are not logged in any case. (Any of these
-          may cause problems if replicated to a slave.) For a syntax
-          example, see <xref linkend="flush"/>.
+          Before MySQL 4.1.1, the <literal>FLUSH</literal>,
+          <literal>ANALYZE TABLE</literal>, <literal>OPTIMIZE
+          TABLE</literal>, and <literal>REPAIR TABLE</literal>
+          statements are not written to the binary log and thus are not
+          replicated to the slaves. This is not normally a problem
+          because these statements do not modify table data. However, it
+          can cause difficulties under certain circumstances. If you
+          replicate the privilege tables in the <literal>mysql</literal>
+          database and update those tables directly without using the
+          <literal>GRANT</literal> statement, you must issue a
+          <literal>FLUSH PRIVILEGES</literal> statement on your slaves
+          to put the new privileges into effect. Also if you use
+          <literal>FLUSH TABLES</literal> when renaming a
+          <literal>MyISAM</literal> table that is part of a
+          <literal>MERGE</literal> table, you have to issue
+          <literal>FLUSH TABLES</literal> manually on the slaves. As of
+          MySQL 4.1.1, these statements are written to the binary log
+          (unless you specify <literal>NO_WRITE_TO_BINLOG</literal>, or
+          its alias <literal>LOCAL</literal>). Exceptions are that
+          <literal>FLUSH LOGS</literal>, <literal>FLUSH
+          MASTER</literal>, <literal>FLUSH SLAVE</literal>, and
+          <literal>FLUSH TABLES WITH READ LOCK</literal> are not logged
+          in any case. (Any of these may cause problems if replicated to
+          a slave.) For a syntax example, see <xref linkend="flush"/>.
         </para>
       </listitem>
 
@@ -1956,12 +1964,12 @@
           When a server shuts down and restarts, its
           <literal>MEMORY</literal> (<literal>HEAP</literal>) tables
           become empty. As of MySQL 4.0.18, the master replicates this
-          effect as follows: The first time that the master uses each
-          <literal>MEMORY</literal> table after startup, it notifies
-          slaves that the table needs to be emptied by writing a
-          <literal>DELETE</literal> statement for that table to the
-          binary log. See <xref linkend="memory-storage-engine"/>, for
-          more information.
+          effect to slaves as follows: The first time that the master
+          uses each <literal>MEMORY</literal> table after startup, it
+          logs an event that notifies the slaves that the table needs to
+          be emptied by writing a <literal>DELETE</literal> statement
+          for that table to the binary log. See
+          <xref linkend="memory-storage-engine"/>, for more information.
         </para>
       </listitem>
 
@@ -1995,7 +2003,7 @@
           <listitem>
             <para>
               If the value is 0, issue a <command>mysqladmin
-              shutdown</command> command to shut down the slave.
+              shutdown</command> command to stop the slave.
             </para>
           </listitem>
 
@@ -2008,13 +2016,18 @@
 
           <listitem>
             <para>
-              Repeat the procedure later to see whether you have better
-              luck next time.
+              Repeat the procedure later until the
+              <literal>Slave_open_temp_tables</literal> variable is 0
+              and you can stop the slave.
             </para>
           </listitem>
 
         </orderedlist>
 
+        <remark role="todo">
+          [pd] Is this a promise we should make?
+        </remark>
+
         <para>
           We plan to fix this problem in the near future.
         </para>
@@ -2023,18 +2036,11 @@
       <listitem>
         <para>
           It is safe to connect servers in a circular master/slave
-          relationship with the <option>--log-slave-updates</option>
-          option specified. Note, however, that many statements do not
-          work correctly in this kind of setup unless your client code
-          is written to take care of the potential problems that can
-          occur from updates that occur in different sequence on
-          different servers.
+          relationship if you use the
+          <option>--log-slave-updates</option> option. That means that
+          you can create a setup such as this:
         </para>
 
-        <para>
-          This means that you can create a setup such as this:
-        </para>
-
         <remark role="todo">
           Create a figure for this.
         </remark>
@@ -2044,6 +2050,13 @@
 </programlisting>
 
         <para>
+          However, many statements do not work correctly in this kind of
+          setup unless your client code is written to take care of the
+          potential problems that can occur from updates that occur in
+          different sequence on different servers.
+        </para>
+
+        <para>
           Server IDs are encoded in binary log events, so server A knows
           when an event that it reads was originally created by itself
           and does not execute the event (unless server A was started
@@ -2061,25 +2074,26 @@
 
       <listitem>
         <para>
-          If a statement on the slave produces an error, the slave SQL
+          If a statement on a slave produces an error, the slave SQL
           thread terminates, and the slave writes a message to its error
-          log. You should then connect to the slave manually, fix the
-          problem (for example, a non-existent table), and then run
-          <literal>START SLAVE</literal>.
+          log. You should then connect to the slave manually and
+          determine the cause of the problem. (<literal>SHOW SLAVE
+          STATUS</literal> is useful for this.) Then fix the problem
+          (for example, you might need to create a non-existent table)
+          and run <literal>START SLAVE</literal>.
         </para>
       </listitem>
 
       <listitem>
         <para>
           It is safe to shut down a master server and restart it later.
-          If a slave loses its connection to the master, the slave tries
-          to reconnect immediately. If that fails, the slave retries
-          periodically. (The default is to retry every 60 seconds. This
-          may be changed with the
-          <option>--master-connect-retry</option> option.) The slave
-          also is able to deal with network connectivity outages.
-          However, the slave does notice the network outage only after
-          receiving no data from the master for
+          When a slave loses its connection to the master, the slave
+          tries to reconnect immediately and retries periodically if
+          that fails. The default is to retry every 60 seconds. This may
+          be changed with the <option>--master-connect-retry</option>
+          option. A slave also is able to deal with network connectivity
+          outages. However, the slave notices the network outage only
+          after receiving no data from the master for
           <literal>slave_net_timeout</literal> seconds. If your outages
           are short, you may want to decrease
           <literal>slave_net_timeout</literal>. See
@@ -2089,14 +2103,14 @@
 
       <listitem>
         <para>
-          Shutting down the slave (cleanly) is also safe, as it keeps
-          track of where it left off. Unclean shutdowns might produce
-          problems, especially if disk cache was not flushed to disk
-          before the system went down. Your system fault tolerance is
-          greatly increased if you have a good uninterruptible power
-          supply. Unclean shutdowns of the master may cause
-          inconsistencies between the content of tables and the binary
-          log in master; this can be avoided by using
+          Shutting down the slave (cleanly) is also safe because it
+          keeps track of where it left off. Unclean shutdowns might
+          produce problems, especially if the disk cache was not flushed
+          to disk before the system went down. Your system fault
+          tolerance is greatly increased if you have a good
+          uninterruptible power supply. Unclean shutdowns of the master
+          may cause inconsistencies between the content of tables and
+          the binary log in master; this can be avoided by using
           <literal>InnoDB</literal> tables and the
           <option>--innodb-safe-binlog</option> option on the master.
           See <xref linkend="binary-log"/>.
@@ -2113,10 +2127,10 @@
           long update statement is killed after updating some of the
           rows. If that happens on the master, the slave thread exits
           and waits for the database administrator to decide what to do
-          about it unless the error code is legitimate and the statement
-          execution results in the same error code. If this error code
-          validation behavior is not desirable, some or all errors can
-          be masked out (ignored) with the
+          about it unless the error code is legitimate and execution of
+          the statement results in the same error code on the slave. If
+          this error code validation behavior is not desirable, some or
+          all errors can be masked out (ignored) with the
           <option>--slave-skip-errors</option> option. This option is
           available starting with MySQL 3.23.47.
         </para>
@@ -2127,10 +2141,10 @@
           If you update transactional tables from non-transactional
           tables inside a
           <literal>BEGIN</literal>/<literal>COMMIT</literal> sequence,
-          updates to the binary log may be out of synchrony if the
-          non-transactional table is updated before the transaction
-          commits. This is because the transaction is written to the
-          binary log only when it is committed.
+          updates to the binary log may be out of synchrony with table
+          states if the non-transactional table is updated before the
+          transaction commits. This occurs because the transaction is
+          written to the binary log only when it is committed.
         </para>
       </listitem>
 
@@ -2144,16 +2158,20 @@
           when updating both transactional tables and non-transactional
           tables within the same transaction. (This is true not only for
           replication, but also if you are using binary logging for
-          backups.) In version 4.0.15, we changed the logging behavior
-          for transactions that mix updates to transactional and
+          backups.)
+        </para>
+
+        <para>
+          As of version 4.0.15, we changed the logging behavior for
+          transactions that mix updates to transactional and
           non-transactional tables, which solves the problems (order of
           statements is good in the binary log, and all needed
           statements are written to the binary log even in case of
-          <literal>ROLLBACK</literal>). The problem that remains is when
-          a second connection updates the non-transactional table while
-          the first connection's transaction is not finished yet; wrong
-          order can still occur, because the second connection's update
-          is written immediately after it is done.
+          <literal>ROLLBACK</literal>). The problem that remains is that
+          when a second connection updates the non-transactional table
+          while the first connection's transaction is not finished yet,
+          incorrect ordering can still occur because the second
+          connection's update is written immediately after it is done.
         </para>
       </listitem>
 

Modified: trunk/refman-5.0/replication.xml
===================================================================
--- trunk/refman-5.0/replication.xml	2006-01-29 22:55:04 UTC (rev 1112)
+++ trunk/refman-5.0/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
@@ -1691,21 +1691,23 @@
           <listitem>
             <para>
               If the master is older than MySQL 4.1.3, the character set
-              of the session should never be made different from its
-              global value (in other words, do not use <literal>SET
-              NAMES</literal>, <literal>SET CHARACTER SET</literal>, and
-              so on) because this character set change is not known to
-              the slave. If both the master and the slave are 4.1.3 or
-              newer, the session can freely set local values for
-              character set variables (such as <literal>NAMES</literal>,
-              <literal>CHARACTER SET</literal>,
-              <literal>COLLATION_CLIENT</literal>, and
-              <literal>COLLATION_SERVER</literal>) as these settings are
-              written to the binary log and so known to the slave.
-              However, the session is prevented from changing the
-              <emphasis role="bold">global</emphasis> value of these; as
-              stated previously, the master and slave must always have
-              identical global character set values.
+              of any client should never be made different from its
+              global value because this character set change is not
+              known to the slave. In other words, clients should not use
+              <literal>SET NAMES</literal>, <literal>SET CHARACTER
+              SET</literal>, and so forth. If both the master and the
+              slave are 4.1.3 or newer, clients can freely set session
+              values for character set variables because these settings
+              are written to the binary log and so are known to the
+              slave. That is, clients can use <literal>SET
+              NAMES</literal> or <literal>SET CHARACTER SET</literal> or
+              can set variables such as
+              <literal>COLLATION_CLIENT</literal> or
+              <literal>COLLATION_SERVER</literal>. However, clients are
+              prevented from changing the <emphasis>global</emphasis>
+              value of these variables; as stated previously, the master
+              and slave must always have identical global character set
+              values.
             </para>
           </listitem>
 
@@ -1717,14 +1719,14 @@
             </remark>
 
             <para>
-              If on the master you have databases with different
-              character sets from the global
-              <literal>collation_server</literal> value, you should
+              If you have databases on the master with character sets
+              that differ from the global
+              <literal>character_set_server</literal> value, you should
               design your <literal>CREATE TABLE</literal> statements so
-              that they do not implicitly rely on the databases' default
-              character sets (Bug #2326); a good workaround is to state
-              the character set and collation explicitly in
-              <literal>CREATE TABLE</literal>.
+              that tables in those databases do not implicitly rely on
+              the database default character set (see Bug #2326). A good
+              workaround is to state the character set and collation
+              explicitly in <literal>CREATE TABLE</literal>.
             </para>
           </listitem>
 
@@ -1733,11 +1735,12 @@
 
       <listitem>
         <para>
-          For both master and slave the same system time zone should be
-          set. Otherwise some statements, for example statements using
+          The same system time zone should be set for both master and
+          slave. Otherwise some statements will not be replicated
+          properly, such as statements that use the
           <literal>NOW()</literal> or <literal>FROM_UNIXTIME()</literal>
-          functions, won't be replicated properly. One could set the
-          time zone in which MySQL server runs by using the
+          functions. You can set the time zone in which MySQL server
+          runs by using the
           <option>--timezone=<replaceable>timezone_name</replaceable></option>
           option of the <filename>mysqld_safe</filename> script or by
           setting the <literal>TZ</literal> environment variable. Both
@@ -1753,21 +1756,22 @@
           <literal>CONVERT_TZ(...,...,@global.time_zone)</literal> is
           not properly replicated.
           <literal>CONVERT_TZ(...,...,@session.time_zone)</literal> is
-          properly replicated only if master and slave are 5.0.4 or
-          newer.
+          properly replicated only if the master and slave are from
+          MySQL 5.0.4 or newer.
         </para>
       </listitem>
 
       <listitem>
         <para>
           Session variables are not replicated properly when used in
-          statements which update tables; for example: <literal>SET
-          MAX_JOIN_SIZE=1000; INSERT INTO mytable
-          VALUES(@MAX_JOIN_SIZE);</literal> will not insert the same
-          data on master and on slave. This does not apply to the common
-          <literal>SET TIME_ZONE=...; INSERT INTO mytable
-          VALUES(CONVERT_TZ(...,...,@time_zone))</literal>, which is
-          fixed in MySQL 5.0.4.
+          statements that update tables. For example, <literal>SET
+          MAX_JOIN_SIZE=1000</literal> followed by <literal>INSERT INTO
+          mytable VALUES(@MAX_JOIN_SIZE)</literal> will not insert the
+          same data on the master and the slave. This does not apply to
+          the common sequence of <literal>SET TIME_ZONE=...</literal>
+          followed by <literal>INSERT INTO mytable
+          VALUES(CONVERT_TZ(...,...,@time_zone))</literal>, which
+          replicates correctly as of MySQL 5.0.4.
         </para>
       </listitem>
 
@@ -1776,13 +1780,17 @@
           Check on the restart issue...
         </remark>
 
+        <remark role="todo">
+          [pd] Is this a promise we want to make?
+        </remark>
+
         <para>
           It is possible to replicate transactional tables on the master
           using non-transactional tables on the slave. For example, you
           can replicate an <literal>InnoDB</literal> master table as a
           <literal>MyISAM</literal> slave table. However, if you do
           this, there are problems if the slave is stopped in the middle
-          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block,
+          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block
           because the slave restarts at the beginning of the
           <literal>BEGIN</literal> block. This issue is on our TODO and
           will be fixed in the near future.
@@ -1791,14 +1799,14 @@
 
       <listitem>
         <para>
-          Update statements that refer to user variables (that is,
-          variables of the form
+          Update statements that refer to user-defined variables (that
+          is, variables of the form
           <literal>@<replaceable>var_name</replaceable></literal>) are
           replicated correctly in MySQL &current-series;; however this
           is not true for versions prior to 4.1. Note that user variable
-          names are case insensitive starting in MySQL &current-series;;
-          you should take this into account when setting up replication
-          between &current-series; and older versions.
+          names are case insensitive starting in MySQL 5.0. you should
+          take this into account when setting up replication between
+          MySQL 5.0 and older versions.
         </para>
       </listitem>
 
@@ -1814,16 +1822,16 @@
           global system variable
           <literal>slave_transaction_retries</literal>: If the
           replication slave SQL thread fails to execute a transaction
-          because of an <literal>InnoDB</literal> deadlock or exceeded
-          <literal>InnoDB</literal>'s
-          <literal>innodb_lock_wait_timeout</literal> or NDBCluster's
+          because of an <literal>InnoDB</literal> deadlock or because it
+          exceeded the <literal>InnoDB</literal>
+          <literal>innodb_lock_wait_timeout</literal> or the NDBCluster
           <literal>TransactionDeadlockDetectionTimeout</literal> or
-          <literal>TransactionInactiveTimeout</literal>, it
-          automatically retries
+          <literal>TransactionInactiveTimeout</literal> value, the
+          transaction automatically retries
           <literal>slave_transaction_retries</literal> times before
           stopping with an error. The default value is 10. Starting from
-          MySQL 5.0.4, the total count of retries can be seen in the
-          output of <literal>SHOW STATUS</literal>; see
+          MySQL 5.0.4, the total retry count can be seen in the output
+          of <literal>SHOW STATUS</literal>; see
           <xref linkend="server-status-variables"/>.
         </para>
       </listitem>
@@ -1831,18 +1839,18 @@
       <listitem>
         <para>
           If a <literal>DATA DIRECTORY</literal> or <literal>INDEX
-          DIRECTORY</literal> clause is used in a <literal>CREATE
-          TABLE</literal> statement on the master server, the clause is
-          also used on the slave. This can cause problems if no
-          corresponding directory exists in the slave host filesystem or
-          exists but is not accessible to the slave server. MySQL
-          &current-series; supports an <literal>sql_mode</literal>
-          option called <literal>NO_DIR_IN_CREATE</literal>. If the
-          slave server is run with its SQL mode set to include this
-          option, it ignores these clauses in replicating the
-          <literal>CREATE TABLE</literal> statement. The result is that
-          <literal>MyISAM</literal> data and index files are created in
-          the table's database directory.
+          DIRECTORY</literal> table option is used in a <literal>CREATE
+          TABLE</literal> statement on the master server, the table
+          option is also used on the slave. This can cause problems if
+          no corresponding directory exists in the slave host filesystem
+          or if it exists but is not accessible to the slave server.
+          MySQL supports an <literal>sql_mode</literal> option called
+          <literal>NO_DIR_IN_CREATE</literal>. If the slave server is
+          run with this SQL mode enabled, it ignores the <literal>DATA
+          DIRECTORY</literal> and <literal>INDEX DIRECTORY</literal>
+          table options when replicating <literal>CREATE TABLE</literal>
+          statements. The result is that <literal>MyISAM</literal> data
+          and index files are created in the table's database directory.
         </para>
       </listitem>
 
@@ -1875,28 +1883,28 @@
 
       <listitem>
         <para>
-          <literal>FLUSH LOGS</literal>, <literal>FLUSH
+          The <literal>FLUSH LOGS</literal>, <literal>FLUSH
           MASTER</literal>, <literal>FLUSH SLAVE</literal>, and
-          <literal>FLUSH TABLES WITH READ LOCK</literal> are not logged,
-          as any of these could cause problems if replicated to a
-          slave.) For a syntax example, see <xref linkend="flush"/>.
-          <literal>FLUSH TABLES</literal>, <literal>ANALYZE
-          TABLE</literal>, <literal>OPTIMIZE TABLE</literal>, and
-          <literal>REPAIR TABLE</literal> statements are written to the
-          binary log and thus replicated to slaves. This is not normally
-          a problem because these statements do not modify table data.
-          However, this can cause difficulties under certain
-          circumstances. If you replicate the privilege tables in the
-          <literal>mysql</literal> database and update those tables
-          directly without using <literal>GRANT</literal>, you must
-          issue a <literal>FLUSH PRIVILEGES</literal> on the slaves to
-          put the new privileges into effect. In addition, if you use
-          <literal>FLUSH TABLES</literal> when renaming a
-          <literal>MyISAM</literal> table that is part of a
-          <literal>MERGE</literal> table, you must issue <literal>FLUSH
-          TABLES</literal> manually on the slaves. These statements are
-          written to the binary log unless you specify
-          <literal>NO_WRITE_TO_BINLOG</literal> or its alias
+          <literal>FLUSH TABLES WITH READ LOCK</literal> statements are
+          not logged because any of these could cause problems if
+          replicated to a slave. For a syntax example, see
+          <xref linkend="flush"/>. The <literal>FLUSH TABLES</literal>,
+          <literal>ANALYZE TABLE</literal>, <literal>OPTIMIZE
+          TABLE</literal>, and <literal>REPAIR TABLE</literal>
+          statements are written to the binary log and thus replicated
+          to slaves. This is not normally a problem because these
+          statements do not modify table data. However, this can cause
+          difficulties under certain circumstances. If you replicate the
+          privilege tables in the <literal>mysql</literal> database and
+          update those tables directly without using
+          <literal>GRANT</literal>, you must issue a <literal>FLUSH
+          PRIVILEGES</literal> on the slaves to put the new privileges
+          into effect. In addition, if you use <literal>FLUSH
+          TABLES</literal> when renaming a <literal>MyISAM</literal>
+          table that is part of a <literal>MERGE</literal> table, you
+          must issue <literal>FLUSH TABLES</literal> manually on the
+          slaves. These statements are written to the binary log unless
+          you specify <literal>NO_WRITE_TO_BINLOG</literal> or its alias
           <literal>LOCAL</literal>.
         </para>
       </listitem>
@@ -1916,13 +1924,13 @@
         <para>
           When a server shuts down and restarts, its
           <literal>MEMORY</literal> (<literal>HEAP</literal> tables
-          become empty. The master replicates this effect as follows:
-          The first time that the master uses each
-          <literal>MEMORY</literal> table after startup, it notifies the
-          slaves that the table needs to be emptied by writing a
-          <literal>DELETE</literal> statement for that table to the
-          binary log. See <xref linkend="memory-storage-engine"/>, for
-          more information.
+          become empty. The master replicates this effect to slaves as
+          follows: The first time that the master uses each
+          <literal>MEMORY</literal> table after startup, it logs an
+          event that notifies the slaves that the table needs to be
+          emptied by writing a <literal>DELETE</literal> statement for
+          that table to the binary log. See
+          <xref linkend="memory-storage-engine"/>, for more information.
         </para>
       </listitem>
 
@@ -1956,7 +1964,7 @@
           <listitem>
             <para>
               If the value is 0, issue a <command>mysqladmin
-              shutdown</command> command to shut down the slave.
+              shutdown</command> command to stop the slave.
             </para>
           </listitem>
 
@@ -1969,13 +1977,18 @@
 
           <listitem>
             <para>
-              Repeat the procedure later to see whether you have better
-              luck next time.
+              Repeat the procedure later until the
+              <literal>Slave_open_temp_tables</literal> variable is 0
+              and you can stop the slave.
             </para>
           </listitem>
 
         </orderedlist>
 
+        <remark role="todo">
+          [pd] Is this a promise we should make?
+        </remark>
+
         <para>
           We plan to fix this problem in the near future.
         </para>
@@ -1984,18 +1997,11 @@
       <listitem>
         <para>
           It is safe to connect servers in a circular master/slave
-          relationship with the <option>--log-slave-updates</option>
-          option specified. Note, however, that many statements do not
-          work correctly in this kind of setup unless your client code
-          is written to take care of the potential problems that can
-          occur from updates that occur in different sequence on
-          different servers.
+          relationship if you use the
+          <option>--log-slave-updates</option> option. That means that
+          you can create a setup such as this:
         </para>
 
-        <para>
-          This means that you can create a setup such as this:
-        </para>
-
         <remark role="todo">
           Create a figure for this.
         </remark>
@@ -2005,6 +2011,13 @@
 </programlisting>
 
         <para>
+          However, many statements do not work correctly in this kind of
+          setup unless your client code is written to take care of the
+          potential problems that can occur from updates that occur in
+          different sequence on different servers.
+        </para>
+
+        <para>
           Server IDs are encoded in binary log events, so server A knows
           when an event that it reads was originally created by itself
           and does not execute the event (unless server A was started
@@ -2022,25 +2035,26 @@
 
       <listitem>
         <para>
-          If a statement on the slave produces an error, the slave SQL
+          If a statement on a slave produces an error, the slave SQL
           thread terminates, and the slave writes a message to its error
-          log. You should then connect to the slave manually, fix the
-          problem (for example, a non-existent table), and then run
-          <literal>START SLAVE</literal>.
+          log. You should then connect to the slave manually and
+          determine the cause of the problem. (<literal>SHOW SLAVE
+          STATUS</literal> is useful for this.) Then fix the problem
+          (for example, you might need to create a non-existent table)
+          and run <literal>START SLAVE</literal>.
         </para>
       </listitem>
 
       <listitem>
         <para>
           It is safe to shut down a master server and restart it later.
-          If a slave loses its connection to the master, the slave tries
-          to reconnect immediately. If that fails, the slave retries
-          periodically. (The default is to retry every 60 seconds. This
-          may be changed with the
-          <option>--master-connect-retry</option> option.) The slave
-          also is able to deal with network connectivity outages.
-          However, the slave does notice the network outage only after
-          receiving no data from the master for
+          When a slave loses its connection to the master, the slave
+          tries to reconnect immediately and retries periodically if
+          that fails. The default is to retry every 60 seconds. This may
+          be changed with the <option>--master-connect-retry</option>
+          option. A slave also is able to deal with network connectivity
+          outages. However, the slave notices the network outage only
+          after receiving no data from the master for
           <literal>slave_net_timeout</literal> seconds. If your outages
           are short, you may want to decrease
           <literal>slave_net_timeout</literal>. See
@@ -2050,22 +2064,25 @@
 
       <listitem>
         <para>
-          Shutting down the slave (cleanly) is also safe, as it keeps
-          track of where it left off. Unclean shutdowns might produce
-          problems, especially if disk cache was not flushed to disk
-          before the system went down. Your system fault tolerance is
-          greatly increased if you have a good uninterruptible power
-          supply. Unclean shutdowns of the master may cause
-          inconsistencies between the content of tables and the binary
-          log in master; this can be avoided by using
+          Shutting down the slave (cleanly) is also safe because it
+          keeps track of where it left off. Unclean shutdowns might
+          produce problems, especially if the disk cache was not flushed
+          to disk before the system went down. Your system fault
+          tolerance is greatly increased if you have a good
+          uninterruptible power supply. Unclean shutdowns of the master
+          may cause inconsistencies between the content of tables and
+          the binary log in master; this can be avoided by using
           <literal>InnoDB</literal> tables and the
           <option>--innodb-safe-binlog</option> option on the master.
           See <xref linkend="binary-log"/>.
-          (<emphasis
+        </para>
+
+        <para>
+          <emphasis
             role="bold">Note</emphasis>:
           <option>--innodb-safe-binlog</option> is unneeded as of MySQL
           5.0.3, having been made obsolete by the introduction of XA
-          transaction support.)
+          transaction support.
         </para>
       </listitem>
 
@@ -2079,10 +2096,10 @@
           long update statement is killed after updating some of the
           rows. If that happens on the master, the slave thread exits
           and waits for the database administrator to decide what to do
-          about it unless the error code is legitimate and the statement
-          execution results in the same error code. If this error code
-          validation behavior is not desirable, some or all errors can
-          be masked out (ignored) with the
+          about it unless the error code is legitimate and execution of
+          the statement results in the same error code on the slave. If
+          this error code validation behavior is not desirable, some or
+          all errors can be masked out (ignored) with the
           <option>--slave-skip-errors</option> option.
         </para>
       </listitem>
@@ -2092,25 +2109,26 @@
           If you update transactional tables from non-transactional
           tables inside a
           <literal>BEGIN</literal>/<literal>COMMIT</literal> sequence,
-          updates to the binary log may be out of synchrony if the
-          non-transactional table is updated before the transaction
-          commits. This is because the transaction is written to the
-          binary log only when it is committed.
+          updates to the binary log may be out of synchrony with table
+          states if the non-transactional table is updated before the
+          transaction commits. This occurs because the transaction is
+          written to the binary log only when it is committed.
         </para>
       </listitem>
 
       <listitem>
         <para>
           In situations where transactions mix updates to transactional
-          and non-transactional, the order of statements in the binary
-          log is correct, and all needed statements are written to the
-          binary log even in case of a <literal>ROLLBACK</literal>).
-          However, when a second connection updates the
-          non-transactional table before the first connection's
-          transaction is complete, statements can be logged out of
-          order, because the second connection's update is written
-          immediately after it is performed, regardless of the state of
-          the transaction being performed by the first connection.
+          and non-transactional tables, the order of statements in the
+          binary log is correct, and all needed statements are written
+          to the binary log even in case of a
+          <literal>ROLLBACK</literal>. However, when a second connection
+          updates the non-transactional table before the first
+          connection's transaction is complete, statements can be logged
+          out of order, because the second connection's update is
+          written immediately after it is performed, regardless of the
+          state of the transaction being performed by the first
+          connection.
         </para>
       </listitem>
 

Modified: trunk/refman-5.1/replication.xml
===================================================================
--- trunk/refman-5.1/replication.xml	2006-01-29 22:55:04 UTC (rev 1112)
+++ trunk/refman-5.1/replication.xml	2006-01-30 00:03:51 UTC (rev 1113)
@@ -1847,21 +1847,23 @@
           <listitem>
             <para>
               If the master is older than MySQL 4.1.3, the character set
-              of the session should never be made different from its
-              global value (in other words, do not use <literal>SET
-              NAMES</literal>, <literal>SET CHARACTER SET</literal>, and
-              so on) because this character set change is not known to
-              the slave. If both the master and the slave are 4.1.3 or
-              newer, the session can freely set local values for
-              character set variables (such as <literal>NAMES</literal>,
-              <literal>CHARACTER SET</literal>,
-              <literal>COLLATION_CLIENT</literal>, and
-              <literal>COLLATION_SERVER</literal>) as these settings are
-              written to the binary log and so known to the slave.
-              However, the session is prevented from changing the
-              <emphasis role="bold">global</emphasis> value of these; as
-              stated previously, the master and slave must always have
-              identical global character set values.
+              of any client should never be made different from its
+              global value because this character set change is not
+              known to the slave. In other words, clients should not use
+              <literal>SET NAMES</literal>, <literal>SET CHARACTER
+              SET</literal>, and so forth. If both the master and the
+              slave are 4.1.3 or newer, clients can freely set session
+              values for character set variables because these settings
+              are written to the binary log and so are known to the
+              slave. That is, clients can use <literal>SET
+              NAMES</literal> or <literal>SET CHARACTER SET</literal> or
+              can set variables such as
+              <literal>COLLATION_CLIENT</literal> or
+              <literal>COLLATION_SERVER</literal>. However, clients are
+              prevented from changing the <emphasis>global</emphasis>
+              value of these variables; as stated previously, the master
+              and slave must always have identical global character set
+              values.
             </para>
           </listitem>
 
@@ -1873,14 +1875,14 @@
             </remark>
 
             <para>
-              If on the master you have databases with different
-              character sets from the global
-              <literal>collation_server</literal> value, you should
+              If you have databases on the master with character sets
+              that differ from the global
+              <literal>character_set_server</literal> value, you should
               design your <literal>CREATE TABLE</literal> statements so
-              that they do not implicitly rely on the databases' default
-              character sets (Bug #2326); a good workaround is to state
-              the character set and collation explicitly in
-              <literal>CREATE TABLE</literal>.
+              that tables in those databases do not implicitly rely on
+              the database default character set (see Bug #2326). A good
+              workaround is to state the character set and collation
+              explicitly in <literal>CREATE TABLE</literal>.
             </para>
           </listitem>
 
@@ -1889,11 +1891,12 @@
 
       <listitem>
         <para>
-          For both master and slave the same system time zone should be
-          set. Otherwise some statements, for example statements using
+          The same system time zone should be set for both master and
+          slave. Otherwise some statements will not be replicated
+          properly, such as statements that use the
           <literal>NOW()</literal> or <literal>FROM_UNIXTIME()</literal>
-          functions, won't be replicated properly. One could set the
-          time zone in which MySQL server runs by using the
+          functions. You can set the time zone in which MySQL server
+          runs by using the
           <option>--timezone=<replaceable>timezone_name</replaceable></option>
           option of the <filename>mysqld_safe</filename> script or by
           setting the <literal>TZ</literal> environment variable. Both
@@ -1909,19 +1912,20 @@
           <literal>CONVERT_TZ(...,...,@global.time_zone)</literal> is
           not properly replicated.
           <literal>CONVERT_TZ(...,...,@session.time_zone)</literal> is
-          properly replicated only if master and slave are 5.0.4 or
-          newer.
+          properly replicated only if the master and slave are from
+          MySQL 5.0.4 or newer.
         </para>
       </listitem>
 
       <listitem>
         <para>
           Session variables are not replicated properly when used in
-          statements which update tables; for example: <literal>SET
-          MAX_JOIN_SIZE=1000; INSERT INTO mytable
-          VALUES(@MAX_JOIN_SIZE);</literal> will not insert the same
-          data on master and on slave. This does not apply to the common
-          <literal>SET TIME_ZONE=...; INSERT INTO mytable
+          statements that update tables. For example, <literal>SET
+          MAX_JOIN_SIZE=1000</literal> followed by <literal>INSERT INTO
+          mytable VALUES(@MAX_JOIN_SIZE)</literal> will not insert the
+          same data on the master and the slave. This does not apply to
+          the common sequence of <literal>SET TIME_ZONE=...</literal>
+          followed by <literal>INSERT INTO mytable
           VALUES(CONVERT_TZ(...,...,@time_zone))</literal>.
         </para>
       </listitem>
@@ -1931,13 +1935,17 @@
           Check on the restart issue...
         </remark>
 
+        <remark role="todo">
+          [pd] Is this a promise we want to make?
+        </remark>
+
         <para>
           It is possible to replicate transactional tables on the master
           using non-transactional tables on the slave. For example, you
           can replicate an <literal>InnoDB</literal> master table as a
           <literal>MyISAM</literal> slave table. However, if you do
           this, there are problems if the slave is stopped in the middle
-          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block,
+          of a <literal>BEGIN</literal>/<literal>COMMIT</literal> block
           because the slave restarts at the beginning of the
           <literal>BEGIN</literal> block. This issue is on our TODO and
           will be fixed in the near future.
@@ -1946,14 +1954,14 @@
 
       <listitem>
         <para>
-          Update statements that refer to user variables (that is,
-          variables of the form
+          Update statements that refer to user-defined variables (that
+          is, variables of the form
           <literal>@<replaceable>var_name</replaceable></literal>) are
           replicated correctly in MySQL &current-series;; however this
           is not true for versions prior to 4.1. Note that user variable
-          names are case insensitive starting in MySQL &current-series;;
-          you should take this into account when setting up replication
-          between &current-series; and older versions.
+          names are case insensitive starting in MySQL 5.0. you should
+          take this into account when setting up replication between
+          MySQL 5.0 and older versions.
         </para>
       </listitem>
 
@@ -1968,16 +1976,16 @@
           There is a global system variable
           <literal>slave_transaction_retries</literal>: If the
           replication slave SQL thread fails to execute a transaction
-          because of an <literal>InnoDB</literal> deadlock or exceeded
-          <literal>InnoDB</literal>'s
-          <literal>innodb_lock_wait_timeout</literal> or NDBCluster's
+          because of an <literal>InnoDB</literal> deadlock or because it
+          exceeded the <literal>InnoDB</literal>
+          <literal>innodb_lock_wait_timeout</literal> or the NDBCluster
           <literal>TransactionDeadlockDetectionTimeout</literal> or
-          <literal>TransactionInactiveTimeout</literal>, it
-          automatically retries
+          <literal>TransactionInactiveTimeout</literal> value, the
+          transaction automatically retries
           <literal>slave_transaction_retries</literal> times before
           stopping with an error. The default value is 10. Starting from
-          MySQL 5.0.4, the total count of retries can be seen in the
-          output of <literal>SHOW STATUS</literal>; see
+          MySQL 5.0.4, the total retry count can be seen in the output
+          of <literal>SHOW STATUS</literal>; see
           <xref linkend="server-status-variables"/>.
         </para>
       </listitem>
@@ -1985,18 +1993,18 @@
       <listitem>
         <para>
           If a <literal>DATA DIRECTORY</literal> or <literal>INDEX
-          DIRECTORY</literal> clause is used in a <literal>CREATE
-          TABLE</literal> statement on the master server, the clause is
-          also used on the slave. This can cause problems if no
-          corresponding directory exists in the slave host filesystem or
-          exists but is not accessible to the slave server. MySQL
-          &current-series; supports an <literal>sql_mode</literal>
-          option called <literal>NO_DIR_IN_CREATE</literal>. If the
-          slave server is run with its SQL mode set to include this
-          option, it ignores these clauses in replicating the
-          <literal>CREATE TABLE</literal> statement. The result is that
-          <literal>MyISAM</literal> data and index files are created in
-          the table's database directory.
+          DIRECTORY</literal> table option is used in a <literal>CREATE
+          TABLE</literal> statement on the master server, the table
+          option is also used on the slave. This can cause problems if
+          no corresponding directory exists in the slave host filesystem
+          or if it exists but is not accessible to the slave server.
+          MySQL supports an <literal>sql_mode</literal> option called
+          <literal>NO_DIR_IN_CREATE</literal>. If the slave server is
+          run with this SQL mode enabled, it ignores the <literal>DATA
+          DIRECTORY</literal> and <literal>INDEX DIRECTORY</literal>
+          table options when replicating <literal>CREATE TABLE</literal>
+          statements. The result is that <literal>MyISAM</literal> data
+          and index files are created in the table's database directory.
         </para>
       </listitem>
 
@@ -2015,28 +2023,28 @@
 
       <listitem>
         <para>
-          <literal>FLUSH LOGS</literal>, <literal>FLUSH
+          The <literal>FLUSH LOGS</literal>, <literal>FLUSH
           MASTER</literal>, <literal>FLUSH SLAVE</literal>, and
-          <literal>FLUSH TABLES WITH READ LOCK</literal> are not logged,
-          as any of these could cause problems if replicated to a
-          slave.) For a syntax example, see <xref linkend="flush"/>.
-          <literal>FLUSH TABLES</literal>, <literal>ANALYZE
-          TABLE</literal>, <literal>OPTIMIZE TABLE</literal>, and
-          <literal>REPAIR TABLE</literal> statements are written to the
-          binary log and thus replicated to slaves. This is not normally
-          a problem because these statements do not modify table data.
-          However, this can cause difficulties under certain
-          circumstances. If you replicate the privilege tables in the
-          <literal>mysql</literal> database and update those tables
-          directly without using <literal>GRANT</literal>, you must
-          issue a <literal>FLUSH PRIVILEGES</literal> on the slaves to
-          put the new privileges into effect. In addition, if you use
-          <literal>FLUSH TABLES</literal> when renaming a
-          <literal>MyISAM</literal> table that is part of a
-          <literal>MERGE</literal> table, you must issue <literal>FLUSH
-          TABLES</literal> manually on the slaves. These statements are
-          written to the binary log unless you specify
-          <literal>NO_WRITE_TO_BINLOG</literal> or its alias
+          <literal>FLUSH TABLES WITH READ LOCK</literal> statements are
+          not logged because any of these could cause problems if
+          replicated to a slave. For a syntax example, see
+          <xref linkend="flush"/>. The <literal>FLUSH TABLES</literal>,
+          <literal>ANALYZE TABLE</literal>, <literal>OPTIMIZE
+          TABLE</literal>, and <literal>REPAIR TABLE</literal>
+          statements are written to the binary log and thus replicated
+          to slaves. This is not normally a problem because these
+          statements do not modify table data. However, this can cause
+          difficulties under certain circumstances. If you replicate the
+          privilege tables in the <literal>mysql</literal> database and
+          update those tables directly without using
+          <literal>GRANT</literal>, you must issue a <literal>FLUSH
+          PRIVILEGES</literal> on the slaves to put the new privileges
+          into effect. In addition, if you use <literal>FLUSH
+          TABLES</literal> when renaming a <literal>MyISAM</literal>
+          table that is part of a <literal>MERGE</literal> table, you
+          must issue <literal>FLUSH TABLES</literal> manually on the
+          slaves. These statements are written to the binary log unless
+          you specify <literal>NO_WRITE_TO_BINLOG</literal> or its alias
           <literal>LOCAL</literal>.
         </para>
       </listitem>
@@ -2056,12 +2064,13 @@
         <para>
           When a server shuts down and restarts, its
           <literal>MEMORY</literal> tables become empty. The master
-          replicates this effect as follows: The first time that the
-          master uses each <literal>MEMORY</literal> table after
-          startup, it notifies the slaves that the table needs to be
-          emptied by writing a <literal>DELETE</literal> statement for
-          that table to the binary log. See
-          <xref linkend="memory-storage-engine"/>, for more information.
+          replicates this effect to slaves as follows: The first time
+          that the master uses each <literal>MEMORY</literal> table
+          after startup, it logs an event that notifies the slaves that
+          the table needs to be emptied by writing a
+          <literal>DELETE</literal> statement for that table to the
+          binary log. See <xref linkend="memory-storage-engine"/>, for
+          more information.
         </para>
       </listitem>
 
@@ -2095,7 +2104,7 @@
           <listitem>
             <para>
               If the value is 0, issue a <command>mysqladmin
-              shutdown</command> command to shut down the slave.
+              shutdown</command> command to stop the slave.
             </para>
           </listitem>
 
@@ -2108,13 +2117,18 @@
 
           <listitem>
             <para>
-              Repeat the procedure later to see whether you have better
-              luck next time.
+              Repeat the procedure later until the
+              <literal>Slave_open_temp_tables</literal> variable is 0
+              and you can stop the slave.
             </para>
           </listitem>
 
         </orderedlist>
 
+        <remark role="todo">
+          [pd] Is this a promise we should make?
+        </remark>
+
         <para>
           We plan to fix this problem in the near future.
         </para>
@@ -2123,18 +2137,11 @@
       <listitem>
         <para>
           It is safe to connect servers in a circular master/slave
-          relationship with the <option>--log-slave-updates</option>
-          option specified. Note, however, that many statements do not
-          work correctly in this kind of setup unless your client code
-          is written to take care of the potential problems that can
-          occur from updates that occur in different sequence on
-          different servers.
+          relationship if you use the
+          <option>--log-slave-updates</option> option. That means that
+          you can create a setup such as this:
         </para>
 
-        <para>
-          This means that you can create a setup such as this:
-        </para>
-
         <remark role="todo">
           Create a figure for this.
         </remark>
@@ -2144,6 +2151,13 @@
 </programlisting>
 
         <para>
+          However, many statements do not work correctly in this kind of
+          setup unless your client code is written to take care of the
+          potential problems that can occur from updates that occur in
+          different sequence on different servers.
+        </para>
+
+        <para>
           Server IDs are encoded in binary log events, so server A knows
           when an event that it reads was originally created by itself
           and does not execute the event (unless server A was started
@@ -2161,25 +2175,26 @@
 
       <listitem>
         <para>
-          If a statement on the slave produces an error, the slave SQL
+          If a statement on a slave produces an error, the slave SQL
           thread terminates, and the slave writes a message to its error
-          log. You should then connect to the slave manually, fix the
-          problem (for example, a non-existent table), and then run
-          <literal>START SLAVE</literal>.
+          log. You should then connect to the slave manually and
+          determine the cause of the problem. (<literal>SHOW SLAVE
+          STATUS</literal> is useful for this.) Then fix the problem
+          (for example, you might need to create a non-existent table)
+          and run <literal>START SLAVE</literal>.
         </para>
       </listitem>
 
       <listitem>
         <para>
           It is safe to shut down a master server and restart it later.
-          If a slave loses its connection to the master, the slave tries
-          to reconnect immediately. If that fails, the slave retries
-          periodically. (The default is to retry every 60 seconds. This
-          may be changed with the
-          <option>--master-connect-retry</option> option.) The slave
-          also is able to deal with network connectivity outages.
-          However, the slave does notice the network outage only after
-          receiving no data from the master for
+          When a slave loses its connection to the master, the slave
+          tries to reconnect immediately and retries periodically if
+          that fails. The default is to retry every 60 seconds. This may
+          be changed with the <option>--master-connect-retry</option>
+          option. A slave also is able to deal with network connectivity
+          outages. However, the slave notices the network outage only
+          after receiving no data from the master for
           <literal>slave_net_timeout</literal> seconds. If your outages
           are short, you may want to decrease
           <literal>slave_net_timeout</literal>. See
@@ -2189,22 +2204,25 @@
 
       <listitem>
         <para>
-          Shutting down the slave (cleanly) is also safe, as it keeps
-          track of where it left off. Unclean shutdowns might produce
-          problems, especially if disk cache was not flushed to disk
-          before the system went down. Your system fault tolerance is
-          greatly increased if you have a good uninterruptible power
-          supply. Unclean shutdowns of the master may cause
-          inconsistencies between the content of tables and the binary
-          log in master; this can be avoided by using
+          Shutting down the slave (cleanly) is also safe because it
+          keeps track of where it left off. Unclean shutdowns might
+          produce problems, especially if the disk cache was not flushed
+          to disk before the system went down. Your system fault
+          tolerance is greatly increased if you have a good
+          uninterruptible power supply. Unclean shutdowns of the master
+          may cause inconsistencies between the content of tables and
+          the binary log in master; this can be avoided by using
           <literal>InnoDB</literal> tables and the
           <option>--innodb-safe-binlog</option> option on the master.
           See <xref linkend="binary-log"/>.
-          (<emphasis
+        </para>
+
+        <para>
+          <emphasis
             role="bold">Note</emphasis>:
           <option>--innodb-safe-binlog</option> is not needed in MySQL
           &current-series;, having been made obsolete by the
-          introduction of XA transaction support.)
+          introduction of XA transaction support.
         </para>
       </listitem>
 
@@ -2218,10 +2236,10 @@
           long update statement is killed after updating some of the
           rows. If that happens on the master, the slave thread exits
           and waits for the database administrator to decide what to do
-          about it unless the error code is legitimate and the statement
-          execution results in the same error code. If this error code
-          validation behavior is not desirable, some or all errors can
-          be masked out (ignored) with the
+          about it unless the error code is legitimate and execution of
+          the statement results in the same error code on the slave. If
+          this error code validation behavior is not desirable, some or
+          all errors can be masked out (ignored) with the
           <option>--slave-skip-errors</option> option.
         </para>
       </listitem>
@@ -2231,25 +2249,26 @@
           If you update transactional tables from non-transactional
           tables inside a
           <literal>BEGIN</literal>/<literal>COMMIT</literal> sequence,
-          updates to the binary log may be out of synchrony if the
-          non-transactional table is updated before the transaction
-          commits. This is because the transaction is written to the
-          binary log only when it is committed.
+          updates to the binary log may be out of synchrony with table
+          states if the non-transactional table is updated before the
+          transaction commits. This occurs because the transaction is
+          written to the binary log only when it is committed.
         </para>
       </listitem>
 
       <listitem>
         <para>
           In situations where transactions mix updates to transactional
-          and non-transactional, the order of statements in the binary
-          log is correct, and all needed statements are written to the
-          binary log even in case of a <literal>ROLLBACK</literal>).
-          However, when a second connection updates the
-          non-transactional table before the first connection's
-          transaction is complete, statements can be logged out of
-          order, because the second connection's update is written
-          immediately after it is performed, regardless of the state of
-          the transaction being performed by the first connection.
+          and non-transactional tables, the order of statements in the
+          binary log is correct, and all needed statements are written
+          to the binary log even in case of a
+          <literal>ROLLBACK</literal>. However, when a second connection
+          updates the non-transactional table before the first
+          connection's transaction is complete, statements can be logged
+          out of order, because the second connection's update is
+          written immediately after it is performed, regardless of the
+          state of the transaction being performed by the first
+          connection.
         </para>
       </listitem>
 

Thread
svn commit - mysqldoc@docsrva: r1113 - in trunk: . refman-4.1 refman-5.0 refman-5.1paul30 Jan