DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(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