(mysql.info.gz) Option files
Info Catalog
(mysql.info.gz) Command-line options
(mysql.info.gz) Program Options
(mysql.info.gz) Environment variable options
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 that 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: `myisamchk', `myisampack',
`mysql', `mysql.server', `mysqladmin', `mysqlbinlog', `mysqlcc',
`mysqlcheck', `mysqld_safe', `mysqldump', `mysqld', `mysqlhotcopy',
`mysqlimport', and `mysqlshow'.
On Windows, MySQL programs read startup options from the following
files:
*Filename* *Purpose*
`WINDIR\my.ini' Global options
`C:\my.cnf' Global options
WINDIR represents the location of your Windows directory. This is
commonly `C:\Windows' or `C:\WinNT'. You can determine its exact
location from the value of the `WINDIR' environment variable using the
following command:
C:\> echo %WINDIR%
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 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 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 should be
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 OPT_NAME 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
Program variables:: for more information on setting program
variables.
Leading and trailing blanks are automatically deleted from option names
and values. 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 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 `[client]' group unless it is recognized by _all_ client programs
that you use. Programs that do not understand the option will quit after
displaying an error message if you try to run them.
As of MySQL 4.0.14, if you want to create option groups that should be
read only by one specific `mysqld' server release series, you can do
this by using groups with names of `[mysqld-4.0]', `[mysqld-4.1]', and
so forth. The following group indicates that the `--new' option should
be used only by MySQL servers with 4.0.x version numbers:
[mysqld-4.0]
new
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 `VAR_NAME=VALUE' syntax for the lines
that set the `key_buffer_size' and `max_allowed_packet' variables.
Prior to MySQL 4.0.2, you would need to use `set-variable' syntax
instead (described earlier in this section).
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
This option file uses `set-variable' syntax to set the
`connect_timeout' variable. For MySQL 4.0.2 and up, you can also set
the variable using just `connect_timeout=2'.
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). On Windows the sample option files may
also be located in the MySQL installation directory. 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.
* On Windows, the `.cnf' option file extension might not be
displayed.
All MySQL programs that support option files handle 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.
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
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.
Info Catalog
(mysql.info.gz) Command-line options
(mysql.info.gz) Program Options
(mysql.info.gz) Environment variable options
automatically generated byinfo2html