4.15 Post-installation setup and testing

Once you've installed MySQL (from either a binary or source distribution), you need to initialize the grant tables, start the server and make sure that the server works okay. You may also wish to arrange for the server to be started and stopped automatically when your system starts up and shuts down.

Normally you install the grant tables and start the server like this for installation from a source distribution: 

shell> ./scripts/mysql_install_db
shell> cd mysql_installation_directory
shell> ./bin/safe_mysqld &

For a binary distribution, do this: 

shell> cd mysql_installation_directory
shell> ./bin/mysql_install_db
shell> ./bin/safe_mysqld &

Testing is most easily done from the top-level directory of the MySQL distribution. For a binary distribution, this is your installation directory (typically something like `/usr/local/mysql'). For a source distribution, this is the main directory of your MySQL source tree.

In the commands shown below in this section and in the following subsections, BINDIR is the path to the location in which programs like mysqladmin and safe_mysqld are installed. For a binary distribution, this is the `bin' directory within the distribution. For a source distribution, BINDIR is probably `/usr/local/bin', unless you specified an installation directory other than `/usr/local' when you ran configure. EXECDIR is the location in which the mysqld server is installed. For a binary distribution, this is the same as BINDIR. For a source distribution, EXECDIR is probably `/usr/local/libexec'.

Testing is described in detail below:

  1. If necessary, start the mysqld server and set up the initial MySQL grant tables containing the privileges that determine how users are allowed to connect to the server. This is normally done with the mysql_install_db script: 
    shell> scripts/mysql_install_db
    Typically, mysql_install_db needs to be run only the first time you install MySQL. Therefore, if you are upgrading an existing installation, you can skip this step. (However, mysql_install_db is quite safe to use and will not update any tables that already exist, so if you are unsure what to do, you can always run mysql_install_db.) mysql_install_db creates six tables (user, db, host, tables_priv, columns_priv and func) in the mysql database. A description of the initial privileges is given in 6.10 Setting up the initial MySQL privileges. Briefly, these privileges allow the MySQL root user to do anything, and allow anybody to create or use databases with a name of 'test' or starting with 'test_'. If you don't set up the grant tables, the following error will appear in the log file when you start the server: 
    mysqld: Can't find file: 'host.frm'
    The above may also happens with a binary MySQL distribution if you don't start MySQL by executing exactly ./bin/safe_mysqld! You might need to run mysql_install_db as root. However, if you prefer, you can run the MySQL server as an unprivileged (non-root) user, provided that user can read and write files in the database directory. Instructions for running MySQL as an unprivileged user are given in Changing MySQL user. If you have problems with mysql_install_db, see mysql_install_db. There are some alternatives to running the mysql_install_db script as it is provided in the MySQL distribution:
    • You may want to edit mysql_install_db before running it, to change the initial privileges that are installed into the grant tables. This is useful if you want to install MySQL on a lot of machines with the same privileges. In this case you probably should need only to add a few extra INSERT statements to the mysql.user and mysql.db tables!
    • If you want to change things in the grant tables after installing them, you can run mysql_install_db, then use mysql -u root mysql to connect to the grant tables as the MySQL root user and issue SQL statements to modify the grant tables directly.
    • It is possible to recreate the grant tables completely after they have already been created. You might want to do this if you've already installed the tables but then want to recreate them after editing mysql_install_db.
    For more information about these alternatives, see 6.10 Setting up the initial MySQL privileges.
  2. Start the MySQL server like this: 
    shell> cd mysql_installation_directory
shell> bin/safe_mysqld &
    If you have problems starting the server, see 4.15.2 Problems starting the MySQL server.
  3. Use mysqladmin to verify that the server is running. The following commands provide a simple test to check that the server is up and responding to connections: 
    shell> BINDIR/mysqladmin version
shell> BINDIR/mysqladmin variables
    The output from mysqladmin version varies slightly depending on your platform and version of MySQL, but should be similar to that shown below: 
    shell> BINDIR/mysqladmin version
mysqladmin  Ver 6.3 Distrib 3.22.9-beta, for pc-linux-gnu on i686
TCX Datakonsult AB, by Monty

Server version          3.22.9-beta
Protocol version        10
Connection              Localhost via UNIX socket
TCP port                3306
UNIX socket             /tmp/mysql.sock
Uptime:                 16 sec

Running threads: 1  Questions: 20  Reloads: 2  Open tables: 3
    To get a feeling for what else you can do with BINDIR/mysqladmin, invoke it with the --help option.
  4. Verify that you can shut down the server: 
    shell> BINDIR/mysqladmin -u root shutdown
  5. Verify that you can restart the server. Do this using safe_mysqld or by invoking mysqld directly. For example: 
    shell> BINDIR/safe_mysqld --log &
    If safe_mysqld fails, try running it from the MySQL installation directory (if you are not already there). If that doesn't work, see 4.15.2 Problems starting the MySQL server.
  6. Run some simple tests to verify that the server is working. The output should be similar to what is shown below: 
    shell> BINDIR/mysqlshow
+-----------+
| Databases |
+-----------+
| mysql     |
+-----------+

shell> BINDIR/mysqlshow mysql
Database: mysql
+--------------+
|    Tables    |
+--------------+
| columns_priv |
| db           |
| func         |
| host         |
| tables_priv  |
| user         |
+--------------+

shell> BINDIR/mysql -e "select host,db,user from db" mysql
+------+--------+------+
| host | db     | user |
+------+--------+------+
| %    | test   |      |
| %    | test_% |      |
+------+--------+------+
    There is also a benchmark suite in the `sql-bench' directory (under the MySQL installation directory) that you can use to compare how MySQL performs on different platforms. The `sql-bench/Results' directory contains the results from many runs against different databases and platforms. To run all tests, execute these commands: 
    shell> cd sql-bench
shell> run-all-tests
    If you don't have the `sql-bench' directory, you are probably using an RPM for a binary distribution. (Source distribution RPMs include the benchmark directory.) In this case, you must first install the benchmark suite before you can use it. Beginning with MySQL 3.22, there are benchmark RPM files named `mysql-bench-VERSION-i386.rpm' that contain benchmark code and data. If you have a source distribution, you can also run the tests in the `tests' subdirectory. For example, to run `auto_increment.tst', do this: 
    shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst
    The expected results are shown in the `./tests/auto_increment.res' file.

4.15.1 Problems running mysql_install_db

This section lists problems you might encounter when you run mysql_install_db:

mysql_install_db doesn't install the grant tables
You may find that mysql_install_db fails to install the grant tables and terminates after displaying the following messages: 
starting mysqld daemon with databases from XXXXXX
mysql daemon ended
In this case, you should examine the log file very carefully! The log should be located in the directory `XXXXXX' named by the error message, and should indicate why mysqld didn't start. If you don't understand what happened, include the log when you post a bug report using mysqlbug! 2.3 How to report bugs or problems.
There is already a mysqld daemon running
In this case, you have probably don't have to run mysql_install_db at all. You have to run mysql_install_db only once, when you install MySQL the first time.
Installing a second mysqld daemon doesn't work when one daemon is running
This can happen when you already have an existing MySQL installation, but want to put a new installation in a different place (e.g., for testing, or perhaps you simply want to run two installations at the same time). Generally the problem that occurs when you try to run the second server is that it tries to use the same socket and port as the old one. In this case you will get the error message: Can't start server: Bind on TCP/IP port: Address already in use or Can't start server : Bind on unix socket... You can start the new server with a different socket and port as follows: 
shell> MYSQL_UNIX_PORT=/tmp/mysqld-new.sock
shell> MYSQL_TCP_PORT=3307
shell> export MYSQL_UNIX_PORT MYSQL_TCP_PORT
shell> scripts/mysql_install_db
shell> bin/safe_mysqld &
After this, you should edit your server boot script to start both daemons with different sockets and ports. For example, it could invoke safe_mysqld twice, but with different --socket, --port and --basedir options for each invocation.
You don't have write access to `/tmp'
If you don't have write access to create a socket file at the default place (in `/tmp') or permission to create temporary files in `/tmp,' you will get an error when running mysql_install_db or when starting or using mysqld. You can specify a different socket and temporary directory as follows: 
shell> TMPDIR=/some_tmp_dir/
shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysqld.sock
shell> export TMPDIR MYSQL_UNIX_PORT
`some_tmp_dir' should be the path to some directory for which you have write permission. After this you should be able to run mysql_install_db and start the server with these commands: 
shell> scripts/mysql_install_db
shell> BINDIR/safe_mysqld &
mysqld crashes immediately
If you are running RedHat 5.0 with a version of glibc older than 2.0.7-5, you should make sure you have installed all glibc patches! There is a lot of information about this in the MySQL mail archives. Links to the mail archives are available at the online MySQL documentation page. Also, see 4.11.5 Linux notes (all Linux versions). You can also start mysqld manually using the --skip-grant option and add the privilege information yourself using mysql: 
shell> BINDIR/safe_mysqld --skip-grant &
shell> BINDIR/mysql -u root mysql
From mysql, manually execute the SQL commands in mysql_install_db. Make sure you run mysqladmin reload afterward to tell the server to reload the grant tables.

