Author: paul
Date: 2007-12-07 19:17:33 +0100 (Fri, 07 Dec 2007)
New Revision: 9199
Log:
r34026@arctic: paul | 2007-12-07 12:06:58 -0600
Move server-logs section closer to initial mysqld material.
Modified:
trunk/refman-4.1/dba-core.xml
trunk/refman-5.0/dba-core.xml
trunk/refman-5.1/dba-core.xml
trunk/refman-6.0/dba-core.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:34025
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:27855
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:22582
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:34026
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:27855
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:22582
Modified: trunk/refman-4.1/dba-core.xml
===================================================================
--- trunk/refman-4.1/dba-core.xml 2007-12-07 18:16:27 UTC (rev 9198)
+++ trunk/refman-4.1/dba-core.xml 2007-12-07 18:17:33 UTC (rev 9199)
Changed blocks: 3, Lines Added: 1152, Lines Deleted: 1152; 91324 bytes
@@ -27,19 +27,19 @@
<listitem>
<para>
- Managing user accounts
+ The server log files
</para>
</listitem>
<listitem>
<para>
- Performing backups
+ Managing user accounts
</para>
</listitem>
<listitem>
<para>
- The server log files
+ Performing backups
</para>
</listitem>
@@ -9342,6 +9342,1155 @@
</section>
+ <section id="log-files">
+
+ <title>MySQL Server Logs</title>
+
+ <indexterm>
+ <primary>log files</primary>
+ </indexterm>
+
+ <para>
+ MySQL has several different logs that can help you find out what
+ is going on inside <command>mysqld</command>:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Log Type</emphasis></entry>
+ <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
+ </row>
+ <row>
+ <entry>The error log</entry>
+ <entry>Problems encountered starting, running, or stopping
+ <command>mysqld</command></entry>
+ </row>
+ <row>
+ <entry>The isam log</entry>
+ <entry>All changes to the <literal>ISAM</literal> tables (used only for
+ debugging the <literal>ISAM</literal> code)</entry>
+ </row>
+ <row>
+ <entry>The general query log</entry>
+ <entry>Established client connections and statements received from clients</entry>
+ </row>
+ <row>
+ <entry>The update log</entry>
+ <entry>All statements that change data (this log is deprecated)</entry>
+ </row>
+ <row>
+ <entry>The binary log</entry>
+ <entry>All statements that change data (also used for replication)</entry>
+ </row>
+ <row>
+ <entry>The slow query log</entry>
+ <entry>All queries that took more than <literal>long_query_time</literal>
+ seconds to execute or didn't use indexes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ By default, all log files are created in the
+ <command>mysqld</command> data directory. You can force
+ <command>mysqld</command> to close and reopen the log files (or in
+ some cases switch to a new log) by flushing the logs. Log flushing
+ occurs when you issue a <literal>FLUSH LOGS</literal> statement or
+ execute <command>mysqladmin flush-logs</command> or
+ <command>mysqladmin refresh</command>. See
+ <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ If you are using MySQL replication capabilities, slave replication
+ servers maintain additional log files called relay logs.
+ <xref linkend="replication"/>, discusses relay log contents and
+ configuration.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The MySQL Enterprise Monitor provides a number of advisors
+ specifically related to the various log files. For more
+ information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <section id="error-log">
+
+ <title>The Error Log</title>
+
+ <para>
+ The error log contains information indicating when
+ <command>mysqld</command> was started and stopped and also any
+ critical errors that occur while the server is running. If
+ <command>mysqld</command> notices a table that needs to be
+ automatically checked or repaired, it writes a message to the
+ error log.
+ </para>
+
+ <para>
+ On some operating systems, the error log contains a stack trace
+ if <command>mysqld</command> dies. The trace can be used to
+ determine where <command>mysqld</command> died. See
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
+ Internals: Porting</ulink>.
+ </para>
+
+ <para>
+ Beginning with MySQL 4.0.10, you can specify where
+ <command>mysqld</command> writes the error log with the
+ <option>--log-error[=<replaceable>file_name</replaceable>]</option>
+ option. If no <replaceable>file_name</replaceable> value is
+ given, <command>mysqld</command> uses the name
+ <filename><replaceable>host_name</replaceable>.err</filename> by
+ default and writes the file in the data directory. (Prior to
+ MySQL 4.0.10, the Windows error log name is
+ <filename>mysql.err</filename>.) If you execute <literal>FLUSH
+ LOGS</literal>, the error log is renamed with a suffix of
+ <literal>-old</literal> and <command>mysqld</command> creates a
+ new empty log file. (No renaming occurs if the
+ <option>--log-error</option> option was not given to
+ <command>mysqld</command>.)
+ </para>
+
+ <para>
+ In older MySQL versions on Unix, error log handling was done by
+ <command>mysqld_safe</command> which redirected the error file
+ to <literal><replaceable>host_name</replaceable>.err</literal>.
+ You could change this filename by specifying a
+ <option>--err-log=<replaceable>file_name</replaceable></option>
+ option to <command>mysqld_safe</command>.
+ </para>
+
+ <para>
+ If you do not specify <option>--log-error</option>, or (on
+ Windows) if you use the <option>--console</option> option,
+ errors are written to <literal>stderr</literal>, the standard
+ error output. Usually this is your terminal.
+ </para>
+
+ <para>
+ On Windows, error output is always written to the
+ <literal>.err</literal> file if <option>--console</option> is
+ not given.
+ </para>
+
+ <para>
+ The <option>--log-warnings</option> option or
+ <literal>log_warnings</literal> system variable can be used to
+ control warning logging to the error log. The default value is
+ enabled (1) as of MySQL 4.0.19 and 4.1.2. Warning logging can be
+ disabled using a value of 0. As of MySQL 4.0.21 and 4.1.3, the
+ value can be greater than 1. If the value is greater than 1,
+ aborted connections are written to the error log. See
+ <xref linkend="communication-errors"/>.
+ </para>
+
+ <para>
+ If <command>mysqld_safe</command> is used to start
+ <command>mysqld</command> and <command>mysqld</command> dies
+ unexpectedly, <command>mysqld_safe</command> notices that it
+ needs to restart <command>mysqld</command> and writes a
+ <literal>restarted mysqld</literal> message to the error log.
+ </para>
+
+ </section>
+
+ <section id="query-log">
+
+ <title>The General Query Log</title>
+
+ <indexterm>
+ <primary>general query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>general query log</secondary>
+ </indexterm>
+
+ <para>
+ The general query log is a general record of what
+ <command>mysqld</command> is doing. The server writes
+ information to this log when clients connect or disconnect, and
+ it logs each SQL statement received from clients. The general
+ query log can be very useful when you suspect an error in a
+ client and want to know exactly what the client sent to
+ <command>mysqld</command>.
+ </para>
+
+ <remark role="note">
+ This instance of "safe_mysql" should not be changed to
+ "mysqld_safe" because it is in the context of a 3.23.x-specific
+ command.
+ </remark>
+
+ <para>
+ Older versions of the <command>mysql.server</command> script
+ (from MySQL 3.23.4 to 3.23.8) pass a <option>--log</option>
+ option to <command>safe_mysqld</command> to enable the general
+ query log. If you need better performance when you start using
+ MySQL in a production environment, you can remove the
+ <option>--log</option> option from
+ <command>mysql.server</command> or change it to
+ <option>--log-bin</option>. See <xref linkend="binary-log"/>.
+ </para>
+
+ <para>
+ <command>mysqld</command> writes statements to the query log in
+ the order that it receives them, which might differ from the
+ order in which they are executed. This logging order contrasts
+ to the update log and the binary log, which are written after
+ the query is executed but before any locks are released. (Also,
+ the query log contains all statements, whereas the update and
+ binary logs do not contain statements that only select data.)
+ </para>
+
+ <para>
+ To enable the general query log, start <command>mysqld</command>
+ with the
+ <option>--log[=<replaceable>file_name</replaceable>]</option> or
+ <option>-l [<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log</option> or <option>-l</option>, the default name
+ is <filename><replaceable>host_name</replaceable>.log</filename>
+ in the data directory.
+ </para>
+
+ <para>
+ Server restarts and log flushing do not cause a new general
+ query log file to be generated (although flushing closes and
+ reopens it). On Unix, you can rename the file and create a new
+ one by using the following commands:
+ </para>
+
+<programlisting>
+shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
+shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
+</programlisting>
+
+ <para>
+ On Windows, you cannot rename the log file while the server has
+ it open. You must stop the server and rename the file, and then
+ restart the server to create a new log file.
+ </para>
+
+ <para>
+ The session <literal>sql_log_off</literal> variable can be set
+ to <literal>ON</literal> or <literal>OFF</literal> to disable or
+ enable general query logging for the current connection.
+ </para>
+
+ </section>
+
+ <section id="update-log">
+
+ <title>The Update Log</title>
+
+ <indexterm>
+ <primary>update log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>update log</secondary>
+ </indexterm>
+
+ <note>
+ <para>
+ The update log has been deprecated and replaced by the more
+ useful, informative, and efficient binary log. See
+ <xref linkend="binary-log"/>.
+ </para>
+ </note>
+
+ <para>
+ When started with the
+ <option>--log-update[=<replaceable>file_name</replaceable>]</option>
+ option, <command>mysqld</command> writes a log file containing
+ all SQL statements that update data. If no
+ <replaceable>file_name</replaceable> value is given, the default
+ name is name of the host machine. If a filename is given, but it
+ does not contain a leading path, the file is written in the data
+ directory. If <filename>file_name</filename> does not have an
+ extension, <command>mysqld</command> creates log files with
+ names of the form <replaceable>file_name.nnnnnn</replaceable>,
+ where <replaceable>nnnnnn</replaceable> is a number that is
+ incremented each time you start the server or flush the logs.
+ </para>
+
+ <note>
+ <para>
+ For this naming scheme to work, you must not create your own
+ files with the same names as those that might be used in the
+ log file sequence.
+ </para>
+ </note>
+
+ <para>
+ Update logging is <quote>smart</quote> in that <emphasis>it logs
+ only statements that actually update data</emphasis>. Thus, an
+ <literal>UPDATE</literal> or <literal>DELETE</literal> with a
+ <literal>WHERE</literal> clause that finds no rows is not
+ written to the log. Update logging also skips
+ <literal>UPDATE</literal> statements that merely set a column to
+ its existing value.
+ </para>
+
+ <para>
+ The update logging is done immediately after a query completes
+ but before any locks are released or any commit is done. This
+ ensures that statements are logged in execution order.
+ </para>
+
+ <para>
+ If you want to update a database from update log files, you
+ could do the following (assuming that your update logs have
+ names of the form <filename>file_name.nnnnnn</filename>):
+ </para>
+
+<programlisting>
+shell> <userinput>ls -1 -t -r file_name.[0-9]* | xargs cat | mysql</userinput>
+</programlisting>
+
+ <para>
+ <command>ls</command> is used to sort the update log filenames
+ into the right order.
+ </para>
+
+ <para>
+ This can be useful if you have to revert to backup files after a
+ crash and you want to redo the updates that occurred between the
+ time of the backup and the crash.
+ </para>
+
+ </section>
+
+ <section id="binary-log">
+
+ <title>The Binary Log</title>
+
+ <indexterm>
+ <primary>binary log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>binary log</secondary>
+ </indexterm>
+
+ <para>
+ The binary log contains all statements that update data or
+ (starting from MySQL 4.1.3) potentially could have updated it
+ (for example, a <literal>DELETE</literal> which matched no
+ rows). Statements are stored in the form of
+ <quote>events</quote> that describe the modifications. The
+ binary log also contains information about how long each
+ statement took that updated data.
+ </para>
+
+ <note>
+ <para>
+ The binary log has replaced the old update log, which is being
+ phased out of future MySQL release series after 4.1. The
+ binary log contains all information that is available in the
+ update log in a more efficient format and in a manner that is
+ transaction-safe. If you are using transactions, you must use
+ the MySQL binary log for backups instead of the old update
+ log.
+ </para>
+ </note>
+
+ <para>
+ The binary log is not used for statements such as
+ <literal>SELECT</literal> or <literal>SHOW</literal> that do not
+ modify data. If you want to log all statements (for example, to
+ identify a problem query), use the general query log. See
+ <xref linkend="query-log"/>.
+ </para>
+
+ <para>
+ The primary purpose of the binary log is to be able to update
+ databases during a restore operation as fully as possible,
+ because the binary log contains all updates done after a backup
+ was made. The binary log is also used on master replication
+ servers as a record of the statements to be sent to slave
+ servers. See <xref linkend="replication"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The binary log can also be used to track significant DDL
+ events. Analyzing the binary log in this way is an integral
+ part of the MySQL Enterprise Monitor. For more information
+ see, <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ Running the server with the binary log enabled makes performance
+ about 1% slower. However, the benefits of the binary log for
+ restore operations and in allowing you to set up replication
+ generally outweigh this minor performance decrement.
+ </para>
+
+ <para>
+ When started with the
+ <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
+ option, <command>mysqld</command> writes a log file containing
+ all SQL statements that update data (both DDL and DML
+ statements). If no <replaceable>base_name</replaceable> value is
+ given, the default name is the value of the
+ <literal>pid-file</literal> option (which by default is the name
+ of host machine) followed by <literal>-bin</literal>. If the
+ basename is given, but not as an absolute pathname, the server
+ writes the file in the data directory. It is recommended that
+ you specify a basename; see <xref linkend="open-bugs"/>, for the
+ reason.
+ </para>
+
+ <para>
+ If you supply an extension in the log name (for example,
+ <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
+ the extension is silently removed and ignored.
+ </para>
+
+ <para>
+ <command>mysqld</command> appends a numeric extension to the
+ binary log basename. The number increases each time the server
+ creates a new log file, thus creating an ordered series of
+ files. The server creates a new binary log file each time it
+ starts or flushes the logs. The server also creates a new binary
+ log file automatically when the current log's size reaches
+ <literal>max_binlog_size</literal>. A binary log file may become
+ larger than <literal>max_binlog_size</literal> if you are using
+ large transactions because a transaction is written to the file
+ in one piece, never split between files.
+ </para>
+
+ <para>
+ To keep track of which binary log files have been used,
+ <command>mysqld</command> also creates a binary log index file
+ that contains the names of all used binary log files. By default
+ this has the same basename as the binary log file, with the
+ extension <literal>'.index'</literal>. You can change the name
+ of the binary log index file with the
+ <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
+ option. You should not manually edit this file while
+ <command>mysqld</command> is running; doing so would confuse
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ Replication slave servers by default do not write to their own
+ binary log any statements that are received from the replication
+ master. To cause these statements to be logged, start the slave
+ with the <option>--log-slave-updates</option> option.
+ </para>
+
+ <para>
+ Before MySQL 4.1.9, writes to a binary log file or binary log
+ index file that failed due to a full disk or an exceeded quota
+ resulted in corruption of the file. Starting from MySQL 4.1.9,
+ writes to the binary log file and binary log index file are
+ handled the same way as writes to <literal>MyISAM</literal>
+ tables. See <xref linkend="full-disk"/>.
+ </para>
+
+ <para>
+ You can delete all binary log files with the <literal>RESET
+ MASTER</literal> statement, or a subset of them with
+ <literal>PURGE MASTER LOGS</literal>. See
+ <xref linkend="reset"/>, and
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ The binary log format has some known limitations that can affect
+ recovery from backups, especially in old versions. These
+ caveats, which also affect replication, are listed at
+ <xref linkend="replication-features"/>. One caveat which does
+ not affect replication but only recovery with
+ <literal>mysqlbinlog</literal>: before MySQL 4.1,
+ <command>mysqlbinlog</command> could not prepare output suitable
+ for <command>mysql</command> if the binary log contained
+ interlaced statements originating from different clients that
+ used temporary tables of the same name. This is fixed in MySQL
+ 4.1. However, the problem still existed for <literal>LOAD DATA
+ INFILE</literal> statements until it was fixed in MySQL 4.1.8.
+ </para>
+
+ <para>
+ You can use the following options to <command>mysqld</command>
+ to affect what is logged to the binary log. See also the
+ discussion that follows this option list.
+ </para>
+
+ <para>
+ If you are using replication, the options described here affect
+ which statements are sent by a master server to its slaves.
+ There are also options for slave servers that control which
+ statements received from the master to execute or ignore. For
+ details, see <xref linkend="replication-options"/>.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para id="option_mysqld_binlog-do-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-do-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-do-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to restrict binary logging to updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). All other databases
+ that are not explicitly mentioned are ignored. If you use
+ this option, you should ensure that you do updates only in
+ the default database.
+ </para>
+
+ <para>
+ There is an exception to this for <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. The server uses
+ the database named in the statement (not the default
+ database) to decide whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-do-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement is
+ <emphasis>not</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To log multiple databases, use multiple options, specifying
+ the option once for each database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqld_binlog-ignore-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-ignore-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-ignore-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to suppress binary logging of updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). If you use this option,
+ you should ensure that you do updates only in the default
+ database.
+ </para>
+
+ <para>
+ As with the <option>--binlog-do-db</option> option, there is
+ an exception for the <literal>CREATE DATABASE</literal>,
+ <literal>ALTER DATABASE</literal>, and <literal>DROP
+ DATABASE</literal> statements. The server uses the database
+ named in the statement (not the default database) to decide
+ whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-ignore-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement
+ <emphasis>is</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To ignore multiple databases, use multiple options,
+ specifying the option once for each database.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server evaluates the options for logging or ignoring updates
+ to the binary log according to the following rules. As described
+ previously, there is an exception for the <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. In those cases, the
+ database being <emphasis>created, altered, or dropped</emphasis>
+ replaces the default database in the following rules:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Are there <option>--binlog-do-db</option> or
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Write the statement to the binary log and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some rules (<option>--binlog-do-db</option>,
+ <option>--binlog-ignore-db</option>, or both). Is there a
+ default database (has any database been selected by
+ <literal>USE</literal>?)?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement, and
+ exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There is a default database. Are there some
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Does the default database match any of the
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Write the statement and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement,
+ and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some <option>--binlog-ignore-db</option> rules.
+ Does the default database match any of the
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Do not write the statement, and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Write the query and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ For example, a slave running with only
+ <option>--binlog-do-db=sales</option> does not write to the
+ binary log any statement for which the default database is
+ different from <literal>sales</literal> (in other words,
+ <option>--binlog-do-db</option> can sometimes mean <quote>ignore
+ other databases</quote>).
+ </para>
+
+ <para>
+ If you are using replication, you should not delete old binary
+ log files until you are sure that no slave still needs to use
+ them. For example, if your slaves never run more than three days
+ behind, once a day you can execute <command>mysqladmin
+ flush-logs</command> on the master and then remove any logs that
+ are more than three days old. You can remove the files manually,
+ but it is preferable to use <literal>PURGE MASTER
+ LOGS</literal>, which also safely updates the binary log index
+ file for you (and which can take a date argument as of MySQL
+ 4.1). See <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ A client that has the <literal>SUPER</literal> privilege can
+ disable binary logging of its own statements by using a
+ <literal>SET SQL_LOG_BIN=0</literal> statement. See
+ <xref linkend="set-option"/>.
+ </para>
+
+ <para>
+ You can display the contents of binary log files with the
+ <command>mysqlbinlog</command> utility. This can be useful when
+ you want to reprocess statements in the log. For example, you
+ can update a MySQL server from the binary log as follows:
+ </para>
+
+<programlisting>
+shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
+</programlisting>
+
+ <para>
+ See <xref linkend="mysqlbinlog"/>, for more information on the
+ <command>mysqlbinlog</command> utility and how to use it.
+ <command>mysqlbinlog</command> also can be used with relay log
+ files because they are written using the same format as binary
+ log files.
+ </para>
+
+ <para>
+ Binary logging is done immediately after a statement completes
+ but before any locks are released or any commit is done. This
+ ensures that the log is logged in execution order.
+ </para>
+
+ <para>
+ Updates to non-transactional tables are stored in the binary log
+ immediately after execution. Within an uncommitted transaction,
+ all updates (<literal>UPDATE</literal>,
+ <literal>DELETE</literal>, or <literal>INSERT</literal>) that
+ change transactional tables such as <literal>BDB</literal> or
+ <literal>InnoDB</literal> tables are cached until a
+ <literal>COMMIT</literal> statement is received by the server.
+ At that point, <command>mysqld</command> writes the entire
+ transaction to the binary log before the
+ <literal>COMMIT</literal> is executed. When the thread that
+ handles the transaction starts, it allocates a buffer of
+ <literal>binlog_cache_size</literal> to buffer statements. If a
+ statement is bigger than this, the thread opens a temporary file
+ to store the transaction. The temporary file is deleted when the
+ thread ends.
+ </para>
+
+ <para>
+ Modifications to non-transactional tables cannot be rolled back.
+ If a transaction that is rolled back includes modifications to
+ non-transactional tables, the entire transaction is logged with
+ a <literal>ROLLBACK</literal> statement at the end to ensure
+ that the modifications to those tables are replicated. This is
+ true as of MySQL 4.0.15.
+ </para>
+
+ <para>
+ The <literal>Binlog_cache_use</literal> status variable shows
+ the number of transactions that used this buffer (and possibly a
+ temporary file) for storing statements. The
+ <literal>Binlog_cache_disk_use</literal> status variable shows
+ how many of those transactions actually had to use a temporary
+ file. These two variables can be used for tuning
+ <literal>binlog_cache_size</literal> to a large enough value
+ that avoids the use of temporary files.
+ </para>
+
+ <para>
+ The <literal>max_binlog_cache_size</literal> system variable
+ (default 4GB, which is also the maximum) can be used to restrict
+ the total size used to cache a multiple-statement transaction.
+ If a transaction is larger than this many bytes, it fails and
+ rolls back. The minimum value is 4096.
+ </para>
+
+ <para>
+ If you are using the update log or binary log, concurrent
+ inserts are converted to normal inserts for <literal>CREATE ...
+ SELECT</literal> or <literal>INSERT ... SELECT</literal>
+ statements. This is done to ensure that you can re-create an
+ exact copy of your tables by applying the log during a backup
+ operation.
+ </para>
+
+ <para>
+ The binary log format differs between versions 3.23 and 4.0.
+ (These format changes were required to implement enhancements to
+ replication.) However, MySQL 4.1 has the same binary log format
+ as 4.0. See <xref linkend="replication-compatibility"/>.
+ </para>
+
+ <para>
+ By default, the binary log is not synchronized to disk at each
+ write. So if the operating system or machine (not only the MySQL
+ server) crashes, there is a chance that the last statements of
+ the binary log are lost. To prevent this, you can make the
+ binary log be synchronized to disk after every
+ <replaceable>N</replaceable> writes to the binary log, with the
+ <literal>sync_binlog</literal> system variable. See
+ <xref linkend="server-system-variables"/>. 1 is the safest value
+ for <literal>sync_binlog</literal>, but also the slowest. Even
+ with <literal>sync_binlog</literal> set to 1, there is still the
+ chance of an inconsistency between the table content and binary
+ log content in case of a crash. For example, if you are using
+ <literal>InnoDB</literal> tables and the MySQL server processes
+ a <literal>COMMIT</literal> statement, it writes the whole
+ transaction to the binary log and then commits this transaction
+ into <literal>InnoDB</literal>. If the server crashes between
+ those two operations, the transaction is rolled back by
+ <literal>InnoDB</literal> at restart but still exists in the
+ binary log. This problem can be solved with the
+ <option>--innodb-safe-binlog</option> option (available starting
+ from MySQL 4.1.3), which adds consistency between the content of
+ <literal>InnoDB</literal> tables and the binary log.
+ </para>
+
+ <para>
+ For this option to provide a greater degree of safety, the MySQL
+ server should also be configured to synchronize the binary log
+ and the <literal>InnoDB</literal> logs to disk at every
+ transaction. The <literal>InnoDB</literal> logs are synchronized
+ by default, and <literal>sync_binlog=1</literal> can be used to
+ synchronize the binary log. The effect of this option is that at
+ restart after a crash, after doing a rollback of transactions,
+ the MySQL server cuts rolled back <literal>InnoDB</literal>
+ transactions from the binary log. This ensures that the binary
+ log reflects the exact data of <literal>InnoDB</literal> tables,
+ and so, that the slave remains in synchrony with the master (not
+ receiving a statement which has been rolled back).
+ </para>
+
+ <para>
+ Note that <option>--innodb-safe-binlog</option> can be used even
+ if the MySQL server updates other storage engines than
+ <literal>InnoDB</literal>. Only statements and transactions that
+ affect <literal>InnoDB</literal> tables are subject to removal
+ from the binary log at <literal>InnoDB</literal>'s crash
+ recovery. If the MySQL server discovers at crash recovery that
+ the binary log is shorter than it should have been, it lacks at
+ least one successfully committed <literal>InnoDB</literal>
+ transaction. This should not happen if
+ <literal>sync_binlog=1</literal> and the disk/filesystem do an
+ actual sync when they are requested to (some don't), so the
+ server prints an error message <literal>The binary log
+ <name> is shorter than its expected size</literal>. In
+ this case, this binary log is not correct and replication should
+ be restarted from a fresh snapshot of the master's data.
+ </para>
+
+ </section>
+
+ <section id="slow-query-log">
+
+ <title>The Slow Query Log</title>
+
+ <indexterm>
+ <primary>slow query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>slow query log</secondary>
+ </indexterm>
+
+ <para>
+ The slow query log consists of all SQL statements that took more
+ than <literal>long_query_time</literal> seconds to execute. The
+ time to acquire the initial table locks is not counted as
+ execution time. <command>mysqld</command> writes a statement to
+ the slow query log after it has been executed and after all
+ locks have been released, so log order might be different from
+ execution order. The minimum and default values of
+ <literal>long_query_time</literal> are 1 and 10, respectively.
+ </para>
+
+ <para>
+ To enable the slow query log, start <command>mysqld</command>
+ with the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log-slow-queries</option>, the default name is
+ <filename><replaceable>host_name</replaceable>-slow.log</filename>.
+ If a filename is given, but not as an absolute pathname, the
+ server writes the file in the data directory.
+ </para>
+
+ <para>
+ The slow query log can be used to find queries that take a long
+ time to execute and are therefore candidates for optimization.
+ However, examining a long slow query log can become a difficult
+ task. To make this easier, you can process the slow query log
+ using the <command>mysqldumpslow</command> command to summarize
+ the queries that appear in the log. Use <command>mysqldumpslow
+ --help</command> to see the options that this command supports.
+ </para>
+
+ <para>
+ Before MySQL 4.1, if you also use
+ <option>--log-long-format</option> when logging slow queries,
+ queries that are not using indexes are logged as well. Starting
+ with MySQL 4.1, logging of queries not using indexes is enabled
+ using the <option>--log-queries-not-using-indexes</option>
+ option instead. The <option>--log-long-format</option> is
+ deprecated as of MySQL 4.1, when
+ <option>--log-short-format</option> was introduced, which causes
+ less information to be logged. (The long log format is the
+ default setting since version 4.1.). See
+ <xref linkend="server-options"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ Excessive table scans are indicative of missing or poorly
+ optimized indexes. Using an advisor specifically designed for
+ the task, the MySQL Enterprise Monitor can identify such
+ problems and offer advice on resolution. For more information
+ see, <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ In MySQL 4.0, slow administrative statements such as
+ <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
+ TABLE</literal>, and <literal>ALTER TABLE</literal> were written
+ to the slow query log. This logging was disabled in MySQL 4.1
+ until 4.1.13, when the
+ <option>--log-slow-admin-statements</option> server option was
+ added to specify logging of slow administrative statements.
+ </para>
+
+ <para>
+ Queries handled by the query cache are not added to the slow
+ query log, nor are queries that would not benefit from the
+ presence of an index because the table has zero rows or one row.
+ </para>
+
+ </section>
+
+ <section id="log-file-maintenance">
+
+ <title>Server Log Maintenance</title>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>log</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>maintaining</primary>
+ <secondary>log files</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>maintaining</secondary>
+ </indexterm>
+
+ <para>
+ MySQL Server can create a number of different log files that
+ make it easy to see what is going on. See
+ <xref linkend="log-files"/>. However, you must clean up these
+ files regularly to ensure that the logs do not take up too much
+ disk space.
+ </para>
+
+ <para>
+ When using MySQL with logging enabled, you may want to back up
+ and remove old log files from time to time and tell MySQL to
+ start logging to new files. See <xref linkend="backup"/>.
+ </para>
+
+ <para>
+ On a Linux (Red Hat) installation, you can use the
+ <literal>mysql-log-rotate</literal> script for this. If you
+ installed MySQL from an RPM distribution, this script should
+ have been installed automatically. You should be careful with
+ this script if you are using the binary log for replication. You
+ should not remove binary logs until you are certain that their
+ contents have been processed by all slaves.
+ </para>
+
+ <para>
+ On other systems, you must install a short script yourself that
+ you start from <command>cron</command> (or its equivalent) for
+ handling log files.
+ </para>
+
+ <para>
+ For the binary log, you can set the
+ <literal>expire_logs_days</literal> system variable to expire
+ binary log files automatically after a given number of days (see
+ <xref linkend="server-system-variables"/>). If you are using
+ replication, you should set the variable no lower than the
+ maximum number of days your slaves might lag behind the master.
+ </para>
+
+ <para>
+ You can force MySQL to start using new log files by issuing a
+ <literal>FLUSH LOGS</literal> statement or executing
+ <command>mysqladmin flush-logs</command> or <command>mysqladmin
+ refresh</command>. See <xref linkend="flush"/>, and
+ <xref linkend="mysqladmin"/>. If you are using MySQL 3.21, you
+ must use <command>mysqladmin refresh</command>.
+ </para>
+
+ <para>
+ A log flushing operation does the following:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If general query logging (<option>--log</option>) or slow
+ query logging (<option>--log-slow-queries</option>) to a log
+ file is enabled, the server closes and reopens the general
+ query log file or slow query log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If update logging (<option>--log-update</option>) or binary
+ logging (<option>--log-bin</option>) is used, closes the log
+ and opens a new log file with a higher sequence number.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the server was given an error log filename with the
+ <option>--log-error</option> option, it renames the error
+ log with the suffix <literal>-old</literal> and creates a
+ new empty error log file.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server creates a new binary log file when you flush the
+ logs. However, it just closes and reopens the general and slow
+ query log files. To cause new files to be created on Unix,
+ rename the current logs before flushing them. At flush time, the
+ server will open new logs with the original names. For example,
+ if the general and slow query logs are named
+ <filename>mysql.log</filename> and
+ <filename>mysql-slow.log</filename>, you can use a series of
+ commands like this:
+ </para>
+
+<programlisting>
+shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
+shell> <userinput>mv mysql.log mysql.old</userinput>
+shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+</programlisting>
+
+ <para>
+ At this point, you can make a backup of
+ <filename>mysql.old</filename> and
+ <filename>mysql-slow.log</filename> and then remove them from
+ disk.
+ </para>
+
+ <para>
+ On Windows, you cannot rename log files while the server has
+ them open. You must stop the server and rename them, and then
+ restart the server to create new logs.
+ </para>
+
+ </section>
+
+ </section>
+
<section id="security">
<title>General Security Issues</title>
@@ -19077,1155 +20226,6 @@
</section>
- <section id="log-files">
-
- <title>MySQL Server Logs</title>
-
- <indexterm>
- <primary>log files</primary>
- </indexterm>
-
- <para>
- MySQL has several different logs that can help you find out what
- is going on inside <command>mysqld</command>:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Log Type</emphasis></entry>
- <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
- </row>
- <row>
- <entry>The error log</entry>
- <entry>Problems encountered starting, running, or stopping
- <command>mysqld</command></entry>
- </row>
- <row>
- <entry>The isam log</entry>
- <entry>All changes to the <literal>ISAM</literal> tables (used only for
- debugging the <literal>ISAM</literal> code)</entry>
- </row>
- <row>
- <entry>The general query log</entry>
- <entry>Established client connections and statements received from clients</entry>
- </row>
- <row>
- <entry>The update log</entry>
- <entry>All statements that change data (this log is deprecated)</entry>
- </row>
- <row>
- <entry>The binary log</entry>
- <entry>All statements that change data (also used for replication)</entry>
- </row>
- <row>
- <entry>The slow query log</entry>
- <entry>All queries that took more than <literal>long_query_time</literal>
- seconds to execute or didn't use indexes</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- By default, all log files are created in the
- <command>mysqld</command> data directory. You can force
- <command>mysqld</command> to close and reopen the log files (or in
- some cases switch to a new log) by flushing the logs. Log flushing
- occurs when you issue a <literal>FLUSH LOGS</literal> statement or
- execute <command>mysqladmin flush-logs</command> or
- <command>mysqladmin refresh</command>. See
- <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- If you are using MySQL replication capabilities, slave replication
- servers maintain additional log files called relay logs.
- <xref linkend="replication"/>, discusses relay log contents and
- configuration.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The MySQL Enterprise Monitor provides a number of advisors
- specifically related to the various log files. For more
- information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <section id="error-log">
-
- <title>The Error Log</title>
-
- <para>
- The error log contains information indicating when
- <command>mysqld</command> was started and stopped and also any
- critical errors that occur while the server is running. If
- <command>mysqld</command> notices a table that needs to be
- automatically checked or repaired, it writes a message to the
- error log.
- </para>
-
- <para>
- On some operating systems, the error log contains a stack trace
- if <command>mysqld</command> dies. The trace can be used to
- determine where <command>mysqld</command> died. See
- <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
- Internals: Porting</ulink>.
- </para>
-
- <para>
- Beginning with MySQL 4.0.10, you can specify where
- <command>mysqld</command> writes the error log with the
- <option>--log-error[=<replaceable>file_name</replaceable>]</option>
- option. If no <replaceable>file_name</replaceable> value is
- given, <command>mysqld</command> uses the name
- <filename><replaceable>host_name</replaceable>.err</filename> by
- default and writes the file in the data directory. (Prior to
- MySQL 4.0.10, the Windows error log name is
- <filename>mysql.err</filename>.) If you execute <literal>FLUSH
- LOGS</literal>, the error log is renamed with a suffix of
- <literal>-old</literal> and <command>mysqld</command> creates a
- new empty log file. (No renaming occurs if the
- <option>--log-error</option> option was not given to
- <command>mysqld</command>.)
- </para>
-
- <para>
- In older MySQL versions on Unix, error log handling was done by
- <command>mysqld_safe</command> which redirected the error file
- to <literal><replaceable>host_name</replaceable>.err</literal>.
- You could change this filename by specifying a
- <option>--err-log=<replaceable>file_name</replaceable></option>
- option to <command>mysqld_safe</command>.
- </para>
-
- <para>
- If you do not specify <option>--log-error</option>, or (on
- Windows) if you use the <option>--console</option> option,
- errors are written to <literal>stderr</literal>, the standard
- error output. Usually this is your terminal.
- </para>
-
- <para>
- On Windows, error output is always written to the
- <literal>.err</literal> file if <option>--console</option> is
- not given.
- </para>
-
- <para>
- The <option>--log-warnings</option> option or
- <literal>log_warnings</literal> system variable can be used to
- control warning logging to the error log. The default value is
- enabled (1) as of MySQL 4.0.19 and 4.1.2. Warning logging can be
- disabled using a value of 0. As of MySQL 4.0.21 and 4.1.3, the
- value can be greater than 1. If the value is greater than 1,
- aborted connections are written to the error log. See
- <xref linkend="communication-errors"/>.
- </para>
-
- <para>
- If <command>mysqld_safe</command> is used to start
- <command>mysqld</command> and <command>mysqld</command> dies
- unexpectedly, <command>mysqld_safe</command> notices that it
- needs to restart <command>mysqld</command> and writes a
- <literal>restarted mysqld</literal> message to the error log.
- </para>
-
- </section>
-
- <section id="query-log">
-
- <title>The General Query Log</title>
-
- <indexterm>
- <primary>general query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>general query log</secondary>
- </indexterm>
-
- <para>
- The general query log is a general record of what
- <command>mysqld</command> is doing. The server writes
- information to this log when clients connect or disconnect, and
- it logs each SQL statement received from clients. The general
- query log can be very useful when you suspect an error in a
- client and want to know exactly what the client sent to
- <command>mysqld</command>.
- </para>
-
- <remark role="note">
- This instance of "safe_mysql" should not be changed to
- "mysqld_safe" because it is in the context of a 3.23.x-specific
- command.
- </remark>
-
- <para>
- Older versions of the <command>mysql.server</command> script
- (from MySQL 3.23.4 to 3.23.8) pass a <option>--log</option>
- option to <command>safe_mysqld</command> to enable the general
- query log. If you need better performance when you start using
- MySQL in a production environment, you can remove the
- <option>--log</option> option from
- <command>mysql.server</command> or change it to
- <option>--log-bin</option>. See <xref linkend="binary-log"/>.
- </para>
-
- <para>
- <command>mysqld</command> writes statements to the query log in
- the order that it receives them, which might differ from the
- order in which they are executed. This logging order contrasts
- to the update log and the binary log, which are written after
- the query is executed but before any locks are released. (Also,
- the query log contains all statements, whereas the update and
- binary logs do not contain statements that only select data.)
- </para>
-
- <para>
- To enable the general query log, start <command>mysqld</command>
- with the
- <option>--log[=<replaceable>file_name</replaceable>]</option> or
- <option>-l [<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log</option> or <option>-l</option>, the default name
- is <filename><replaceable>host_name</replaceable>.log</filename>
- in the data directory.
- </para>
-
- <para>
- Server restarts and log flushing do not cause a new general
- query log file to be generated (although flushing closes and
- reopens it). On Unix, you can rename the file and create a new
- one by using the following commands:
- </para>
-
-<programlisting>
-shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
-shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
-</programlisting>
-
- <para>
- On Windows, you cannot rename the log file while the server has
- it open. You must stop the server and rename the file, and then
- restart the server to create a new log file.
- </para>
-
- <para>
- The session <literal>sql_log_off</literal> variable can be set
- to <literal>ON</literal> or <literal>OFF</literal> to disable or
- enable general query logging for the current connection.
- </para>
-
- </section>
-
- <section id="update-log">
-
- <title>The Update Log</title>
-
- <indexterm>
- <primary>update log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>update log</secondary>
- </indexterm>
-
- <note>
- <para>
- The update log has been deprecated and replaced by the more
- useful, informative, and efficient binary log. See
- <xref linkend="binary-log"/>.
- </para>
- </note>
-
- <para>
- When started with the
- <option>--log-update[=<replaceable>file_name</replaceable>]</option>
- option, <command>mysqld</command> writes a log file containing
- all SQL statements that update data. If no
- <replaceable>file_name</replaceable> value is given, the default
- name is name of the host machine. If a filename is given, but it
- does not contain a leading path, the file is written in the data
- directory. If <filename>file_name</filename> does not have an
- extension, <command>mysqld</command> creates log files with
- names of the form <replaceable>file_name.nnnnnn</replaceable>,
- where <replaceable>nnnnnn</replaceable> is a number that is
- incremented each time you start the server or flush the logs.
- </para>
-
- <note>
- <para>
- For this naming scheme to work, you must not create your own
- files with the same names as those that might be used in the
- log file sequence.
- </para>
- </note>
-
- <para>
- Update logging is <quote>smart</quote> in that <emphasis>it logs
- only statements that actually update data</emphasis>. Thus, an
- <literal>UPDATE</literal> or <literal>DELETE</literal> with a
- <literal>WHERE</literal> clause that finds no rows is not
- written to the log. Update logging also skips
- <literal>UPDATE</literal> statements that merely set a column to
- its existing value.
- </para>
-
- <para>
- The update logging is done immediately after a query completes
- but before any locks are released or any commit is done. This
- ensures that statements are logged in execution order.
- </para>
-
- <para>
- If you want to update a database from update log files, you
- could do the following (assuming that your update logs have
- names of the form <filename>file_name.nnnnnn</filename>):
- </para>
-
-<programlisting>
-shell> <userinput>ls -1 -t -r file_name.[0-9]* | xargs cat | mysql</userinput>
-</programlisting>
-
- <para>
- <command>ls</command> is used to sort the update log filenames
- into the right order.
- </para>
-
- <para>
- This can be useful if you have to revert to backup files after a
- crash and you want to redo the updates that occurred between the
- time of the backup and the crash.
- </para>
-
- </section>
-
- <section id="binary-log">
-
- <title>The Binary Log</title>
-
- <indexterm>
- <primary>binary log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>binary log</secondary>
- </indexterm>
-
- <para>
- The binary log contains all statements that update data or
- (starting from MySQL 4.1.3) potentially could have updated it
- (for example, a <literal>DELETE</literal> which matched no
- rows). Statements are stored in the form of
- <quote>events</quote> that describe the modifications. The
- binary log also contains information about how long each
- statement took that updated data.
- </para>
-
- <note>
- <para>
- The binary log has replaced the old update log, which is being
- phased out of future MySQL release series after 4.1. The
- binary log contains all information that is available in the
- update log in a more efficient format and in a manner that is
- transaction-safe. If you are using transactions, you must use
- the MySQL binary log for backups instead of the old update
- log.
- </para>
- </note>
-
- <para>
- The binary log is not used for statements such as
- <literal>SELECT</literal> or <literal>SHOW</literal> that do not
- modify data. If you want to log all statements (for example, to
- identify a problem query), use the general query log. See
- <xref linkend="query-log"/>.
- </para>
-
- <para>
- The primary purpose of the binary log is to be able to update
- databases during a restore operation as fully as possible,
- because the binary log contains all updates done after a backup
- was made. The binary log is also used on master replication
- servers as a record of the statements to be sent to slave
- servers. See <xref linkend="replication"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The binary log can also be used to track significant DDL
- events. Analyzing the binary log in this way is an integral
- part of the MySQL Enterprise Monitor. For more information
- see, <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- Running the server with the binary log enabled makes performance
- about 1% slower. However, the benefits of the binary log for
- restore operations and in allowing you to set up replication
- generally outweigh this minor performance decrement.
- </para>
-
- <para>
- When started with the
- <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
- option, <command>mysqld</command> writes a log file containing
- all SQL statements that update data (both DDL and DML
- statements). If no <replaceable>base_name</replaceable> value is
- given, the default name is the value of the
- <literal>pid-file</literal> option (which by default is the name
- of host machine) followed by <literal>-bin</literal>. If the
- basename is given, but not as an absolute pathname, the server
- writes the file in the data directory. It is recommended that
- you specify a basename; see <xref linkend="open-bugs"/>, for the
- reason.
- </para>
-
- <para>
- If you supply an extension in the log name (for example,
- <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
- the extension is silently removed and ignored.
- </para>
-
- <para>
- <command>mysqld</command> appends a numeric extension to the
- binary log basename. The number increases each time the server
- creates a new log file, thus creating an ordered series of
- files. The server creates a new binary log file each time it
- starts or flushes the logs. The server also creates a new binary
- log file automatically when the current log's size reaches
- <literal>max_binlog_size</literal>. A binary log file may become
- larger than <literal>max_binlog_size</literal> if you are using
- large transactions because a transaction is written to the file
- in one piece, never split between files.
- </para>
-
- <para>
- To keep track of which binary log files have been used,
- <command>mysqld</command> also creates a binary log index file
- that contains the names of all used binary log files. By default
- this has the same basename as the binary log file, with the
- extension <literal>'.index'</literal>. You can change the name
- of the binary log index file with the
- <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
- option. You should not manually edit this file while
- <command>mysqld</command> is running; doing so would confuse
- <command>mysqld</command>.
- </para>
-
- <para>
- Replication slave servers by default do not write to their own
- binary log any statements that are received from the replication
- master. To cause these statements to be logged, start the slave
- with the <option>--log-slave-updates</option> option.
- </para>
-
- <para>
- Before MySQL 4.1.9, writes to a binary log file or binary log
- index file that failed due to a full disk or an exceeded quota
- resulted in corruption of the file. Starting from MySQL 4.1.9,
- writes to the binary log file and binary log index file are
- handled the same way as writes to <literal>MyISAM</literal>
- tables. See <xref linkend="full-disk"/>.
- </para>
-
- <para>
- You can delete all binary log files with the <literal>RESET
- MASTER</literal> statement, or a subset of them with
- <literal>PURGE MASTER LOGS</literal>. See
- <xref linkend="reset"/>, and
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- The binary log format has some known limitations that can affect
- recovery from backups, especially in old versions. These
- caveats, which also affect replication, are listed at
- <xref linkend="replication-features"/>. One caveat which does
- not affect replication but only recovery with
- <literal>mysqlbinlog</literal>: before MySQL 4.1,
- <command>mysqlbinlog</command> could not prepare output suitable
- for <command>mysql</command> if the binary log contained
- interlaced statements originating from different clients that
- used temporary tables of the same name. This is fixed in MySQL
- 4.1. However, the problem still existed for <literal>LOAD DATA
- INFILE</literal> statements until it was fixed in MySQL 4.1.8.
- </para>
-
- <para>
- You can use the following options to <command>mysqld</command>
- to affect what is logged to the binary log. See also the
- discussion that follows this option list.
- </para>
-
- <para>
- If you are using replication, the options described here affect
- which statements are sent by a master server to its slaves.
- There are also options for slave servers that control which
- statements received from the master to execute or ignore. For
- details, see <xref linkend="replication-options"/>.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para id="option_mysqld_binlog-do-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-do-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-do-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to restrict binary logging to updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). All other databases
- that are not explicitly mentioned are ignored. If you use
- this option, you should ensure that you do updates only in
- the default database.
- </para>
-
- <para>
- There is an exception to this for <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. The server uses
- the database named in the statement (not the default
- database) to decide whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-do-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement is
- <emphasis>not</emphasis> written into the binary log.
- </para>
-
- <para>
- To log multiple databases, use multiple options, specifying
- the option once for each database.
- </para>
- </listitem>
-
- <listitem>
- <para id="option_mysqld_binlog-ignore-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-ignore-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-ignore-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to suppress binary logging of updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). If you use this option,
- you should ensure that you do updates only in the default
- database.
- </para>
-
- <para>
- As with the <option>--binlog-do-db</option> option, there is
- an exception for the <literal>CREATE DATABASE</literal>,
- <literal>ALTER DATABASE</literal>, and <literal>DROP
- DATABASE</literal> statements. The server uses the database
- named in the statement (not the default database) to decide
- whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-ignore-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement
- <emphasis>is</emphasis> written into the binary log.
- </para>
-
- <para>
- To ignore multiple databases, use multiple options,
- specifying the option once for each database.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server evaluates the options for logging or ignoring updates
- to the binary log according to the following rules. As described
- previously, there is an exception for the <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. In those cases, the
- database being <emphasis>created, altered, or dropped</emphasis>
- replaces the default database in the following rules:
- </para>
-
- <orderedlist>
-
- <listitem>
- <para>
- Are there <option>--binlog-do-db</option> or
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Write the statement to the binary log and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some rules (<option>--binlog-do-db</option>,
- <option>--binlog-ignore-db</option>, or both). Is there a
- default database (has any database been selected by
- <literal>USE</literal>?)?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement, and
- exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There is a default database. Are there some
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Does the default database match any of the
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Write the statement and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement,
- and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- No: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some <option>--binlog-ignore-db</option> rules.
- Does the default database match any of the
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Do not write the statement, and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Write the query and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- </orderedlist>
-
- <para>
- For example, a slave running with only
- <option>--binlog-do-db=sales</option> does not write to the
- binary log any statement for which the default database is
- different from <literal>sales</literal> (in other words,
- <option>--binlog-do-db</option> can sometimes mean <quote>ignore
- other databases</quote>).
- </para>
-
- <para>
- If you are using replication, you should not delete old binary
- log files until you are sure that no slave still needs to use
- them. For example, if your slaves never run more than three days
- behind, once a day you can execute <command>mysqladmin
- flush-logs</command> on the master and then remove any logs that
- are more than three days old. You can remove the files manually,
- but it is preferable to use <literal>PURGE MASTER
- LOGS</literal>, which also safely updates the binary log index
- file for you (and which can take a date argument as of MySQL
- 4.1). See <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- A client that has the <literal>SUPER</literal> privilege can
- disable binary logging of its own statements by using a
- <literal>SET SQL_LOG_BIN=0</literal> statement. See
- <xref linkend="set-option"/>.
- </para>
-
- <para>
- You can display the contents of binary log files with the
- <command>mysqlbinlog</command> utility. This can be useful when
- you want to reprocess statements in the log. For example, you
- can update a MySQL server from the binary log as follows:
- </para>
-
-<programlisting>
-shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
-</programlisting>
-
- <para>
- See <xref linkend="mysqlbinlog"/>, for more information on the
- <command>mysqlbinlog</command> utility and how to use it.
- <command>mysqlbinlog</command> also can be used with relay log
- files because they are written using the same format as binary
- log files.
- </para>
-
- <para>
- Binary logging is done immediately after a statement completes
- but before any locks are released or any commit is done. This
- ensures that the log is logged in execution order.
- </para>
-
- <para>
- Updates to non-transactional tables are stored in the binary log
- immediately after execution. Within an uncommitted transaction,
- all updates (<literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>INSERT</literal>) that
- change transactional tables such as <literal>BDB</literal> or
- <literal>InnoDB</literal> tables are cached until a
- <literal>COMMIT</literal> statement is received by the server.
- At that point, <command>mysqld</command> writes the entire
- transaction to the binary log before the
- <literal>COMMIT</literal> is executed. When the thread that
- handles the transaction starts, it allocates a buffer of
- <literal>binlog_cache_size</literal> to buffer statements. If a
- statement is bigger than this, the thread opens a temporary file
- to store the transaction. The temporary file is deleted when the
- thread ends.
- </para>
-
- <para>
- Modifications to non-transactional tables cannot be rolled back.
- If a transaction that is rolled back includes modifications to
- non-transactional tables, the entire transaction is logged with
- a <literal>ROLLBACK</literal> statement at the end to ensure
- that the modifications to those tables are replicated. This is
- true as of MySQL 4.0.15.
- </para>
-
- <para>
- The <literal>Binlog_cache_use</literal> status variable shows
- the number of transactions that used this buffer (and possibly a
- temporary file) for storing statements. The
- <literal>Binlog_cache_disk_use</literal> status variable shows
- how many of those transactions actually had to use a temporary
- file. These two variables can be used for tuning
- <literal>binlog_cache_size</literal> to a large enough value
- that avoids the use of temporary files.
- </para>
-
- <para>
- The <literal>max_binlog_cache_size</literal> system variable
- (default 4GB, which is also the maximum) can be used to restrict
- the total size used to cache a multiple-statement transaction.
- If a transaction is larger than this many bytes, it fails and
- rolls back. The minimum value is 4096.
- </para>
-
- <para>
- If you are using the update log or binary log, concurrent
- inserts are converted to normal inserts for <literal>CREATE ...
- SELECT</literal> or <literal>INSERT ... SELECT</literal>
- statements. This is done to ensure that you can re-create an
- exact copy of your tables by applying the log during a backup
- operation.
- </para>
-
- <para>
- The binary log format differs between versions 3.23 and 4.0.
- (These format changes were required to implement enhancements to
- replication.) However, MySQL 4.1 has the same binary log format
- as 4.0. See <xref linkend="replication-compatibility"/>.
- </para>
-
- <para>
- By default, the binary log is not synchronized to disk at each
- write. So if the operating system or machine (not only the MySQL
- server) crashes, there is a chance that the last statements of
- the binary log are lost. To prevent this, you can make the
- binary log be synchronized to disk after every
- <replaceable>N</replaceable> writes to the binary log, with the
- <literal>sync_binlog</literal> system variable. See
- <xref linkend="server-system-variables"/>. 1 is the safest value
- for <literal>sync_binlog</literal>, but also the slowest. Even
- with <literal>sync_binlog</literal> set to 1, there is still the
- chance of an inconsistency between the table content and binary
- log content in case of a crash. For example, if you are using
- <literal>InnoDB</literal> tables and the MySQL server processes
- a <literal>COMMIT</literal> statement, it writes the whole
- transaction to the binary log and then commits this transaction
- into <literal>InnoDB</literal>. If the server crashes between
- those two operations, the transaction is rolled back by
- <literal>InnoDB</literal> at restart but still exists in the
- binary log. This problem can be solved with the
- <option>--innodb-safe-binlog</option> option (available starting
- from MySQL 4.1.3), which adds consistency between the content of
- <literal>InnoDB</literal> tables and the binary log.
- </para>
-
- <para>
- For this option to provide a greater degree of safety, the MySQL
- server should also be configured to synchronize the binary log
- and the <literal>InnoDB</literal> logs to disk at every
- transaction. The <literal>InnoDB</literal> logs are synchronized
- by default, and <literal>sync_binlog=1</literal> can be used to
- synchronize the binary log. The effect of this option is that at
- restart after a crash, after doing a rollback of transactions,
- the MySQL server cuts rolled back <literal>InnoDB</literal>
- transactions from the binary log. This ensures that the binary
- log reflects the exact data of <literal>InnoDB</literal> tables,
- and so, that the slave remains in synchrony with the master (not
- receiving a statement which has been rolled back).
- </para>
-
- <para>
- Note that <option>--innodb-safe-binlog</option> can be used even
- if the MySQL server updates other storage engines than
- <literal>InnoDB</literal>. Only statements and transactions that
- affect <literal>InnoDB</literal> tables are subject to removal
- from the binary log at <literal>InnoDB</literal>'s crash
- recovery. If the MySQL server discovers at crash recovery that
- the binary log is shorter than it should have been, it lacks at
- least one successfully committed <literal>InnoDB</literal>
- transaction. This should not happen if
- <literal>sync_binlog=1</literal> and the disk/filesystem do an
- actual sync when they are requested to (some don't), so the
- server prints an error message <literal>The binary log
- <name> is shorter than its expected size</literal>. In
- this case, this binary log is not correct and replication should
- be restarted from a fresh snapshot of the master's data.
- </para>
-
- </section>
-
- <section id="slow-query-log">
-
- <title>The Slow Query Log</title>
-
- <indexterm>
- <primary>slow query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>slow query log</secondary>
- </indexterm>
-
- <para>
- The slow query log consists of all SQL statements that took more
- than <literal>long_query_time</literal> seconds to execute. The
- time to acquire the initial table locks is not counted as
- execution time. <command>mysqld</command> writes a statement to
- the slow query log after it has been executed and after all
- locks have been released, so log order might be different from
- execution order. The minimum and default values of
- <literal>long_query_time</literal> are 1 and 10, respectively.
- </para>
-
- <para>
- To enable the slow query log, start <command>mysqld</command>
- with the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log-slow-queries</option>, the default name is
- <filename><replaceable>host_name</replaceable>-slow.log</filename>.
- If a filename is given, but not as an absolute pathname, the
- server writes the file in the data directory.
- </para>
-
- <para>
- The slow query log can be used to find queries that take a long
- time to execute and are therefore candidates for optimization.
- However, examining a long slow query log can become a difficult
- task. To make this easier, you can process the slow query log
- using the <command>mysqldumpslow</command> command to summarize
- the queries that appear in the log. Use <command>mysqldumpslow
- --help</command> to see the options that this command supports.
- </para>
-
- <para>
- Before MySQL 4.1, if you also use
- <option>--log-long-format</option> when logging slow queries,
- queries that are not using indexes are logged as well. Starting
- with MySQL 4.1, logging of queries not using indexes is enabled
- using the <option>--log-queries-not-using-indexes</option>
- option instead. The <option>--log-long-format</option> is
- deprecated as of MySQL 4.1, when
- <option>--log-short-format</option> was introduced, which causes
- less information to be logged. (The long log format is the
- default setting since version 4.1.). See
- <xref linkend="server-options"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- Excessive table scans are indicative of missing or poorly
- optimized indexes. Using an advisor specifically designed for
- the task, the MySQL Enterprise Monitor can identify such
- problems and offer advice on resolution. For more information
- see, <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- In MySQL 4.0, slow administrative statements such as
- <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
- TABLE</literal>, and <literal>ALTER TABLE</literal> were written
- to the slow query log. This logging was disabled in MySQL 4.1
- until 4.1.13, when the
- <option>--log-slow-admin-statements</option> server option was
- added to specify logging of slow administrative statements.
- </para>
-
- <para>
- Queries handled by the query cache are not added to the slow
- query log, nor are queries that would not benefit from the
- presence of an index because the table has zero rows or one row.
- </para>
-
- </section>
-
- <section id="log-file-maintenance">
-
- <title>Server Log Maintenance</title>
-
- <indexterm>
- <primary>files</primary>
- <secondary>log</secondary>
- </indexterm>
-
- <indexterm>
- <primary>maintaining</primary>
- <secondary>log files</secondary>
- </indexterm>
-
- <indexterm>
- <primary>log files</primary>
- <secondary>maintaining</secondary>
- </indexterm>
-
- <para>
- MySQL Server can create a number of different log files that
- make it easy to see what is going on. See
- <xref linkend="log-files"/>. However, you must clean up these
- files regularly to ensure that the logs do not take up too much
- disk space.
- </para>
-
- <para>
- When using MySQL with logging enabled, you may want to back up
- and remove old log files from time to time and tell MySQL to
- start logging to new files. See <xref linkend="backup"/>.
- </para>
-
- <para>
- On a Linux (Red Hat) installation, you can use the
- <literal>mysql-log-rotate</literal> script for this. If you
- installed MySQL from an RPM distribution, this script should
- have been installed automatically. You should be careful with
- this script if you are using the binary log for replication. You
- should not remove binary logs until you are certain that their
- contents have been processed by all slaves.
- </para>
-
- <para>
- On other systems, you must install a short script yourself that
- you start from <command>cron</command> (or its equivalent) for
- handling log files.
- </para>
-
- <para>
- For the binary log, you can set the
- <literal>expire_logs_days</literal> system variable to expire
- binary log files automatically after a given number of days (see
- <xref linkend="server-system-variables"/>). If you are using
- replication, you should set the variable no lower than the
- maximum number of days your slaves might lag behind the master.
- </para>
-
- <para>
- You can force MySQL to start using new log files by issuing a
- <literal>FLUSH LOGS</literal> statement or executing
- <command>mysqladmin flush-logs</command> or <command>mysqladmin
- refresh</command>. See <xref linkend="flush"/>, and
- <xref linkend="mysqladmin"/>. If you are using MySQL 3.21, you
- must use <command>mysqladmin refresh</command>.
- </para>
-
- <para>
- A log flushing operation does the following:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If general query logging (<option>--log</option>) or slow
- query logging (<option>--log-slow-queries</option>) to a log
- file is enabled, the server closes and reopens the general
- query log file or slow query log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If update logging (<option>--log-update</option>) or binary
- logging (<option>--log-bin</option>) is used, closes the log
- and opens a new log file with a higher sequence number.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the server was given an error log filename with the
- <option>--log-error</option> option, it renames the error
- log with the suffix <literal>-old</literal> and creates a
- new empty error log file.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server creates a new binary log file when you flush the
- logs. However, it just closes and reopens the general and slow
- query log files. To cause new files to be created on Unix,
- rename the current logs before flushing them. At flush time, the
- server will open new logs with the original names. For example,
- if the general and slow query logs are named
- <filename>mysql.log</filename> and
- <filename>mysql-slow.log</filename>, you can use a series of
- commands like this:
- </para>
-
-<programlisting>
-shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
-shell> <userinput>mv mysql.log mysql.old</userinput>
-shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-</programlisting>
-
- <para>
- At this point, you can make a backup of
- <filename>mysql.old</filename> and
- <filename>mysql-slow.log</filename> and then remove them from
- disk.
- </para>
-
- <para>
- On Windows, you cannot rename log files while the server has
- them open. You must stop the server and rename them, and then
- restart the server to create new logs.
- </para>
-
- </section>
-
- </section>
-
<section id="multiple-servers">
<title>Running Multiple MySQL Servers on the Same Machine</title>
Modified: trunk/refman-5.0/dba-core.xml
===================================================================
--- trunk/refman-5.0/dba-core.xml 2007-12-07 18:16:27 UTC (rev 9198)
+++ trunk/refman-5.0/dba-core.xml 2007-12-07 18:17:33 UTC (rev 9199)
Changed blocks: 3, Lines Added: 1078, Lines Deleted: 1078; 82534 bytes
@@ -26,19 +26,19 @@
<listitem>
<para>
- Managing user accounts
+ The server log files
</para>
</listitem>
<listitem>
<para>
- Performing backups
+ Managing user accounts
</para>
</listitem>
<listitem>
<para>
- The server log files
+ Performing backups
</para>
</listitem>
@@ -11318,6 +11318,1081 @@
</section>
+ <section id="log-files">
+
+ <title>MySQL Server Logs</title>
+
+ <indexterm>
+ <primary>log files</primary>
+ </indexterm>
+
+ <para>
+ MySQL has several different logs that can help you find out what
+ is going on inside <command>mysqld</command>:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Log Type</emphasis></entry>
+ <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
+ </row>
+ <row>
+ <entry>The error log</entry>
+ <entry>Problems encountered starting, running, or stopping
+ <command>mysqld</command></entry>
+ </row>
+ <row>
+ <entry>The general query log</entry>
+ <entry>Established client connections and statements received from clients</entry>
+ </row>
+ <row>
+ <entry>The binary log</entry>
+ <entry>All statements that change data (also used for replication)</entry>
+ </row>
+ <row>
+ <entry>The slow query log</entry>
+ <entry>All queries that took more than <literal>long_query_time</literal>
+ seconds to execute or didn't use indexes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ By default, all log files are created in the
+ <command>mysqld</command> data directory. You can force
+ <command>mysqld</command> to close and reopen the log files (or in
+ some cases switch to a new log) by flushing the logs. Log flushing
+ occurs when you issue a <literal>FLUSH LOGS</literal> statement or
+ execute <command>mysqladmin flush-logs</command> or
+ <command>mysqladmin refresh</command>. See
+ <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ If you are using MySQL replication capabilities, slave replication
+ servers maintain additional log files called relay logs.
+ <xref linkend="replication"/>, discusses relay log contents and
+ configuration.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The MySQL Enterprise Monitor provides a number of advisors
+ specifically related to the various log files. For more
+ information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <section id="error-log">
+
+ <title>The Error Log</title>
+
+ <para>
+ The error log contains information indicating when
+ <command>mysqld</command> was started and stopped and also any
+ critical errors that occur while the server is running. If
+ <command>mysqld</command> notices a table that needs to be
+ automatically checked or repaired, it writes a message to the
+ error log.
+ </para>
+
+ <para>
+ On some operating systems, the error log contains a stack trace
+ if <command>mysqld</command> dies. The trace can be used to
+ determine where <command>mysqld</command> died. See
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
+ Internals: Porting</ulink>.
+ </para>
+
+ <para>
+ You can specify where <command>mysqld</command> writes the error
+ log with the
+ <option>--log-error[=<replaceable>file_name</replaceable>]</option>
+ option. If no <replaceable>file_name</replaceable> value is
+ given, <command>mysqld</command> uses the name
+ <filename><replaceable>host_name</replaceable>.err</filename> by
+ default and writes the file in the data directory. If you
+ execute <literal>FLUSH LOGS</literal>, the error log is renamed
+ with the suffix <literal>-old</literal> and
+ <command>mysqld</command> creates a new empty log file. (No
+ renaming occurs if the <option>--log-error</option> option was
+ not given to <command>mysqld</command>.)
+ </para>
+
+ <para>
+ If you do not specify <option>--log-error</option>, or (on
+ Windows) if you use the <option>--console</option> option,
+ errors are written to <literal>stderr</literal>, the standard
+ error output. Usually this is your terminal.
+ </para>
+
+ <para>
+ On Windows, error output is always written to the
+ <literal>.err</literal> file if <option>--console</option> is
+ not given.
+ </para>
+
+ <para>
+ The <option>--log-warnings</option> option or
+ <literal>log_warnings</literal> system variable can be used to
+ control warning logging to the error log. The default value is
+ enabled (1). Warning logging can be disabled using a value of 0.
+ If the value is greater than 1, aborted connections are written
+ to the error log. See <xref linkend="communication-errors"/>.
+ </para>
+
+ <para>
+ If you use <command>mysqld_safe</command> to start
+ <command>mysqld</command>, <command>mysqld_safe</command>
+ arranges for <command>mysqld</command> to write error messages
+ to a log file. If you specify a filename via
+ <option>--log-error</option> to <command>mysqld_safe</command>
+ or <command>mysqld</command>, that filename is used. Otherwise,
+ <command>mysqld_safe</command> uses the default error log file.
+ </para>
+
+ <para>
+ If <command>mysqld_safe</command> is used to start
+ <command>mysqld</command> and <command>mysqld</command> dies
+ unexpectedly, <command>mysqld_safe</command> notices that it
+ needs to restart <command>mysqld</command> and writes a
+ <literal>restarted mysqld</literal> message to the error log.
+ </para>
+
+ </section>
+
+ <section id="query-log">
+
+ <title>The General Query Log</title>
+
+ <indexterm>
+ <primary>general query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>general query log</secondary>
+ </indexterm>
+
+ <para>
+ The general query log is a general record of what
+ <command>mysqld</command> is doing. The server writes
+ information to this log when clients connect or disconnect, and
+ it logs each SQL statement received from clients. The general
+ query log can be very useful when you suspect an error in a
+ client and want to know exactly what the client sent to
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ <command>mysqld</command> writes statements to the query log in
+ the order that it receives them, which might differ from the
+ order in which they are executed. This logging order contrasts
+ to the binary log, for which statements are written after they
+ are executed but before any locks are released. (Also, the query
+ log contains all statements, whereas the binary log does not
+ contain statements that only select data.)
+ </para>
+
+ <para>
+ To enable the general query log, start <command>mysqld</command>
+ with the
+ <option>--log[=<replaceable>file_name</replaceable>]</option> or
+ <option>-l [<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log</option> or <option>-l</option>, the default name
+ is <filename><replaceable>host_name</replaceable>.log</filename>
+ in the data directory.
+ </para>
+
+ <para>
+ Server restarts and log flushing do not cause a new general
+ query log file to be generated (although flushing closes and
+ reopens it). On Unix, you can rename the file and create a new
+ one by using the following commands:
+ </para>
+
+<programlisting>
+shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
+shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
+</programlisting>
+
+ <para>
+ On Windows, you cannot rename the log file while the server has
+ it open. You must stop the server and rename the file, and then
+ restart the server to create a new log file.
+ </para>
+
+ </section>
+
+ <section id="binary-log">
+
+ <title>The Binary Log</title>
+
+ <indexterm>
+ <primary>binary log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>binary log</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>update log (obsolete)</secondary>
+ </indexterm>
+
+ <para>
+ The binary log contains all statements that update data or
+ potentially could have updated it (for example, a
+ <literal>DELETE</literal> which matched no rows). Statements are
+ stored in the form of <quote>events</quote> that describe the
+ modifications. The binary log also contains information about
+ how long each statement took that updated data.
+ </para>
+
+ <note>
+ <para>
+ The binary log has replaced the old update log, which is no
+ longer available as of MySQL 5.0. The binary log contains all
+ information that is available in the update log in a more
+ efficient format and in a manner that is transaction-safe. If
+ you are using transactions, you must use the MySQL binary log
+ for backups instead of the old update log.
+ </para>
+ </note>
+
+ <para>
+ The binary log is not used for statements such as
+ <literal>SELECT</literal> or <literal>SHOW</literal> that do not
+ modify data. If you want to log all statements (for example, to
+ identify a problem query), use the general query log. See
+ <xref linkend="query-log"/>.
+ </para>
+
+ <para>
+ The primary purpose of the binary log is to be able to update
+ databases during a restore operation as fully as possible,
+ because the binary log contains all updates done after a backup
+ was made. The binary log is also used on master replication
+ servers as a record of the statements to be sent to slave
+ servers. See <xref linkend="replication"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The binary log can also be used to track significant DDL
+ events. Analyzing the binary log in this way is an integral
+ part of the MySQL Enterprise Monitor. For more information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ Running the server with the binary log enabled makes performance
+ about 1% slower. However, the benefits of the binary log for
+ restore operations and in allowing you to set up replication
+ generally outweigh this minor performance decrement.
+ </para>
+
+ <para>
+ When started with the
+ <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
+ option, <command>mysqld</command> writes a log file containing
+ all SQL statements that update data (both DDL and DML
+ statements). If no <replaceable>base_name</replaceable> value is
+ given, the default name is the value of the
+ <literal>pid-file</literal> option (which by default is the name
+ of host machine) followed by <literal>-bin</literal>. If the
+ basename is given, but not as an absolute pathname, the server
+ writes the file in the data directory. It is recommended that
+ you specify a basename; see <xref linkend="open-bugs"/>, for the
+ reason.
+ </para>
+
+ <para>
+ If you supply an extension in the log name (for example,
+ <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
+ the extension is silently removed and ignored.
+ </para>
+
+ <para>
+ <command>mysqld</command> appends a numeric extension to the
+ binary log basename. The number increases each time the server
+ creates a new log file, thus creating an ordered series of
+ files. The server creates a new binary log file each time it
+ starts or flushes the logs. The server also creates a new binary
+ log file automatically when the current log's size reaches
+ <literal>max_binlog_size</literal>. A binary log file may become
+ larger than <literal>max_binlog_size</literal> if you are using
+ large transactions because a transaction is written to the file
+ in one piece, never split between files.
+ </para>
+
+ <para>
+ To keep track of which binary log files have been used,
+ <command>mysqld</command> also creates a binary log index file
+ that contains the names of all used binary log files. By default
+ this has the same basename as the binary log file, with the
+ extension <literal>'.index'</literal>. You can change the name
+ of the binary log index file with the
+ <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
+ option. You should not manually edit this file while
+ <command>mysqld</command> is running; doing so would confuse
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ Replication slave servers by default do not write to their own
+ binary log any statements that are received from the replication
+ master. To cause these statements to be logged, start the slave
+ with the <option>--log-slave-updates</option> option.
+ </para>
+
+ <para>
+ Writes to the binary log file and binary log index file are
+ handled in the same way as writes to <literal>MyISAM</literal>
+ tables. See <xref linkend="full-disk"/>.
+ </para>
+
+ <para>
+ You can delete all binary log files with the <literal>RESET
+ MASTER</literal> statement, or a subset of them with
+ <literal>PURGE MASTER LOGS</literal>. See
+ <xref linkend="reset"/>, and
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ The binary log format has some known limitations that can affect
+ recovery from backups. See
+ <xref linkend="replication-features"/>.
+ </para>
+
+ <para>
+ Binary logging for stored routines and triggers is done as
+ described in <xref linkend="stored-procedure-logging"/>.
+ </para>
+
+ <para>
+ You can use the following options to <command>mysqld</command>
+ to affect what is logged to the binary log. See also the
+ discussion that follows this option list.
+ </para>
+
+ <para>
+ If you are using replication, the options described here affect
+ which statements are sent by a master server to its slaves.
+ There are also options for slave servers that control which
+ statements received from the master to execute or ignore. For
+ details, see <xref linkend="replication-options"/>.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para id="option_mysqld_binlog-do-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-do-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-do-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to restrict binary logging to updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). All other databases
+ that are not explicitly mentioned are ignored. If you use
+ this option, you should ensure that you do updates only in
+ the default database.
+ </para>
+
+ <para>
+ There is an exception to this for <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. The server uses
+ the database named in the statement (not the default
+ database) to decide whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-do-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement is
+ <emphasis>not</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To log multiple databases, use multiple options, specifying
+ the option once for each database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqld_binlog-ignore-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-ignore-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-ignore-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to suppress binary logging of updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). If you use this option,
+ you should ensure that you do updates only in the default
+ database.
+ </para>
+
+ <para>
+ As with the <option>--binlog-do-db</option> option, there is
+ an exception for the <literal>CREATE DATABASE</literal>,
+ <literal>ALTER DATABASE</literal>, and <literal>DROP
+ DATABASE</literal> statements. The server uses the database
+ named in the statement (not the default database) to decide
+ whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-ignore-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement
+ <emphasis>is</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To ignore multiple databases, use multiple options,
+ specifying the option once for each database.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server evaluates the options for logging or ignoring updates
+ to the binary log according to the following rules. As described
+ previously, there is an exception for the <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. In those cases, the
+ database being <emphasis>created, altered, or dropped</emphasis>
+ replaces the default database in the following rules:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Are there <option>--binlog-do-db</option> or
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Write the statement to the binary log and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some rules (<option>--binlog-do-db</option>,
+ <option>--binlog-ignore-db</option>, or both). Is there a
+ default database (has any database been selected by
+ <literal>USE</literal>?)?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement, and
+ exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There is a default database. Are there some
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Does the default database match any of the
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Write the statement and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement,
+ and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some <option>--binlog-ignore-db</option> rules.
+ Does the default database match any of the
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Do not write the statement, and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Write the query and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ For example, a slave running with only
+ <option>--binlog-do-db=sales</option> does not write to the
+ binary log any statement for which the default database is
+ different from <literal>sales</literal> (in other words,
+ <option>--binlog-do-db</option> can sometimes mean <quote>ignore
+ other databases</quote>).
+ </para>
+
+ <para>
+ If you are using replication, you should not delete old binary
+ log files until you are sure that no slave still needs to use
+ them. For example, if your slaves never run more than three days
+ behind, once a day you can execute <command>mysqladmin
+ flush-logs</command> on the master and then remove any logs that
+ are more than three days old. You can remove the files manually,
+ but it is preferable to use <literal>PURGE MASTER
+ LOGS</literal>, which also safely updates the binary log index
+ file for you (and which can take a date argument). See
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ A client that has the <literal>SUPER</literal> privilege can
+ disable binary logging of its own statements by using a
+ <literal>SET SQL_LOG_BIN=0</literal> statement. See
+ <xref linkend="set-option"/>.
+ </para>
+
+ <para>
+ You can display the contents of binary log files with the
+ <command>mysqlbinlog</command> utility. This can be useful when
+ you want to reprocess statements in the log. For example, you
+ can update a MySQL server from the binary log as follows:
+ </para>
+
+<programlisting>
+shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
+</programlisting>
+
+ <para>
+ See <xref linkend="mysqlbinlog"/>, for more information on the
+ <command>mysqlbinlog</command> utility and how to use it.
+ <command>mysqlbinlog</command> also can be used with relay log
+ files because they are written using the same format as binary
+ log files.
+ </para>
+
+ <para>
+ Binary logging is done immediately after a statement completes
+ but before any locks are released or any commit is done. This
+ ensures that the log is logged in execution order.
+ </para>
+
+ <para>
+ Updates to non-transactional tables are stored in the binary log
+ immediately after execution. Within an uncommitted transaction,
+ all updates (<literal>UPDATE</literal>,
+ <literal>DELETE</literal>, or <literal>INSERT</literal>) that
+ change transactional tables such as <literal>BDB</literal> or
+ <literal>InnoDB</literal> tables are cached until a
+ <literal>COMMIT</literal> statement is received by the server.
+ At that point, <command>mysqld</command> writes the entire
+ transaction to the binary log before the
+ <literal>COMMIT</literal> is executed. When the thread that
+ handles the transaction starts, it allocates a buffer of
+ <literal>binlog_cache_size</literal> to buffer statements. If a
+ statement is bigger than this, the thread opens a temporary file
+ to store the transaction. The temporary file is deleted when the
+ thread ends.
+ </para>
+
+ <para>
+ Modifications to non-transactional tables cannot be rolled back.
+ If a transaction that is rolled back includes modifications to
+ non-transactional tables, the entire transaction is logged with
+ a <literal>ROLLBACK</literal> statement at the end to ensure
+ that the modifications to those tables are replicated.
+ </para>
+
+ <para>
+ The <literal>Binlog_cache_use</literal> status variable shows
+ the number of transactions that used this buffer (and possibly a
+ temporary file) for storing statements. The
+ <literal>Binlog_cache_disk_use</literal> status variable shows
+ how many of those transactions actually had to use a temporary
+ file. These two variables can be used for tuning
+ <literal>binlog_cache_size</literal> to a large enough value
+ that avoids the use of temporary files.
+ </para>
+
+ <para>
+ The <literal>max_binlog_cache_size</literal> system variable
+ (default 4GB, which is also the maximum) can be used to restrict
+ the total size used to cache a multiple-statement transaction.
+ If a transaction is larger than this many bytes, it fails and
+ rolls back. The minimum value is 4096.
+ </para>
+
+ <para>
+ Note that the binary log format is different in MySQL
+ ¤t-series; from previous versions of MySQL, due to
+ enhancements in replication. See
+ <xref linkend="replication-compatibility"/>.
+ </para>
+
+ <para>
+ By default, the binary log is not synchronized to disk at each
+ write. So if the operating system or machine (not only the MySQL
+ server) crashes, there is a chance that the last statements of
+ the binary log are lost. To prevent this, you can make the
+ binary log be synchronized to disk after every
+ <replaceable>N</replaceable> writes to the binary log, with the
+ <literal>sync_binlog</literal> system variable. See
+ <xref linkend="server-system-variables"/>. 1 is the safest value
+ for <literal>sync_binlog</literal>, but also the slowest. Even
+ with <literal>sync_binlog</literal> set to 1, there is still the
+ chance of an inconsistency between the table content and binary
+ log content in case of a crash. For example, if you are using
+ <literal>InnoDB</literal> tables and the MySQL server processes
+ a <literal>COMMIT</literal> statement, it writes the whole
+ transaction to the binary log and then commits this transaction
+ into <literal>InnoDB</literal>. If the server crashes between
+ those two operations, the transaction is rolled back by
+ <literal>InnoDB</literal> at restart but still exists in the
+ binary log. This problem can be solved with the
+ <option>--innodb-safe-binlog</option> option, which adds
+ consistency between the content of <literal>InnoDB</literal>
+ tables and the binary log. (Note:
+ <option>--innodb-safe-binlog</option> is unneeded as of MySQL
+ 5.0; it was made obsolete by the introduction of XA transaction
+ support.)
+ </para>
+
+ <para>
+ For this option to provide a greater degree of safety, the MySQL
+ server should also be configured to synchronize the binary log
+ and the <literal>InnoDB</literal> logs to disk at every
+ transaction. The <literal>InnoDB</literal> logs are synchronized
+ by default, and <literal>sync_binlog=1</literal> can be used to
+ synchronize the binary log. The effect of this option is that at
+ restart after a crash, after doing a rollback of transactions,
+ the MySQL server cuts rolled back <literal>InnoDB</literal>
+ transactions from the binary log. This ensures that the binary
+ log reflects the exact data of <literal>InnoDB</literal> tables,
+ and so, that the slave remains in synchrony with the master (not
+ receiving a statement which has been rolled back).
+ </para>
+
+ <para>
+ Note that <option>--innodb-safe-binlog</option> can be used even
+ if the MySQL server updates other storage engines than
+ <literal>InnoDB</literal>. Only statements and transactions that
+ affect <literal>InnoDB</literal> tables are subject to removal
+ from the binary log at <literal>InnoDB</literal>'s crash
+ recovery. If the MySQL server discovers at crash recovery that
+ the binary log is shorter than it should have been, it lacks at
+ least one successfully committed <literal>InnoDB</literal>
+ transaction. This should not happen if
+ <literal>sync_binlog=1</literal> and the disk/filesystem do an
+ actual sync when they are requested to (some don't), so the
+ server prints an error message <literal>The binary log
+ <name> is shorter than its expected size</literal>. In
+ this case, this binary log is not correct and replication should
+ be restarted from a fresh snapshot of the master's data.
+ </para>
+
+ <para>
+ For MySQL 5.0.46, the following session variables are written to
+ the binary log and honoured by the replication slave when
+ parsing the binary log:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>FOREIGN_KEY_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>UNIQUE_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>SQL_AUTO_IS_NULL</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="slow-query-log">
+
+ <title>The Slow Query Log</title>
+
+ <indexterm>
+ <primary>slow query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>slow query log</secondary>
+ </indexterm>
+
+ <para>
+ The slow query log consists of all SQL statements that took more
+ than <literal>long_query_time</literal> seconds to execute. The
+ time to acquire the initial table locks is not counted as
+ execution time. <command>mysqld</command> writes a statement to
+ the slow query log after it has been executed and after all
+ locks have been released, so log order might be different from
+ execution order. The minimum and default values of
+ <literal>long_query_time</literal> are 1 and 10, respectively.
+ </para>
+
+ <para>
+ To enable the slow query log, start <command>mysqld</command>
+ with the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log-slow-queries</option>, the default name is
+ <filename><replaceable>host_name</replaceable>-slow.log</filename>.
+ If a filename is given, but not as an absolute pathname, the
+ server writes the file in the data directory.
+ </para>
+
+ <para>
+ The slow query log can be used to find queries that take a long
+ time to execute and are therefore candidates for optimization.
+ However, examining a long slow query log can become a difficult
+ task. To make this easier, you can process the slow query log
+ using the <command>mysqldumpslow</command> command to summarize
+ the queries that appear in the log. Use <command>mysqldumpslow
+ --help</command> to see the options that this command supports.
+ </para>
+
+ <para>
+ In MySQL ¤t-series;, queries that do not use indexes are
+ logged in the slow query log if the
+ <option>--log-queries-not-using-indexes</option> option is
+ specified. See <xref linkend="server-options"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ Excessive table scans are indicative of missing or poorly
+ optimized indexes. Using an advisor specifically designed for
+ the task, the MySQL Enterprise Monitor can identify such
+ problems and offer advice on resolution. For more information
+ see <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ In MySQL ¤t-series;, the
+ <option>--log-slow-admin-statements</option> server option
+ enables you to request logging of slow administrative statements
+ such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
+ TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
+ query log.
+ </para>
+
+ <para>
+ Queries handled by the query cache are not added to the slow
+ query log, nor are queries that would not benefit from the
+ presence of an index because the table has zero rows or one row.
+ </para>
+
+ </section>
+
+ <section id="log-file-maintenance">
+
+ <title>Server Log Maintenance</title>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>log</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>maintaining</primary>
+ <secondary>log files</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>maintaining</secondary>
+ </indexterm>
+
+ <para>
+ MySQL Server can create a number of different log files that
+ make it easy to see what is going on. See
+ <xref linkend="log-files"/>. However, you must clean up these
+ files regularly to ensure that the logs do not take up too much
+ disk space.
+ </para>
+
+ <para>
+ When using MySQL with logging enabled, you may want to back up
+ and remove old log files from time to time and tell MySQL to
+ start logging to new files. See <xref linkend="backup"/>.
+ </para>
+
+ <para>
+ On a Linux (Red Hat) installation, you can use the
+ <literal>mysql-log-rotate</literal> script for this. If you
+ installed MySQL from an RPM distribution, this script should
+ have been installed automatically. You should be careful with
+ this script if you are using the binary log for replication. You
+ should not remove binary logs until you are certain that their
+ contents have been processed by all slaves.
+ </para>
+
+ <para>
+ On other systems, you must install a short script yourself that
+ you start from <command>cron</command> (or its equivalent) for
+ handling log files.
+ </para>
+
+ <para>
+ For the binary log, you can set the
+ <literal>expire_logs_days</literal> system variable to expire
+ binary log files automatically after a given number of days (see
+ <xref linkend="server-system-variables"/>). If you are using
+ replication, you should set the variable no lower than the
+ maximum number of days your slaves might lag behind the master.
+ </para>
+
+ <para>
+ You can force MySQL to start using new log files by issuing a
+ <literal>FLUSH LOGS</literal> statement or executing
+ <command>mysqladmin flush-logs</command> or <command>mysqladmin
+ refresh</command>. See <xref linkend="flush"/>, and
+ <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ A log flushing operation does the following:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If general query logging (<option>--log</option>) or slow
+ query logging (<option>--log-slow-queries</option>) to a log
+ file is enabled, the server closes and reopens the general
+ query log file or slow query log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If binary logging (<option>--log-bin</option>) is used, the
+ server closes the current log file and opens a new log file
+ with the next sequence number.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the server was given an error log filename with the
+ <option>--log-error</option> option, it renames the error
+ log with the suffix <literal>-old</literal> and creates a
+ new empty error log file.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server creates a new binary log file when you flush the
+ logs. However, it just closes and reopens the general and slow
+ query log files. To cause new files to be created on Unix,
+ rename the current logs before flushing them. At flush time, the
+ server will open new logs with the original names. For example,
+ if the general and slow query logs are named
+ <filename>mysql.log</filename> and
+ <filename>mysql-slow.log</filename>, you can use a series of
+ commands like this:
+ </para>
+
+<programlisting>
+shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
+shell> <userinput>mv mysql.log mysql.old</userinput>
+shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+</programlisting>
+
+ <para>
+ At this point, you can make a backup of
+ <filename>mysql.old</filename> and
+ <filename>mysql-slow.log</filename> and then remove them from
+ disk.
+ </para>
+
+ <para>
+ On Windows, you cannot rename log files while the server has
+ them open. You must stop the server and rename them, and then
+ restart the server to create new logs.
+ </para>
+
+ <para>
+ The session <literal>sql_log_off</literal> variable can be set
+ to <literal>ON</literal> or <literal>OFF</literal> to disable or
+ enable general query logging for the current connection.
+ </para>
+
+ </section>
+
+ </section>
+
<section id="security">
<title>General Security Issues</title>
@@ -21324,1081 +22399,6 @@
</section>
- <section id="log-files">
-
- <title>MySQL Server Logs</title>
-
- <indexterm>
- <primary>log files</primary>
- </indexterm>
-
- <para>
- MySQL has several different logs that can help you find out what
- is going on inside <command>mysqld</command>:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Log Type</emphasis></entry>
- <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
- </row>
- <row>
- <entry>The error log</entry>
- <entry>Problems encountered starting, running, or stopping
- <command>mysqld</command></entry>
- </row>
- <row>
- <entry>The general query log</entry>
- <entry>Established client connections and statements received from clients</entry>
- </row>
- <row>
- <entry>The binary log</entry>
- <entry>All statements that change data (also used for replication)</entry>
- </row>
- <row>
- <entry>The slow query log</entry>
- <entry>All queries that took more than <literal>long_query_time</literal>
- seconds to execute or didn't use indexes</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- By default, all log files are created in the
- <command>mysqld</command> data directory. You can force
- <command>mysqld</command> to close and reopen the log files (or in
- some cases switch to a new log) by flushing the logs. Log flushing
- occurs when you issue a <literal>FLUSH LOGS</literal> statement or
- execute <command>mysqladmin flush-logs</command> or
- <command>mysqladmin refresh</command>. See
- <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- If you are using MySQL replication capabilities, slave replication
- servers maintain additional log files called relay logs.
- <xref linkend="replication"/>, discusses relay log contents and
- configuration.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The MySQL Enterprise Monitor provides a number of advisors
- specifically related to the various log files. For more
- information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <section id="error-log">
-
- <title>The Error Log</title>
-
- <para>
- The error log contains information indicating when
- <command>mysqld</command> was started and stopped and also any
- critical errors that occur while the server is running. If
- <command>mysqld</command> notices a table that needs to be
- automatically checked or repaired, it writes a message to the
- error log.
- </para>
-
- <para>
- On some operating systems, the error log contains a stack trace
- if <command>mysqld</command> dies. The trace can be used to
- determine where <command>mysqld</command> died. See
- <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
- Internals: Porting</ulink>.
- </para>
-
- <para>
- You can specify where <command>mysqld</command> writes the error
- log with the
- <option>--log-error[=<replaceable>file_name</replaceable>]</option>
- option. If no <replaceable>file_name</replaceable> value is
- given, <command>mysqld</command> uses the name
- <filename><replaceable>host_name</replaceable>.err</filename> by
- default and writes the file in the data directory. If you
- execute <literal>FLUSH LOGS</literal>, the error log is renamed
- with the suffix <literal>-old</literal> and
- <command>mysqld</command> creates a new empty log file. (No
- renaming occurs if the <option>--log-error</option> option was
- not given to <command>mysqld</command>.)
- </para>
-
- <para>
- If you do not specify <option>--log-error</option>, or (on
- Windows) if you use the <option>--console</option> option,
- errors are written to <literal>stderr</literal>, the standard
- error output. Usually this is your terminal.
- </para>
-
- <para>
- On Windows, error output is always written to the
- <literal>.err</literal> file if <option>--console</option> is
- not given.
- </para>
-
- <para>
- The <option>--log-warnings</option> option or
- <literal>log_warnings</literal> system variable can be used to
- control warning logging to the error log. The default value is
- enabled (1). Warning logging can be disabled using a value of 0.
- If the value is greater than 1, aborted connections are written
- to the error log. See <xref linkend="communication-errors"/>.
- </para>
-
- <para>
- If you use <command>mysqld_safe</command> to start
- <command>mysqld</command>, <command>mysqld_safe</command>
- arranges for <command>mysqld</command> to write error messages
- to a log file. If you specify a filename via
- <option>--log-error</option> to <command>mysqld_safe</command>
- or <command>mysqld</command>, that filename is used. Otherwise,
- <command>mysqld_safe</command> uses the default error log file.
- </para>
-
- <para>
- If <command>mysqld_safe</command> is used to start
- <command>mysqld</command> and <command>mysqld</command> dies
- unexpectedly, <command>mysqld_safe</command> notices that it
- needs to restart <command>mysqld</command> and writes a
- <literal>restarted mysqld</literal> message to the error log.
- </para>
-
- </section>
-
- <section id="query-log">
-
- <title>The General Query Log</title>
-
- <indexterm>
- <primary>general query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>general query log</secondary>
- </indexterm>
-
- <para>
- The general query log is a general record of what
- <command>mysqld</command> is doing. The server writes
- information to this log when clients connect or disconnect, and
- it logs each SQL statement received from clients. The general
- query log can be very useful when you suspect an error in a
- client and want to know exactly what the client sent to
- <command>mysqld</command>.
- </para>
-
- <para>
- <command>mysqld</command> writes statements to the query log in
- the order that it receives them, which might differ from the
- order in which they are executed. This logging order contrasts
- to the binary log, for which statements are written after they
- are executed but before any locks are released. (Also, the query
- log contains all statements, whereas the binary log does not
- contain statements that only select data.)
- </para>
-
- <para>
- To enable the general query log, start <command>mysqld</command>
- with the
- <option>--log[=<replaceable>file_name</replaceable>]</option> or
- <option>-l [<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log</option> or <option>-l</option>, the default name
- is <filename><replaceable>host_name</replaceable>.log</filename>
- in the data directory.
- </para>
-
- <para>
- Server restarts and log flushing do not cause a new general
- query log file to be generated (although flushing closes and
- reopens it). On Unix, you can rename the file and create a new
- one by using the following commands:
- </para>
-
-<programlisting>
-shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
-shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
-</programlisting>
-
- <para>
- On Windows, you cannot rename the log file while the server has
- it open. You must stop the server and rename the file, and then
- restart the server to create a new log file.
- </para>
-
- </section>
-
- <section id="binary-log">
-
- <title>The Binary Log</title>
-
- <indexterm>
- <primary>binary log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>binary log</secondary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>update log (obsolete)</secondary>
- </indexterm>
-
- <para>
- The binary log contains all statements that update data or
- potentially could have updated it (for example, a
- <literal>DELETE</literal> which matched no rows). Statements are
- stored in the form of <quote>events</quote> that describe the
- modifications. The binary log also contains information about
- how long each statement took that updated data.
- </para>
-
- <note>
- <para>
- The binary log has replaced the old update log, which is no
- longer available as of MySQL 5.0. The binary log contains all
- information that is available in the update log in a more
- efficient format and in a manner that is transaction-safe. If
- you are using transactions, you must use the MySQL binary log
- for backups instead of the old update log.
- </para>
- </note>
-
- <para>
- The binary log is not used for statements such as
- <literal>SELECT</literal> or <literal>SHOW</literal> that do not
- modify data. If you want to log all statements (for example, to
- identify a problem query), use the general query log. See
- <xref linkend="query-log"/>.
- </para>
-
- <para>
- The primary purpose of the binary log is to be able to update
- databases during a restore operation as fully as possible,
- because the binary log contains all updates done after a backup
- was made. The binary log is also used on master replication
- servers as a record of the statements to be sent to slave
- servers. See <xref linkend="replication"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The binary log can also be used to track significant DDL
- events. Analyzing the binary log in this way is an integral
- part of the MySQL Enterprise Monitor. For more information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- Running the server with the binary log enabled makes performance
- about 1% slower. However, the benefits of the binary log for
- restore operations and in allowing you to set up replication
- generally outweigh this minor performance decrement.
- </para>
-
- <para>
- When started with the
- <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
- option, <command>mysqld</command> writes a log file containing
- all SQL statements that update data (both DDL and DML
- statements). If no <replaceable>base_name</replaceable> value is
- given, the default name is the value of the
- <literal>pid-file</literal> option (which by default is the name
- of host machine) followed by <literal>-bin</literal>. If the
- basename is given, but not as an absolute pathname, the server
- writes the file in the data directory. It is recommended that
- you specify a basename; see <xref linkend="open-bugs"/>, for the
- reason.
- </para>
-
- <para>
- If you supply an extension in the log name (for example,
- <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
- the extension is silently removed and ignored.
- </para>
-
- <para>
- <command>mysqld</command> appends a numeric extension to the
- binary log basename. The number increases each time the server
- creates a new log file, thus creating an ordered series of
- files. The server creates a new binary log file each time it
- starts or flushes the logs. The server also creates a new binary
- log file automatically when the current log's size reaches
- <literal>max_binlog_size</literal>. A binary log file may become
- larger than <literal>max_binlog_size</literal> if you are using
- large transactions because a transaction is written to the file
- in one piece, never split between files.
- </para>
-
- <para>
- To keep track of which binary log files have been used,
- <command>mysqld</command> also creates a binary log index file
- that contains the names of all used binary log files. By default
- this has the same basename as the binary log file, with the
- extension <literal>'.index'</literal>. You can change the name
- of the binary log index file with the
- <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
- option. You should not manually edit this file while
- <command>mysqld</command> is running; doing so would confuse
- <command>mysqld</command>.
- </para>
-
- <para>
- Replication slave servers by default do not write to their own
- binary log any statements that are received from the replication
- master. To cause these statements to be logged, start the slave
- with the <option>--log-slave-updates</option> option.
- </para>
-
- <para>
- Writes to the binary log file and binary log index file are
- handled in the same way as writes to <literal>MyISAM</literal>
- tables. See <xref linkend="full-disk"/>.
- </para>
-
- <para>
- You can delete all binary log files with the <literal>RESET
- MASTER</literal> statement, or a subset of them with
- <literal>PURGE MASTER LOGS</literal>. See
- <xref linkend="reset"/>, and
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- The binary log format has some known limitations that can affect
- recovery from backups. See
- <xref linkend="replication-features"/>.
- </para>
-
- <para>
- Binary logging for stored routines and triggers is done as
- described in <xref linkend="stored-procedure-logging"/>.
- </para>
-
- <para>
- You can use the following options to <command>mysqld</command>
- to affect what is logged to the binary log. See also the
- discussion that follows this option list.
- </para>
-
- <para>
- If you are using replication, the options described here affect
- which statements are sent by a master server to its slaves.
- There are also options for slave servers that control which
- statements received from the master to execute or ignore. For
- details, see <xref linkend="replication-options"/>.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para id="option_mysqld_binlog-do-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-do-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-do-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to restrict binary logging to updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). All other databases
- that are not explicitly mentioned are ignored. If you use
- this option, you should ensure that you do updates only in
- the default database.
- </para>
-
- <para>
- There is an exception to this for <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. The server uses
- the database named in the statement (not the default
- database) to decide whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-do-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement is
- <emphasis>not</emphasis> written into the binary log.
- </para>
-
- <para>
- To log multiple databases, use multiple options, specifying
- the option once for each database.
- </para>
- </listitem>
-
- <listitem>
- <para id="option_mysqld_binlog-ignore-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-ignore-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-ignore-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to suppress binary logging of updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). If you use this option,
- you should ensure that you do updates only in the default
- database.
- </para>
-
- <para>
- As with the <option>--binlog-do-db</option> option, there is
- an exception for the <literal>CREATE DATABASE</literal>,
- <literal>ALTER DATABASE</literal>, and <literal>DROP
- DATABASE</literal> statements. The server uses the database
- named in the statement (not the default database) to decide
- whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-ignore-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement
- <emphasis>is</emphasis> written into the binary log.
- </para>
-
- <para>
- To ignore multiple databases, use multiple options,
- specifying the option once for each database.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server evaluates the options for logging or ignoring updates
- to the binary log according to the following rules. As described
- previously, there is an exception for the <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. In those cases, the
- database being <emphasis>created, altered, or dropped</emphasis>
- replaces the default database in the following rules:
- </para>
-
- <orderedlist>
-
- <listitem>
- <para>
- Are there <option>--binlog-do-db</option> or
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Write the statement to the binary log and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some rules (<option>--binlog-do-db</option>,
- <option>--binlog-ignore-db</option>, or both). Is there a
- default database (has any database been selected by
- <literal>USE</literal>?)?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement, and
- exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There is a default database. Are there some
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Does the default database match any of the
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Write the statement and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement,
- and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- No: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some <option>--binlog-ignore-db</option> rules.
- Does the default database match any of the
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Do not write the statement, and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Write the query and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- </orderedlist>
-
- <para>
- For example, a slave running with only
- <option>--binlog-do-db=sales</option> does not write to the
- binary log any statement for which the default database is
- different from <literal>sales</literal> (in other words,
- <option>--binlog-do-db</option> can sometimes mean <quote>ignore
- other databases</quote>).
- </para>
-
- <para>
- If you are using replication, you should not delete old binary
- log files until you are sure that no slave still needs to use
- them. For example, if your slaves never run more than three days
- behind, once a day you can execute <command>mysqladmin
- flush-logs</command> on the master and then remove any logs that
- are more than three days old. You can remove the files manually,
- but it is preferable to use <literal>PURGE MASTER
- LOGS</literal>, which also safely updates the binary log index
- file for you (and which can take a date argument). See
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- A client that has the <literal>SUPER</literal> privilege can
- disable binary logging of its own statements by using a
- <literal>SET SQL_LOG_BIN=0</literal> statement. See
- <xref linkend="set-option"/>.
- </para>
-
- <para>
- You can display the contents of binary log files with the
- <command>mysqlbinlog</command> utility. This can be useful when
- you want to reprocess statements in the log. For example, you
- can update a MySQL server from the binary log as follows:
- </para>
-
-<programlisting>
-shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
-</programlisting>
-
- <para>
- See <xref linkend="mysqlbinlog"/>, for more information on the
- <command>mysqlbinlog</command> utility and how to use it.
- <command>mysqlbinlog</command> also can be used with relay log
- files because they are written using the same format as binary
- log files.
- </para>
-
- <para>
- Binary logging is done immediately after a statement completes
- but before any locks are released or any commit is done. This
- ensures that the log is logged in execution order.
- </para>
-
- <para>
- Updates to non-transactional tables are stored in the binary log
- immediately after execution. Within an uncommitted transaction,
- all updates (<literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>INSERT</literal>) that
- change transactional tables such as <literal>BDB</literal> or
- <literal>InnoDB</literal> tables are cached until a
- <literal>COMMIT</literal> statement is received by the server.
- At that point, <command>mysqld</command> writes the entire
- transaction to the binary log before the
- <literal>COMMIT</literal> is executed. When the thread that
- handles the transaction starts, it allocates a buffer of
- <literal>binlog_cache_size</literal> to buffer statements. If a
- statement is bigger than this, the thread opens a temporary file
- to store the transaction. The temporary file is deleted when the
- thread ends.
- </para>
-
- <para>
- Modifications to non-transactional tables cannot be rolled back.
- If a transaction that is rolled back includes modifications to
- non-transactional tables, the entire transaction is logged with
- a <literal>ROLLBACK</literal> statement at the end to ensure
- that the modifications to those tables are replicated.
- </para>
-
- <para>
- The <literal>Binlog_cache_use</literal> status variable shows
- the number of transactions that used this buffer (and possibly a
- temporary file) for storing statements. The
- <literal>Binlog_cache_disk_use</literal> status variable shows
- how many of those transactions actually had to use a temporary
- file. These two variables can be used for tuning
- <literal>binlog_cache_size</literal> to a large enough value
- that avoids the use of temporary files.
- </para>
-
- <para>
- The <literal>max_binlog_cache_size</literal> system variable
- (default 4GB, which is also the maximum) can be used to restrict
- the total size used to cache a multiple-statement transaction.
- If a transaction is larger than this many bytes, it fails and
- rolls back. The minimum value is 4096.
- </para>
-
- <para>
- Note that the binary log format is different in MySQL
- ¤t-series; from previous versions of MySQL, due to
- enhancements in replication. See
- <xref linkend="replication-compatibility"/>.
- </para>
-
- <para>
- By default, the binary log is not synchronized to disk at each
- write. So if the operating system or machine (not only the MySQL
- server) crashes, there is a chance that the last statements of
- the binary log are lost. To prevent this, you can make the
- binary log be synchronized to disk after every
- <replaceable>N</replaceable> writes to the binary log, with the
- <literal>sync_binlog</literal> system variable. See
- <xref linkend="server-system-variables"/>. 1 is the safest value
- for <literal>sync_binlog</literal>, but also the slowest. Even
- with <literal>sync_binlog</literal> set to 1, there is still the
- chance of an inconsistency between the table content and binary
- log content in case of a crash. For example, if you are using
- <literal>InnoDB</literal> tables and the MySQL server processes
- a <literal>COMMIT</literal> statement, it writes the whole
- transaction to the binary log and then commits this transaction
- into <literal>InnoDB</literal>. If the server crashes between
- those two operations, the transaction is rolled back by
- <literal>InnoDB</literal> at restart but still exists in the
- binary log. This problem can be solved with the
- <option>--innodb-safe-binlog</option> option, which adds
- consistency between the content of <literal>InnoDB</literal>
- tables and the binary log. (Note:
- <option>--innodb-safe-binlog</option> is unneeded as of MySQL
- 5.0; it was made obsolete by the introduction of XA transaction
- support.)
- </para>
-
- <para>
- For this option to provide a greater degree of safety, the MySQL
- server should also be configured to synchronize the binary log
- and the <literal>InnoDB</literal> logs to disk at every
- transaction. The <literal>InnoDB</literal> logs are synchronized
- by default, and <literal>sync_binlog=1</literal> can be used to
- synchronize the binary log. The effect of this option is that at
- restart after a crash, after doing a rollback of transactions,
- the MySQL server cuts rolled back <literal>InnoDB</literal>
- transactions from the binary log. This ensures that the binary
- log reflects the exact data of <literal>InnoDB</literal> tables,
- and so, that the slave remains in synchrony with the master (not
- receiving a statement which has been rolled back).
- </para>
-
- <para>
- Note that <option>--innodb-safe-binlog</option> can be used even
- if the MySQL server updates other storage engines than
- <literal>InnoDB</literal>. Only statements and transactions that
- affect <literal>InnoDB</literal> tables are subject to removal
- from the binary log at <literal>InnoDB</literal>'s crash
- recovery. If the MySQL server discovers at crash recovery that
- the binary log is shorter than it should have been, it lacks at
- least one successfully committed <literal>InnoDB</literal>
- transaction. This should not happen if
- <literal>sync_binlog=1</literal> and the disk/filesystem do an
- actual sync when they are requested to (some don't), so the
- server prints an error message <literal>The binary log
- <name> is shorter than its expected size</literal>. In
- this case, this binary log is not correct and replication should
- be restarted from a fresh snapshot of the master's data.
- </para>
-
- <para>
- For MySQL 5.0.46, the following session variables are written to
- the binary log and honoured by the replication slave when
- parsing the binary log:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>FOREIGN_KEY_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>UNIQUE_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>SQL_AUTO_IS_NULL</literal>
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="slow-query-log">
-
- <title>The Slow Query Log</title>
-
- <indexterm>
- <primary>slow query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>slow query log</secondary>
- </indexterm>
-
- <para>
- The slow query log consists of all SQL statements that took more
- than <literal>long_query_time</literal> seconds to execute. The
- time to acquire the initial table locks is not counted as
- execution time. <command>mysqld</command> writes a statement to
- the slow query log after it has been executed and after all
- locks have been released, so log order might be different from
- execution order. The minimum and default values of
- <literal>long_query_time</literal> are 1 and 10, respectively.
- </para>
-
- <para>
- To enable the slow query log, start <command>mysqld</command>
- with the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log-slow-queries</option>, the default name is
- <filename><replaceable>host_name</replaceable>-slow.log</filename>.
- If a filename is given, but not as an absolute pathname, the
- server writes the file in the data directory.
- </para>
-
- <para>
- The slow query log can be used to find queries that take a long
- time to execute and are therefore candidates for optimization.
- However, examining a long slow query log can become a difficult
- task. To make this easier, you can process the slow query log
- using the <command>mysqldumpslow</command> command to summarize
- the queries that appear in the log. Use <command>mysqldumpslow
- --help</command> to see the options that this command supports.
- </para>
-
- <para>
- In MySQL ¤t-series;, queries that do not use indexes are
- logged in the slow query log if the
- <option>--log-queries-not-using-indexes</option> option is
- specified. See <xref linkend="server-options"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- Excessive table scans are indicative of missing or poorly
- optimized indexes. Using an advisor specifically designed for
- the task, the MySQL Enterprise Monitor can identify such
- problems and offer advice on resolution. For more information
- see <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- In MySQL ¤t-series;, the
- <option>--log-slow-admin-statements</option> server option
- enables you to request logging of slow administrative statements
- such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
- TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
- query log.
- </para>
-
- <para>
- Queries handled by the query cache are not added to the slow
- query log, nor are queries that would not benefit from the
- presence of an index because the table has zero rows or one row.
- </para>
-
- </section>
-
- <section id="log-file-maintenance">
-
- <title>Server Log Maintenance</title>
-
- <indexterm>
- <primary>files</primary>
- <secondary>log</secondary>
- </indexterm>
-
- <indexterm>
- <primary>maintaining</primary>
- <secondary>log files</secondary>
- </indexterm>
-
- <indexterm>
- <primary>log files</primary>
- <secondary>maintaining</secondary>
- </indexterm>
-
- <para>
- MySQL Server can create a number of different log files that
- make it easy to see what is going on. See
- <xref linkend="log-files"/>. However, you must clean up these
- files regularly to ensure that the logs do not take up too much
- disk space.
- </para>
-
- <para>
- When using MySQL with logging enabled, you may want to back up
- and remove old log files from time to time and tell MySQL to
- start logging to new files. See <xref linkend="backup"/>.
- </para>
-
- <para>
- On a Linux (Red Hat) installation, you can use the
- <literal>mysql-log-rotate</literal> script for this. If you
- installed MySQL from an RPM distribution, this script should
- have been installed automatically. You should be careful with
- this script if you are using the binary log for replication. You
- should not remove binary logs until you are certain that their
- contents have been processed by all slaves.
- </para>
-
- <para>
- On other systems, you must install a short script yourself that
- you start from <command>cron</command> (or its equivalent) for
- handling log files.
- </para>
-
- <para>
- For the binary log, you can set the
- <literal>expire_logs_days</literal> system variable to expire
- binary log files automatically after a given number of days (see
- <xref linkend="server-system-variables"/>). If you are using
- replication, you should set the variable no lower than the
- maximum number of days your slaves might lag behind the master.
- </para>
-
- <para>
- You can force MySQL to start using new log files by issuing a
- <literal>FLUSH LOGS</literal> statement or executing
- <command>mysqladmin flush-logs</command> or <command>mysqladmin
- refresh</command>. See <xref linkend="flush"/>, and
- <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- A log flushing operation does the following:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If general query logging (<option>--log</option>) or slow
- query logging (<option>--log-slow-queries</option>) to a log
- file is enabled, the server closes and reopens the general
- query log file or slow query log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If binary logging (<option>--log-bin</option>) is used, the
- server closes the current log file and opens a new log file
- with the next sequence number.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the server was given an error log filename with the
- <option>--log-error</option> option, it renames the error
- log with the suffix <literal>-old</literal> and creates a
- new empty error log file.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server creates a new binary log file when you flush the
- logs. However, it just closes and reopens the general and slow
- query log files. To cause new files to be created on Unix,
- rename the current logs before flushing them. At flush time, the
- server will open new logs with the original names. For example,
- if the general and slow query logs are named
- <filename>mysql.log</filename> and
- <filename>mysql-slow.log</filename>, you can use a series of
- commands like this:
- </para>
-
-<programlisting>
-shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
-shell> <userinput>mv mysql.log mysql.old</userinput>
-shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-</programlisting>
-
- <para>
- At this point, you can make a backup of
- <filename>mysql.old</filename> and
- <filename>mysql-slow.log</filename> and then remove them from
- disk.
- </para>
-
- <para>
- On Windows, you cannot rename log files while the server has
- them open. You must stop the server and rename them, and then
- restart the server to create new logs.
- </para>
-
- <para>
- The session <literal>sql_log_off</literal> variable can be set
- to <literal>ON</literal> or <literal>OFF</literal> to disable or
- enable general query logging for the current connection.
- </para>
-
- </section>
-
- </section>
-
<section id="multiple-servers">
<title>Running Multiple MySQL Servers on the Same Machine</title>
Modified: trunk/refman-5.1/dba-core.xml
===================================================================
--- trunk/refman-5.1/dba-core.xml 2007-12-07 18:16:27 UTC (rev 9198)
+++ trunk/refman-5.1/dba-core.xml 2007-12-07 18:17:33 UTC (rev 9199)
Changed blocks: 3, Lines Added: 2438, Lines Deleted: 2438; 180034 bytes
@@ -26,19 +26,19 @@
<listitem>
<para>
- Managing user accounts
+ The server log files
</para>
</listitem>
<listitem>
<para>
- Performing backups
+ Managing user accounts
</para>
</listitem>
<listitem>
<para>
- The server log files
+ Performing backups
</para>
</listitem>
@@ -11896,6 +11896,2441 @@
</section>
+ <section id="log-files">
+
+ <title>MySQL Server Logs</title>
+
+ <indexterm>
+ <primary>log files</primary>
+ </indexterm>
+
+ <para>
+ MySQL has several different logs that can help you find out what
+ is going on inside <command>mysqld</command>:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Log Type</emphasis></entry>
+ <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
+ </row>
+ <row>
+ <entry>The error log</entry>
+ <entry>Problems encountered starting, running, or stopping
+ <command>mysqld</command></entry>
+ </row>
+ <row>
+ <entry>The general query log</entry>
+ <entry>Established client connections and statements received from clients</entry>
+ </row>
+ <row>
+ <entry>The binary log</entry>
+ <entry>All statements that change data (also used for replication)</entry>
+ </row>
+ <row>
+ <entry>The slow query log</entry>
+ <entry>All queries that took more than <literal>long_query_time</literal>
+ seconds to execute or didn't use indexes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ By default, all log files are created in the
+ <command>mysqld</command> data directory. You can force
+ <command>mysqld</command> to close and reopen the log files (or in
+ some cases switch to a new log) by flushing the logs. Log flushing
+ occurs when you issue a <literal>FLUSH LOGS</literal> statement or
+ execute <command>mysqladmin flush-logs</command> or
+ <command>mysqladmin refresh</command>. See
+ <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ If you are using MySQL replication capabilities, slave replication
+ servers maintain additional log files called relay logs.
+ <xref linkend="replication"/>, discusses relay log contents and
+ configuration.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The MySQL Enterprise Monitor provides a number of advisors
+ specifically related to the various log files. For more
+ information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ As of MySQL 5.1.6, the server can write general query and slow
+ query entries to log tables, log files, or both. For details, see
+ <xref linkend="log-tables"/>.
+ </para>
+
+ <para>
+ As of MySQL 5.1.12, additional runtime control of the general
+ query and slow query logs is available: You can enable or disable
+ logging, or change the name of the log file. See
+ <xref linkend="query-log"/>, and <xref linkend="slow-query-log"/>.
+ </para>
+
+ <section id="log-tables">
+
+ <title>Selecting General Query and Slow Query Log Output Destinations</title>
+
+ <para>
+ As of MySQL 5.1.6, the server provides flexible control over the
+ destination for log output. Log entries can be written to log
+ files to the <literal>general_log</literal> and
+ <literal>slow_log</literal> tables in the
+ <literal>mysql</literal> database. If logging is enabled, either
+ or both destinations can be selected. (Before MySQL 5.1.6, the
+ server uses only log files as the destination for general query
+ log and slow query log entries, if those logs are enabled.)
+ </para>
+
+ <note>
+ <para>
+ For new installations of MySQL 5.1.6 or higher, the log tables
+ are created during the installation procedure along with the
+ other system tables. If you upgrade MySQL from a release older
+ than 5.1.6 to MySQL 5.1.6 or higher, you must upgrade the
+ system tables after upgrading to make sure that the log tables
+ exist. See <xref linkend="mysql-upgrade"/>.
+ </para>
+ </note>
+
+ <para>
+ Currently, logging to tables incurs significantly more server
+ overhead than logging to files. If you enable the general log or
+ slow query log and require highest performance, you should log
+ to files and not to tables.
+ </para>
+
+ <para>
+ The <option>--log-output</option> option specifies the
+ destination for log output, if logging is enabled, but the
+ option does not in itself enable the logs. The syntax for this
+ option is
+ <option>--log-output[=<replaceable>value</replaceable>,...]</option>:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> is given with a value, the
+ value can be a comma-separated list of one or more of the
+ words <literal>TABLE</literal> (log to tables),
+ <literal>FILE</literal> (log to files), or
+ <literal>NONE</literal> (do not log to tables or files).
+ <literal>NONE</literal>, if present, takes precedence over
+ any other specifiers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> is omitted or given without
+ a value, the effect is the same as
+ <option>--log-output=FILE</option>. That is, the file
+ destination is selected. (For MySQL 5.1.6 through 5.1.20,
+ the default is the table destination.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> option also sets the value
+ of the global <literal>log_output</literal> system variable,
+ which can be modified at runtime to change the logging
+ destination for the server while it executes.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The
+ <option>--log[=<replaceable>file_name</replaceable>]</option>
+ option, if given, enables logging to the general query log for
+ the selected log destinations. Similarly, the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option, if given, enables logging to the slow query log for the
+ selected destinations. If you specify either option, the server
+ opens the corresponding log file and writes startup messages to
+ it. However, logging of queries to the file does not occur
+ unless the <literal>FILE</literal> log destination is selected.
+ </para>
+
+ <para>
+ Examples:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ To write general query log entries to the log table and the
+ log file, use <option>--log-output=TABLE,FILE</option> to
+ select both log destinations and the <option>--log</option>
+ option to enable the general query log.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To write general and slow query log entries only to the log
+ tables, use <option>--log-output=TABLE</option> to select
+ tables as the log destination and the <option>--log</option>
+ and <option>--log-slow-queries</option> options to enable
+ both logs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To write slow query log entries only to the log file, use
+ <option>--log-output=FILE</option> to select files as the
+ log destination and the <option>--log-slow-queries</option>
+ option to enable the slow query log. (In this case, because
+ the default log destination is <literal>FILE</literal>, you
+ could omit the <option>--log-output</option> option.)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Several system variables are associated with log tables and
+ files:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The global <literal>general_log</literal> and
+ <literal>slow_query_log</literal> variables indicate whether
+ the general query log and slow query log are enabled
+ (<literal>ON</literal>) or disabled
+ (<literal>OFF</literal>). You can set these variables at
+ runtime to control whether the logs are enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The global <literal>general_log_file</literal> and
+ <literal>slow_query_log_file</literal> variables indicate
+ the names of the general query log and slow query log files.
+ You can set these variables at runtime to change the names
+ of the log files. (If the <option>--log</option> and
+ <literal>--log-slow-queries</literal> options were not
+ given, the variable values are set to the default log
+ filenames.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The session <literal>sql_log_off</literal> variable can be
+ set to <literal>ON</literal> or <literal>OFF</literal> to
+ disable or enable general query logging for the current
+ connection.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The use of tables for log output offers the following benefits:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Log entries have a standard format. To display the current
+ structure of the log tables, use these statements:
+ </para>
+
+<programlisting>
+SHOW CREATE TABLE mysql.general_log;
+SHOW CREATE TABLE mysql.slow_log;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Log contents are accessible via SQL statements. This enables
+ the use of queries that select only those log entries that
+ satisfy specific criteria. For example, to select log
+ contents associated with a particular client (which can be
+ useful for identifying problematic queries from that
+ client), it is easier to do this using a log table than a
+ log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Logs are accessible remotely through any client that can
+ connect to the server and issue queries (if the client has
+ the appropriate log table privileges). It's not necessary to
+ log in to the server host and directly access the
+ filesystem.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The log table implementation has the following characteristics:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ In general, the primary purpose of log tables is to provide
+ an interface for users to observe the runtime execution of
+ the server, not to interfere with its runtime execution.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>CREATE TABLE</literal>, <literal>ALTER
+ TABLE</literal>, and <literal>DROP TABLE</literal> are valid
+ operations on a log table. For <literal>ALTER
+ TABLE</literal> and <literal>DROP TABLE</literal>, the log
+ table cannot be in use and must be disabled, as described
+ later.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default, the log tables use the <literal>CSV</literal>
+ storage engine that writes data in comma-separated values
+ format. For users who have access to the
+ <filename>.CSV</filename> files that contain log table data,
+ the files are easy to import into other programs such as
+ spreadsheets that can process CSV input.
+ </para>
+
+ <para>
+ Beginning with MySQL 5.1.12, the log tables can be altered
+ to use the <literal>MyISAM</literal> storage engine. You
+ cannot use <literal>ALTER TABLE</literal> to alter a log
+ table that is in use. The log must be disabled first. No
+ engines other than <literal>CSV</literal> or
+ <literal>MyISAM</literal> are legal for the log tables.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To disable logging so that you can alter (or drop) a log
+ table, you can use the following strategy. The example uses
+ the general query log; the procedure for the slow query log
+ is similar but uses the <literal>slow_log</literal> table
+ and <literal>slow_query_log</literal> system variable.
+ </para>
+
+<programlisting>
+SET @old_log_state = @@global.general_log;
+SET GLOBAL general_log = 'OFF';
+ALTER TABLE mysql.general_log ENGINE = MyISAM;
+SET GLOBAL general_log = @old_log_state;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>TRUNCATE TABLE</literal> is a valid operation on a
+ log table. It can be used to expire log entries.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ As of MySQL 5.1.13, <literal>RENAME TABLE</literal> is a
+ valid operation on a log table. You can atomically rename a
+ log table (to perform log rotation, for example) using the
+ following strategy:
+ </para>
+
+<programlisting>
+USE mysql;
+CREATE TABLE IF NOT EXISTS general_log2 LIKE general_log;
+RENAME TABLE general_log TO general_log_backup, general_log2 TO general_log;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>LOCK TABLES</literal> cannot be used on a log
+ table.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>INSERT</literal>, <literal>DELETE</literal>, and
+ <literal>UPDATE</literal> cannot be used on a log table.
+ These operations are allowed only internally to the server
+ itself.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The global read lock and the state of the global
+ <literal>read_only</literal> system variable have no effect
+ on log tables. The server can always write to the log
+ tables.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Entries written to the log tables are not written to the
+ binary log and thus are not replicated to slave servers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To flush the log tables or log files, use <literal>FLUSH
+ TABLES</literal> or <literal>FLUSH LOGS</literal>,
+ respectively. (From MySQL 5.1.12 to 5.1.20, <literal>FLUSH
+ TABLES</literal> ignores log tables and <literal>FLUSH
+ LOGS</literal> flushes both the log tables and files.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It is not recommended to partition log tables, and doing so
+ is not allowed beginning with MySQL 5.1.20.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="error-log">
+
+ <title>The Error Log</title>
+
+ <para>
+ The error log contains information indicating when
+ <command>mysqld</command> was started and stopped and also any
+ critical errors that occur while the server is running. If
+ <command>mysqld</command> notices a table that needs to be
+ automatically checked or repaired, it writes a message to the
+ error log.
+ </para>
+
+ <para>
+ On some operating systems, the error log contains a stack trace
+ if <command>mysqld</command> dies. The trace can be used to
+ determine where <command>mysqld</command> died. See
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
+ Internals: Porting</ulink>.
+ </para>
+
+ <para>
+ You can specify where <command>mysqld</command> writes the error
+ log with the
+ <option>--log-error[=<replaceable>file_name</replaceable>]</option>
+ option. If no <replaceable>file_name</replaceable> value is
+ given, <command>mysqld</command> uses the name
+ <filename><replaceable>host_name</replaceable>.err</filename> by
+ default and writes the file in the data directory. If you
+ execute <literal>FLUSH LOGS</literal>, the error log is renamed
+ with the suffix <literal>-old</literal> and
+ <command>mysqld</command> creates a new empty log file. (No
+ renaming occurs if the <option>--log-error</option> option was
+ not given to <command>mysqld</command>.)
+ </para>
+
+ <para>
+ If you do not specify <option>--log-error</option>, or (on
+ Windows) if you use the <option>--console</option> option,
+ errors are written to <literal>stderr</literal>, the standard
+ error output. Usually this is your terminal.
+ </para>
+
+ <para>
+ On Windows, error output is always written to the
+ <literal>.err</literal> file if <option>--console</option> is
+ not given.
+ </para>
+
+ <para>
+ The <option>--log-warnings</option> option or
+ <literal>log_warnings</literal> system variable can be used to
+ control warning logging to the error log. The default value is
+ enabled (1). Warning logging can be disabled using a value of 0.
+ If the value is greater than 1, aborted connections are written
+ to the error log. See <xref linkend="communication-errors"/>.
+ </para>
+
+ <para>
+ If you use <command>mysqld_safe</command> to start
+ <command>mysqld</command>, <command>mysqld_safe</command>
+ arranges for <command>mysqld</command> to write error messages
+ to a log file or (as of MySQL 5.1.20) to
+ <literal>syslog</literal>:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Before 5.1.20, <command>mysqld_safe</command> behavior is to
+ log to a file, using the default error log file if the
+ <option>--log-error</option> option is not given to
+ <command>mysqld_safe</command>. Otherwise,
+ <command>mysqld_safe</command> uses the filename specified
+ via
+ <option>--log-error=<replaceable>file_name</replaceable></option>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ From 5.1.20 on, <command>mysqld_safe</command> has two
+ additional error-logging options, <option>--syslog</option>
+ and <option>--skip-syslog</option>.
+ </para>
+
+ <para>
+ In 5.1.21 and up, the default with no logging options is
+ <option>--skip-syslog</option>, which is compatible with the
+ default behavior of writing an error log file for releases
+ prior to 5.1.20. To explicitly specify use of an error log
+ file, specify
+ <option>--log-error=<replaceable>file_name</replaceable></option>
+ to <command>mysqld_safe</command>, and
+ <command>mysqld_safe</command> will arrange for
+ <command>mysqld</command> to write messages to a log file.
+ To use <literal>syslog</literal> instead, specify the
+ <option>--syslog</option> option.
+ </para>
+
+ <para>
+ <emphasis role="bold">In 5.1.20 <emphasis>only</emphasis>,
+ the following conditions apply</emphasis>: 1) The default is
+ to use <literal>syslog</literal>, which is not compatible
+ with releases prior to 5.1.20. 2) Logging to
+ <literal>syslog</literal> may fail to operate correctly in
+ some cases, so we recommend that you use
+ <option>--skip-syslog</option> or
+ <option>--log-error</option>.
+ </para>
+
+ <para>
+ For logging to <literal>syslog</literal>, messages from
+ <command>mysqld_safe</command> and <command>mysqld</command>
+ are written with a tag of <literal>mysqld_safe</literal> and
+ <literal>mysqld</literal>, respectively. As of MySQL 5.1.21,
+ to specify a suffix for the tag, use
+ <option>--syslog-tag=<replaceable>tag</replaceable></option>,
+ which modifies the tags to be
+ <literal>mysqld_safe-<replaceable>tag</replaceable></literal>
+ and
+ <literal>mysqld-<replaceable>tag</replaceable></literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ If you specify <option>--log-error</option> in an option file in
+ a section that <command>mysqld</command> reads,
+ <command>mysqld_safe</command> also will find and use the
+ option.
+ </para>
+
+ <para>
+ If <command>mysqld_safe</command> is used to start
+ <command>mysqld</command> and <command>mysqld</command> dies
+ unexpectedly, <command>mysqld_safe</command> notices that it
+ needs to restart <command>mysqld</command> and writes a
+ <literal>restarted mysqld</literal> message to the error log.
+ </para>
+
+ </section>
+
+ <section id="query-log">
+
+ <title>The General Query Log</title>
+
+ <indexterm>
+ <primary>general query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>general query log</secondary>
+ </indexterm>
+
+ <para>
+ The general query log is a general record of what
+ <command>mysqld</command> is doing. The server writes
+ information to this log when clients connect or disconnect, and
+ it logs each SQL statement received from clients. The general
+ query log can be very useful when you suspect an error in a
+ client and want to know exactly what the client sent to
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ <command>mysqld</command> writes statements to the query log in
+ the order that it receives them, which might differ from the
+ order in which they are executed. This logging order contrasts
+ to the binary log, for which statements are written after they
+ are executed but before any locks are released. (Also, the query
+ log contains all statements, whereas the binary log does not
+ contain statements that only select data.)
+ </para>
+
+ <para>
+ To enable the general query log as of MySQL 5.1.6, start
+ <command>mysqld</command> with the
+ <option>--log[=<replaceable>file_name</replaceable>]</option> or
+ <option>-l [<replaceable>file_name</replaceable>]</option>
+ option, and optionally use <option>--log-output</option> to
+ specify the log destination (as described in
+ <xref linkend="log-tables"/>). Before 5.1.6, the general query
+ log destination is always a file. To enable the general query
+ log file, use the
+ <option>--log[=<replaceable>file_name</replaceable>]</option> or
+ <option>-l [<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log</option> or <option>-l</option>, the default name
+ is <filename><replaceable>host_name</replaceable>.log</filename>
+ in the data directory. If a filename is given, but not as an
+ absolute pathname, the server writes the file in the data
+ directory.
+ </para>
+
+ <para>
+ When <option>--log</option> or <option>-l</option> is specified,
+ the <option>--general-log</option> option also may be given as
+ of MySQL 5.1.12 to specify the initial general query log state.
+ With no argument or an argument of 0, the option disables the
+ log. If omitted or given with an argument of 1, the option
+ enables the log. If <option>--log</option> or
+ <option>-l</option> is not specified,
+ <option>--general-log</option> has no effect.
+ </para>
+
+ <para>
+ The global <literal>general_log</literal> and
+ <literal>general_log_file</literal> system variables provide
+ runtime control over the general query log. Set
+ <literal>general_log</literal> to 0 (or <literal>OFF</literal>)
+ to disable the log or to 1 (or <literal>ON</literal>) to enable
+ it. Set <literal>general_log_file</literal> to specify the name
+ of the log file. If a log file already is open, it is closed and
+ the new file is opened.
+ </para>
+
+ <para>
+ When the general query log is enabled, output is written to any
+ destinations specified by the <option>--log-output</option>
+ option or <literal>log_output</literal> system variable. Note
+ that if the destination is <literal>NONE</literal>, no output is
+ written even if the general log is enabled. Setting the log
+ filename has no effect on logging if the log destination value
+ does not contain <literal>FILE</literal>.
+ </para>
+
+ <para>
+ Server restarts and log flushing do not cause a new general
+ query log file to be generated (although flushing closes and
+ reopens it). On Unix, you can rename the file and create a new
+ one by using the following commands:
+ </para>
+
+<programlisting>
+shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
+shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
+</programlisting>
+
+ <para>
+ On Windows, you cannot rename the log file while the server has
+ it open. You must stop the server and rename the file, and then
+ restart the server to create a new log file.
+ </para>
+
+ <para>
+ As of MySQL 5.1.12, you can disable the general query log at
+ runtime:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'OFF';
+</programlisting>
+
+ <para>
+ With the log disabled, rename the log file externally; for
+ example, from the command line. Then enable the log again:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'ON';
+</programlisting>
+
+ <para>
+ This method works on any platform and does not require a server
+ restart.
+ </para>
+
+ <para>
+ The session <literal>sql_log_off</literal> variable can be set
+ to <literal>ON</literal> or <literal>OFF</literal> to disable or
+ enable general query logging for the current connection.
+ </para>
+
+ </section>
+
+ <section id="binary-log">
+
+ <title>The Binary Log</title>
+
+ <indexterm>
+ <primary>binary log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>binary log</secondary>
+ </indexterm>
+
+ <para>
+ The binary log contains all statements that update data or
+ potentially could have updated it (for example, a
+ <literal>DELETE</literal> which matched no rows). Statements are
+ stored in the form of <quote>events</quote> that describe the
+ modifications. The binary log also contains information about
+ how long each statement took that updated data.
+ </para>
+
+ <para>
+ The binary log is not used for statements such as
+ <literal>SELECT</literal> or <literal>SHOW</literal> that do not
+ modify data. If you want to log all statements (for example, to
+ identify a problem query), use the general query log. See
+ <xref linkend="query-log"/>.
+ </para>
+
+ <para>
+ The format of the events recorded in the binary log is dependent
+ on the binary logging format. Three format types are supported,
+ row-based logging, statement-based logging and mixed-base
+ logging. The binary logging format used depends on the MySQL
+ version. For more information on logging formats, see
+ <xref linkend="binary-log-formats"/>.
+ </para>
+
+ <para>
+ The primary purpose of the binary log is to be able to update
+ databases during a restore operation as fully as possible,
+ because the binary log contains all updates done after a backup
+ was made. The binary log is also used on master replication
+ servers as a record of the statements to be sent to slave
+ servers. See <xref linkend="replication"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The binary log can also be used to track significant DDL
+ events. Analyzing the binary log in this way is an integral
+ part of the MySQL Enterprise Monitor. For more information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ Running the server with the binary log enabled makes performance
+ about 1% slower. However, the benefits of the binary log for
+ restore operations and in allowing you to set up replication
+ generally outweigh this minor performance decrement.
+ </para>
+
+ <para>
+ When started with the
+ <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
+ option, <command>mysqld</command> writes a log file containing
+ all SQL statements that update data (both DDL and DML
+ statements). If no <replaceable>base_name</replaceable> value is
+ given, the default name is the value of the
+ <literal>pid-file</literal> option (which by default is the name
+ of host machine) followed by <literal>-bin</literal>. If the
+ basename is given, but not as an absolute pathname, the server
+ writes the file in the data directory. It is recommended that
+ you specify a basename; see <xref linkend="open-bugs"/>, for the
+ reason.
+ </para>
+
+ <para>
+ If you supply an extension in the log name (for example,
+ <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
+ the extension is silently removed and ignored.
+ </para>
+
+ <para>
+ <command>mysqld</command> appends a numeric extension to the
+ binary log basename. The number increases each time the server
+ creates a new log file, thus creating an ordered series of
+ files. The server creates a new binary log file each time it
+ starts or flushes the logs. The server also creates a new binary
+ log file automatically when the current log's size reaches
+ <literal>max_binlog_size</literal>. A binary log file may become
+ larger than <literal>max_binlog_size</literal> if you are using
+ large transactions because a transaction is written to the file
+ in one piece, never split between files.
+ </para>
+
+ <para>
+ To keep track of which binary log files have been used,
+ <command>mysqld</command> also creates a binary log index file
+ that contains the names of all used binary log files. By default
+ this has the same basename as the binary log file, with the
+ extension <literal>'.index'</literal>. You can change the name
+ of the binary log index file with the
+ <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
+ option. You should not manually edit this file while
+ <command>mysqld</command> is running; doing so would confuse
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ Replication slave servers by default do not write to their own
+ binary log any statements that are received from the replication
+ master. To cause these statements to be logged, start the slave
+ with the <option>--log-slave-updates</option> option.
+ </para>
+
+ <para>
+ Writes to the binary log file and binary log index file are
+ handled in the same way as writes to <literal>MyISAM</literal>
+ tables. See <xref linkend="full-disk"/>.
+ </para>
+
+ <para>
+ You can delete all binary log files with the <literal>RESET
+ MASTER</literal> statement, or a subset of them with
+ <literal>PURGE MASTER LOGS</literal>. See
+ <xref linkend="reset"/>, and
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ The binary log format has some known limitations that can affect
+ recovery from backups. See
+ <xref linkend="replication-features"/>.
+ </para>
+
+ <para>
+ Binary logging for stored routines and triggers is done as
+ described in <xref linkend="stored-procedure-logging"/>.
+ </para>
+
+ <para>
+ You can use the following options to <command>mysqld</command>
+ to affect what is logged to the binary log. See also the
+ discussion that follows this option list.
+ </para>
+
+ <para>
+ If you are using replication, the options described here affect
+ which statements are sent by a master server to its slaves.
+ There are also options for slave servers that control which
+ statements received from the master to execute or ignore. For
+ details, see <xref linkend="replication-options"/>.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para id="option_mysqld_binlog-do-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-do-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-do-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to restrict binary logging to updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). All other databases
+ that are not explicitly mentioned are ignored. If you use
+ this option, you should ensure that you do updates only in
+ the default database.
+ </para>
+
+ <para>
+ There is an exception to this for <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. The server uses
+ the database named in the statement (not the default
+ database) to decide whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-do-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement is
+ <emphasis>not</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To log multiple databases, use multiple options, specifying
+ the option once for each database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqld_binlog-ignore-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-ignore-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-ignore-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to suppress binary logging of updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). If you use this option,
+ you should ensure that you do updates only in the default
+ database.
+ </para>
+
+ <para>
+ As with the <option>--binlog-do-db</option> option, there is
+ an exception for the <literal>CREATE DATABASE</literal>,
+ <literal>ALTER DATABASE</literal>, and <literal>DROP
+ DATABASE</literal> statements. The server uses the database
+ named in the statement (not the default database) to decide
+ whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-ignore-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement
+ <emphasis>is</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To ignore multiple databases, use multiple options,
+ specifying the option once for each database.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server evaluates the options for logging or ignoring updates
+ to the binary log according to the following rules. As described
+ previously, there is an exception for the <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. In those cases, the
+ database being <emphasis>created, altered, or dropped</emphasis>
+ replaces the default database in the following rules:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Are there <option>--binlog-do-db</option> or
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Write the statement to the binary log and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some rules (<option>--binlog-do-db</option>,
+ <option>--binlog-ignore-db</option>, or both). Is there a
+ default database (has any database been selected by
+ <literal>USE</literal>?)?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement, and
+ exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There is a default database. Are there some
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Does the default database match any of the
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Write the statement and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement,
+ and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some <option>--binlog-ignore-db</option> rules.
+ Does the default database match any of the
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Do not write the statement, and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Write the query and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ For example, a slave running with only
+ <option>--binlog-do-db=sales</option> does not write to the
+ binary log any statement for which the default database is
+ different from <literal>sales</literal> (in other words,
+ <option>--binlog-do-db</option> can sometimes mean <quote>ignore
+ other databases</quote>).
+ </para>
+
+ <para>
+ If you are using replication, you should not delete old binary
+ log files until you are sure that no slave still needs to use
+ them. For example, if your slaves never run more than three days
+ behind, once a day you can execute <command>mysqladmin
+ flush-logs</command> on the master and then remove any logs that
+ are more than three days old. You can remove the files manually,
+ but it is preferable to use <literal>PURGE MASTER
+ LOGS</literal>, which also safely updates the binary log index
+ file for you (and which can take a date argument). See
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ A client that has the <literal>SUPER</literal> privilege can
+ disable binary logging of its own statements by using a
+ <literal>SET SQL_LOG_BIN=0</literal> statement. See
+ <xref linkend="set-option"/>.
+ </para>
+
+ <para>
+ You can display the contents of binary log files with the
+ <command>mysqlbinlog</command> utility. This can be useful when
+ you want to reprocess statements in the log. For example, you
+ can update a MySQL server from the binary log as follows:
+ </para>
+
+<programlisting>
+shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
+</programlisting>
+
+ <para>
+ See <xref linkend="mysqlbinlog"/>, for more information on the
+ <command>mysqlbinlog</command> utility and how to use it.
+ <command>mysqlbinlog</command> also can be used with relay log
+ files because they are written using the same format as binary
+ log files.
+ </para>
+
+ <para>
+ Binary logging is done immediately after a statement completes
+ but before any locks are released or any commit is done. This
+ ensures that the log is logged in execution order.
+ </para>
+
+ <para>
+ Updates to non-transactional tables are stored in the binary log
+ immediately after execution. Within an uncommitted transaction,
+ all updates (<literal>UPDATE</literal>,
+ <literal>DELETE</literal>, or <literal>INSERT</literal>) that
+ change transactional tables such as <literal>InnoDB</literal>
+ tables are cached until a <literal>COMMIT</literal> statement is
+ received by the server. At that point, <command>mysqld</command>
+ writes the entire transaction to the binary log before the
+ <literal>COMMIT</literal> is executed. When the thread that
+ handles the transaction starts, it allocates a buffer of
+ <literal>binlog_cache_size</literal> to buffer statements. If a
+ statement is bigger than this, the thread opens a temporary file
+ to store the transaction. The temporary file is deleted when the
+ thread ends.
+ </para>
+
+ <para>
+ Modifications to non-transactional tables cannot be rolled back.
+ If a transaction that is rolled back includes modifications to
+ non-transactional tables, the entire transaction is logged with
+ a <literal>ROLLBACK</literal> statement at the end to ensure
+ that the modifications to those tables are replicated.
+ </para>
+
+ <para>
+ The <literal>Binlog_cache_use</literal> status variable shows
+ the number of transactions that used this buffer (and possibly a
+ temporary file) for storing statements. The
+ <literal>Binlog_cache_disk_use</literal> status variable shows
+ how many of those transactions actually had to use a temporary
+ file. These two variables can be used for tuning
+ <literal>binlog_cache_size</literal> to a large enough value
+ that avoids the use of temporary files.
+ </para>
+
+ <para>
+ The <literal>max_binlog_cache_size</literal> system variable
+ (default 4GB, which is also the maximum) can be used to restrict
+ the total size used to cache a multiple-statement transaction.
+ If a transaction is larger than this many bytes, it fails and
+ rolls back. The minimum value is 4096.
+ </para>
+
+ <para>
+ If you are using the binary log and row based logging,
+ concurrent inserts are converted to normal inserts for
+ <literal>CREATE ... SELECT</literal> or <literal>INSERT ...
+ SELECT</literal> statement. This is done to ensure that you can
+ re-create an exact copy of your tables by applying the log
+ during a backup operation. If you are using statement based
+ logging then the original statement is written to the log.
+ </para>
+
+ <para>
+ Note that the binary log format is different in MySQL
+ ¤t-series; from previous versions of MySQL, due to
+ enhancements in replication. See
+ <xref linkend="replication-compatibility"/>.
+ </para>
+
+ <para>
+ By default, the binary log is not synchronized to disk at each
+ write. So if the operating system or machine (not only the MySQL
+ server) crashes, there is a chance that the last statements of
+ the binary log are lost. To prevent this, you can make the
+ binary log be synchronized to disk after every
+ <replaceable>N</replaceable> writes to the binary log, with the
+ <literal>sync_binlog</literal> system variable. See
+ <xref linkend="server-system-variables"/>. 1 is the safest value
+ for <literal>sync_binlog</literal>, but also the slowest. Even
+ with <literal>sync_binlog</literal> set to 1, there is still the
+ chance of an inconsistency between the table content and binary
+ log content in case of a crash. For example, if you are using
+ <literal>InnoDB</literal> tables and the MySQL server processes
+ a <literal>COMMIT</literal> statement, it writes the whole
+ transaction to the binary log and then commits this transaction
+ into <literal>InnoDB</literal>. If the server crashes between
+ those two operations, the transaction is rolled back by
+ <literal>InnoDB</literal> at restart but still exists in the
+ binary log. To resolve this, you should set
+ <option>--innodb_support_xa</option> to 1. Although this option
+ is related to the support of XA transactions in InnoDB, it also
+ ensures that the binary log and InnoDB data files are
+ synchronized.
+ </para>
+
+ <para>
+ For this option to provide a greater degree of safety, the MySQL
+ server should also be configured to synchronize the binary log
+ and the <literal>InnoDB</literal> logs to disk at every
+ transaction. The <literal>InnoDB</literal> logs are synchronized
+ by default, and <literal>sync_binlog=1</literal> can be used to
+ synchronize the binary log. The effect of this option is that at
+ restart after a crash, after doing a rollback of transactions,
+ the MySQL server cuts rolled back <literal>InnoDB</literal>
+ transactions from the binary log. This ensures that the binary
+ log reflects the exact data of <literal>InnoDB</literal> tables,
+ and so, that the slave remains in synchrony with the master (not
+ receiving a statement which has been rolled back).
+ </para>
+
+ <para>
+ If the MySQL server discovers at crash recovery that the binary
+ log is shorter than it should have been, it lacks at least one
+ successfully committed <literal>InnoDB</literal> transaction.
+ This should not happen if <literal>sync_binlog=1</literal> and
+ the disk/filesystem do an actual sync when they are requested to
+ (some don't), so the server prints an error message <literal>The
+ binary log <name> is shorter than its expected
+ size</literal>. In this case, this binary log is not correct and
+ replication should be restarted from a fresh snapshot of the
+ master's data.
+ </para>
+
+ <para>
+ For MySQL 5.1.20 and later (and MySQL 5.0.46 for backwards
+ compatibility), the following session variables are written to
+ the binary log and honoured by the replication slave when
+ parsing the binary log:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>FOREIGN_KEY_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>UNIQUE_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>SQL_AUTO_IS_NULL</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <section id="binary-log-formats">
+
+ <title>Binary Logging Formats</title>
+
+ <para>
+ A number of different logging formats are used to record
+ information in the binary log. The exact format employed
+ depends on the version of MySQL being used. There are three
+ logging formats:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Replication capabilities in MySQL originally were based on
+ propagation of SQL statements from master to slave. This
+ is called <emphasis>statement-based logging</emphasis>
+ (SBL). SBL is identified internally using
+ <literal>STATMENT</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In <emphasis>row-based logging</emphasis> (RBL), the
+ master writes events to the binary log that indicate how
+ individual table rows are affected. Support for RBL was
+ added in MySQL 5.1.5. RBL is identified internally using
+ <literal>ROW</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ As of MySQL 5.1.8, a third option is available:
+ <emphasis>mixed-based logging</emphasis> (MBL). With MBL,
+ SBL is used by default, but automatically switches to RBL
+ in particular cases as described below. From MySQL 5.1.8,
+ MBL is the default mode. MBL is identified internally
+ using <literal>MIXED</literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Starting with MySQL 5.1.20, MBL is the default but storage
+ engine being used can also set or limit the logging format
+ according to the capabilities of the storage engine. This
+ helps to eliminate issues when logging, and more specifically
+ replicating, certain statements between the master and slave
+ using the different engines.
+ </para>
+
+ </section>
+
+ <section id="binary-log-setting">
+
+ <title>Setting The Binary Log Format</title>
+
+ <para>
+ The default binary logging format depends on the version of
+ MySQL you are using:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ For MySQL 5.1.11 and earlier, statement-based logging is
+ used by default.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For MySQL 5.1.12 and later, mixed-based logging is used by
+ default.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ You can force the default replication format by specifying the
+ format type to the
+ <option>--binlog-format=<replaceable>type</replaceable></option>
+ option. When set, all replication slaves connecting to the
+ server will read the events according to this setting. The
+ supported options are:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>ROW</literal> — sets row-based
+ replication as the default.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>STATEMENT</literal> — sets
+ statement-based replication as the default. This is the
+ default for MySQL 5.1.11 and earlier.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>MIXED</literal> — sets mixed-based
+ replication as the default. This is the default for
+ MySQL 5.1.12 and later.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ <para>
+ The logging format also can be switched at runtime. To specify
+ the format globally for all clients, set the global value of
+ the <literal>binlog_format</literal> system variable. (To
+ change a global variable you need the <literal>SUPER</literal>
+ privilege.)
+ </para>
+
+ <para>
+ To switch to statement-based format, use either of these
+ statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'STATEMENT';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 1;</userinput>
+</programlisting>
+
+ <para>
+ To switch to row-based format, use either of these statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'ROW';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 2;</userinput>
+</programlisting>
+
+ <para>
+ To switch to mixed format, use either of these statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'MIXED';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 3;</userinput>
+</programlisting>
+
+ <para>
+ Individual clients can control the logging format for their
+ own statements by setting the session value of
+ <literal>binlog_format</literal>. For example:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET SESSION binlog_format = 'STATEMENT';</userinput>
+mysql> <userinput>SET SESSION binlog_format = 'ROW';</userinput>
+mysql> <userinput>SET SESSION binlog_format = 'MIXED';</userinput>
+</programlisting>
+
+ <para>
+ In addition to switching the logging format manually, a slave
+ server may switch the format
+ <emphasis>automatically</emphasis>. This happens when the
+ server is running in either <literal>STATEMENT</literal> or
+ <literal>MIXED</literal> format and encounters a row in the
+ binary log that is written in <literal>ROW</literal> logging
+ format. In that case, the slave switches to row-based
+ replication temporarily for that event, and switches back to
+ the previous format afterwards.
+ </para>
+
+ <para>
+ There are two reasons why you might want to set replication
+ logging on a per-connection basis:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A thread that makes many small changes to the database
+ might want to use row-based logging. A thread that
+ performs updates that match many rows in the
+ <literal>WHERE</literal> clause might want to use
+ statement-based logging because it will be more efficient
+ to log a few statements than many rows.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Some statements require a lot of execution time on the
+ master, but result in just a few rows being modified. It
+ might therefore be beneficial to replicate them using
+ row-based logging.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ There are exceptions when you cannot switch the replication
+ format at runtime:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ From within a stored function or a trigger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <literal>NDB</literal> is enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the session is currently in row-based replication
+ mode and has open temporary tables.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ Trying to switch the format in those cases results in an
+ error.
+ </para>
+
+ <para>
+ Switching the replication format at runtime is not recommended
+ when any <emphasis>temporary tables</emphasis> exist, because
+ temporary tables are logged only when using statement-based
+ replication, whereas with row-based replication they are not
+ logged. With mixed replication, temporary tables are usually
+ logged; exceptions happen with user-defined functions (UDF)
+ and with the <function>UUID()</function> function.
+ </para>
+
+ <para>
+ With the binlog format set to <literal>ROW</literal>, many
+ changes are written to the binary log using the row-based
+ format. Some changes, however, still use the statement-based
+ format. Examples include all DDL (data definition language)
+ statements such as <literal>CREATE TABLE</literal>,
+ <literal>ALTER TABLE</literal>, or <literal>DROP
+ TABLE</literal>.
+ </para>
+
+ <para>
+ The <option>--binlog-row-event-max-size</option> option is
+ available for servers that are capable of row-based
+ replication. Rows are stored into the binary log in chunks
+ having a size in bytes not exceeding the value of this option.
+ The value must be a multiple of 256. The default value is
+ 1024.
+ </para>
+
+ <warning>
+ <para>
+ When using <emphasis>statement-based logging</emphasis> in a
+ replication scenario, it is possible for the data on the
+ master and slave to become different if a statement is
+ designed in such a way that the data modification is
+ <firstterm>non-deterministic</firstterm>; that is, it is
+ left to the will of the query optimizer. In general, this is
+ not a good practice even outside of replication. For a
+ detailed explanation of this issue, see
+ <xref linkend="open-bugs"/>.
+ </para>
+ </warning>
+
+ </section>
+
+ <section id="binary-log-mixed">
+
+ <title>Mixed Binary Logging (MBL) Format</title>
+
+ <para>
+ When running in <literal>MIXED</literal> mode, automatic
+ switching from statement-based to row-based replication takes
+ place under the following conditions:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When a DML statement updates an <literal>NDB</literal>
+ table
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a function contains
+ <function role="sql">UUID()</function>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When 2 or more tables with
+ <literal>AUTO_INCREMENT</literal> columns are updated
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When any <literal>INSERT DELAYED</literal> is executed
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When the body of a view requires row-based replication,
+ the statement creating the view also uses it — for
+ example, this occurs when the statement creating a view
+ uses the <function role="sql">UUID()</function> function
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a call to a UDF is involved
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Beginning with MySQL 5.1.23:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When <function role="sql">FOUND_ROWS()</function> or
+ <function role="sql">ROW_COUNT()</function> is used
+ (Bug #12092, Bug #30244)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When <function role="sql">USER()</function>,
+ <function role="sql">CURRENT_USER()</function>, or
+ <function role="sql" condition="function_current-user">CURRENT_USER</function>
+ is used (Bug #28086)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <note>
+ <para>
+ Starting with MySQL 5.1.20 a warning is generated if you try
+ to log execute a statement in statement-logging mode that
+ should be logged in row-logging mode. The warning will be
+ shown both in the client (and available with <literal>SHOW
+ WARNINGS</literal>) and through the
+ <command>mysqld</command> error log. A warning is added to
+ the <literal>SHOW WARNINGS</literal> table each time a
+ statement is executed. However, only the first statement
+ that generated the warning for each client session is logged
+ to the <literal>mysqld</literal> error log to prevent
+ flooding the error log.
+ </para>
+ </note>
+
+ <para>
+ Starting with MySQL 5.1.20, mixed based logging is used by
+ default, but in addition to the decisions above, individual
+ engines can also enforce the logging format used when
+ information in a table is updated.
+ </para>
+
+ <para>
+ The logging formats supported by a particular engine are
+ controlled by internal flags. The table below lists the
+ logging formats supported by each of the current engines.
+ </para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="50*"/>
+ <colspec colwidth="25*"/>
+ <colspec colwidth="25*"/>
+ <thead>
+ <row>
+ <entry>Engine</entry>
+ <entry>Row-logging supported</entry>
+ <entry>Statement-logging supported</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Archive</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Blackhole</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>CSV</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Example</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Federated</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Heap</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>MyISAM</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Merge</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>NDB</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ Note that an engine can be support either or both logging
+ formats, and the logging capabilities of an individual engine
+ can be further defined as follows
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If an engine supports row-based logging, then the engine
+ is said to be <emphasis>row-logging capable
+ (RLC)</emphasis>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If an engine support statement-based logging, then the
+ engine is said to be <emphasis>statement-logging capable
+ (SLC)</emphasis>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ When determining what logging mode to use, the capabilities of
+ all the tables in the event are combined. The set of tables is
+ then marked according to these rules:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A set of tables is defined as <emphasis>row logging
+ restricted (RLR)</emphasis> if the tables are row logging
+ capable but not statement logging capable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A set of tables is defined as <emphasis>statement logging
+ restricted (SLR)</emphasis> if the tables are statement
+ logging capable but not row logging capable.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Once the determination of the possible logging formats
+ required by the statement is complete it is compared to the
+ current <literal>BINLOG_FORMAT</literal> setting. The
+ following table is used to decide how the information is
+ recorded in the binary log or, if appropriate, whether an
+ error is raised. In the table, a safe operation is defined as
+ one that is deterministic. A number of internal rules decide
+ whether the statement is deterministic or not.
+ </para>
+
+ <informaltable>
+ <tgroup cols="6">
+ <colspec colwidth="10*" colname="safe"/>
+ <colspec colwidth="25*" colname="format"/>
+ <colspec colwidth="10*" colname="RLC"/>
+ <colspec colwidth="10*" colname="SLC"/>
+ <colspec colwidth="20*" colname="error"/>
+ <colspec colwidth="25*" colname="logas"/>
+ <spanspec namest="safe" nameend="SLC" spanname="condition"/>
+ <spanspec namest="error" nameend="logas" spanname="action"/>
+ <thead>
+ <row>
+ <entry spanname="condition">Condition</entry>
+ <entry spanname="action">Action</entry>
+ </row>
+ <row>
+ <entry>Safe/unsafe</entry>
+ <entry><literal>BINLOG_FORMAT</literal></entry>
+ <entry>RLC</entry>
+ <entry>SLC</entry>
+ <entry>Error/Warning</entry>
+ <entry>Logged as</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Warning: unsafe</entry>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry>Warning: unsafe</entry>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ When a warning is produced by the determination, a standard
+ MySQL warning is produced (and is available using
+ <literal>SHOW WARNINGS</literal>). The information is also
+ written to the <command>mysqld</command> error log. Only one
+ error for each error instance per client connection is logged.
+ The log message will include the SQL statement that was
+ attempted.
+ </para>
+
+ </section>
+
+ <section id="binary-log-mysql-database">
+
+ <title>Logging Format for Changes to <literal>mysql</literal> Database Tables</title>
+
+ <para>
+ The contents of the grant tables in the
+ <literal>mysql</literal> database can be modified directly
+ (for example, with <literal>INSERT</literal> or
+ <literal>DELETE</literal>) or indirectly (for example, with
+ <literal>GRANT</literal> or <literal>CREATE USER</literal>).
+ As of MySQL 5.1.17, statements that affect
+ <literal>mysql</literal> database tables are written to the
+ binary log using the following rules:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Data manipulation statements that change data in
+ <literal>mysql</literal> database tables directly are
+ logged according to the setting of the
+ <literal>binlog_format</literal> system variable. This
+ pertains to statements such as <literal>INSERT</literal>,
+ <literal>UPDATE</literal>, <literal>DELETE</literal>,
+ <literal>REPLACE</literal>, <literal>DO</literal>,
+ <literal>LOAD DATA INFILE</literal>,
+ <literal>SELECT</literal>, and
+ <literal>TRUNCATE</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Statements that change the <literal>mysql</literal>
+ database indirectly are logged as statements regardless of
+ the value of <literal>binlog_format</literal>. This
+ pertains to statements such as <literal>GRANT</literal>,
+ <literal>REVOKE</literal>, <literal>SET
+ PASSWORD</literal>, <literal>RENAME USER</literal>,
+ <literal>CREATE</literal> (all forms except
+ <literal>CREATE TABLE ... SELECT</literal>),
+ <literal>ALTER</literal> (all forms), and
+ <literal>DROP</literal> (all forms).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ <literal>CREATE TABLE ... SELECT</literal> is a combination of
+ data definition and data manipulation. The <literal>CREATE
+ TABLE</literal> part is logged using statement format and the
+ <literal>SELECT</literal> part is logged according to the
+ value of <literal>binlog_format</literal>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="slow-query-log">
+
+ <title>The Slow Query Log</title>
+
+ <indexterm>
+ <primary>slow query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>slow query log</secondary>
+ </indexterm>
+
+ <para>
+ The slow query log consists of all SQL statements that took more
+ than <literal>long_query_time</literal> seconds to execute. The
+ time to acquire the initial table locks is not counted as
+ execution time. <command>mysqld</command> writes a statement to
+ the slow query log after it has been executed and after all
+ locks have been released, so log order might be different from
+ execution order. The minimum and default values of
+ <literal>long_query_time</literal> are 1 and 10, respectively.
+ Prior to MySQL 5.1.21, the minimum value is 1, and the value for
+ this variable must be an integer. Beginning with MySQL 5.1.21,
+ the default is 0, and a resolution of microseconds is supported
+ when logging to a file. However, the microseconds part is
+ ignored and only integer values are written when logging to
+ tables.
+ </para>
+
+ <para>
+ To enable the slow query log as of MySQL 5.1.6, start
+ <command>mysqld</command> with the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option, and optionally use <option>--log-output</option> to
+ specify the log destination (as described in
+ <xref linkend="log-tables"/>). Before 5.1.6, the slow query log
+ destination is always a file. To enable the slow query log file,
+ use the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option.
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log-slow-queries</option>, the default name is
+ <filename><replaceable>host_name</replaceable>-slow.log</filename>.
+ If a filename is given, but not as an absolute pathname, the
+ server writes the file in the data directory.
+ </para>
+
+ <para>
+ When <option>--log-slow-queries</option> is specified, the
+ <option>--slow-query-log</option> option also may be given as of
+ MySQL 5.1.12 to specify the initial slow query log state. With
+ no argument or an argument of 0, the option disables the log. If
+ omitted or given with an argument of 1, the option enables the
+ log. If <option>--log--slow-queries</option> is not given,
+ <option>--slow-query-log</option> has no effect.
+ </para>
+
+ <para>
+ The global <literal>slow_query_log</literal> and
+ <literal>slow_query_log_file</literal> system variables provide
+ runtime control over the slow query log. Set
+ <literal>slow_query_log</literal> to 0 (or
+ <literal>OFF</literal>) to disable the log or to 1 (or
+ <literal>ON</literal>) to enable it. Set
+ <literal>general_log_file</literal> to specify the name of the
+ log file. If a log file already is open, it is closed and the
+ new file is opened.
+ </para>
+
+ <para>
+ When the slow query log is enabled, output is written to any
+ destinations specified by the <option>--log-output</option>
+ option or <literal>log_output</literal> system variable. Note
+ that if the destination is <literal>NONE</literal>, no output is
+ written even if the slow query log is enabled. Setting the log
+ filename has no effect on logging if the log destination value
+ does not contain <literal>FILE</literal>.
+ </para>
+
+ <para>
+ The slow query log can be used to find queries that take a long
+ time to execute and are therefore candidates for optimization.
+ However, examining a long slow query log can become a difficult
+ task. To make this easier, you can process the slow query log
+ using the <command>mysqldumpslow</command> command to summarize
+ the queries that appear in the log. Use <command>mysqldumpslow
+ --help</command> to see the options that this command supports.
+ </para>
+
+ <para>
+ In MySQL ¤t-series;, queries that do not use indexes are
+ logged in the slow query log if the
+ <option>--log-queries-not-using-indexes</option> option is
+ specified. See <xref linkend="server-options"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ Excessive table scans are indicative of missing or poorly
+ optimized indexes. Using an advisor specifically designed for
+ the task, the MySQL Enterprise Monitor can identify such
+ problems and offer advice on resolution. For more information
+ see <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ In MySQL ¤t-series;, the
+ <option>--log-slow-admin-statements</option> server option
+ enables you to request logging of slow administrative statements
+ such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
+ TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
+ query log.
+ </para>
+
+ <para>
+ Queries handled by the query cache are not added to the slow
+ query log, nor are queries that would not benefit from the
+ presence of an index because the table has zero rows or one row.
+ </para>
+
+ </section>
+
+ <section id="log-file-maintenance">
+
+ <title>Server Log Maintenance</title>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>log</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>maintaining</primary>
+ <secondary>log files</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>maintaining</secondary>
+ </indexterm>
+
+ <para>
+ MySQL Server can create a number of different log files that
+ make it easy to see what is going on. See
+ <xref linkend="log-files"/>. However, you must clean up these
+ files regularly to ensure that the logs do not take up too much
+ disk space.
+ </para>
+
+ <para>
+ When using MySQL with logging enabled, you may want to back up
+ and remove old log files from time to time and tell MySQL to
+ start logging to new files. See <xref linkend="backup"/>.
+ </para>
+
+ <para>
+ On a Linux (Red Hat) installation, you can use the
+ <literal>mysql-log-rotate</literal> script for this. If you
+ installed MySQL from an RPM distribution, this script should
+ have been installed automatically. You should be careful with
+ this script if you are using the binary log for replication. You
+ should not remove binary logs until you are certain that their
+ contents have been processed by all slaves.
+ </para>
+
+ <para>
+ On other systems, you must install a short script yourself that
+ you start from <command>cron</command> (or its equivalent) for
+ handling log files.
+ </para>
+
+ <para>
+ For the binary log, you can set the
+ <literal>expire_logs_days</literal> system variable to expire
+ binary log files automatically after a given number of days (see
+ <xref linkend="server-system-variables"/>). If you are using
+ replication, you should set the variable no lower than the
+ maximum number of days your slaves might lag behind the master.
+ </para>
+
+ <para>
+ You can force MySQL to start using new log files by issuing a
+ <literal>FLUSH LOGS</literal> statement or executing
+ <command>mysqladmin flush-logs</command> or <command>mysqladmin
+ refresh</command>. See <xref linkend="flush"/>, and
+ <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ A log flushing operation does the following:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If general query logging (<option>--log</option>) or slow
+ query logging (<option>--log-slow-queries</option>) to a log
+ file is enabled, the server closes and reopens the general
+ query log file or slow query log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If binary logging (<option>--log-bin</option>) is used, the
+ server closes the current log file and opens a new log file
+ with the next sequence number.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the server was given an error log filename with the
+ <option>--log-error</option> option, it renames the error
+ log with the suffix <literal>-old</literal> and creates a
+ new empty error log file.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server creates a new binary log file when you flush the
+ logs. However, it just closes and reopens the general and slow
+ query log files. To cause new files to be created on Unix,
+ rename the current logs before flushing them. At flush time, the
+ server will open new logs with the original names. For example,
+ if the general and slow query logs are named
+ <filename>mysql.log</filename> and
+ <filename>mysql-slow.log</filename>, you can use a series of
+ commands like this:
+ </para>
+
+<programlisting>
+shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
+shell> <userinput>mv mysql.log mysql.old</userinput>
+shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+</programlisting>
+
+ <para>
+ At this point, you can make a backup of
+ <filename>mysql.old</filename> and
+ <filename>mysql-slow.log</filename> and then remove them from
+ disk.
+ </para>
+
+ <para>
+ On Windows, you cannot rename log files while the server has
+ them open. You must stop the server and rename them, and then
+ restart the server to create new logs.
+ </para>
+
+ <para>
+ As of MySQL 5.1.2, you can disable the general query log or slow
+ query log at runtime:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'OFF';
+SET GLOBAL slow_query_log = 'OFF';
+</programlisting>
+
+ <para>
+ With the logs disabled, rename the log files externally; for
+ example, from the command line. Then enable the logs again:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'ON';
+SET GLOBAL slow_query_log = 'ON';
+</programlisting>
+
+ <para>
+ This method works on any platform and does not require a server
+ restart.
+ </para>
+
+ </section>
+
+ </section>
+
<section id="security">
<title>General Security Issues</title>
@@ -21934,2441 +24369,6 @@
</section>
- <section id="log-files">
-
- <title>MySQL Server Logs</title>
-
- <indexterm>
- <primary>log files</primary>
- </indexterm>
-
- <para>
- MySQL has several different logs that can help you find out what
- is going on inside <command>mysqld</command>:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Log Type</emphasis></entry>
- <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
- </row>
- <row>
- <entry>The error log</entry>
- <entry>Problems encountered starting, running, or stopping
- <command>mysqld</command></entry>
- </row>
- <row>
- <entry>The general query log</entry>
- <entry>Established client connections and statements received from clients</entry>
- </row>
- <row>
- <entry>The binary log</entry>
- <entry>All statements that change data (also used for replication)</entry>
- </row>
- <row>
- <entry>The slow query log</entry>
- <entry>All queries that took more than <literal>long_query_time</literal>
- seconds to execute or didn't use indexes</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- By default, all log files are created in the
- <command>mysqld</command> data directory. You can force
- <command>mysqld</command> to close and reopen the log files (or in
- some cases switch to a new log) by flushing the logs. Log flushing
- occurs when you issue a <literal>FLUSH LOGS</literal> statement or
- execute <command>mysqladmin flush-logs</command> or
- <command>mysqladmin refresh</command>. See
- <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- If you are using MySQL replication capabilities, slave replication
- servers maintain additional log files called relay logs.
- <xref linkend="replication"/>, discusses relay log contents and
- configuration.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The MySQL Enterprise Monitor provides a number of advisors
- specifically related to the various log files. For more
- information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- As of MySQL 5.1.6, the server can write general query and slow
- query entries to log tables, log files, or both. For details, see
- <xref linkend="log-tables"/>.
- </para>
-
- <para>
- As of MySQL 5.1.12, additional runtime control of the general
- query and slow query logs is available: You can enable or disable
- logging, or change the name of the log file. See
- <xref linkend="query-log"/>, and <xref linkend="slow-query-log"/>.
- </para>
-
- <section id="log-tables">
-
- <title>Selecting General Query and Slow Query Log Output Destinations</title>
-
- <para>
- As of MySQL 5.1.6, the server provides flexible control over the
- destination for log output. Log entries can be written to log
- files to the <literal>general_log</literal> and
- <literal>slow_log</literal> tables in the
- <literal>mysql</literal> database. If logging is enabled, either
- or both destinations can be selected. (Before MySQL 5.1.6, the
- server uses only log files as the destination for general query
- log and slow query log entries, if those logs are enabled.)
- </para>
-
- <note>
- <para>
- For new installations of MySQL 5.1.6 or higher, the log tables
- are created during the installation procedure along with the
- other system tables. If you upgrade MySQL from a release older
- than 5.1.6 to MySQL 5.1.6 or higher, you must upgrade the
- system tables after upgrading to make sure that the log tables
- exist. See <xref linkend="mysql-upgrade"/>.
- </para>
- </note>
-
- <para>
- Currently, logging to tables incurs significantly more server
- overhead than logging to files. If you enable the general log or
- slow query log and require highest performance, you should log
- to files and not to tables.
- </para>
-
- <para>
- The <option>--log-output</option> option specifies the
- destination for log output, if logging is enabled, but the
- option does not in itself enable the logs. The syntax for this
- option is
- <option>--log-output[=<replaceable>value</replaceable>,...]</option>:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If <option>--log-output</option> is given with a value, the
- value can be a comma-separated list of one or more of the
- words <literal>TABLE</literal> (log to tables),
- <literal>FILE</literal> (log to files), or
- <literal>NONE</literal> (do not log to tables or files).
- <literal>NONE</literal>, if present, takes precedence over
- any other specifiers.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <option>--log-output</option> is omitted or given without
- a value, the effect is the same as
- <option>--log-output=FILE</option>. That is, the file
- destination is selected. (For MySQL 5.1.6 through 5.1.20,
- the default is the table destination.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <option>--log-output</option> option also sets the value
- of the global <literal>log_output</literal> system variable,
- which can be modified at runtime to change the logging
- destination for the server while it executes.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The
- <option>--log[=<replaceable>file_name</replaceable>]</option>
- option, if given, enables logging to the general query log for
- the selected log destinations. Similarly, the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option, if given, enables logging to the slow query log for the
- selected destinations. If you specify either option, the server
- opens the corresponding log file and writes startup messages to
- it. However, logging of queries to the file does not occur
- unless the <literal>FILE</literal> log destination is selected.
- </para>
-
- <para>
- Examples:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- To write general query log entries to the log table and the
- log file, use <option>--log-output=TABLE,FILE</option> to
- select both log destinations and the <option>--log</option>
- option to enable the general query log.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To write general and slow query log entries only to the log
- tables, use <option>--log-output=TABLE</option> to select
- tables as the log destination and the <option>--log</option>
- and <option>--log-slow-queries</option> options to enable
- both logs.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To write slow query log entries only to the log file, use
- <option>--log-output=FILE</option> to select files as the
- log destination and the <option>--log-slow-queries</option>
- option to enable the slow query log. (In this case, because
- the default log destination is <literal>FILE</literal>, you
- could omit the <option>--log-output</option> option.)
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Several system variables are associated with log tables and
- files:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- The global <literal>general_log</literal> and
- <literal>slow_query_log</literal> variables indicate whether
- the general query log and slow query log are enabled
- (<literal>ON</literal>) or disabled
- (<literal>OFF</literal>). You can set these variables at
- runtime to control whether the logs are enabled.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The global <literal>general_log_file</literal> and
- <literal>slow_query_log_file</literal> variables indicate
- the names of the general query log and slow query log files.
- You can set these variables at runtime to change the names
- of the log files. (If the <option>--log</option> and
- <literal>--log-slow-queries</literal> options were not
- given, the variable values are set to the default log
- filenames.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- The session <literal>sql_log_off</literal> variable can be
- set to <literal>ON</literal> or <literal>OFF</literal> to
- disable or enable general query logging for the current
- connection.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The use of tables for log output offers the following benefits:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Log entries have a standard format. To display the current
- structure of the log tables, use these statements:
- </para>
-
-<programlisting>
-SHOW CREATE TABLE mysql.general_log;
-SHOW CREATE TABLE mysql.slow_log;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- Log contents are accessible via SQL statements. This enables
- the use of queries that select only those log entries that
- satisfy specific criteria. For example, to select log
- contents associated with a particular client (which can be
- useful for identifying problematic queries from that
- client), it is easier to do this using a log table than a
- log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Logs are accessible remotely through any client that can
- connect to the server and issue queries (if the client has
- the appropriate log table privileges). It's not necessary to
- log in to the server host and directly access the
- filesystem.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The log table implementation has the following characteristics:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- In general, the primary purpose of log tables is to provide
- an interface for users to observe the runtime execution of
- the server, not to interfere with its runtime execution.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>CREATE TABLE</literal>, <literal>ALTER
- TABLE</literal>, and <literal>DROP TABLE</literal> are valid
- operations on a log table. For <literal>ALTER
- TABLE</literal> and <literal>DROP TABLE</literal>, the log
- table cannot be in use and must be disabled, as described
- later.
- </para>
- </listitem>
-
- <listitem>
- <para>
- By default, the log tables use the <literal>CSV</literal>
- storage engine that writes data in comma-separated values
- format. For users who have access to the
- <filename>.CSV</filename> files that contain log table data,
- the files are easy to import into other programs such as
- spreadsheets that can process CSV input.
- </para>
-
- <para>
- Beginning with MySQL 5.1.12, the log tables can be altered
- to use the <literal>MyISAM</literal> storage engine. You
- cannot use <literal>ALTER TABLE</literal> to alter a log
- table that is in use. The log must be disabled first. No
- engines other than <literal>CSV</literal> or
- <literal>MyISAM</literal> are legal for the log tables.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To disable logging so that you can alter (or drop) a log
- table, you can use the following strategy. The example uses
- the general query log; the procedure for the slow query log
- is similar but uses the <literal>slow_log</literal> table
- and <literal>slow_query_log</literal> system variable.
- </para>
-
-<programlisting>
-SET @old_log_state = @@global.general_log;
-SET GLOBAL general_log = 'OFF';
-ALTER TABLE mysql.general_log ENGINE = MyISAM;
-SET GLOBAL general_log = @old_log_state;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- <literal>TRUNCATE TABLE</literal> is a valid operation on a
- log table. It can be used to expire log entries.
- </para>
- </listitem>
-
- <listitem>
- <para>
- As of MySQL 5.1.13, <literal>RENAME TABLE</literal> is a
- valid operation on a log table. You can atomically rename a
- log table (to perform log rotation, for example) using the
- following strategy:
- </para>
-
-<programlisting>
-USE mysql;
-CREATE TABLE IF NOT EXISTS general_log2 LIKE general_log;
-RENAME TABLE general_log TO general_log_backup, general_log2 TO general_log;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- <literal>LOCK TABLES</literal> cannot be used on a log
- table.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>INSERT</literal>, <literal>DELETE</literal>, and
- <literal>UPDATE</literal> cannot be used on a log table.
- These operations are allowed only internally to the server
- itself.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The global read lock and the state of the global
- <literal>read_only</literal> system variable have no effect
- on log tables. The server can always write to the log
- tables.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Entries written to the log tables are not written to the
- binary log and thus are not replicated to slave servers.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To flush the log tables or log files, use <literal>FLUSH
- TABLES</literal> or <literal>FLUSH LOGS</literal>,
- respectively. (From MySQL 5.1.12 to 5.1.20, <literal>FLUSH
- TABLES</literal> ignores log tables and <literal>FLUSH
- LOGS</literal> flushes both the log tables and files.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- It is not recommended to partition log tables, and doing so
- is not allowed beginning with MySQL 5.1.20.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="error-log">
-
- <title>The Error Log</title>
-
- <para>
- The error log contains information indicating when
- <command>mysqld</command> was started and stopped and also any
- critical errors that occur while the server is running. If
- <command>mysqld</command> notices a table that needs to be
- automatically checked or repaired, it writes a message to the
- error log.
- </para>
-
- <para>
- On some operating systems, the error log contains a stack trace
- if <command>mysqld</command> dies. The trace can be used to
- determine where <command>mysqld</command> died. See
- <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
- Internals: Porting</ulink>.
- </para>
-
- <para>
- You can specify where <command>mysqld</command> writes the error
- log with the
- <option>--log-error[=<replaceable>file_name</replaceable>]</option>
- option. If no <replaceable>file_name</replaceable> value is
- given, <command>mysqld</command> uses the name
- <filename><replaceable>host_name</replaceable>.err</filename> by
- default and writes the file in the data directory. If you
- execute <literal>FLUSH LOGS</literal>, the error log is renamed
- with the suffix <literal>-old</literal> and
- <command>mysqld</command> creates a new empty log file. (No
- renaming occurs if the <option>--log-error</option> option was
- not given to <command>mysqld</command>.)
- </para>
-
- <para>
- If you do not specify <option>--log-error</option>, or (on
- Windows) if you use the <option>--console</option> option,
- errors are written to <literal>stderr</literal>, the standard
- error output. Usually this is your terminal.
- </para>
-
- <para>
- On Windows, error output is always written to the
- <literal>.err</literal> file if <option>--console</option> is
- not given.
- </para>
-
- <para>
- The <option>--log-warnings</option> option or
- <literal>log_warnings</literal> system variable can be used to
- control warning logging to the error log. The default value is
- enabled (1). Warning logging can be disabled using a value of 0.
- If the value is greater than 1, aborted connections are written
- to the error log. See <xref linkend="communication-errors"/>.
- </para>
-
- <para>
- If you use <command>mysqld_safe</command> to start
- <command>mysqld</command>, <command>mysqld_safe</command>
- arranges for <command>mysqld</command> to write error messages
- to a log file or (as of MySQL 5.1.20) to
- <literal>syslog</literal>:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Before 5.1.20, <command>mysqld_safe</command> behavior is to
- log to a file, using the default error log file if the
- <option>--log-error</option> option is not given to
- <command>mysqld_safe</command>. Otherwise,
- <command>mysqld_safe</command> uses the filename specified
- via
- <option>--log-error=<replaceable>file_name</replaceable></option>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- From 5.1.20 on, <command>mysqld_safe</command> has two
- additional error-logging options, <option>--syslog</option>
- and <option>--skip-syslog</option>.
- </para>
-
- <para>
- In 5.1.21 and up, the default with no logging options is
- <option>--skip-syslog</option>, which is compatible with the
- default behavior of writing an error log file for releases
- prior to 5.1.20. To explicitly specify use of an error log
- file, specify
- <option>--log-error=<replaceable>file_name</replaceable></option>
- to <command>mysqld_safe</command>, and
- <command>mysqld_safe</command> will arrange for
- <command>mysqld</command> to write messages to a log file.
- To use <literal>syslog</literal> instead, specify the
- <option>--syslog</option> option.
- </para>
-
- <para>
- <emphasis role="bold">In 5.1.20 <emphasis>only</emphasis>,
- the following conditions apply</emphasis>: 1) The default is
- to use <literal>syslog</literal>, which is not compatible
- with releases prior to 5.1.20. 2) Logging to
- <literal>syslog</literal> may fail to operate correctly in
- some cases, so we recommend that you use
- <option>--skip-syslog</option> or
- <option>--log-error</option>.
- </para>
-
- <para>
- For logging to <literal>syslog</literal>, messages from
- <command>mysqld_safe</command> and <command>mysqld</command>
- are written with a tag of <literal>mysqld_safe</literal> and
- <literal>mysqld</literal>, respectively. As of MySQL 5.1.21,
- to specify a suffix for the tag, use
- <option>--syslog-tag=<replaceable>tag</replaceable></option>,
- which modifies the tags to be
- <literal>mysqld_safe-<replaceable>tag</replaceable></literal>
- and
- <literal>mysqld-<replaceable>tag</replaceable></literal>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- If you specify <option>--log-error</option> in an option file in
- a section that <command>mysqld</command> reads,
- <command>mysqld_safe</command> also will find and use the
- option.
- </para>
-
- <para>
- If <command>mysqld_safe</command> is used to start
- <command>mysqld</command> and <command>mysqld</command> dies
- unexpectedly, <command>mysqld_safe</command> notices that it
- needs to restart <command>mysqld</command> and writes a
- <literal>restarted mysqld</literal> message to the error log.
- </para>
-
- </section>
-
- <section id="query-log">
-
- <title>The General Query Log</title>
-
- <indexterm>
- <primary>general query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>general query log</secondary>
- </indexterm>
-
- <para>
- The general query log is a general record of what
- <command>mysqld</command> is doing. The server writes
- information to this log when clients connect or disconnect, and
- it logs each SQL statement received from clients. The general
- query log can be very useful when you suspect an error in a
- client and want to know exactly what the client sent to
- <command>mysqld</command>.
- </para>
-
- <para>
- <command>mysqld</command> writes statements to the query log in
- the order that it receives them, which might differ from the
- order in which they are executed. This logging order contrasts
- to the binary log, for which statements are written after they
- are executed but before any locks are released. (Also, the query
- log contains all statements, whereas the binary log does not
- contain statements that only select data.)
- </para>
-
- <para>
- To enable the general query log as of MySQL 5.1.6, start
- <command>mysqld</command> with the
- <option>--log[=<replaceable>file_name</replaceable>]</option> or
- <option>-l [<replaceable>file_name</replaceable>]</option>
- option, and optionally use <option>--log-output</option> to
- specify the log destination (as described in
- <xref linkend="log-tables"/>). Before 5.1.6, the general query
- log destination is always a file. To enable the general query
- log file, use the
- <option>--log[=<replaceable>file_name</replaceable>]</option> or
- <option>-l [<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log</option> or <option>-l</option>, the default name
- is <filename><replaceable>host_name</replaceable>.log</filename>
- in the data directory. If a filename is given, but not as an
- absolute pathname, the server writes the file in the data
- directory.
- </para>
-
- <para>
- When <option>--log</option> or <option>-l</option> is specified,
- the <option>--general-log</option> option also may be given as
- of MySQL 5.1.12 to specify the initial general query log state.
- With no argument or an argument of 0, the option disables the
- log. If omitted or given with an argument of 1, the option
- enables the log. If <option>--log</option> or
- <option>-l</option> is not specified,
- <option>--general-log</option> has no effect.
- </para>
-
- <para>
- The global <literal>general_log</literal> and
- <literal>general_log_file</literal> system variables provide
- runtime control over the general query log. Set
- <literal>general_log</literal> to 0 (or <literal>OFF</literal>)
- to disable the log or to 1 (or <literal>ON</literal>) to enable
- it. Set <literal>general_log_file</literal> to specify the name
- of the log file. If a log file already is open, it is closed and
- the new file is opened.
- </para>
-
- <para>
- When the general query log is enabled, output is written to any
- destinations specified by the <option>--log-output</option>
- option or <literal>log_output</literal> system variable. Note
- that if the destination is <literal>NONE</literal>, no output is
- written even if the general log is enabled. Setting the log
- filename has no effect on logging if the log destination value
- does not contain <literal>FILE</literal>.
- </para>
-
- <para>
- Server restarts and log flushing do not cause a new general
- query log file to be generated (although flushing closes and
- reopens it). On Unix, you can rename the file and create a new
- one by using the following commands:
- </para>
-
-<programlisting>
-shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
-shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
-</programlisting>
-
- <para>
- On Windows, you cannot rename the log file while the server has
- it open. You must stop the server and rename the file, and then
- restart the server to create a new log file.
- </para>
-
- <para>
- As of MySQL 5.1.12, you can disable the general query log at
- runtime:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'OFF';
-</programlisting>
-
- <para>
- With the log disabled, rename the log file externally; for
- example, from the command line. Then enable the log again:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'ON';
-</programlisting>
-
- <para>
- This method works on any platform and does not require a server
- restart.
- </para>
-
- <para>
- The session <literal>sql_log_off</literal> variable can be set
- to <literal>ON</literal> or <literal>OFF</literal> to disable or
- enable general query logging for the current connection.
- </para>
-
- </section>
-
- <section id="binary-log">
-
- <title>The Binary Log</title>
-
- <indexterm>
- <primary>binary log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>binary log</secondary>
- </indexterm>
-
- <para>
- The binary log contains all statements that update data or
- potentially could have updated it (for example, a
- <literal>DELETE</literal> which matched no rows). Statements are
- stored in the form of <quote>events</quote> that describe the
- modifications. The binary log also contains information about
- how long each statement took that updated data.
- </para>
-
- <para>
- The binary log is not used for statements such as
- <literal>SELECT</literal> or <literal>SHOW</literal> that do not
- modify data. If you want to log all statements (for example, to
- identify a problem query), use the general query log. See
- <xref linkend="query-log"/>.
- </para>
-
- <para>
- The format of the events recorded in the binary log is dependent
- on the binary logging format. Three format types are supported,
- row-based logging, statement-based logging and mixed-base
- logging. The binary logging format used depends on the MySQL
- version. For more information on logging formats, see
- <xref linkend="binary-log-formats"/>.
- </para>
-
- <para>
- The primary purpose of the binary log is to be able to update
- databases during a restore operation as fully as possible,
- because the binary log contains all updates done after a backup
- was made. The binary log is also used on master replication
- servers as a record of the statements to be sent to slave
- servers. See <xref linkend="replication"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The binary log can also be used to track significant DDL
- events. Analyzing the binary log in this way is an integral
- part of the MySQL Enterprise Monitor. For more information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- Running the server with the binary log enabled makes performance
- about 1% slower. However, the benefits of the binary log for
- restore operations and in allowing you to set up replication
- generally outweigh this minor performance decrement.
- </para>
-
- <para>
- When started with the
- <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
- option, <command>mysqld</command> writes a log file containing
- all SQL statements that update data (both DDL and DML
- statements). If no <replaceable>base_name</replaceable> value is
- given, the default name is the value of the
- <literal>pid-file</literal> option (which by default is the name
- of host machine) followed by <literal>-bin</literal>. If the
- basename is given, but not as an absolute pathname, the server
- writes the file in the data directory. It is recommended that
- you specify a basename; see <xref linkend="open-bugs"/>, for the
- reason.
- </para>
-
- <para>
- If you supply an extension in the log name (for example,
- <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
- the extension is silently removed and ignored.
- </para>
-
- <para>
- <command>mysqld</command> appends a numeric extension to the
- binary log basename. The number increases each time the server
- creates a new log file, thus creating an ordered series of
- files. The server creates a new binary log file each time it
- starts or flushes the logs. The server also creates a new binary
- log file automatically when the current log's size reaches
- <literal>max_binlog_size</literal>. A binary log file may become
- larger than <literal>max_binlog_size</literal> if you are using
- large transactions because a transaction is written to the file
- in one piece, never split between files.
- </para>
-
- <para>
- To keep track of which binary log files have been used,
- <command>mysqld</command> also creates a binary log index file
- that contains the names of all used binary log files. By default
- this has the same basename as the binary log file, with the
- extension <literal>'.index'</literal>. You can change the name
- of the binary log index file with the
- <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
- option. You should not manually edit this file while
- <command>mysqld</command> is running; doing so would confuse
- <command>mysqld</command>.
- </para>
-
- <para>
- Replication slave servers by default do not write to their own
- binary log any statements that are received from the replication
- master. To cause these statements to be logged, start the slave
- with the <option>--log-slave-updates</option> option.
- </para>
-
- <para>
- Writes to the binary log file and binary log index file are
- handled in the same way as writes to <literal>MyISAM</literal>
- tables. See <xref linkend="full-disk"/>.
- </para>
-
- <para>
- You can delete all binary log files with the <literal>RESET
- MASTER</literal> statement, or a subset of them with
- <literal>PURGE MASTER LOGS</literal>. See
- <xref linkend="reset"/>, and
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- The binary log format has some known limitations that can affect
- recovery from backups. See
- <xref linkend="replication-features"/>.
- </para>
-
- <para>
- Binary logging for stored routines and triggers is done as
- described in <xref linkend="stored-procedure-logging"/>.
- </para>
-
- <para>
- You can use the following options to <command>mysqld</command>
- to affect what is logged to the binary log. See also the
- discussion that follows this option list.
- </para>
-
- <para>
- If you are using replication, the options described here affect
- which statements are sent by a master server to its slaves.
- There are also options for slave servers that control which
- statements received from the master to execute or ignore. For
- details, see <xref linkend="replication-options"/>.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para id="option_mysqld_binlog-do-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-do-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-do-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to restrict binary logging to updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). All other databases
- that are not explicitly mentioned are ignored. If you use
- this option, you should ensure that you do updates only in
- the default database.
- </para>
-
- <para>
- There is an exception to this for <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. The server uses
- the database named in the statement (not the default
- database) to decide whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-do-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement is
- <emphasis>not</emphasis> written into the binary log.
- </para>
-
- <para>
- To log multiple databases, use multiple options, specifying
- the option once for each database.
- </para>
- </listitem>
-
- <listitem>
- <para id="option_mysqld_binlog-ignore-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-ignore-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-ignore-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to suppress binary logging of updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). If you use this option,
- you should ensure that you do updates only in the default
- database.
- </para>
-
- <para>
- As with the <option>--binlog-do-db</option> option, there is
- an exception for the <literal>CREATE DATABASE</literal>,
- <literal>ALTER DATABASE</literal>, and <literal>DROP
- DATABASE</literal> statements. The server uses the database
- named in the statement (not the default database) to decide
- whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-ignore-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement
- <emphasis>is</emphasis> written into the binary log.
- </para>
-
- <para>
- To ignore multiple databases, use multiple options,
- specifying the option once for each database.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server evaluates the options for logging or ignoring updates
- to the binary log according to the following rules. As described
- previously, there is an exception for the <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. In those cases, the
- database being <emphasis>created, altered, or dropped</emphasis>
- replaces the default database in the following rules:
- </para>
-
- <orderedlist>
-
- <listitem>
- <para>
- Are there <option>--binlog-do-db</option> or
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Write the statement to the binary log and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some rules (<option>--binlog-do-db</option>,
- <option>--binlog-ignore-db</option>, or both). Is there a
- default database (has any database been selected by
- <literal>USE</literal>?)?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement, and
- exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There is a default database. Are there some
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Does the default database match any of the
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Write the statement and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement,
- and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- No: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some <option>--binlog-ignore-db</option> rules.
- Does the default database match any of the
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Do not write the statement, and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Write the query and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- </orderedlist>
-
- <para>
- For example, a slave running with only
- <option>--binlog-do-db=sales</option> does not write to the
- binary log any statement for which the default database is
- different from <literal>sales</literal> (in other words,
- <option>--binlog-do-db</option> can sometimes mean <quote>ignore
- other databases</quote>).
- </para>
-
- <para>
- If you are using replication, you should not delete old binary
- log files until you are sure that no slave still needs to use
- them. For example, if your slaves never run more than three days
- behind, once a day you can execute <command>mysqladmin
- flush-logs</command> on the master and then remove any logs that
- are more than three days old. You can remove the files manually,
- but it is preferable to use <literal>PURGE MASTER
- LOGS</literal>, which also safely updates the binary log index
- file for you (and which can take a date argument). See
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- A client that has the <literal>SUPER</literal> privilege can
- disable binary logging of its own statements by using a
- <literal>SET SQL_LOG_BIN=0</literal> statement. See
- <xref linkend="set-option"/>.
- </para>
-
- <para>
- You can display the contents of binary log files with the
- <command>mysqlbinlog</command> utility. This can be useful when
- you want to reprocess statements in the log. For example, you
- can update a MySQL server from the binary log as follows:
- </para>
-
-<programlisting>
-shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
-</programlisting>
-
- <para>
- See <xref linkend="mysqlbinlog"/>, for more information on the
- <command>mysqlbinlog</command> utility and how to use it.
- <command>mysqlbinlog</command> also can be used with relay log
- files because they are written using the same format as binary
- log files.
- </para>
-
- <para>
- Binary logging is done immediately after a statement completes
- but before any locks are released or any commit is done. This
- ensures that the log is logged in execution order.
- </para>
-
- <para>
- Updates to non-transactional tables are stored in the binary log
- immediately after execution. Within an uncommitted transaction,
- all updates (<literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>INSERT</literal>) that
- change transactional tables such as <literal>InnoDB</literal>
- tables are cached until a <literal>COMMIT</literal> statement is
- received by the server. At that point, <command>mysqld</command>
- writes the entire transaction to the binary log before the
- <literal>COMMIT</literal> is executed. When the thread that
- handles the transaction starts, it allocates a buffer of
- <literal>binlog_cache_size</literal> to buffer statements. If a
- statement is bigger than this, the thread opens a temporary file
- to store the transaction. The temporary file is deleted when the
- thread ends.
- </para>
-
- <para>
- Modifications to non-transactional tables cannot be rolled back.
- If a transaction that is rolled back includes modifications to
- non-transactional tables, the entire transaction is logged with
- a <literal>ROLLBACK</literal> statement at the end to ensure
- that the modifications to those tables are replicated.
- </para>
-
- <para>
- The <literal>Binlog_cache_use</literal> status variable shows
- the number of transactions that used this buffer (and possibly a
- temporary file) for storing statements. The
- <literal>Binlog_cache_disk_use</literal> status variable shows
- how many of those transactions actually had to use a temporary
- file. These two variables can be used for tuning
- <literal>binlog_cache_size</literal> to a large enough value
- that avoids the use of temporary files.
- </para>
-
- <para>
- The <literal>max_binlog_cache_size</literal> system variable
- (default 4GB, which is also the maximum) can be used to restrict
- the total size used to cache a multiple-statement transaction.
- If a transaction is larger than this many bytes, it fails and
- rolls back. The minimum value is 4096.
- </para>
-
- <para>
- If you are using the binary log and row based logging,
- concurrent inserts are converted to normal inserts for
- <literal>CREATE ... SELECT</literal> or <literal>INSERT ...
- SELECT</literal> statement. This is done to ensure that you can
- re-create an exact copy of your tables by applying the log
- during a backup operation. If you are using statement based
- logging then the original statement is written to the log.
- </para>
-
- <para>
- Note that the binary log format is different in MySQL
- ¤t-series; from previous versions of MySQL, due to
- enhancements in replication. See
- <xref linkend="replication-compatibility"/>.
- </para>
-
- <para>
- By default, the binary log is not synchronized to disk at each
- write. So if the operating system or machine (not only the MySQL
- server) crashes, there is a chance that the last statements of
- the binary log are lost. To prevent this, you can make the
- binary log be synchronized to disk after every
- <replaceable>N</replaceable> writes to the binary log, with the
- <literal>sync_binlog</literal> system variable. See
- <xref linkend="server-system-variables"/>. 1 is the safest value
- for <literal>sync_binlog</literal>, but also the slowest. Even
- with <literal>sync_binlog</literal> set to 1, there is still the
- chance of an inconsistency between the table content and binary
- log content in case of a crash. For example, if you are using
- <literal>InnoDB</literal> tables and the MySQL server processes
- a <literal>COMMIT</literal> statement, it writes the whole
- transaction to the binary log and then commits this transaction
- into <literal>InnoDB</literal>. If the server crashes between
- those two operations, the transaction is rolled back by
- <literal>InnoDB</literal> at restart but still exists in the
- binary log. To resolve this, you should set
- <option>--innodb_support_xa</option> to 1. Although this option
- is related to the support of XA transactions in InnoDB, it also
- ensures that the binary log and InnoDB data files are
- synchronized.
- </para>
-
- <para>
- For this option to provide a greater degree of safety, the MySQL
- server should also be configured to synchronize the binary log
- and the <literal>InnoDB</literal> logs to disk at every
- transaction. The <literal>InnoDB</literal> logs are synchronized
- by default, and <literal>sync_binlog=1</literal> can be used to
- synchronize the binary log. The effect of this option is that at
- restart after a crash, after doing a rollback of transactions,
- the MySQL server cuts rolled back <literal>InnoDB</literal>
- transactions from the binary log. This ensures that the binary
- log reflects the exact data of <literal>InnoDB</literal> tables,
- and so, that the slave remains in synchrony with the master (not
- receiving a statement which has been rolled back).
- </para>
-
- <para>
- If the MySQL server discovers at crash recovery that the binary
- log is shorter than it should have been, it lacks at least one
- successfully committed <literal>InnoDB</literal> transaction.
- This should not happen if <literal>sync_binlog=1</literal> and
- the disk/filesystem do an actual sync when they are requested to
- (some don't), so the server prints an error message <literal>The
- binary log <name> is shorter than its expected
- size</literal>. In this case, this binary log is not correct and
- replication should be restarted from a fresh snapshot of the
- master's data.
- </para>
-
- <para>
- For MySQL 5.1.20 and later (and MySQL 5.0.46 for backwards
- compatibility), the following session variables are written to
- the binary log and honoured by the replication slave when
- parsing the binary log:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>FOREIGN_KEY_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>UNIQUE_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>SQL_AUTO_IS_NULL</literal>
- </para>
- </listitem>
-
- </itemizedlist>
-
- <section id="binary-log-formats">
-
- <title>Binary Logging Formats</title>
-
- <para>
- A number of different logging formats are used to record
- information in the binary log. The exact format employed
- depends on the version of MySQL being used. There are three
- logging formats:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Replication capabilities in MySQL originally were based on
- propagation of SQL statements from master to slave. This
- is called <emphasis>statement-based logging</emphasis>
- (SBL). SBL is identified internally using
- <literal>STATMENT</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- In <emphasis>row-based logging</emphasis> (RBL), the
- master writes events to the binary log that indicate how
- individual table rows are affected. Support for RBL was
- added in MySQL 5.1.5. RBL is identified internally using
- <literal>ROW</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- As of MySQL 5.1.8, a third option is available:
- <emphasis>mixed-based logging</emphasis> (MBL). With MBL,
- SBL is used by default, but automatically switches to RBL
- in particular cases as described below. From MySQL 5.1.8,
- MBL is the default mode. MBL is identified internally
- using <literal>MIXED</literal>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Starting with MySQL 5.1.20, MBL is the default but storage
- engine being used can also set or limit the logging format
- according to the capabilities of the storage engine. This
- helps to eliminate issues when logging, and more specifically
- replicating, certain statements between the master and slave
- using the different engines.
- </para>
-
- </section>
-
- <section id="binary-log-setting">
-
- <title>Setting The Binary Log Format</title>
-
- <para>
- The default binary logging format depends on the version of
- MySQL you are using:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- For MySQL 5.1.11 and earlier, statement-based logging is
- used by default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- For MySQL 5.1.12 and later, mixed-based logging is used by
- default.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- You can force the default replication format by specifying the
- format type to the
- <option>--binlog-format=<replaceable>type</replaceable></option>
- option. When set, all replication slaves connecting to the
- server will read the events according to this setting. The
- supported options are:
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>ROW</literal> — sets row-based
- replication as the default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>STATEMENT</literal> — sets
- statement-based replication as the default. This is the
- default for MySQL 5.1.11 and earlier.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>MIXED</literal> — sets mixed-based
- replication as the default. This is the default for
- MySQL 5.1.12 and later.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- The logging format also can be switched at runtime. To specify
- the format globally for all clients, set the global value of
- the <literal>binlog_format</literal> system variable. (To
- change a global variable you need the <literal>SUPER</literal>
- privilege.)
- </para>
-
- <para>
- To switch to statement-based format, use either of these
- statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'STATEMENT';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 1;</userinput>
-</programlisting>
-
- <para>
- To switch to row-based format, use either of these statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'ROW';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 2;</userinput>
-</programlisting>
-
- <para>
- To switch to mixed format, use either of these statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'MIXED';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 3;</userinput>
-</programlisting>
-
- <para>
- Individual clients can control the logging format for their
- own statements by setting the session value of
- <literal>binlog_format</literal>. For example:
- </para>
-
-<programlisting>
-mysql> <userinput>SET SESSION binlog_format = 'STATEMENT';</userinput>
-mysql> <userinput>SET SESSION binlog_format = 'ROW';</userinput>
-mysql> <userinput>SET SESSION binlog_format = 'MIXED';</userinput>
-</programlisting>
-
- <para>
- In addition to switching the logging format manually, a slave
- server may switch the format
- <emphasis>automatically</emphasis>. This happens when the
- server is running in either <literal>STATEMENT</literal> or
- <literal>MIXED</literal> format and encounters a row in the
- binary log that is written in <literal>ROW</literal> logging
- format. In that case, the slave switches to row-based
- replication temporarily for that event, and switches back to
- the previous format afterwards.
- </para>
-
- <para>
- There are two reasons why you might want to set replication
- logging on a per-connection basis:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- A thread that makes many small changes to the database
- might want to use row-based logging. A thread that
- performs updates that match many rows in the
- <literal>WHERE</literal> clause might want to use
- statement-based logging because it will be more efficient
- to log a few statements than many rows.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Some statements require a lot of execution time on the
- master, but result in just a few rows being modified. It
- might therefore be beneficial to replicate them using
- row-based logging.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- There are exceptions when you cannot switch the replication
- format at runtime:
-
- <itemizedlist>
-
- <listitem>
- <para>
- From within a stored function or a trigger.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <literal>NDB</literal> is enabled.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the session is currently in row-based replication
- mode and has open temporary tables.
- </para>
- </listitem>
-
- </itemizedlist>
-
- Trying to switch the format in those cases results in an
- error.
- </para>
-
- <para>
- Switching the replication format at runtime is not recommended
- when any <emphasis>temporary tables</emphasis> exist, because
- temporary tables are logged only when using statement-based
- replication, whereas with row-based replication they are not
- logged. With mixed replication, temporary tables are usually
- logged; exceptions happen with user-defined functions (UDF)
- and with the <function>UUID()</function> function.
- </para>
-
- <para>
- With the binlog format set to <literal>ROW</literal>, many
- changes are written to the binary log using the row-based
- format. Some changes, however, still use the statement-based
- format. Examples include all DDL (data definition language)
- statements such as <literal>CREATE TABLE</literal>,
- <literal>ALTER TABLE</literal>, or <literal>DROP
- TABLE</literal>.
- </para>
-
- <para>
- The <option>--binlog-row-event-max-size</option> option is
- available for servers that are capable of row-based
- replication. Rows are stored into the binary log in chunks
- having a size in bytes not exceeding the value of this option.
- The value must be a multiple of 256. The default value is
- 1024.
- </para>
-
- <warning>
- <para>
- When using <emphasis>statement-based logging</emphasis> in a
- replication scenario, it is possible for the data on the
- master and slave to become different if a statement is
- designed in such a way that the data modification is
- <firstterm>non-deterministic</firstterm>; that is, it is
- left to the will of the query optimizer. In general, this is
- not a good practice even outside of replication. For a
- detailed explanation of this issue, see
- <xref linkend="open-bugs"/>.
- </para>
- </warning>
-
- </section>
-
- <section id="binary-log-mixed">
-
- <title>Mixed Binary Logging (MBL) Format</title>
-
- <para>
- When running in <literal>MIXED</literal> mode, automatic
- switching from statement-based to row-based replication takes
- place under the following conditions:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- When a DML statement updates an <literal>NDB</literal>
- table
- </para>
- </listitem>
-
- <listitem>
- <para>
- When a function contains
- <function role="sql">UUID()</function>
- </para>
- </listitem>
-
- <listitem>
- <para>
- When 2 or more tables with
- <literal>AUTO_INCREMENT</literal> columns are updated
- </para>
- </listitem>
-
- <listitem>
- <para>
- When any <literal>INSERT DELAYED</literal> is executed
- </para>
- </listitem>
-
- <listitem>
- <para>
- When the body of a view requires row-based replication,
- the statement creating the view also uses it — for
- example, this occurs when the statement creating a view
- uses the <function role="sql">UUID()</function> function
- </para>
- </listitem>
-
- <listitem>
- <para>
- When a call to a UDF is involved
- </para>
- </listitem>
-
- <listitem>
- <para>
- Beginning with MySQL 5.1.23:
-
- <itemizedlist>
-
- <listitem>
- <para>
- When <function role="sql">FOUND_ROWS()</function> or
- <function role="sql">ROW_COUNT()</function> is used
- (Bug #12092, Bug #30244)
- </para>
- </listitem>
-
- <listitem>
- <para>
- When <function role="sql">USER()</function>,
- <function role="sql">CURRENT_USER()</function>, or
- <function role="sql" condition="function_current-user">CURRENT_USER</function>
- is used (Bug #28086)
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
- </listitem>
-
- </itemizedlist>
-
- <note>
- <para>
- Starting with MySQL 5.1.20 a warning is generated if you try
- to log execute a statement in statement-logging mode that
- should be logged in row-logging mode. The warning will be
- shown both in the client (and available with <literal>SHOW
- WARNINGS</literal>) and through the
- <command>mysqld</command> error log. A warning is added to
- the <literal>SHOW WARNINGS</literal> table each time a
- statement is executed. However, only the first statement
- that generated the warning for each client session is logged
- to the <literal>mysqld</literal> error log to prevent
- flooding the error log.
- </para>
- </note>
-
- <para>
- Starting with MySQL 5.1.20, mixed based logging is used by
- default, but in addition to the decisions above, individual
- engines can also enforce the logging format used when
- information in a table is updated.
- </para>
-
- <para>
- The logging formats supported by a particular engine are
- controlled by internal flags. The table below lists the
- logging formats supported by each of the current engines.
- </para>
-
- <informaltable>
- <tgroup cols="3">
- <colspec colwidth="50*"/>
- <colspec colwidth="25*"/>
- <colspec colwidth="25*"/>
- <thead>
- <row>
- <entry>Engine</entry>
- <entry>Row-logging supported</entry>
- <entry>Statement-logging supported</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Archive</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Blackhole</entry>
- <entry>No</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>CSV</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Example</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- <row>
- <entry>Federated</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Heap</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>MyISAM</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Merge</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>NDB</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- Note that an engine can be support either or both logging
- formats, and the logging capabilities of an individual engine
- can be further defined as follows
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If an engine supports row-based logging, then the engine
- is said to be <emphasis>row-logging capable
- (RLC)</emphasis>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If an engine support statement-based logging, then the
- engine is said to be <emphasis>statement-logging capable
- (SLC)</emphasis>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- When determining what logging mode to use, the capabilities of
- all the tables in the event are combined. The set of tables is
- then marked according to these rules:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- A set of tables is defined as <emphasis>row logging
- restricted (RLR)</emphasis> if the tables are row logging
- capable but not statement logging capable.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A set of tables is defined as <emphasis>statement logging
- restricted (SLR)</emphasis> if the tables are statement
- logging capable but not row logging capable.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Once the determination of the possible logging formats
- required by the statement is complete it is compared to the
- current <literal>BINLOG_FORMAT</literal> setting. The
- following table is used to decide how the information is
- recorded in the binary log or, if appropriate, whether an
- error is raised. In the table, a safe operation is defined as
- one that is deterministic. A number of internal rules decide
- whether the statement is deterministic or not.
- </para>
-
- <informaltable>
- <tgroup cols="6">
- <colspec colwidth="10*" colname="safe"/>
- <colspec colwidth="25*" colname="format"/>
- <colspec colwidth="10*" colname="RLC"/>
- <colspec colwidth="10*" colname="SLC"/>
- <colspec colwidth="20*" colname="error"/>
- <colspec colwidth="25*" colname="logas"/>
- <spanspec namest="safe" nameend="SLC" spanname="condition"/>
- <spanspec namest="error" nameend="logas" spanname="action"/>
- <thead>
- <row>
- <entry spanname="condition">Condition</entry>
- <entry spanname="action">Action</entry>
- </row>
- <row>
- <entry>Safe/unsafe</entry>
- <entry><literal>BINLOG_FORMAT</literal></entry>
- <entry>RLC</entry>
- <entry>SLC</entry>
- <entry>Error/Warning</entry>
- <entry>Logged as</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Warning: unsafe</entry>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry>Warning: unsafe</entry>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- When a warning is produced by the determination, a standard
- MySQL warning is produced (and is available using
- <literal>SHOW WARNINGS</literal>). The information is also
- written to the <command>mysqld</command> error log. Only one
- error for each error instance per client connection is logged.
- The log message will include the SQL statement that was
- attempted.
- </para>
-
- </section>
-
- <section id="binary-log-mysql-database">
-
- <title>Logging Format for Changes to <literal>mysql</literal> Database Tables</title>
-
- <para>
- The contents of the grant tables in the
- <literal>mysql</literal> database can be modified directly
- (for example, with <literal>INSERT</literal> or
- <literal>DELETE</literal>) or indirectly (for example, with
- <literal>GRANT</literal> or <literal>CREATE USER</literal>).
- As of MySQL 5.1.17, statements that affect
- <literal>mysql</literal> database tables are written to the
- binary log using the following rules:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Data manipulation statements that change data in
- <literal>mysql</literal> database tables directly are
- logged according to the setting of the
- <literal>binlog_format</literal> system variable. This
- pertains to statements such as <literal>INSERT</literal>,
- <literal>UPDATE</literal>, <literal>DELETE</literal>,
- <literal>REPLACE</literal>, <literal>DO</literal>,
- <literal>LOAD DATA INFILE</literal>,
- <literal>SELECT</literal>, and
- <literal>TRUNCATE</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Statements that change the <literal>mysql</literal>
- database indirectly are logged as statements regardless of
- the value of <literal>binlog_format</literal>. This
- pertains to statements such as <literal>GRANT</literal>,
- <literal>REVOKE</literal>, <literal>SET
- PASSWORD</literal>, <literal>RENAME USER</literal>,
- <literal>CREATE</literal> (all forms except
- <literal>CREATE TABLE ... SELECT</literal>),
- <literal>ALTER</literal> (all forms), and
- <literal>DROP</literal> (all forms).
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal>CREATE TABLE ... SELECT</literal> is a combination of
- data definition and data manipulation. The <literal>CREATE
- TABLE</literal> part is logged using statement format and the
- <literal>SELECT</literal> part is logged according to the
- value of <literal>binlog_format</literal>.
- </para>
-
- </section>
-
- </section>
-
- <section id="slow-query-log">
-
- <title>The Slow Query Log</title>
-
- <indexterm>
- <primary>slow query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>slow query log</secondary>
- </indexterm>
-
- <para>
- The slow query log consists of all SQL statements that took more
- than <literal>long_query_time</literal> seconds to execute. The
- time to acquire the initial table locks is not counted as
- execution time. <command>mysqld</command> writes a statement to
- the slow query log after it has been executed and after all
- locks have been released, so log order might be different from
- execution order. The minimum and default values of
- <literal>long_query_time</literal> are 1 and 10, respectively.
- Prior to MySQL 5.1.21, the minimum value is 1, and the value for
- this variable must be an integer. Beginning with MySQL 5.1.21,
- the default is 0, and a resolution of microseconds is supported
- when logging to a file. However, the microseconds part is
- ignored and only integer values are written when logging to
- tables.
- </para>
-
- <para>
- To enable the slow query log as of MySQL 5.1.6, start
- <command>mysqld</command> with the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option, and optionally use <option>--log-output</option> to
- specify the log destination (as described in
- <xref linkend="log-tables"/>). Before 5.1.6, the slow query log
- destination is always a file. To enable the slow query log file,
- use the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option.
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log-slow-queries</option>, the default name is
- <filename><replaceable>host_name</replaceable>-slow.log</filename>.
- If a filename is given, but not as an absolute pathname, the
- server writes the file in the data directory.
- </para>
-
- <para>
- When <option>--log-slow-queries</option> is specified, the
- <option>--slow-query-log</option> option also may be given as of
- MySQL 5.1.12 to specify the initial slow query log state. With
- no argument or an argument of 0, the option disables the log. If
- omitted or given with an argument of 1, the option enables the
- log. If <option>--log--slow-queries</option> is not given,
- <option>--slow-query-log</option> has no effect.
- </para>
-
- <para>
- The global <literal>slow_query_log</literal> and
- <literal>slow_query_log_file</literal> system variables provide
- runtime control over the slow query log. Set
- <literal>slow_query_log</literal> to 0 (or
- <literal>OFF</literal>) to disable the log or to 1 (or
- <literal>ON</literal>) to enable it. Set
- <literal>general_log_file</literal> to specify the name of the
- log file. If a log file already is open, it is closed and the
- new file is opened.
- </para>
-
- <para>
- When the slow query log is enabled, output is written to any
- destinations specified by the <option>--log-output</option>
- option or <literal>log_output</literal> system variable. Note
- that if the destination is <literal>NONE</literal>, no output is
- written even if the slow query log is enabled. Setting the log
- filename has no effect on logging if the log destination value
- does not contain <literal>FILE</literal>.
- </para>
-
- <para>
- The slow query log can be used to find queries that take a long
- time to execute and are therefore candidates for optimization.
- However, examining a long slow query log can become a difficult
- task. To make this easier, you can process the slow query log
- using the <command>mysqldumpslow</command> command to summarize
- the queries that appear in the log. Use <command>mysqldumpslow
- --help</command> to see the options that this command supports.
- </para>
-
- <para>
- In MySQL ¤t-series;, queries that do not use indexes are
- logged in the slow query log if the
- <option>--log-queries-not-using-indexes</option> option is
- specified. See <xref linkend="server-options"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- Excessive table scans are indicative of missing or poorly
- optimized indexes. Using an advisor specifically designed for
- the task, the MySQL Enterprise Monitor can identify such
- problems and offer advice on resolution. For more information
- see <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- In MySQL ¤t-series;, the
- <option>--log-slow-admin-statements</option> server option
- enables you to request logging of slow administrative statements
- such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
- TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
- query log.
- </para>
-
- <para>
- Queries handled by the query cache are not added to the slow
- query log, nor are queries that would not benefit from the
- presence of an index because the table has zero rows or one row.
- </para>
-
- </section>
-
- <section id="log-file-maintenance">
-
- <title>Server Log Maintenance</title>
-
- <indexterm>
- <primary>files</primary>
- <secondary>log</secondary>
- </indexterm>
-
- <indexterm>
- <primary>maintaining</primary>
- <secondary>log files</secondary>
- </indexterm>
-
- <indexterm>
- <primary>log files</primary>
- <secondary>maintaining</secondary>
- </indexterm>
-
- <para>
- MySQL Server can create a number of different log files that
- make it easy to see what is going on. See
- <xref linkend="log-files"/>. However, you must clean up these
- files regularly to ensure that the logs do not take up too much
- disk space.
- </para>
-
- <para>
- When using MySQL with logging enabled, you may want to back up
- and remove old log files from time to time and tell MySQL to
- start logging to new files. See <xref linkend="backup"/>.
- </para>
-
- <para>
- On a Linux (Red Hat) installation, you can use the
- <literal>mysql-log-rotate</literal> script for this. If you
- installed MySQL from an RPM distribution, this script should
- have been installed automatically. You should be careful with
- this script if you are using the binary log for replication. You
- should not remove binary logs until you are certain that their
- contents have been processed by all slaves.
- </para>
-
- <para>
- On other systems, you must install a short script yourself that
- you start from <command>cron</command> (or its equivalent) for
- handling log files.
- </para>
-
- <para>
- For the binary log, you can set the
- <literal>expire_logs_days</literal> system variable to expire
- binary log files automatically after a given number of days (see
- <xref linkend="server-system-variables"/>). If you are using
- replication, you should set the variable no lower than the
- maximum number of days your slaves might lag behind the master.
- </para>
-
- <para>
- You can force MySQL to start using new log files by issuing a
- <literal>FLUSH LOGS</literal> statement or executing
- <command>mysqladmin flush-logs</command> or <command>mysqladmin
- refresh</command>. See <xref linkend="flush"/>, and
- <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- A log flushing operation does the following:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If general query logging (<option>--log</option>) or slow
- query logging (<option>--log-slow-queries</option>) to a log
- file is enabled, the server closes and reopens the general
- query log file or slow query log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If binary logging (<option>--log-bin</option>) is used, the
- server closes the current log file and opens a new log file
- with the next sequence number.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the server was given an error log filename with the
- <option>--log-error</option> option, it renames the error
- log with the suffix <literal>-old</literal> and creates a
- new empty error log file.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server creates a new binary log file when you flush the
- logs. However, it just closes and reopens the general and slow
- query log files. To cause new files to be created on Unix,
- rename the current logs before flushing them. At flush time, the
- server will open new logs with the original names. For example,
- if the general and slow query logs are named
- <filename>mysql.log</filename> and
- <filename>mysql-slow.log</filename>, you can use a series of
- commands like this:
- </para>
-
-<programlisting>
-shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
-shell> <userinput>mv mysql.log mysql.old</userinput>
-shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-</programlisting>
-
- <para>
- At this point, you can make a backup of
- <filename>mysql.old</filename> and
- <filename>mysql-slow.log</filename> and then remove them from
- disk.
- </para>
-
- <para>
- On Windows, you cannot rename log files while the server has
- them open. You must stop the server and rename them, and then
- restart the server to create new logs.
- </para>
-
- <para>
- As of MySQL 5.1.2, you can disable the general query log or slow
- query log at runtime:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'OFF';
-SET GLOBAL slow_query_log = 'OFF';
-</programlisting>
-
- <para>
- With the logs disabled, rename the log files externally; for
- example, from the command line. Then enable the logs again:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'ON';
-SET GLOBAL slow_query_log = 'ON';
-</programlisting>
-
- <para>
- This method works on any platform and does not require a server
- restart.
- </para>
-
- </section>
-
- </section>
-
<section id="multiple-servers">
<title>Running Multiple MySQL Servers on the Same Machine</title>
Modified: trunk/refman-6.0/dba-core.xml
===================================================================
--- trunk/refman-6.0/dba-core.xml 2007-12-07 18:16:27 UTC (rev 9198)
+++ trunk/refman-6.0/dba-core.xml 2007-12-07 18:17:33 UTC (rev 9199)
Changed blocks: 3, Lines Added: 2342, Lines Deleted: 2342; 171682 bytes
@@ -26,19 +26,19 @@
<listitem>
<para>
- Managing user accounts
+ The server log files
</para>
</listitem>
<listitem>
<para>
- Performing backups
+ Managing user accounts
</para>
</listitem>
<listitem>
<para>
- The server log files
+ Performing backups
</para>
</listitem>
@@ -11544,6 +11544,2345 @@
</section>
+ <section id="log-files">
+
+ <title>MySQL Server Logs</title>
+
+ <indexterm>
+ <primary>log files</primary>
+ </indexterm>
+
+ <para>
+ MySQL has several different logs that can help you find out what
+ is going on inside <command>mysqld</command>:
+ </para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="30*"/>
+ <colspec colwidth="70*"/>
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Log Type</emphasis></entry>
+ <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
+ </row>
+ <row>
+ <entry>The error log</entry>
+ <entry>Problems encountered starting, running, or stopping
+ <command>mysqld</command></entry>
+ </row>
+ <row>
+ <entry>The general query log</entry>
+ <entry>Established client connections and statements received from clients</entry>
+ </row>
+ <row>
+ <entry>The binary log</entry>
+ <entry>All statements that change data (also used for replication)</entry>
+ </row>
+ <row>
+ <entry>The slow query log</entry>
+ <entry>All queries that took more than <literal>long_query_time</literal>
+ seconds to execute or didn't use indexes</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ By default, all log files are created in the
+ <command>mysqld</command> data directory. You can force
+ <command>mysqld</command> to close and reopen the log files (or in
+ some cases switch to a new log) by flushing the logs. Log flushing
+ occurs when you issue a <literal>FLUSH LOGS</literal> statement or
+ execute <command>mysqladmin flush-logs</command> or
+ <command>mysqladmin refresh</command>. See
+ <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ If you are using MySQL replication capabilities, slave replication
+ servers maintain additional log files called relay logs.
+ <xref linkend="replication"/>, discusses relay log contents and
+ configuration.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The MySQL Enterprise Monitor provides a number of advisors
+ specifically related to the various log files. For more
+ information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ The server can write general query and slow query entries to log
+ tables, log files, or both. For details, see
+ <xref linkend="log-tables"/>.
+ </para>
+
+ <para>
+ You can also control during runtimethe general query and slow
+ query logs. You can enable or disable logging, or change the name
+ of the log file. See <xref linkend="query-log"/>, and
+ <xref linkend="slow-query-log"/>.
+ </para>
+
+ <section id="log-tables">
+
+ <title>Selecting General Query and Slow Query Log Output Destinations</title>
+
+ <para>
+ MySQL Server provides flexible control over the destination for
+ log output. Log entries can be written to log files or to the
+ <literal>general_log</literal> and <literal>slow_log</literal>
+ tables in the <literal>mysql</literal> database. If logging is
+ enabled, either or both destinations can be selected.
+ </para>
+
+ <note>
+ <para>
+ The log tables are created during the installation procedure
+ along with the other system tables. If you upgrade MySQL from
+ a release older than 5.1.6 to MySQL 5.1.6 or higher, you must
+ upgrade the system tables after upgrading to make sure that
+ the log tables exist. See <xref linkend="mysql-upgrade"/>.
+ </para>
+ </note>
+
+ <para>
+ Currently, logging to tables incurs significantly more server
+ overhead than logging to files. If you enable the general log or
+ slow query log and require highest performance, you should log
+ to files and not to tables.
+ </para>
+
+ <para>
+ The <option>--log-output</option> option specifies the
+ destination for log output, if logging is enabled, but the
+ option does not in itself enable the logs. The syntax for this
+ option is
+ <option>--log-output[=<replaceable>value</replaceable>,...]</option>:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> is given with a value, the
+ value can be a comma-separated list of one or more of the
+ words <literal>TABLE</literal> (log to tables),
+ <literal>FILE</literal> (log to files), or
+ <literal>NONE</literal> (do not log to tables or files).
+ <literal>NONE</literal>, if present, takes precedence over
+ any other specifiers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> is omitted or given without
+ a value, the effect is the same as
+ <option>--log-output=FILE</option>. That is, the file
+ destination is selected.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <option>--log-output</option> option also sets the value
+ of the global <literal>log_output</literal> system variable,
+ which can be modified at runtime to change the logging
+ destination for the server while it executes.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The
+ <option>--log[=<replaceable>file_name</replaceable>]</option>
+ option, if given, enables logging to the general query log for
+ the selected log destinations. Similarly, the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option, if given, enables logging to the slow query log for the
+ selected destinations. If you specify either option, the server
+ opens the corresponding log file and writes startup messages to
+ it. However, logging of queries to the file does not occur
+ unless the <literal>FILE</literal> log destination is selected.
+ </para>
+
+ <para>
+ Examples:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ To write general query log entries to the log table and the
+ log file, use <option>--log-output=TABLE,FILE</option> to
+ select both log destinations and the <option>--log</option>
+ option to enable the general query log.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To write general and slow query log entries only to the log
+ tables, use <option>--log-output=TABLE</option> to select
+ tables as the log destination and the <option>--log</option>
+ and <option>--log-slow-queries</option> options to enable
+ both logs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To write slow query log entries only to the log file, use
+ <option>--log-output=FILE</option> to select files as the
+ log destination and the <option>--log-slow-queries</option>
+ option to enable the slow query log. (In this case, because
+ the default log destination is <literal>FILE</literal>, you
+ could omit the <option>--log-output</option> option.)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Several system variables are associated with log tables and
+ files:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The global <literal>general_log</literal> and
+ <literal>slow_query_log</literal> variables indicate whether
+ the general query log and slow query log are enabled
+ (<literal>ON</literal>) or disabled
+ (<literal>OFF</literal>). You can set these variables at
+ runtime to control whether the logs are enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The global <literal>general_log_file</literal> and
+ <literal>slow_query_log_file</literal> variables indicate
+ the names of the general query log and slow query log files.
+ You can set these variables at runtime to change the names
+ of the log files. (If the <option>--log</option> and
+ <literal>--log-slow-queries</literal> options were not
+ given, the variable values are set to the default log
+ filenames.)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The session <literal>sql_log_off</literal> variable can be
+ set to <literal>ON</literal> or <literal>OFF</literal> to
+ disable or enable general query logging for the current
+ connection.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The use of tables for log output offers the following benefits:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Log entries have a standard format. To display the current
+ structure of the log tables, use these statements:
+ </para>
+
+<programlisting>
+SHOW CREATE TABLE mysql.general_log;
+SHOW CREATE TABLE mysql.slow_log;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Log contents are accessible via SQL statements. This enables
+ the use of queries that select only those log entries that
+ satisfy specific criteria. For example, to select log
+ contents associated with a particular client (which can be
+ useful for identifying problematic queries from that
+ client), it is easier to do this using a log table than a
+ log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Logs are accessible remotely through any client that can
+ connect to the server and issue queries (if the client has
+ the appropriate log table privileges). It's not necessary to
+ log in to the server host and directly access the
+ filesystem.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The log table implementation has the following characteristics:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ In general, the primary purpose of log tables is to provide
+ an interface for users to observe the runtime execution of
+ the server, not to interfere with its runtime execution.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>CREATE TABLE</literal>, <literal>ALTER
+ TABLE</literal>, and <literal>DROP TABLE</literal> are valid
+ operations on a log table. For <literal>ALTER
+ TABLE</literal> and <literal>DROP TABLE</literal>, the log
+ table cannot be in use and must be disabled, as described
+ later.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ By default, the log tables use the <literal>CSV</literal>
+ storage engine that writes data in comma-separated values
+ format. For users who have access to the
+ <filename>.CSV</filename> files that contain log table data,
+ the files are easy to import into other programs such as
+ spreadsheets that can process CSV input.
+ </para>
+
+ <para>
+ The log tables can be altered to use the
+ <literal>MyISAM</literal> storage engine. You cannot use
+ <literal>ALTER TABLE</literal> to alter a log table that is
+ in use. The log must be disabled first. No engines other
+ than <literal>CSV</literal> or <literal>MyISAM</literal> are
+ legal for the log tables.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To disable logging so that you can alter (or drop) a log
+ table, you can use the following strategy. The example uses
+ the general query log; the procedure for the slow query log
+ is similar but uses the <literal>slow_log</literal> table
+ and <literal>slow_query_log</literal> system variable.
+ </para>
+
+<programlisting>
+SET @old_log_state = @@global.general_log;
+SET GLOBAL general_log = 'OFF';
+ALTER TABLE mysql.general_log ENGINE = MyISAM;
+SET GLOBAL general_log = @old_log_state;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>TRUNCATE TABLE</literal> is a valid operation on a
+ log table. It can be used to expire log entries.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>RENAME TABLE</literal> is a valid operation on a
+ log table. You can atomically rename a log table (to perform
+ log rotation, for example) using the following strategy:
+ </para>
+
+<programlisting>
+USE mysql;
+CREATE TABLE IF NOT EXISTS general_log2 LIKE general_log;
+RENAME TABLE general_log TO general_log_backup, general_log2 TO general_log;
+</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>LOCK TABLES</literal> cannot be used on a log
+ table.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>INSERT</literal>, <literal>DELETE</literal>, and
+ <literal>UPDATE</literal> cannot be used on a log table.
+ These operations are allowed only internally to the server
+ itself.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The global read lock and the state of the global
+ <literal>read_only</literal> system variable have no effect
+ on log tables. The server can always write to the log
+ tables.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Entries written to the log tables are not written to the
+ binary log and thus are not replicated to slave servers.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To flush the log tables or log files, use <literal>FLUSH
+ TABLES</literal> or <literal>FLUSH LOGS</literal>,
+ respectively.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It is not allowed to partition log tables.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="error-log">
+
+ <title>The Error Log</title>
+
+ <para>
+ The error log contains information indicating when
+ <command>mysqld</command> was started and stopped and also any
+ critical errors that occur while the server is running. If
+ <command>mysqld</command> notices a table that needs to be
+ automatically checked or repaired, it writes a message to the
+ error log.
+ </para>
+
+ <para>
+ On some operating systems, the error log contains a stack trace
+ if <command>mysqld</command> dies. The trace can be used to
+ determine where <command>mysqld</command> died. See
+ <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
+ Internals: Porting</ulink>.
+ </para>
+
+ <para>
+ You can specify where <command>mysqld</command> writes the error
+ log with the
+ <option>--log-error[=<replaceable>file_name</replaceable>]</option>
+ option. If no <replaceable>file_name</replaceable> value is
+ given, <command>mysqld</command> uses the name
+ <filename><replaceable>host_name</replaceable>.err</filename> by
+ default and writes the file in the data directory. If you
+ execute <literal>FLUSH LOGS</literal>, the error log is renamed
+ with the suffix <literal>-old</literal> and
+ <command>mysqld</command> creates a new empty log file. (No
+ renaming occurs if the <option>--log-error</option> option was
+ not given to <command>mysqld</command>.)
+ </para>
+
+ <para>
+ If you do not specify <option>--log-error</option>, or (on
+ Windows) if you use the <option>--console</option> option,
+ errors are written to <literal>stderr</literal>, the standard
+ error output. Usually this is your terminal.
+ </para>
+
+ <para>
+ On Windows, error output is always written to the
+ <literal>.err</literal> file if <option>--console</option> is
+ not given.
+ </para>
+
+ <para>
+ The <option>--log-warnings</option> option or
+ <literal>log_warnings</literal> system variable can be used to
+ control warning logging to the error log. The default value is
+ enabled (1). Warning logging can be disabled using a value of 0.
+ If the value is greater than 1, aborted connections are written
+ to the error log. See <xref linkend="communication-errors"/>.
+ </para>
+
+ <para>
+ If you use <command>mysqld_safe</command> to start
+ <command>mysqld</command>, <command>mysqld_safe</command>
+ arranges for <command>mysqld</command> to write error messages
+ to a log file or to <literal>syslog</literal>
+ <command>mysqld_safe</command> has three error-logging options,
+ <option>--syslog</option>, <option>--skip-syslog</option>, and
+ <option>--log-error</option>. The default with no logging
+ options or with <option>--skip-syslog</option> is to use the
+ default log file. To explicitly specify use of an error log
+ file, specify
+ <option>--log-error=<replaceable>file_name</replaceable></option>
+ to <command>mysqld_safe</command>, and
+ <command>mysqld_safe</command> will arrange for
+ <command>mysqld</command> to write messages to a log file. To
+ use <literal>syslog</literal> instead, specify the
+ <option>--syslog</option> option.
+ </para>
+
+ <para>
+ If you specify <option>--log-error</option> in an option file in
+ a section that <command>mysqld</command> reads,
+ <command>mysqld_safe</command> also will find and use the
+ option.
+ </para>
+
+ <para>
+ For logging to <literal>syslog</literal>, messages from
+ <command>mysqld_safe</command> and <command>mysqld</command> are
+ written with a tag of <literal>mysqld_safe</literal> and
+ <literal>mysqld</literal>, respectively. To specify a suffix for
+ the tag, use
+ <option>--syslog-tag=<replaceable>tag</replaceable></option>,
+ which modifies the tags to be
+ <literal>mysqld_safe-<replaceable>tag</replaceable></literal>
+ and <literal>mysqld-<replaceable>tag</replaceable></literal>.
+ </para>
+
+ <para>
+ If <command>mysqld_safe</command> is used to start
+ <command>mysqld</command> and <command>mysqld</command> dies
+ unexpectedly, <command>mysqld_safe</command> notices that it
+ needs to restart <command>mysqld</command> and writes a
+ <literal>restarted mysqld</literal> message to the error log.
+ </para>
+
+ </section>
+
+ <section id="query-log">
+
+ <title>The General Query Log</title>
+
+ <indexterm>
+ <primary>general query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>general query log</secondary>
+ </indexterm>
+
+ <para>
+ The general query log is a general record of what
+ <command>mysqld</command> is doing. The server writes
+ information to this log when clients connect or disconnect, and
+ it logs each SQL statement received from clients. The general
+ query log can be very useful when you suspect an error in a
+ client and want to know exactly what the client sent to
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ <command>mysqld</command> writes statements to the query log in
+ the order that it receives them, which might differ from the
+ order in which they are executed. This logging order contrasts
+ to the binary log, for which statements are written after they
+ are executed but before any locks are released. (Also, the query
+ log contains all statements, whereas the binary log does not
+ contain statements that only select data.)
+ </para>
+
+ <para>
+ To enable the general query log, start <command>mysqld</command>
+ with the
+ <option>--log[=<replaceable>file_name</replaceable>]</option> or
+ <option>-l [<replaceable>file_name</replaceable>]</option>
+ option, and optionally use <option>--log-output</option> to
+ specify the log destination (as described in
+ <xref linkend="log-tables"/>).
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log</option> or <option>-l</option>, the default name
+ is <filename><replaceable>host_name</replaceable>.log</filename>
+ in the data directory. If a filename is given, but not as an
+ absolute pathname, the server writes the file in the data
+ directory.
+ </para>
+
+ <para>
+ When <option>--log</option> or <option>-l</option> is specified,
+ the <option>--general-log</option> option also may be given to
+ specify the initial general query log state. With no argument or
+ an argument of 0, the option disables the log. If omitted or
+ given with an argument of 1, the option enables the log. If
+ <option>--log</option> or <option>-l</option> is not specified,
+ <option>--general-log</option> has no effect.
+ </para>
+
+ <para>
+ The global <literal>general_log</literal> and
+ <literal>general_log_file</literal> system variables provide
+ runtime control over the general query log. Set
+ <literal>general_log</literal> to 0 (or <literal>OFF</literal>)
+ to disable the log or to 1 (or <literal>ON</literal>) to enable
+ it. Set <literal>general_log_file</literal> to specify the name
+ of the log file. If a log file already is open, it is closed and
+ the new file is opened.
+ </para>
+
+ <para>
+ When the general query log is enabled, output is written to any
+ destinations specified by the <option>--log-output</option>
+ option or <literal>log_output</literal> system variable. Note
+ that if the destination is <literal>NONE</literal>, no output is
+ written even if the general log is enabled. Setting the log
+ filename has no effect on logging if the log destination value
+ does not contain <literal>FILE</literal>.
+ </para>
+
+ <para>
+ Server restarts and log flushing do not cause a new general
+ query log file to be generated (although flushing closes and
+ reopens it). On Unix, you can rename the file and create a new
+ one by using the following commands:
+ </para>
+
+<programlisting>
+shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
+shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
+</programlisting>
+
+ <para>
+ On Windows, you cannot rename the log file while the server has
+ it open. You must stop the server and rename the file, and then
+ restart the server to create a new log file.
+ </para>
+
+ <para>
+ You can disable the general query log at runtime:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'OFF';
+</programlisting>
+
+ <para>
+ With the log disabled, rename the log file externally; for
+ example, from the command line. Then enable the log again:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'ON';
+</programlisting>
+
+ <para>
+ This method works on any platform and does not require a server
+ restart.
+ </para>
+
+ <para>
+ The session <literal>sql_log_off</literal> variable can be set
+ to <literal>ON</literal> or <literal>OFF</literal> to disable or
+ enable general query logging for the current connection.
+ </para>
+
+ </section>
+
+ <section id="binary-log">
+
+ <title>The Binary Log</title>
+
+ <indexterm>
+ <primary>binary log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>binary log</secondary>
+ </indexterm>
+
+ <para>
+ The binary log contains all statements that update data or
+ potentially could have updated it (for example, a
+ <literal>DELETE</literal> which matched no rows). Statements are
+ stored in the form of <quote>events</quote> that describe the
+ modifications. The binary log also contains information about
+ how long each statement took that updated data.
+ </para>
+
+ <para>
+ The binary log is not used for statements such as
+ <literal>SELECT</literal> or <literal>SHOW</literal> that do not
+ modify data. If you want to log all statements (for example, to
+ identify a problem query), use the general query log. See
+ <xref linkend="query-log"/>.
+ </para>
+
+ <para>
+ The primary purpose of the binary log is to be able to update
+ databases during a restore operation as fully as possible,
+ because the binary log contains all updates done after a backup
+ was made. The binary log is also used on master replication
+ servers as a record of the statements to be sent to slave
+ servers. See <xref linkend="replication"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ The binary log can also be used to track significant DDL
+ events. Analyzing the binary log in this way is an integral
+ part of the MySQL Enterprise Monitor. For more information see
+ <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ Running the server with the binary log enabled makes performance
+ about 1% slower. However, the benefits of the binary log for
+ restore operations and in allowing you to set up replication
+ generally outweigh this minor performance decrement.
+ </para>
+
+ <para>
+ When started with the
+ <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
+ option, <command>mysqld</command> writes a log file containing
+ all SQL statements that update data (both DDL and DML
+ statements). If no <replaceable>base_name</replaceable> value is
+ given, the default name is the value of the
+ <literal>pid-file</literal> option (which by default is the name
+ of host machine) followed by <literal>-bin</literal>. If the
+ basename is given, but not as an absolute pathname, the server
+ writes the file in the data directory. It is recommended that
+ you specify a basename; see <xref linkend="open-bugs"/>, for the
+ reason.
+ </para>
+
+ <para>
+ If you supply an extension in the log name (for example,
+ <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
+ the extension is silently removed and ignored.
+ </para>
+
+ <para>
+ <command>mysqld</command> appends a numeric extension to the
+ binary log basename. The number increases each time the server
+ creates a new log file, thus creating an ordered series of
+ files. The server creates a new binary log file each time it
+ starts or flushes the logs. The server also creates a new binary
+ log file automatically when the current log's size reaches
+ <literal>max_binlog_size</literal>. A binary log file may become
+ larger than <literal>max_binlog_size</literal> if you are using
+ large transactions because a transaction is written to the file
+ in one piece, never split between files.
+ </para>
+
+ <para>
+ To keep track of which binary log files have been used,
+ <command>mysqld</command> also creates a binary log index file
+ that contains the names of all used binary log files. By default
+ this has the same basename as the binary log file, with the
+ extension <literal>'.index'</literal>. You can change the name
+ of the binary log index file with the
+ <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
+ option. You should not manually edit this file while
+ <command>mysqld</command> is running; doing so would confuse
+ <command>mysqld</command>.
+ </para>
+
+ <para>
+ Replication slave servers by default do not write to their own
+ binary log any statements that are received from the replication
+ master. To cause these statements to be logged, start the slave
+ with the <option>--log-slave-updates</option> option.
+ </para>
+
+ <para>
+ Writes to the binary log file and binary log index file are
+ handled in the same way as writes to <literal>MyISAM</literal>
+ tables. See <xref linkend="full-disk"/>.
+ </para>
+
+ <para>
+ You can delete all binary log files with the <literal>RESET
+ MASTER</literal> statement, or a subset of them with
+ <literal>PURGE MASTER LOGS</literal>. See
+ <xref linkend="reset"/>, and
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ The binary log format has some known limitations that can affect
+ recovery from backups. See
+ <xref linkend="replication-features"/>.
+ </para>
+
+ <para>
+ Binary logging for stored routines and triggers is done as
+ described in <xref linkend="stored-procedure-logging"/>.
+ </para>
+
+ <para>
+ You can use the following options to <command>mysqld</command>
+ to affect what is logged to the binary log. See also the
+ discussion that follows this option list.
+ </para>
+
+ <para>
+ If you are using replication, the options described here affect
+ which statements are sent by a master server to its slaves.
+ There are also options for slave servers that control which
+ statements received from the master to execute or ignore. For
+ details, see <xref linkend="replication-options"/>.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para id="option_mysqld_binlog-do-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-do-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-do-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to restrict binary logging to updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). All other databases
+ that are not explicitly mentioned are ignored. If you use
+ this option, you should ensure that you do updates only in
+ the default database.
+ </para>
+
+ <para>
+ There is an exception to this for <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. The server uses
+ the database named in the statement (not the default
+ database) to decide whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-do-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement is
+ <emphasis>not</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To log multiple databases, use multiple options, specifying
+ the option once for each database.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para id="option_mysqld_binlog-ignore-db">
+ <indexterm>
+ <primary>mysqld</primary>
+ <secondary>binlog-ignore-db option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>binlog-ignore-db option</primary>
+ <secondary>mysqld</secondary>
+ </indexterm>
+
+ <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
+ </para>
+
+ <para>
+ Tell the server to suppress binary logging of updates for
+ which the default database is
+ <replaceable>db_name</replaceable> (that is, the database
+ selected by <literal>USE</literal>). If you use this option,
+ you should ensure that you do updates only in the default
+ database.
+ </para>
+
+ <para>
+ As with the <option>--binlog-do-db</option> option, there is
+ an exception for the <literal>CREATE DATABASE</literal>,
+ <literal>ALTER DATABASE</literal>, and <literal>DROP
+ DATABASE</literal> statements. The server uses the database
+ named in the statement (not the default database) to decide
+ whether it should log the statement.
+ </para>
+
+ <para>
+ An example of what does not work as you might expect: If the
+ server is started with
+ <literal>binlog-ignore-db=sales</literal>, and you run
+ <literal>USE prices; UPDATE sales.january SET
+ amount=amount+1000;</literal>, this statement
+ <emphasis>is</emphasis> written into the binary log.
+ </para>
+
+ <para>
+ To ignore multiple databases, use multiple options,
+ specifying the option once for each database.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server evaluates the options for logging or ignoring updates
+ to the binary log according to the following rules. As described
+ previously, there is an exception for the <literal>CREATE
+ DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
+ <literal>DROP DATABASE</literal> statements. In those cases, the
+ database being <emphasis>created, altered, or dropped</emphasis>
+ replaces the default database in the following rules:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Are there <option>--binlog-do-db</option> or
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Write the statement to the binary log and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some rules (<option>--binlog-do-db</option>,
+ <option>--binlog-ignore-db</option>, or both). Is there a
+ default database (has any database been selected by
+ <literal>USE</literal>?)?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement, and
+ exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Yes: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There is a default database. Are there some
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Does the default database match any of the
+ <option>--binlog-do-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Write the statement and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Do <emphasis>not</emphasis> write the statement,
+ and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Go to the next step.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>
+ There are some <option>--binlog-ignore-db</option> rules.
+ Does the default database match any of the
+ <option>--binlog-ignore-db</option> rules?
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Yes: Do not write the statement, and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ No: Write the query and exit.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ For example, a slave running with only
+ <option>--binlog-do-db=sales</option> does not write to the
+ binary log any statement for which the default database is
+ different from <literal>sales</literal> (in other words,
+ <option>--binlog-do-db</option> can sometimes mean <quote>ignore
+ other databases</quote>).
+ </para>
+
+ <para>
+ If you are using replication, you should not delete old binary
+ log files until you are sure that no slave still needs to use
+ them. For example, if your slaves never run more than three days
+ behind, once a day you can execute <command>mysqladmin
+ flush-logs</command> on the master and then remove any logs that
+ are more than three days old. You can remove the files manually,
+ but it is preferable to use <literal>PURGE MASTER
+ LOGS</literal>, which also safely updates the binary log index
+ file for you (and which can take a date argument). See
+ <xref linkend="purge-master-logs"/>.
+ </para>
+
+ <para>
+ A client that has the <literal>SUPER</literal> privilege can
+ disable binary logging of its own statements by using a
+ <literal>SET SQL_LOG_BIN=0</literal> statement. See
+ <xref linkend="set-option"/>.
+ </para>
+
+ <para>
+ You can display the contents of binary log files with the
+ <command>mysqlbinlog</command> utility. This can be useful when
+ you want to reprocess statements in the log. For example, you
+ can update a MySQL server from the binary log as follows:
+ </para>
+
+<programlisting>
+shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
+</programlisting>
+
+ <para>
+ See <xref linkend="mysqlbinlog"/>, for more information on the
+ <command>mysqlbinlog</command> utility and how to use it.
+ <command>mysqlbinlog</command> also can be used with relay log
+ files because they are written using the same format as binary
+ log files.
+ </para>
+
+ <para>
+ Binary logging is done immediately after a statement completes
+ but before any locks are released or any commit is done. This
+ ensures that the log is logged in execution order.
+ </para>
+
+ <para>
+ Updates to non-transactional tables are stored in the binary log
+ immediately after execution. Within an uncommitted transaction,
+ all updates (<literal>UPDATE</literal>,
+ <literal>DELETE</literal>, or <literal>INSERT</literal>) that
+ change transactional tables such as <literal>InnoDB</literal>
+ tables are cached until a <literal>COMMIT</literal> statement is
+ received by the server. At that point, <command>mysqld</command>
+ writes the entire transaction to the binary log before the
+ <literal>COMMIT</literal> is executed. When the thread that
+ handles the transaction starts, it allocates a buffer of
+ <literal>binlog_cache_size</literal> to buffer statements. If a
+ statement is bigger than this, the thread opens a temporary file
+ to store the transaction. The temporary file is deleted when the
+ thread ends.
+ </para>
+
+ <para>
+ Modifications to non-transactional tables cannot be rolled back.
+ If a transaction that is rolled back includes modifications to
+ non-transactional tables, the entire transaction is logged with
+ a <literal>ROLLBACK</literal> statement at the end to ensure
+ that the modifications to those tables are replicated.
+ </para>
+
+ <para>
+ The <literal>Binlog_cache_use</literal> status variable shows
+ the number of transactions that used this buffer (and possibly a
+ temporary file) for storing statements. The
+ <literal>Binlog_cache_disk_use</literal> status variable shows
+ how many of those transactions actually had to use a temporary
+ file. These two variables can be used for tuning
+ <literal>binlog_cache_size</literal> to a large enough value
+ that avoids the use of temporary files.
+ </para>
+
+ <para>
+ The <literal>max_binlog_cache_size</literal> system variable
+ (default 4GB, which is also the maximum) can be used to restrict
+ the total size used to cache a multiple-statement transaction.
+ If a transaction is larger than this many bytes, it fails and
+ rolls back. The minimum value is 4096.
+ </para>
+
+ <para>
+ If you are using the binary log and row based logging,
+ concurrent inserts are converted to normal inserts for
+ <literal>CREATE ... SELECT</literal> or <literal>INSERT ...
+ SELECT</literal> statement. This is done to ensure that you can
+ re-create an exact copy of your tables by applying the log
+ during a backup operation. If you are using statement based
+ logging then the original statement is written to the log.
+ </para>
+
+ <para>
+ Note that the binary log format is different in MySQL
+ ¤t-series; from previous versions of MySQL, due to
+ enhancements in replication. See
+ <xref linkend="replication-compatibility"/>.
+ </para>
+
+ <para>
+ By default, the binary log is not synchronized to disk at each
+ write. So if the operating system or machine (not only the MySQL
+ server) crashes, there is a chance that the last statements of
+ the binary log are lost. To prevent this, you can make the
+ binary log be synchronized to disk after every
+ <replaceable>N</replaceable> writes to the binary log, with the
+ <literal>sync_binlog</literal> system variable. See
+ <xref linkend="server-system-variables"/>. 1 is the safest value
+ for <literal>sync_binlog</literal>, but also the slowest. Even
+ with <literal>sync_binlog</literal> set to 1, there is still the
+ chance of an inconsistency between the table content and binary
+ log content in case of a crash. For example, if you are using
+ <literal>InnoDB</literal> tables and the MySQL server processes
+ a <literal>COMMIT</literal> statement, it writes the whole
+ transaction to the binary log and then commits this transaction
+ into <literal>InnoDB</literal>. If the server crashes between
+ those two operations, the transaction is rolled back by
+ <literal>InnoDB</literal> at restart but still exists in the
+ binary log. To resolve this, you should set
+ <option>--innodb_support_xa</option> to 1. Although this option
+ is related to the support of XA transactions in InnoDB, it also
+ ensures that the binary log and InnoDB data files are
+ synchronized.
+ </para>
+
+ <para>
+ For this option to provide a greater degree of safety, the MySQL
+ server should also be configured to synchronize the binary log
+ and the <literal>InnoDB</literal> logs to disk at every
+ transaction. The <literal>InnoDB</literal> logs are synchronized
+ by default, and <literal>sync_binlog=1</literal> can be used to
+ synchronize the binary log. The effect of this option is that at
+ restart after a crash, after doing a rollback of transactions,
+ the MySQL server cuts rolled back <literal>InnoDB</literal>
+ transactions from the binary log. This ensures that the binary
+ log reflects the exact data of <literal>InnoDB</literal> tables,
+ and so, that the slave remains in synchrony with the master (not
+ receiving a statement which has been rolled back).
+ </para>
+
+ <para>
+ If the MySQL server discovers at crash recovery that the binary
+ log is shorter than it should have been, it lacks at least one
+ successfully committed <literal>InnoDB</literal> transaction.
+ This should not happen if <literal>sync_binlog=1</literal> and
+ the disk/filesystem do an actual sync when they are requested to
+ (some don't), so the server prints an error message <literal>The
+ binary log <name> is shorter than its expected
+ size</literal>. In this case, this binary log is not correct and
+ replication should be restarted from a fresh snapshot of the
+ master's data.
+ </para>
+
+ <para>
+ The following session variables are written to the binary log
+ and honoured by the replication slave when parsing the binary
+ log:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>FOREIGN_KEY_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>UNIQUE_CHECKS</literal>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>SQL_AUTO_IS_NULL</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <section id="binary-log-formats">
+
+ <title>Binary Logging Formats</title>
+
+ <para>
+ A number of different logging formats are used to record
+ information in the binary log. The exact format employed
+ depends on the version of MySQL being used. There are three
+ logging formats:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Replication capabilities in MySQL originally were based on
+ propagation of SQL statements from master to slave. This
+ is called <emphasis>statement-based logging</emphasis>
+ (SBL). SBL is identified internally using
+ <literal>STATMENT</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ In <emphasis>row-based logging</emphasis> (RBL), the
+ master writes events to the binary log that indicate how
+ individual table rows are affected. RBL is identified
+ internally using <literal>ROW</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ With <emphasis>mixed-based logging</emphasis> (MBL), SBL
+ is used by default, but automatically switches to RBL in
+ particular cases as described below. MBL is the default
+ mode. MBL is identified internally using
+ <literal>MIXED</literal>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ MBL is the default but storage engine being used can also set
+ or limit the logging format according to the capabilities of
+ the storage engine. This helps to eliminate issues when
+ logging, and more specifically replicating, certain statements
+ between the master and slave using the different engines.
+ </para>
+
+ </section>
+
+ <section id="binary-log-setting">
+
+ <title>Setting The Binary Log Format</title>
+
+ <para>
+ The default binary logging format is mixed-based.
+ </para>
+
+ <para>
+ You can force the default replication format by specifying the
+ format type to the
+ <option>--binlog-format=<replaceable>type</replaceable></option>
+ option. When set, all replication slaves connecting to the
+ server will read the events according to this setting. The
+ supported options are:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>ROW</literal> — sets row-based
+ replication as the default.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>STATEMENT</literal> — sets
+ statement-based replication as the default.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>MIXED</literal> — sets mixed-based
+ replication as the default.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ <para>
+ The logging format also can be switched at runtime. To specify
+ the format globally for all clients, set the global value of
+ the <literal>binlog_format</literal> system variable. (To
+ change a global variable you need the <literal>SUPER</literal>
+ privilege.)
+ </para>
+
+ <para>
+ To switch to statement-based format, use either of these
+ statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'STATEMENT';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 1;</userinput>
+</programlisting>
+
+ <para>
+ To switch to row-based format, use either of these statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'ROW';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 2;</userinput>
+</programlisting>
+
+ <para>
+ To switch to mixed format, use either of these statements:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET GLOBAL binlog_format = 'MIXED';</userinput>
+mysql> <userinput>SET GLOBAL binlog_format = 3;</userinput>
+</programlisting>
+
+ <para>
+ Individual clients can control the logging format for their
+ own statements by setting the session value of
+ <literal>binlog_format</literal>. For example:
+ </para>
+
+<programlisting>
+mysql> <userinput>SET SESSION binlog_format = 'STATEMENT';</userinput>
+mysql> <userinput>SET SESSION binlog_format = 'ROW';</userinput>
+mysql> <userinput>SET SESSION binlog_format = 'MIXED';</userinput>
+</programlisting>
+
+ <para>
+ In addition to switching the logging format manually, a slave
+ server may switch the format
+ <emphasis>automatically</emphasis>. This happens when the
+ server is running in either <literal>STATEMENT</literal> or
+ <literal>MIXED</literal> format and encounters a row in the
+ binary log that is written in <literal>ROW</literal> logging
+ format. In that case, the slave switches to row-based
+ replication temporarily for that event, and switches back to
+ the previous format afterwards.
+ </para>
+
+ <para>
+ There are two reasons why you might want to set replication
+ logging on a per-connection basis:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A thread that makes many small changes to the database
+ might want to use row-based logging. A thread that
+ performs updates that match many rows in the
+ <literal>WHERE</literal> clause might want to use
+ statement-based logging because it will be more efficient
+ to log a few statements than many rows.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Some statements require a lot of execution time on the
+ master, but result in just a few rows being modified. It
+ might therefore be beneficial to replicate them using
+ row-based logging.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ There are exceptions when you cannot switch the replication
+ format at runtime:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ From within a stored function or a trigger.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If <literal>NDB</literal> is enabled.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the session is currently in row-based replication
+ mode and has open temporary tables.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ Trying to switch the format in those cases results in an
+ error.
+ </para>
+
+ <para>
+ Switching the replication format at runtime is not recommended
+ when any <emphasis>temporary tables</emphasis> exist, because
+ temporary tables are logged only when using statement-based
+ replication, whereas with row-based replication they are not
+ logged. With mixed replication, temporary tables are usually
+ logged; exceptions happen with user-defined functions (UDF)
+ and with the <function>UUID()</function> function.
+ </para>
+
+ <para>
+ With the binlog format set to <literal>ROW</literal>, many
+ changes are written to the binary log using the row-based
+ format. Some changes, however, still use the statement-based
+ format. Examples include all DDL (data definition language)
+ statements such as <literal>CREATE TABLE</literal>,
+ <literal>ALTER TABLE</literal>, or <literal>DROP
+ TABLE</literal>.
+ </para>
+
+ <para>
+ The <option>--binlog-row-event-max-size</option> option is
+ available for servers that are capable of row-based
+ replication. Rows are stored into the binary log in chunks
+ having a size in bytes not exceeding the value of this option.
+ The value must be a multiple of 256. The default value is
+ 1024.
+ </para>
+
+ <warning>
+ <para>
+ When using <emphasis>statement-based logging</emphasis> in a
+ replication scenario, it is possible for the data on the
+ master and slave to become different if a statement is
+ designed in such a way that the data modification is
+ <firstterm>non-deterministic</firstterm>; that is, it is
+ left to the will of the query optimizer. In general, this is
+ not a good practice even outside of replication. For a
+ detailed explanation of this issue, see
+ <xref linkend="open-bugs"/>.
+ </para>
+ </warning>
+
+ </section>
+
+ <section id="binary-log-mixed">
+
+ <title>Mixed Binary Logging (MBL) Format</title>
+
+ <para>
+ When running in <literal>MIXED</literal> mode, automatic
+ switching from statement-based to row-based replication takes
+ place under the following conditions:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When a DML statement updates an <literal>NDB</literal>
+ table
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a function contains
+ <function role="sql">UUID()</function>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When 2 or more tables with
+ <literal>AUTO_INCREMENT</literal> columns are updated
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When any <literal>INSERT DELAYED</literal> is executed
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When the body of a view requires row-based replication,
+ the statement creating the view also uses it — for
+ example, this occurs when the statement creating a view
+ uses the <function role="sql">UUID()</function> function
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a call to a UDF is involved.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Beginning with MySQL 6.0.4:
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When <function role="sql">FOUND_ROWS()</function> or
+ <function role="sql">ROW_COUNT()</function> is used
+ (Bug #12092, Bug #30244)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When <function role="sql">USER()</function>,
+ <function role="sql">CURRENT_USER()</function>, or
+ <function role="sql" condition="function_current-user">CURRENT_USER</function>
+ is used (Bug #28086)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <note>
+ <para>
+ A warning is generated if you try to log execute a statement
+ in statement-logging mode that should be logged in
+ row-logging mode. The warning will be shown both in the
+ client (and available with <literal>SHOW WARNINGS</literal>)
+ and through the <command>mysqld</command> error log. A
+ warning is added to the <literal>SHOW WARNINGS</literal>
+ table each time a statement is executed. However, only the
+ first statement that generated the warning for each client
+ session is logged to the <literal>mysqld</literal> error log
+ to prevent flooding the error log.
+ </para>
+ </note>
+
+ <para>
+ Mixed based logging is used by default, but in addition to the
+ decisions above, individual engines can also enforce the
+ logging format used when information in a table is updated.
+ </para>
+
+ <para>
+ The logging formats supported by a particular engine are
+ controlled by internal flags. The table below lists the
+ logging formats supported by each of the current engines.
+ </para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <colspec colwidth="50*"/>
+ <colspec colwidth="25*"/>
+ <colspec colwidth="25*"/>
+ <thead>
+ <row>
+ <entry>Engine</entry>
+ <entry>Row-logging supported</entry>
+ <entry>Statement-logging supported</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Archive</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Blackhole</entry>
+ <entry>No</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>CSV</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Example</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Federated</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Heap</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>MyISAM</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>Merge</entry>
+ <entry>Yes</entry>
+ <entry>Yes</entry>
+ </row>
+ <row>
+ <entry>NDB</entry>
+ <entry>Yes</entry>
+ <entry>No</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ Note that an engine can be support either or both logging
+ formats, and the logging capabilities of an individual engine
+ can be further defined as follows
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If an engine supports row-based logging, then the engine
+ is said to be <emphasis>row-logging capable
+ (RLC)</emphasis>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If an engine support statement-based logging, then the
+ engine is said to be <emphasis>statement-logging capable
+ (SLC)</emphasis>.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ When determining what logging mode to use, the capabilities of
+ all the tables in the event are combined. The set of tables is
+ then marked according to these rules:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ A set of tables is defined as <emphasis>row logging
+ restricted (RLR)</emphasis> if the tables are row logging
+ capable but not statement logging capable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A set of tables is defined as <emphasis>statement logging
+ restricted (SLR)</emphasis> if the tables are statement
+ logging capable but not row logging capable.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Once the determination of the possible logging formats
+ required by the statement is complete it is compared to the
+ current <literal>BINLOG_FORMAT</literal> setting. The
+ following table is used to decide how the information is
+ recorded in the binary log or, if appropriate, whether an
+ error is raised. In the table, a safe operation is defined as
+ one that is deterministic. A number of internal rules decide
+ whether the statement is deterministic or not.
+ </para>
+
+ <informaltable>
+ <tgroup cols="6">
+ <colspec colwidth="10*" colname="safe"/>
+ <colspec colwidth="25*" colname="format"/>
+ <colspec colwidth="10*" colname="RLC"/>
+ <colspec colwidth="10*" colname="SLC"/>
+ <colspec colwidth="20*" colname="error"/>
+ <colspec colwidth="25*" colname="logas"/>
+ <spanspec namest="safe" nameend="SLC" spanname="condition"/>
+ <spanspec namest="error" nameend="logas" spanname="action"/>
+ <thead>
+ <row>
+ <entry spanname="condition">Condition</entry>
+ <entry spanname="action">Action</entry>
+ </row>
+ <row>
+ <entry>Safe/unsafe</entry>
+ <entry><literal>BINLOG_FORMAT</literal></entry>
+ <entry>RLC</entry>
+ <entry>SLC</entry>
+ <entry>Error/Warning</entry>
+ <entry>Logged as</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Safe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Warning: unsafe</entry>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>STATEMENT</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry>Warning: unsafe</entry>
+ <entry>STATEMENT</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>MIXED</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>N</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>N</entry>
+ <entry>Y</entry>
+ <entry>Error: not loggable</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>N</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ <row>
+ <entry>Unsafe</entry>
+ <entry>ROW</entry>
+ <entry>Y</entry>
+ <entry>Y</entry>
+ <entry/>
+ <entry>ROW</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>
+ When a warning is produced by the determination, a standard
+ MySQL warning is produced (and is available using
+ <literal>SHOW WARNINGS</literal>). The information is also
+ written to the <command>mysqld</command> error log. Only one
+ error for each error instance per client connection is logged.
+ The log message will include the SQL statement that was
+ attempted.
+ </para>
+
+ </section>
+
+ <section id="binary-log-mysql-database">
+
+ <title>Logging Format for Changes to <literal>mysql</literal> Database Tables</title>
+
+ <para>
+ The contents of the grant tables in the
+ <literal>mysql</literal> database can be modified directly
+ (for example, with <literal>INSERT</literal> or
+ <literal>DELETE</literal>) or indirectly (for example, with
+ <literal>GRANT</literal> or <literal>CREATE USER</literal>).
+ Database tables are written to the binary log using the
+ following rules:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Data manipulation statements that change data in
+ <literal>mysql</literal> database tables directly are
+ logged according to the setting of the
+ <literal>binlog_format</literal> system variable. This
+ pertains to statements such as <literal>INSERT</literal>,
+ <literal>UPDATE</literal>, <literal>DELETE</literal>,
+ <literal>REPLACE</literal>, <literal>DO</literal>,
+ <literal>LOAD DATA INFILE</literal>,
+ <literal>SELECT</literal>, and
+ <literal>TRUNCATE</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Statements that change the <literal>mysql</literal>
+ database indirectly are logged as statements regardless of
+ the value of <literal>binlog_format</literal>. This
+ pertains to statements such as <literal>GRANT</literal>,
+ <literal>REVOKE</literal>, <literal>SET
+ PASSWORD</literal>, <literal>RENAME USER</literal>,
+ <literal>CREATE</literal> (all forms except
+ <literal>CREATE TABLE ... SELECT</literal>),
+ <literal>ALTER</literal> (all forms), and
+ <literal>DROP</literal> (all forms).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ <literal>CREATE TABLE ... SELECT</literal> is a combination of
+ data definition and data manipulation. The <literal>CREATE
+ TABLE</literal> part is logged using statement format and the
+ <literal>SELECT</literal> part is logged according to the
+ value of <literal>binlog_format</literal>.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="slow-query-log">
+
+ <title>The Slow Query Log</title>
+
+ <indexterm>
+ <primary>slow query log</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>slow query log</secondary>
+ </indexterm>
+
+ <para>
+ The slow query log consists of all SQL statements that took more
+ than <literal>long_query_time</literal> seconds to execute. The
+ time to acquire the initial table locks is not counted as
+ execution time. <command>mysqld</command> writes a statement to
+ the slow query log after it has been executed and after all
+ locks have been released, so log order might be different from
+ execution order. The minimum and default values of
+ <literal>long_query_time</literal> are 1 and 10, respectively.
+ Prior to MySQL 6.0.4, the minimum value is 1, and the value for
+ this variable must be an integer. Beginning with MySQL 6.0.4,
+ the default is 0, and a resolution of microseconds is supported
+ when logging to a file. However, the microseconds part is
+ ignored and only integer values are written when logging to
+ tables.
+ </para>
+
+ <para>
+ To enable the slow query log, start <command>mysqld</command>
+ with the
+ <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
+ option, and optionally use <option>--log-output</option> to
+ specify the log destination (as described in
+ <xref linkend="log-tables"/>).
+ </para>
+
+ <para>
+ If no <replaceable>file_name</replaceable> value is given for
+ <option>--log-slow-queries</option>, the default name is
+ <filename><replaceable>host_name</replaceable>-slow.log</filename>.
+ If a filename is given, but not as an absolute pathname, the
+ server writes the file in the data directory.
+ </para>
+
+ <para>
+ When <option>--log-slow-queries</option> is specified, the
+ <option>--slow-query-log</option> option also may be given to
+ specify the initial slow query log state. With no argument or an
+ argument of 0, the option disables the log. If omitted or given
+ with an argument of 1, the option enables the log. If
+ <option>--log--slow-queries</option> is not given,
+ <option>--slow-query-log</option> has no effect.
+ </para>
+
+ <para>
+ The global <literal>slow_query_log</literal> and
+ <literal>slow_query_log_file</literal> system variables provide
+ runtime control over the slow query log. Set
+ <literal>slow_query_log</literal> to 0 (or
+ <literal>OFF</literal>) to disable the log or to 1 (or
+ <literal>ON</literal>) to enable it. Set
+ <literal>general_log_file</literal> to specify the name of the
+ log file. If a log file already is open, it is closed and the
+ new file is opened.
+ </para>
+
+ <para>
+ When the slow query log is enabled, output is written to any
+ destinations specified by the <option>--log-output</option>
+ option or <literal>log_output</literal> system variable. Note
+ that if the destination is <literal>NONE</literal>, no output is
+ written even if the slow query log is enabled. Setting the log
+ filename has no effect on logging if the log destination value
+ does not contain <literal>FILE</literal>.
+ </para>
+
+ <para>
+ The slow query log can be used to find queries that take a long
+ time to execute and are therefore candidates for optimization.
+ However, examining a long slow query log can become a difficult
+ task. To make this easier, you can process the slow query log
+ using the <command>mysqldumpslow</command> command to summarize
+ the queries that appear in the log. Use <command>mysqldumpslow
+ --help</command> to see the options that this command supports.
+ </para>
+
+ <para>
+ In MySQL ¤t-series;, queries that do not use indexes are
+ logged in the slow query log if the
+ <option>--log-queries-not-using-indexes</option> option is
+ specified. See <xref linkend="server-options"/>.
+ </para>
+
+ <formalpara role="mnmas">
+
+ <title>MySQL Enterprise</title>
+
+ <para>
+ Excessive table scans are indicative of missing or poorly
+ optimized indexes. Using an advisor specifically designed for
+ the task, the MySQL Enterprise Monitor can identify such
+ problems and offer advice on resolution. For more information
+ see <ulink url="&base-url-enterprise;advisors.html"/>.
+ </para>
+
+ </formalpara>
+
+ <para>
+ In MySQL ¤t-series;, the
+ <option>--log-slow-admin-statements</option> server option
+ enables you to request logging of slow administrative statements
+ such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
+ TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
+ query log.
+ </para>
+
+ <para>
+ Queries handled by the query cache are not added to the slow
+ query log, nor are queries that would not benefit from the
+ presence of an index because the table has zero rows or one row.
+ </para>
+
+ </section>
+
+ <section id="log-file-maintenance">
+
+ <title>Server Log Maintenance</title>
+
+ <indexterm>
+ <primary>files</primary>
+ <secondary>log</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>maintaining</primary>
+ <secondary>log files</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>log files</primary>
+ <secondary>maintaining</secondary>
+ </indexterm>
+
+ <para>
+ MySQL Server can create a number of different log files that
+ make it easy to see what is going on. See
+ <xref linkend="log-files"/>. However, you must clean up these
+ files regularly to ensure that the logs do not take up too much
+ disk space.
+ </para>
+
+ <para>
+ When using MySQL with logging enabled, you may want to back up
+ and remove old log files from time to time and tell MySQL to
+ start logging to new files. See <xref linkend="backup"/>.
+ </para>
+
+ <para>
+ On a Linux (Red Hat) installation, you can use the
+ <literal>mysql-log-rotate</literal> script for this. If you
+ installed MySQL from an RPM distribution, this script should
+ have been installed automatically. You should be careful with
+ this script if you are using the binary log for replication. You
+ should not remove binary logs until you are certain that their
+ contents have been processed by all slaves.
+ </para>
+
+ <para>
+ On other systems, you must install a short script yourself that
+ you start from <command>cron</command> (or its equivalent) for
+ handling log files.
+ </para>
+
+ <para>
+ For the binary log, you can set the
+ <literal>expire_logs_days</literal> system variable to expire
+ binary log files automatically after a given number of days (see
+ <xref linkend="server-system-variables"/>). If you are using
+ replication, you should set the variable no lower than the
+ maximum number of days your slaves might lag behind the master.
+ </para>
+
+ <para>
+ You can force MySQL to start using new log files by issuing a
+ <literal>FLUSH LOGS</literal> statement or executing
+ <command>mysqladmin flush-logs</command> or <command>mysqladmin
+ refresh</command>. See <xref linkend="flush"/>, and
+ <xref linkend="mysqladmin"/>.
+ </para>
+
+ <para>
+ A log flushing operation does the following:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If general query logging (<option>--log</option>) or slow
+ query logging (<option>--log-slow-queries</option>) to a log
+ file is enabled, the server closes and reopens the general
+ query log file or slow query log file.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If binary logging (<option>--log-bin</option>) is used, the
+ server closes the current log file and opens a new log file
+ with the next sequence number.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If the server was given an error log filename with the
+ <option>--log-error</option> option, it renames the error
+ log with the suffix <literal>-old</literal> and creates a
+ new empty error log file.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ The server creates a new binary log file when you flush the
+ logs. However, it just closes and reopens the general and slow
+ query log files. To cause new files to be created on Unix,
+ rename the current logs before flushing them. At flush time, the
+ server will open new logs with the original names. For example,
+ if the general and slow query logs are named
+ <filename>mysql.log</filename> and
+ <filename>mysql-slow.log</filename>, you can use a series of
+ commands like this:
+ </para>
+
+<programlisting>
+shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
+shell> <userinput>mv mysql.log mysql.old</userinput>
+shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
+shell> <userinput>mysqladmin flush-logs</userinput>
+</programlisting>
+
+ <para>
+ At this point, you can make a backup of
+ <filename>mysql.old</filename> and
+ <filename>mysql-slow.log</filename> and then remove them from
+ disk.
+ </para>
+
+ <para>
+ On Windows, you cannot rename log files while the server has
+ them open. You must stop the server and rename them, and then
+ restart the server to create new logs.
+ </para>
+
+ <para>
+ You can disable the general query log or slow query log at
+ runtime:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'OFF';
+SET GLOBAL slow_query_log = 'OFF';
+</programlisting>
+
+ <para>
+ With the logs disabled, rename the log files externally; for
+ example, from the command line. Then enable the logs again:
+ </para>
+
+<programlisting>
+SET GLOBAL general_log = 'ON';
+SET GLOBAL slow_query_log = 'ON';
+</programlisting>
+
+ <para>
+ This method works on any platform and does not require a server
+ restart.
+ </para>
+
+ </section>
+
+ </section>
+
<section id="security">
<title>General Security Issues</title>
@@ -21523,2345 +23862,6 @@
</section>
- <section id="log-files">
-
- <title>MySQL Server Logs</title>
-
- <indexterm>
- <primary>log files</primary>
- </indexterm>
-
- <para>
- MySQL has several different logs that can help you find out what
- is going on inside <command>mysqld</command>:
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colwidth="30*"/>
- <colspec colwidth="70*"/>
- <tbody>
- <row>
- <entry><emphasis role="bold">Log Type</emphasis></entry>
- <entry><emphasis role="bold">Information Written to Log</emphasis></entry>
- </row>
- <row>
- <entry>The error log</entry>
- <entry>Problems encountered starting, running, or stopping
- <command>mysqld</command></entry>
- </row>
- <row>
- <entry>The general query log</entry>
- <entry>Established client connections and statements received from clients</entry>
- </row>
- <row>
- <entry>The binary log</entry>
- <entry>All statements that change data (also used for replication)</entry>
- </row>
- <row>
- <entry>The slow query log</entry>
- <entry>All queries that took more than <literal>long_query_time</literal>
- seconds to execute or didn't use indexes</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- By default, all log files are created in the
- <command>mysqld</command> data directory. You can force
- <command>mysqld</command> to close and reopen the log files (or in
- some cases switch to a new log) by flushing the logs. Log flushing
- occurs when you issue a <literal>FLUSH LOGS</literal> statement or
- execute <command>mysqladmin flush-logs</command> or
- <command>mysqladmin refresh</command>. See
- <xref linkend="flush"/>, and <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- If you are using MySQL replication capabilities, slave replication
- servers maintain additional log files called relay logs.
- <xref linkend="replication"/>, discusses relay log contents and
- configuration.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The MySQL Enterprise Monitor provides a number of advisors
- specifically related to the various log files. For more
- information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- The server can write general query and slow query entries to log
- tables, log files, or both. For details, see
- <xref linkend="log-tables"/>.
- </para>
-
- <para>
- You can also control during runtimethe general query and slow
- query logs. You can enable or disable logging, or change the name
- of the log file. See <xref linkend="query-log"/>, and
- <xref linkend="slow-query-log"/>.
- </para>
-
- <section id="log-tables">
-
- <title>Selecting General Query and Slow Query Log Output Destinations</title>
-
- <para>
- MySQL Server provides flexible control over the destination for
- log output. Log entries can be written to log files or to the
- <literal>general_log</literal> and <literal>slow_log</literal>
- tables in the <literal>mysql</literal> database. If logging is
- enabled, either or both destinations can be selected.
- </para>
-
- <note>
- <para>
- The log tables are created during the installation procedure
- along with the other system tables. If you upgrade MySQL from
- a release older than 5.1.6 to MySQL 5.1.6 or higher, you must
- upgrade the system tables after upgrading to make sure that
- the log tables exist. See <xref linkend="mysql-upgrade"/>.
- </para>
- </note>
-
- <para>
- Currently, logging to tables incurs significantly more server
- overhead than logging to files. If you enable the general log or
- slow query log and require highest performance, you should log
- to files and not to tables.
- </para>
-
- <para>
- The <option>--log-output</option> option specifies the
- destination for log output, if logging is enabled, but the
- option does not in itself enable the logs. The syntax for this
- option is
- <option>--log-output[=<replaceable>value</replaceable>,...]</option>:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If <option>--log-output</option> is given with a value, the
- value can be a comma-separated list of one or more of the
- words <literal>TABLE</literal> (log to tables),
- <literal>FILE</literal> (log to files), or
- <literal>NONE</literal> (do not log to tables or files).
- <literal>NONE</literal>, if present, takes precedence over
- any other specifiers.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <option>--log-output</option> is omitted or given without
- a value, the effect is the same as
- <option>--log-output=FILE</option>. That is, the file
- destination is selected.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <option>--log-output</option> option also sets the value
- of the global <literal>log_output</literal> system variable,
- which can be modified at runtime to change the logging
- destination for the server while it executes.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The
- <option>--log[=<replaceable>file_name</replaceable>]</option>
- option, if given, enables logging to the general query log for
- the selected log destinations. Similarly, the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option, if given, enables logging to the slow query log for the
- selected destinations. If you specify either option, the server
- opens the corresponding log file and writes startup messages to
- it. However, logging of queries to the file does not occur
- unless the <literal>FILE</literal> log destination is selected.
- </para>
-
- <para>
- Examples:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- To write general query log entries to the log table and the
- log file, use <option>--log-output=TABLE,FILE</option> to
- select both log destinations and the <option>--log</option>
- option to enable the general query log.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To write general and slow query log entries only to the log
- tables, use <option>--log-output=TABLE</option> to select
- tables as the log destination and the <option>--log</option>
- and <option>--log-slow-queries</option> options to enable
- both logs.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To write slow query log entries only to the log file, use
- <option>--log-output=FILE</option> to select files as the
- log destination and the <option>--log-slow-queries</option>
- option to enable the slow query log. (In this case, because
- the default log destination is <literal>FILE</literal>, you
- could omit the <option>--log-output</option> option.)
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Several system variables are associated with log tables and
- files:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- The global <literal>general_log</literal> and
- <literal>slow_query_log</literal> variables indicate whether
- the general query log and slow query log are enabled
- (<literal>ON</literal>) or disabled
- (<literal>OFF</literal>). You can set these variables at
- runtime to control whether the logs are enabled.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The global <literal>general_log_file</literal> and
- <literal>slow_query_log_file</literal> variables indicate
- the names of the general query log and slow query log files.
- You can set these variables at runtime to change the names
- of the log files. (If the <option>--log</option> and
- <literal>--log-slow-queries</literal> options were not
- given, the variable values are set to the default log
- filenames.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- The session <literal>sql_log_off</literal> variable can be
- set to <literal>ON</literal> or <literal>OFF</literal> to
- disable or enable general query logging for the current
- connection.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The use of tables for log output offers the following benefits:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Log entries have a standard format. To display the current
- structure of the log tables, use these statements:
- </para>
-
-<programlisting>
-SHOW CREATE TABLE mysql.general_log;
-SHOW CREATE TABLE mysql.slow_log;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- Log contents are accessible via SQL statements. This enables
- the use of queries that select only those log entries that
- satisfy specific criteria. For example, to select log
- contents associated with a particular client (which can be
- useful for identifying problematic queries from that
- client), it is easier to do this using a log table than a
- log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Logs are accessible remotely through any client that can
- connect to the server and issue queries (if the client has
- the appropriate log table privileges). It's not necessary to
- log in to the server host and directly access the
- filesystem.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The log table implementation has the following characteristics:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- In general, the primary purpose of log tables is to provide
- an interface for users to observe the runtime execution of
- the server, not to interfere with its runtime execution.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>CREATE TABLE</literal>, <literal>ALTER
- TABLE</literal>, and <literal>DROP TABLE</literal> are valid
- operations on a log table. For <literal>ALTER
- TABLE</literal> and <literal>DROP TABLE</literal>, the log
- table cannot be in use and must be disabled, as described
- later.
- </para>
- </listitem>
-
- <listitem>
- <para>
- By default, the log tables use the <literal>CSV</literal>
- storage engine that writes data in comma-separated values
- format. For users who have access to the
- <filename>.CSV</filename> files that contain log table data,
- the files are easy to import into other programs such as
- spreadsheets that can process CSV input.
- </para>
-
- <para>
- The log tables can be altered to use the
- <literal>MyISAM</literal> storage engine. You cannot use
- <literal>ALTER TABLE</literal> to alter a log table that is
- in use. The log must be disabled first. No engines other
- than <literal>CSV</literal> or <literal>MyISAM</literal> are
- legal for the log tables.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To disable logging so that you can alter (or drop) a log
- table, you can use the following strategy. The example uses
- the general query log; the procedure for the slow query log
- is similar but uses the <literal>slow_log</literal> table
- and <literal>slow_query_log</literal> system variable.
- </para>
-
-<programlisting>
-SET @old_log_state = @@global.general_log;
-SET GLOBAL general_log = 'OFF';
-ALTER TABLE mysql.general_log ENGINE = MyISAM;
-SET GLOBAL general_log = @old_log_state;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- <literal>TRUNCATE TABLE</literal> is a valid operation on a
- log table. It can be used to expire log entries.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>RENAME TABLE</literal> is a valid operation on a
- log table. You can atomically rename a log table (to perform
- log rotation, for example) using the following strategy:
- </para>
-
-<programlisting>
-USE mysql;
-CREATE TABLE IF NOT EXISTS general_log2 LIKE general_log;
-RENAME TABLE general_log TO general_log_backup, general_log2 TO general_log;
-</programlisting>
- </listitem>
-
- <listitem>
- <para>
- <literal>LOCK TABLES</literal> cannot be used on a log
- table.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>INSERT</literal>, <literal>DELETE</literal>, and
- <literal>UPDATE</literal> cannot be used on a log table.
- These operations are allowed only internally to the server
- itself.
- </para>
- </listitem>
-
- <listitem>
- <para>
- The global read lock and the state of the global
- <literal>read_only</literal> system variable have no effect
- on log tables. The server can always write to the log
- tables.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Entries written to the log tables are not written to the
- binary log and thus are not replicated to slave servers.
- </para>
- </listitem>
-
- <listitem>
- <para>
- To flush the log tables or log files, use <literal>FLUSH
- TABLES</literal> or <literal>FLUSH LOGS</literal>,
- respectively.
- </para>
- </listitem>
-
- <listitem>
- <para>
- It is not allowed to partition log tables.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
- <section id="error-log">
-
- <title>The Error Log</title>
-
- <para>
- The error log contains information indicating when
- <command>mysqld</command> was started and stopped and also any
- critical errors that occur while the server is running. If
- <command>mysqld</command> notices a table that needs to be
- automatically checked or repaired, it writes a message to the
- error log.
- </para>
-
- <para>
- On some operating systems, the error log contains a stack trace
- if <command>mysqld</command> dies. The trace can be used to
- determine where <command>mysqld</command> died. See
- <ulink url="http://forge.mysql.com/wiki/MySQL_Internals_Porting">MySQL
- Internals: Porting</ulink>.
- </para>
-
- <para>
- You can specify where <command>mysqld</command> writes the error
- log with the
- <option>--log-error[=<replaceable>file_name</replaceable>]</option>
- option. If no <replaceable>file_name</replaceable> value is
- given, <command>mysqld</command> uses the name
- <filename><replaceable>host_name</replaceable>.err</filename> by
- default and writes the file in the data directory. If you
- execute <literal>FLUSH LOGS</literal>, the error log is renamed
- with the suffix <literal>-old</literal> and
- <command>mysqld</command> creates a new empty log file. (No
- renaming occurs if the <option>--log-error</option> option was
- not given to <command>mysqld</command>.)
- </para>
-
- <para>
- If you do not specify <option>--log-error</option>, or (on
- Windows) if you use the <option>--console</option> option,
- errors are written to <literal>stderr</literal>, the standard
- error output. Usually this is your terminal.
- </para>
-
- <para>
- On Windows, error output is always written to the
- <literal>.err</literal> file if <option>--console</option> is
- not given.
- </para>
-
- <para>
- The <option>--log-warnings</option> option or
- <literal>log_warnings</literal> system variable can be used to
- control warning logging to the error log. The default value is
- enabled (1). Warning logging can be disabled using a value of 0.
- If the value is greater than 1, aborted connections are written
- to the error log. See <xref linkend="communication-errors"/>.
- </para>
-
- <para>
- If you use <command>mysqld_safe</command> to start
- <command>mysqld</command>, <command>mysqld_safe</command>
- arranges for <command>mysqld</command> to write error messages
- to a log file or to <literal>syslog</literal>
- <command>mysqld_safe</command> has three error-logging options,
- <option>--syslog</option>, <option>--skip-syslog</option>, and
- <option>--log-error</option>. The default with no logging
- options or with <option>--skip-syslog</option> is to use the
- default log file. To explicitly specify use of an error log
- file, specify
- <option>--log-error=<replaceable>file_name</replaceable></option>
- to <command>mysqld_safe</command>, and
- <command>mysqld_safe</command> will arrange for
- <command>mysqld</command> to write messages to a log file. To
- use <literal>syslog</literal> instead, specify the
- <option>--syslog</option> option.
- </para>
-
- <para>
- If you specify <option>--log-error</option> in an option file in
- a section that <command>mysqld</command> reads,
- <command>mysqld_safe</command> also will find and use the
- option.
- </para>
-
- <para>
- For logging to <literal>syslog</literal>, messages from
- <command>mysqld_safe</command> and <command>mysqld</command> are
- written with a tag of <literal>mysqld_safe</literal> and
- <literal>mysqld</literal>, respectively. To specify a suffix for
- the tag, use
- <option>--syslog-tag=<replaceable>tag</replaceable></option>,
- which modifies the tags to be
- <literal>mysqld_safe-<replaceable>tag</replaceable></literal>
- and <literal>mysqld-<replaceable>tag</replaceable></literal>.
- </para>
-
- <para>
- If <command>mysqld_safe</command> is used to start
- <command>mysqld</command> and <command>mysqld</command> dies
- unexpectedly, <command>mysqld_safe</command> notices that it
- needs to restart <command>mysqld</command> and writes a
- <literal>restarted mysqld</literal> message to the error log.
- </para>
-
- </section>
-
- <section id="query-log">
-
- <title>The General Query Log</title>
-
- <indexterm>
- <primary>general query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>general query log</secondary>
- </indexterm>
-
- <para>
- The general query log is a general record of what
- <command>mysqld</command> is doing. The server writes
- information to this log when clients connect or disconnect, and
- it logs each SQL statement received from clients. The general
- query log can be very useful when you suspect an error in a
- client and want to know exactly what the client sent to
- <command>mysqld</command>.
- </para>
-
- <para>
- <command>mysqld</command> writes statements to the query log in
- the order that it receives them, which might differ from the
- order in which they are executed. This logging order contrasts
- to the binary log, for which statements are written after they
- are executed but before any locks are released. (Also, the query
- log contains all statements, whereas the binary log does not
- contain statements that only select data.)
- </para>
-
- <para>
- To enable the general query log, start <command>mysqld</command>
- with the
- <option>--log[=<replaceable>file_name</replaceable>]</option> or
- <option>-l [<replaceable>file_name</replaceable>]</option>
- option, and optionally use <option>--log-output</option> to
- specify the log destination (as described in
- <xref linkend="log-tables"/>).
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log</option> or <option>-l</option>, the default name
- is <filename><replaceable>host_name</replaceable>.log</filename>
- in the data directory. If a filename is given, but not as an
- absolute pathname, the server writes the file in the data
- directory.
- </para>
-
- <para>
- When <option>--log</option> or <option>-l</option> is specified,
- the <option>--general-log</option> option also may be given to
- specify the initial general query log state. With no argument or
- an argument of 0, the option disables the log. If omitted or
- given with an argument of 1, the option enables the log. If
- <option>--log</option> or <option>-l</option> is not specified,
- <option>--general-log</option> has no effect.
- </para>
-
- <para>
- The global <literal>general_log</literal> and
- <literal>general_log_file</literal> system variables provide
- runtime control over the general query log. Set
- <literal>general_log</literal> to 0 (or <literal>OFF</literal>)
- to disable the log or to 1 (or <literal>ON</literal>) to enable
- it. Set <literal>general_log_file</literal> to specify the name
- of the log file. If a log file already is open, it is closed and
- the new file is opened.
- </para>
-
- <para>
- When the general query log is enabled, output is written to any
- destinations specified by the <option>--log-output</option>
- option or <literal>log_output</literal> system variable. Note
- that if the destination is <literal>NONE</literal>, no output is
- written even if the general log is enabled. Setting the log
- filename has no effect on logging if the log destination value
- does not contain <literal>FILE</literal>.
- </para>
-
- <para>
- Server restarts and log flushing do not cause a new general
- query log file to be generated (although flushing closes and
- reopens it). On Unix, you can rename the file and create a new
- one by using the following commands:
- </para>
-
-<programlisting>
-shell> <userinput>mv <replaceable>host_name</replaceable>.log <replaceable>host_name</replaceable>-old.log</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-shell> <userinput>cp <replaceable>host_name</replaceable>-old.log <replaceable>backup-directory</replaceable></userinput>
-shell> <userinput>rm <replaceable>host_name</replaceable>-old.log</userinput>
-</programlisting>
-
- <para>
- On Windows, you cannot rename the log file while the server has
- it open. You must stop the server and rename the file, and then
- restart the server to create a new log file.
- </para>
-
- <para>
- You can disable the general query log at runtime:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'OFF';
-</programlisting>
-
- <para>
- With the log disabled, rename the log file externally; for
- example, from the command line. Then enable the log again:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'ON';
-</programlisting>
-
- <para>
- This method works on any platform and does not require a server
- restart.
- </para>
-
- <para>
- The session <literal>sql_log_off</literal> variable can be set
- to <literal>ON</literal> or <literal>OFF</literal> to disable or
- enable general query logging for the current connection.
- </para>
-
- </section>
-
- <section id="binary-log">
-
- <title>The Binary Log</title>
-
- <indexterm>
- <primary>binary log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>binary log</secondary>
- </indexterm>
-
- <para>
- The binary log contains all statements that update data or
- potentially could have updated it (for example, a
- <literal>DELETE</literal> which matched no rows). Statements are
- stored in the form of <quote>events</quote> that describe the
- modifications. The binary log also contains information about
- how long each statement took that updated data.
- </para>
-
- <para>
- The binary log is not used for statements such as
- <literal>SELECT</literal> or <literal>SHOW</literal> that do not
- modify data. If you want to log all statements (for example, to
- identify a problem query), use the general query log. See
- <xref linkend="query-log"/>.
- </para>
-
- <para>
- The primary purpose of the binary log is to be able to update
- databases during a restore operation as fully as possible,
- because the binary log contains all updates done after a backup
- was made. The binary log is also used on master replication
- servers as a record of the statements to be sent to slave
- servers. See <xref linkend="replication"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- The binary log can also be used to track significant DDL
- events. Analyzing the binary log in this way is an integral
- part of the MySQL Enterprise Monitor. For more information see
- <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- Running the server with the binary log enabled makes performance
- about 1% slower. However, the benefits of the binary log for
- restore operations and in allowing you to set up replication
- generally outweigh this minor performance decrement.
- </para>
-
- <para>
- When started with the
- <option>--log-bin[=<replaceable>base_name</replaceable>]</option>
- option, <command>mysqld</command> writes a log file containing
- all SQL statements that update data (both DDL and DML
- statements). If no <replaceable>base_name</replaceable> value is
- given, the default name is the value of the
- <literal>pid-file</literal> option (which by default is the name
- of host machine) followed by <literal>-bin</literal>. If the
- basename is given, but not as an absolute pathname, the server
- writes the file in the data directory. It is recommended that
- you specify a basename; see <xref linkend="open-bugs"/>, for the
- reason.
- </para>
-
- <para>
- If you supply an extension in the log name (for example,
- <option>--log-bin=<replaceable>base_name.extension</replaceable></option>),
- the extension is silently removed and ignored.
- </para>
-
- <para>
- <command>mysqld</command> appends a numeric extension to the
- binary log basename. The number increases each time the server
- creates a new log file, thus creating an ordered series of
- files. The server creates a new binary log file each time it
- starts or flushes the logs. The server also creates a new binary
- log file automatically when the current log's size reaches
- <literal>max_binlog_size</literal>. A binary log file may become
- larger than <literal>max_binlog_size</literal> if you are using
- large transactions because a transaction is written to the file
- in one piece, never split between files.
- </para>
-
- <para>
- To keep track of which binary log files have been used,
- <command>mysqld</command> also creates a binary log index file
- that contains the names of all used binary log files. By default
- this has the same basename as the binary log file, with the
- extension <literal>'.index'</literal>. You can change the name
- of the binary log index file with the
- <option>--log-bin-index[=<replaceable>file_name</replaceable>]</option>
- option. You should not manually edit this file while
- <command>mysqld</command> is running; doing so would confuse
- <command>mysqld</command>.
- </para>
-
- <para>
- Replication slave servers by default do not write to their own
- binary log any statements that are received from the replication
- master. To cause these statements to be logged, start the slave
- with the <option>--log-slave-updates</option> option.
- </para>
-
- <para>
- Writes to the binary log file and binary log index file are
- handled in the same way as writes to <literal>MyISAM</literal>
- tables. See <xref linkend="full-disk"/>.
- </para>
-
- <para>
- You can delete all binary log files with the <literal>RESET
- MASTER</literal> statement, or a subset of them with
- <literal>PURGE MASTER LOGS</literal>. See
- <xref linkend="reset"/>, and
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- The binary log format has some known limitations that can affect
- recovery from backups. See
- <xref linkend="replication-features"/>.
- </para>
-
- <para>
- Binary logging for stored routines and triggers is done as
- described in <xref linkend="stored-procedure-logging"/>.
- </para>
-
- <para>
- You can use the following options to <command>mysqld</command>
- to affect what is logged to the binary log. See also the
- discussion that follows this option list.
- </para>
-
- <para>
- If you are using replication, the options described here affect
- which statements are sent by a master server to its slaves.
- There are also options for slave servers that control which
- statements received from the master to execute or ignore. For
- details, see <xref linkend="replication-options"/>.
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para id="option_mysqld_binlog-do-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-do-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-do-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-do-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to restrict binary logging to updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). All other databases
- that are not explicitly mentioned are ignored. If you use
- this option, you should ensure that you do updates only in
- the default database.
- </para>
-
- <para>
- There is an exception to this for <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. The server uses
- the database named in the statement (not the default
- database) to decide whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-do-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement is
- <emphasis>not</emphasis> written into the binary log.
- </para>
-
- <para>
- To log multiple databases, use multiple options, specifying
- the option once for each database.
- </para>
- </listitem>
-
- <listitem>
- <para id="option_mysqld_binlog-ignore-db">
- <indexterm>
- <primary>mysqld</primary>
- <secondary>binlog-ignore-db option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>binlog-ignore-db option</primary>
- <secondary>mysqld</secondary>
- </indexterm>
-
- <option>--binlog-ignore-db=<replaceable>db_name</replaceable></option>
- </para>
-
- <para>
- Tell the server to suppress binary logging of updates for
- which the default database is
- <replaceable>db_name</replaceable> (that is, the database
- selected by <literal>USE</literal>). If you use this option,
- you should ensure that you do updates only in the default
- database.
- </para>
-
- <para>
- As with the <option>--binlog-do-db</option> option, there is
- an exception for the <literal>CREATE DATABASE</literal>,
- <literal>ALTER DATABASE</literal>, and <literal>DROP
- DATABASE</literal> statements. The server uses the database
- named in the statement (not the default database) to decide
- whether it should log the statement.
- </para>
-
- <para>
- An example of what does not work as you might expect: If the
- server is started with
- <literal>binlog-ignore-db=sales</literal>, and you run
- <literal>USE prices; UPDATE sales.january SET
- amount=amount+1000;</literal>, this statement
- <emphasis>is</emphasis> written into the binary log.
- </para>
-
- <para>
- To ignore multiple databases, use multiple options,
- specifying the option once for each database.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server evaluates the options for logging or ignoring updates
- to the binary log according to the following rules. As described
- previously, there is an exception for the <literal>CREATE
- DATABASE</literal>, <literal>ALTER DATABASE</literal>, and
- <literal>DROP DATABASE</literal> statements. In those cases, the
- database being <emphasis>created, altered, or dropped</emphasis>
- replaces the default database in the following rules:
- </para>
-
- <orderedlist>
-
- <listitem>
- <para>
- Are there <option>--binlog-do-db</option> or
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Write the statement to the binary log and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some rules (<option>--binlog-do-db</option>,
- <option>--binlog-ignore-db</option>, or both). Is there a
- default database (has any database been selected by
- <literal>USE</literal>?)?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement, and
- exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Yes: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There is a default database. Are there some
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Does the default database match any of the
- <option>--binlog-do-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Write the statement and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Do <emphasis>not</emphasis> write the statement,
- and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- No: Go to the next step.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>
- There are some <option>--binlog-ignore-db</option> rules.
- Does the default database match any of the
- <option>--binlog-ignore-db</option> rules?
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Yes: Do not write the statement, and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- No: Write the query and exit.
- </para>
- </listitem>
-
- </itemizedlist>
- </listitem>
-
- </orderedlist>
-
- <para>
- For example, a slave running with only
- <option>--binlog-do-db=sales</option> does not write to the
- binary log any statement for which the default database is
- different from <literal>sales</literal> (in other words,
- <option>--binlog-do-db</option> can sometimes mean <quote>ignore
- other databases</quote>).
- </para>
-
- <para>
- If you are using replication, you should not delete old binary
- log files until you are sure that no slave still needs to use
- them. For example, if your slaves never run more than three days
- behind, once a day you can execute <command>mysqladmin
- flush-logs</command> on the master and then remove any logs that
- are more than three days old. You can remove the files manually,
- but it is preferable to use <literal>PURGE MASTER
- LOGS</literal>, which also safely updates the binary log index
- file for you (and which can take a date argument). See
- <xref linkend="purge-master-logs"/>.
- </para>
-
- <para>
- A client that has the <literal>SUPER</literal> privilege can
- disable binary logging of its own statements by using a
- <literal>SET SQL_LOG_BIN=0</literal> statement. See
- <xref linkend="set-option"/>.
- </para>
-
- <para>
- You can display the contents of binary log files with the
- <command>mysqlbinlog</command> utility. This can be useful when
- you want to reprocess statements in the log. For example, you
- can update a MySQL server from the binary log as follows:
- </para>
-
-<programlisting>
-shell> <userinput>mysqlbinlog <replaceable>log_file</replaceable> | mysql -h <replaceable>server_name</replaceable></userinput>
-</programlisting>
-
- <para>
- See <xref linkend="mysqlbinlog"/>, for more information on the
- <command>mysqlbinlog</command> utility and how to use it.
- <command>mysqlbinlog</command> also can be used with relay log
- files because they are written using the same format as binary
- log files.
- </para>
-
- <para>
- Binary logging is done immediately after a statement completes
- but before any locks are released or any commit is done. This
- ensures that the log is logged in execution order.
- </para>
-
- <para>
- Updates to non-transactional tables are stored in the binary log
- immediately after execution. Within an uncommitted transaction,
- all updates (<literal>UPDATE</literal>,
- <literal>DELETE</literal>, or <literal>INSERT</literal>) that
- change transactional tables such as <literal>InnoDB</literal>
- tables are cached until a <literal>COMMIT</literal> statement is
- received by the server. At that point, <command>mysqld</command>
- writes the entire transaction to the binary log before the
- <literal>COMMIT</literal> is executed. When the thread that
- handles the transaction starts, it allocates a buffer of
- <literal>binlog_cache_size</literal> to buffer statements. If a
- statement is bigger than this, the thread opens a temporary file
- to store the transaction. The temporary file is deleted when the
- thread ends.
- </para>
-
- <para>
- Modifications to non-transactional tables cannot be rolled back.
- If a transaction that is rolled back includes modifications to
- non-transactional tables, the entire transaction is logged with
- a <literal>ROLLBACK</literal> statement at the end to ensure
- that the modifications to those tables are replicated.
- </para>
-
- <para>
- The <literal>Binlog_cache_use</literal> status variable shows
- the number of transactions that used this buffer (and possibly a
- temporary file) for storing statements. The
- <literal>Binlog_cache_disk_use</literal> status variable shows
- how many of those transactions actually had to use a temporary
- file. These two variables can be used for tuning
- <literal>binlog_cache_size</literal> to a large enough value
- that avoids the use of temporary files.
- </para>
-
- <para>
- The <literal>max_binlog_cache_size</literal> system variable
- (default 4GB, which is also the maximum) can be used to restrict
- the total size used to cache a multiple-statement transaction.
- If a transaction is larger than this many bytes, it fails and
- rolls back. The minimum value is 4096.
- </para>
-
- <para>
- If you are using the binary log and row based logging,
- concurrent inserts are converted to normal inserts for
- <literal>CREATE ... SELECT</literal> or <literal>INSERT ...
- SELECT</literal> statement. This is done to ensure that you can
- re-create an exact copy of your tables by applying the log
- during a backup operation. If you are using statement based
- logging then the original statement is written to the log.
- </para>
-
- <para>
- Note that the binary log format is different in MySQL
- ¤t-series; from previous versions of MySQL, due to
- enhancements in replication. See
- <xref linkend="replication-compatibility"/>.
- </para>
-
- <para>
- By default, the binary log is not synchronized to disk at each
- write. So if the operating system or machine (not only the MySQL
- server) crashes, there is a chance that the last statements of
- the binary log are lost. To prevent this, you can make the
- binary log be synchronized to disk after every
- <replaceable>N</replaceable> writes to the binary log, with the
- <literal>sync_binlog</literal> system variable. See
- <xref linkend="server-system-variables"/>. 1 is the safest value
- for <literal>sync_binlog</literal>, but also the slowest. Even
- with <literal>sync_binlog</literal> set to 1, there is still the
- chance of an inconsistency between the table content and binary
- log content in case of a crash. For example, if you are using
- <literal>InnoDB</literal> tables and the MySQL server processes
- a <literal>COMMIT</literal> statement, it writes the whole
- transaction to the binary log and then commits this transaction
- into <literal>InnoDB</literal>. If the server crashes between
- those two operations, the transaction is rolled back by
- <literal>InnoDB</literal> at restart but still exists in the
- binary log. To resolve this, you should set
- <option>--innodb_support_xa</option> to 1. Although this option
- is related to the support of XA transactions in InnoDB, it also
- ensures that the binary log and InnoDB data files are
- synchronized.
- </para>
-
- <para>
- For this option to provide a greater degree of safety, the MySQL
- server should also be configured to synchronize the binary log
- and the <literal>InnoDB</literal> logs to disk at every
- transaction. The <literal>InnoDB</literal> logs are synchronized
- by default, and <literal>sync_binlog=1</literal> can be used to
- synchronize the binary log. The effect of this option is that at
- restart after a crash, after doing a rollback of transactions,
- the MySQL server cuts rolled back <literal>InnoDB</literal>
- transactions from the binary log. This ensures that the binary
- log reflects the exact data of <literal>InnoDB</literal> tables,
- and so, that the slave remains in synchrony with the master (not
- receiving a statement which has been rolled back).
- </para>
-
- <para>
- If the MySQL server discovers at crash recovery that the binary
- log is shorter than it should have been, it lacks at least one
- successfully committed <literal>InnoDB</literal> transaction.
- This should not happen if <literal>sync_binlog=1</literal> and
- the disk/filesystem do an actual sync when they are requested to
- (some don't), so the server prints an error message <literal>The
- binary log <name> is shorter than its expected
- size</literal>. In this case, this binary log is not correct and
- replication should be restarted from a fresh snapshot of the
- master's data.
- </para>
-
- <para>
- The following session variables are written to the binary log
- and honoured by the replication slave when parsing the binary
- log:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_sql_mode"><literal>SQL_MODE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>FOREIGN_KEY_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>UNIQUE_CHECKS</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_character_set_client"><literal>CHARACTER_SET_CLIENT</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_connection"><literal>COLLATION_CONNECTION</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_database"><literal>COLLATION_DATABASE</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <link linkend="option_mysqld_collation_server"><literal>COLLATION_SERVER</literal></link>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>SQL_AUTO_IS_NULL</literal>
- </para>
- </listitem>
-
- </itemizedlist>
-
- <section id="binary-log-formats">
-
- <title>Binary Logging Formats</title>
-
- <para>
- A number of different logging formats are used to record
- information in the binary log. The exact format employed
- depends on the version of MySQL being used. There are three
- logging formats:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Replication capabilities in MySQL originally were based on
- propagation of SQL statements from master to slave. This
- is called <emphasis>statement-based logging</emphasis>
- (SBL). SBL is identified internally using
- <literal>STATMENT</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- In <emphasis>row-based logging</emphasis> (RBL), the
- master writes events to the binary log that indicate how
- individual table rows are affected. RBL is identified
- internally using <literal>ROW</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- With <emphasis>mixed-based logging</emphasis> (MBL), SBL
- is used by default, but automatically switches to RBL in
- particular cases as described below. MBL is the default
- mode. MBL is identified internally using
- <literal>MIXED</literal>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- MBL is the default but storage engine being used can also set
- or limit the logging format according to the capabilities of
- the storage engine. This helps to eliminate issues when
- logging, and more specifically replicating, certain statements
- between the master and slave using the different engines.
- </para>
-
- </section>
-
- <section id="binary-log-setting">
-
- <title>Setting The Binary Log Format</title>
-
- <para>
- The default binary logging format is mixed-based.
- </para>
-
- <para>
- You can force the default replication format by specifying the
- format type to the
- <option>--binlog-format=<replaceable>type</replaceable></option>
- option. When set, all replication slaves connecting to the
- server will read the events according to this setting. The
- supported options are:
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>ROW</literal> — sets row-based
- replication as the default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>STATEMENT</literal> — sets
- statement-based replication as the default.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>MIXED</literal> — sets mixed-based
- replication as the default.
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
-
- <para>
- The logging format also can be switched at runtime. To specify
- the format globally for all clients, set the global value of
- the <literal>binlog_format</literal> system variable. (To
- change a global variable you need the <literal>SUPER</literal>
- privilege.)
- </para>
-
- <para>
- To switch to statement-based format, use either of these
- statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'STATEMENT';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 1;</userinput>
-</programlisting>
-
- <para>
- To switch to row-based format, use either of these statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'ROW';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 2;</userinput>
-</programlisting>
-
- <para>
- To switch to mixed format, use either of these statements:
- </para>
-
-<programlisting>
-mysql> <userinput>SET GLOBAL binlog_format = 'MIXED';</userinput>
-mysql> <userinput>SET GLOBAL binlog_format = 3;</userinput>
-</programlisting>
-
- <para>
- Individual clients can control the logging format for their
- own statements by setting the session value of
- <literal>binlog_format</literal>. For example:
- </para>
-
-<programlisting>
-mysql> <userinput>SET SESSION binlog_format = 'STATEMENT';</userinput>
-mysql> <userinput>SET SESSION binlog_format = 'ROW';</userinput>
-mysql> <userinput>SET SESSION binlog_format = 'MIXED';</userinput>
-</programlisting>
-
- <para>
- In addition to switching the logging format manually, a slave
- server may switch the format
- <emphasis>automatically</emphasis>. This happens when the
- server is running in either <literal>STATEMENT</literal> or
- <literal>MIXED</literal> format and encounters a row in the
- binary log that is written in <literal>ROW</literal> logging
- format. In that case, the slave switches to row-based
- replication temporarily for that event, and switches back to
- the previous format afterwards.
- </para>
-
- <para>
- There are two reasons why you might want to set replication
- logging on a per-connection basis:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- A thread that makes many small changes to the database
- might want to use row-based logging. A thread that
- performs updates that match many rows in the
- <literal>WHERE</literal> clause might want to use
- statement-based logging because it will be more efficient
- to log a few statements than many rows.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Some statements require a lot of execution time on the
- master, but result in just a few rows being modified. It
- might therefore be beneficial to replicate them using
- row-based logging.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- There are exceptions when you cannot switch the replication
- format at runtime:
-
- <itemizedlist>
-
- <listitem>
- <para>
- From within a stored function or a trigger.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If <literal>NDB</literal> is enabled.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the session is currently in row-based replication
- mode and has open temporary tables.
- </para>
- </listitem>
-
- </itemizedlist>
-
- Trying to switch the format in those cases results in an
- error.
- </para>
-
- <para>
- Switching the replication format at runtime is not recommended
- when any <emphasis>temporary tables</emphasis> exist, because
- temporary tables are logged only when using statement-based
- replication, whereas with row-based replication they are not
- logged. With mixed replication, temporary tables are usually
- logged; exceptions happen with user-defined functions (UDF)
- and with the <function>UUID()</function> function.
- </para>
-
- <para>
- With the binlog format set to <literal>ROW</literal>, many
- changes are written to the binary log using the row-based
- format. Some changes, however, still use the statement-based
- format. Examples include all DDL (data definition language)
- statements such as <literal>CREATE TABLE</literal>,
- <literal>ALTER TABLE</literal>, or <literal>DROP
- TABLE</literal>.
- </para>
-
- <para>
- The <option>--binlog-row-event-max-size</option> option is
- available for servers that are capable of row-based
- replication. Rows are stored into the binary log in chunks
- having a size in bytes not exceeding the value of this option.
- The value must be a multiple of 256. The default value is
- 1024.
- </para>
-
- <warning>
- <para>
- When using <emphasis>statement-based logging</emphasis> in a
- replication scenario, it is possible for the data on the
- master and slave to become different if a statement is
- designed in such a way that the data modification is
- <firstterm>non-deterministic</firstterm>; that is, it is
- left to the will of the query optimizer. In general, this is
- not a good practice even outside of replication. For a
- detailed explanation of this issue, see
- <xref linkend="open-bugs"/>.
- </para>
- </warning>
-
- </section>
-
- <section id="binary-log-mixed">
-
- <title>Mixed Binary Logging (MBL) Format</title>
-
- <para>
- When running in <literal>MIXED</literal> mode, automatic
- switching from statement-based to row-based replication takes
- place under the following conditions:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- When a DML statement updates an <literal>NDB</literal>
- table
- </para>
- </listitem>
-
- <listitem>
- <para>
- When a function contains
- <function role="sql">UUID()</function>
- </para>
- </listitem>
-
- <listitem>
- <para>
- When 2 or more tables with
- <literal>AUTO_INCREMENT</literal> columns are updated
- </para>
- </listitem>
-
- <listitem>
- <para>
- When any <literal>INSERT DELAYED</literal> is executed
- </para>
- </listitem>
-
- <listitem>
- <para>
- When the body of a view requires row-based replication,
- the statement creating the view also uses it — for
- example, this occurs when the statement creating a view
- uses the <function role="sql">UUID()</function> function
- </para>
- </listitem>
-
- <listitem>
- <para>
- When a call to a UDF is involved.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Beginning with MySQL 6.0.4:
-
- <itemizedlist>
-
- <listitem>
- <para>
- When <function role="sql">FOUND_ROWS()</function> or
- <function role="sql">ROW_COUNT()</function> is used
- (Bug #12092, Bug #30244)
- </para>
- </listitem>
-
- <listitem>
- <para>
- When <function role="sql">USER()</function>,
- <function role="sql">CURRENT_USER()</function>, or
- <function role="sql" condition="function_current-user">CURRENT_USER</function>
- is used (Bug #28086)
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
- </listitem>
-
- </itemizedlist>
-
- <note>
- <para>
- A warning is generated if you try to log execute a statement
- in statement-logging mode that should be logged in
- row-logging mode. The warning will be shown both in the
- client (and available with <literal>SHOW WARNINGS</literal>)
- and through the <command>mysqld</command> error log. A
- warning is added to the <literal>SHOW WARNINGS</literal>
- table each time a statement is executed. However, only the
- first statement that generated the warning for each client
- session is logged to the <literal>mysqld</literal> error log
- to prevent flooding the error log.
- </para>
- </note>
-
- <para>
- Mixed based logging is used by default, but in addition to the
- decisions above, individual engines can also enforce the
- logging format used when information in a table is updated.
- </para>
-
- <para>
- The logging formats supported by a particular engine are
- controlled by internal flags. The table below lists the
- logging formats supported by each of the current engines.
- </para>
-
- <informaltable>
- <tgroup cols="3">
- <colspec colwidth="50*"/>
- <colspec colwidth="25*"/>
- <colspec colwidth="25*"/>
- <thead>
- <row>
- <entry>Engine</entry>
- <entry>Row-logging supported</entry>
- <entry>Statement-logging supported</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Archive</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Blackhole</entry>
- <entry>No</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>CSV</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Example</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- <row>
- <entry>Federated</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Heap</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>MyISAM</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>Merge</entry>
- <entry>Yes</entry>
- <entry>Yes</entry>
- </row>
- <row>
- <entry>NDB</entry>
- <entry>Yes</entry>
- <entry>No</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- Note that an engine can be support either or both logging
- formats, and the logging capabilities of an individual engine
- can be further defined as follows
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If an engine supports row-based logging, then the engine
- is said to be <emphasis>row-logging capable
- (RLC)</emphasis>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If an engine support statement-based logging, then the
- engine is said to be <emphasis>statement-logging capable
- (SLC)</emphasis>.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- When determining what logging mode to use, the capabilities of
- all the tables in the event are combined. The set of tables is
- then marked according to these rules:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- A set of tables is defined as <emphasis>row logging
- restricted (RLR)</emphasis> if the tables are row logging
- capable but not statement logging capable.
- </para>
- </listitem>
-
- <listitem>
- <para>
- A set of tables is defined as <emphasis>statement logging
- restricted (SLR)</emphasis> if the tables are statement
- logging capable but not row logging capable.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Once the determination of the possible logging formats
- required by the statement is complete it is compared to the
- current <literal>BINLOG_FORMAT</literal> setting. The
- following table is used to decide how the information is
- recorded in the binary log or, if appropriate, whether an
- error is raised. In the table, a safe operation is defined as
- one that is deterministic. A number of internal rules decide
- whether the statement is deterministic or not.
- </para>
-
- <informaltable>
- <tgroup cols="6">
- <colspec colwidth="10*" colname="safe"/>
- <colspec colwidth="25*" colname="format"/>
- <colspec colwidth="10*" colname="RLC"/>
- <colspec colwidth="10*" colname="SLC"/>
- <colspec colwidth="20*" colname="error"/>
- <colspec colwidth="25*" colname="logas"/>
- <spanspec namest="safe" nameend="SLC" spanname="condition"/>
- <spanspec namest="error" nameend="logas" spanname="action"/>
- <thead>
- <row>
- <entry spanname="condition">Condition</entry>
- <entry spanname="action">Action</entry>
- </row>
- <row>
- <entry>Safe/unsafe</entry>
- <entry><literal>BINLOG_FORMAT</literal></entry>
- <entry>RLC</entry>
- <entry>SLC</entry>
- <entry>Error/Warning</entry>
- <entry>Logged as</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Safe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Warning: unsafe</entry>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>STATEMENT</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry>Warning: unsafe</entry>
- <entry>STATEMENT</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>MIXED</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>N</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>N</entry>
- <entry>Y</entry>
- <entry>Error: not loggable</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>N</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- <row>
- <entry>Unsafe</entry>
- <entry>ROW</entry>
- <entry>Y</entry>
- <entry>Y</entry>
- <entry/>
- <entry>ROW</entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <para>
- When a warning is produced by the determination, a standard
- MySQL warning is produced (and is available using
- <literal>SHOW WARNINGS</literal>). The information is also
- written to the <command>mysqld</command> error log. Only one
- error for each error instance per client connection is logged.
- The log message will include the SQL statement that was
- attempted.
- </para>
-
- </section>
-
- <section id="binary-log-mysql-database">
-
- <title>Logging Format for Changes to <literal>mysql</literal> Database Tables</title>
-
- <para>
- The contents of the grant tables in the
- <literal>mysql</literal> database can be modified directly
- (for example, with <literal>INSERT</literal> or
- <literal>DELETE</literal>) or indirectly (for example, with
- <literal>GRANT</literal> or <literal>CREATE USER</literal>).
- Database tables are written to the binary log using the
- following rules:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Data manipulation statements that change data in
- <literal>mysql</literal> database tables directly are
- logged according to the setting of the
- <literal>binlog_format</literal> system variable. This
- pertains to statements such as <literal>INSERT</literal>,
- <literal>UPDATE</literal>, <literal>DELETE</literal>,
- <literal>REPLACE</literal>, <literal>DO</literal>,
- <literal>LOAD DATA INFILE</literal>,
- <literal>SELECT</literal>, and
- <literal>TRUNCATE</literal>.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Statements that change the <literal>mysql</literal>
- database indirectly are logged as statements regardless of
- the value of <literal>binlog_format</literal>. This
- pertains to statements such as <literal>GRANT</literal>,
- <literal>REVOKE</literal>, <literal>SET
- PASSWORD</literal>, <literal>RENAME USER</literal>,
- <literal>CREATE</literal> (all forms except
- <literal>CREATE TABLE ... SELECT</literal>),
- <literal>ALTER</literal> (all forms), and
- <literal>DROP</literal> (all forms).
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal>CREATE TABLE ... SELECT</literal> is a combination of
- data definition and data manipulation. The <literal>CREATE
- TABLE</literal> part is logged using statement format and the
- <literal>SELECT</literal> part is logged according to the
- value of <literal>binlog_format</literal>.
- </para>
-
- </section>
-
- </section>
-
- <section id="slow-query-log">
-
- <title>The Slow Query Log</title>
-
- <indexterm>
- <primary>slow query log</primary>
- </indexterm>
-
- <indexterm>
- <primary>files</primary>
- <secondary>slow query log</secondary>
- </indexterm>
-
- <para>
- The slow query log consists of all SQL statements that took more
- than <literal>long_query_time</literal> seconds to execute. The
- time to acquire the initial table locks is not counted as
- execution time. <command>mysqld</command> writes a statement to
- the slow query log after it has been executed and after all
- locks have been released, so log order might be different from
- execution order. The minimum and default values of
- <literal>long_query_time</literal> are 1 and 10, respectively.
- Prior to MySQL 6.0.4, the minimum value is 1, and the value for
- this variable must be an integer. Beginning with MySQL 6.0.4,
- the default is 0, and a resolution of microseconds is supported
- when logging to a file. However, the microseconds part is
- ignored and only integer values are written when logging to
- tables.
- </para>
-
- <para>
- To enable the slow query log, start <command>mysqld</command>
- with the
- <option>--log-slow-queries[=<replaceable>file_name</replaceable>]</option>
- option, and optionally use <option>--log-output</option> to
- specify the log destination (as described in
- <xref linkend="log-tables"/>).
- </para>
-
- <para>
- If no <replaceable>file_name</replaceable> value is given for
- <option>--log-slow-queries</option>, the default name is
- <filename><replaceable>host_name</replaceable>-slow.log</filename>.
- If a filename is given, but not as an absolute pathname, the
- server writes the file in the data directory.
- </para>
-
- <para>
- When <option>--log-slow-queries</option> is specified, the
- <option>--slow-query-log</option> option also may be given to
- specify the initial slow query log state. With no argument or an
- argument of 0, the option disables the log. If omitted or given
- with an argument of 1, the option enables the log. If
- <option>--log--slow-queries</option> is not given,
- <option>--slow-query-log</option> has no effect.
- </para>
-
- <para>
- The global <literal>slow_query_log</literal> and
- <literal>slow_query_log_file</literal> system variables provide
- runtime control over the slow query log. Set
- <literal>slow_query_log</literal> to 0 (or
- <literal>OFF</literal>) to disable the log or to 1 (or
- <literal>ON</literal>) to enable it. Set
- <literal>general_log_file</literal> to specify the name of the
- log file. If a log file already is open, it is closed and the
- new file is opened.
- </para>
-
- <para>
- When the slow query log is enabled, output is written to any
- destinations specified by the <option>--log-output</option>
- option or <literal>log_output</literal> system variable. Note
- that if the destination is <literal>NONE</literal>, no output is
- written even if the slow query log is enabled. Setting the log
- filename has no effect on logging if the log destination value
- does not contain <literal>FILE</literal>.
- </para>
-
- <para>
- The slow query log can be used to find queries that take a long
- time to execute and are therefore candidates for optimization.
- However, examining a long slow query log can become a difficult
- task. To make this easier, you can process the slow query log
- using the <command>mysqldumpslow</command> command to summarize
- the queries that appear in the log. Use <command>mysqldumpslow
- --help</command> to see the options that this command supports.
- </para>
-
- <para>
- In MySQL ¤t-series;, queries that do not use indexes are
- logged in the slow query log if the
- <option>--log-queries-not-using-indexes</option> option is
- specified. See <xref linkend="server-options"/>.
- </para>
-
- <formalpara role="mnmas">
-
- <title>MySQL Enterprise</title>
-
- <para>
- Excessive table scans are indicative of missing or poorly
- optimized indexes. Using an advisor specifically designed for
- the task, the MySQL Enterprise Monitor can identify such
- problems and offer advice on resolution. For more information
- see <ulink url="&base-url-enterprise;advisors.html"/>.
- </para>
-
- </formalpara>
-
- <para>
- In MySQL ¤t-series;, the
- <option>--log-slow-admin-statements</option> server option
- enables you to request logging of slow administrative statements
- such as <literal>OPTIMIZE TABLE</literal>, <literal>ANALYZE
- TABLE</literal>, and <literal>ALTER TABLE</literal> to the slow
- query log.
- </para>
-
- <para>
- Queries handled by the query cache are not added to the slow
- query log, nor are queries that would not benefit from the
- presence of an index because the table has zero rows or one row.
- </para>
-
- </section>
-
- <section id="log-file-maintenance">
-
- <title>Server Log Maintenance</title>
-
- <indexterm>
- <primary>files</primary>
- <secondary>log</secondary>
- </indexterm>
-
- <indexterm>
- <primary>maintaining</primary>
- <secondary>log files</secondary>
- </indexterm>
-
- <indexterm>
- <primary>log files</primary>
- <secondary>maintaining</secondary>
- </indexterm>
-
- <para>
- MySQL Server can create a number of different log files that
- make it easy to see what is going on. See
- <xref linkend="log-files"/>. However, you must clean up these
- files regularly to ensure that the logs do not take up too much
- disk space.
- </para>
-
- <para>
- When using MySQL with logging enabled, you may want to back up
- and remove old log files from time to time and tell MySQL to
- start logging to new files. See <xref linkend="backup"/>.
- </para>
-
- <para>
- On a Linux (Red Hat) installation, you can use the
- <literal>mysql-log-rotate</literal> script for this. If you
- installed MySQL from an RPM distribution, this script should
- have been installed automatically. You should be careful with
- this script if you are using the binary log for replication. You
- should not remove binary logs until you are certain that their
- contents have been processed by all slaves.
- </para>
-
- <para>
- On other systems, you must install a short script yourself that
- you start from <command>cron</command> (or its equivalent) for
- handling log files.
- </para>
-
- <para>
- For the binary log, you can set the
- <literal>expire_logs_days</literal> system variable to expire
- binary log files automatically after a given number of days (see
- <xref linkend="server-system-variables"/>). If you are using
- replication, you should set the variable no lower than the
- maximum number of days your slaves might lag behind the master.
- </para>
-
- <para>
- You can force MySQL to start using new log files by issuing a
- <literal>FLUSH LOGS</literal> statement or executing
- <command>mysqladmin flush-logs</command> or <command>mysqladmin
- refresh</command>. See <xref linkend="flush"/>, and
- <xref linkend="mysqladmin"/>.
- </para>
-
- <para>
- A log flushing operation does the following:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- If general query logging (<option>--log</option>) or slow
- query logging (<option>--log-slow-queries</option>) to a log
- file is enabled, the server closes and reopens the general
- query log file or slow query log file.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If binary logging (<option>--log-bin</option>) is used, the
- server closes the current log file and opens a new log file
- with the next sequence number.
- </para>
- </listitem>
-
- <listitem>
- <para>
- If the server was given an error log filename with the
- <option>--log-error</option> option, it renames the error
- log with the suffix <literal>-old</literal> and creates a
- new empty error log file.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- The server creates a new binary log file when you flush the
- logs. However, it just closes and reopens the general and slow
- query log files. To cause new files to be created on Unix,
- rename the current logs before flushing them. At flush time, the
- server will open new logs with the original names. For example,
- if the general and slow query logs are named
- <filename>mysql.log</filename> and
- <filename>mysql-slow.log</filename>, you can use a series of
- commands like this:
- </para>
-
-<programlisting>
-shell> <userinput>cd <replaceable>mysql-data-directory</replaceable></userinput>
-shell> <userinput>mv mysql.log mysql.old</userinput>
-shell> <userinput>mv mysql-slow.log mysql-slow.old</userinput>
-shell> <userinput>mysqladmin flush-logs</userinput>
-</programlisting>
-
- <para>
- At this point, you can make a backup of
- <filename>mysql.old</filename> and
- <filename>mysql-slow.log</filename> and then remove them from
- disk.
- </para>
-
- <para>
- On Windows, you cannot rename log files while the server has
- them open. You must stop the server and rename them, and then
- restart the server to create new logs.
- </para>
-
- <para>
- You can disable the general query log or slow query log at
- runtime:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'OFF';
-SET GLOBAL slow_query_log = 'OFF';
-</programlisting>
-
- <para>
- With the logs disabled, rename the log files externally; for
- example, from the command line. Then enable the logs again:
- </para>
-
-<programlisting>
-SET GLOBAL general_log = 'ON';
-SET GLOBAL slow_query_log = 'ON';
-</programlisting>
-
- <para>
- This method works on any platform and does not require a server
- restart.
- </para>
-
- </section>
-
- </section>
-
<section id="multiple-servers">
<title>Running Multiple MySQL Servers on the Same Machine</title>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r9199 - in trunk: . refman-4.1 refman-5.0 refman-5.1 refman-6.0 | paul | 7 Dec |
