4.3 Server and Server-Startup Programs

Menu:
mysqld:: mysqld -- The MySQL Server
mysqld-safe:: mysqld_safe -- MySQL Server Startup Script
mysql-server:: mysql.server -- MySQL Server Startup Script
mysqld-multi:: mysqld_multi -- Manage Multiple MySQL Servers

This section describes *note 'mysqld': mysqld, the MySQL server, and several programs that are used to start the server.

File: manual.info.tmp, Node: mysqld, Next: mysqld-safe, Prev: programs-server, Up: programs-server

4.3.1 mysqld -- The MySQL Server

*note 'mysqld': mysqld, also known as MySQL Server, is a single multithreaded program that does most of the work in a MySQL installation. It does not spawn additional processes. MySQL Server manages access to the MySQL data directory that contains databases and tables. The data directory is also the default location for other information such as log files and status files.

Note:

Some installation packages contain a debugging version of the server named note 'mysqld-debug': mysqld. Invoke this version instead of note 'mysqld': mysqld. for debugging support, memory allocation checking, and trace file support (see *note making-trace-files::).

When MySQL server starts, it listens for network connections from client programs and manages access to databases on behalf of those clients.

The *note 'mysqld': mysqld. program has many options that can be specified at startup. For a complete list of options, run this command:

 mysqld --verbose --help

MySQL Server also has a set of system variables that affect its operation as it runs. System variables can be set at server startup, and many of them can be changed at runtime to effect dynamic server reconfiguration. MySQL Server also has a set of status variables that provide information about its operation. You can monitor these status variables to access runtime performance characteristics.

For a full description of MySQL Server command options, system variables, and status variables, see note mysqld-server::. For information about installing MySQL and setting up the initial configuration, see note installing::.

File: manual.info.tmp, Node: mysqld-safe, Next: mysql-server, Prev: mysqld, Up: programs-server

4.3.2 mysqld_safe -- MySQL Server Startup Script

note 'mysqld_safe': mysqld-safe. is the recommended way to start a note 'mysqld': mysqld. server on Unix. *note 'mysqld_safe': mysqld-safe. adds some safety features such as restarting the server when an error occurs and logging runtime information to an error log. A description of error logging is given later in this section.

Note:

For some Linux platforms, MySQL installation from RPM or Debian packages includes systemd support for managing MySQL server startup and shutdown. On these platforms, note 'mysqld_safe': mysqld-safe. is not installed because it is unnecessary. For more information, see note using-systemd::.

One implication of the non-use of *note 'mysqld_safe': mysqld-safe. on platforms that use systemd for server management is that use of '[mysqld_safe]' or '[safe_mysqld]' sections in option files is not supported and might lead to unexpected behavior.

note 'mysqld_safe': mysqld-safe. tries to start an executable named note 'mysqld': mysqld. To override the default behavior and specify explicitly the name of the server you want to run, specify a '--mysqld' or '--mysqld-version' option to note 'mysqld_safe': mysqld-safe. You can also use '--ledir' to indicate the directory where note 'mysqld_safe': mysqld-safe. should look for the server.

Many of the options to note 'mysqld_safe': mysqld-safe. are the same as the options to note 'mysqld': mysqld. See *note server-options::.

Options unknown to note 'mysqld_safe': mysqld-safe. are passed to note 'mysqld': mysqld. if they are specified on the command line, but ignored if they are specified in the '[mysqld_safe]' group of an option file. See *note option-files::.

note 'mysqld_safe': mysqld-safe. reads all options from the '[mysqld]', '[server]', and '[mysqld_safe]' sections in option files. For example, if you specify a '[mysqld]' section like this, note 'mysqld_safe': mysqld-safe. finds and uses the '--log-error' option:

 [mysqld]
 log-error=error.log

For backward compatibility, *note 'mysqld_safe': mysqld-safe. also reads '[safe_mysqld]' sections, but to be current you should rename such sections to '[mysqld_safe]'.

note 'mysqld_safe': mysqld-safe. accepts options on the command line and in option files, as described in the following table. For information about option files used by MySQL programs, see note option-files::.

mysqld_safe Options

Option Name Description IntroducedDeprecated

-basedir

Path to MySQL installation directory

-core-file-size

Size of core file that mysqld should be able to create

-datadir

Path to data directory

-defaults-extra-file

Read named option file in addition to usual option files

-defaults-file

Read only named option file

-help

Display help message and exit

-ledir

Path to directory where server is located

-log-error

Write error log to named file

-malloc-lib

Alternative malloc library to use for mysqld

-mysqld

Name of server program to start (in ledir directory)

-mysqld-safe-log-timestamps

Timestamp format 5.7.11 for logging

-mysqld-version

Suffix for server program name

-nice

Use nice program to set server scheduling priority

