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 --help
option.
(For mysqld,
use --verbose
and --help
.)
If the program reads option files, the help message indicates which files it looks for and which option groups it recognizes.
On Windows, MySQL programs read startup options from the following files, in the specified order (top items are used first).
File Name | Purpose |
---|---|
,
|
Global options |
,
|
Global options |
C:\my.ini , C:\my.cnf |
Global options |
,
|
Global options |
defaults-extra-file |
The file specified with --defaults-extra-file= ,
if any |
%PROGRAMDATA%
represents the file system
directory that contains application data for all users on the host. This path defaults to C:\ProgramData
on
Microsoft Windows Vista and greater, and C:\Documents
and Settings\All Users\Application Data
on older versions of Microsoft Windows.
%WINDIR%
represents the location of your
Windows directory. This is commonly C:\WINDOWS
. You can determine
its exact location from the value of the WINDIR
environment
variable using the following command:
C:\> echo %WINDIR%
INSTALLDIR
represents
the MySQL installation directory. This is typically C:\
where PROGRAMDIR
\MySQL\MySQL
5.5 ServerPROGRAMDIR
represents
the programs directory (usually Program Files
on English-language
versions of Windows), when MySQL 5.5 has been installed using the installation and configuration wizards. SeeSection 2.3.3,
“Installing MySQL on Microsoft Windows Using MySQL Installer”.
On Unix, Linux and Mac OS X, MySQL programs read startup options from the following files, in the specified order (top items are used first).
File Name | Purpose |
---|---|
/etc/my.cnf |
Global options |
/etc/mysql/my.cnf |
Global options |
|
Global options |
$MYSQL_HOME/my.cnf |
Server-specific options |
defaults-extra-file |
The file specified with --defaults-extra-file= ,
if any |
~/.my.cnf |
User-specific options |
~
represents the current user's home directory (the value
of $HOME
).
SYSCONFDIR
represents
the directory specified with the SYSCONFDIR
option
to CMake when
MySQL was built. By default, this is the etc
directory located
under the compiled-in installation directory.
MYSQL_HOME
is an environment variable containing
the path to the directory in which the server-specific my.cnf
file
resides. If MYSQL_HOME
is not set and
you start the server using the mysqld_safe program, mysqld_safeattempts
to set MYSQL_HOME
as follows:
-
Let
BASEDIR
andDATADIR
represent the path names of the MySQL base directory and data directory, respectively. -
If there is a
my.cnf
file inDATADIR
but not inBASEDIR
, mysqld_safe setsMYSQL_HOME
toDATADIR
. -
Otherwise, if
MYSQL_HOME
is not set and there is nomy.cnf
file inDATADIR
, mysqld_safe setsMYSQL_HOME
toBASEDIR
.
In MySQL 5.5, use of DATADIR
as
the location for my.cnf
is deprecated.
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: Formysqld,
the first instance
of the --user
option
is used as a security precaution, to prevent a user specified in an option file from being overridden on the command line.
On Unix platforms, MySQL ignores configuration files that are world-writable. This is intentional as a security measure.
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 enables 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.
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-5.1]
, [mysqld-5.5]
,
and so forth. The following group indicates that the --new
option
should be used only by MySQL servers with 5.5.x version numbers:
[mysqld-5.5] new
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,
use the following directive:
!include /home/mydir/myopt.cnf
To search the /home/mydir
directory and read option files
found there, use this directive:
!includedir /home/mydir
There is no guarantee about the order in which the option files in the directory will be read.
Currently, any files to be found and included using the !includedir
directive
on Unix operating systems musthave
file names ending in .cnf
. On Windows, this directive checks
for files with the .ini
or .cnf
extension.
Write the contents of an included option file like any other option file. That is, it should contain groups of options, each preceded by a [
line
that indicates the program to which the options apply.group
]
While an included file is being processed, only those options in groups that the current program is looking for are used. Other groups are ignored. Suppose that a my.cnf
file
contains this line:
!include /home/mydir/myopt.cnf
And suppose that /home/mydir/myopt.cnf
looks like this:
[mysqladmin] force [mysqld] key_buffer_size=16M
If my.cnf
is processed by mysqld,
only the [mysqld]
group in /home/mydir/myopt.cnf
is
used. If the file is processed by mysqladmin,
only the [mysqladmin]
group is used. If
the file is processed by any other program, no options in /home/mydir/myopt.cnf
are
used.
The !includedir
directive is processed
similarly except that all option files in the named directory are read.