4.15.2 Problems starting the MySQL server

Generally, you start the mysqld server in one of three ways:

  • By invoking mysql.server. This script is used primarily at system startup and shutdown, and is described more fully in 4.15.3 Starting and stopping MySQL automatically.
  • By invoking safe_mysqld, which tries to determine the proper options for mysqld and then runs it with those options.
  • By invoking mysqld directly.

Whichever method you use to start the server, if it fails to start up correctly, check the log file to see if you can find out why. Log files are located in the data directory (typically `/usr/local/mysql/data' for a binary distribution, `/usr/local/var' for a source distribution). Look in the data directory for files with names of the form `host_name.err' and `host_name.log' where host_name is the name of your server host. Then check the last few lines of these files: 

shell> tail host_name.err
shell> tail host_name.log

When the mysqld daemon starts up, it changes directory to the data directory. This is where it expects to write log files and the pid (process ID) file, and where it expects to find databases.

The data directory location is hardwired in when the distribution is compiled. However, if mysqld expects to find the data directory somewhere other than where it really is on your system, it will not work properly. If you have problems with incorrect paths, you can find out what options mysqld allows and what the default path settings are by invoking mysqld with the --help option. You can override the defaults by specifying the correct pathnames as command-line arguments to mysqld. (These options can be used with safe_mysqld as well.)

Normally you should need to tell mysqld only the base directory under which MySQL is installed. You can do this with the --basedir option. You can also use --help to check the effect of changing path options (note that --help must be the final option of the mysqld command). For example: 

shell> EXECDIR/mysqld --basedir=/usr/local --help

Once you determine the path settings you want, start the server without the --help option.

If you get the following error, it means that some other program (or another mysqld server) is already using the TCP/IP port or socket mysqld is trying to use: 

Can't start server: Bind on TCP/IP port: Address already in use
  or
Can't start server : Bind on unix socket...

Use ps to make sure that you don't have another mysqld server running. If you can't find another server running, you can try to execute the command telnet your-host-name tcp-ip-port-number and press RETURN a couple of times. If you don't get a error message like telnet: Unable to connect to remote host: Connection refused, something is using the TCP/IP port mysqld is trying to use. mysql_install_db, and 19.3 Running multiple MySQL servers on the same machine.

The safe_mysqld script is written so that it normally is able to start a server that was installed from either a source or a binary version of MySQL, even if these install the server in slightly different locations. safe_mysqld expects one of these conditions to be true:

  • The server and databases can be found relative to the directory from which safe_mysqld is invoked. safe_mysqld looks under its working directory for `bin' and `data' directories (for binary distributions) or for `libexec' and `var' directories (for source distributions). This condition should be met if you execute safe_mysqld from your MySQL installation directory (for example, `/usr/local/mysql' for a binary distribution).
  • If the server and databases cannot be found relative to its working directory, safe_mysqld attempts to locate them by absolute pathnames. Typical locations are `/usr/local/libexec' and `/usr/local/var'. The actual locations are determined when the distribution was built from which safe_mysqld comes. They should be correct if MySQL was installed in a standard location.

