4.3. Specifying Program Options

MySQL 5.0

previous page next page

4.3. Specifying Program Options

There are several ways to specify options for MySQL programs:

  • List the options on the command line following the program name. This is most common for options that apply to a specific invocation of the program.

  • List the options in an option file that the program reads when it starts. This is common for options that you want the program to use each time it runs.

  • List the options in environment variables. This method is useful for options that you want to apply each time the program runs. In practice, option files are used more commonly for this purpose. However, Section 5.13.2, “Running Multiple Servers on Unix”, discusses one situation in which environment variables can be very helpful. It describes a handy technique that uses such variables to specify the TCP/IP port number and Unix socket file for both the server and client programs.

MySQL programs determine which options are given first by examining environment variables, then by reading option files, and then by checking the command line. This means that environment variables have the lowest precedence and command-line options the highest.

Because options are processed in order, if an option is specified multiple times, the last occurrence takes precedence. The following command causes mysql to connect to the server running on : 

shell>

If conflicting or related options are given, later options take precedence over earlier options. The following command runs mysql in “no column names” mode: 

shell>

An option can be specified by writing it in full or as any unambiguous prefix. For example, the option can be given to mysqldump as , but not as because that is ambiguous: 

shell> 
mysqldump: ambiguous option '--comp' (compatible, compress)

Be aware that the use of option prefixes can cause problems in the event that new options are implemented for a program. A prefix that is unambigious now might become ambiguous in the future.

You can take advantage of the way that MySQL programs process options by specifying default values for a program's options in an option file. That enables you to avoid typing them each time you run the program, but also allows you to override the defaults if necessary by using command-line options.

4.3.1. Using Options on the Command Line

Program options specified on the command line follow these rules:

  • Options are given after the command name.

  • An option argument begins with one dash or two dashes, depending on whether it has a short name or a long name. Many options have both forms. For example, and are the short and long forms of the option that instructs a MySQL program to display its help message.

  • Option names are case sensitive. and are both legal and have different meanings. (They are the corresponding short forms of the and options.)

  • Some options take a value following the option name. For example, or indicate the MySQL server host to a client program. The option value tells the program the name of the host where the MySQL server is running.

  • For a long option that takes a value, separate the option name and the value by an ‘’ sign. For a short option that takes a value, the option value can immediately follow the option letter, or there can be a space between: and are equivalent. An exception to this rule is the option for specifying your MySQL password. This option can be given in long form as or as . In the latter case (with no password value given), the program prompts you for the password. The password option also may be given in short form as or as . However, for the short form, if the password value is given, it must follow the option letter with no intervening space. The reason for this is that if a space follows the option letter, the program has no way to tell whether a following argument is supposed to be the password value or some other kind of argument. Consequently, the following two commands have two completely different meanings: 

    shell> 
shell>

    The first command instructs mysql to use a password value of , but specifies no default database. The second instructs mysql to prompt for the password value and to use as the default database.

Some options control behavior that can be turned on or off. For example, the mysql client supports a option that determines whether or not to display a row of column names at the beginning of query results. By default, this option is enabled. However, you may want to disable it in some instances, such as when sending the output of mysql into another program that expects to see only data and not an initial header line.

To disable column names, you can specify the option using any of these forms: 

--disable-column-names
--skip-column-names
--column-names=0

The and prefixes and the suffix all have the same effect: They turn the option off.

The “enabled” form of the option may be specified in any of these ways: 

--column-names
--enable-column-names
--column-names=1

If an option is prefixed by , a program does not exit with an error if it does not recognize the option, but instead issues only a warning: 

shell> 
mysql: WARNING: unknown option '--no-such-option'

The prefix can be useful when you run programs from multiple installations of MySQL on the same machine and list options in an option file, An option that may not be recognized by all versions of a program can be given using the prefix (or in an option file). Versions of the program that recognize the option process it normally, and versions that do not recognize it issue a warning and ignore it.

