2.2 Standard MySQL Installation Using a Binary Distribution | MySQL AB MySQL Administrator[ap]s Guide

< Day Day Up >

This section covers the installation of MySQL on platforms where we offer packages using the native packaging format of the respective platform. (This is also known as performing a "binary install.") However, binary distributions of MySQL are available for many other platforms as well. See Section 2.2.5, "Installing MySQL on Other Unix-Like Systems," for generic installation instructions for these packages that apply to all platforms.

See Section 2.1, "General Installation Issues," for more information on what other binary distributions are available and how to obtain them.

2.2.1 Installing MySQL on Windows

The installation process for MySQL on Windows has the following steps:

Obtain and install the distribution.
Set up an option file if necessary.
Select the server you want to use.
Start the server.
Assign passwords to the initial MySQL accounts.

MySQL for Windows is available in two distribution formats:

The binary distribution contains a setup program that installs everything you need so that you can start the server immediately.
The source distribution contains all the code and support files for building the executables using the VC++ 6.0 compiler.

Generally speaking, you should use the binary distribution. It's simpler, and you need no additional tools to get MySQL up and running.

This section describes how to install MySQL on Windows using a binary distribution. To install using a source distribution, see Section 2.3.6, "Installing MySQL from Source on Windows."

2.2.1.1 Windows System Requirements

To run MySQL on Windows, you need the following:

A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP. The NT family (Windows NT, 2000, and XP) permits you to run the MySQL server as a service. See Section 2.2.1.7, "Starting MySQL as a Windows Service."
TCP/IP protocol support.
A copy of the MySQL binary distribution for Windows, which can be downloaded from http://dev.mysql.com/downloads/. See Section 2.1.3, "How to Get MySQL."

Note: If you download the distribution via FTP, we recommend the use of an adequate FTP client with a resume feature to avoid corruption of files during the download process.
WinZip or other Windows tool that can read .zip files, to unpack the distribution file.
Enough space on the hard drive to unpack, install, and create the databases in accordance with your requirements.
If you plan to connect to the MySQL server via ODBC, you also need the MyODBC driver.
If you need tables with a size larger than 4GB, install MySQL on an NTFS or newer filesystem. Don't forget to use MAX_ROWS and AVG_ROW_LENGTH when you create tables.

2.2.1.2 Installing a Windows Binary Distribution

To install MySQL on Windows using a binary distribution, follow this procedure:

If you are working on a Windows NT, 2000, or XP machine, make sure that you have logged in as a user with administrator privileges.
If you are doing an upgrade of an earlier MySQL installation, it is necessary to stop the current server. On Windows NT, 2000, or XP machines, if you are running the server as a Windows service, stop it as follows from the command prompt:
```
 
```
```
 C:\>  NET STOP MySQL  
```
If you plan to use a different server after the upgrade (for example, if you want to run mysqld-max rather than mysqld ), remove the existing service:
```
 
```
```
 C:\>  C:\mysql\bin\mysqld --remove  
```
You can reinstall the service to use the proper server after upgrading.

If you are not running the MySQL server as a service, stop it like this:
```
 
```
```
 C:\>  C:\mysql\bin\mysqladmin -u root shutdown  
```
Exit the WinMySQLAdmin program if it is running.
Unzip the distribution file to a temporary directory.
Run the setup.exe program to begin the installation process. If you want to install MySQL into a location other than the default directory ( C:\mysql ), use the Browse button to specify your preferred directory. If you do not install MySQL into the default location, you will need to specify the location whenever you start the server. The easiest way to do this is to use an option file, as described in Section 2.2.1.3, "Preparing the Windows MySQL Environment."
Finish the install process.

Important note: Early alpha Windows distributions for MySQL 4.1 do not contain an installer program. A 4.1 distribution is a Zip file that you just unzip in the location where you want to install MySQL. For example, to install mysql-4.1.1-alpha-win.zip as C:\mysql , unzip the distribution file on the C: drive, then rename the resulting mysql-4.1.1-alpha directory to mysql .

If you are upgrading to MySQL 4.1 from an earlier version, you will want to preserve your existing data directory that contains the grant tables in the mysql database and your own databases. Before installing 4.1, stop the server if it is running, and save your data directory to another location. Then either rename the existing C:\mysql directory or remove it. Install 4.1 as described in the preceding paragraph, and then replace its data directory with your old data directory. This will avoid the loss of your current databases. Start the new server and update the grant tables. See Section 2.5.8, "Upgrading the Grant Tables."

2.2.1.3 Preparing the Windows MySQL Environment

If you need to specify startup options when you run the server, you can indicate them on the command line or place them in an option file. For options that will be used every time the server starts, you will find it most convenient to use an option file to specify your MySQL configuration. This is true particularly under the following circumstances:

The installation or data directory locations are different from the default locations ( C:\mysql and C:\mysql\data ).
You need to tune the server settings. For example, to use the InnoDB transactional tables in MySQL 3.23, you must manually add some extra lines to the option file, as described in Section 9.4, "InnoDB Configuration." (As of MySQL 4.0, InnoDB creates its data files and log files in the data directory by default. This means you need not configure InnoDB explicitly. You may still do so if you wish, and an option file will be useful in this case, too.)

On Windows, the MySQL installer places the data directory directly under the directory where you install MySQL. If you would like to use a data directory in a different location, you should copy the entire contents of the data directory to the new location. For example, by default, the installer places MySQL in C:\mysql and the data directory in C:\mysql\data . If you want to use a data directory of E:\mydata , you must do two things:

Move the data directory from C:\mysql\data to E:\mydata .
Use a --datadir option to specify the new data directory location each time you start the server.