-no-defaults

Read no option files

-open-files-limit

Number of files that mysqld should be able to open

-pid-file

Path name of server process ID file

-plugin-dir

Directory where plugins are installed

-port

Port number on which to listen for TCP/IP connections

-skip-kill-mysqld

Do not try to kill stray mysqld processes

-skip-syslog

Do not write Yes error messages to
syslog; use error log file

-socket

Socket file on which to listen for Unix socket connections

-syslog

Write error Yes messages to
syslog

-syslog-tag

Tag suffix for Yes messages written
to syslog

-timezone

Set TZ time zone environment variable to named value

-user

Run mysqld as user having name user_name or numeric user ID user_id

'--help'

Command-Line Format

'--help'

Command-Line Format

'--help'

Display a help message and exit.
'--basedir=DIR_NAME'

Command-Line Format

'--basedir=dir_name'

Type

Directory name

Command-Line Format

'--basedir=dir_name'

Type

Directory name

The path to the MySQL installation directory.
'--core-file-size=SIZE'

Command-Line Format

'--core-file-size=size'

Type

String

Command-Line Format

'--core-file-size=size'

Type

String

The size of the core file that *note 'mysqld': mysqld. should be able to create. The option value is passed to 'ulimit -c'.
'--datadir=DIR_NAME'

Command-Line Format

'--datadir=dir_name'

Type

Directory name

Command-Line Format

'--datadir=dir_name'

Type

Directory name

The path to the data directory.
'--defaults-extra-file=FILE_NAME'

Command-Line Format

'--defaults-extra-file=file_name'

Type

File name

Command-Line Format

'--defaults-extra-file=file_name'

Type

File name

Read this option file in addition to the usual option files. If the file does not exist or is otherwise inaccessible, the server exits with an error. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory. This must be the first option on the command line if it is used.

For additional information about this and other option-file options, see *note option-file-options::.
'--defaults-file=FILE_NAME'

Command-Line Format

'--defaults-file=file_name'

Type

File name

Use only the given option file. If the file does not exist or is otherwise inaccessible, the server exits with an error. If FILE_NAME is not an absolute path name, it is interpreted relative to the current directory. This must be the first option on the command line if it is used.

For additional information about this and other option-file options, see *note option-file-options::.
'--ledir=DIR_NAME'

Command-Line Format

'--ledir=dir_name'

Type

Directory name

If *note 'mysqld_safe': mysqld-safe. cannot find the server, use this option to indicate the path name to the directory where the server is located.

As of MySQL 5.7.17, this option is accepted only on the command line, not in option files. On platforms that use systemd, the value can be specified in the value of 'MYSQLD_OPTS'. See *note using-systemd::.
'--log-error=FILE_NAME'

Command-Line Format

'--log-error=file_name'

Type

File name

Write the error log to the given file. See *note error-log::.
'--mysqld-safe-log-timestamps'

Command-Line Format

'--mysqld-safe-log-timestamps=type'

Introduced

5.7.11

Type

Enumeration

Default Value

'utc'

Valid Values

'system' 'hyphen' 'legacy'

This option controls the format for timestamps in log output produced by note 'mysqld_safe': mysqld-safe. The following list describes the permitted values. For any other value, note 'mysqld_safe': mysqld-safe. logs a warning and uses 'UTC' format.
```
* 'UTC', 'utc'

  ISO 8601 UTC format (same as '--log_timestamps=UTC' for the
  server).  This is the default.

* 'SYSTEM', 'system'

  ISO 8601 local time format (same as '--log_timestamps=SYSTEM'
  for the server).

* 'HYPHEN', 'hyphen'

  YY-MM-DD H:MM:SS format, as in *note 'mysqld_safe':
  mysqld-safe. for MySQL 5.6.

* 'LEGACY', 'legacy'

  YYMMDD HH:MM:SS format, as in *note 'mysqld_safe':
  mysqld-safe. prior to MySQL 5.6.
```
This option was added in MySQL 5.7.11.
'--malloc-lib=[LIB_NAME]'

Command-Line Format

'--malloc-lib=[lib-name]'

Type

String

The name of the library to use for memory allocation instead of the system 'malloc()' library. As of MySQL 5.7.15, the option value must be one of the directories '/usr/lib', '/usr/lib64', '/usr/lib/i386-linux-gnu', or '/usr/lib/x86_64-linux-gnu'. Prior to MySQL 5.7.15, any library can be used by specifying its path name, but there is a shortcut form to enable use of the 'tcmalloc' library that is shipped with binary MySQL distributions for Linux in MySQL 5.7. It is possible for the shortcut form not to work under certain configurations, in which case you should specify a path name instead.

Note:

As of MySQL 5.7.13, MySQL distributions no longer include a 'tcmalloc' library.

