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

Log:
 r6886@frost:  paul | 2006-01-29 21:16:50 -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:6883
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:2588
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:6886
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-30 02:01:55 UTC (rev 1115)
+++ trunk/refman-4.1/replication.xml	2006-01-30 04:31:33 UTC (rev 1116)
@@ -3527,11 +3527,11 @@
     </para>
 
     <para>
-      <emphasis role="bold">A</emphasis>: There are several options. If
-      you have taken a backup of the master at some point and recorded
-      the binary log name and offset (from the output of <literal>SHOW
-      MASTER STATUS</literal>) corresponding to the snapshot, use the
-      following procedure:
+      <emphasis role="bold">A</emphasis>: There are several
+      possibilities. If you have taken a snapshot backup of the master
+      at some point and recorded the binary log filename and offset
+      (from the output of <literal>SHOW MASTER STATUS</literal>)
+      corresponding to the snapshot, use the following procedure:
     </para>
 
     <orderedlist>
@@ -3550,11 +3550,11 @@
 
 <programlisting>
 mysql&gt; <userinput>CHANGE MASTER TO</userinput>
-    -&gt;     <userinput>MASTER_HOST='master_host_name',</userinput>
-    -&gt;     <userinput>MASTER_USER='master_user_name',</userinput>
-    -&gt;     <userinput>MASTER_PASSWORD='master_pass',</userinput>
-    -&gt;     <userinput>MASTER_LOG_FILE='recorded_log_file_name',</userinput>
-    -&gt;     <userinput>MASTER_LOG_POS=recorded_log_position;</userinput>
+    -&gt;     <userinput>MASTER_HOST='<replaceable>master_host_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_USER='<replaceable>master_user_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_PASSWORD='<replaceable>master_pass</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_FILE='<replaceable>recorded_log_file_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_POS=<replaceable>recorded_log_position</replaceable>;</userinput>
 </programlisting>
       </listitem>
 
@@ -3576,7 +3576,7 @@
 
       <listitem>
         <para>
-          Issue this statement:
+          Issue this statement to acquire a global read lock:
         </para>
 
 <programlisting>
@@ -3597,8 +3597,8 @@
 
       <listitem>
         <para>
-          Issue this statement and make sure to record the output, which
-          you need later:
+          Issue this statement and record the output, which you will
+          need later:
         </para>
 
 <programlisting>
@@ -3619,36 +3619,44 @@
     </orderedlist>
 
     <para>
-      An alternative is to make an SQL dump of the master instead of a
-      binary copy as in the preceding procedure. To do this, you can use
+      An alternative to using the preceding procedure to make a binary
+      copy is to make an SQL dump of the master. To do this, you can use
       <command>mysqldump --master-data</command> on your master and
       later load the SQL dump into your slave. However, this is slower
       than making a binary copy.
     </para>
 
+    <remark role="todo">
+      [pd] Following para isn't so clear...
+    </remark>
+
     <para>
-      No matter which of the two methods you use, afterward follow the
-      instructions for the case when you have a snapshot and have
-      recorded the log name and offset. You can use the same snapshot to
-      set up several slaves. Once you have the snapshot of the master,
-      you can wait to set up a slave as long as the binary logs of the
-      master are left intact. The two practical limitations on the
-      length of time you can wait are the amount of disk space available
-      to retain binary logs on the master and the length of time it
-      takes the slave to catch up.
+      Regardless of which of the two methods you use, afterward follow
+      the instructions for the case when you have a snapshot and have
+      recorded the log filename and offset. You can use the same
+      snapshot to set up several slaves. Once you have the snapshot of
+      the master, you can wait to set up a slave as long as the binary
+      logs of the master are left intact. The two practical limitations
+      on the length of time you can wait are the amount of disk space
+      available to retain binary logs on the master and the length of
+      time it takes the slave to catch up.
     </para>
 
+    <remark role="todo">
+      [pd] Really true that LDFM will be recommended in the future?
+    </remark>
+
     <para>
       You can also use <literal>LOAD DATA FROM MASTER</literal>. This is
       a convenient statement that transfers a snapshot to the slave and
-      adjusts the log name and offset all at once. In the future,
+      adjusts the log filename and offset all at once. In the future,
       <literal>LOAD DATA FROM MASTER</literal> will be the recommended
       way to set up a slave. Be warned, however, that it works only for
       <literal>MyISAM</literal> tables and it may hold a read lock for a
       long time. It is not yet implemented as efficiently as we would
-      like. If you have large tables, the preferred method at this time
-      is still to make a binary snapshot on the master server after
-      executing <literal>FLUSH TABLES WITH READ LOCK</literal>.
+      like. If you have large tables, the preferred method is still to
+      make a binary snapshot on the master server after executing
+      <literal>FLUSH TABLES WITH READ LOCK</literal>.
     </para>
 
     <para>
@@ -3656,9 +3664,13 @@
       connected to the master all the time?
     </para>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       <emphasis role="bold">A</emphasis>: No, it does not. The slave can
-      go down or stay disconnected for hours or even days, then
+      go down or stay disconnected for hours or even days, and then
       reconnect and catch up on updates. For example, you can set up a
       master/slave relationship over a dial-up link where the link is up
       only sporadically and for short periods of time. The implication
@@ -3692,8 +3704,8 @@
 
     <para>
       When the slave SQL thread executes an event read from the master,
-      it modifies its own time to the event timestamp (this is why
-      <literal>TIMESTAMP</literal> is well replicated). In the
+      it modifies its own time to the event timestamp. (This is why
+      <literal>TIMESTAMP</literal> is well replicated.) In the
       <literal>Time</literal> column in the output of <literal>SHOW
       PROCESSLIST</literal>, the number of seconds displayed for the
       slave SQL thread is the number of seconds between the timestamp of
@@ -3702,8 +3714,8 @@
       event. Note that if your slave has been disconnected from the
       master for one hour, and then reconnects, you may immediately see
       <literal>Time</literal> values like 3600 for the slave SQL thread
-      in <literal>SHOW PROCESSLIST</literal>. This would be because the
-      slave is executing statements that are one hour old.
+      in <literal>SHOW PROCESSLIST</literal>. This is because the slave
+      is executing statements that are one hour old.
     </para>
 
     <para>
@@ -3728,9 +3740,9 @@
 </programlisting>
 
         <para>
-          Record the log name and the offset from the output of the
-          <literal>SHOW</literal> statement. These are the replication
-          coordinates.
+          Record the replication cooredinates (the log filename and
+          offset) from the output of the <literal>SHOW</literal>
+          statement.
         </para>
       </listitem>
 
@@ -3743,7 +3755,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT MASTER_POS_WAIT('log_name', log_offset);</userinput>
+mysql&gt; <userinput>SELECT MASTER_POS_WAIT('<replaceable>log_name</replaceable>', <replaceable>log_offset</replaceable>);</userinput>
 </programlisting>
 
         <para>
@@ -3791,10 +3803,10 @@
     </para>
 
     <para>
-      You must also realize that two-way replication actually does not
-      improve performance very much (if at all), as far as updates are
-      concerned. Both servers need to do the same number of updates
-      each, as you would have one server do. The only difference is that
+      You should also realize that two-way replication actually does not
+      improve performance very much (if at all) as far as updates are
+      concerned. Each server must do the same number of updates, just as
+      you would have a single server do. The only difference is that
       there is a little less lock contention, because the updates
       originating on another server are serialized in one slave thread.
       Even this benefit might be offset by network delays.
@@ -3827,7 +3839,7 @@
       improvements on the slave end. In this case, the slave uses
       non-transactional <literal>MyISAM</literal> tables instead of
       <literal>InnoDB</literal> and <literal>BDB</literal> tables to get
-      more speed.
+      more speed by eliminating transactional overhead.
     </para>
 
     <para>
@@ -3840,13 +3852,13 @@
       <emphasis role="bold">A</emphasis>: If the part of your code that
       is responsible for database access has been properly
       abstracted/modularized, converting it to run with a replicated
-      setup should be very smooth and easy. Just change the
-      implementation of your database access to send all writes to the
-      master, and to send reads to either the master or a slave. If your
-      code does not have this level of abstraction, setting up a
-      replicated system gives you the opportunity and motivation to it
-      clean up. You should start by creating a wrapper library or module
-      with the following functions:
+      setup should be very smooth and easy. Change the implementation of
+      your database access to send all writes to the master, and to send
+      reads to either the master or a slave. If your code does not have
+      this level of abstraction, setting up a replicated system gives
+      you the opportunity and motivation to it clean up. Start by
+      creating a wrapper library or module that implements the following
+      functions:
     </para>
 
     <itemizedlist>