When the MySQL server starts on Windows, it looks for options in two files: the my.ini file in the Windows directory, and the C:\my.cnf file. The Windows directory typically is named something like 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%

MySQL looks for options first in the my.ini file, then in the my.cnf file. However, to avoid confusion, it's best if you use only one file. If your PC uses a boot loader where the C: drive isn't the boot drive, your only option is to use the my.ini file. Whichever option file you use, it must be a plain text file.

An option file can be created and modified with any text editor, such as the Notepad program. For example, if MySQL is installed at E:\mysql and the data directory is located at E:\mydata\data , you can create the option file and set up a [mysqld] section to specify values for the basedir and datadir parameters:

 [mysqld] # set basedir to your installation path basedir=E:/mysql # set datadir to the location of your data directory datadir=E:/mydata/data

Note that Windows pathnames are specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them.

Another way to manage an option file is to use the WinMySQLAdmin tool. You can find WinMySQLAdmin in the bin directory of your MySQL installation, as well as a help file containing instructions for using it. WinMySQLAdmin has the capability of editing your option file, but note these points:

WinMySQLAdmin uses only the my.ini file.
If WinMySQLAdmin finds a C:\my.cnf file, it will in fact rename it to C:\my_cnf.bak to disable it.

Now you are ready to start the server.

2.2.1.4 Selecting a Windows Server

Starting with MySQL 3.23.38, the Windows distribution includes both the normal and the MySQL-Max server binaries. Here is a list of the different MySQL servers from which you can choose:

Binary	Description
`mysqld`	Compiled with full debugging and automatic memory allocation checking, symbolic links, and `InnoDB` and `BDB` tables.
`mysqld-opt`	Optimized binary. From version 4.0 on, `InnoDB` is enabled. Before 4.0, this server includes no transactional table support.
`mysqld-nt`	Optimized binary for Windows NT, 2000, and XP with support for named pipes.
`mysqld-max`	Optimized binary with support for symbolic links, and `InnoDB` and `BDB` tables.
`mysqld-max-nt`	Like `mysqld-max` , but compiled with support for named pipes.

All of the preceding binaries are optimized for modern Intel processors, but should work on any Intel i386-class or higher processor.

MySQL supports TCP/IP on all Windows platforms. The mysqld-nt and mysql-max-nt servers support named pipes on NT, 2000, and XP. However, the default is to use TCP/IP regardless of the platform. (Named pipes are slower than TCP/IP in many Windows configurations.) Named pipe use is subject to these conditions:

Starting from MySQL 3.23.50, named pipes are enabled only if you start the server with the --enable-named-pipe option. It is now necessary to use this option explicitly because some users have experienced problems shutting down the MySQL server when named pipes were used.
Named pipe connections are allowed only by the mysqld-nt or mysqld-max-nt servers, and only if the server is run on a version of Windows that supports named pipes (NT, 2000, XP).
These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named pipe connections cannot be used.
On Windows 95, these servers cannot be used.

Note: Most of the examples in the following sections use mysqld as the server name . If you choose to use a different server, such as mysqld-opt , make the appropriate substitutions in the commands that are shown in the examples. One good reason to choose a different server is that because mysqld contains full debugging support, it uses more memory and runs slower than the other Windows servers.

2.2.1.5 Starting the Server for the First Time

On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. (This will allow any machine on your network to connect to your MySQL server.) Because of this, you must make sure that TCP/IP support is installed on your machine before starting MySQL. You can find TCP/IP on your Windows CD-ROM.

Note that if you are using an old Windows 95 release (for example, OSR2), it's likely that you have an old Winsock package; MySQL requires Winsock 2! You can get the newest Winsock from http://www.microsoft.com/. Windows 98 has the new Winsock 2 library, so it is unnecessary to update the library.

On NT-based systems such as Windows NT, 2000, or XP, clients have two options. They can use TCP/IP, or they can use a named pipe if the server supports named pipe connections.

For information about which server binary to run, see Section 2.2.1.4, "Selecting a Windows Server."

This section gives a general overview of starting the MySQL server. The following sections provide more specific information for particular versions of Windows.

The examples in these sections assume that MySQL is installed under the default location of C:\mysql . Adjust the pathnames shown in the examples if you have MySQL installed in a different location.

Testing is best done from a command prompt in a console window (a "DOS window"). This way you can have the server display status messages in the window where they are easy to see. If something is wrong with your configuration, these messages will make it easier for you to identify and fix any problems.

To start the server, enter this command:

 C:\>  C:\mysql\bin\mysqld --console

For servers that include InnoDB support, you should see the following messages as the server starts:

 InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200 InnoDB: Database physically writes the file full: wait... InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280 InnoDB: Doublewrite buffer not found: creating new InnoDB: Doublewrite buffer created InnoDB: creating foreign key constraint system tables InnoDB: foreign key constraint system tables created 011024 10:58:25  InnoDB: Started

When the server finishes its startup sequence, you should see something like this, which indicates that the server is ready to service client connections:

 mysqld: ready for connections Version: '4.0.14-log'  socket: ''  port: 3306

The server will continue to write to the console any further diagnostic output it produces. You can open a new console window in which to run client programs.

If you omit the --console option, the server writes diagnostic output to the error log in the data directory ( C:\mysql\data by default). The error log is the file with the .err extension.

Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in Section 2.4, "Post-Installation Setup and Testing."

2.2.1.6 Starting MySQL from the Windows Command Line

The MySQL server can be started manually from the command line. This can be done on any version of Windows.

To start the mysqld server from the command line, you should start a console window (a "DOS window") and enter this command:

 C:\>  C:\mysql\bin\mysqld

On non-NT versions of Windows, this will start mysqld in the background. That is, after the server starts, you should see another command prompt. If you start the server this way on Windows NT, 2000, or XP, the server will run in the foreground and no command prompt will appear until the server exits. Because of this, you should open another console window to run client programs while the server is running.

