(mysql.info) option-files
Info Catalog
(mysql.info) command-line-options
(mysql.info) program-options
(mysql.info) environment-variable-options
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.
To determine whether a program reads option files, invoke it with the
-help option (-verbose and -help 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-NEWLINE- mysql-cluster-configuration.
On Windows, MySQL programs read startup options from the following
files:
*Filename* *Purpose*
`WINDIR\my.ini' Global options
`C:\my.cnf' Global options
`INSTALLDIR\my.ini' Global Options
`defaults-extra-file' The file specified with -defaults-extra-file=PATH,
if any
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%
INSTALLDIR represents the installation directory of MySQL. This is
typically `C:\PROGRAMDIR\MySQL\MySQL 5.0 Server' where PROGRAMDIR
represents the programs directory (usually `Program Files' on
English-language versions of Windows), when MySQL 5.0 has been
installed using the installation and configuration wizards. See
mysql-config-wizard-file-location.
On Unix, MySQL programs read startup options from the following files:
*Filename* *Purpose*
`/etc/my.cnf' Global options
`$MYSQL_HOME/my.cnf' Server-specific options
`defaults-extra-file' The file specified with -defaults-extra-file=PATH,
if any
`~/.my.cnf' User-specific options
`MYSQL_HOME' is an environment variable containing the path to the
directory in which the server-specific `my.cnf' file resides. (This was
DATADIR prior to MySQL version 5.0.3.)
If `MYSQL_HOME' is not set and you start the server using the
`mysqld_safe' program, `mysqld_safe' attempts to set `MYSQL_HOME' as
follows:
* Let BASEDIR and DATADIR represent the pathnames of the MySQL base
directory and data directory, respectively.
* If there is a `my.cnf' file in DATADIR but not in BASEDIR,
`mysqld_safe' sets `MYSQL_HOME' to DATADIR.
* Otherwise, if `MYSQL_HOME' is not set and there is no `my.cnf'
file in DATADIR, `mysqld_safe' sets `MYSQL_HOME' to BASEDIR.
Typically, DATADIR 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 the -datadir option 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 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 -user option is used as a security precaution, to keep
a user specified on an option file from being overridden on the command
line.
* 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 -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 ‘`;'’. 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-setting 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. 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 `K', `M', or `G' (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> mysqladmin --count=1K --sleep=10 ping
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.
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 `[mysqld]'
and `[mysql]' groups apply to the `mysqld' server and the `mysql'
client program, respectively.
The `[client]' 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, `[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 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 `VAR_NAME=VALUE' syntax for the lines
that set the `key_buffer_size' and `max_allowed_packet' 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 `[mysqld-4.1]', `[mysqld-5.0]', and so
forth. The following group indicates that the -new 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 `!include' directives
in option files to include other option files and `!includedir' to
search specific directories for option files. For example, to include
the `/home/mydir/myopt.cnf' file, you can use the following directive:
!include /home/me/myopt.cnf
To search the `/home/mydir' directory and read option files found
there, you would use this directive:
!includedir /home/mydir
* Currently, any files to be found and included using the
`!includedir' directive on Unix operating systems _must_ have filenames
ending in `.cnf'. On Windows, this directive checks for files with the
`.ini' or `.cnf' 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 `my.cnf':
[mysqld]
!include /home/mydir/myopt.cnf
In this case, the `myopt.cnf' file is processed only for the server,
and the `!include' directive is ignored by any client applications.
However, if you were to use the following lines, the directory
`/home/mydir/my-dump-options' 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 `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. On Windows, the sample option files may
be located in the MySQL installation directory (see earlier in this
section or installing, 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
`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
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 -print-defaults may be used immediately after -defaults-file or
-defaults-extra-file.
* -no-defaults
Don't read any option files.
* -print-defaults
Print the program name and all options that it gets from option
files.
* -defaults-file=FILE_NAME
Use only the given option file. FILE_NAME is the full pathname to
the file.
* -defaults-extra-file=FILE_NAME
Read this option file after the global option file but (on Unix)
before the user option file. FILE_NAME is the full pathname to
the file.
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 `[client]' and
`[mysql]' groups:
shell> my_print_defaults client mysql
--port=3306
--socket=/tmp/mysql.sock
--no-auto-rehash
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.
Info Catalog
(mysql.info) command-line-options
(mysql.info) program-options
(mysql.info) environment-variable-options
automatically generated byinfo2html