Another option that may occasionally be useful with mysql is the or option, which can be used to pass SQL statements to the server. The statements must be enclosed by single or double quotation marks. If you wish to use quoted values within a statement, you should use double quotes for the statement, and single quotes for any quoted values within the statement. When this option is used, mysql executes the statements and exits.

For example, you can use the following command to obtain a list of user accounts: 

shell> 
Enter password: 
+------+-----------+
| User | Host      |
+------+-----------+
|      | gigan     |
| root | gigan     |
|      | localhost |
| jon  | localhost |
| root | localhost |
+------+-----------+
shell>

Note that the long form () is followed by an equals sign ().

In the preceding example, the name of the database was passed as a separate argument. However, the same statement could have been executed using this command, which specifies no default database: 

mysql>

Multiple SQL statements may be passed on the command line, separated by semicolons: 

shell> 
Enter password: 
+------------+
| VERSION()  |
+------------+
| 5.0.19-log |
+------------+
+---------------------+
| NOW()               |
+---------------------+
| 2006-01-05 21:19:04 |
+---------------------+

The or option may also be used to pass commands in an analogous fashion to the ndb_mgm management client for MySQL Cluster. See Section 15.3.6, “Safe Shutdown and Restart”, for an example.

4.3.2. Using Option Files

Most MySQL programs can read startup options from option files (also sometimes called configuration files). Option files provide a convenient way to specify commonly used options so that they need not be entered on the command line each time you run a program. For the MySQL server, MySQL provides a number of preconfigured option files.

To determine whether a program reads option files, invoke it with the option ( and for mysqld). If the program reads option files, the help message indicates which files it looks for and which option groups it recognizes.

Note: Option files used with MySQL Cluster programs are covered in Section 15.4, “MySQL Cluster Configuration”.

On Windows, MySQL programs read startup options from the following files:

Filename Purpose
\my.ini Global options
Global options
\my.ini Global Options
The file specified with , if any

represents the location of your Windows directory. This is commonly or . You can determine its exact location from the value of the environment variable using the following command: 

C:\>

represents the installation directory of MySQL. This is typically \MySQL\MySQL 5.0 Server where represents the programs directory (usually on English-language versions of Windows), when MySQL 5.0 has been installed using the installation and configuration wizards. See Section 2.3.4.14, “The Location of the my.ini File”.

On Unix, MySQL programs read startup options from the following files:

Filename Purpose
Global options
Server-specific options
The file specified with , if any
User-specific options

is an environment variable containing the path to the directory in which the server-specific file resides. (This was prior to MySQL version 5.0.3.)

If is not set and you start the server using the mysqld_safe program, mysqld_safe attempts to set as follows:

  • Let and represent the pathnames of the MySQL base directory and data directory, respectively.

  • If there is a file in but not in , mysqld_safe sets to .

  • Otherwise, if is not set and there is no file in , mysqld_safe sets to .

In MySQL , use of as the location for is deprecated. is a better location.

Typically, is for a binary installation or for a source installation. Note that this is the data directory location that was specified at configuration time, not the one specified with the option when mysqld starts. Use of at runtime has no effect on where the server looks for option files, because it looks for them before processing any options.

MySQL looks for option files in the order just described and reads any that exist. If an option file that you want to use does not exist, create it with a plain text editor.

If multiple instances of a given option are found, the last instance takes precedence. There is one exception: For mysqld, the first instance of the option is used as a security precaution, to prevent a user specified in an option file from being overridden on the command line.

Note: On Unix platforms, MySQL ignores configuration files that are world-writable. This is intentional, and acts as a security measure.

Any long option that may be given on the command line when running a MySQL program can be given in an option file as well. To get the list of available options for a program, run it with the option.

The syntax for specifying options in an option file is similar to command-line syntax, except that you omit the leading two dashes. For example, or on the command line should be specified as or in an option file. To specify an option of the form in an option file, write it as .