You can stop the MySQL server by executing this command:

 C:\>  C:\mysql\bin\mysqladmin -u root shutdown

This invokes the MySQL administrative utility mysqladmin to connect to the server and tell it to shut down. The command connects as root , which is the default administrative account in the MySQL grant system. Note that users in the MySQL grant system are wholly independent from any login users under Windows.

If mysqld doesn't start, check the error log to see whether the server wrote any messages there to indicate the cause of the problem. The error log is located in the C:\mysql\data directory. It is the file with a suffix of .err . You can also try to start the server as mysqld --console ; in this case, you may get some useful information on the screen that may help solve the problem.

The last option is to start mysqld with --standalone --debug . In this case, mysqld will write a log file C:\mysqld.trace that should contain the reason why mysqld doesn't start.

Use mysqld --help to display all the options that mysqld understands!

2.2.1.7 Starting MySQL as a Windows Service

On the NT family (Windows NT, 2000, or XP), the recommended way to run MySQL is to install it as a Windows service. Then Windows starts and stops the MySQL server automatically when Windows starts and stops. A server installed as a service can also be controlled from the command line using NET commands, or with the graphical Services utility.

The Services utility (the Windows Service Control Manager ) can be found in the Windows Control Panel (under Administrative Tools on Windows 2000 or XP). It is advisable to close the Services utility while performing server installation or removal operations from this command line. This prevents some odd errors.

To get MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3 (or newer).

Before installing MySQL as a Windows service, you should first stop the current server if it is running by using the following command:

 C:\>  C:\mysql\bin\mysqladmin -u root shutdown

Now install the server as a service:

 C:\>  mysqld --install

If you have problems installing mysqld as a service using just the server name, try installing it using its full pathname:

 C:\>  C:\mysql\bin\mysqld --install

As of MySQL 4.0.2, you can specify a specific service name after the --install option. As of MySQL 4.0.3, you can in addition specify a --defaults-file option after the service name to indicate where the server should obtain options when it starts. The rules that determine the service name and option files the server uses are as follows:

If you specify no service name, the server uses the default service name of MySQL and the server reads options from the [mysqld] group in the standard option files.
If you specify a service name after the --install option, the server ignores the [mysqld] option group and instead reads options from the group that has the same name as the service. The server reads options from the standard option files.
If you specify a --defaults-file option after the service name, the server ignores the standard option files and reads options only from the [mysqld] group of the named file.

Note: Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its pathname or the service name contains spaces. For this reason, avoid installing MySQL in a directory such as C:\Program Files or using a service name containing spaces.

In the unusual case that you install the server with --install but no service name, the server is installed with a service name of MySQL .

As a more complex example, consider the following command:

 C:\>  C:\mysql\bin\mysqld --install mysql--defaults-file=C:\my-opts.cnf

Here, a service name is given after the --install option. If no --defaults-file option had been given, this command would have the effect of causing the server to read the [mysql] group from the standard option files. (This would be a bad idea, because that option group is for use by the mysql client program.) However, because the --defaults-file option is present, the server reads options only from the named file, and only from the [mysqld] option group.

You can also specify options as " Start parameters " in the Windows Services utility before you start the MySQL service.

Once a MySQL server is installed as a service, Windows will start the service automatically whenever Windows starts. The service also can be started immediately from the Services utility, or by using the command NET START MySQL . The NET command is not case sensitive.

When run as a service, mysqld has no access to a console window, so no messages can be seen there. If mysqld doesn't start, check the error log to see whether the server wrote any messages there to indicate the cause of the problem. The error log is located in the C:\mysql\data directory. It is the file with a suffix of .err .

When mysqld is running as a service, it can be stopped by using the Services utility, the command NET STOP MySQL , or the command mysqladmin shutdown . If the service is running when Windows shuts down, Windows will stop the server automatically.

From MySQL 3.23.44 on, you have the choice of installing the server as a Manual service if you don't wish the service to be started automatically during the boot process. To do this, use the --install-manual option rather than the --install option:

 C:\>  C:\mysql\bin\mysqld --install-manual

To remove a server that is installed as a service, first stop it if it is running. Then use the --remove option to remove it:

 C:\>  C:\mysql\bin\mysqld --remove

For MySQL versions older than 3.23.49, one problem with automatic MySQL service shutdown is that Windows waited only for a few seconds for the shutdown to complete, then killed the database server process if the time limit was exceeded. This had the potential to cause problems. (For example, the InnoDB storage engine had to perform crash recovery at the next startup.) Starting from MySQL 3.23.49, Windows waits longer for the MySQL server shutdown to complete. If you notice this still is not enough for your installation, it is safest not to run the MySQL server as a service. Instead, start it from the command-line prompt, and stop it with mysqladmin shutdown .

This change to tell Windows to wait longer when stopping the MySQL server works for Windows 2000 and XP. It does not work for Windows NT, where Windows waits only 20 seconds for a service to shut down, and after that kills the service process. You can increase this default by opening the Registry Editor \winnt\system32\regedt32.exe and editing the value of WaitToKillServiceTimeout at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control in the Registry tree. Specify the new larger value in milliseconds . For example, the value 120000 tells Windows NT to wait up to 120 seconds.

If you don't want to start mysqld as a service, you can start it from the command line. For instructions, see Section 2.2.1.6, "Starting MySQL from the Windows Command Line."

2.2.1.8 Running MySQL Client Programs on Windows

You can test whether the MySQL server is working by executing any of the following commands:

 C:\>  C:\mysql\bin\mysqlshow  C:\>  C:\mysql\bin\mysqlshow -u root mysql  C:\>  C:\mysql\bin\mysqladmin version status proc  C:\>  C:\mysql\bin\mysql test