Since safe_mysqld will try 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 start safe_mysqld from the MySQL installation directory: 

shell> cd mysql_installation_directory
shell> bin/safe_mysqld &

If safe_mysqld fails, even when invoked from the MySQL installation directory, you can modify it to use the path to mysqld and the pathname options that are correct for your system. Note that if you upgrade MySQL in the future, your modified version of safe_mysqld will be overwritten, so you should make a copy of your edited version that you can reinstall.

If mysqld is currently running, you can find out what path settings it is using by executing this command: 

shell> mysqladmin variables

or

shell> mysqladmin -h 'your-host-name' variables

If safe_mysqld starts the server but you can't connect to it, you should make sure you have an entry in `/etc/hosts' that looks like this: 

127.0.0.1       localhost

This problem occurs only on systems that don't have a working thread library and for which MySQL must be configured to use MIT-pthreads.

4.15.3 Starting and stopping MySQL automatically

The mysql.server script can be used to start or stop the server, by invoking it with start or stop arguments: 

shell> mysql.server start
shell> mysql.server stop

mysql.server can be found in the `share/mysql' directory under the MySQL installation directory, or in the `support-files' directory of the MySQL source tree.

Before mysql.server starts the server, it changes directory to the MySQL installation directory, then invokes safe_mysqld. You might need to edit mysql.server if you have a binary distribution that you've installed in a non-standard location. Modify it to cd into the proper directory before it runs safe_mysqld. If you want the server to run as some specific user, you can change the mysql_daemon_user=root line to use another user. You can also modify mysql.server to pass other options to safe_mysqld.

