<div id="docs-body">
 <div class="section">
  <div class="titlepage">
   <div>
    <div>
     <h4 class="title">
      <a name="replica-logs-relaylog">
      </a>
      19.2.4.1 The Relay Log
     </h4>
    </div>
   </div>
  </div>
  <p>
   The relay log, like the binary log, consists of a set of
        numbered files containing events that describe database changes,
        and an index file that contains the names of all used relay log
        files. The default location for relay log files is the data
        directory.
  </p>
  <p>
   The term
   <span class="quote">
    “
    <span class="quote">
     relay log file
    </span>
    ”
   </span>
   generally denotes an
        individual numbered file containing database events. The term
   <span class="quote">
    “
    <span class="quote">
     relay log
    </span>
    ”
   </span>
   collectively denotes the set of
        numbered relay log files plus the index file.
  </p>
  <p>
   Relay log files have the same format as binary log files and can
        be read using
   <a class="link" href="mysqlbinlog.html" title="6.6.9 mysqlbinlog — Utility for Processing Binary Log Files">
    <span class="command">
     <strong>
      mysqlbinlog
     </strong>
    </span>
   </a>
   (see
   <a class="xref" href="mysqlbinlog.html" title="6.6.9 mysqlbinlog — Utility for Processing Binary Log Files">
    Section 6.6.9, “mysqlbinlog — Utility for Processing Binary Log Files”
   </a>
   ). If binary log transaction
        compression is in use, transaction payloads written to the relay
        log are compressed in the same way as for the binary log. For
        more information on binary log transaction compression, see
   <a class="xref" href="binary-log-transaction-compression.html" title="7.4.4.5 Binary Log Transaction Compression">
    Section 7.4.4.5, “Binary Log Transaction Compression”
   </a>
   .
  </p>
  <p>
   For the default replication channel, relay log file names have
        the default form
   <code class="filename">
    <em class="replaceable">
     <code>
      host_name
     </code>
    </em>
    -relay-bin.
    <em class="replaceable">
     <code>
      nnnnnn
     </code>
    </em>
   </code>
   ,
        where
   <em class="replaceable">
    <code>
     host_name
    </code>
   </em>
   is the name of the
        replica server host and
   <em class="replaceable">
    <code>
     nnnnnn
    </code>
   </em>
   is a
        sequence number. Successive relay log files are created using
        successive sequence numbers, beginning with
   <code class="literal">
    000001
   </code>
   . For non-default replication channels,
        the default base name is
   <code class="filename">
    <em class="replaceable">
     <code>
      host_name
     </code>
    </em>
    -relay-bin-
    <em class="replaceable">
     <code>
      channel
     </code>
    </em>
   </code>
   ,
        where
   <em class="replaceable">
    <code>
     channel
    </code>
   </em>
   is the name of the
        replication channel recorded in the relay log.
  </p>
  <p>
   The replica uses an index file to track the relay log files
        currently in use. The default relay log index file name is
   <code class="filename">
    <em class="replaceable">
     <code>
      host_name
     </code>
    </em>
    -relay-bin.index
   </code>
   for the default channel, and
   <code class="filename">
    <em class="replaceable">
     <code>
      host_name
     </code>
    </em>
    -relay-bin-
    <em class="replaceable">
     <code>
      channel
     </code>
    </em>
    .index
   </code>
   for non-default replication channels.
  </p>
  <p>
   The default relay log file and relay log index file names and
        locations can be overridden with, respectively, the
   <a class="link" href="replication-options-replica.html#sysvar_relay_log">
    <code class="literal">
     relay_log
    </code>
   </a>
   and
   <a class="link" href="replication-options-replica.html#sysvar_relay_log_index">
    <code class="literal">
     relay_log_index
    </code>
   </a>
   system
        variables (see
   <a class="xref" href="replication-options.html" title="19.1.6 Replication and Binary Logging Options and Variables">
    Section 19.1.6, “Replication and Binary Logging Options and Variables”
   </a>
   ).
  </p>
  <p>
   If a replica uses the default host-based relay log file names,
        changing a replica's host name after replication has been set up
        can cause replication to fail with the errors
   <span class="errortext">
    Failed
        to open the relay log
   </span>
   and
   <span class="errortext">
    Could not find
        target log during relay log initialization
   </span>
   . This is
        a known issue (see Bug #2122). If you anticipate that a
        replica's host name might change in the future (for example, if
        networking is set up on the replica such that its host name can
        be modified using DHCP), you can avoid this issue entirely by
        using the
   <a class="link" href="replication-options-replica.html#sysvar_relay_log">
    <code class="literal">
     relay_log
    </code>
   </a>
   and
   <a class="link" href="replication-options-replica.html#sysvar_relay_log_index">
    <code class="literal">
     relay_log_index
    </code>
   </a>
   system
        variables to specify relay log file names explicitly when you
        initially set up the replica. This causes the names to be
        independent of server host name changes.
  </p>
  <p>
   If you encounter the issue after replication has already begun,
        one way to work around it is to stop the replica server, prepend
        the contents of the old relay log index file to the new one, and
        then restart the replica. On a Unix system, this can be done as
        shown here:
  </p>
  <div class="copytoclipboard-wrapper">
   <pre class="programlisting language-terminal"><div class="docs-select-all right" id="sa39275147"><div class="copy-help left">Press ⌘+C to copy</div> <div class="right"><button class="clipboard-btn" title="Copy to Clipboard"><span class="icon-clipboard"></span></button></div></div><code class="language-terminal"><span class="token prompt">$&gt; </span><span class="token command">cat</span> <em class="replaceable">new_relay_log_name</em><span class="token punctuation">.</span>index &gt;&gt; <em class="replaceable">old_relay_log_name</em><span class="token punctuation">.</span>index