If mysqld is slow to respond to TCP/IP connections from client programs on Windows 9x/Me, there is probably a problem with your DNS. In this case, start mysqld with the --skip-name-resolve option and use only localhost and IP numbers in the Host column of the MySQL grant tables.

You can force a MySQL client to use a named pipe connection rather than TCP/IP by specifying the --pipe option or by specifying . (period) as the host name. Use the --socket option to specify the name of the pipe. As of MySQL 4.1, you should use the --protocol=PIPE option.

There are two versions of the MySQL command-line tool:

Binary	Description
`mysql`	Compiled on native Windows, offering limited text editing capabilities.
`mysqlc`	Compiled with the Cygnus GNU compiler and libraries, which offers `readline` editing.

If you want to use mysqlc , you must have a copy of the cygwinb19.dll library installed somewhere that mysqlc can find it. Current distributions of MySQL include this library in the same directory as mysqlc (the bin directory under the base directory of your MySQL installation). If your distribution does not have the cygwinb19.dll library in the bin directory, look for it in the lib directory and copy it to your Windows system directory ( \Windows\system or a similar place).

2.2.1.9 MySQL on Windows Compared to MySQL on Unix

MySQL for Windows has by now proven itself to be very stable. The Windows version of MySQL has the same features as the corresponding Unix version, with the following exceptions:

Windows 95 and threads

Windows 95 leaks about 200 bytes of main memory for each thread creation. Each connection in MySQL creates a new thread, so you shouldn't run mysqld for an extended time on Windows 95 if your server handles many connections! Other versions of Windows don't suffer from this bug.
Limited number of ports

Windows systems have about 4,000 ports available for client connections, and after a connection on a port closes , it takes two to four minutes before the port can be reused. In situations where clients connect to and disconnect from the server at a high rate, it is possible for all available ports to be used up before closed ports become available again. If this happens, the MySQL server will appear to have become unresponsive even though it is running. Note that ports may be used by other applications running on the machine as well, in which case the number of ports available to MySQL is lower.
Concurrent reads

MySQL depends on the pread() and pwrite() calls to be able to mix INSERT and SELECT . Currently we use mutexes to emulate pread() / pwrite() . We will, in the long run, replace the file level interface with a virtual interface so that we can use the readfile() / writefile() interface on NT, 2000, and XP to get more speed. The current implementation limits the number of open files MySQL can use to 1,024, which means that you will not be able to run as many concurrent threads on NT, 2000, and XP as on Unix.
Blocking read

MySQL uses a blocking read for each connection, which has the following implications if named pipe connections are enabled:
- A connection will not be disconnected automatically after eight hours, as happens with the Unix version of MySQL.
- If a connection hangs , it's impossible to break it without killing MySQL.
- mysqladmin kill will not work on a sleeping connection.
- mysqladmin shutdown can't abort as long as there are sleeping connections.
We plan to fix this problem when our Windows developers have figured out a nice workaround.
ALTER TABLE

While you are executing an ALTER TABLE statement, the table is locked from being used by other threads. This has to do with the fact that on Windows, you can't delete a file that is in use by another thread. In the future, we may find some way to work around this problem.
DROP TABLE

DROP TABLE on a table that is in use by a MERGE table will not work on Windows because the MERGE handler does the table mapping hidden from the upper layer of MySQL. Because Windows doesn't allow you to drop files that are open, you first must flush all MERGE tables (with FLUSH TABLES ) or drop the MERGE table before dropping the table. We will fix this at the same time we introduce views.
DATA DIRECTORY and INDEX DIRECTORY

The DATA DIRECTORY and INDEX DIRECTORY options for CREATE TABLE are ignored on Windows, because Windows doesn't support symbolic links. These options also are ignored on systems that have a non-functional realpath() call.
DROP DATABASE

You cannot drop a database that is in use by some thread.
Killing MySQL from the Task Manager

You cannot kill MySQL from the Task Manager or with the shutdown utility in Windows 95. You must take it down with mysqladmin shutdown .
Case-insensitive names

Filenames are not case sensitive on Windows, so MySQL database and table names are also not case sensitive on Windows. The only restriction is that database and table names must be specified using the same case throughout a given statement.
The ' \ ' pathname separator character

Pathname components in Windows 95 are separated by the ' \ ' character, which is also the escape character in MySQL. If you are using LOAD DATA INFILE or SELECT ... INTO OUTFILE , use Unix-style filenames with ' / ' characters :
```
 
```
```
 mysql>  LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr;  mysql>  SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;  
```
Alternatively, you must double the ' \ ' character:
```
 
```
```
 mysql>  LOAD DATA INFILE 'C:\tmp\skr.txt' INTO TABLE skr;  mysql>  SELECT * INTO OUTFILE 'C:\tmp\skr.txt' FROM skr;  
```
Problems with pipes

Pipes do not work reliably from the Windows command-line prompt. If the pipe includes the character ^Z / CHAR(24) , Windows will think it has encountered end-of-file and abort the program.

This is mainly a problem when you try to apply a binary log as follows:
```
 
```
```
 C:\>  mysqlbinlog   binary-log-name   mysql --user=root  
```
If you have a problem applying the log and suspect that it is because of a ^Z / CHAR(24) character, you can use the following workaround:
```
 
```
```
 C:\>  mysqlbinlog   binary-log-file   --result-file=/tmp/bin.sql  C:\>  mysql --user=root --execute "source /tmp/bin.sql"  
```
The latter command also can be used to reliably read in any SQL file that may contain binary data.
Can't open named pipe error