The '--malloc-lib' option works by modifying the 'LD_PRELOAD' environment value to affect dynamic linking to enable the loader to find the memory-allocation library when *note 'mysqld': mysqld. runs:
```
* If the option is not given, or is given without a value
  ('--malloc-lib='), 'LD_PRELOAD' is not modified and no attempt
  is made to use 'tcmalloc'.

* Prior to MySQL 5.7.31, if the option is given as
  '--malloc-lib=tcmalloc', *note 'mysqld_safe': mysqld-safe.
  looks for a 'tcmalloc' library in '/usr/lib' and then in the
  MySQL 'pkglibdir' location (for example,
  '/usr/local/mysql/lib' or whatever is appropriate).  If
  'tmalloc' is found, its path name is added to the beginning of
  the 'LD_PRELOAD' value for *note 'mysqld': mysqld.  If
  'tcmalloc' is not found, *note 'mysqld_safe': mysqld-safe.
  aborts with an error.

  As of MySQL 5.7.31, 'tcmalloc' is not a permitted value for
  the '--malloc-lib' option.

* If the option is given as
  '--malloc-lib=/PATH/TO/SOME/LIBRARY', that full path is added
  to the beginning of the 'LD_PRELOAD' value.  If the full path
  points to a nonexistent or unreadable file, *note
  'mysqld_safe': mysqld-safe. aborts with an error.

* For cases where *note 'mysqld_safe': mysqld-safe. adds a path
  name to 'LD_PRELOAD', it adds the path to the beginning of any
  existing value the variable already has.
```
Note:

On systems that manage the server using systemd, *note 'mysqld_safe': mysqld-safe. is not available. Instead, specify the allocation library by setting 'LD_PRELOAD' in '/etc/sysconfig/mysql'.

Linux users can use the 'libtcmalloc_minimal.so' included in binary packages by adding these lines to the 'my.cnf' file:
```
  [mysqld_safe]
  malloc-lib=tcmalloc
```
Those lines also suffice for users on any platform who have installed a 'tcmalloc' package in '/usr/lib'. To use a specific 'tcmalloc' library, specify its full path name. Example:
```
  [mysqld_safe]
  malloc-lib=/opt/lib/libtcmalloc_minimal.so
```
'--mysqld=PROG_NAME'

Command-Line Format

'--mysqld=file_name'

Type

File name

The name of the server program (in the 'ledir' directory) that you want to start. This option is needed if you use the MySQL binary distribution but have the data directory outside of the binary distribution. If *note 'mysqld_safe': mysqld-safe. cannot find the server, use the '--ledir' option to indicate the path name to the directory where the server is located.

As of MySQL 5.7.15, this option is accepted only on the command line, not in option files. On platforms that use systemd, the value can be specified in the value of 'MYSQLD_OPTS'. See *note using-systemd::.
'--mysqld-version=SUFFIX'

Command-Line Format

'--mysqld-version=suffix'

Type

String

This option is similar to the '--mysqld' option, but you specify only the suffix for the server program name. The base name is assumed to be note 'mysqld': mysqld. For example, if you use '--mysqld-version=debug', note 'mysqld_safe': mysqld-safe. starts the note 'mysqld-debug': mysqld. program in the 'ledir' directory. If the argument to '--mysqld-version' is empty, note 'mysqld_safe': mysqld-safe. uses *note 'mysqld': mysqld. in the 'ledir' directory.

As of MySQL 5.7.15, this option is accepted only on the command line, not in option files. On platforms that use systemd, the value can be specified in the value of 'MYSQLD_OPTS'. See *note using-systemd::.
'--nice=PRIORITY'

Command-Line Format

'--nice=priority'

Type

Numeric

Use the 'nice' program to set the server's scheduling priority to the given value.
'--no-defaults'

Command-Line Format

'--no-defaults'

Type

String

Do not read any option files. If program startup fails due to reading unknown options from an option file, '--no-defaults' can be used to prevent them from being read. This must be the first option on the command line if it is used.

For additional information about this and other option-file options, see *note option-file-options::.
'--open-files-limit=COUNT'

Command-Line Format

'--open-files-limit=count'

Type

String

The number of files that *note 'mysqld': mysqld. should be able to open. The option value is passed to 'ulimit -n'.

Note:

You must start *note 'mysqld_safe': mysqld-safe. as 'root' for this to function properly.
'--pid-file=FILE_NAME'

Command-Line Format

'--pid-file=file_name'

Type

File name

The path name that *note 'mysqld': mysqld. should use for its process ID file.

From MySQL 5.7.2 to 5.7.17, *note 'mysqld_safe': mysqld-safe. has its own process ID file, which is always named 'mysqld_safe.pid' and located in the MySQL data directory.
'--plugin-dir=DIR_NAME'

