Documentation Home
The MySQL Test Framework, Version 1.0
Download this Manual
PDF (US Ltr) - 443.9Kb
PDF (A4) - 445.6Kb

6.1 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
  • (Deprecated syntax) A line that begins with -- as the first nonwhitespace content also is treated as a comment that extends to the end of the line. However, unlike # comments, if the first word of the comment is a valid mysqltest command, mysqltest executes the line from that word to the end of the line as a command.

    mysqltest interprets the following lines as comments because the first word is not a mysqltest command:

    -- this is a comment
    -- clean up from previous test runs

    mysqltest interprets the following lines as commands and executes them because the first word is a mysqltest command:

    --disconnect conn1
    -- error 1050

    The -- syntax is useful for writing commands that contain embedded instances of the command delimiter:

    -- echo write this text; it goes to the result file

    The -- syntax for writing comments is deprecated because of the potential for accidentally writing comments that begin with a keyword and being executed. This syntax cannot be used for comments as of MySQL 5.1.30/6.0.8.

  • 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 or -- comments can begin on a command line following a delimiter:

SELECT 'hello'; # select a string value
SELECT 'hello'; -- echo that was a SELECT statement

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;

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

  • A -- comment 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 as comments (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 ;//

The input language has certain ambiguities. For example, if you write the following line, intending it as a comment that indicates where test 43 ends, it will not work:

-- End of test 43

The comment is not treated as such because end is a valid mysqltest command. Thus, although it is possible to write a noncommand comment that begins with --, it is better to use # instead. Writing comments with # also has less potential to cause problems in the future. For example, mysqltest interprets the line --switch to conn1 as a comment currently, but if mysqltest is extended in the future to add a switch command, that line will be treated as a command instead. If you use # for all comments, this problem will not occur.

Another ambiguity occurs because a noncomment 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.