MySQL Reference Manual for version 4.0.18.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3.2 Using Option Files

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 they need not be entered on the command line each time you run a program. Option file capability is available from MySQL 3.22 on.

The following programs support option files: mysql, mysqladmin, mysqld, mysqld_safe, mysql.server, mysqldump, mysqlimport, mysqlshow, mysqlcheck, mysqlhotcopy, myisamchk, and myisampack.

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

Filename Purpose
windows-dir\my.ini Global options
C:\my.cnf Global options

windows-dir represents the location of your Windows directory. This is commonly `C:\Windows' or `C:\WinNT'. Check the value of the WINDIR environment vairable to see where this directory is located on your system.

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

Filename Purpose
/etc/my.cnf Global options
DATADIR/my.cnf Server-specific options
defaults-extra-file The file specified with --defaults-extra-file=path, if any
~/.my.cnf User-specific options

DATADIR represents the location of the MySQL data directory. Typically this is `/usr/local/mysql/data' for a binary installation or `/usr/local/var' for a source installation. Note that this is the data directory location that was specified at configuration time, not the one specified with --datadir when mysqld starts! Use of --datadir at runtime has no effect on where the server looks for option files, because it looks for them before processing any command-line arguments.

MySQL looks for option files in the order listed above and reads any that exist. If multiple option files exist, an option specified in a file read later takes precedence over the same option specified in a file read earlier.

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 --help 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, --quick or --host=localhost on the command line are specified as quick or host=localhost in an option file. To specify an option of the form --loose-opt_name in an option file, write it as loose-opt_name.

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

#comment
;comment
Comment lines start with `#' or `;'. As of MySQL 4.0.14, a `#'-comment can start in the middle of a line as well.

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

opt_name
This is equivalent to --opt_name on the command-line.

opt_name=value
This is equivalent to --opt_name=value on the command-line. In an option file, you can have spaces around the `=' character, something that is not true on the command line. As of MySQL 4.0.16, you can quote the value with double quotes or single quotes. This is useful if the value contains a comment character or whitespace.

set-variable = var_name=value
Set the program variable var_name to the given value. This is equivalent to --set-variable=var_name=value on the command-line. Spaces are allowed around the first `=' character but not around the second. This syntax is deprecated as of MySQL 4.0. See 4.3.4 Using Options to Set Program Variables for more information on setting program variables.

Note that for options and values, all leading and trailing blanks are automatically deleted. You may use the escape sequences `\b', `\t', `\n', `\r', `\\', and `\s' in option values to represent the backspace, tab, newline, carriage return, and space characters.

On Windows, if an option value represents a pathname, you should specify the value using `/' rather than `\' as the pathname separator. If you use `\', you must double it as `\\', because `\' is the escape character in MySQL.

If an option group name is the same as a program name, options in the group apply specifically to that program.

The [client] option group is read by all client programs (but not by mysqld). This allows you to specify options that apply to every client. For example, [client] is the perfect group to use to specify the password that you use to connect to the server. (But make sure 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 [client] group unless it is recognized by all client programs.

As of MySQL 4.0.14, if you want to create options that should only be read by one specific mysqld server release series, you can do this with [mysqld-4.0], [mysqld-4.1], and so forth:

 
[mysqld-4.0]
new

The above new option will be used only with MySQL server versions 4.0.x.

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=1M

[mysqldump]
quick

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
set-variable = connect_timeout=2

[mysqlhotcopy]
interactive-timeout

If you have a source distribution, you will find sample option files named `my-xxxx.cnf' in the `support-files' directory. If you have a binary distribution, look in the `support-files' directory under your MySQL installation directory (typically `C:\mysql' on Windows or `/usr/local/mysql' on Unix). Currently there are sample option files for small, medium, large, and very large systems. To experiment with one of these files, copy it to `C:\my.cnf' on Windows or to `.my.cnf' in your home directory on Unix.

All MySQL programs that support option files support the following command-line options:

--no-defaults
Don't read any option files.

--print-defaults
Print the program name and all options that it will get from option files.

--defaults-file=path_name
Use only the given option file. path_name is the full pathname to the file.

--defaults-extra-file=path_name
Read this option file after the global option file but before the user option file. path_name is the full pathname to the file.

Note that to work properly, each of these options must immediately follow the command name on the command line, with the exception that --print-defaults may be used immediately after --defaults-file or --defaults-extra-file.

In shell scripts, you can use the my_print_defaults program to parse the option files. The following example shows the output that my_print_defaults might produce when asked to show the options found in the [client] and [mysql] groups:

 
shell> my_print_defaults client mysql
--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 matching options (that is, options in the appropriate group) before any command-line arguments. This works nicely 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 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. See the documentation for your preferred interface for details.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by rdg (Feb 25 2004) using texi2html