Command-Line Format

'--plugin-dir=dir_name'

Type

Directory name

The path name of the plugin directory.
'--port=PORT_NUM'

Command-Line Format

'--port=number'

Type

Numeric

The port number that the server should use when listening for TCP/IP connections. The port number must be 1024 or higher unless the server is started by the 'root' operating system user.
'--skip-kill-mysqld'

Command-Line Format

'--skip-kill-mysqld'

Do not try to kill stray *note 'mysqld': mysqld. processes at startup. This option works only on Linux.
'--socket=PATH'

Command-Line Format

'--socket=file_name'

Type

File name

The Unix socket file that the server should use when listening for local connections.
'--syslog', '--skip-syslog'

Command-Line Format

'--syslog'

Deprecated

Yes

Command-Line Format

'--skip-syslog'

Deprecated

Yes

'--syslog' causes error messages to be sent to 'syslog' on systems that support the 'logger' program. '--skip-syslog' suppresses the use of 'syslog'; messages are written to an error log file.

When 'syslog' is used for error logging, the 'daemon.err' facility/severity is used for all log messages.

Using these options to control note 'mysqld': mysqld. logging is deprecated as of MySQL 5.7.5. Use the server 'log_syslog' system variable instead. To control the facility, use the server 'log_syslog_facility' system variable. See note error-log-syslog::.
'--syslog-tag=TAG'

Command-Line Format

'--syslog-tag=tag'

Deprecated

Yes

For logging to 'syslog', messages from note 'mysqld_safe': mysqld-safe. and note 'mysqld': mysqld. are written with identifiers of 'mysqld_safe' and 'mysqld', respectively. To specify a suffix for the identifiers, use '--syslog-tag=TAG', which modifies the identifiers to be 'mysqld_safe-TAG' and 'mysqld-TAG'.

Using this option to control note 'mysqld': mysqld. logging is deprecated as of MySQL 5.7.5. Use the server 'log_syslog_tag' system variable instead. See note error-log-syslog::.
'--timezone=TIMEZONE'

Command-Line Format

'--timezone=timezone'

Type

String

Set the 'TZ' time zone environment variable to the given option value. Consult your operating system documentation for legal time zone specification formats.
'--user={USER_NAME|USER_ID}'

Command-Line Format

'--user={user_name|user_id}'

Type

String

Type

Numeric

Run the *note 'mysqld': mysqld. server as the user having the name USER_NAME or the numeric user ID USER_ID. ('User' in this context refers to a system login account, not a MySQL user listed in the grant tables.)

If you execute *note 'mysqld_safe': mysqld-safe. with the '--defaults-file' or '--defaults-extra-file' option to name an option file, the option must be the first one given on the command line or the option file is not used. For example, this command does not use the named option file:

 mysql> mysqld_safe --port=PORT_NUM --defaults-file=FILE_NAME

Instead, use the following command:

 mysql> mysqld_safe --defaults-file=FILE_NAME --port=PORT_NUM

The note 'mysqld_safe': mysqld-safe. script is written so that it normally can start a server that was installed from either a source or a binary distribution of MySQL, even though these types of distributions typically install the server in slightly different locations. (See note installation-layouts::.) *note 'mysqld_safe': mysqld-safe. expects one of the following conditions to be true:

The server and databases can be found relative to the working directory (the directory from which note 'mysqld_safe': mysqld-safe. is invoked). For binary distributions, note 'mysqld_safe': mysqld-safe. looks under its working directory for 'bin' and 'data' directories. For source distributions, it looks for 'libexec' and 'var' directories. This condition should be met if you execute *note 'mysqld_safe': mysqld-safe. from your MySQL installation directory (for example, '/usr/local/mysql' for a binary distribution).
If the server and databases cannot be found relative to the working directory, *note 'mysqld_safe': mysqld-safe. attempts to locate them by absolute path names. Typical locations are '/usr/local/libexec' and '/usr/local/var'. The actual locations are determined from the values configured into the distribution at the time it was built. They should be correct if MySQL is installed in the location specified at configuration time.

Because note 'mysqld_safe': mysqld-safe. tries to find the server and databases relative to its own working directory, you can install a binary distribution of MySQL anywhere, as long as you run note 'mysqld_safe': mysqld-safe. from the MySQL installation directory:

 cd MYSQL_INSTALLATION_DIRECTORY
 bin/mysqld_safe &

If *note 'mysqld_safe': mysqld-safe. fails, even when invoked from the MySQL installation directory, specify the '--ledir' and '--datadir' options to indicate the directories in which the server and databases are located on your system.