mysql.server stop brings down server by sending a signal to it. You can take down the server manually by executing mysqladmin shutdown.

You might want to add these start and stop commands to the appropriate places in your `/etc/rc*' files when you start using MySQL for production applications. Note that if you modify mysql.server, then if you upgrade MySQL sometime, your modified version will be overwritten, so you should make a copy of your edited version that you can reinstall.

If your system uses `/etc/rc.local' to start external scripts, you should append the following to it: 

/bin/sh -c 'cd /usr/local/mysql ; ./bin/safe_mysqld &'

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

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

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

The mysql.server script uses the following variables: user, datadir, basedir, bindir and pid-file.

4.15.4 Option files.

4.15.4 Option files

MySQL 3.22 can read default startup options for the server and for clients from option files.

MySQL reads default options from the following files on Unix:

Filename Purpose
/etc/my.cnf Global options
DATADIR/my.cnf Server-specific options
~/.my.cnf User-specific options

DATADIR is the MySQL data directory (typically `/usr/local/mysql/data' for a binary installation, or `/usr/local/var' for a source installation). Note that this is the directory that was specified at configuration time, not the one specified with --datadir when mysqld starts up! (--datadir has no effect on where the server looks for option files, because it looks for them before it processes any command-line arguments.)

MySQL reads default options from the following files on Win32:

Filename Purpose
windows-system-directory\my.ini
C:\my.cnf Global options
C:\mysql\data\my.cnf Server-specific options

Note that you on Win32 should specify all paths with / instead of \. If you use \, you need to specify this twice, as \ is the escape character in MySQL.

MySQL tries to read option files in the order listed above. 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. Options specified on the command line take precedence over options specified in any option file. Some options can be specified using environment variables. Options specified on the command line or in option files take precedence over environment variable values.

The following programs support option files: mysql, mysqladmin, mysqld, mysqldump, mysqlimport, mysql.server, isamchk and pack_isam.

You can use option files to specify any long option that a program supports! Run the program with --help to get a list of available options.

An option file can contain lines of the following forms:

#comment
Comment lines start with `#' or `;'. Empty lines are ignored.
[group]
group is the name of the program or group for which you want to set options. After a group line, any option or set-variable lines apply to the named group until the end of the option file or another group line is given.
option
This is equivalent to --option on the command line.
option=value
This is equivalent to --option=value on the command line.
set-variable = variable=value
This is equivalent to --set-variable variable=value on the command line. This syntax must be used to set a mysqld variable.

The client group allows you to specify options that apply to all MySQL clients (not mysqld). This is the perfect group to use to specify the password you use to connect to the server. (But make sure the option file is readable and writable only to yourself.)

Note that for options and values, all leading and trailing blanks are automatically deleted. You may use the escape sequences `\b', `\t', `\n', `\r', `\\' and `\s' in your value string (`\s' == blank).

Here is a typical global option file: 

[client]
port=3306
socket=/tmp/mysql.sock

[mysqld]
port=3306
socket=/tmp/mysql.sock
set-variable = key_buffer=16M
set-variable = max_allowed_packet=1M

[mysqldump]
quick

Here is typical user option file: 

[client]
# The following password will be sent to all standard MySQL clients
password=my_password

[mysql]
no-auto-rehash

If you have a source distribution, you will find a sample configuration file named `my-example.cnf' in the `support-files' directory. If you have a binary distribution, look in the `DIR/share/mysql' directory, where DIR is the pathname to the MySQL installation directory (typically `/usr/local/mysql'). You can copy `my-example.cnf' to your home directory (rename the copy to `.my.cnf') to experiment with.

To tell a MySQL program not to read any option files, specify --no-defaults as the first option on the command line. This MUST be the first option or it will have no effect! If you want to check which options are used, you can give the option --print-defaults as the first option.

If you want to force the use of a specific config file, you can use the option --defaults-file=full-path-to-default-file. If you do this, only the specified file will be read.

Note for developers: Option file handling is implemented simply by processing all matching options (i.e., 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 an old 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.