MySQL 8.4.0
Source Code Documentation
Writing Replication Tests

If you are writing a replication test case, the test case file should begin with this command:

--source include/rpl/

To switch between the master and slave, use these commands:

connection master;
connection slave;

If you need to do something on an alternative connection, you can use connection master1; for the master and connection slave1; for the slave.

To run the master with additional options for your test case, put them in command-line format in t/test_name-master.opt. When a file named t/test_name-master.opt exists, examines it for extra options that the server needs to be run with when executing the test_name test case. If no server has yet been started or the current server is running with different options, restarts the server with the new options.

For the slave, similar principles apply, but you should list additional options in t/test_name-slave.opt.

Several include files are available for use in tests that enable better control over the behavior of slave server I/O and SQL threads. The files are located in the include directory and have names of the form rpl/wait_for_(replica|receiver|applier)*.inc. By using these files, you can help make replication tests more stable because it will be more likely that test failures are due to replication failures, not due to problems with the tests themselves.

The slave-control include files address the issue that it is not always sufficient to use a START REPLICA or STOP SLAVE statement by itself: When the statement returns, the slave may not have reached the desired operational state. For example, with START REPLICA, the following considerations apply:

  • It is not necessary to wait for the SQL thread after START SLAVE or START REPLICA SQL_THREAD because the thread will have started by the time statement returns.

  • By contrast, it is necessary to wait for the I/O thread after START REPLICA or START REPLICA IO_THREAD because although the thread will have started when the statement returns, it may not yet have established the connection to the master.

To verify that a slave has reached the desired state, combine the use of START REPLICA or STOP REPLICA with an appropriate “wait” include file. The file contains code that waits until the state has been reached or a timeout occurs. For example, to verify that both slave threads have started, do this:

--source include/rpl/

Similarly, to stop both slave threads, do this:

--source include/rpl/

The following list describes the include files that are available for slave control:

  • rpl/

    Waits for both slave threads (I/O and SQL) to start. Should be preceded by a START REPLICA statement.

  • rpl/

    Waits for both slave threads (I/O and SQL) to stop. Should be preceded by a STOP REPLICA statement.

  • rpl/

    Waits for the slave SQL thread to stop. Should be preceded by a STOP REPLICA SQL_THREAD statement.

  • rpl/

    Waits for the slave I/O thread to stop. Should be preceded by a STOP REPLICA IO_THREAD statement.

  • rpl/

    Waits until SHOW REPLICA STATUS output contains a given value or a timeout occurs. Before including the file, you should set the $slave_param variable to the column name to look for in SHOW REPLICA STATUS output, and $slave_param_value to the value that you are waiting for the column to have.


    --let $slave_param= Replica_SQL_Running
    --let $slave_param_value= No
    --source include/rpl/

  • rpl/

    Waits until the SQL thread for the current connection has gotten an error or a timeout occurs. Occurrence of an error is determined by waiting for the Last_SQL_Errno column of SHOW REPLICA STATUS output to have a nonzero value.