Empty lines in option files are ignored. Non-empty lines can take any of the following forms:

  • ,

    Comment lines start with ‘’ or ‘’. A ‘’ comment can start in the middle of a line as well.

  • ]

    is the name of the program or group for which you want to set options. After a group line, any option-setting lines apply to the named group until the end of the option file or another group line is given.

  • This is equivalent to on the command line.

  • =

    This is equivalent to = on the command line. In an option file, you can have spaces around the ‘’ character, something that is not true on the command line. You can enclose the value within single quotes or double quotes, which is useful if the value contains a ‘’ comment character or whitespace.

For options that take a numeric value, the value can be given with a suffix of , , or (either uppercase or lowercase) to indicate a multiplier of 1024, 10242 or 10243. For example, the following command tells mysqladmin to ping the server 1024 times, sleeping 10 seconds between each ping: 

mysql>

Leading and trailing blanks are automatically deleted from option names and values. You may use the escape sequences ‘’, ‘’, ‘’, ‘’, ‘’, and ‘’ in option values to represent the backspace, tab, newline, carriage return, backslash, and space characters.

Because the ‘’ escape sequence represents a single backslash, you must write each ‘’ as ‘’. Alternatively, you can specify the value using ‘’ rather than ‘’ as the pathname separator.

If an option group name is the same as a program name, options in the group apply specifically to that program. For example, the and groups apply to the mysqld server and the mysql client program, respectively.

The option group is read by all client programs (but not by mysqld). This allows you to specify options that apply to all clients. For example, is the perfect group to use to specify the password that you use to connect to the server. (But make sure that the option file is readable and writable only by yourself, so that other people cannot find out your password.) Be sure not to put an option in the group unless it is recognized by all client programs that you use. Programs that do not understand the option quit after displaying an error message if you try to run them.

Here is a typical global option file: 

[client]
port=3306
socket=/tmp/mysql.sock

[mysqld]
port=3306
socket=/tmp/mysql.sock
key_buffer_size=16M
max_allowed_packet=8M

[mysqldump]
quick

The preceding option file uses = syntax for the lines that set the and variables.

Here is a typical user option file: 

[client]
# The following password will be sent to all standard MySQL clients
password="my_password"

[mysql]
no-auto-rehash
connect_timeout=2

[mysqlhotcopy]
interactive-timeout

If you want to create option groups that should be read by mysqld servers from a specific MySQL release series only, you can do this by using groups with names of , , and so forth. The following group indicates that the option should be used only by MySQL servers with 5.0.x version numbers: 

[mysqld-5.0]
new

Beginning with MySQL 5.0.4, it is possible to use directives in option files to include other option files and to search specific directories for option files. For example, to include the file, you can use the following directive: 

!include /home/me/myopt.cnf

To search the directory and read option files found there, you would use this directive: 

!includedir /home/mydir

Note: Currently, any files to be found and included using the directive on Unix operating systems must have filenames ending in . On Windows, this directive checks for files with the or extension.

Note that options read from included files are applied in the context of the current option group. Suppose that you were to write the following lines in : 

[mysqld]
!include /home/mydir/myopt.cnf

In this case, the file is processed only for the server, and the directive is ignored by any client applications. However, if you were to use the following lines, the directory is checked for option files by mysqldump only, and not by the server or by any other client applications: 

[mysqldump]
!includedir /home/mydir/my-dump-options

If you have a source distribution, you can find sample option files named .cnf in the directory. If you have a binary distribution, look in the directory under your MySQL installation directory. On Windows, the sample option files may be located in the MySQL installation directory (see earlier in this section or Chapter 2, Installing and Upgrading MySQL, if you do not know where this is). Currently, there are sample option files for small, medium, large, and very large systems. To experiment with one of these files, copy it to on Windows or to in your home directory on Unix.

Note: On Windows, the option file extension might not be displayed.

