Author: jstephens
Date: 2008-03-26 19:04:08 +0100 (Wed, 26 Mar 2008)
New Revision: 10347
Log:
Documented fix for Replication Bug #31168
Fixed mysqld optvars file (binlog_format was shown as not dynamic)
Fixed some contradictory statements, harmonisation and various other
issues in binlog docs
Modified:
trunk/dynamic-docs/changelog/mysqld-1.xml
trunk/dynamic-docs/command-optvars/mysqld.xml
trunk/refman-5.1/dba-core.xml
trunk/refman-6.0/dba-core.xml
Modified: trunk/dynamic-docs/changelog/mysqld-1.xml
===================================================================
--- trunk/dynamic-docs/changelog/mysqld-1.xml 2008-03-26 09:24:08 UTC (rev 10346)
+++ trunk/dynamic-docs/changelog/mysqld-1.xml 2008-03-26 18:04:08 UTC (rev 10347)
Changed blocks: 1, Lines Added: 54, Lines Deleted: 0; 1792 bytes
@@ -6,6 +6,60 @@
]>
<changelog>
+ <logentry entrytype="feature">
+
+ <tags>
+ <highlight type="replication"/>
+ <manual type="system variables"/>
+ </tags>
+
+ <bugs>
+ <fixes bugid="31168"/>
+ <seealsobug bugid="34732"/>
+ </bugs>
+
+ <versions>
+ <version ver="5.1.24"/>
+ <version ver="6.0.5"/>
+ </versions>
+
+ <message>
+
+ <para>
+ When running the server with
+ <option>--binlog-format=MIXED</option> or
+ <option>--binlog-format=STATEMENT</option>, a query that
+ referred to a system variable used the slave's value when
+ replayed on the slave. This meant that, if the value of a system
+ variable was inserted into a table, the slave differed from the
+ master. Now, statements that refer to a system variable are
+ marked as <quote>unsafe</quote>, which means that:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When the server is using
+ <option>--binlog-format=MIXED</option>, the row-based
+ format is used automatically to replicate these
+ statements.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When the server is using
+ <option>--binlog-format=STATEMENT</option>, these
+ statements produce a warning.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </message>
+
+ </logentry>
+
<logentry entrytype="bug">
<tags>
Modified: trunk/dynamic-docs/command-optvars/mysqld.xml
===================================================================
--- trunk/dynamic-docs/command-optvars/mysqld.xml 2008-03-26 09:24:08 UTC (rev 10346)
+++ trunk/dynamic-docs/command-optvars/mysqld.xml 2008-03-26 18:04:08 UTC (rev 10347)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 1; 726 bytes
@@ -5759,7 +5759,7 @@
<types>
<optype class="mycnf" format="binlog-format" setvar="binlog_format"/>
<optype class="cmdline" format="--binlog-format" />
- <vartype class="system" isdynamic="no" scope="both" inversion="5.1.8" format="binlog_format"/>
+ <vartype class="system" isdynamic="yes" scope="both" inversion="5.1.8" format="binlog_format"/>
</types>
<values vartype="enumeration" platform="all">
Modified: trunk/refman-5.1/dba-core.xml
===================================================================
--- trunk/refman-5.1/dba-core.xml 2008-03-26 09:24:08 UTC (rev 10346)
+++ trunk/refman-5.1/dba-core.xml 2008-03-26 18:04:08 UTC (rev 10347)
Changed blocks: 13, Lines Added: 97, Lines Deleted: 82; 13644 bytes
@@ -12649,10 +12649,10 @@
</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:
+ For MySQL 5.1.20 and later (and MySQL 5.0.46 and later for
+ backwards compatibility), the following session variables are
+ written to the binary log and honored by the replication slave
+ when parsing the binary log:
</para>
<itemizedlist>
@@ -12724,44 +12724,55 @@
<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>.
+ is called <emphasis>statement-based logging</emphasis>.
+ You can cause this format to be used by starting the
+ server with <option>--binlog-format=STATEMENT</option>.
</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>.
+ In <emphasis>row-based logging</emphasis>, the master
+ writes events to the binary log that indicate how
+ individual table rows are affected. You can cause the
+ server to use row-based logging by starting it with
+ <option>--binlog-format=ROW</option>.
</para>
+
+ <para>
+ Support for row-based logging was added in MySQL 5.1.5.
+ </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>.
+ A third option is also available: <emphasis>mixed
+ logging</emphasis>. With mixed logging, statement-based
+ logging is used by default, but the logging mode switches
+ automatically to row-based in certain cases as described
+ below. You can cause MySQL to use mixed logging explicitly
+ by starting <command>mysqld</command> with the option
+ <option>--binlog-format=MIXED</option>.
</para>
+
+ <para>
+ Mixed logging is available beginning with MySQL 5.1.8.
+ Beginning with MySQL 5.1.12, it is the default logging
+ mode.
+ </para>
+
+ <para>
+ Starting with MySQL 5.1.20, the logging format can also be
+ set or limited by the storage engine being used. This
+ helps to eliminate issues when logging, and more
+ specifically replicating, certain statements between a
+ master and slave which are using different storage
+ engines.
+ </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">
@@ -12784,7 +12795,7 @@
<listitem>
<para>
- For MySQL 5.1.12 and later, mixed-based logging is used by
+ For MySQL 5.1.12 and later, mixed logging is used by
default.
</para>
</listitem>
@@ -12792,35 +12803,34 @@
</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:
+ You can force the replication format by starting the MySQL
+ server with
+ <option>--binlog-format=<replaceable>type</replaceable></option>.
+ When set, all replication slaves connecting to the server will
+ read the events according to this setting. The supported
+ values for <replaceable>type</replaceable> are:
<itemizedlist>
<listitem>
<para>
- <literal>ROW</literal> — sets row-based
- replication as the default.
+ <literal>ROW</literal> causes replication to be
+ row-based.
</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.
+ <literal>STATEMENT</literal> causes replication to be
+ statement-based. 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.
+ <literal>MIXED</literal> causes replication to use mixed
+ format. This is the default for MySQL 5.1.12 and later.
</para>
</listitem>
@@ -12864,7 +12874,7 @@
</programlisting>
<para>
- Individual clients can control the logging format for their
+ An individual client can control the logging format for its
own statements by setting the session value of
<literal>binlog_format</literal>. For example:
</para>
@@ -12943,18 +12953,18 @@
</itemizedlist>
- Trying to switch the format in those cases results in an
- error.
+ Trying to switch the format in any of these 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.
+ when any temporary tables 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 (UDFs) and with the
+ <function>UUID()</function> function.
</para>
<para>
@@ -12994,7 +13004,7 @@
<section id="binary-log-mixed">
- <title>Mixed Binary Logging (MBL) Format</title>
+ <title>Mixed Binary Logging Format</title>
<para>
When running in <literal>MIXED</literal> mode, automatic
@@ -13093,6 +13103,13 @@
</para>
</listitem>
+ <listitem>
+ <para>
+ Beginning with MySQL 5.1.24, when a statement refers
+ to one or more system variables. (Bug #31168)
+ </para>
+ </listitem>
+
</itemizedlist>
</para>
</listitem>
@@ -13103,8 +13120,8 @@
<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
+ should be logged in row-logging mode. The warning is shown
+ both in the client (in the output of <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
@@ -13116,18 +13133,13 @@
</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.
+ Starting with MySQL 5.1.20, in addition to the decisions
+ above, individual engines can also determine the logging
+ format used when information in a table is updated. The
+ following table lists the logging formats supported by each
+ storage engine:
</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*"/>
@@ -13196,9 +13208,9 @@
</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
+ A given storage engine can support either or both logging
+ formats; the logging capabilities of an individual engine can
+ be further defined as follows:
</para>
<itemizedlist>
@@ -13206,42 +13218,41 @@
<listitem>
<para>
If an engine supports row-based logging, then the engine
- is said to be <emphasis>row-logging capable
- (RLC)</emphasis>.
+ is said to be <firstterm>row-logging capable</firstterm>.
</para>
</listitem>
<listitem>
<para>
- If an engine support statement-based logging, then the
- engine is said to be <emphasis>statement-logging capable
- (SLC)</emphasis>.
+ If an engine supports statement-based logging, then the
+ engine is said to be <firstterm>statement-logging
+ capable</firstterm>.
</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:
+ When determining the logging mode to be used, the capabilities
+ of all the tables affected by the event are combined. The set
+ of affected 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
+ A set of tables is defined as <firstterm>row logging
+ restricted</firstterm> 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.
+ A set of tables is defined as <firstterm>statement logging
+ restricted</firstterm> if the tables are statement logging
+ capable but not row logging capable.
</para>
</listitem>
@@ -13254,8 +13265,12 @@
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.
+ one that is deterministic. A number of rules decide whether
+ the statement is deterministic or not, as shown in the
+ following table (where <emphasis role="bold">RLC</emphasis>
+ stands for <quote>row-logging capable</quote> and
+ <emphasis role="bold">SLC</emphasis> stands for
+ <quote>statement-logging capable</quote>):
</para>
<informaltable>
Modified: trunk/refman-6.0/dba-core.xml
===================================================================
--- trunk/refman-6.0/dba-core.xml 2008-03-26 09:24:08 UTC (rev 10346)
+++ trunk/refman-6.0/dba-core.xml 2008-03-26 18:04:08 UTC (rev 10347)
Changed blocks: 12, Lines Added: 93, Lines Deleted: 80; 13350 bytes
@@ -12533,41 +12533,48 @@
<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>.
+ is called <emphasis>statement-based logging</emphasis>.
+ You can cause this format to be used by starting the
+ server with <option>--binlog-format=STATEMENT</option>.
</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>.
+ In <emphasis>row-based logging</emphasis>, the master
+ writes events to the binary log that indicate how
+ individual table rows are affected. You can cause the
+ server to use row-based logging by starting it with
+ <option>--binlog-format=ROW</option>.
</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>.
+ A third option is also available: <emphasis>mixed
+ logging</emphasis>. With mixed logging, statement-based
+ logging is used by default, but the logging mode switches
+ automatically to row-based in certain cases as described
+ below. You can cause MySQL to use mixed logging explicitly
+ by starting <command>mysqld</command> with the option
+ <option>--binlog-format=MIXED</option>.
</para>
+
+ <para>
+ Mixed logging is the default logging mode.
+ </para>
+
+ <para>
+ The logging format can also be set or limited by the
+ storage engine being used. This helps to eliminate issues
+ when logging, and more specifically replicating, certain
+ statements between a master and slave which are using
+ different storage engines.
+ </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">
@@ -12579,33 +12586,33 @@
</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:
+ You can force the replication format by starting the MySQL
+ server with
+ <option>--binlog-format=<replaceable>type</replaceable></option>.
+ When set, all replication slaves connecting to the server will
+ read the events according to this setting. The supported
+ values for <replaceable>type</replaceable> are:
<itemizedlist>
<listitem>
<para>
- <literal>ROW</literal> — sets row-based
- replication as the default.
+ <literal>ROW</literal> causes replication to be
+ row-based.
</para>
</listitem>
<listitem>
<para>
- <literal>STATEMENT</literal> — sets
- statement-based replication as the default.
+ <literal>STATEMENT</literal> causes replication to be
+ statement-based.
</para>
</listitem>
<listitem>
<para>
- <literal>MIXED</literal> — sets mixed-based
- replication as the default.
+ <literal>MIXED</literal> causes replication to use mixed
+ format.
</para>
</listitem>
@@ -12649,7 +12656,7 @@
</programlisting>
<para>
- Individual clients can control the logging format for their
+ An individual client can control the logging format for its
own statements by setting the session value of
<literal>binlog_format</literal>. For example:
</para>
@@ -12728,18 +12735,18 @@
</itemizedlist>
- Trying to switch the format in those cases results in an
- error.
+ Trying to switch the format in any of these 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.
+ when any temporary tables 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 (UDFs) and with the
+ <function>UUID()</function> function.
</para>
<para>
@@ -12779,7 +12786,7 @@
<section id="binary-log-mixed">
- <title>Mixed Binary Logging (MBL) Format</title>
+ <title>Mixed Binary Logging Format</title>
<para>
When running in <literal>MIXED</literal> mode, automatic
@@ -12827,7 +12834,7 @@
<listitem>
<para>
- When a call to a UDF is involved.
+ When a call to a UDF is involved
</para>
</listitem>
@@ -12878,6 +12885,13 @@
</para>
</listitem>
+ <listitem>
+ <para>
+ Beginning with MySQL 6.0.5, when a statement refers
+ to one or more system variables. (Bug #31168)
+ </para>
+ </listitem>
+
</itemizedlist>
</para>
</listitem>
@@ -12888,29 +12902,24 @@
<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.
+ row-logging mode. The warning is shown both in the client
+ (in the output of <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.
+ In addition to the decisions above, individual engines can
+ also determine the logging format used when information in a
+ table is updated. The following table lists the logging
+ formats supported by each storage engine:
</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*"/>
@@ -12979,9 +12988,9 @@
</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
+ A given storage engine can support either or both logging
+ formats; the logging capabilities of an individual engine can
+ be further defined as follows:
</para>
<itemizedlist>
@@ -12989,42 +12998,41 @@
<listitem>
<para>
If an engine supports row-based logging, then the engine
- is said to be <emphasis>row-logging capable
- (RLC)</emphasis>.
+ is said to be <firstterm>row-logging capable</firstterm>.
</para>
</listitem>
<listitem>
<para>
- If an engine support statement-based logging, then the
- engine is said to be <emphasis>statement-logging capable
- (SLC)</emphasis>.
+ If an engine supports statement-based logging, then the
+ engine is said to be <firstterm>statement-logging
+ capable</firstterm>.
</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:
+ When determining the logging mode to be used, the capabilities
+ of all the tables affected by the event are combined. The set
+ of affected 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
+ A set of tables is defined as <firstterm>row logging
+ restricted</firstterm> 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.
+ A set of tables is defined as <firstterm>statement logging
+ restricted</firstterm> if the tables are statement logging
+ capable but not row logging capable.
</para>
</listitem>
@@ -13037,8 +13045,12 @@
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.
+ one that is deterministic. A number of rules decide whether
+ the statement is deterministic or not, as shown in the
+ following table (where <emphasis role="bold">RLC</emphasis>
+ stands for <quote>row-logging capable</quote> and
+ <emphasis role="bold">SLC</emphasis> stands for
+ <quote>statement-logging capable</quote>):
</para>
<informaltable>
@@ -13273,8 +13285,9 @@
(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:
+ Statements that affect <literal>mysql</literal> database
+ tables are written to the binary log using the following
+ rules:
</para>
<itemizedlist>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r10347 - in trunk: dynamic-docs/changelog dynamic-docs/command-optvars refman-5.1 refman-6.0 | jon | 26 Mar |