note 'mysqld_safe': mysqld-safe. tries to use the 'sleep' and 'date' system utilities to determine how many times per second it has attempted to start. If these utilities are present and the attempted starts per second is greater than 5, note 'mysqld_safe': mysqld-safe. waits 1 full second before starting again. This is intended to prevent excessive CPU usage in the event of repeated failures. (Bug #11761530, Bug #54035)

When you use note 'mysqld_safe': mysqld-safe. to start note 'mysqld': mysqld, note 'mysqld_safe': mysqld-safe. arranges for error (and notice) messages from itself and from note 'mysqld': mysqld. to go to the same destination.

There are several *note 'mysqld_safe': mysqld-safe. options for controlling the destination of these messages:

'--log-error=FILE_NAME': Write error messages to the named error file.
'--syslog': Write error messages to 'syslog' on systems that support the 'logger' program.
'--skip-syslog': Do not write error messages to 'syslog'. Messages are written to the default error log file ('HOST_NAME.err' in the data directory), or to a named file if the '--log-error' option is given.

If none of these options is given, the default is '--skip-syslog'.

When *note 'mysqld_safe': mysqld-safe. writes a message, notices go to the logging destination ('syslog' or the error log file) and 'stdout'. Errors go to the logging destination and 'stderr'.

Note:

Controlling note 'mysqld': mysqld. logging from note 'mysqld_safe': mysqld-safe. is deprecated as of MySQL 5.7.5. Use the server's native 'syslog' support instead. For more information, see *note error-log-syslog::.

File: manual.info.tmp, Node: mysql-server, Next: mysqld-multi, Prev: mysqld-safe, Up: programs-server

4.3.3 mysql.server -- MySQL Server Startup Script

MySQL distributions on Unix and Unix-like system include a script named note 'mysql.server': mysql-server, which starts the MySQL server using note 'mysqld_safe': mysqld-safe. It can be used on systems such as Linux and Solaris that use System V-style run directories to start and stop system services. It is also used by the macOS Startup Item for MySQL.

note 'mysql.server': mysql-server. is the script name as used within the MySQL source tree. The installed name might be different (for example, note 'mysqld': mysqld. or note 'mysql': mysql.). In the following discussion, adjust the name note 'mysql.server': mysql-server. as appropriate for your system.

Note:

For some Linux platforms, MySQL installation from RPM or Debian packages includes systemd support for managing MySQL server startup and shutdown. On these platforms, note 'mysql.server': mysql-server. and note 'mysqld_safe': mysqld-safe. are not installed because they are unnecessary. For more information, see *note using-systemd::.

To start or stop the server manually using the *note 'mysql.server': mysql-server. script, invoke it from the command line with 'start' or 'stop' arguments:

 mysql.server start
 mysql.server stop

note 'mysql.server': mysql-server. changes location to the MySQL installation directory, then invokes note 'mysqld_safe': mysqld-safe. To run the server as some specific user, add an appropriate 'user' option to the '[mysqld]' group of the global '/etc/my.cnf' option file, as shown later in this section. (It is possible that you must edit note 'mysql.server': mysql-server. if you've installed a binary distribution of MySQL in a nonstandard location. Modify it to change location into the proper directory before it runs note 'mysqld_safe': mysqld-safe. If you do this, your modified version of *note 'mysql.server': mysql-server. may be overwritten if you upgrade MySQL in the future; make a copy of your edited version that you can reinstall.)

note 'mysql.server stop': mysql-server. stops the server by sending a signal to it. You can also stop the server manually by executing note 'mysqladmin shutdown': mysqladmin.

To start and stop MySQL automatically on your server, you must add start and stop commands to the appropriate places in your '/etc/rc*' files:

If you use the Linux server RPM package ('MySQL-server-VERSION.rpm'), or a native Linux package installation, the note 'mysql.server': mysql-server. script may be installed in the '/etc/init.d' directory with the name 'mysqld' or 'mysql'. See note linux-installation-rpm::, for more information on the Linux RPM packages.
If you install MySQL from a source distribution or using a binary distribution format that does not install note 'mysql.server': mysql-server. automatically, you can install the script manually. It can be found in the 'support-files' directory under the MySQL installation directory or in a MySQL source tree. Copy the script to the '/etc/init.d' directory with the name note 'mysql': mysql. and make it executable:
```
  cp mysql.server /etc/init.d/mysql
  chmod +x /etc/init.d/mysql
```
After installing the script, the commands needed to activate it to run at system startup depend on your operating system. On Linux, you can use 'chkconfig':
```
  chkconfig --add mysql
```
On some Linux systems, the following command also seems to be necessary to fully enable the *note 'mysql': mysql. script:
```
  chkconfig --level 345 mysql on
```
On FreeBSD, startup scripts generally should go in '/usr/local/etc/rc.d/'. Install the 'mysql.server' script as '/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup. The 'rc(8)' manual page states that scripts in this directory are executed only if their base name matches the '*.sh' shell file name pattern. Any other files or directories present within the directory are silently ignored.
As an alternative to the preceding setup, some operating systems also use '/etc/rc.local' or '/etc/init.d/boot.local' to start additional services on startup. To start up MySQL using this method, append a command like the one following to the appropriate startup file:
```
  /bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'
```
For other systems, consult your operating system documentation to see how to install startup scripts.

*note 'mysql.server': mysql-server. reads options from the '[mysql.server]' and '[mysqld]' sections of option files. For backward compatibility, it also reads '[mysql_server]' sections, but to be current you should rename such sections to '[mysql.server]'.

You can add options for *note 'mysql.server': mysql-server. in a global '/etc/my.cnf' file. A typical 'my.cnf' file might look like this:

 [mysqld]
 datadir=/usr/local/mysql/var
 socket=/var/tmp/mysql.sock
 port=3306
 user=mysql

 [mysql.server]
 basedir=/usr/local/mysql

The note 'mysql.server': mysql-server. script supports the options shown in the following table. If specified, they must be placed in an option file, not on the command line. note 'mysql.server': mysql-server. supports only 'start' and 'stop' as command-line arguments.

mysql.server Option-File Options

Option Name Description Type

'basedir'

Path to Directory name MySQL
installation directory

'datadir'

Path to Directory name MySQL data
directory

'pid-file'

File in File name which server
should write its process ID

'service-startup-timeout'

How long to Integer wait for server startup

'basedir=DIR_NAME'

The path to the MySQL installation directory.
'datadir=DIR_NAME'

The path to the MySQL data directory.
'pid-file=FILE_NAME'

The path name of the file in which the server should write its process ID. The server creates the file in the data directory unless an absolute path name is given to specify a different directory.

If this option is not given, note 'mysql.server': mysql-server. uses a default value of 'HOST_NAME.pid'. The PID file value passed to note 'mysqld_safe': mysqld-safe. overrides any value specified in the '[mysqld_safe]' option file group. Because note 'mysql.server': mysql-server. reads the '[mysqld]' option file group but not the '[mysqld_safe]' group, you can ensure that note 'mysqld_safe': mysqld-safe. gets the same value when invoked from *note 'mysql.server': mysql-server. as when invoked manually by putting the same 'pid-file' setting in both the '[mysqld_safe]' and '[mysqld]' groups.
'service-startup-timeout=SECONDS'

How long in seconds to wait for confirmation of server startup. If the server does not start within this time, *note 'mysql.server': mysql-server. exits with an error. The default value is 900. A value of 0 means not to wait at all for startup. Negative values mean to wait forever (no timeout).

File: manual.info.tmp, Node: mysqld-multi, Prev: mysql-server, Up: programs-server

4.3.4 mysqld_multi -- Manage Multiple MySQL Servers

note 'mysqld_multi': mysqld-multi. is designed to manage several note 'mysqld': mysqld. processes that listen for connections on different Unix socket files and TCP/IP ports. It can start or stop servers, or report their current status.

Note:

For some Linux platforms, MySQL installation from RPM or Debian packages includes systemd support for managing MySQL server startup and shutdown. On these platforms, note 'mysqld_multi': mysqld-multi. is not installed because it is unnecessary. For information about using systemd to handle multiple MySQL instances, see note using-systemd::.

note 'mysqld_multi': mysqld-multi. searches for groups named '[mysqldN]' in 'my.cnf' (or in the file named by the '--defaults-file' option). N can be any positive integer. This number is referred to in the following discussion as the option group number, or GNR. Group numbers distinguish option groups from one another and are used as arguments to note 'mysqld_multi': mysqld-multi. to specify which servers you want to start, stop, or obtain a status report for. Options listed in these groups are the same that you would use in the '[mysqld]' group used for starting note 'mysqld': mysqld. (See, for example, note automatic-start::.) However, when using multiple servers, it is necessary that each one use its own value for options such as the Unix socket file and TCP/IP port number. For more information on which options must be unique per server in a multiple-server environment, see *note multiple-servers::.

To invoke *note 'mysqld_multi': mysqld-multi, use the following syntax:

 mysqld_multi [OPTIONS] {start|stop|reload|report} [GNR[,GNR] ...]

'start', 'stop', 'reload' (stop and restart), and 'report' indicate which operation to perform. You can perform the designated operation for a single server or multiple servers, depending on the GNR list that follows the option name. If there is no list, *note 'mysqld_multi': mysqld-multi. performs the operation for all servers in the option file.

Each GNR value represents an option group number or range of group numbers. The value should be the number at the end of the group name in the option file. For example, the GNR for a group named '[mysqld17]' is '17'. To specify a range of numbers, separate the first and last numbers by a dash. The GNR value '10-13' represents groups '[mysqld10]' through '[mysqld13]'. Multiple groups or group ranges can be specified on the command line, separated by commas. There must be no whitespace characters (spaces or tabs) in the GNR list; anything after a whitespace character is ignored.

This command starts a single server using option group '[mysqld17]':

 mysqld_multi start 17

This command stops several servers, using option groups '[mysqld8]' and '[mysqld10]' through '[mysqld13]':

 mysqld_multi stop 8,10-13

For an example of how you might set up an option file, use this command:

 mysqld_multi --example

*note 'mysqld_multi': mysqld-multi. searches for option files as follows:

With '--no-defaults', no option files are read.

Command-Line Format

'--no-defaults'

Type

Boolean

Default Value

'false'
With '--defaults-file=FILE_NAME', only the named file is read.

Command-Line Format

'--defaults-file=filename'

Type

File name

Default Value

'[none]'
Otherwise, option files in the standard list of locations are read, including any file named by the '--defaults-extra-file=FILE_NAME' option, if one is given. (If the option is given multiple times, the last value is used.)

Command-Line Format

'--defaults-extra-file=filename'

Type

File name

Default Value

'[none]'

For additional information about these and other option-file options, see *note option-file-options::.

Option files read are searched for '[mysqld_multi]' and '[mysqldN]' option groups. The '[mysqld_multi]' group can be used for options to note 'mysqld_multi': mysqld-multi. itself. '[mysqldN]' groups can be used for options passed to specific note 'mysqld': mysqld. instances.

The '[mysqld]' or '[mysqld_safe]' groups can be used for common options read by all instances of note 'mysqld': mysqld. or note 'mysqld_safe': mysqld-safe. You can specify a '--defaults-file=FILE_NAME' option to use a different configuration file for that instance, in which case the '[mysqld]' or '[mysqld_safe]' groups from that file are used for that instance.

*note 'mysqld_multi': mysqld-multi. supports the following options.

'--help'

Command-Line Format

'--help'

Type

Boolean

Default Value

'false'

Display a help message and exit.
'--example'

Command-Line Format

'--example'

Type

Boolean

Default Value

'false'

Display a sample option file.
'--log=FILE_NAME'

Command-Line Format

'--log=path'

Type

File name

Default Value

'/var/log/mysqld_multi.log'

Specify the name of the log file. If the file exists, log output is appended to it.
'--mysqladmin=PROG_NAME'

Command-Line Format

'--mysqladmin=file'

Type

File name

Default Value

'[none]'

The *note 'mysqladmin': mysqladmin. binary to be used to stop servers.
'--mysqld=PROG_NAME'

Command-Line Format

'--mysqld=file'

Type

File name

Default Value

'[none]'

The note 'mysqld': mysqld. binary to be used. Note that you can specify note 'mysqld_safe': mysqld-safe. as the value for this option also. If you use note 'mysqld_safe': mysqld-safe. to start the server, you can include the 'mysqld' or 'ledir' options in the corresponding '[mysqldN]' option group. These options indicate the name of the server that note 'mysqld_safe': mysqld-safe. should start and the path name of the directory where the server is located. (See the descriptions for these options in *note mysqld-safe::.) Example:
```
  [mysqld38]
  mysqld = mysqld-debug
  ledir  = /opt/local/mysql/libexec
```
'--no-log'

Command-Line Format

'--no-log'

Type

Boolean

Default Value

'false'

Print log information to 'stdout' rather than to the log file. By default, output goes to the log file.
'--password=PASSWORD'

Command-Line Format

'--password=string'

Type

String

Default Value

'[none]'

The password of the MySQL account to use when invoking *note 'mysqladmin': mysqladmin. Note that the password value is not optional for this option, unlike for other MySQL programs.
'--silent'

Command-Line Format

'--silent'

Type

Boolean

Default Value

'false'

Silent mode; disable warnings.
'--tcp-ip'

Command-Line Format

'--tcp-ip'

Type

Boolean

Default Value

'false'

Connect to each MySQL server through the TCP/IP port instead of the Unix socket file. (If a socket file is missing, the server might still be running, but accessible only through the TCP/IP port.) By default, connections are made using the Unix socket file. This option affects 'stop' and 'report' operations.
'--user=USER_NAME'

Command-Line Format

'--user=name'

Type

String

Default Value

'root'

The user name of the MySQL account to use when invoking *note 'mysqladmin': mysqladmin.
'--verbose'

Command-Line Format

'--verbose'

Type

Boolean

Default Value

'false'

Be more verbose.
'--version'

Command-Line Format

'--version'

Type

Boolean

Default Value

'false'

Display version information and exit.

Some notes about *note 'mysqld_multi': mysqld-multi.:

Most important: Before using note 'mysqld_multi': mysqld-multi. be sure that you understand the meanings of the options that are passed to the note 'mysqld': mysqld. servers and why you would want to have separate note 'mysqld': mysqld. processes. Beware of the dangers of using multiple note 'mysqld': mysqld. servers with the same data directory. Use separate data directories, unless you know what you are doing. Starting multiple servers with the same data directory does not give you extra performance in a threaded system. See *note multiple-servers::.

Important:

Make sure that the data directory for each server is fully accessible to the Unix account that the specific note 'mysqld': mysqld. process is started as. Do not use the Unix ROOT account for this, unless you know what you are doing. See note changing-mysql-user::.
Make sure that the MySQL account used for stopping the note 'mysqld': mysqld. servers (with the note 'mysqladmin': mysqladmin. program) has the same user name and password for each server. Also, make sure that the account has the 'SHUTDOWN' privilege. If the servers that you want to manage have different user names or passwords for the administrative accounts, you might want to create an account on each server that has the same user name and password. For example, you might set up a common 'multi_admin' account by executing the following commands for each server:
```
  $> mysql -u root -S /tmp/mysql.sock -p
  Enter password:
  mysql> CREATE USER 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
  mysql> GRANT SHUTDOWN ON *.* TO 'multi_admin'@'localhost';
```
See note access-control::. You have to do this for each note 'mysqld': mysqld. server. Change the connection parameters appropriately when connecting to each one. Note that the host name part of the account name must permit you to connect as 'multi_admin' from the host where you want to run *note 'mysqld_multi': mysqld-multi.
The Unix socket file and the TCP/IP port number must be different for every *note 'mysqld': mysqld. (Alternatively, if the host has multiple network addresses, you can set the 'bind_address' system variable to cause different servers to listen to different interfaces.)
The '--pid-file' option is very important if you are using note 'mysqld_safe': mysqld-safe. to start note 'mysqld': mysqld. (for example, '--mysqld=mysqld_safe') Every note 'mysqld': mysqld. should have its own process ID file. The advantage of using note 'mysqld_safe': mysqld-safe. instead of note 'mysqld': mysqld. is that note 'mysqld_safe': mysqld-safe. monitors its *note 'mysqld': mysqld. process and restarts it if the process terminates due to a signal sent using 'kill -9' or for other reasons, such as a segmentation fault.
You might want to use the '--user' option for note 'mysqld': mysqld, but to do this you need to run the note 'mysqld_multi': mysqld-multi. script as the Unix superuser ('root'). Having the option in the option file does not matter; you just get a warning if you are not the superuser and the *note 'mysqld': mysqld. processes are started under your own Unix account.

The following example shows how you might set up an option file for use with note 'mysqld_multi': mysqld-multi. The order in which the note 'mysqld': mysqld. programs are started or stopped depends on the order in which they appear in the option file. Group numbers need not form an unbroken sequence. The first and fifth '[mysqldN]' groups were intentionally omitted from the example to illustrate that you can have 'gaps' in the option file. This gives you more flexibility.

 # This is an example of a my.cnf file for mysqld_multi.
 # Usually this file is located in home dir ~/.my.cnf or /etc/my.cnf

 [mysqld_multi]
 mysqld     = /usr/local/mysql/bin/mysqld_safe
 mysqladmin = /usr/local/mysql/bin/mysqladmin
 user       = multi_admin
 password   = my_password

 [mysqld2]
 socket     = /tmp/mysql.sock2
 port       = 3307
 pid-file   = /usr/local/mysql/data2/hostname.pid2
 datadir    = /usr/local/mysql/data2
 language   = /usr/local/mysql/share/mysql/english
 user       = unix_user1

 [mysqld3]
 mysqld     = /path/to/mysqld_safe
 ledir      = /path/to/mysqld-binary/
 mysqladmin = /path/to/mysqladmin
 socket     = /tmp/mysql.sock3
 port       = 3308
 pid-file   = /usr/local/mysql/data3/hostname.pid3
 datadir    = /usr/local/mysql/data3
 language   = /usr/local/mysql/share/mysql/swedish
 user       = unix_user2

 [mysqld4]
 socket     = /tmp/mysql.sock4
 port       = 3309
 pid-file   = /usr/local/mysql/data4/hostname.pid4
 datadir    = /usr/local/mysql/data4
 language   = /usr/local/mysql/share/mysql/estonia
 user       = unix_user3

 [mysqld6]
 socket     = /tmp/mysql.sock6
 port       = 3311
 pid-file   = /usr/local/mysql/data6/hostname.pid6
 datadir    = /usr/local/mysql/data6
 language   = /usr/local/mysql/share/mysql/japanese
 user       = unix_user4

See *note option-files::.

File: manual.info.tmp, Node: programs-installation, Next: programs-client, Prev: programs-server, Up: programs