If you use a MySQL 3.22 server on Windows NT with the newest MySQL client programs, you will get the following error:
```
 
```
```
 error 2017: can't open named pipe to host: . pipe... 
```
This happens because the release version of MySQL uses named pipes on NT by default. You can avoid this error by using the --host=localhost option to the new MySQL clients or by creating an option file C:\my.cnf that contains the following information:
```
 
```
```
 [client] host = localhost 
```
Starting from 3.23.50, named pipes are enabled only if mysqld-nt or mysqld-max-nt is started with --enable-named-pipe .
Access denied for user error

If you attempt to run a MySQL client program to connect to a server running on the same machine, but get the error Access denied for user: ' some-user @unknown' to database 'mysql' , this means that MySQL cannot resolve your hostname properly.

To fix this, you should create a file named \windows\ hosts containing the following information:
```
 
```
```
 127.0.0.1       localhost 
```

Here are some open issues for anyone who might want to help us improve MySQL on Windows:

Add some nice start and shutdown icons to the MySQL installation.
It would be really nice to be able to kill mysqld from the Task Manager in Windows 95. For the moment, you must use mysqladmin shutdown .
Port readline to Windows for use in the mysql command-line tool.
GUI versions of the standard MySQL clients ( mysql , mysqlshow , mysqladmin , and mysqldump ) would be nice.
It would be nice if the socket read and write functions in net.c were interruptible. This would make it possible to kill open threads with mysqladmin kill on Windows.
Add macros to use the faster thread-safe increment/decrement methods provided by Windows.

2.2.2 Installing MySQL on Linux

The recommended way to install MySQL on Linux is by using the RPM packages. The MySQL RPMs are currently built on a SuSE Linux 7.3 system, but should work on most versions of Linux that support rpm and use glibc . To obtain RPM packages, see Section 2.1.3, "How to Get MySQL."

Note: RPM distributions of MySQL often are provided by other vendors . Be aware that they may differ in features and capabilities from those built by MySQL AB, and that the instructions in this manual do not necessarily apply to installing them. The vendor's instructions should be consulted instead.

If you have problems with an RPM file (for example, if you receive the error " Sorry, the host ' xxxx ' could not be looked up "), see Section 2.6.1.2, "Linux Binary Distribution Notes."

In most cases, you only need to install the MySQL-server and MySQL-client packages to get a functional MySQL installation. The other packages are not required for a standard installation. If you want to run a MySQL-Max server that has additional capabilities, you should also install the MySQL-Max RPM. However, you should do so only after installing the MySQL-server RPM. See Section 4.1.2, "The mysqld-max Extended MySQL Server."

If you get a dependency failure when trying to install the MySQL 4.0 packages (for example, " error: removing these packages would break dependencies: libmysqlclient.so.10 is needed by ... "), you should also install the package MySQL-shared-compat , which includes both the shared libraries for backward compatibility ( libmysqlclient.so.12 for MySQL 4.0 and libmysqlclient.so.10 for MySQL 3.23).

Many Linux distributions still ship with MySQL 3.23 and they usually link applications dynamically to save disk space. If these shared libraries are in a separate package (for example, MySQL-shared ), it is sufficient to simply leave this package installed and just upgrade the MySQL server and client packages (which are statically linked and do not depend on the shared libraries). For distributions that include the shared libraries in the same package as the MySQL server (for example, Red Hat Linux), you could either install our 3.23 MySQL-shared RPM, or use the MySQL-shared-compat package instead.

The following RPM packages are available:

MySQL-server- VERSION .i386.rpm

The MySQL server. You will need this unless you only want to connect to a MySQL server running on another machine. Note: Server RPM files were called MySQL- VERSION .i386.rpm before MySQL 4.0.10. That is, they did not have -server in the name.
MySQL-Max- VERSION .i386.rpm

The MySQL-Max server. This server has additional capabilities that the one provided in the MySQL-server RPM does not. You must install the MySQL-server RPM first, because the MySQL-Max RPM depends on it.
MySQL-client- VERSION .i386.rpm

The standard MySQL client programs. You probably always want to install this package.
MySQL-bench- VERSION .i386.rpm

Tests and benchmarks. Requires Perl and the DBD::mysql module.
MySQL- devel - VERSION .i386.rpm

The libraries and include files that are needed if you want to compile other MySQL clients, such as the Perl modules.
MySQL-shared- VERSION .i386.rpm

This package contains the shared libraries ( libmysqlclient.so* ) that certain languages and applications need to dynamically load and use MySQL.
MySQL-shared-compat- VERSION .i386.rpm

This package includes the shared libraries for both MySQL 3.23 and MySQL 4.0. Install this package instead of MySQL-shared if you have applications installed that are dynamically linked against MySQL 3.23 but you want to upgrade to MySQL 4.0 without breaking the library dependencies. This package has been available since MySQL 4.0.13.
MySQL-embedded- VERSION .i386.rpm

The embedded MySQL server library (from MySQL 4.0).
MySQL- VERSION .src.rpm

This contains the source code for all of the previous packages. It can also be used to rebuild the RPMs on other architectures (for example, Alpha or SPARC).

To see all files in an RPM package (for example, a MySQL-server RPM), run:

 shell>  rpm -qpl MySQL-server-   VERSION   .i386.rpm

To perform a standard minimal installation, run:

 shell>  rpm -i MySQL-server-   VERSION   .i386.rpm  shell>  rpm -i MySQL-client-   VERSION   .i386.rpm

To install just the client package, run:

 shell>  rpm -i MySQL-client-   VERSION   .i386.rpm

RPM provides a feature to verify the integrity and authenticity of packages before installing them. If you would like to learn more about this feature, see Section 2.1.4, "Verifying Package Integrity Using MD5 Checksums or GnuPG."

