svn commit - mysqldoc@docsrva: r10980 - in trunk: it/refman-5.1 pt/refman-5.1 refman-4.1 refman-5.0 refman-5.1 refman-6.0

[jon]

Author: jstephens
Date: 2008-06-19 12:25:43 +0200 (Thu, 19 Jun 2008)
New Revision: 10980

Log:

Preventing or dealing with issues caused by hostname change on
replication slave (Bug #2122/user comments)

Added pointer to mysql-cluster-replication (5.1/6.0)

Some wording fixes



Modified:
   trunk/it/refman-5.1/replication-implementation.xml
   trunk/it/refman-5.1/replication-notes.xml
   trunk/pt/refman-5.1/replication-implementation.xml
   trunk/pt/refman-5.1/replication-notes.xml
   trunk/refman-4.1/replication.xml
   trunk/refman-5.0/replication-implementation.xml
   trunk/refman-5.0/replication-notes.xml
   trunk/refman-5.1/replication-implementation.xml
   trunk/refman-5.1/replication-notes.xml
   trunk/refman-6.0/replication-implementation.xml
   trunk/refman-6.0/replication-notes.xml


Modified: trunk/it/refman-5.1/replication-implementation.xml
===================================================================
--- trunk/it/refman-5.1/replication-implementation.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/it/refman-5.1/replication-implementation.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 27, Lines Deleted: 4; 2586 bytes

@@ -281,14 +281,37 @@
         the relay log files currently in use. The default relay log
         index filename is
        
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
+        By default, the slave server creates relay log files in its data
+        directory.
       </para>
 
       <para>
-        By default, the slave server creates relay log files in its data
-        directory. The default filenames can be overridden with the
+        The default filenames for relay logs and relay log index files
+        can be overridden with, respectively, the
         <option>--relay-log</option> and
-        <option>--relay-log-index</option> server options. See
-        <xref linkend="replication-options"/>.
+        <option>--relay-log-index</option> server options (see
+        <xref linkend="replication-options"/>). For this reason,
+        changing a replication slave&apos;s hostname can cause
+        replication to fail with the errors <errortext>Failed to open
+        the relay log</errortext> and <errortext>Could not find target
+        log during relay log initialization</errortext>. This is a known
+        issue which we intend to fix in a future MySQL release (see Bug
+        #2122). If you anticipate that a slave&apos;s hostname may
+        change in the future (for example, if networking is set up on
+        the slave such that its hostname can be modified via DHCP), then
+        you can use these options to prevent this problem from
+        occurring. However, if you encounter this issue, one way to work
+        around it is to stop the slave server, prepend the contents of
+        the old relay log index file to the new one, then restart the
+        slave. On a Unix system, this can be done as shown here, where
+        <replaceable>new_host_name</replaceable> is the new hostname and
+        <replaceable>old_host_name</replaceable> is the old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
       </para>
 
       <para>


Modified: trunk/it/refman-5.1/replication-notes.xml
===================================================================
--- trunk/it/refman-5.1/replication-notes.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/it/refman-5.1/replication-notes.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 3; 991 bytes

@@ -65,9 +65,11 @@
     <para>
       The following sections provide details about what is supported and
       what is not, and about specific issues and situations that may
-      occur when replicating certain statements. Additional
-      <literal>InnoDB</literal>-specific information about replication
-      is given in <xref linkend="innodb-and-mysql-replication"/>.
+      occur when replicating certain statements. Additional information
+      specific to <literal>InnoDB</literal> and replication is given in
+      <xref linkend="innodb-and-mysql-replication"/>. For information
+      relating to replication with MySQL Cluster, see
+      <xref linkend="mysql-cluster-replication"/>.
     </para>
 
     <para>


Modified: trunk/pt/refman-5.1/replication-implementation.xml
===================================================================
--- trunk/pt/refman-5.1/replication-implementation.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/pt/refman-5.1/replication-implementation.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 27, Lines Deleted: 4; 2586 bytes

@@ -281,14 +281,37 @@
         the relay log files currently in use. The default relay log
         index filename is
        
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
+        By default, the slave server creates relay log files in its data
+        directory.
       </para>
 
       <para>
-        By default, the slave server creates relay log files in its data
-        directory. The default filenames can be overridden with the
+        The default filenames for relay logs and relay log index files
+        can be overridden with, respectively, the
         <option>--relay-log</option> and
-        <option>--relay-log-index</option> server options. See
-        <xref linkend="replication-options"/>.
+        <option>--relay-log-index</option> server options (see
+        <xref linkend="replication-options"/>). For this reason,
+        changing a replication slave&apos;s hostname can cause
+        replication to fail with the errors <errortext>Failed to open
+        the relay log</errortext> and <errortext>Could not find target
+        log during relay log initialization</errortext>. This is a known
+        issue which we intend to fix in a future MySQL release (see Bug
+        #2122). If you anticipate that a slave&apos;s hostname may
+        change in the future (for example, if networking is set up on
+        the slave such that its hostname can be modified via DHCP), then
+        you can use these options to prevent this problem from
+        occurring. However, if you encounter this issue, one way to work
+        around it is to stop the slave server, prepend the contents of
+        the old relay log index file to the new one, then restart the
+        slave. On a Unix system, this can be done as shown here, where
+        <replaceable>new_host_name</replaceable> is the new hostname and
+        <replaceable>old_host_name</replaceable> is the old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
       </para>
 
       <para>


Modified: trunk/pt/refman-5.1/replication-notes.xml
===================================================================
--- trunk/pt/refman-5.1/replication-notes.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/pt/refman-5.1/replication-notes.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 3; 991 bytes

@@ -65,9 +65,11 @@
     <para>
       The following sections provide details about what is supported and
       what is not, and about specific issues and situations that may
-      occur when replicating certain statements. Additional
-      <literal>InnoDB</literal>-specific information about replication
-      is given in <xref linkend="innodb-and-mysql-replication"/>.
+      occur when replicating certain statements. Additional information
+      specific to <literal>InnoDB</literal> and replication is given in
+      <xref linkend="innodb-and-mysql-replication"/>. For information
+      relating to replication with MySQL Cluster, see
+      <xref linkend="mysql-cluster-replication"/>.
     </para>
 
     <para>


Modified: trunk/refman-4.1/replication.xml
===================================================================
--- trunk/refman-4.1/replication.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-4.1/replication.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 3, Lines Added: 32, Lines Deleted: 6; 3282 bytes

@@ -343,7 +343,7 @@
       <title>Replication Relay and Status Files</title>
 
       <para>
-        By default, relay logs filenames have the form
+        By default, relay log filenames have the form
        
<filename><replaceable>host_name</replaceable>-relay-bin.<replaceable>nnnnnn</replaceable></filename>,
         where <replaceable>host_name</replaceable> is the name of the
         slave server host and <replaceable>nnnnnn</replaceable> is a

@@ -354,10 +354,36 @@
         files currently in use. The default relay log index filename is
        
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
         By default, the slave server creates relay log files in its data
-        directory. The default filenames can be overridden with the
+        directory.
+      </para>
+
+      <para>
+        The default filenames for relay logs and relay log index files
+        can be overridden with, respectively, the
         <option>--relay-log</option> and
-        <option>--relay-log-index</option> server options. See
-        <xref linkend="replication-options"/>.
+        <option>--relay-log-index</option> server options (see
+        <xref linkend="replication-options"/>). For this reason,
+        changing a replication slave&apos;s hostname can cause
+        replication to fail with the errors <errortext>Failed to open
+        the relay log</errortext> and <errortext>Could not find target
+        log during relay log initialization</errortext>. This is a known
+        issue which we intend to fix in a future MySQL release (see Bug
+        #2122). If you anticipate that a slave&apos;s hostname may
+        change in the future (for example, if networking is set up on
+        the slave such that its hostname can be modified via DHCP), then
+        you can use these options to prevent this problem from
+        occurring. However, if you encounter this issue, one way to work
+        around it is to stop the slave server, prepend the contents of
+        the old relay log index file to the new one, then restart the
+        slave. On a Unix system, this can be done as shown here, where
+        <replaceable>new_host_name</replaceable> is the new hostname and
+        <replaceable>old_host_name</replaceable> is the old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
       </para>
 
       <para>

@@ -1388,8 +1414,8 @@
 
     <para>
       The following list provides details about what is supported and
-      what is not. Additional <literal>InnoDB</literal>-specific
-      information about replication is given in
+      what is not. Additional information specific to
+      <literal>InnoDB</literal> and replication is given in
       <xref linkend="innodb-and-mysql-replication"/>.
     </para>
 


Modified: trunk/refman-5.0/replication-implementation.xml
===================================================================
--- trunk/refman-5.0/replication-implementation.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-5.0/replication-implementation.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 29, Lines Deleted: 4; 2615 bytes

@@ -209,13 +209,38 @@
       filename is
      
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
       By default, the slave server creates relay log files in its data
-      directory. The default filenames can be overridden with the
-      <option>--relay-log</option> and
-      <option>--relay-log-index</option> server options. See
-      <xref linkend="replication-options"/>.
+      directory.
     </para>
 
     <para>
+      The default filenames for relay logs and relay log index files can
+      be overridden with, respectively, the <option>--relay-log</option>
+      and <option>--relay-log-index</option> server options (see
+      <xref linkend="replication-options"/>). For this reason, changing
+      a replication slave&apos;s hostname can cause replication to fail
+      with the errors <errortext>Failed to open the relay
+      log</errortext> and <errortext>Could not find target log during
+      relay log initialization</errortext>. This is a known issue which
+      we intend to fix in a future MySQL release (see Bug #2122). If you
+      anticipate that a slave&apos;s hostname may change in the future
+      (for example, if networking is set up on the slave such that its
+      hostname can be modified via DHCP), then you can use these options
+      to prevent this problem from occurring. However, if you encounter
+      this issue, one way to work around it is to stop the slave server,
+      prepend the contents of the old relay log index file to the new
+      one, then restart the slave. On a Unix system, this can be done as
+      shown here, where <replaceable>new_host_name</replaceable> is the
+      new hostname and <replaceable>old_host_name</replaceable> is the
+      old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
+    </para>
+
+    <para>
       Relay logs have the same format as binary logs and can be read
       using <command>mysqlbinlog</command>. The SQL thread automatically
       deletes each relay log file as soon as it has executed all events


Modified: trunk/refman-5.0/replication-notes.xml
===================================================================
--- trunk/refman-5.0/replication-notes.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-5.0/replication-notes.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 3, Lines Deleted: 3; 749 bytes

@@ -63,9 +63,9 @@
     </para>
 
     <para>
-      The following list provides details about what is supported and
-      what is not. Additional <literal>InnoDB</literal>-specific
-      information about replication is given in
+      The following sections provide details about what is supported and
+      what is not. Additional information specific to
+      <literal>InnoDB</literal> and replication is given in
       <xref linkend="innodb-and-mysql-replication"/>.
     </para>
 


Modified: trunk/refman-5.1/replication-implementation.xml
===================================================================
--- trunk/refman-5.1/replication-implementation.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-5.1/replication-implementation.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 27, Lines Deleted: 4; 2577 bytes

@@ -281,14 +281,37 @@
         the relay log files currently in use. The default relay log
         index filename is
        
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
+        By default, the slave server creates relay log files in its data
+        directory.
       </para>
 
       <para>
-        By default, the slave server creates relay log files in its data
-        directory. The default filenames can be overridden with the
+        The default filenames for relay logs and relay log index files
+        can be overridden with, respectively, the
         <option>--relay-log</option> and
-        <option>--relay-log-index</option> server options. See
-        <xref linkend="replication-options"/>.
+        <option>--relay-log-index</option> server options (see
+        <xref linkend="replication-options"/>). For this reason,
+        changing a replication slave&apos;s hostname can cause
+        replication to fail with the errors <errortext>Failed to open
+        the relay log</errortext> and <errortext>Could not find target
+        log during relay log initialization</errortext>. This is a known
+        issue which we intend to fix in a future MySQL release (see Bug
+        #2122). If you anticipate that a slave&apos;s hostname may
+        change in the future (for example, if networking is set up on
+        the slave such that its hostname can be modified via DHCP), then
+        you can use these options to prevent this problem from
+        occurring. However, if you encounter this issue, one way to work
+        around it is to stop the slave server, prepend the contents of
+        the old relay log index file to the new one, then restart the
+        slave. On a Unix system, this can be done as shown here, where
+        <replaceable>new_host_name</replaceable> is the new hostname and
+        <replaceable>old_host_name</replaceable> is the old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
       </para>
 
       <para>


Modified: trunk/refman-5.1/replication-notes.xml
===================================================================
--- trunk/refman-5.1/replication-notes.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-5.1/replication-notes.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 3; 982 bytes

@@ -65,9 +65,11 @@
     <para>
       The following sections provide details about what is supported and
       what is not, and about specific issues and situations that may
-      occur when replicating certain statements. Additional
-      <literal>InnoDB</literal>-specific information about replication
-      is given in <xref linkend="innodb-and-mysql-replication"/>.
+      occur when replicating certain statements. Additional information
+      specific to <literal>InnoDB</literal> and replication is given in
+      <xref linkend="innodb-and-mysql-replication"/>. For information
+      relating to replication with MySQL Cluster, see
+      <xref linkend="mysql-cluster-replication"/>.
     </para>
 
     <para>


Modified: trunk/refman-6.0/replication-implementation.xml
===================================================================
--- trunk/refman-6.0/replication-implementation.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-6.0/replication-implementation.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 27, Lines Deleted: 4; 2577 bytes

@@ -281,14 +281,37 @@
         the relay log files currently in use. The default relay log
         index filename is
        
<filename><replaceable>host_name</replaceable>-relay-bin.index</filename>.
+        By default, the slave server creates relay log files in its data
+        directory.
       </para>
 
       <para>
-        By default, the slave server creates relay log files in its data
-        directory. The default filenames can be overridden with the
+        The default filenames for relay logs and relay log index files
+        can be overridden with, respectively, the
         <option>--relay-log</option> and
-        <option>--relay-log-index</option> server options. See
-        <xref linkend="replication-options"/>.
+        <option>--relay-log-index</option> server options (see
+        <xref linkend="replication-options"/>). For this reason,
+        changing a replication slave&apos;s hostname can cause
+        replication to fail with the errors <errortext>Failed to open
+        the relay log</errortext> and <errortext>Could not find target
+        log during relay log initialization</errortext>. This is a known
+        issue which we intend to fix in a future MySQL release (see Bug
+        #2122). If you anticipate that a slave&apos;s hostname may
+        change in the future (for example, if networking is set up on
+        the slave such that its hostname can be modified via DHCP), then
+        you can use these options to prevent this problem from
+        occurring. However, if you encounter this issue, one way to work
+        around it is to stop the slave server, prepend the contents of
+        the old relay log index file to the new one, then restart the
+        slave. On a Unix system, this can be done as shown here, where
+        <replaceable>new_host_name</replaceable> is the new hostname and
+        <replaceable>old_host_name</replaceable> is the old one:
+
+<programlisting>
+shell&lt; <userinput>cat
<replaceable>new_host_name</replaceable>-relay-bin.index &gt;&gt;
<replaceable>old_host_name</replaceable>-relay-bin.index</userinput>
+
+shell&lt; <userinput>mv
<replaceable>old_host_name</replaceable>-relay-bin.index
<replaceable>new_host_name</replaceable>-relay-bin.index</userinput>
+</programlisting>
       </para>
 
       <para>


Modified: trunk/refman-6.0/replication-notes.xml
===================================================================
--- trunk/refman-6.0/replication-notes.xml	2008-06-19 02:03:27 UTC (rev 10979)
+++ trunk/refman-6.0/replication-notes.xml	2008-06-19 10:25:43 UTC (rev 10980)
Changed blocks: 1, Lines Added: 5, Lines Deleted: 3; 982 bytes

@@ -65,9 +65,11 @@
     <para>
       The following sections provide details about what is supported and
       what is not, and about specific issues and situations that may
-      occur when replicating certain statements. Additional
-      <literal>InnoDB</literal>-specific information about replication
-      is given in <xref linkend="innodb-and-mysql-replication"/>.
+      occur when replicating certain statements. Additional information
+      specific to <literal>InnoDB</literal> and replication is given in
+      <xref linkend="innodb-and-mysql-replication"/>. For information
+      relating to replication with MySQL Cluster, see
+      <xref linkend="mysql-cluster-replication"/>.
     </para>
 
     <para>