Author: paul
Date: 2008-08-25 21:10:52 +0200 (Mon, 25 Aug 2008)
New Revision: 11605
Log:
r33512@frost: paul | 2008-08-25 14:10:31 -0500
mysqltest manual: Add section describing how to control binary logging format.
(WL#3949)
Modified:
trunk/mysqltest/programs.xml
trunk/mysqltest/writing-tests.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33508
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32819
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:35828
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:33512
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:32819
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2008-08-25 17:38:38 UTC (rev 11604)
+++ trunk/mysqltest/programs.xml 2008-08-25 19:10:52 UTC (rev 11605)
Changed blocks: 2, Lines Added: 35, Lines Deleted: 1; 1882 bytes
@@ -1905,6 +1905,37 @@
<para>
<indexterm>
<primary>mysql-test-run.pl</primary>
+ <secondary>combination option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>combination option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--combination=<replaceable>str</replaceable></option>
+ </para>
+
+ <para>
+ Extra options to pass to <command>mysqld</command>. This
+ option is similar to <option>--mysqld</option> but should be
+ given two or more times.
+ <command>mysql-test-run.pl</command> executes multiple test
+ runs, using the options for each instance of
+ <option>--combination</option> in successive runs. If
+ <option>--combination</option> is given only once, it has no
+ effect.
+ </para>
+
+ <para>
+ This option was added in MySQL 5.1.23/6.0.4.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
<secondary>comment option</secondary>
</indexterm>
@@ -2449,7 +2480,10 @@
</para>
<para>
- Extra options to pass to <command>mysqld</command>.
+ Extra options to pass to <command>mysqld</command>. See also
+ the description for the <option>--combination</option>
+ option, which can be use to pass options for multiple test
+ runs.
</para>
</listitem>
Modified: trunk/mysqltest/writing-tests.xml
===================================================================
--- trunk/mysqltest/writing-tests.xml 2008-08-25 17:38:38 UTC (rev 11604)
+++ trunk/mysqltest/writing-tests.xml 2008-08-25 19:10:52 UTC (rev 11605)
Changed blocks: 1, Lines Added: 177, Lines Deleted: 2; 6879 bytes
@@ -1344,17 +1344,192 @@
<section id="writing-tests-binlog-control">
- <title>Controlling the Binary Log Format</title>
+ <title>Controlling the Binary Log Format Used for Tests</title>
<indexterm>
<primary>binary logging</primary>
<secondary>controlling</secondary>
</indexterm>
+ <indexterm>
+ <primary>--combination option</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>combinations file</primary>
+ </indexterm>
+
<para>
- To be added.
+ Some tests require the use of a particular binary logging format.
+ This section describes how to control the format for testing
+ purposes.
</para>
+ <para>
+ Before MySQL 5.1, the server does all binary logging using
+ statement-based logging (SBL), which logs events as statements
+ that produce data changes. As of MySQL 5.1, the server also
+ supports row-based logging (RBL), which logs events as changes to
+ individual rows, and mixed logging, which switches between SBL and
+ RBL automatically as necessary.
+ </para>
+
+ <para>
+ The global <literal>binlog_format</literal> system variable
+ indicates which logging format is in effect. It has possible
+ values of <literal>STATEMENT</literal>, <literal>ROW</literal>,
+ and <literal>MIXED</literal> (not case sensitive). This system
+ variable can be set at server startup by specifying
+ <option>--binlog_format=<replaceable>value</replaceable></option>
+ on the command line or in an option file. A user who has the
+ <literal>SUPER</literal> privilege can change the logging format
+ at runtime. For example:
+ </para>
+
+<programlisting>
+SET GLOBAL binlog_format = STATEMENT;
+</programlisting>
+
+ <para>
+ At test time, you can exercise control over the binary logging
+ format:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ To control which format the server uses, you can pass options
+ to <command>mysql-test-run.pl</command>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To verify that a particular format is in effect for a test
+ case, you can use an appropriate include file that checks the
+ current format and exits if the format is other than what is
+ required.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ To set the binary logging format for a test run, you can use the
+ <option>--mysqld</option> option to tell
+ <command>mysql-test-run.pl</command> to pass a logging option to
+ <command>mysqld</command>. For example, to use statement-based
+ logging, do this:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --mysqld=--binlog_format=statement [<replaceable>option</replaceable>] ...</userinput>
+</programlisting>
+
+ <para>
+ Alternatively, to run tests under multiple log formats, use two or
+ more instances of the <option>--combination</option> option. For
+ example, the following command runs those tests from the
+ <literal>rpl</literal> suite that have names that begin with
+ <literal>rpl_row</literal>. The tests are run once with the binary
+ log format set to <literal>ROW</literal> and a second time with
+ the format set to <literal>MIXED</literal>:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --suite=rpl --do-test=rpl_row</userinput>
+ <userinput>--combination=--binlog_format=row</userinput>
+ <userinput>--combination=--binlog_format=mixed</userinput>
+</programlisting>
+
+ <para>
+ The <option>--combination</option> option must be given at least
+ two times or it has no effect.
+ </para>
+
+ <para>
+ As an alternative to using the <option>--combination</option>
+ option, you can create a file named
+ <filename>combinations</filename> in the test suite directory and
+ list the arguments that you would specify via
+ <option>--combination</option>, one line per argument. For the
+ preceding <command>mysql-test-run.pl</command> command, the suite
+ name is <literal>rpl</literal>, so you would create a file named
+ <filename>suite/rpt/combinations</filename> with these contents:
+ </para>
+
+<programlisting>
+[row]
+--binlog_format=row
+
+[mixed]
+--binlog_format=mixed
+</programlisting>
+
+ <para>
+ Then invoke <command>mysql-test-run.pl</command> like this:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl --suite=rpl --do-test=row</userinput>
+</programlisting>
+
+ <para>
+ <option>--combination</option> options specified on the command
+ line override those found in the combinations file if both are
+ used.
+ </para>
+
+ <para>
+ The <option>--combination</option> option and the
+ <filename>combinations</filename> file have different scope. The
+ <option>--combination</option> applies globally to all tests run
+ by a given invocation of <command>mysql-test-run.pl</command>. The
+ <filename>combinations</filename> file is placed in a test suite
+ directory and applies only to tests in that suite.
+ </para>
+
+ <para>
+ To specify within a test case that a particular binary log format
+ is required, include one of the following lines to indicate the
+ format:
+ </para>
+
+<programlisting>
+--source include/have_binlog_format_row.inc
+--source include/have_binlog_format_statement.inc
+--source include/have_binlog_format_mixed.inc
+</programlisting>
+
+ <para>
+ The following files can be used for tests that support two logging
+ formats:
+ </para>
+
+<programlisting>
+--source include/have_binlog_format_mixed_or_row.inc
+--source include/have_binlog_format_mixed_or_statement.inc
+--source include/have_binlog_format_row_or_statement.inc
+</programlisting>
+
+ <para>
+ Before <command>mysql-test-run.pl</command> runs the test case, it
+ checks whether the value that it is using for the
+ <literal>binlog_format</literal> system variable matches what the
+ test requires, based on whether the test sources one of the
+ preceding include files. If <literal>binlog_format</literal> does
+ not have an appropriate value,
+ <command>mysql-test-run.pl</command> skips the test.
+ </para>
+
+ <para>
+ If a test supports all binary logging formats, none of the
+ preceding include files should be used in the test file. A test
+ that includes no <filename>have_binlog_format_*.inc</filename>
+ file is assumed to support all formats.
+ </para>
+
</section>
<section id="writing-tests-replication-tests">
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r11605 - in trunk: . mysqltest | paul.dubois | 25 Aug |