@@ -3886,15 +3898,15 @@
     </para>
 
     <para>
-      You should then convert your client code to use the wrapper
-      library. This may be a painful and scary process at first, but it
-      pays off in the long run. All applications that use the approach
-      just described are able to take advantage of a master/slave
-      configuration, even one involving multiple slaves. The code is a
-      lot easier to maintain, and adding troubleshooting options is
-      trivial. You need modify only one or two functions; for example,
-      to log how long each statement took, or which statement among
-      those issued gave you an error.
+      Then convert your client code to use the wrapper library. This may
+      be a painful and scary process at first, but it pays off in the
+      long run. All applications that use the approach just described
+      are able to take advantage of a master/slave configuration, even
+      one involving multiple slaves. The code is much easier to
+      maintain, and adding troubleshooting options is trivial. You need
+      modify only one or two functions; for example, to log how long
+      each statement took, or which statement among those issued gave
+      you an error.
     </para>
 
     <para>
@@ -3914,21 +3926,22 @@
 
     <para>
       <emphasis role="bold">A</emphasis>: MySQL replication is most
-      beneficial for a system with frequent reads and infrequent writes.
-      In theory, by using a single-master/multiple-slave setup, you can
-      scale the system by adding more slaves until you either run out of
-      network bandwidth, or your update load grows to the point that the
-      master cannot handle it.
+      beneficial for a system that processes frequent reads and
+      infrequent writes. In theory, by using a
+      single-master/multiple-slave setup, you can scale the system by
+      adding more slaves until you either run out of network bandwidth,
+      or your update load grows to the point that the master cannot
+      handle it.
     </para>
 
     <para>
-      To determine how many slaves you can get before the added benefits
+      To determine how many slaves you can use before the added benefits
       begin to level out, and how much you can improve performance of
       your site, you need to know your query patterns, and to determine
       empirically by benchmarking the relationship between the
       throughput for reads (reads per second, or
-      <literal>max_reads</literal>) and for writes
-      (<literal>max_writes</literal>) on a typical master and a typical
+      <literal>reads</literal>) and for writes
+      (<literal>writes</literal>) on a typical master and a typical
       slave. The example here shows a rather simplified calculation of
       what you can get with replication for a hypothetical system.
     </para>
@@ -3936,13 +3949,13 @@
     <para>
       Let's say that system load consists of 10% writes and 90% reads,
       and we have determined by benchmarking that
-      <literal>max_reads</literal> is 1200 &minus; 2 &times;
-      <literal>max_writes</literal>. In other words, the system can do
-      1,200 reads per second with no writes, the average write is twice
-      as slow as the average read, and the relationship is linear. Let
-      us suppose that the master and each slave have the same capacity,
-      and that we have one master and <replaceable>N</replaceable>
-      slaves. Then we have for each server (master or slave):
+      <literal>reads</literal> is 1200 &minus; 2 &times;
+      <literal>writes</literal>. In other words, the system can do 1,200
+      reads per second with no writes, the average write is twice as
+      slow as the average read, and the relationship is linear. Let us
+      suppose that the master and each slave have the same capacity, and
+      that we have one master and <replaceable>N</replaceable> slaves.
+      Then we have for each server (master or slave):
     </para>
 
     <para>
@@ -3965,7 +3978,7 @@
     </para>
 
     <para>
-      The last equation indicates that the maximum number of writes for
+      The last equation indicates the maximum number of writes for
       <replaceable>N</replaceable> slaves, given a maximum possible read
       rate of 1,200 per minute and a ratio of nine reads per write.
     </para>
@@ -4019,10 +4032,10 @@
 
     <para>
       Note that these computations assume infinite network bandwidth and
-      neglect several other factors that could turn out to be
-      significant on your system. In many cases, you may not be able to
-      perform a computation similar to the one just shown that
-      accurately predicts what will happen on your system if you add
+      neglect several other factors that could be significant on your
+      system. In many cases, you may not be able to perform a
+      computation similar to the one just shown that accurately predicts
+      what will happen on your system if you add
       <replaceable>N</replaceable> replication slaves. However,
       answering the following questions should help you decide whether
       and by how much replication will improve the performance of your
@@ -4055,7 +4068,7 @@
 
     <para>
       <emphasis role="bold">Q</emphasis>: How can I use replication to
-      provide redundancy/high availability?
+      provide redundancy or high availability?
     </para>
 
     <para>
@@ -4086,13 +4099,13 @@
 
       <listitem>
         <para>
-          You should run your slaves with the <option>--log-bin</option>
-          option and without <option>--log-slave-updates</option>. In
-          this way, the slave is ready to become a master as soon as you
-          issue <literal>STOP SLAVE</literal>; <literal>RESET
-          MASTER</literal>, and <literal>CHANGE MASTER TO</literal> on
-          the other slaves. For example, assume that you have the
-          following setup:
+          Run your slaves with the <option>--log-bin</option> option and
+          without <option>--log-slave-updates</option>. In this way, the
+          slave is ready to become a master as soon as you issue
+          <literal>STOP SLAVE</literal>; <literal>RESET
+          MASTER</literal>, and <literal>CHANGE MASTER TO</literal>
+          statement on the other slaves. For example, assume that you
+          have the following setup:
         </para>
 
         <remark role="todo">
@@ -4111,74 +4124,78 @@
 </programlisting>
 
         <para>
-          <emphasis role="bold">M</emphasis> means the master,
-          <emphasis role="bold">S</emphasis> the slaves,
-          <emphasis role="bold">WC</emphasis> the clients issuing
-          database writes and reads; clients that issue only database
-          reads are not represented, because they need not switch.
-          <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> are slaves running with
+          In this diagram, <literal>M</literal> means the master,
+          <literal>S</literal> the slaves, <literal>WC</literal> the
+          clients issuing database writes and reads; clients that issue
+          only database reads are not represented, because they need not
+          switch. <literal>S1</literal>, <literal>S2</literal>, and
+          <literal>S3</literal> are slaves running with
           <option>--log-bin</option> and without
           <option>--log-slave-updates</option>. Because updates received
           by a slave from the master are not logged in the binary log
           unless <option>--log-slave-updates</option> is specified, the
-          binary log on each slave is empty. If for some reason
-          <emphasis role="bold">M</emphasis> becomes unavailable, you
-          can pick one of the slaves to become the new master. For
-          example, if you pick <emphasis role="bold">S1</emphasis>, all
-          <emphasis role="bold">WC</emphasis> should be redirected to
-          <emphasis role="bold">S1</emphasis>, and
-          <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis> should then replicate from
-          <emphasis role="bold">S1</emphasis>.
+          binary log on each slave is empty initially. If for some
+          reason <literal>M</literal> becomes unavailable, you can pick
+          one of the slaves to become the new master. For example, if
+          you pick <literal>S1</literal>, all <literal>WC</literal>
+          should be redirected to <literal>S1</literal>, which will log
+          updates to its binary log. <literal>S2</literal> and
+          <literal>S3</literal> should then replicate from
+          <literal>S1</literal>.
         </para>
 
         <para>
+          The reason for running the slave without
+          <option>--log-slave-updates</option> is to prevent slaves from
+          receiving updates twice in case you cause one of the slaves to
+          become the new master. Suppose that <literal>S1</literal> has
+          <option>--log-slave-updates</option> enabled. Then it will
+          write updates that it receives from <literal>M</literal> to
+          its own binary log. When <literal>S2</literal> changes from
+          <literal>M</literal> to <literal>S1</literal> as its master,
+          it may receive updates from <literal>S1</literal> that it has
+          already received from <literal>M</literal>
+        </para>
+
+        <para>
           Make sure that all slaves have processed any statements in
           their relay log. On each slave, issue <literal>STOP SLAVE
           IO_THREAD</literal>, then check the output of <literal>SHOW
           PROCESSLIST</literal> until you see <literal>Has read all
           relay log</literal>. When this is true for all slaves, they
           can be reconfigured to the new setup. On the slave
