DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

(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