After you install MySQL on Unix, 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> cd mysql_installation_directory shell> bin/mysql_install_db shell> bin/mysqld_safe --user=mysql &
For a binary distribution (not RPM or PKG packages), do this:
shell> cd mysql_installation_directory shell> scripts/mysql_install_db shell> bin/mysqld_safe --user=mysql &
The mysql_install_db script creates the mysql database that holds all database privileges, and the test database that you can use to test MySQL. The script also creates privilege table entries for root accounts and anonymous-user accounts. The entries are created without passwords. The mysqld_safe script starts the mysqld server. (For versions of MySQL older than 4.0, use safe_mysqld rather than mysqld_safe.)
mysql_install_db will not overwrite any old privilege tables, so it should be safe to run in any circumstances. If you don't want to have the test database you can remove it with mysqladmin -u root drop test after starting the server.
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 in this section and in the following subsections, BINDIR is the path to the location in which programs like mysqladmin and mysqld_safe 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:
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 of 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 Default 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'
This may also happen with a binary MySQL distribution if you don't start MySQL by executing exactly ./bin/mysqld_safe. See mysqld_safe.
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 the 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 the contents of 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 re-create 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 re-create them after editing mysql_install_db.
For more information about these alternatives, see Default privileges.
Start the MySQL server like this:
shell> cd mysql_installation_directory shell> bin/mysqld_safe &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe in the final command.
If you have problems starting the server, see Starting server.
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 here:
shell> BINDIR/mysqladmin version mysqladmin Ver 8.40 Distrib 4.0.18, for linux on i586 Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB This software comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to modify and redistribute it under the GPL license Server version 4.0.18-log Protocol version 10 Connection Localhost via Unix socket TCP port 3306 UNIX socket /tmp/mysql.sock Uptime: 16 sec Threads: 1 Questions: 9 Slow queries: 0 Opens: 7 Flush tables: 2 Open tables: 0 Queries per second avg: 0.000 Memory in use: 132K Max memory used: 16773K
To see what else you can do with mysqladmin, invoke it with the --help option.
Verify that you can shut down the server:
shell> BINDIR/mysqladmin -u root shutdown
Verify that you can restart the server. Do this using mysqld_safe or by invoking mysqld directly. For example:
shell> BINDIR/mysqld_safe --log &
If mysqld_safe fails, try running it from the MySQL installation directory (if you are not already there). If that doesn't work, see Starting server.
Run some simple tests to verify that the server is working. The output should be similar to what is shown here:
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 benchmark suite is written in Perl. It uses the Perl DBI module to provide a database-independent interface to the various databases. The following additional Perl modules are required to run the benchmark suite:
DBI DBD::mysql Data::Dumper Data::ShowTable
These modules can be obtained from CPAN http://www.cpan.org/. See Perl installation.
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 probably installed MySQL using RPM files other than the source RPM. (The source RPM includes the sql-bench benchmark directory.) In this case, you must first install the benchmark suite before you can use it. Beginning with MySQL Version 3.22, there are separate benchmark RPM files named mysql-bench-VERSION-i386.rpm that contain benchmark code and data.
If you have a source distribution, there are also tests in its tests subdirectory that you can run. For example, to run auto_increment.tst, do this:
shell> BINDIR/mysql -vvf test < ./tests/auto_increment.tst
The expected result of the test can be found in the ./tests/auto_increment.res file.
The purpose of the mysql_install_db script is to generate new MySQL privilege tables. It will not overwrite existing MySQL privilege tables, and it will not affect any other data.
If you want to re-create your privilege tables, you should take down the mysqld server, if it's running, and then do something like:
mv mysql-data-directory/mysql mysql-data-directory/mysql-old 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 mysqld endedIn 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. See Bug reports. |
There is already a mysqld process running | In this case, you 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 server doesn't work when one server is running | This can happen when you already have an existing MySQL installation, but want to put a new installation in a different location (for example, 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.... See Multiple servers. |
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_PORTSee Problems with mysql.sock. some_tmp_dir should be the path to some directory for which you have write permission. See Environment variables. 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/mysqld_safe & |
mysqld crashes immediately |
If you are running Red Hat Version 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 online at
http://lists.mysql.com/.
Also, see Linux.
You can also start mysqld manually using the --skip-grant-tables
option and add the privilege information yourself using mysql:
shell> BINDIR/mysqld_safe --skip-grant-tables & shell> BINDIR/mysql -u root mysqlFrom mysql, manually execute the SQL commands in mysql_install_db. Make sure you run mysqladmin flush-privileges or mysqladmin reload afterward to tell the server to reload the grant tables. |
Generally, you start the mysqld server in one of these ways:
By invoking mysqld directly. This works on any platform.
By running the MySQL server as a Windows service. This can be done on Windows NT, 2000, and XP. For instructions, see NT start.
By invoking mysql.server. This script is used primarily at system startup and shutdown on systems that use System V-style run directories. It is described more fully later in this section.
By invoking mysqld_safe, which tries to determine the proper options for mysqld and then runs it with those options. This script is used on systems based on BSD Unix. It also is invoked by mysql.server. See mysqld_safe.
The mysql.server and mysqld_safe scripts can be used to start the server automatically at system startup time. mysql.server can also be used to stop the server.
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.
Note that if you use the Linux RPM package (MySQL-server-VERSION.rpm), the mysql.server script has already been installed as /etc/init.d/mysql. You don't have to install it manually. See Linux-RPM for more information on the Linux RPM packages.
On Mac OS X, you can install a separate MySQL Startup Item package to enable the automatic startup of MySQL on system bootup. See Mac OS X installation for details.
Before mysql.server starts the server, it changes the directory to the MySQL installation directory, then invokes mysqld_safe. 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 mysqld_safe. If you want the server to run as some specific user, add an appropriate user line to the /etc/my.cnf file, as shown later in this section.
mysql.server stop brings down the server by sending a signal to it. You can also stop the server manually by executing mysqladmin shutdown.
You need to add these start and stop commands to the appropriate places in your /etc/rc* files when you want to start up MySQL automatically on your server.
On most current Linux distributions, it is sufficient to copy the file mysql.server into the /etc/init.d directory (or /etc/rc.d/init.d on older Red Hat systems). Afterwards, run the following command to enable the startup of MySQL on system bootup:
shell> chkconfig --add mysql.server
On FreeBSD startup scripts generally should go in /usr/local/etc/rc.d/. The rc(8) manual page also states that scripts in this directory are only executed, if their basename matches the shell globbing pattern *.sh. Any other files or directories present within the directory are silently ignored. In other words, on FreeBSD you should install the file mysql.server as /usr/local/etc/rc.d/mysql.server.sh to enable automatic startup.
As an alternative to the above, some operating systems also use /etc/rc.local or /etc/init.d/boot.local to start additional services on bootup. To start up MySQL using this method, you could append something like the following to it:
/bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'
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=/var/tmp/mysql.sock port=3306 user=mysql [mysql.server] basedir=/usr/local/mysql
The mysql.server script understands the following options: datadir, basedir, and pid-file.
The following table shows which option groups each startup script reads from option files:
Script | Option groups |
mysqld | [mysqld], [server] and [mysqld-major-version] |
mysql.server | [mysql.server], [mysqld], and [server] |
mysqld_safe | [mysqld], [server], and [mysqld_safe] |
For backward compatibility, mysql.server also reads the [mysql_server] group and mysqld_safe also reads the [safe_mysqld] group. However, you should update your option files to use the [mysql.server] and [mysqld_safe] groups instead.
See Option files.
If you are going to use storage engines that support transactional tables (InnoDB, BDB), you should first create a my.cnf file and set startup options for the engines you plan to use. See Table types.
When the mysqld server starts up, it changes location 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 mysqld_safe 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.
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, and \mysql\data\mysql.err on Windows). 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
Look for something like the following in the log file:
000729 14:50:10 bdb: Recovery function for LSN 1 27595 failed 000729 14:50:10 bdb: warning: ./test/t1.db: No such file or directory 000729 14:50:10 Can't init databases
This means that you didn't start mysqld with --bdb-no-recover and Berkeley DB found something wrong with its log files when it tried to recover your databases. To be able to continue, you should move away the old Berkeley DB log file from the database directory to some other place, where you can later examine it. The log files are named log.0000000001, where the number will increase over time.
If you are running mysqld with BDB table support and mysqld core dumps at start this could be because of some problems with the BDB recovery log. In this case you can try starting mysqld with --bdb-no-recover. If this helps, then you should remove all log.* files from the data directory and try starting mysqld again.
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 Enter a couple of times. If you don't get an error message like telnet: Unable to connect to remote host: Connection refused, something is using the TCP/IP port mysqld is trying to use. See Problems Running mysql_install_db and Multiple servers.
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 you get Errcode 13, which means Permission denied, when starting mysqld this means that you didn't have the right to read/create files in the MySQL database or log directory. In this case you should either start mysqld as the root user or change the permissions for the involved files and directories so that you have the right to use them.
If mysqld_safe 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.
If you can't get mysqld to start you can try to make a trace file to find the problem. See Making trace files.
If you are using InnoDB tables, refer to the InnoDB-specific startup options. See InnoDB start.
If you are using BDB (Berkeley DB) tables, you should familiarise yourself with the different BDB-specific startup options. See BDB start.