-          <emphasis role="bold">S1</emphasis> being promoted to become
-          the master, issue <literal>STOP SLAVE</literal> and
-          <literal>RESET MASTER</literal>.
+          <literal>S1</literal> being promoted to become the master,
+          issue <literal>STOP SLAVE</literal> and <literal>RESET
+          MASTER</literal>.
         </para>
 
         <para>
-          On the other slaves <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, use <literal>STOP
-          SLAVE</literal> and <literal>CHANGE MASTER TO
-          MASTER_HOST='S1'</literal> (where <literal>'S1'</literal>
-          represents the real hostname of
-          <emphasis role="bold">S1</emphasis>). To <literal>CHANGE
-          MASTER</literal>, add all information about how to connect to
-          <emphasis role="bold">S1</emphasis> from
-          <emphasis role="bold">S2</emphasis> or
-          <emphasis role="bold">S3</emphasis>
-          (<replaceable>user</replaceable>,
+          On the other slaves <literal>S2</literal> and
+          <literal>S3</literal>, use <literal>STOP SLAVE</literal> and
+          <literal>CHANGE MASTER TO MASTER_HOST='S1'</literal> (where
+          <literal>'S1'</literal> represents the real hostname of
+          <literal>S1</literal>). To <literal>CHANGE MASTER</literal>,
+          add all information about how to connect to
+          <literal>S1</literal> from <literal>S2</literal> or
+          <literal>S3</literal> (<replaceable>user</replaceable>,
           <replaceable>password</replaceable>,
           <replaceable>port</replaceable>). In <literal>CHANGE
           MASTER</literal>, there is no need to specify the name of
-          <emphasis role="bold">S1</emphasis>'s binary log or binary log
-          position to read from: We know it is the first binary log and
-          position 4, which are the defaults for <literal>CHANGE
-          MASTER</literal>. Finally, use <literal>START SLAVE</literal>
-          on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>.
+          <literal>S1</literal>'s binary log or binary log position to
+          read from: We know it is the first binary log and position 4,
+          which are the defaults for <literal>CHANGE MASTER</literal>.
+          Finally, use <literal>START SLAVE</literal> on
+          <literal>S2</literal> and <literal>S3</literal>.
         </para>
 
         <para>
-          Then instruct all <emphasis role="bold">WC</emphasis> to
-          direct their statements to
-          <emphasis role="bold">S1</emphasis>. From that point on, all
-          updates statements sent by <emphasis role="bold">WC</emphasis>
-          to <emphasis role="bold">S1</emphasis> are written to the
-          binary log of <emphasis role="bold">S1</emphasis>, which then
-          contains every update statement sent to
-          <emphasis role="bold">S1</emphasis> since
-          <emphasis role="bold">M</emphasis> died.
+          Then instruct all <literal>WC</literal> to direct their
+          statements to <literal>S1</literal>. From that point on, all
+          updates statements sent by <literal>WC</literal> to
+          <literal>S1</literal> are written to the binary log of
+          <literal>S1</literal>, which then contains every update
+          statement sent to <literal>S1</literal> since
+          <literal>M</literal> died.
         </para>
 
         <para>
@@ -4203,26 +4220,21 @@
 </programlisting>
 
         <para>
-          When <emphasis role="bold">M</emphasis> is up again, you must
-          issue on it the same <literal>CHANGE MASTER</literal> as that
-          issued on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, so that
-          <emphasis role="bold">M</emphasis> becomes a slave of
-          <emphasis role="bold">S1</emphasis> and picks up all the
-          <emphasis role="bold">WC</emphasis> writes that it missed
-          while it was down. To make <emphasis role="bold">M</emphasis>
-          a master again (because it is the most powerful machine, for
+          When <literal>M</literal> is up again, you must issue on it
+          the same <literal>CHANGE MASTER</literal> as that issued on
+          <literal>S2</literal> and <literal>S3</literal>, so that
+          <literal>M</literal> becomes a slave of <literal>S1</literal>
+          and picks up all the <literal>WC</literal> writes that it
+          missed while it was down. To make <literal>M</literal> a
+          master again (because it is the most powerful machine, for
           example), use the preceding procedure as if
-          <emphasis role="bold">S1</emphasis> was unavailable and
-          <emphasis role="bold">M</emphasis> was to be the new master.
-          During this procedure, do not forget to run <literal>RESET
-          MASTER</literal> on <emphasis role="bold">M</emphasis> before
-          making <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> slaves of
-          <emphasis role="bold">M</emphasis>. Otherwise, they may pick
-          up old <emphasis role="bold">WC</emphasis> writes from before
-          the point at which <emphasis role="bold">M</emphasis> became
+          <literal>S1</literal> was unavailable and <literal>M</literal>
+          was to be the new master. During this procedure, do not forget
+          to run <literal>RESET MASTER</literal> on <literal>M</literal>
+          before making <literal>S1</literal>, <literal>S2</literal>,
+          and <literal>S3</literal> slaves of <literal>M</literal>.
+          Otherwise, they may pick up old <literal>WC</literal> writes
+          from before the point at which <literal>M</literal> became
           unavailable.
         </para>
       </listitem>

Modified: trunk/refman-5.0/replication.xml
===================================================================
--- trunk/refman-5.0/replication.xml	2006-01-30 02:01:55 UTC (rev 1115)
+++ trunk/refman-5.0/replication.xml	2006-01-30 04:31:33 UTC (rev 1116)
@@ -3422,11 +3422,11 @@
     </para>
 
     <para>
-      <emphasis role="bold">A</emphasis>: There are several options. If
-      you have taken a backup of the master at some point and recorded
-      the binary log name and offset (from the output of <literal>SHOW
-      MASTER STATUS</literal>) corresponding to the snapshot, use the
-      following procedure:
+      <emphasis role="bold">A</emphasis>: There are several
+      possibilities. If you have taken a snapshot backup of the master
+      at some point and recorded the binary log filename and offset
+      (from the output of <literal>SHOW MASTER STATUS</literal>)
+      corresponding to the snapshot, use the following procedure:
     </para>
 
     <orderedlist>
@@ -3445,11 +3445,11 @@
 
 <programlisting>
 mysql&gt; <userinput>CHANGE MASTER TO</userinput>
-    -&gt;     <userinput>MASTER_HOST='master_host_name',</userinput>
-    -&gt;     <userinput>MASTER_USER='master_user_name',</userinput>
-    -&gt;     <userinput>MASTER_PASSWORD='master_pass',</userinput>
-    -&gt;     <userinput>MASTER_LOG_FILE='recorded_log_file_name',</userinput>
-    -&gt;     <userinput>MASTER_LOG_POS=recorded_log_position;</userinput>
+    -&gt;     <userinput>MASTER_HOST='<replaceable>master_host_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_USER='<replaceable>master_user_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_PASSWORD='<replaceable>master_pass</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_FILE='<replaceable>recorded_log_file_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_POS=<replaceable>recorded_log_position</replaceable>;</userinput>
 </programlisting>
       </listitem>
 
@@ -3471,7 +3471,7 @@
 
       <listitem>
         <para>
-          Issue this statement:
+          Issue this statement to acquire a global read lock:
         </para>
 
 <programlisting>
@@ -3492,8 +3492,8 @@
 
       <listitem>
         <para>
-          Issue this statement and make sure to record the output, which
-          you need later:
+          Issue this statement and record the output, which you will
+          need later:
         </para>
 
 <programlisting>
@@ -3514,36 +3514,44 @@
     </orderedlist>
 
     <para>
-      An alternative is to make an SQL dump of the master instead of a
-      binary copy as in the preceding procedure. To do this, you can use
+      An alternative to using the preceding procedure to make a binary
+      copy is to make an SQL dump of the master. To do this, you can use
       <command>mysqldump --master-data</command> on your master and
       later load the SQL dump into your slave. However, this is slower
       than making a binary copy.
     </para>
 
+    <remark role="todo">
+      [pd] Following para isn't so clear...
+    </remark>
+
     <para>
-      No matter which of the two methods you use, afterward follow the
-      instructions for the case when you have a snapshot and have
-      recorded the log name and offset. You can use the same snapshot to
-      set up several slaves. Once you have the snapshot of the master,
-      you can wait to set up a slave as long as the binary logs of the
-      master are left intact. The two practical limitations on the
-      length of time you can wait are the amount of disk space available
-      to retain binary logs on the master and the length of time it
-      takes the slave to catch up.
+      Regardless of which of the two methods you use, afterward follow
+      the instructions for the case when you have a snapshot and have
+      recorded the log filename and offset. You can use the same
+      snapshot to set up several slaves. Once you have the snapshot of
+      the master, you can wait to set up a slave as long as the binary
+      logs of the master are left intact. The two practical limitations
+      on the length of time you can wait are the amount of disk space
+      available to retain binary logs on the master and the length of
+      time it takes the slave to catch up.
     </para>
 
+    <remark role="todo">
+      [pd] Really true that LDFM will be recommended in the future?
+    </remark>
+
     <para>
       You can also use <literal>LOAD DATA FROM MASTER</literal>. This is
       a convenient statement that transfers a snapshot to the slave and
-      adjusts the log name and offset all at once. In the future,
+      adjusts the log filename and offset all at once. In the future,
       <literal>LOAD DATA FROM MASTER</literal> will be the recommended
       way to set up a slave. Be warned, however, that it works only for
       <literal>MyISAM</literal> tables and it may hold a read lock for a
       long time. It is not yet implemented as efficiently as we would
-      like. If you have large tables, the preferred method at this time
-      is still to make a binary snapshot on the master server after
-      executing <literal>FLUSH TABLES WITH READ LOCK</literal>.
+      like. If you have large tables, the preferred method is still to
+      make a binary snapshot on the master server after executing
+      <literal>FLUSH TABLES WITH READ LOCK</literal>.
     </para>
 
     <para>
@@ -3551,9 +3559,13 @@
       connected to the master all the time?
     </para>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       <emphasis role="bold">A</emphasis>: No, it does not. The slave can
-      go down or stay disconnected for hours or even days, then
+      go down or stay disconnected for hours or even days, and then
       reconnect and catch up on updates. For example, you can set up a
       master/slave relationship over a dial-up link where the link is up
       only sporadically and for short periods of time. The implication
@@ -3583,8 +3595,8 @@
 
     <para>
       When the slave SQL thread executes an event read from the master,
-      it modifies its own time to the event timestamp (this is why
-      <literal>TIMESTAMP</literal> is well replicated). In the
+      it modifies its own time to the event timestamp. (This is why
+      <literal>TIMESTAMP</literal> is well replicated.) In the
       <literal>Time</literal> column in the output of <literal>SHOW
       PROCESSLIST</literal>, the number of seconds displayed for the
       slave SQL thread is the number of seconds between the timestamp of
@@ -3593,8 +3605,8 @@
       event. Note that if your slave has been disconnected from the
       master for one hour, and then reconnects, you may immediately see
       <literal>Time</literal> values like 3600 for the slave SQL thread
-      in <literal>SHOW PROCESSLIST</literal>. This would be because the
-      slave is executing statements that are one hour old.
+      in <literal>SHOW PROCESSLIST</literal>. This is because the slave
+      is executing statements that are one hour old.
     </para>
 
     <para>
@@ -3619,9 +3631,9 @@
 </programlisting>
 
         <para>
-          Record the log name and the offset from the output of the
-          <literal>SHOW</literal> statement. These are the replication
-          coordinates.
+          Record the replication cooredinates (the log filename and
+          offset) from the output of the <literal>SHOW</literal>
+          statement.
         </para>
       </listitem>
 
@@ -3634,7 +3646,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT MASTER_POS_WAIT('log_name', log_offset);</userinput>
+mysql&gt; <userinput>SELECT MASTER_POS_WAIT('<replaceable>log_name</replaceable>', <replaceable>log_offset</replaceable>);</userinput>
 </programlisting>
 
         <para>
@@ -3682,10 +3694,10 @@
     </para>
 
     <para>
-      You must also realize that two-way replication actually does not
-      improve performance very much (if at all), as far as updates are
-      concerned. Both servers need to do the same number of updates
-      each, as you would have one server do. The only difference is that
+      You should also realize that two-way replication actually does not
+      improve performance very much (if at all) as far as updates are
+      concerned. Each server must do the same number of updates, just as
+      you would have a single server do. The only difference is that
       there is a little less lock contention, because the updates
       originating on another server are serialized in one slave thread.
       Even this benefit might be offset by network delays.
@@ -3718,7 +3730,7 @@
       improvements on the slave end. In this case, the slave uses
       non-transactional <literal>MyISAM</literal> tables instead of
       <literal>InnoDB</literal> and <literal>BDB</literal> tables to get
-      more speed.
+      more speed by eliminating transactional overhead.
     </para>
 
     <para>
@@ -3731,13 +3743,13 @@
       <emphasis role="bold">A</emphasis>: If the part of your code that
       is responsible for database access has been properly
       abstracted/modularized, converting it to run with a replicated
-      setup should be very smooth and easy. Just change the
-      implementation of your database access to send all writes to the
-      master, and to send reads to either the master or a slave. If your
-      code does not have this level of abstraction, setting up a
-      replicated system gives you the opportunity and motivation to it
-      clean up. You should start by creating a wrapper library or module
-      with the following functions:
+      setup should be very smooth and easy. Change the implementation of
+      your database access to send all writes to the master, and to send
+      reads to either the master or a slave. If your code does not have
+      this level of abstraction, setting up a replicated system gives
+      you the opportunity and motivation to it clean up. Start by
+      creating a wrapper library or module that implements the following
+      functions:
     </para>
 
     <itemizedlist>
@@ -3777,15 +3789,15 @@
     </para>
 
     <para>
-      You should then convert your client code to use the wrapper
-      library. This may be a painful and scary process at first, but it
-      pays off in the long run. All applications that use the approach
-      just described are able to take advantage of a master/slave
-      configuration, even one involving multiple slaves. The code is
-      much easier to maintain, and adding troubleshooting options is
-      trivial. You just need to modify one or two functions; for
-      example, to log how long each statement took, or which statement
-      among your many thousands gave you an error.
+      Then convert your client code to use the wrapper library. This may
+      be a painful and scary process at first, but it pays off in the
+      long run. All applications that use the approach just described
+      are able to take advantage of a master/slave configuration, even
+      one involving multiple slaves. The code is much easier to
+      maintain, and adding troubleshooting options is trivial. You need
+      modify only one or two functions; for example, to log how long
+      each statement took, or which statement among those issued gave
+      you an error.
     </para>
 
     <para>
@@ -3805,21 +3817,22 @@
 
     <para>
       <emphasis role="bold">A</emphasis>: MySQL replication is most
-      beneficial for a system with frequent reads and infrequent writes.
-      In theory, by using a single-master/multiple-slave setup, you can
-      scale the system by adding more slaves until you either run out of
-      network bandwidth, or your update load grows to the point that the
-      master cannot handle it.
+      beneficial for a system that processes frequent reads and
+      infrequent writes. In theory, by using a
+      single-master/multiple-slave setup, you can scale the system by
+      adding more slaves until you either run out of network bandwidth,
+      or your update load grows to the point that the master cannot
+      handle it.
     </para>
 
     <para>
-      To determine how many slaves you can get before the added benefits
+      To determine how many slaves you can use before the added benefits
       begin to level out, and how much you can improve performance of
       your site, you need to know your query patterns, and to determine
       empirically by benchmarking the relationship between the
       throughput for reads (reads per second, or
-      <literal>max_reads</literal>) and for writes
-      (<literal>max_writes</literal>) on a typical master and a typical
+      <literal>reads</literal>) and for writes
+      (<literal>writes</literal>) on a typical master and a typical
       slave. The example here shows a rather simplified calculation of
       what you can get with replication for a hypothetical system.
     </para>
@@ -3827,13 +3840,13 @@
     <para>
       Let's say that system load consists of 10% writes and 90% reads,
       and we have determined by benchmarking that
-      <literal>max_reads</literal> is 1200 &minus; 2 &times;
-      <literal>max_writes</literal>. In other words, the system can do
-      1,200 reads per second with no writes, the average write is twice
-      as slow as the average read, and the relationship is linear. Let
-      us suppose that the master and each slave have the same capacity,
-      and that we have one master and <replaceable>N</replaceable>
-      slaves. Then we have for each server (master or slave):
+      <literal>reads</literal> is 1200 &minus; 2 &times;
+      <literal>writes</literal>. In other words, the system can do 1,200
+      reads per second with no writes, the average write is twice as
+      slow as the average read, and the relationship is linear. Let us
+      suppose that the master and each slave have the same capacity, and
+      that we have one master and <replaceable>N</replaceable> slaves.
+      Then we have for each server (master or slave):
     </para>
 
     <para>
@@ -3856,7 +3869,7 @@
     </para>
 
     <para>
-      The last equation indicates that the maximum number of writes for
+      The last equation indicates the maximum number of writes for
       <replaceable>N</replaceable> slaves, given a maximum possible read
       rate of 1,200 per minute and a ratio of nine reads per write.
     </para>
@@ -3910,10 +3923,10 @@
 
     <para>
       Note that these computations assume infinite network bandwidth and
-      neglect several other factors that could turn out to be
-      significant on your system. In many cases, you may not be able to
-      perform a computation similar to the one just shown that
-      accurately predicts what will happen on your system if you add
+      neglect several other factors that could be significant on your
+      system. In many cases, you may not be able to perform a
+      computation similar to the one just shown that accurately predicts
+      what will happen on your system if you add
       <replaceable>N</replaceable> replication slaves. However,
       answering the following questions should help you decide whether
       and by how much replication will improve the performance of your
@@ -3946,7 +3959,7 @@
 
     <para>
       <emphasis role="bold">Q</emphasis>: How can I use replication to
-      provide redundancy/high availability?
+      provide redundancy or high availability?
     </para>
 
     <para>
@@ -3977,13 +3990,13 @@
 
       <listitem>
         <para>
-          You should run your slaves with the <option>--log-bin</option>
-          option and without <option>--log-slave-updates</option>. In
-          this way, the slave is ready to become a master as soon as you
-          issue <literal>STOP SLAVE</literal>; <literal>RESET
-          MASTER</literal>, and <literal>CHANGE MASTER TO</literal> on
-          the other slaves. For example, assume that you have the
-          following setup:
+          Run your slaves with the <option>--log-bin</option> option and
+          without <option>--log-slave-updates</option>. In this way, the
+          slave is ready to become a master as soon as you issue
+          <literal>STOP SLAVE</literal>; <literal>RESET
+          MASTER</literal>, and <literal>CHANGE MASTER TO</literal>
+          statement on the other slaves. For example, assume that you
+          have the following setup:
         </para>
 
         <remark role="todo">
@@ -4002,74 +4015,78 @@
 </programlisting>
 
         <para>
-          <emphasis role="bold">M</emphasis> means the master,
-          <emphasis role="bold">S</emphasis> the slaves,
-          <emphasis role="bold">WC</emphasis> the clients issuing
-          database writes and reads; clients that issue only database
-          reads are not represented, because they need not switch.
-          <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> are slaves running with
+          In this diagram, <literal>M</literal> means the master,
+          <literal>S</literal> the slaves, <literal>WC</literal> the
+          clients issuing database writes and reads; clients that issue
+          only database reads are not represented, because they need not
+          switch. <literal>S1</literal>, <literal>S2</literal>, and
+          <literal>S3</literal> are slaves running with
           <option>--log-bin</option> and without
           <option>--log-slave-updates</option>. Because updates received
           by a slave from the master are not logged in the binary log
           unless <option>--log-slave-updates</option> is specified, the
-          binary log on each slave is empty. If for some reason
-          <emphasis role="bold">M</emphasis> becomes unavailable, you
-          can pick one of the slaves to become the new master. For
-          example, if you pick <emphasis role="bold">S1</emphasis>, all
-          <emphasis role="bold">WC</emphasis> should be redirected to
-          <emphasis role="bold">S1</emphasis>, and
-          <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis> should then replicate from
-          <emphasis role="bold">S1</emphasis>.
+          binary log on each slave is empty initially. If for some
+          reason <literal>M</literal> becomes unavailable, you can pick
+          one of the slaves to become the new master. For example, if
+          you pick <literal>S1</literal>, all <literal>WC</literal>
+          should be redirected to <literal>S1</literal>, which will log
+          updates to its binary log. <literal>S2</literal> and
+          <literal>S3</literal> should then replicate from
+          <literal>S1</literal>.
         </para>
 
         <para>
+          The reason for running the slave without
+          <option>--log-slave-updates</option> is to prevent slaves from
+          receiving updates twice in case you cause one of the slaves to
+          become the new master. Suppose that <literal>S1</literal> has
+          <option>--log-slave-updates</option> enabled. Then it will
+          write updates that it receives from <literal>M</literal> to
+          its own binary log. When <literal>S2</literal> changes from
+          <literal>M</literal> to <literal>S1</literal> as its master,
+          it may receive updates from <literal>S1</literal> that it has
+          already received from <literal>M</literal>
+        </para>
+
+        <para>
           Make sure that all slaves have processed any statements in
           their relay log. On each slave, issue <literal>STOP SLAVE
           IO_THREAD</literal>, then check the output of <literal>SHOW
           PROCESSLIST</literal> until you see <literal>Has read all
           relay log</literal>. When this is true for all slaves, they
           can be reconfigured to the new setup. On the slave
-          <emphasis role="bold">S1</emphasis> being promoted to become
-          the master, issue <literal>STOP SLAVE</literal> and
-          <literal>RESET MASTER</literal>.
+          <literal>S1</literal> being promoted to become the master,
+          issue <literal>STOP SLAVE</literal> and <literal>RESET
+          MASTER</literal>.
         </para>
 
         <para>
-          On the other slaves <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, use <literal>STOP
-          SLAVE</literal> and <literal>CHANGE MASTER TO
-          MASTER_HOST='S1'</literal> (where <literal>'S1'</literal>
-          represents the real hostname of
-          <emphasis role="bold">S1</emphasis>). To <literal>CHANGE
-          MASTER</literal>, add all information about how to connect to
-          <emphasis role="bold">S1</emphasis> from
-          <emphasis role="bold">S2</emphasis> or
-          <emphasis role="bold">S3</emphasis>
-          (<replaceable>user</replaceable>,
+          On the other slaves <literal>S2</literal> and
+          <literal>S3</literal>, use <literal>STOP SLAVE</literal> and
+          <literal>CHANGE MASTER TO MASTER_HOST='S1'</literal> (where
+          <literal>'S1'</literal> represents the real hostname of
+          <literal>S1</literal>). To <literal>CHANGE MASTER</literal>,
+          add all information about how to connect to
+          <literal>S1</literal> from <literal>S2</literal> or
+          <literal>S3</literal> (<replaceable>user</replaceable>,
           <replaceable>password</replaceable>,
           <replaceable>port</replaceable>). In <literal>CHANGE
           MASTER</literal>, there is no need to specify the name of
-          <emphasis role="bold">S1</emphasis>'s binary log or binary log
-          position to read from: We know it is the first binary log and
-          position 4, which are the defaults for <literal>CHANGE
-          MASTER</literal>. Finally, use <literal>START SLAVE</literal>
-          on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>.
+          <literal>S1</literal>'s binary log or binary log position to
+          read from: We know it is the first binary log and position 4,
+          which are the defaults for <literal>CHANGE MASTER</literal>.
+          Finally, use <literal>START SLAVE</literal> on
+          <literal>S2</literal> and <literal>S3</literal>.
         </para>
 
         <para>
-          Then instruct all <emphasis role="bold">WC</emphasis> to
-          direct their statements to
-          <emphasis role="bold">S1</emphasis>. From that point on, all
-          updates statements sent by <emphasis role="bold">WC</emphasis>
-          to <emphasis role="bold">S1</emphasis> are written to the
-          binary log of <emphasis role="bold">S1</emphasis>, which then
-          contains every update statement sent to
-          <emphasis role="bold">S1</emphasis> since
-          <emphasis role="bold">M</emphasis> died.
+          Then instruct all <literal>WC</literal> to direct their
+          statements to <literal>S1</literal>. From that point on, all
+          updates statements sent by <literal>WC</literal> to
+          <literal>S1</literal> are written to the binary log of
+          <literal>S1</literal>, which then contains every update
+          statement sent to <literal>S1</literal> since
+          <literal>M</literal> died.
         </para>
 
         <para>
@@ -4094,26 +4111,21 @@
 </programlisting>
 
         <para>
-          When <emphasis role="bold">M</emphasis> is up again, you must
-          issue on it the same <literal>CHANGE MASTER</literal> as that
-          issued on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, so that
-          <emphasis role="bold">M</emphasis> becomes a slave of
-          <emphasis role="bold">S1</emphasis> and picks up all the
-          <emphasis role="bold">WC</emphasis> writes that it missed
-          while it was down. To make <emphasis role="bold">M</emphasis>
-          a master again (because it is the most powerful machine, for
+          When <literal>M</literal> is up again, you must issue on it
+          the same <literal>CHANGE MASTER</literal> as that issued on
+          <literal>S2</literal> and <literal>S3</literal>, so that
+          <literal>M</literal> becomes a slave of <literal>S1</literal>
+          and picks up all the <literal>WC</literal> writes that it
+          missed while it was down. To make <literal>M</literal> a
+          master again (because it is the most powerful machine, for
           example), use the preceding procedure as if
-          <emphasis role="bold">S1</emphasis> was unavailable and
-          <emphasis role="bold">M</emphasis> was to be the new master.
-          During this procedure, do not forget to run <literal>RESET
-          MASTER</literal> on <emphasis role="bold">M</emphasis> before
-          making <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> slaves of
-          <emphasis role="bold">M</emphasis>. Otherwise, they may pick
-          up old <emphasis role="bold">WC</emphasis> writes from before
-          the point at which <emphasis role="bold">M</emphasis> became
+          <literal>S1</literal> was unavailable and <literal>M</literal>
+          was to be the new master. During this procedure, do not forget
+          to run <literal>RESET MASTER</literal> on <literal>M</literal>
+          before making <literal>S1</literal>, <literal>S2</literal>,
+          and <literal>S3</literal> slaves of <literal>M</literal>.
+          Otherwise, they may pick up old <literal>WC</literal> writes
+          from before the point at which <literal>M</literal> became
           unavailable.
         </para>
       </listitem>

Modified: trunk/refman-5.1/replication.xml
===================================================================
--- trunk/refman-5.1/replication.xml	2006-01-30 02:01:55 UTC (rev 1115)
+++ trunk/refman-5.1/replication.xml	2006-01-30 04:31:33 UTC (rev 1116)
@@ -3578,11 +3578,11 @@
     </para>
 
     <para>
-      <emphasis role="bold">A</emphasis>: There are several options. If
-      you have taken a backup of the master at some point and recorded
-      the binary log name and offset (from the output of <literal>SHOW
-      MASTER STATUS</literal>) corresponding to the snapshot, use the
-      following procedure:
+      <emphasis role="bold">A</emphasis>: There are several
+      possibilities. If you have taken a snapshot backup of the master
+      at some point and recorded the binary log filename and offset
+      (from the output of <literal>SHOW MASTER STATUS</literal>)
+      corresponding to the snapshot, use the following procedure:
     </para>
 
     <orderedlist>
@@ -3601,11 +3601,11 @@
 
 <programlisting>
 mysql&gt; <userinput>CHANGE MASTER TO</userinput>
-    -&gt;     <userinput>MASTER_HOST='master_host_name',</userinput>
-    -&gt;     <userinput>MASTER_USER='master_user_name',</userinput>
-    -&gt;     <userinput>MASTER_PASSWORD='master_pass',</userinput>
-    -&gt;     <userinput>MASTER_LOG_FILE='recorded_log_file_name',</userinput>
-    -&gt;     <userinput>MASTER_LOG_POS=recorded_log_position;</userinput>
+    -&gt;     <userinput>MASTER_HOST='<replaceable>master_host_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_USER='<replaceable>master_user_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_PASSWORD='<replaceable>master_pass</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_FILE='<replaceable>recorded_log_file_name</replaceable>',</userinput>
+    -&gt;     <userinput>MASTER_LOG_POS=<replaceable>recorded_log_position</replaceable>;</userinput>
 </programlisting>
       </listitem>
 
@@ -3627,7 +3627,7 @@
 
       <listitem>
         <para>
-          Issue this statement:
+          Issue this statement to acquire a global read lock:
         </para>
 
 <programlisting>
@@ -3648,8 +3648,8 @@
 
       <listitem>
         <para>
-          Issue this statement and make sure to record the output, which
-          you need later:
+          Issue this statement and record the output, which you will
+          need later:
         </para>
 
 <programlisting>
@@ -3670,36 +3670,44 @@
     </orderedlist>
 
     <para>
-      An alternative is to make an SQL dump of the master instead of a
-      binary copy as in the preceding procedure. To do this, you can use
+      An alternative to using the preceding procedure to make a binary
+      copy is to make an SQL dump of the master. To do this, you can use
       <command>mysqldump --master-data</command> on your master and
       later load the SQL dump into your slave. However, this is slower
       than making a binary copy.
     </para>
 
+    <remark role="todo">
+      [pd] Following para isn't so clear...
+    </remark>
+
     <para>
-      No matter which of the two methods you use, afterward follow the
-      instructions for the case when you have a snapshot and have
-      recorded the log name and offset. You can use the same snapshot to
-      set up several slaves. Once you have the snapshot of the master,
-      you can wait to set up a slave as long as the binary logs of the
-      master are left intact. The two practical limitations on the
-      length of time you can wait are the amount of disk space available
-      to retain binary logs on the master and the length of time it
-      takes the slave to catch up.
+      Regardless of which of the two methods you use, afterward follow
+      the instructions for the case when you have a snapshot and have
+      recorded the log filename and offset. You can use the same
+      snapshot to set up several slaves. Once you have the snapshot of
+      the master, you can wait to set up a slave as long as the binary
+      logs of the master are left intact. The two practical limitations
+      on the length of time you can wait are the amount of disk space
+      available to retain binary logs on the master and the length of
+      time it takes the slave to catch up.
     </para>
 
+    <remark role="todo">
+      [pd] Really true that LDFM will be recommended in the future?
+    </remark>
+
     <para>
       You can also use <literal>LOAD DATA FROM MASTER</literal>. This is
       a convenient statement that transfers a snapshot to the slave and
-      adjusts the log name and offset all at once. In the future,
+      adjusts the log filename and offset all at once. In the future,
       <literal>LOAD DATA FROM MASTER</literal> will be the recommended
       way to set up a slave. Be warned, however, that it works only for
       <literal>MyISAM</literal> tables and it may hold a read lock for a
       long time. It is not yet implemented as efficiently as we would
-      like. If you have large tables, the preferred method at this time
-      is still to make a binary snapshot on the master server after
-      executing <literal>FLUSH TABLES WITH READ LOCK</literal>.
+      like. If you have large tables, the preferred method is still to
+      make a binary snapshot on the master server after executing
+      <literal>FLUSH TABLES WITH READ LOCK</literal>.
     </para>
 
     <para>
@@ -3707,9 +3715,13 @@
       connected to the master all the time?
     </para>
 
+    <remark role="todo">
+      [pd] Is this a promise we should make?
+    </remark>
+
     <para>
       <emphasis role="bold">A</emphasis>: No, it does not. The slave can
-      go down or stay disconnected for hours or even days, then
+      go down or stay disconnected for hours or even days, and then
       reconnect and catch up on updates. For example, you can set up a
       master/slave relationship over a dial-up link where the link is up
       only sporadically and for short periods of time. The implication
@@ -3739,8 +3751,8 @@
 
     <para>
       When the slave SQL thread executes an event read from the master,
-      it modifies its own time to the event timestamp (this is why
-      <literal>TIMESTAMP</literal> is well replicated). In the
+      it modifies its own time to the event timestamp. (This is why
+      <literal>TIMESTAMP</literal> is well replicated.) In the
       <literal>Time</literal> column in the output of <literal>SHOW
       PROCESSLIST</literal>, the number of seconds displayed for the
       slave SQL thread is the number of seconds between the timestamp of
@@ -3749,8 +3761,8 @@
       event. Note that if your slave has been disconnected from the
       master for one hour, and then reconnects, you may immediately see
       <literal>Time</literal> values like 3600 for the slave SQL thread
-      in <literal>SHOW PROCESSLIST</literal>. This would be because the
-      slave is executing statements that are one hour old.
+      in <literal>SHOW PROCESSLIST</literal>. This is because the slave
+      is executing statements that are one hour old.
     </para>
 
     <para>
@@ -3775,9 +3787,9 @@
 </programlisting>
 
         <para>
-          Record the log name and the offset from the output of the
-          <literal>SHOW</literal> statement. These are the replication
-          coordinates.
+          Record the replication cooredinates (the log filename and
+          offset) from the output of the <literal>SHOW</literal>
+          statement.
         </para>
       </listitem>
 
@@ -3790,7 +3802,7 @@
         </para>
 
 <programlisting>
-mysql&gt; <userinput>SELECT MASTER_POS_WAIT('log_name', log_offset);</userinput>
+mysql&gt; <userinput>SELECT MASTER_POS_WAIT('<replaceable>log_name</replaceable>', <replaceable>log_offset</replaceable>);</userinput>
 </programlisting>
 
         <para>
@@ -3838,10 +3850,10 @@
     </para>
 
     <para>
-      You must also realize that two-way replication actually does not
-      improve performance very much (if at all), as far as updates are
-      concerned. Both servers need to do the same number of updates
-      each, as you would have one server do. The only difference is that
+      You should also realize that two-way replication actually does not
+      improve performance very much (if at all) as far as updates are
+      concerned. Each server must do the same number of updates, just as
+      you would have a single server do. The only difference is that
       there is a little less lock contention, because the updates
       originating on another server are serialized in one slave thread.
       Even this benefit might be offset by network delays.
@@ -3874,7 +3886,7 @@
       improvements on the slave end. In this case, the slave uses
       non-transactional <literal>MyISAM</literal> tables instead of
       <literal>InnoDB</literal> and <literal>BDB</literal> tables to get
-      more speed.
+      more speed by eliminating transactional overhead.
     </para>
 
     <para>
@@ -3887,13 +3899,13 @@
       <emphasis role="bold">A</emphasis>: If the part of your code that
       is responsible for database access has been properly
       abstracted/modularized, converting it to run with a replicated
-      setup should be very smooth and easy. Just change the
-      implementation of your database access to send all writes to the
-      master, and to send reads to either the master or a slave. If your
-      code does not have this level of abstraction, setting up a
-      replicated system gives you the opportunity and motivation to it
-      clean up. You should start by creating a wrapper library or module
-      with the following functions:
+      setup should be very smooth and easy. Change the implementation of
+      your database access to send all writes to the master, and to send
+      reads to either the master or a slave. If your code does not have
+      this level of abstraction, setting up a replicated system gives
+      you the opportunity and motivation to it clean up. Start by
+      creating a wrapper library or module that implements the following
+      functions:
     </para>
 
     <itemizedlist>
@@ -3933,15 +3945,15 @@
     </para>
 
     <para>
-      You should then convert your client code to use the wrapper
-      library. This may be a painful and scary process at first, but it
-      pays off in the long run. All applications that use the approach
-      just described are able to take advantage of a master/slave
-      configuration, even one involving multiple slaves. The code is
-      much easier to maintain, and adding troubleshooting options is
-      trivial. You just need to modify one or two functions; for
-      example, to log how long each statement took, or which statement
-      among your many thousands gave you an error.
+      Then convert your client code to use the wrapper library. This may
+      be a painful and scary process at first, but it pays off in the
+      long run. All applications that use the approach just described
+      are able to take advantage of a master/slave configuration, even
+      one involving multiple slaves. The code is much easier to
+      maintain, and adding troubleshooting options is trivial. You need
+      modify only one or two functions; for example, to log how long
+      each statement took, or which statement among those issued gave
+      you an error.
     </para>
 
     <para>
@@ -3961,21 +3973,22 @@
 
     <para>
       <emphasis role="bold">A</emphasis>: MySQL replication is most
-      beneficial for a system with frequent reads and infrequent writes.
-      In theory, by using a single-master/multiple-slave setup, you can
-      scale the system by adding more slaves until you either run out of
-      network bandwidth, or your update load grows to the point that the
-      master cannot handle it.
+      beneficial for a system that processes frequent reads and
+      infrequent writes. In theory, by using a
+      single-master/multiple-slave setup, you can scale the system by
+      adding more slaves until you either run out of network bandwidth,
+      or your update load grows to the point that the master cannot
+      handle it.
     </para>
 
     <para>
-      To determine how many slaves you can get before the added benefits
+      To determine how many slaves you can use before the added benefits
       begin to level out, and how much you can improve performance of
       your site, you need to know your query patterns, and to determine
       empirically by benchmarking the relationship between the
       throughput for reads (reads per second, or
-      <literal>max_reads</literal>) and for writes
-      (<literal>max_writes</literal>) on a typical master and a typical
+      <literal>reads</literal>) and for writes
+      (<literal>writes</literal>) on a typical master and a typical
       slave. The example here shows a rather simplified calculation of
       what you can get with replication for a hypothetical system.
     </para>
@@ -3983,13 +3996,13 @@
     <para>
       Let's say that system load consists of 10% writes and 90% reads,
       and we have determined by benchmarking that
-      <literal>max_reads</literal> is 1200 &minus; 2 &times;
-      <literal>max_writes</literal>. In other words, the system can do
-      1,200 reads per second with no writes, the average write is twice
-      as slow as the average read, and the relationship is linear. Let
-      us suppose that the master and each slave have the same capacity,
-      and that we have one master and <replaceable>N</replaceable>
-      slaves. Then we have for each server (master or slave):
+      <literal>reads</literal> is 1200 &minus; 2 &times;
+      <literal>writes</literal>. In other words, the system can do 1,200
+      reads per second with no writes, the average write is twice as
+      slow as the average read, and the relationship is linear. Let us
+      suppose that the master and each slave have the same capacity, and
+      that we have one master and <replaceable>N</replaceable> slaves.
+      Then we have for each server (master or slave):
     </para>
 
     <para>
@@ -4012,7 +4025,7 @@
     </para>
 
     <para>
-      The last equation indicates that the maximum number of writes for
+      The last equation indicates the maximum number of writes for
       <replaceable>N</replaceable> slaves, given a maximum possible read
       rate of 1,200 per minute and a ratio of nine reads per write.
     </para>
@@ -4066,10 +4079,10 @@
 
     <para>
       Note that these computations assume infinite network bandwidth and
-      neglect several other factors that could turn out to be
-      significant on your system. In many cases, you may not be able to
-      perform a computation similar to the one just shown that
-      accurately predicts what will happen on your system if you add
+      neglect several other factors that could be significant on your
+      system. In many cases, you may not be able to perform a
+      computation similar to the one just shown that accurately predicts
+      what will happen on your system if you add
       <replaceable>N</replaceable> replication slaves. However,
       answering the following questions should help you decide whether
       and by how much replication will improve the performance of your
@@ -4102,7 +4115,7 @@
 
     <para>
       <emphasis role="bold">Q</emphasis>: How can I use replication to
-      provide redundancy/high availability?
+      provide redundancy or high availability?
     </para>
 
     <para>
@@ -4133,13 +4146,13 @@
 
       <listitem>
         <para>
-          You should run your slaves with the <option>--log-bin</option>
-          option and without <option>--log-slave-updates</option>. In
-          this way, the slave is ready to become a master as soon as you
-          issue <literal>STOP SLAVE</literal>; <literal>RESET
-          MASTER</literal>, and <literal>CHANGE MASTER TO</literal> on
-          the other slaves. For example, assume that you have the
-          following setup:
+          Run your slaves with the <option>--log-bin</option> option and
+          without <option>--log-slave-updates</option>. In this way, the
+          slave is ready to become a master as soon as you issue
+          <literal>STOP SLAVE</literal>; <literal>RESET
+          MASTER</literal>, and <literal>CHANGE MASTER TO</literal>
+          statement on the other slaves. For example, assume that you
+          have the following setup:
         </para>
 
         <remark role="todo">
@@ -4158,74 +4171,78 @@
 </programlisting>
 
         <para>
-          <emphasis role="bold">M</emphasis> means the master,
-          <emphasis role="bold">S</emphasis> the slaves,
-          <emphasis role="bold">WC</emphasis> the clients issuing
-          database writes and reads; clients that issue only database
-          reads are not represented, because they need not switch.
-          <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> are slaves running with
+          In this diagram, <literal>M</literal> means the master,
+          <literal>S</literal> the slaves, <literal>WC</literal> the
+          clients issuing database writes and reads; clients that issue
+          only database reads are not represented, because they need not
+          switch. <literal>S1</literal>, <literal>S2</literal>, and
+          <literal>S3</literal> are slaves running with
           <option>--log-bin</option> and without
           <option>--log-slave-updates</option>. Because updates received
           by a slave from the master are not logged in the binary log
           unless <option>--log-slave-updates</option> is specified, the
-          binary log on each slave is empty. If for some reason
-          <emphasis role="bold">M</emphasis> becomes unavailable, you
-          can pick one of the slaves to become the new master. For
-          example, if you pick <emphasis role="bold">S1</emphasis>, all
-          <emphasis role="bold">WC</emphasis> should be redirected to
-          <emphasis role="bold">S1</emphasis>, and
-          <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis> should then replicate from
-          <emphasis role="bold">S1</emphasis>.
+          binary log on each slave is empty initially. If for some
+          reason <literal>M</literal> becomes unavailable, you can pick
+          one of the slaves to become the new master. For example, if
+          you pick <literal>S1</literal>, all <literal>WC</literal>
+          should be redirected to <literal>S1</literal>, which will log
+          updates to its binary log. <literal>S2</literal> and
+          <literal>S3</literal> should then replicate from
+          <literal>S1</literal>.
         </para>
 
         <para>
+          The reason for running the slave without
+          <option>--log-slave-updates</option> is to prevent slaves from
+          receiving updates twice in case you cause one of the slaves to
+          become the new master. Suppose that <literal>S1</literal> has
+          <option>--log-slave-updates</option> enabled. Then it will
+          write updates that it receives from <literal>M</literal> to
+          its own binary log. When <literal>S2</literal> changes from
+          <literal>M</literal> to <literal>S1</literal> as its master,
+          it may receive updates from <literal>S1</literal> that it has
+          already received from <literal>M</literal>
+        </para>
+
+        <para>
           Make sure that all slaves have processed any statements in
           their relay log. On each slave, issue <literal>STOP SLAVE
           IO_THREAD</literal>, then check the output of <literal>SHOW
           PROCESSLIST</literal> until you see <literal>Has read all
           relay log</literal>. When this is true for all slaves, they
           can be reconfigured to the new setup. On the slave
-          <emphasis role="bold">S1</emphasis> being promoted to become
-          the master, issue <literal>STOP SLAVE</literal> and
-          <literal>RESET MASTER</literal>.
+          <literal>S1</literal> being promoted to become the master,
+          issue <literal>STOP SLAVE</literal> and <literal>RESET
+          MASTER</literal>.
         </para>
 
         <para>
-          On the other slaves <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, use <literal>STOP
-          SLAVE</literal> and <literal>CHANGE MASTER TO
-          MASTER_HOST='S1'</literal> (where <literal>'S1'</literal>
-          represents the real hostname of
-          <emphasis role="bold">S1</emphasis>). To <literal>CHANGE
-          MASTER</literal>, add all information about how to connect to
-          <emphasis role="bold">S1</emphasis> from
-          <emphasis role="bold">S2</emphasis> or
-          <emphasis role="bold">S3</emphasis>
-          (<replaceable>user</replaceable>,
+          On the other slaves <literal>S2</literal> and
+          <literal>S3</literal>, use <literal>STOP SLAVE</literal> and
+          <literal>CHANGE MASTER TO MASTER_HOST='S1'</literal> (where
+          <literal>'S1'</literal> represents the real hostname of
+          <literal>S1</literal>). To <literal>CHANGE MASTER</literal>,
+          add all information about how to connect to
+          <literal>S1</literal> from <literal>S2</literal> or
+          <literal>S3</literal> (<replaceable>user</replaceable>,
           <replaceable>password</replaceable>,
           <replaceable>port</replaceable>). In <literal>CHANGE
           MASTER</literal>, there is no need to specify the name of
-          <emphasis role="bold">S1</emphasis>'s binary log or binary log
-          position to read from: We know it is the first binary log and
-          position 4, which are the defaults for <literal>CHANGE
-          MASTER</literal>. Finally, use <literal>START SLAVE</literal>
-          on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>.
+          <literal>S1</literal>'s binary log or binary log position to
+          read from: We know it is the first binary log and position 4,
+          which are the defaults for <literal>CHANGE MASTER</literal>.
+          Finally, use <literal>START SLAVE</literal> on
+          <literal>S2</literal> and <literal>S3</literal>.
         </para>
 
         <para>
-          Then instruct all <emphasis role="bold">WC</emphasis> to
-          direct their statements to
-          <emphasis role="bold">S1</emphasis>. From that point on, all
-          updates statements sent by <emphasis role="bold">WC</emphasis>
-          to <emphasis role="bold">S1</emphasis> are written to the
-          binary log of <emphasis role="bold">S1</emphasis>, which then
-          contains every update statement sent to
-          <emphasis role="bold">S1</emphasis> since
-          <emphasis role="bold">M</emphasis> died.
+          Then instruct all <literal>WC</literal> to direct their
+          statements to <literal>S1</literal>. From that point on, all
+          updates statements sent by <literal>WC</literal> to
+          <literal>S1</literal> are written to the binary log of
+          <literal>S1</literal>, which then contains every update
+          statement sent to <literal>S1</literal> since
+          <literal>M</literal> died.
         </para>
 
         <para>
@@ -4250,26 +4267,21 @@
 </programlisting>
 
         <para>
-          When <emphasis role="bold">M</emphasis> is up again, you must
-          issue on it the same <literal>CHANGE MASTER</literal> as that
-          issued on <emphasis role="bold">S2</emphasis> and
-          <emphasis role="bold">S3</emphasis>, so that
-          <emphasis role="bold">M</emphasis> becomes a slave of
-          <emphasis role="bold">S1</emphasis> and picks up all the
-          <emphasis role="bold">WC</emphasis> writes that it missed
-          while it was down. To make <emphasis role="bold">M</emphasis>
-          a master again (because it is the most powerful machine, for
+          When <literal>M</literal> is up again, you must issue on it
+          the same <literal>CHANGE MASTER</literal> as that issued on
+          <literal>S2</literal> and <literal>S3</literal>, so that
+          <literal>M</literal> becomes a slave of <literal>S1</literal>
+          and picks up all the <literal>WC</literal> writes that it
+          missed while it was down. To make <literal>M</literal> a
+          master again (because it is the most powerful machine, for
           example), use the preceding procedure as if
-          <emphasis role="bold">S1</emphasis> was unavailable and
-          <emphasis role="bold">M</emphasis> was to be the new master.
-          During this procedure, do not forget to run <literal>RESET
-          MASTER</literal> on <emphasis role="bold">M</emphasis> before
-          making <emphasis role="bold">S1</emphasis>,
-          <emphasis role="bold">S2</emphasis>, and
-          <emphasis role="bold">S3</emphasis> slaves of
-          <emphasis role="bold">M</emphasis>. Otherwise, they may pick
-          up old <emphasis role="bold">WC</emphasis> writes from before
-          the point at which <emphasis role="bold">M</emphasis> became
+          <literal>S1</literal> was unavailable and <literal>M</literal>
+          was to be the new master. During this procedure, do not forget
+          to run <literal>RESET MASTER</literal> on <literal>M</literal>
+          before making <literal>S1</literal>, <literal>S2</literal>,
+          and <literal>S3</literal> slaves of <literal>M</literal>.
+          Otherwise, they may pick up old <literal>WC</literal> writes
+          from before the point at which <literal>M</literal> became
           unavailable.
         </para>
       </listitem>
@@ -4277,26 +4289,33 @@
     </itemizedlist>
 
     <para>
-      <emphasis role="bold">Q</emphasis>: How do I tell which format I'm
-      currently running (row-based or statement-based)?
+      <emphasis role="bold">Q</emphasis>: How do I tell whether a master
+      server is using statement-based or row-based replication logging
+      format?
     </para>
 
     <para>
-      <emphasis role="bold">A</emphasis>: By issuing this statement:
+      <emphasis role="bold">A</emphasis>: Check the value of the
+      <literal>binlog_format</literal> system variable:
     </para>
 
 <programlisting>
-mysql&gt; <userinput>SHOW VARIABLES LIKE "%binlog_format%";</userinput>
+mysql&gt; <userinput>SHOW VARIABLES LIKE 'binlog_format';</userinput>
 </programlisting>
 
     <para>
-      <emphasis role="bold">Q</emphasis>: How do I tell the slave to use
+      The value will be either <literal>STATEMENT</literal> or
+      <literal>ROW</literal>.
+    </para>
+
+    <para>
+      <emphasis role="bold">Q</emphasis>: How do I tell a slave to use
       row-based replication?
     </para>
 
     <para>
-      <emphasis role="bold">A</emphasis>: The slave automatically knows
-      which format it should use.
+      <emphasis role="bold">A</emphasis>: Slaves automatically know
+      which format to use.
     </para>
 
   </section>

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