Table of Contents
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 Installing binary for generic installation instructions for these packages that apply to all platforms.
See General Installation Issues for more information on what other binary distributions are available and how to obtain them.
The installation process for MySQL on Windows has the following steps:
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 Windows source build.
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 NT start.
TCP/IP protocol support.
A copy of the MySQL binary distribution for Windows, which can be downloaded from http://www.mysql.com/downloads/.
Note: The distribution files are supplied with a zipped format and we recommend the use of an adequate FTP client with resume feature to avoid corruption of files during the download process.
A ZIP program 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. See ODBC.
If you need tables with a size larger than 4 GB, install MySQL on an NTFS or newer filesystem. Don't forget to use MAX_ROWS and AVG_ROW_LENGTH when you create tables. See CREATE TABLE.
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 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:\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:\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 Windows prepare environment.
Finish the install process.
Important note: Early alpha Windows distributions for MySQL 4.1 do not contain any 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. Start the new server and update the grant tables. This will avoid loss of your current databases. See Upgrading-grant-tables.
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 version 3.23, you must manually create two new directories to hold the InnoDB data and log files---such as, C:\ibdata and C:\iblogs. You will also need to add some extra lines to the option file, as described in InnoDB start. (As of MySQL 4.0, InnoDB creates its datafiles 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 one 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 D:\mysql and the data directory is located as D:\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=D:/mysql # set datadir to the location of your data directory datadir=D:/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 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 test starting the 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 NT/2000/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 are 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.
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 Windows prepare environment.
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.
Make sure you are in the directory where the server is located, then enter this command:
C:\mysql\bin> mysqld --console
For servers that include InnoDB support, you should see the following messages as the server starts up:
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. The error log is the file with the .err extension.
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 Post-installation.
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:
shell> C:\mysql\bin\mysqld
On non-NT versions of Windows, this will start mysqld in the background. That is, after the server starts up, 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:
shell> 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. Please 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 if 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. See Making trace files.
Use mysqld --help to display all the options that mysqld understands!
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). 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:
shell> 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. Please note that users in the MySQL grant system are wholly independent from any login users under Windows.
Now install the server as a service:
shell> mysqld --install
If you have problems installing mysqld as a service using just the server name, try installing it using its full pathname:
shell> 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 up. 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 usual 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 (which should be entered on a single line):
shell> 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.
Please note that 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 if 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 version 3.23.44, 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:
shell> 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:
shell> 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 version 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 the same way as for versions of Windows that are not based on NT. For instructions, see Win95 start.
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. In 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 similar place).
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. |
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/XP to get more speed. The current implementation limits the number of open files MySQL can use to 1024, which means that you will not be able to run as many concurrent threads on NT/2000/XP as on Unix. |
Blocking read |
MySQL uses a blocking read for each connection, which
has the following implications:
|
DROP DATABASE | You can't drop a database that is in use by some thread. |
Killing MySQL from the task manager | You can't 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. See Name case sensitivity. |
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 doesn't work reliably in 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:
mysqlbinlog binary-log-name | mysql --user=rootIf you get a problem applying the log and suspect it's because of an ^Z / CHAR(24) character you can use the following workaround: mysqlbinlog binary-log-file --result-file=/tmp/bin.sql 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 Version 3.22 server on NT with the newest MySQL client
programs, you will get the following error:
error 2017: can't open named pipe to host: . pipe...This is 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 create an option file C:\my.cnf that contains the following information: [client] host = localhostStarting 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 can't resolve your hostname properly.
To fix this, you should create a file \windows\hosts with the
following information:
127.0.0.1 localhost |
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 threads. 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. |
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. 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.