<span class="token prompt">$&gt; </span><span class="token command">mv</span> <em class="replaceable">old_relay_log_name</em><span class="token punctuation">.</span>index <em class="replaceable">new_relay_log_name</em><span class="token punctuation">.</span>index</code></pre>
  </div>
  <p>
   A replica server creates a new relay log file under the
        following conditions:
  </p>
  <div class="itemizedlist">
   <ul class="itemizedlist" style="list-style-type: disc; ">
    <li class="listitem">
     <p>
      Each time the replication I/O (receiver) thread starts.
     </p>
    </li>
    <li class="listitem">
     <p>
      When the logs are flushed (for example, with
      <a class="link" href="flush.html#flush-logs">
       <code class="literal">
        FLUSH LOGS
       </code>
      </a>
      or
      <a class="link" href="mysqladmin.html" title="6.5.2 mysqladmin — A MySQL Server Administration Program">
       <span class="command">
        <strong>
         mysqladmin flush-logs
        </strong>
       </span>
      </a>
      ).
     </p>
    </li>
    <li class="listitem">
     <p>
      When the size of the current relay log file becomes too
            large, which is determined as follows:
     </p>
     <div class="itemizedlist">
      <ul class="itemizedlist" style="list-style-type: circle; ">
       <li class="listitem">
        <p>
         If the value of
         <a class="link" href="replication-options-replica.html#sysvar_max_relay_log_size">
          <code class="literal">
           max_relay_log_size
          </code>
         </a>
         is
                greater than 0, that is the maximum relay log file size.
        </p>
       </li>
       <li class="listitem">
        <p>
         If the value of
         <a class="link" href="replication-options-replica.html#sysvar_max_relay_log_size">
          <code class="literal">
           max_relay_log_size
          </code>
         </a>
         is
                0,
         <a class="link" href="replication-options-binary-log.html#sysvar_max_binlog_size">
          <code class="literal">
           max_binlog_size
          </code>
         </a>
         determines the maximum relay log file size.
        </p>
       </li>
      </ul>
     </div>
    </li>
   </ul>
  </div>
  <p>
   The replication SQL (applier) thread automatically deletes each
        relay log file after it has executed all events in the file and
        no longer needs it. There is no explicit mechanism for deleting
        relay logs because the replication SQL thread takes care of
        doing so. However,
   <a class="link" href="flush.html#flush-logs">
    <code class="literal">
     FLUSH LOGS
    </code>
   </a>
   rotates relay logs, which influences when the replication SQL
        thread deletes them.
  </p>
 </div>
 <br/>
</div>