The server RPM places data under the /var/lib/mysql directory. The RPM also creates a login account for a user named mysql (if one does not already exist) to use for running the MySQL server, and creates the appropriate entries in /etc/init.d/ to start the server automatically at boot time. (This means that if you have performed a previous installation and have made changes to its startup script, you may want to make a copy of the script so that you don't lose it when you install a newer RPM.) See Section 2.4.3, "Starting and Stopping MySQL Automatically," for more information on how MySQL can be started automatically on system startup.

If you want to install the MySQL RPM on older Linux distributions that do not support initialization scripts in /etc/init.d (directly or via a symlink ), you should create a symbolic link that points to the location where your initialization scripts actually are installed. For example, if that location is /etc/rc.d/init.d , use these commands before installing the RPM to create /etc/init.d as a symbolic link that points there:

 shell>  cd /etc  shell>  ln -s rc.d/init.d .

However, all current major Linux distributions should already support the new directory layout that uses /etc/init.d , because it is required for LSB (Linux Standard Base) compliance.

If the RPM files that you install include MySQL-server , the mysqld server should be up and running after installation. You should now be able to start using MySQL.

If something goes wrong, you can find more information in the binary installation section. See Section 2.2.5, "Installing MySQL on Other Unix-Like Systems."

2.2.3 Installing MySQL on Mac OS X

Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2 ("Jaguar") and up using a Mac OS X binary package in PKG format instead of the binary tarball distribution. Please note that older versions of Mac OS X (for example, 10.1.x) are not supported by this package.

The package is located inside a disk image ( .dmg ) file that you first need to mount by double-clicking its icon in the Finder. It should then mount the image and display its contents.

To obtain MySQL, see Section 2.1.3, "How to Get MySQL."

Note: Before proceeding with the installation, be sure to shut down all running MySQL server instances by either using the MySQL Manager Application (on Mac OS X Server) or via mysqladmin shutdown on the command line.

To actually install the MySQL PKG file, double-click on the package icon. This launches the Mac OS X Package Installer, which will guide you through the installation of MySQL.

Due to a bug in the Mac OS X package installer, you may see this error message in the destination disk selection dialog:

 You cannot install this software on this disk. (null)

If this error occurs, simply click the Go Back button once to return to the previous screen. Then click Continue to advance to the destination disk selection again, and you should be able to choose the destination disk correctly. We have reported this bug to Apple and it is investigating this problem.

The Mac OS X PKG of MySQL will install itself into /usr/local/mysql- VERSION and will also install a symbolic link, /usr/local/mysql , pointing to the new location. If a directory named /usr/local/mysql already exists, it will be renamed to /usr/local/mysql.bak first. Additionally, the installer will create the grant tables in the mysql database by executing mysql_install_db after the installation.

The installation layout is similar to that of a tar file binary distribution; all MySQL binaries are located in the directory /usr/local/mysql/bin . The MySQL socket file is created as /tmp/mysql.sock by default. See Section 2.1.5, "Installation Layouts."

MySQL installation requires a Mac OS X user account named mysql . A user account with this name should exist by default on Mac OS X 10.2 and up.

If you are running Mac OS X Server, you already have a version of MySQL installed. The versions of MySQL that ship with Mac OS X Server versions are shown in the following table:

Mac OS X Server Version	MySQL Version
10.2-10.2.2	3.23.51
10.2.3-10.2.6	3.23.53
10.3	4.0.14
10.3.2	4.0.16

This manual section covers the installation of the official MySQL Mac OS X PKG only. Make sure to read Apple's help information about installing MySQL: Run the "Help View" application, select "Mac OS X Server" help, do a search for "MySQL," and read the item entitled "Installing MySQL."

For pre-installed versions of MySQL on Mac OS X Server, note especially that you should start mysqld with safe_mysqld instead of mysqld_safe if MySQL is older than version 4.0.

If you previously used Marc Liyanage's MySQL packages for Mac OS X from http://www.entropy.ch, you can simply follow the update instructions for packages using the binary installation layout as given on his pages.

If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X Server version of MySQL to the official MySQL PKG, you also need to convert the existing MySQL privilege tables to the current format, because some new security privileges have been added. See Section 2.5.8, "Upgrading the Grant Tables."

If you would like to automatically start up MySQL during system startup, you also need to install the MySQL Startup Item. Starting with MySQL 4.0.15, it is part of the Mac OS X installation disk images as a separate installation package. Simply double-click the MySQLStartupItem.pkg icon and follow the instructions to install it.

Note that the Startup Item need be installed only once! There is no need to install it each time you upgrade the MySQL package later.

The Startup Item will be installed into /Library/StartupItems/MySQLCOM . (Before MySQL 4.1.2, the location was /Library/StartupItems/MySQL , but that collided with the MySQL Startup Item installed by Mac OS X Server.) Startup Item installation adds a variable MYSQLCOM=-YES- to the system configuration file /etc/hostconfig . If you would like to disable the automatic startup of MySQL, simply change this variable to MYSQLCOM=-NO- .

On Mac OS X Server, the default MySQL installation uses the variable MYSQL in the /etc/hostconfig file. The MySQL AB Startup Item installer disables this variable by setting it to MYSQL=-NO- . This avoids boot time conflicts with the MYSQLCOM variable used by the MySQL AB Startup Item. However, it does not shut down an already running MySQL server. You should do that yourself.

After the installation, you can start up MySQL by running the following commands in a terminal window. You must have administrator privileges to perform this task.

If you have installed the Startup Item:

 shell>  sudo /Library/StartupItems/MySQL/MySQL start  (Enter your password, if necessary) (Press Control-D or enter "exit" to exit the shell)

If you don't use the Startup Item, enter the following command sequence:

 shell>  cd /usr/local/mysql  shell>  sudo ./bin/mysqld_safe  (Enter your password, if necessary) (Press Control-Z) shell>  bg  (Press Control-D or enter "exit" to exit the shell)

You should now be able to connect to the MySQL server, for example, by running /usr/local/mysql/bin/mysql .

You might want to add aliases to your shell's resource file to make it easier to access commonly used programs such as mysql and mysqladmin from the command line. The syntax for tcsh is:

 alias mysql /usr/local/mysql/bin/mysql alias mysqladmin /usr/local/mysql/bin/mysqladmin

For bash , use:

 alias mysql=/usr/local/mysql/bin/mysql alias mysqladmin=/usr/local/mysql/bin/mysqladmin

Even better, add /usr/local/mysql/bin to your PATH environment variable. For example, add the following line to your $HOME/.tcshrc file if your shell is tcsh :

 setenv PATH ${PATH}:/usr/local/mysql/bin

If no .tcshrc file exists in your home directory, create it with a text editor.

If you are upgrading an existing installation, please note that installing a new MySQL PKG does not remove the directory of an older installation. Unfortunately, the Mac OS X Installer does not yet offer the functionality required to properly upgrade previously installed packages.

To use your existing databases with the new installation, you'll need to copy the contents of the old data directory to the new data directory. Make sure that neither the old server nor the new one is running when you do this. After you have copied over the MySQL database files from the previous installation and have successfully started the new server, you should consider removing the old installation files to save disk space. Additionally, you should also remove older versions of the Package Receipt directories located in /Library/Receipts/mysql- VERSION .pkg .

2.2.4 Installing MySQL on NetWare

Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers will be pleased to note that NetWare 6.5 ships with bundled MySQL binaries, complete with an automatic commercial use license for all servers running that version of NetWare.

As of version 4.0.11, the MySQL server is available for Novell NetWare in binary package form. MySQL for NetWare is compiled using a combination of Metrowerks CodeWarrior for NetWare and special cross-compilation versions of the GNU autotools.

The binary package for NetWare can be obtained at http://dev.mysql.com/downloads/. See Section 2.1.3, "How to Get MySQL."

In order to host MySQL, the NetWare server must meet these requirements:

NetWare version 6.5, or NetWare 6.0 with Support Pack 3 installed (you can obtain this at http://support.novell.com/filefinder/13659/index.html).
The system must meet Novell's minimum requirements to run the respective version of NetWare.
MySQL data, as well as the binaries themselves , must be installed on an NSS volume; traditional volumes are not supported.

To install MySQL for NetWare, use the following procedure:

If you are upgrading from a prior installation, stop the MySQL server. This is done from the server console, using the following command:
```
 
```
```
 SERVER:  mysqladmin -u root shutdown  
```
Log on to the target server from a client machine with access to the location where you will install MySQL.
Extract the binary package Zip file onto the server. Be sure to allow the paths in the Zip file to be used. It is safe to simply extract the file to SYS:\ .

If you are upgrading from a prior installation, you may need to copy the data directory (for example, SYS:MYSQL\DATA ) now, as well as my.cnf , if you have customized it. You can then delete the old copy of MySQL.
You might want to rename the directory to something more consistent and easy to use. We recommend using SYS:MYSQL ; examples in this manual use this name to refer to the installation directory in general.
At the server console, add a search path for the directory containing the MySQL NLMs. For example:
```
 
```
```
 SERVER:  SEARCH ADD SYS:MYSQL\BIN  
```
Initialize the data directory and the grant tables, if needed, by executing mysql_install_db at the server console.
Start the MySQL server using mysqld_safe at the server console.
To finish the installation, you should also add the following commands to autoexec.ncf . For example, if your MySQL installation is in SYS:MYSQL and you want MySQL to start automatically, you could add these lines:
```
 
```
```
 #Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE 
```
If you are running MySQL on NetWare 6.0, we strongly suggest that you use the --skip-external-locking option on the command line:
```
 
```
```
 #Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --skip-external-locking 
```
It will also be necessary to use CHECK TABLE and REPAIR TABLE instead of myisamchk , because myisamchk makes use of external locking. External locking is known to have problems on NetWare 6.0; the problem has been eliminated in NetWare 6.5.

mysqld_safe on NetWare provides a screen presence. When you unload (shut down) the mysqld_safe NLM, the screen does not by default go away. Instead, it prompts for user input:
```
 
```
```
 *<NLM has terminated; Press any key to close the screen>* 
```
If you want NetWare to close the screen automatically instead, use the -- autoclose option to mysqld_safe . For example:
```
 
```
```
 #Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --autoclose 
```

The behavior of mysqld_safe on NetWare is described further in Section 4.1.3, "The mysqld_safe Server Startup Script."

If there was an existing installation of MySQL on the server, be sure to check for existing MySQL startup commands in autoexec.ncf , and edit or delete them as necessary.

2.2.5 Installing MySQL on Other Unix-Like Systems

This section covers the installation of MySQL binary distributions that are provided for various platforms in the form of compressed tar files (files with a .tar.gz extension). See Section 2.1.2.5, "MySQL Binaries Compiled by MySQL AB," for a detailed list.

To obtain MySQL, see Section 2.1.3, "How to Get MySQL."

MySQL tar file binary distributions have names of the form mysql- VERSION-OS .tar.gz , where VERSION is a number (for example, 4.0.17 ), and OS indicates the type of operating system for which the distribution is intended (for example, pc-linux-gnu-i586 ).

In addition to these generic packages, we also offer binaries in platform-specific package formats for selected platforms. See Section 2.2, "Standard MySQL Installation Using a Binary Distribution," for more information on how to install these.

You need the following tools to install a MySQL tar file binary distribution:

GNU gunzip to uncompress the distribution.
A reasonable tar to unpack the distribution. GNU tar is known to work. Some operating systems come with a pre-installed version of tar that is known to have problems. For example, Mac OS X tar and Sun tar are known to have problems with long filenames. On Mac OS X, you can use the pre-installed gnutar program. On other systems with a deficient tar , you should install GNU tar first.

If you run into problems, please always use mysqlbug when posting questions to a MySQL mailing list. Even if the problem isn't a bug, mysqlbug gathers system information that will help others solve your problem. By not using mysqlbug , you lessen the likelihood of getting a solution to your problem. You will find mysqlbug in the bin directory after you unpack the distribution. See Section 1.7.1.3, "How to Report Bugs or Problems."

The basic commands you must execute to install and use a MySQL binary distribution are:

 shell>  groupadd mysql  shell>  useradd -g mysql mysql  shell>  cd /usr/local  shell>  gunzip <   /path/to/mysql-VERSION-OS   .tar.gz  tar xvf -  shell>  ln -s   full-path-to-mysql-VERSION-OS   mysql  shell>  cd mysql  shell>  scripts/mysql_install_db --user=mysql  shell>  chown -R root  .  shell>  chown -R mysql data  shell>  chgrp -R mysql .  shell>  bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe in the final command.

Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to Section 2.4, "Post-Installation Setup and Testing."

A more detailed version of the preceding description for installing a binary distribution follows:

Add a login user and group for mysqld to run as:
```
 
```
```
 shell>  groupadd mysql  shell>  useradd -g mysql mysql  
```
These commands add the mysql group and the mysql user. The syntax for useradd and groupadd may differ slightly on different versions of Unix. They may also be called adduser and addgroup .

You might want to call the user and group something else instead of mysql . If so, substitute the appropriate name in the following steps.
Pick the directory under which you want to unpack the distribution, and change location into it. In the following example, we unpack the distribution under /usr/local . (The instructions, therefore, assume that you have permission to create files and directories in /usr/local . If that directory is protected, you will need to perform the installation as root .)
```
 
```
```
 shell>  cd /usr/local  
```
Obtain a distribution file from one of the sites listed in Section 2.1.3, "How to Get MySQL." For a given release, binary distributions for all platforms are built from the same MySQL source distribution.
Unpack the distribution, which will create the installation directory. Then create a symbolic link to that directory:
```
 
```
```
 shell>  gunzip <   /path/to/mysql-VERSION-OS   .tar.gz  tar xvf -  shell>  ln -s   full-path-to-mysql-VERSION-OS   mysql  
```
The tar command creates a directory named mysql- VERSION-OS . The ln command makes a symbolic link to that directory. This lets you refer more easily to the installation directory as /usr/local/mysql .

With GNU tar , no separate invocation of gunzip is necessary. You can replace the first line with the following alternative command to uncompress and extract the distribution:
```
 
```
```
 shell>  tar zxvf   /path/to/mysql-VERSION-OS   .tar.gz  
```
Change location into the installation directory:
```
 
```
```
 shell>  cd mysql  
```
You will find several files and subdirectories in the mysql directory. The most important for installation purposes are the bin and scripts subdirectories.
- bin
This directory contains client programs and the server. You should add the full pathname of this directory to your PATH environment variable so that your shell finds the MySQL programs properly. See Appendix B, "Environment Variables."
- scripts
This directory contains the mysql_install_db script used to initialize the mysql database containing the grant tables that store the server access permissions.
If you haven't installed MySQL before, you must create the MySQL grant tables:
```
 
```
```
 shell>  scripts/mysql_install_db --user=mysql  
```
If you run the command as root, you should use the --user option as shown. The value of the option should be the name of the login account that you created in the first step to use for running the server. If you run the command while logged in as that user, you can omit the --user option.

Note that for MySQL versions older than 3.22.10, mysql_install_db left the server running after creating the grant tables. This is no longer true; you will need to restart the server after performing the remaining steps in this procedure.
Change the ownership of program binaries to root and ownership of the data directory to the user that you will run mysqld as. Assuming that you are located in the installation directory ( /usr/local/mysql ), the commands look like this:
```
 
```
```
 shell>  chown -R root  .  shell>  chown -R mysql data  shell>  chgrp -R mysql .  
```
The first command changes the owner attribute of the files to the root user. The second changes the owner attribute of the data directory to the mysql user. The third changes the group attribute to the mysql group.
If you would like MySQL to start automatically when you boot your machine, you can copy support-files/mysql.server to the location where your system has its startup files. More information can be found in the support-files/mysql.server script itself and in Section 2.4.3, "Starting and Stopping MySQL Automatically."
You can set up new accounts using the bin/mysql_setpermission script if you install the DBI and DBD::mysql Perl modules. For instructions, see Section 2.7, "Perl Installation Notes."
If you would like to use mysqlaccess and have the MySQL distribution in some non-standard place, you must change the location where mysqlaccess expects to find the mysql client. Edit the bin/mysqlaccess script at approximately line 18. Search for a line that looks like this:
```
 
```
```
 $MYSQL     = '/usr/local/bin/mysql';    # path to mysql executable 
```
Change the path to reflect the location where mysql actually is stored on your system. If you do not do this, you will get a Broken pipe error when you run mysqlaccess .

After everything has been unpacked and installed, you should test your distribution.

You can start the MySQL server with the following command:

 shell>  bin/mysqld_safe --user=mysql &

For versions of MySQL older than 4.0, substitute bin/safe_mysqld for bin/mysqld_safe in the command.

More information about mysqld_safe is given in Section 4.1.3, "The mysqld_safe Server Startup Script."

< Day Day Up >