All MySQL programs that support option files handle the following options. They affect option-file handling, so they must be given on the command line and not in an option file. To work properly, each of these options must immediately follow the command name, with the exception that may be used immediately after or .

  • Don't read any option files.

  • Print the program name and all options that it gets from option files.

  • Use only the given option file. is the full pathname to the file.

  • Read this option file after the global option file but (on Unix) before the user option file. is the full pathname to the file. As of MySQL 5.0.6, if the file does not exist or is otherwise inaccessible, the program will exit with an error.

  • If this option is given, the program reads not only its usual option groups, but also groups with the usual names and a suffix of . For example, the mysql client normally reads the and groups. If the option is given, mysql also reads the and groups. This option was added in MySQL 5.0.10.

In shell scripts, you can use the my_print_defaults program to parse option files and see what options would be used by a given program. The following example shows the output that my_print_defaults might produce when asked to show the options found in the and groups: 

shell> 
--port=3306
--socket=/tmp/mysql.sock
--no-auto-rehash

Note for developers: Option file handling is implemented in the C client library simply by processing all options in the appropriate group or groups before any command-line arguments. This works well for programs that use the last instance of an option that is specified multiple times. If you have a C or C++ program that handles multiply specified options this way but that doesn't read option files, you need add only two lines to give it that capability. Check the source code of any of the standard MySQL clients to see how to do this.

Several other language interfaces to MySQL are based on the C client library, and some of them provide a way to access option file contents. These include Perl and Python. For details, see the documentation for your preferred interface.

4.3.2.1. Preconfigured Option Files

MySQL provides a number of preconfigured option files that can be used as a basis for tuning the MySQL server. Look in your installation directory for files such as , , , and , which you can rename and copy to the appropriate location for use as a base configuration file. Regarding names and appropriate location, see the general information provided in Section 4.3.2, “Using Option Files”. On Windows, those files have a rather than a extension.

4.3.3. Using Environment Variables to Specify Options

To specify an option using an environment variable, set the variable using the syntax appropriate for your command processor. For example, on Windows or NetWare, you can set the variable to specify your MySQL account name. To do so, use this syntax: 

SET USER=

The syntax on Unix depends on your shell. Suppose that you want to specify the TCP/IP port number using the variable. Typical syntax (such as for sh, , zsh, and so on) is as follows: 

MYSQL_TCP_PORT=3306
export MYSQL_TCP_PORT

The first command sets the variable, and the command exports the variable to the shell environment so that its value becomes accessible to MySQL and other processes.

For csh and tcsh, use setenv to make the shell variable available to the environment: 

setenv MYSQL_TCP_PORT 3306

The commands to set environment variables can be executed at your command prompt to take effect immediately, but the settings persist only until you log out. To have the settings take effect each time you log in, place the appropriate command or commands in a startup file that your command interpreter reads each time it starts. Typical startup files are for Windows, for bash, or for tcsh. Consult the documentation for your command interpreter for specific details.

Appendix F, Environment Variables, lists all environment variables that affect MySQL program operation.

4.3.4. Using Options to Set Program Variables

Many MySQL programs have internal variables that can be set at runtime. Program variables are set the same way as any other long option that takes a value. For example, mysql has a variable that controls the maximum size of its communication buffer. To set the variable for mysql to a value of 16MB, use either of the following commands: 

shell> 
shell>

The first command specifies the value in bytes. The second specifies the value in megabytes. For variables that take a numeric value, the value can be given with a suffix of , , or (either uppercase or lowercase) to indicate a multiplier of 1024, 10242 or 10243. (For example, when used to set , the suffixes indicate units of kilobytes, megabytes, or gigabygtes.)

In an option file, variable settings are given without the leading dashes: 

[mysql]
max_allowed_packet=16777216

Or: 

[mysql]
max_allowed_packet=16M

If you like, underscores in a variable name can be specified as dashes. The following option groups are equivalent. Both set the size of the server's key buffer to 512MB: 

[mysqld]
key_buffer_size=512M

[mysqld]
key-buffer-size=512M

Note: Before MySQL 4.0.2, the only syntax for setting program variables was = (or = in option files). This syntax still is recognized, but is deprecated as of MySQL 4.0.2.

Many server system variables can also be set at runtime. For details, see Section 5.2.3.2, “Dynamic System Variables”.

previous page start next page