MySQL 8.4.0
Source Code Documentation
mysqltest Input Conventions

mysqltest reads input lines and processes them as follows:

  • “End of line” means a newline (linefeed) character. A carriage return/linefeed (CRLF) pair also is allowable as as a line terminator (the carriage return is ignored). Carriage return by itself is not allowed as a line terminator.

  • A line that begins with "#" as the first nonwhitespace content is treated as a comment that extends to the end of the line and is ignored. Example:

    # this is a comment

  • Earlier versions would also allow comments beginning with “--” unless the first word was a valid mysqltest command, but this has been deprecated and is longer allowed.

  • Other input is taken as normal command input. The command extends to the next occurrence of the command delimiter, which is semicolon (“;”) by default. The delimiter can be changed with the delimiter command.

    If mysqltest recognizes the first word of the delimiter-terminated command, mysqltest executes the command itself. Otherwise, mysqltest assumes that the command is an SQL statement and sends it to the MySQL server to be executed.

    Because the command extends to the delimiter, a given input line can contain multiple commands, and a given command can span multiple lines. The ability to write multiple-line statements is useful for making long statements more readable, such as a create table statement for a table that has many columns.

After mysqltest reads a command up to a delimiter and executes it, input reading restarts following the delimiter and any remaining input on the line that contains the delimiter is treated as though it begins on a new line. Consider the following two input lines:

echo issue a select statement; select 1; echo done
issuing the select statement;

That input contains two commands and one SQL statement:

echo issue a SELECT statement
echo done issuing the SELECT statement

Similarly, "#" comments can begin on a command line following a delimiter:

SELECT 'hello'; # select a string value

On a multiple-line command, "#" or “--” at the beginning of the second or following lines is not special. Thus, the second and third lines of the following variable-assignment command are not taken as comments. Instead, the variable $a is set to a value that contains two linefeed characters:

let $a= This is a variable
# assignment that sets a variable
-- to a multiple-line value;

-- commands and normal commands have complementary properties with regard to how mysqltest reads them:

  • A “--” command is terminated by a newline, regardless of how many delimiters it contains.
  • A normal command (without “--”) is terminated by the delimiter (semicolon), no matter how many newlines it contains.

mysqltest commands can be written either with a leading “--”) or as normal command input (no leading “--”). Use the command delimiter only in the latter case. Thus, these two lines are equivalent:

--sleep 2
sleep 2;

The equivalence is true even for the delimiter command. For example, to set the delimiter to “//”, either of these commands work:

--delimiter //
delimiter //;

To set the delimiter back to “;”, use either of these commands:

--delimiter ;
delimiter ;//

A potential ambiguity occurs because a command line can contain either a mysqltest command or an SQL statement. This has a couple of implications:

  • No mysqltest command should be the same as any keyword that can begin an SQL statement.
  • Should extensions to SQL be implemented in the future, it is possible that a new SQL keyword could be impossible for mysqltest to recognize as such if that keyword is already used as a mysqltest command.

Any ambiguity can be resolved by using the “--” syntax to force interpetation as a mysqltest command, or the query command to force interpretation as SQL.

All file paths used in test commands should use forward slash "/" as the directory separator as in Unix. They will be automatically converted when needed if the test is run on Windows. We also recommend putting all temporary or auxiliary files made during the test under the directory referred to by $MYSQL_TMP_DIR. Do not put them under fixed full paths like /tmp. This will help ensuring portability of the test, and avoiding conflicts with other programs.

$MYSQL_TMP_DIR is equivalent to $MYSQLTEST_VARDIR/tmp if you are not running with parallel test threads, but if you run with --parallel, they will be different. It is therefore best to be consistent and use $MYSQL_TMP_DIR.

Commands named disable_X or enable_X, except parsing, reconnect and rpl_parse, can take an optional modifier ONCE. If this is added, the relevant setting is enabled or disabled only for the next command or statement, after which it is reverted to whatever it was before. Note that the word ONCE must be in upper case; this was chosen in order to make it more visible when reading the test script.

For example, --disable_query_log ONCE will ensure query log is disabled for the next statement, but will not affect whether or not query log is enabled for statements following the next. It is possible to enable/disable more that one property (e.g. both query log and result log) for a single statement using the ONCE modifier.