This chapter describes how to obtain and install MySQL. A summary of
the procedure follows and later sections provide the details. If you
plan to upgrade an existing version of MySQL to a newer version
rather than install MySQL for the first time, see
Section 2.11, “Upgrading MySQL”, for information about upgrade procedures
and about issues that you should consider before upgrading.
Determine whether your platform is
supported. Please note that not all supported systems
are equally suitable for running MySQL. On some platforms it is
much more robust and efficient than others. See
Section 2.1.1, “Operating Systems Supported by MySQL”, for details.
Choose which distribution to
install. Several versions of MySQL are available, and
most are available in several distribution formats. You can
choose from pre-packaged distributions containing binary
(precompiled) programs or source code. When in doubt, use a
binary distribution. We also provide public access to our
current source tree for those who want to see our most recent
developments and help us test new code. To determine which
version and type of distribution you should use, see
Section 2.1.2, “Choosing Which MySQL Distribution to Install”.
Perform any necessary post-installation
setup. After installing MySQL, read
Section 2.10, “Post-Installation Setup and Testing”. This section contains
important information about making sure the MySQL server is
working properly. It also describes how to secure the initial
MySQL user accounts, which have no
passwords until you assign passwords. The section
applies whether you install MySQL using a binary or source
distribution.
Before installing MySQL, you should do the following:
Determine whether MySQL runs on your platform.
Choose a distribution to install.
Download the distribution and verify its integrity.
This section contains the information necessary to carry out these
steps. After doing so, you can use the instructions in later
sections of the chapter to install the distribution that you
choose.
2.1.1. Operating Systems Supported by MySQL
This section lists the operating systems on which you can expect
to be able to run MySQL.
We use GNU Autoconf, so it is possible to port MySQL to all
modern systems that have a C++ compiler and a working
implementation of POSIX threads. (Thread support is needed for
the server. To compile only the client code, the only
requirement is a C++ compiler.) We use and develop the software
ourselves primarily on Linux (SuSE and Red Hat), FreeBSD, and
Sun Solaris (versions 8 and 9).
MySQL has been reported to compile successfully on the following
combinations of operating system and thread package. Note that
for many operating systems, native thread support works only in
the latest versions.
Not all platforms are equally well-suited for running MySQL. How
well a certain platform is suited for a high-load
mission-critical MySQL server is determined by the following
factors:
General stability of the thread library. A platform may have
an excellent reputation otherwise, but MySQL is only as
stable as the thread library it calls, even if everything
else is perfect.
The capability of the kernel and the thread library to take
advantage of symmetric multi-processor (SMP) systems. In
other words, when a process creates a thread, it should be
possible for that thread to run on a CPU different from the
original process.
The capability of the kernel and the thread library to run
many threads that acquire and release a mutex over a short
critical region frequently without excessive context
switches. If the implementation of
pthread_mutex_lock() is too anxious to
yield CPU time, this hurts MySQL tremendously. If this issue
is not taken care of, adding extra CPUs actually makes MySQL
slower.
General filesystem stability and performance.
If your tables are large, performance is affected by the
ability of the filesystem to deal with large files at all
and to deal with them efficiently.
Our level of expertise here at MySQL AB with the platform.
If we know a platform well, we enable platform-specific
optimizations and fixes at compile time. We can also provide
advice on configuring your system optimally for MySQL.
The amount of testing we have done internally for similar
configurations.
The number of users that have run MySQL successfully on the
platform in similar configurations. If this number is high,
the likelihood of encountering platform-specific surprises
is much smaller.
Based on the preceding criteria, the best platforms for running
MySQL at this point are x86 with SuSE Linux using a 2.4 or 2.6
kernel, and ReiserFS (or any similar Linux distribution) and
SPARC with Solaris (2.7-9). FreeBSD comes third, but we really
hope it joins the top club once the thread library is improved.
We also hope that at some point we are able to include into the
top category all other platforms on which MySQL currently
compiles and runs, but not quite with the same level of
stability and performance. This requires some effort on our part
in cooperation with the developers of the operating systems and
library components that MySQL depends on. If you are interested
in improving one of those components, are in a position to
influence its development, and need more detailed instructions
on what MySQL needs to run better, send an email message to the
MySQL internals mailing list. See
Section 1.7.1, “MySQL Mailing Lists”.
Please note that the purpose of the preceding comparison is not
to say that one operating system is better or worse than another
in general. We are talking only about choosing an OS for the
specific purpose of running MySQL. With this in mind, the result
of this comparison might be different if other factors were
considered. In some cases, the reason one OS is better for MySQL
than another might simply be that we have been able to put more
effort into testing and optimizing for a particular platform. We
are just stating our observations to help you decide which
platform to use for running MySQL.
2.1.2. Choosing Which MySQL Distribution to Install
When preparing to install MySQL, you should decide which version
to use. MySQL development occurs in several release series, and
you can pick the one that best fits your needs. After deciding
which version to install, you can choose a distribution format.
Releases are available in binary or source format.
2.1.2.1. Choosing Which Version of MySQL to Install
The first decision to make is whether you want to use a
production (stable) release or a development release. In the
MySQL development process, multiple release series co-exist,
each at a different stage of maturity:
MySQL 5.1 is the current development release series.
MySQL 5.0 is the current stable (production-quality)
release series. New releases are issued for bugfixes only;
no new features are being added that could effect
stability.
MySQL 4.1 is the previous stable (production-quality)
release series. New releases are issued for critical
bugfixes and security fixes. No significant new features
are to be added to this series.
MySQL 4.0 and 3.23 are the old stable (production-quality)
release series. These versions are now retired, so new
releases are issued only to fix extremely critical bugs
(primarily security issues).
We do not believe in a complete code freeze because this
prevents us from making bugfixes and other fixes that must be
done. By “somewhat frozen” we mean that we may
add small things that should not affect anything that
currently works in a production release. Naturally, relevant
bugfixes from an earlier series propagate to later series.
Normally, if you are beginning to use MySQL for the first time
or trying to port it to some system for which there is no
binary distribution, we recommend going with the production
release series. Currently, this is MySQL 5.0. All MySQL
releases, even those from development series, are checked with
the MySQL benchmarks and an extensive test suite before being
issued.
If you are running an older system and want to upgrade, but do
not want to take the chance of having a non-seamless upgrade,
you should upgrade to the latest version in the same release
series you are using (where only the last part of the version
number is newer than yours). We have tried to fix only fatal
bugs and make only small, relatively “safe”
changes to that version.
If you want to use new features not present in the production
release series, you can use a version from a development
series. Note that development releases are not as stable as
production releases.
If you want to use the very latest sources containing all
current patches and bugfixes, you can use one of our BitKeeper
repositories. These are not “releases” as such,
but are available as previews of the code on which future
releases are to be based.
The MySQL naming scheme uses release names that consist of
three numbers and a suffix; for example,
mysql-5.0.12-beta. The
numbers within the release name are interpreted as follows:
The first number (5) is
the major version and describes the file format. All MySQL
5 releases have the same file format.
The second number (0) is
the release level. Taken together, the major version and
release level constitute the release series number.
The third number (12) is
the version number within the release series. This is
incremented for each new release. Usually you want the
latest version for the series you have chosen.
For each minor update, the last number in the version string
is incremented. When there are major new features or minor
incompatibilities with previous versions, the second number in
the version string is incremented. When the file format
changes, the first number is increased.
Release names also include a suffix to indicates the stability
level of the release. Releases within a series progress
through a set of suffixes to indicate how the stability level
improves. The possible suffixes are:
alpha indicates that the
release contains new features that have not been
thoroughly tested. Known bugs should be documented in the
News section. See Appendix D, MySQL Change History. Most alpha
releases implement new commands and extensions. Active
development that may involve major code changes can occur
in an alpha release. However, we do conduct testing before
issuing a release.
beta means that the
release is intended to be feature-complete and that all
new code has been tested. No major new features that are
added. There should be no known critical bugs. A version
changes from alpha to beta when there have been no
reported fatal bugs within an alpha version for at least a
month and we have no plans to add any new features that
could make previously implemented features unreliable.
All APIs, externally visible structures, and columns for
SQL statements will not change during future beta, release
candidate, or production releases.
rc is a release
candidate; that is, a beta that has been around for a
while and seems to work well. Only minor fixes are added.
(A release candidate is what formerly was known as a gamma
release.)
If there is no suffix, it means that the version has been
run for a while at many different sites with no reports of
critical repeatable bugs other than platform-specific
bugs. Only critical bugfixes are applied to the release.
This is what we call a production (stable) or
“General Availability” (GA) release.
MySQL uses a naming scheme that is slightly different from
most other products. In general, it is usually safe to use any
version that has been out for a couple of weeks without being
replaced by a new version within the same release series.
All releases of MySQL are run through our standard tests and
benchmarks to ensure that they are relatively safe to use.
Because the standard tests are extended over time to check for
all previously found bugs, the test suite keeps getting
better.
All releases have been tested at least with these tools:
An internal test suite
The mysql-test directory contains an
extensive set of test cases. We run these tests for
virtually every server binary. See
Section 24.1.2, “MySQL Test Suite”, for more information
about this test suite.
The MySQL benchmark suite
This suite runs a range of common queries. It is also a
test to determine whether the latest batch of
optimizations actually made the code faster. See
Section 7.1.4, “The MySQL Benchmark Suite”.
We also test the newest MySQL version in our internal
production environment, on at least one machine. We have more
than 100GB of data to work with.
2.1.2.2. Choosing a Distribution Format
After choosing which version of MySQL to install, you should
decide whether to use a binary distribution or a source
distribution. In most cases, you should probably use a binary
distribution, if one exists for your platform. Binary
distributions are available in native format for many
platforms, such as RPM files for Linux or PKG package
installers for Mac OS X or Solaris. Distributions also are
available as Zip archives or compressed tar
files.
Reasons to choose a binary distribution include the following:
Binary distributions generally are easier to install than
source distributions.
To satisfy different user requirements, we provide two
different binary versions. One is compiled with the core
feature set. The other (MySQL-Max) is compiled with an
extended feature set. Both versions are compiled from the
same source distribution. All native MySQL clients can
connect to servers from either MySQL version.
For RPM distributions, if you want to use the
MySQL-Max RPM, you must first install
the standard MySQL-server RPM.
Under some circumstances, you may be better off installing
MySQL from a source distribution:
You want to install MySQL at some explicit location. The
standard binary distributions are ready to run at any
installation location, but you might require even more
flexibility to place MySQL components where you want.
You want to configure mysqld to ensure
that features are available that might not be included in
the standard binary distributions. Here is a list of the
most common extra options that you may want to use to
ensure feature availability:
--with-innodb
--with-berkeley-db (not available on
all platforms)
--with-libwrap
--with-named-z-libs (this is done for
some of the binaries)
--with-debug[=full]
You want to configure mysqld without
some features that are included in the standard binary
distributions. For example, distributions normally are
compiled with support for all character sets. If you want
a smaller MySQL server, you can recompile it with support
for only the character sets you need.
You have a special compiler (such as
pgcc) or want to use compiler options
that are better optimized for your processor. Binary
distributions are compiled with options that should work
on a variety of processors from the same processor family.
You want to use the latest sources from one of the
BitKeeper repositories to have access to all current
bugfixes. For example, if you have found a bug and
reported it to the MySQL development team, the bugfix is
committed to the source repository and you can access it
there. The bugfix does not appear in a release until a
release actually is issued.
You want to read (or modify) the C and C++ code that makes
up MySQL. For this purpose, you should get a source
distribution, because the source code is always the
ultimate manual.
Source distributions contain more tests and examples than
binary distributions.
2.1.2.3. How and When Updates Are Released
MySQL is evolving quite rapidly and we want to share new
developments with other MySQL users. We try to produce a new
release whenever we have new and useful features that others
also seem to have a need for.
We also try to help users who request features that are easy
to implement. We take note of what our licensed users want,
and we especially take note of what our support customers want
and try to help them in this regard.
No one is required to download a new
release. The News section helps you determine whether the new
release has something you really want. See
Appendix D, MySQL Change History.
We use the following policy when updating MySQL:
Releases are issued within each series. For each release,
the last number in the version is one more than the
previous release within the same series.
Production (stable) releases are meant to appear about 1-2
times a year. However, if small bugs are found, a release
with only bugfixes is issued.
Working releases/bugfixes to old releases are meant to
appear about every 4-8 weeks.
Binary distributions for some platforms are made by us for
major releases. Other people may make binary distributions
for other systems, but probably less frequently.
We make fixes available as soon as we have identified and
corrected small or non-critical but annoying bugs. The
fixes are available immediately from our public BitKeeper
repositories, and are included in the next release.
If by any chance a fatal bug is found in a release, our
policy is to fix it in a new release as soon as possible.
(We would like other companies to do this, too!)
2.1.2.4. Release Philosophy—No Known Bugs in Releases
We put considerable time and effort into making our releases
bug-free. Our policy is never to release a version of MySQL
intended for production use that has any known fatal,
repeatable bugs.
Our aim is to fix everything that is fixable without making a
stable MySQL version less stable. In certain cases, this means
we can fix an issue in the development versions, but not in
the stable (production) version. Naturally, we document such
issues so that users are aware of them.
Here is a description of our build process:
We monitor bugs from our customer support list, the bugs
database at http://bugs.mysql.com/, and the
MySQL external mailing lists.
All reported bugs for live versions are entered into the
bugs database.
When we fix a bug, we always try to make a test case for
it and include it into our test system to ensure that the
bug can never recur without being detected. (About 90% of
all fixed bugs have test cases.)
We create test cases for each new feature that we add to
MySQL.
Before we start to build a new MySQL release, we ensure
that all reported repeatable bugs for that MySQL version
(3.23.x, 4.0.x, 4.1.x, 5.0.x, 5.1.x, and so on) are fixed.
If something is impossible to fix due to some internal
design decision in MySQL, we document this in the manual.
See Section A.8, “Known Issues in MySQL”.
We do a build on all platforms for which we support
binaries and run our test suite and benchmark suite on all
of them.
We do not publish a binary for a platform for which the
test or benchmark suite fails. If the problem is due to a
general error in the source, we fix it and do the build
plus tests on all systems again from scratch.
The build and test process takes a week. If we receive a
report regarding a fatal bug during this process (for
example, one that causes a core dump), we fix the problem
and restart the build process.
After publishing the binaries on
http://dev.mysql.com/, we send out an
announcement message to the mysql and
announce mailing lists. See
Section 1.7.1, “MySQL Mailing Lists”. The announcement message
contains a list of all changes to the release and any
known problems with the release. The
Known Problems section in
the release notes has been needed for only a handful of
releases.
To quickly give our users access to the latest MySQL
features, we try to produce a new MySQL release every 4-8
weeks. Source code snapshots are built daily and are
available at
http://downloads.mysql.com/snapshots.php.
If, despite our best efforts, we receive any bug reports
after a release is issued that a critical problem exists
for the build on a specific platform, we fix it at once
and build a new 'a' release for that
platform. Thanks to our large user base, problems are
found and resolved very quickly.
Our track record for making stable releases is quite good.
In the last 150 releases, we had to do a new build for
fewer than 10 of them. In three of these cases, the bug
was a faulty glibc library on one of
our build machines that took us a long time to track down.
2.1.2.5. MySQL Binaries Compiled by MySQL AB
As a service of MySQL AB, we provide a set of binary
distributions of MySQL that are compiled on systems at our
site or on systems where supporters of MySQL kindly have given
us access to their machines.
These distributions are generated using the script
Build-tools/Do-compile, which compiles the
source code and creates the binary tar.gz
archive using
scripts/make_binary_distribution.
These binaries are configured and built with the following
compilers and options. This information can also be obtained
by looking at the variables COMP_ENV_INFO
and CONFIGURE_LINE inside the script
bin/mysqlbug of every binary
tar file distribution.
Anyone who has more optimal options for any of the following
configure commands can mail them to the
MySQL internals mailing list. See
Section 1.7.1, “MySQL Mailing Lists”.
If you want to compile a debug version of MySQL, you should
add --with-debug or
--with-debug=full to the following
configure commands and remove any
-fomit-frame-pointer options.
The following binaries are built on MySQL AB development
systems:
Note that versions 8.1 and newer of the Intel compiler
have separate drivers for 'pure' C
(icc) and C++
(icpc); if you use
icc version 8.0 or older for building
MySQL, you will need to set CXX=icc.
Linux 2.4.xx Intel Itanium 2 with ecc
(Intel C++ Itanium Compiler 7.0):
The following binaries are built on third-party systems kindly
provided to MySQL AB by other users. These are provided only
as a courtesy; MySQL AB does not have full control over these
systems, so we can provide only limited support for the
binaries built on them.
The following compile options have been used for binary
packages that MySQL AB provided in the past. These binaries no
longer are being updated, but the compile options are listed
here for reference purposes.
Check our downloads page at http://dev.mysql.com/downloads/
for information about the current version of MySQL and for
downloading instructions. For a complete up-to-date list of
MySQL download mirror sites, see
http://dev.mysql.com/downloads/mirrors.html. You can also
find information there about becoming a MySQL mirror site and
how to report a bad or out-of-date mirror.
After you have downloaded the MySQL package that suits your
needs and before you attempt to install it, you should make sure
that it is intact and has not been tampered with. MySQL AB
offers three means of integrity checking:
MD5 checksums
Cryptographic signatures using GnuPG, the
GNU Privacy Guard
For RPM packages, the built-in RPM integrity verification
mechanism
The following sections describe how to use these methods.
If you notice that the MD5 checksum or GPG signatures do not
match, first try to download the respective package one more
time, perhaps from another mirror site. If you repeatedly cannot
successfully verify the integrity of the package, please notify
us about such incidents, including the full package name and the
download site you have been using, at
<webmaster@mysql.com> or
<build@mysql.com>. Do not report downloading
problems using the bug-reporting system.
2.1.4.1. Verifying the MD5 Checksum
After you have downloaded a MySQL package, you should make
sure that its MD5 checksum matches the one provided on the
MySQL download pages. Each package has an individual checksum
that you can verify with the following command, where
package_name is the name of the
package you downloaded:
You should verify that the resulting checksum (the string of
hexadecimal digits) matches the one displayed on the download
page immediately below the respective package.
Note: Make sure to verify the
checksum of the archive file (for
example, the .zip or
.tar.gz file) and not of the files that are
contained inside of the archive.
Note that not all operating systems support the
md5sum command. On some, it is simply
called md5, and others do not ship it at
all. On Linux, it is part of the GNU
Text Utilities package, which is available for a
wide range of platforms. You can download the source code from
http://www.gnu.org/software/textutils/ as well.
If you have OpenSSL installed, you can use the command
openssl md5
package_name instead. A
Windows implementation of the md5 command
line utility is available from
http://www.fourmilab.ch/md5/.
winMd5Sum is a graphical MD5 checking tool
that can be obtained from
http://www.nullriver.com/index/products/winmd5sum.
2.1.4.2. Signature Checking Using GnuPG
Another method of verifying the integrity and authenticity of
a package is to use cryptographic signatures. This is more
reliable than using MD5 checksums, but requires more work.
At MySQL AB, we sign MySQL downloadable packages with
GnuPG (GNU Privacy Guard).
GnuPG is an Open Source alternative to the
well-known Pretty Good Privacy (PGP) by
Phil Zimmermann. See http://www.gnupg.org/ for
more information about GnuPG and how to
obtain and install it on your system. Most Linux distributions
ship with GnuPG installed by default. For
more information about GnuPG, see
http://www.openpgp.org/.
To verify the signature for a specific package, you first need
to obtain a copy of MySQL AB's public GPG build key, which you
can download from http://www.keyserver.net/.
The key that you want to obtain is named
build@mysql.com. Alternatively, you can cut
and paste the key directly from the following text:
To import the build key into your personal public GPG keyring,
use gpg --import. For example, if you have
saved the key in a file named
mysql_pubkey.asc, the import command
looks like this:
shell> gpg --import mysql_pubkey.asc
After you have downloaded and imported the public build key,
download your desired MySQL package and the corresponding
signature, which also is available from the download page. The
signature file has the same name as the distribution file with
an .asc extension. For example:
Distribution file
mysql-standard-5.0.25-linux-i686.tar.gz
Signature file
mysql-standard-5.0.25-linux-i686.tar.gz.asc
Make sure that both files are stored in the same directory and
then run the following command to verify the signature for the
distribution file:
shell> gpg --verify package_name.asc
Example:
shell> gpg --verify mysql-standard-5.0.25-linux-i686.tar.gz.asc
gpg: Signature made Tue 12 Jul 2005 23:35:41 EST using DSA key ID 5072E1F5
gpg: Good signature from "MySQL Package signing key (www.mysql.com) <build@mysql.com>"
The Good signature message indicates that
everything is all right. You can ignore any insecure
memory warning you might obtain.
See the GPG documentation for more information on how to work
with public keys.
2.1.4.3. Signature Checking Using RPM
For RPM packages, there is no separate signature. RPM packages
have a built-in GPG signature and MD5 checksum. You can verify
a package by running the following command:
shell> rpm --checksig package_name.rpm
Example:
shell> rpm --checksig MySQL-server-5.0.25-0.i386.rpm
MySQL-server-5.0.25-0.i386.rpm: md5 gpg OK
Note: If you are using RPM
4.1 and it complains about (GPG) NOT OK (MISSING
KEYS: GPG#5072e1f5), even though you have imported
the MySQL public build key into your own GPG keyring, you need
to import the key into the RPM keyring first. RPM 4.1 no
longer uses your personal GPG keyring (or GPG itself). Rather,
it maintains its own keyring because it is a system-wide
application and a user's GPG public keyring is a user-specific
file. To import the MySQL public key into the RPM keyring,
first obtain the key as described in
Section 2.1.4.2, “Signature Checking Using GnuPG”. Then use
rpm --import to import the key. For
example, if you have saved the public key in a file named
mysql_pubkey.asc, import it using this
command:
This section describes the default layout of the directories
created by installing binary or source distributions provided by
MySQL AB. A distribution provided by another vendor might use a
layout different from those shown here.
For MySQL 5.0 on Windows, the default installation
directory is C:\Program Files\MySQL\MySQL Server
5.0. (Some Windows users prefer to
install in C:\mysql, the directory that
formerly was used as the default. However, the layout of the
subdirectories remains the same.) The installation directory has
the following subdirectories:
Directory
Contents of Directory
bin
Client programs and the mysqld server
data
Log files, databases
Docs
Documentation
examples
Example programs and scripts
include
Include (header) files
lib
Libraries
scripts
Utility scripts
share
Error message files
Installations created from MySQL AB's Linux RPM distributions
result in files under the following system directories:
Directory
Contents of Directory
/usr/bin
Client programs and scripts
/usr/sbin
The mysqld server
/var/lib/mysql
Log files, databases
/usr/share/doc/packages
Documentation
/usr/include/mysql
Include (header) files
/usr/lib/mysql
Libraries
/usr/share/mysql
Error message and character set files
/usr/share/sql-bench
Benchmarks
On Unix, a tar file binary distribution is
installed by unpacking it at the installation location you
choose (typically /usr/local/mysql) and
creates the following directories in that location:
Directory
Contents of Directory
bin
Client programs and the mysqld server
data
Log files, databases
docs
Documentation, ChangeLog
include
Include (header) files
lib
Libraries
scripts
mysql_install_db
share/mysql
Error message files
sql-bench
Benchmarks
A source distribution is installed after you configure and
compile it. By default, the installation step installs files
under /usr/local, in the following
subdirectories:
Directory
Contents of Directory
bin
Client programs and scripts
include/mysql
Include (header) files
info
Documentation in Info format
lib/mysql
Libraries
libexec
The mysqld server
share/mysql
Error message files
sql-bench
Benchmarks and crash-me test
var
Databases and log files
Within its installation directory, the layout of a source
installation differs from that of a binary installation in the
following ways:
The mysqld server is installed in the
libexec directory rather than in the
bin directory.
The data directory is var rather than
data.
mysql_install_db is installed in the
bin directory rather than in the
scripts directory.
The header file and library directories are
include/mysql and
lib/mysql rather than
include and lib.
You can create your own binary installation from a compiled
source distribution by executing the
scripts/make_binary_distribution script
from the top directory of the source distribution.
2.2. Standard MySQL Installation Using a Binary Distribution
The next several sections cover 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.8, “Installing MySQL on Other Unix-Like Systems”, for generic
installation instructions for these packages that apply to all
platforms.
A native Windows distribution of MySQL has been available from
MySQL AB since version 3.21 and represents a sizable percentage of
the daily downloads of MySQL. This section describes the process
for installing MySQL on Windows.
Note: If you are upgrading MySQL
from an existing installation older than MySQL 4.1.5, you must
first perform the the procedure described in
Section 2.3.14, “Upgrading MySQL on Windows”.
To run MySQL on Windows, you need the following:
A 32-bit Windows operating system such as 9x, Me, NT, 2000,
XP, or Windows Server 2003.
A Windows NT-based operating system (NT, 2000, XP, 2003)
permits you to run the MySQL server as a service. The use of a
Windows NT-based operating system is strongly recommended. See
Section 2.3.11, “Starting MySQL as a Windows Service”.
Generally, you should install MySQL on Windows using an
account that has administrator rights. Otherwise, you may
encounter problems with certain operations such as editing the
PATH environment variable or accessing the
Service Control Manager.
TCP/IP protocol support.
Enough space on the hard drive to unpack, install, and create
the databases in accordance with your requirements (generally
a minimum of 200 megabytes is recommended.)
There may also be other requirements, depending on how you plan to
use MySQL:
If you plan to connect to the MySQL server via ODBC, you need
a Connector/ODBC driver. See Chapter 23, Connectors.
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. See
Section 13.1.5, “CREATE TABLE Syntax”.
MySQL for Windows is available in several distribution formats:
Binary distributions are available that contain a setup
program that installs everything you need so that you can
start the server immediately. Another binary distribution
format contains an archive that you simply unpack in the
installation location and then configure yourself. For
details, see Section 2.3.1, “Choosing An Installation Package”.
The source distribution contains all the code and support
files for building the executables using the Visual Studio 7.1
compiler system.
Generally speaking, you should use a binary distribution that
includes an installer. It is simpler to use than the others, and
you need no additional tools to get MySQL up and running. The
installer for the Windows version of MySQL, combined with a GUI
Configuration Wizard, automatically installs MySQL, creates an
option file, starts the server, and secures the default user
accounts.
For MySQL 5.0, there are three installation
packages to choose from when installing MySQL on Windows:
The Essentials Package:
This package has a filename similar to
mysql-essential-5.0.25-win32.msi
and contains the minimum set of files needed to install
MySQL on Windows, including the Configuration Wizard. This
package does not include optional components such as the
embedded server and benchmark suite.
The Complete Package: This
package has a filename similar to
mysql-5.0.25-win32.zip and
contains all files needed for a complete Windows
installation, including the Configuration Wizard. This
package includes optional components such as the embedded
server and benchmark suite.
The Noinstall Archive: This
package has a filename similar to
mysql-noinstall-5.0.25-win32.zip
and contains all the files found in the Complete install
package, with the exception of the Configuration Wizard.
This package does not include an automated installer, and
must be manually installed and configured.
The Essentials package is recommended for most users. It is
provided as an .msi file for use with the
Windows Installer. The Complete and Noinstall distributions are
packaged as Zip archives. To use them, you must have a tool that
can unpack .zip files.
2.3.2. Installing MySQL with the Automated Installer
New MySQL users can use the MySQL Installation Wizard and MySQL
Configuration Wizard to install MySQL on Windows. These are
designed to install and configure MySQL in such a way that new
users can immediately get started using MySQL.
The MySQL Installation Wizard and MySQL Configuration Wizard are
available in the Essentials and Complete install packages. They
are recommended for most standard MySQL installations.
Exceptions include users who need to install multiple instances
of MySQL on a single server host and advanced users who want
complete control of server configuration.
MySQL Installation Wizard is an installer for the MySQL server
that uses the latest installer technologies for Microsoft
Windows. The MySQL Installation Wizard, in combination with
the MySQL Configuration Wizard, allows a user to install and
configure a MySQL server that is ready for use immediately
after installation.
The MySQL Installation Wizard is the standard installer for
all MySQL server distributions, version 4.1.5 and higher.
Users of previous versions of MySQL need to shut down and
remove their existing MySQL installations manually before
installing MySQL with the MySQL Installation Wizard. See
Section 2.3.3.7, “Upgrading MySQL with the Installation Wizard”, for more
information on upgrading from a previous version.
Microsoft has included an improved version of their Microsoft
Windows Installer (MSI) in the recent versions of Windows. MSI
has become the de-facto standard for application installations
on Windows 2000, Windows XP, and Windows Server 2003. The
MySQL Installation Wizard makes use of this technology to
provide a smoother and more flexible installation process.
The Microsoft Windows Installer Engine was updated with the
release of Windows XP; those using a previous version of
Windows can reference
this
Microsoft Knowledge Base article for information on
upgrading to the latest version of the Windows Installer
Engine.
In addition, Microsoft has introduced the WiX (Windows
Installer XML) toolkit recently. This is the first highly
acknowledged Open Source project from Microsoft. We have
switched to WiX because it is an Open Source project and it
allows us to handle the complete Windows installation process
in a flexible manner using scripts.
Improving the MySQL Installation Wizard depends on the support
and feedback of users like you. If you find that the MySQL
Installation Wizard is lacking some feature important to you,
or if you discover a bug, please report it in our bugs
database using the instructions given in
Section 1.8, “How to Report Bugs or Problems”.
2.3.3.2. Downloading and Starting the MySQL Installation Wizard
The MySQL installation packages can be downloaded from
http://dev.mysql.com/downloads/. If the package you
download is contained within a Zip archive, you need to
extract the archive first.
The process for starting the wizard depends on the contents of
the installation package you download. If there is a
setup.exe file present, double-click it
to start the installation process. If there is an
.msi file present, double-click it to
start the installation process.
2.3.3.3. Choosing an Install Type
There are three installation types available:
Typical,
Complete, and
Custom.
The Typical installation type
installs the MySQL server, the mysql
command-line client, and the command-line utilities. The
command-line clients and utilities include
mysqldump, myisamchk,
and several other tools to help you manage the MySQL server.
The Complete installation
type installs all components included in the installation
package. The full installation package includes components
such as the embedded server library, the benchmark suite,
support scripts, and documentation.
The Custom installation type
gives you complete control over which packages you wish to
install and the installation path that is used. See
Section 2.3.3.4, “The Custom Install Dialog”, for
more information on performing a custom install.
If you choose the Typical or
Complete installation types
and click the Next button, you advance
to the confirmation screen to verify your choices and begin
the installation. If you choose the
Custom installation type and
click the Next button, you advance to
the custom installation dialog, described in
Section 2.3.3.4, “The Custom Install Dialog”.
2.3.3.4. The Custom Install Dialog
If you wish to change the installation path or the specific
components that are installed by the MySQL Installation
Wizard, choose the Custom
installation type.
A tree view on the left side of the custom install dialog
lists all available components. Components that are not
installed have a red X icon; components
that are installed have a gray icon. To change whether a
component is installed, click on that component's icon and
choose a new option from the drop-down list that appears.
You can change the default installation path by clicking the
Change... button to the right of the
displayed installation path.
After choosing your installation components and installation
path, click the Next button to advance
to the confirmation dialog.
2.3.3.5. The Confirmation Dialog
Once you choose an installation type and optionally choose
your installation components, you advance to the confirmation
dialog. Your installation type and installation path are
displayed for you to review.
To install MySQL if you are satisfied with your settings,
click the Install button. To change
your settings, click the Back button.
To exit the MySQL Installation Wizard without installing
MySQL, click the Cancel button.
After installation is complete, you have the option of
registering with the MySQL web site. Registration gives you
access to post in the MySQL forums at
forums.mysql.com,
along with the ability to report bugs at
bugs.mysql.com and
to subscribe to our newsletter. The final screen of the
installer provides a summary of the installation and gives you
the option to launch the MySQL Configuration Wizard, which you
can use to create a configuration file, install the MySQL
service, and configure security settings.
2.3.3.6. Changes Made by MySQL Installation Wizard
Once you click the Install button, the
MySQL Installation Wizard begins the installation process and
makes certain changes to your system which are described in
the sections that follow.
Changes to the Registry
The MySQL Installation Wizard creates one Windows registry key
in a typical install situation, located in
HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB.
The MySQL Installation Wizard creates a key named after the
major version of the server that is being installed, such as
MySQL Server 5.0. It contains
two string values, Location and
Version. The Location
string contains the path to the installation directory. In a
default installation it contains C:\Program
Files\MySQL\MySQL Server 5.0\. The
Version string contains the release number.
For example, for an installation of MySQL Server
5.0.25, the key contains a value of
5.0.25.
These registry keys are used to help external tools identify
the installed location of the MySQL server, preventing a
complete scan of the hard-disk to determine the installation
path of the MySQL server. The registry keys are not required
to run the server, and if you install MySQL using the
noinstall Zip archive, the registry keys
are not created.
Changes to the Start Menu
The MySQL Installation Wizard creates a new entry in the
Windows Start menu under a common MySQL
menu heading named after the major version of MySQL that you
have installed. For example, if you install MySQL
5.0, the MySQL Installation Wizard creates a
MySQL Server 5.0 section
in the Start menu.
The following entries are created within the new
Start menu section:
MySQL Command Line Client: This
is a shortcut to the mysql command-line
client and is configured to connect as the
root user. The shortcut prompts for a
root user password when you connect.
MySQL Server Instance Config
Wizard: This is a shortcut to the MySQL
Configuration Wizard. Use this shortcut to configure a
newly installed server, or to reconfigure an existing
server.
MySQL Documentation: This is a
link to the MySQL server documentation that is stored
locally in the MySQL server installation directory. This
option is not available when the MySQL server is installed
using the Essentials installation package.
Changes to the File System
The MySQL Installation Wizard by default installs the MySQL
5.0 server to C:\Program
Files\MySQL\MySQL Server
5.0, where
Program Files is the default
location for applications in your system, and
5.0 is the major
version of your MySQL server. This is the recommended location
for the MySQL server, replacing the former default location
C:\mysql.
By default, all MySQL applications are stored in a common
directory at C:\Program
Files\MySQL, where
Program Files is the default
location for applications in your Windows installation. A
typical MySQL installation on a developer machine might look
like this:
This approach makes it easier to manage and maintain all MySQL
applications installed on a particular system.
2.3.3.7. Upgrading MySQL with the Installation Wizard
The MySQL Installation Wizard can perform server upgrades
automatically using the upgrade capabilities of MSI. That
means you do not need to remove a previous installation
manually before installing a new release. The installer
automatically shuts down and removes the previous MySQL
service before installing the new version.
Automatic upgrades are available only when upgrading between
installations that have the same major and minor version
numbers. For example, you can upgrade automatically from MySQL
4.1.5 to MySQL 4.1.6, but not from MySQL 4.1 to
MySQL 5.0.
The MySQL Configuration Wizard helps automate the process of
configuring your server under Windows. The MySQL Configuration
Wizard creates a custom my.ini file by
asking you a series of questions and then applying your
responses to a template to generate a
my.ini file that is tuned to your
installation.
The MySQL Configuration Wizard is included with the MySQL
5.0 server, and is currently available for
Windows users only.
The MySQL Configuration Wizard is to a large extent the result
of feedback that MySQL AB has received from many users over a
period of several years. However, if you find that it lacks
some feature important to you, please report it in our bugs
database using the instructions given in
Section 1.8, “How to Report Bugs or Problems”.
2.3.4.2. Starting the MySQL Configuration Wizard
The MySQL Configuration Wizard is typically launched from the
MySQL Installation Wizard, as the MySQL Installation Wizard
exits. You can also launch the MySQL Configuration Wizard by
clicking the MySQL Server Instance Config
Wizard entry in the
MySQL section of the Windows
Start menu.
Alternatively, you can navigate to the
bin directory of your MySQL installation
and launch the MySQLInstanceConfig.exe
file directly.
2.3.4.3. Choosing a Maintenance Option
If the MySQL Configuration Wizard detects an existing
my.ini file, you have the option of
either reconfiguring your existing server, or removing the
server instance by deleting the my.ini
file and stopping and removing the MySQL service.
To reconfigure an existing server, choose the
Re-configure Instance option and
click the Next button. Your existing
my.ini file is renamed to
mytimestamp.ini.bak,
where timestamp is the date and
time at which the existing my.ini file
was created. To remove the existing server instance, choose
the Remove Instance option and
click the Next button.
If you choose the Remove Instance
option, you advance to a confirmation window. Click the
Execute button. The MySQL Configuration
Wizard stops and removes the MySQL service, and then deletes
the my.ini file. The server installation
and its data folder are not removed.
If you choose the Re-configure
Instance option, you advance to the
Configuration Type dialog where you can
choose the type of installation that you wish to configure.
2.3.4.4. Choosing a Configuration Type
When you start the MySQL Configuration Wizard for a new MySQL
installation, or choose the Re-configure
Instance option for an existing installation,
you advance to the Configuration Type
dialog.
There are two configuration types available:
Detailed Configuration and
Standard Configuration. The
Standard Configuration option is
intended for new users who want to get started with MySQL
quickly without having to make many decisions about server
configuration. The Detailed
Configuration option is intended for advanced
users who want more fine-grained control over server
configuration.
If you are new to MySQL and need a server configured as a
single-user developer machine, the Standard
Configuration should suit your needs. Choosing
the Standard Configuration option
causes the MySQL Configuration Wizard to set all configuration
options automatically with the exception of
Service Options and
Security Options.
The Standard Configuration sets
options that may be incompatible with systems where there are
existing MySQL installations. If you have an existing MySQL
installation on your system in addition to the installation
you wish to configure, the Detailed
Configuration option is recommended.
There are three different server types available to choose
from. The server type that you choose affects the decisions
that the MySQL Configuration Wizard makes with regard to
memory, disk, and processor usage.
Developer Machine: Choose this
option for a typical desktop workstation where MySQL is
intended only for personal use. It is assumed that many
other desktop applications are running. The MySQL server
is configured to use minimal system resources.
Server Machine: Choose this
option for a server machine where the MySQL server is
running alongside other server applications such as FTP,
email, and Web servers. The MySQL server is configured to
use a moderate portion of the system resources.
Dedicated MySQL Server Machine:
Choose this option for a server machine that is intended
to run only the MySQL server. It is assumed that no other
applications are running. The MySQL server is configured
to use all available system resources.
2.3.4.6. The Database Usage Dialog
The Database Usage dialog allows you to
indicate the storage engines that you expect to use when
creating MySQL tables. The option you choose determines
whether the InnoDB storage engine is
available and what percentage of the server resources are
available to InnoDB.
Multifunctional Database: This
option enables both the InnoDB and
MyISAM storage engines and divides
resources evenly between the two. This option is
recommended for users who use both storage engines on a
regular basis.
Transactional Database Only:
This option enables both the InnoDB and
MyISAM storage engines, but dedicates
most server resources to the InnoDB
storage engine. This option is recommended for users who
use InnoDB almost exclusively and make
only minimal use of MyISAM.
Non-Transactional Database
Only: This option disables the
InnoDB storage engine completely and
dedicates all server resources to the
MyISAM storage engine. This option is
recommended for users who do not use
InnoDB.
2.3.4.7. The InnoDB Tablespace Dialog
Some users may want to locate the InnoDB
tablespace files in a different location than the MySQL server
data directory. Placing the tablespace files in a separate
location can be desirable if your system has a higher capacity
or higher performance storage device available, such as a RAID
storage system.
To change the default location for the
InnoDB tablespace files, choose a new drive
from the drop-down list of drive letters and choose a new path
from the drop-down list of paths. To create a custom path,
click the ... button.
If you are modifying the configuration of an existing server,
you must click the Modify button before
you change the path. In this situation you must move the
existing tablespace files to the new location manually before
starting the server.
2.3.4.8. The Concurrent Connections Dialog
To prevent the server from running out of resources, it is
important to limit the number of concurrent connections to the
MySQL server that can be established. The Concurrent
Connections dialog allows you to choose the expected
usage of your server, and sets the limit for concurrent
connections accordingly. It is also possible to set the
concurrent connection limit manually.
Decision Support (DSS)/OLAP:
Choose this option if your server does not require a large
number of concurrent connections. The maximum number of
connections is set at 100, with an average of 20
concurrent connections assumed.
Online Transaction Processing
(OLTP): Choose this option if your server
requires a large number of concurrent connections. The
maximum number of connections is set at 500.
Manual Setting: Choose this
option to set the maximum number of concurrent connections
to the server manually. Choose the number of concurrent
connections from the drop-down box provided, or enter the
maximum number of connections into the drop-down box if
the number you desire is not listed.
2.3.4.9. The Networking and Strict Mode Options Dialog
Use the Networking Options dialog to enable
or disable TCP/IP networking and to configure the port number
that is used to connect to the MySQL server.
TCP/IP networking is enabled by default. To disable TCP/IP
networking, uncheck the box next to the Enable
TCP/IP Networking option.
Port 3306 is used by default. To change the port used to
access MySQL, choose a new port number from the drop-down box
or type a new port number directly into the drop-down box. If
the port number you choose is in use, you are prompted to
confirm your choice of port number.
Set the Server SQL Mode to either enable or
disable strict mode. Enabling strict mode (default) makes
MySQL behave more like other database management systems.
If you run applications that rely on MySQL's old
“forgiving” behavior, make sure to either adapt
those applications or to disable strict mode. For
more information about strict mode, see
Section 5.2.5, “The Server SQL Mode”.
2.3.4.10. The Character Set Dialog
The MySQL server supports multiple character sets and it is
possible to set a default server character set that is applied
to all tables, columns, and databases unless overridden. Use
the Character Set dialog to change the
default character set of the MySQL server.
Standard Character Set: Choose
this option if you want to use latin1
as the default server character set.
latin1 is used for English and many
Western European languages.
Best Support For
Multilingualism: Choose this option if you
want to use utf8 as the default server
character set. This is a Unicode character set that can
store characters from many different languages.
Manual Selected Default Character Set /
Collation: Choose this option if you want to
pick the server's default character set manually. Choose
the desired character set from the provided drop-down
list.
2.3.4.11. The Service Options Dialog
On Windows NT-based platforms, the MySQL server can be
installed as a Windows service. When installed this way, the
MySQL server can be started automatically during system
startup, and even restarted automatically by Windows in the
event of a service failure.
The MySQL Configuration Wizard installs the MySQL server as a
service by default, using the service name
MySQL. If you do not wish to install the
service, uncheck the box next to the Install As
Windows Service option. You can change the
service name by picking a new service name from the drop-down
box provided or by entering a new service name into the
drop-down box.
To install the MySQL server as a service but not have it
started automatically at startup, uncheck the box next to the
Launch the MySQL Server
Automatically option.
2.3.4.12. The Security Options Dialog
It is strongly recommended that you set a
root password for your MySQL
server, and the MySQL Configuration Wizard requires
by default that you do so. If you do not wish to set a
root password, uncheck the box next to the
Modify Security Settings option.
To set the root password, enter the desired
password into both the New root
password and Confirm
boxes. If you are reconfiguring an existing server, you need
to enter the existing root password into
the Current root password box.
To prevent root logins from across the
network, check the box next to the Root may only
connect from localhost option. This increases
the security of your root account.
To create an anonymous user account, check the box next to the
Create An Anonymous Account option.
Creating an anonymous account can decrease server security and
cause login and permission difficulties. For this reason, it
is not recommended.
2.3.4.13. The Confirmation Dialog
The final dialog in the MySQL Configuration Wizard is the
Confirmation Dialog. To start the
configuration process, click the
Execute button. To return to a previous
dialog, click the Back button. To exit
the MySQL Configuration Wizard without configuring the server,
click the Cancel button.
After you click the Execute button, the
MySQL Configuration Wizard performs a series of tasks and
displays the progress onscreen as the tasks are performed.
The MySQL Configuration Wizard first determines configuration
file options based on your choices using a template prepared
by MySQL AB developers and engineers. This template is named
my-template.ini and is located in your
server installation directory.
The MySQL Configuration Wizard then writes these options to a
my.ini file. The final location of the
my.ini file is displayed next to the
Write configuration file task.
If you chose to create a service for the MySQL server, the
MySQL Configuration Wizard creates and starts the service. If
you are reconfiguring an existing service, the MySQL
Configuration Wizard restarts the service to apply your
configuration changes.
If you chose to set a root password, the
MySQL Configuration Wizard connects to the server, sets your
new root password and applies any other
security settings you may have selected.
After the MySQL Configuration Wizard has completed its tasks,
it displays a summary. Click the Finish
button to exit the MySQL Configuration Wizard.
2.3.4.14. The Location of the my.ini File
The MySQL Configuration Wizard places the
my.ini file in the installation directory
for the MySQL server. This helps associate configuration files
with particular server instances.
To ensure that the MySQL server knows where to look for the
my.ini file, an argument similar to this
is passed to the MySQL server as part of the service
installation:
--defaults-file="C:\Program Files\MySQL\MySQL Server 5.0\my.ini"
Here, C:\Program Files\MySQL\MySQL Server
5.0 is replaced with the
installation path to the MySQL Server. The
--defaults-file option instructs the MySQL
server to read the specified file for configuration options
when it starts.
2.3.4.15. Editing the my.ini File
To modify the my.ini file, open it with a
text editor and make any necessary changes. You can also
modify the server configuration with the
MySQL
Administrator utility.
MySQL clients and utilities such as the
mysql and mysqldump
command-line clients are not able to locate the
my.ini file located in the server
installation directory. To configure the client and utility
applications, create a new my.ini file in
the C:\WINDOWS or
C:\WINNT directory (whichever is
applicable to your Windows version).
2.3.5. Installing MySQL from a Noinstall Zip Archive
Users who are installing from the Noinstall package can use the
instructions in this section to manually install MySQL. The
process for installing MySQL from a Zip archive is as follows:
Extract the archive to the desired install directory
Create an option file
Choose a MySQL server type
Start the MySQL server
Secure the default user accounts
This process is described in the sections that follow.
If you are using a Windows NT-based operating system such as
Windows NT, Windows 2000, Windows XP, or Windows Server
2003, make sure that you are logged in as a user with
administrator privileges.
Choose an installation location. Traditionally, the MySQL
server is installed in C:\mysql. The
MySQL Installation Wizard installs MySQL under
C:\Program Files\MySQL. If you do not
install MySQL at C:\mysql, you must
specify the path to the install directory during startup or
in an option file. See
Section 2.3.7, “Creating an Option File”.
Extract the install archive to the chosen installation
location using your preferred Zip archive tool. Some tools
may extract the archive to a folder within your chosen
installation location. If this occurs, you can move the
contents of the subfolder into the chosen installation
location.
2.3.7. Creating an Option File
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 are used every time the server
starts, you may find it most convenient to use an option file to
specify your MySQL configuration. This is particularly true
under the following circumstances:
The installation or data directory locations are different
from the default locations (C:\Program
Files\MySQL\MySQL Server 5.0 and
C:\Program Files\MySQL\MySQL Server
5.0\data).
You need to tune the server settings.
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, and 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 C: is not 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 Notepad. For example, if MySQL is installed in
E:\mysql and the data directory is in
E:\mydata\data, you can create an option
file containing 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:
[mysqld]
# set basedir to your installation path
basedir=E:\\mysql
# set datadir to the location of your data directory
datadir=E:\\mydata\\data
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, if MySQL is
installed in C:\Program Files\MySQL\MySQL Server
5.0, the data directory is by default in
C:\Program Files\MySQL\MySQL Server
5.0\data. If you want to use
E:\mydata as the data directory instead,
you must do two things:
Move the entire data directory and all
of its contents from C:\Program Files\MySQL\MySQL
Server 5.0\data to
E:\mydata.
Use a --datadir option to specify the new
data directory location each time you start the server.
2.3.8. Selecting a MySQL Server type
The following table shows the available servers for Windows in
MySQL 5.0:
Binary
Description
mysqld-debug
Compiled with full debugging and automatic memory allocation checking,
as well as InnoDB and
BDB support.
mysqld
Optimized binary with InnoDB support.
mysqld-nt
Optimized binary for Windows NT, 2000, and XP with support for named
pipes.
mysqld-max
Optimized binary with InnoDB and
BDB support.
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.
All Windows MySQL 5.0 servers have support for
symbolic linking of database directories.
MySQL supports TCP/IP on all Windows platforms. The
mysqld-nt and mysql-max-nt
servers support named pipes on Windows NT, 2000, XP, and 2003.
However, the default is to use TCP/IP regardless of platform.
(Named pipes are slower than TCP/IP in many Windows
configurations.)
Use of named pipes is subject to these conditions:
Named pipes are enabled only if you start the server with
the --enable-named-pipe option. It is
necessary to use this option explicitly because some users
have experienced problems with 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, 2003).
These servers can be run on Windows 98 or Me, but only if
TCP/IP is installed; named-pipe connections cannot be used.
These servers cannot be run on Windows 95.
Note: Most of the examples in
this manual use mysqld as the server name. If
you choose to use a different server, such as
mysqld-nt, make the appropriate substitutions
in the commands that are shown in the examples.
2.3.9. Starting the Server for the First Time
This section gives a general overview of starting the MySQL
server. The following sections provide more specific information
for starting the MySQL server from the command line or as a
Windows service.
The information here applies primarily if you installed MySQL
using the Noinstall version, or if you wish
to configure and test MySQL manually rather than with the GUI
tools.
The examples in these sections assume that MySQL is installed
under the default location of C:\Program
Files\MySQL\MySQL Server 5.0. Adjust the
pathnames shown in the examples if you have MySQL installed in a
different location.
On NT-based systems such as Windows NT, 2000, XP, or 2003,
clients have two options. They can use TCP/IP, or they can use a
named pipe if the server supports named-pipe connections. For
MySQL to work with TCP/IP on Windows NT 4, you must install
service pack 3 (or newer).
On Windows 95, 98, or Me, MySQL clients always connect to the
server using TCP/IP. (This allows 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 is 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.
MySQL for Windows also supports shared-memory connections if the
server is started with the --shared-memory
option. Clients can connect through shared memory by using the
--protocol=memory option.
Testing is best done from a command prompt in a console window
(or “DOS window”). In 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 make it easier for you to identify and fix any
problems.
To start the server, enter this command:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --console
For a server that includes InnoDB support,
you should see the messages similar to those following as it
starts (the pathnames and sizes may differ):
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: '5.0.25' socket: '' port: 3306
The server continues 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:\Program Files\MySQL\MySQL Server
5.0\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.10, “Post-Installation Setup and Testing”.
2.3.10. 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 (or “DOS
window”) and enter this command:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld"
The path to mysqld may vary depending on the
install location of MySQL on your system.
On non-NT versions of Windows, this command starts
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, XP, or 2003, the
server runs in the foreground and no command prompt appears
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:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" -u root shutdown
Note: If the MySQL
root user account has a password, you need to
invoke mysqladmin with the
-p option and supply the password when
prompted.
This command invokes the MySQL administrative utility
mysqladmin to connect to the server and tell
it to shut down. The command connects as the MySQL
root user, 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:\Program Files\MySQL\MySQL Server
5.0\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 the
--standalone and --debug
options. In this case, mysqld writes a log
file C:\mysqld.trace that should contain
the reason why mysqld doesn't start. See
Section E.1.2, “Creating Trace Files”.
Use mysqld --verbose --help to display all
the options that mysqld understands.
2.3.11. Starting MySQL as a Windows Service
On the NT family (Windows NT, 2000, XP, 2003), the recommended
way to run MySQL is to install it as a Windows service, whereby
MySQL starts and stops automatically when Windows starts and
stops. A MySQL 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, XP, and Server 2003). To
avoid conflicts, it is advisable to close the
Services utility while performing server
installation or removal operations from the command line.
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:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" -u root shutdown
Note: If the MySQL
root user account has a password, you need to
invoke mysqladmin with the
-p option and supply the password when
prompted.
This command invokes the MySQL administrative utility
mysqladmin to connect to the server and tell
it to shut down. The command connects as the MySQL
root user, 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.
Install the server as a service using this command:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --install
The service-installation command does not start the server.
Instructions for that are given later in this section.
To make it easier to invoke MySQL programs, you can add the
pathname of the MySQL bin directory to your
Windows system PATH environment variable:
On the Windows desktop, right-click on the My
Computer icon, and select
Properties
Next select the Advanced tab from
the System Properties menu that appears,
and click the Environment Variables
button.
Under System Variables, select
Path, and then click the
Edit button. The Edit System
Variable dialogue should appear.
Place your cursor at the end of the text appearing in the
space marked Variable Value. (Use the
End key to ensure that your cursor is
positioned at the very end of the text in this space.) Then
enter the complete pathname of your MySQL
bin directory (for example,
C:\Program Files\MySQL\MySQL Server
5.0\bin), Note that there should be a
semicolon separating this path from any values present in
this field. Dismiss this dialogue, and each dialogue in
turn, by clicking OK until all of the
dialogues that were opened have been dismissed. You should
now be able to invoke any MySQL executable program by typing
its name at the DOS prompt from any directory on the system,
without having to supply the path. This includes the
servers, the mysql client, and all MySQL
command-line utilities such as mysqladmin
and mysqldump.
You should not add the MySQL bin
directory to your Windows PATH if you are
running multiple MySQL servers on the same machine.
Warning: You must exercise
great care when editing your system PATH by
hand; accidental deletion or modification of any portion of the
existing PATH value can leave you with a
malfunctioning or even unusable system.
The following additional arguments can be used in MySQL
5.0 when installing the service:
You can specify a service name immediately following the
--install option. The default service name
is MySQL.
If a service name is given, it can be followed by a single
option. By convention, this should be
--defaults-file=file_name
to specify the name of an option file from which the server
should read options when it starts.
It is possible to use a single option other than
--defaults-file, but this is discouraged.
--defaults-file is more flexible because it
enables you to specify multiple startup options for the
server by placing them in the named option file. Also, in
MySQL 5.0, use of an option different from
--defaults-file is not supported until
5.0.3.
As of MySQL 5.0.1, you can also specify a
--local-service option following the
service name. This causes the server to run using the
LocalService Windows account that has
limited system privileges. This account is available only
for Windows XP or newer. If both
--defaults-file and
--local-service are given following the
service name, they can be in any order.
For a MySQL server that is installed as a Windows service, the
following rules determine the service name and option files that
the server uses:
If the service-installation command specifies no service
name or the default service name (MySQL)
following the --install option, the server
uses the a service name of MySQL and
reads options from the [mysqld] group in
the standard option files.
If the service-installation command specifies a service name
other than MySQL following the
--install option, the server uses that
service name. It reads options from the group that has the
same name as the service, and reads options from the
standard option files.
The server also reads options from the
[mysqld] group from the standard option
files. This allows you to use the
[mysqld] group for options that should be
used by all MySQL services, and an option group with the
same name as a service for use by the server installed with
that service name.
If the service-installation command specifies a
--defaults-file option after the service
name, the server reads options only from the
[mysqld] group of the named file and
ignores the standard option files.
As a more complex example, consider the following command:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld"--install MySQL --defaults-file=C:\my-opts.cnf
Here, the default service name (MySQL) 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
[mysqld] group from the standard option
files. However, because the --defaults-file
option is present, the server reads options from the
[mysqld] option group, and only from the
named file.
You can also specify options as Start parameters in the Windows
Services utility before you start the MySQL
service.
Once a MySQL server has been installed as a service, Windows
starts the service automatically whenever Windows starts. The
service also can be started immediately from the
Services utility, or by using a NET
START MySQL command. 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 does not 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 MySQL data
directory (for example, C:\Program Files\MySQL\MySQL
Server 5.0\data). It is the file with a
suffix of .err.
When a MySQL server has been installed as a service, and the
service is running, Windows stops the service automatically when
Windows shuts down. The server also can be stopped manually by
using the Services utility, the NET
STOP MySQL command, or the mysqladmin
shutdown command.
You also have the choice of installing the server as a manual
service if you do not wish for 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:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --install-manual
To remove a server that is installed as a service, first stop it
if it is running by executing NET STOP MySQL.
Then use the --remove option to remove it:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --remove
You can test whether the MySQL server is working by executing
any of the following commands:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqlshow"
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqlshow" -u root mysql
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" version status proc
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysql" test
If mysqld is slow to respond to TCP/IP
connections from client programs, 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 or
--protocol=PIPE option, or by specifying
. (period) as the host name. Use the
--socket option to specify the name of the pipe
if you do not want to use the default pipe name.
Note that if you have set a password for the
root account, deleted the anonymous account,
or ceated a new user account, then you must use the appropriate
-u and -p options with the
commands shown above in order to connect with the MySQL Server.
See Section 5.8.4, “Connecting to the MySQL Server”.
2.3.13. Troubleshooting a MySQL Installation Under Windows
When installing and running MySQL for the first time, you may
encounter certain errors that prevent the MySQL server from
starting. The purpose of this section is to help you diagnose
and correct some of these errors.
Your first resource when troubleshooting server issues is the
error log. The MySQL server uses the error log to record
information relevant to the error that prevents the server from
starting. The error log is located in the data directory
specified in your my.ini file. The default
data directory location is C:\Program
Files\MySQL\MySQL Server 5.0\data. See
Section 5.12.1, “The Error Log”.
Another source of information regarding possible errors is the
console messages displayed when the MySQL service is starting.
Use the NET START MySQL command from the
command line after installing mysqld as a
service to see any error messages regarding the starting of the
MySQL server as a service. See
Section 2.3.11, “Starting MySQL as a Windows Service”.
The following examples show other common error messages you may
encounter when installing MySQL and starting the server for the
first time:
If the MySQL server cannot find the mysql
privileges database or other critical files, you may see
these messsages:
System error 1067 has occurred.
Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't exist
These messages often occur when the MySQL base or data
directories are installed in different locations than the
default locations (C:\Program Files\MySQL\MySQL
Server 5.0 and C:\Program
Files\MySQL\MySQL Server 5.0\data,
respectively).
This situation may occur when MySQL is upgraded and
installed to a new location, but the configuration file is
not updated to reflect the new location. In addition, there
may be old and new configuration files that conflict. Be
sure to delete or rename any old configuration files when
upgrading MySQL.
If you have installed MySQL to a directory other than
C:\Program Files\MySQL\MySQL Server
5.0, you need to ensure that the
MySQL server is aware of this through the use of a
configuration (my.ini) file. The
my.ini file needs to be located in your
Windows directory, typically C:\WINDOWS
or C:\WINNT. You can determine its
exact location from the value of the
WINDIR environment variable by issuing
the following command from the command prompt:
C:\> echo %WINDIR%
An option file can be created and modified with any text
editor, such as Notepad. For example, if MySQL is installed
in E:\mysql and the data directory is
D:\MySQLdata, 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=D:/MySQLdata
Note that Windows pathnames are specified in option files
using (forward) slashes rather than backslashes. If you do
use backslashes, you must double them:
[mysqld]
# set basedir to your installation path
basedir=C:\\Program Files\\MySQL\\MySQL Server 5.0
# set datadir to the location of your data directory
datadir=D:\\MySQLdata
If you change the datadir value in your
MySQL configuration file, you must move the contents of the
existing MySQL data directory before restarting the MySQL
server.
If you reinstall or upgrade MySQL without first stopping and
removing the existing MySQL service and install MySQL using
the MySQL Configuration Wizard, you may see this error:
Error: Cannot create Windows service for MySql. Error: 0
This occurs when the Configuration Wizard tries to install
the service and finds an existing service with the same
name.
One solution to this problem is to choose a service name
other than mysql when using the
configuration wizard. This allows the new service to be
installed correctly, but leaves the outdated service in
place. Although this is harmless, it is best to remove old
services that are no longer in use.
To permanently remove the old mysql
service, execute the following command as a user with
administrative privileges, on the command-line:
Before upgrading MySQL, you must stop the server. If the
server is installed as a service, stop the service with the
following command from the command prompt:
C:\> NET STOP MySQL
If you are not running the MySQL server as a service, use
the following command to stop it:
C:\> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" -u root shutdown
Note: If the MySQL
root user account has a password, you
need to invoke mysqladmin with the
-p option and supply the password when
prompted.
When upgrading to MySQL 5.0 from a version
previous to 4.1.5, or when upgrading from a version of MySQL
installed from a Zip archive to a version of MySQL installed
with the MySQL Installation Wizard, you must manually remove
the previous installation and MySQL service (if the server
is installed as a service).
To remove the MySQL service, use the following command:
C:\> C:\mysql\bin\mysqld --remove
If you do not remove the existing
service, the MySQL Installation Wizard may fail to properly
install the new MySQL service.
If you are installing MySQL from a Zip archive, extract the
archive. You may either overwrite your existing MySQL
installation (usually located at
C:\mysql), or install it into a
different directory, such as C:\mysql5.
Overwriting the existing installation is recommended.
2.3.15. MySQL on Windows Compared to MySQL on Unix
MySQL for Windows has 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! Newer 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 appears to be
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.
MySQL depends on the pread() and
pwrite() system calls to be able to mix
INSERT and SELECT.
Currently, we use mutexes to emulate
pread() and pwrite().
We intend to replace the file level interface with a virtual
interface in the future 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 that MySQL
5.0 can use to 2,048, which means that you
cannot run as many concurrent threads on Windows NT, 2000,
XP, and 2003 as on Unix.
Blocking read
MySQL uses a blocking read for each connection. That has the
following implications if named-pipe connections are
enabled:
A connection is not disconnected automatically after
eight hours, as happens with the Unix version of MySQL.
If a connection hangs, it is not possible to break it
without killing MySQL.
mysqladmin kill does not work on a
sleeping connection.
mysqladmin shutdown cannot abort as
long as there are sleeping connections.
We plan to fix this problem in the future.
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 does not work on Windows
because the MERGE handler does the table
mapping hidden from the upper layer of MySQL. Because
Windows does not allow dropping files that are open, you
first must flush all MERGE tables (with
FLUSH TABLES) or drop the
MERGE table before dropping the table.
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
On Windows 95, you cannot kill MySQL from the Task Manager
or with the shutdown utility. You must stop it 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
Section 9.2.2, “Identifier Case Sensitivity”.
The ‘\’
pathname separator character
Pathname components in Windows 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
thinks that it has encountered end-of-file and aborts the
program.
This is mainly a problem when you try to apply a binary log
as follows:
C:\> mysqlbinlog binary_log_file | 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.
Access denied for
user error
If MySQL cannot resolve your hostname properly, you may get
the following error when you attempt to run a MySQL client
program to connect to a server running on the same machine:
Access denied for user 'some_user'@'unknown'
to database 'mysql'
To fix this problem, 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 macros to use the faster thread-safe increment/decrement
methods provided by Windows.
2.4. 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”.
MySQL AB does provide some platform-specific RPMs; the difference
between a platform-specific RPM and a generic RPM is that a
platform-specific RPM is built on the targeted platform and is
linked dynamically whereas a generic RPM is linked statically with
LinuxThreads.
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.
In most cases, you need to install only 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 5.3, “The mysqld-max Extended MySQL Server”.
If you get a dependency failure when trying to install MySQL
packages (for example, error: removing these packages
would break dependencies: libmysqlclient.so.10 is needed by
...), you should also install the
MySQL-shared-compat package, which includes
both the shared libraries for backward compatibility
(libmysqlclient.so.12 for MySQL 4.0 and
libmysqlclient.so.10 for MySQL 3.23).
Some 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. (Do not
install both.)
The following RPM packages are available:
MySQL-server-VERSION.i386.rpm
The MySQL server. You 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
DBI and DBD::mysql
modules.
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. It
contains single-threaded and thread-safe libraries. If you
install this package, do not install the
MySQL-shared-compat package.
MySQL-shared-compat-VERSION.i386.rpm
This package includes the shared libraries for MySQL 3.23,
4.0, 4.1, and 5.0. It contains single-threaded and thread-safe
libraries. Install this package instead of
MySQL-shared if you have applications
installed that are dynamically linked against older versions
of MySQL but you want to upgrade to the current version
without breaking the library dependencies.
MySQL-embedded-VERSION.i386.rpm
The embedded MySQL server library (available as of 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 a commnd like this:
shell> rpm -qpl MySQL-server-VERSION.i386.rpm
To perform a standard minimal installation, install the server and
client RPMs:
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 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.10.2.2, “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 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 be
able to start using MySQL.
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.10, “Post-Installation Setup and Testing”.
2.5. Installing MySQL on Mac OS X
You can install MySQL on Mac OS X 10.3.x (“Panther”)
or newer 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 or 10.2.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.
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
guides 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 installs itself into
/usr/local/mysql-VERSION
and also installs a symbolic link,
/usr/local/mysql, that points to the new
location. If a directory named
/usr/local/mysql exists, it is renamed to
/usr/local/mysql.bak first. Additionally, the
installer creates the grant tables in the mysql
database by executing mysql_install_db.
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, a version of MySQL should
already be installed. The following table shows the versions of
MySQL that ship with Mac OS X Server versions.
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
10.4.0
4.1.10a
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.x 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 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
If you want MySQL to start automatically during system startup,
you also need to install the MySQL Startup Item. 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. 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 for MySQL is 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 want 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 a 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, use this command:
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM 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 be able to connect to the MySQL server, for example, by
running /usr/local/mysql/bin/mysql.
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.10, “Post-Installation Setup and Testing”.
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 bash is:
alias mysql=/usr/local/mysql/bin/mysql
alias mysqladmin=/usr/local/mysql/bin/mysqladmin
For tcsh, 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/.bashrc file if
your shell is bash:
PATH=${PATH}:/usr/local/mysql/bin
Add the following line to your $HOME/.tcshrc
file if your shell is tcsh:
setenv PATH ${PATH}:/usr/local/mysql/bin
If no .bashrc or .tcshrc
file exists in your home directory, create it with a text editor.
If you are upgrading an existing installation, 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.6. Installing MySQL on Solaris
If you install MySQL using a binary tarball distribution on
Solaris, you may run into trouble even before you get the MySQL
distribution unpacked, as the Solaris tar
cannot handle long filenames. This means that you may see errors
when you try to unpack MySQL.
You can install MySQL on Solaris using a binary package in PKG
format instead of the binary tarball distribution. Before
installing using the binary PKG format, you should create the
mysql user and group, for example:
groupadd mysql
useradd -g mysql mysql
Some basic PKG-handling commands follow:
To add a package:
pkgadd -d package_name.pkg
To remove a package:
pkgrm package_name
To get a full list of installed packages:
pkginfo
To get detailed information for a package:
pkginfo -l package_name
To list the files belonging to a package:
pkgchk -v package_name
To get packaging information for an arbitrary file:
Porting MySQL to NetWare was an effort spearheaded by Novell.
Novell customers should 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.
MySQL for NetWare is compiled using a combination of Metrowerks
CodeWarrior for NetWare and special cross-compilation versions of
the GNU autotools.
To host MySQL, the NetWare server must meet these requirements:
The latest Support Pack of
NetWare
6.5 must be installed.
The system must meet Novell's minimum requirements to run the
respective version of NetWare.
MySQL data and the program binaries 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
Note: If the MySQL
root user account has a password, you need
to invoke mysqladmin with the
-p option and supply the password when
prompted.
Log on to the target server from a client machine with access
to the location where you are installing 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), 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. The examples in this manual use
SYS:MYSQL to refer to the installation
directory.
Note that MySQL installation on NetWare does not detect if a
version of MySQL is already installed outside the NetWare
release. Therefore, if you have installed the latest MySQL
version from the Web (for example, MySQL 4.1 or later) in
SYS:\MYSQL, you must rename the folder
before upgrading the NetWare server; otherwise, files in
SYS:\MySQL are overwritten by the MySQL
version present in NetWare Support Pack.
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
necessary, 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 5.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 5.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --skip-external-locking
It is also 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. Note that the use
of MySQL on Netware 6.0 is not officially supported.
mysqld_safe on NetWare provides a screen
presence. When you unload (shut down) the
mysqld_safe NLM, the screen does not go
away by default. 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 5.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --autoclose
When installing MySQL, either for the first time or upgrading
from a previous version, download and install the latest and
appropriate Perl module and PHP extensions for NetWare:
If there was an existing installation of MySQL on the NetWare
server, be sure to check for existing MySQL startup commands in
autoexec.ncf, and edit or delete them as
necessary.
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.10, “Post-Installation Setup and Testing”.
2.8. 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.
MySQL tar file binary distributions have names
of the form
mysql-VERSION-OS.tar.gz,
where VERSION is a
number (for example, 5.0.25), and
OS indicates the type of operating
system for which the distribution is intended (for example,
pc-linux-i686).
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.
The basic commands that 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 &
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, or they may
have different names such as 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 must perform the installation as
root.)
shell> cd /usr/local
Obtain a distribution file using the instructions 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 creates 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:
The bin 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 F, Environment Variables.
The scripts 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 have not 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 must
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.
After creating or updating the grant tables, you need to
restart the server manually.
Change the ownership of program binaries to
root and ownership of the data directory to
the user that you 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 want 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.10.2.2, “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.14, “Perl Installation Notes”.
If you would like to use mysqlaccess and
have the MySQL distribution in some non-standard location, 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, a Broken pipe error
will occur when you run mysqlaccess.
After everything has been unpacked and installed, you should test
your distribution. To start the MySQL server, use the following
command:
shell> bin/mysqld_safe --user=mysql &
If that command fails immediately and prints mysqld
ended, you can find some information in the
host_name.err file
in the data directory.
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.10, “Post-Installation Setup and Testing”.
2.9. MySQL Installation Using a Source Distribution
Before you proceed with an installation from source, first check
whether our binary is available for your platform and whether it
works for you. We put a great deal of effort into ensuring that
our binaries are built with the best possible options.
MySQL source distributions are provided as compressed
tar archives and have names of the form
mysql-VERSION.tar.gz,
where VERSION is a number like
5.0.25.
You need the following tools to build and install MySQL from
source:
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, the tar provided with early
versions of Mac OS X tar, SunOS 4.x and
Solaris 8 and earlier 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.
A working ANSI C++ compiler. gcc 2.95.2 or
later, egcs 1.0.2 or later or egcs
2.91.66, SGI C++, and SunPro C++ are some of the
compilers that are known to work. libg++ is
not needed when using gcc.
gcc 2.7.x has a bug that makes it
impossible to compile some perfectly legal C++ files, such as
sql/sql_base.cc. If you have only
gcc 2.7.x, you must upgrade your
gcc to be able to compile MySQL.
gcc 2.8.1 is also known to have problems on
some platforms, so it should be avoided if a new compiler
exists for the platform.
gcc 2.95.2 or later is recommended when
compiling MySQL 3.23.x.
A good make program. GNU
make is always recommended and is sometimes
required. If you have problems, we recommend GNU
make 3.75 or newer.
If you are using a version of gcc recent enough
to understand the -fno-exceptions option, it is
very important that you use this option.
Otherwise, you may compile a binary that crashes randomly. We also
recommend that you use -felide-constructors and
-fno-rtti along with
-fno-exceptions. When in doubt, do the following:
This makes a binary RPM that you can install. For older versions
of RPM, you may have to replace the command
rpmbuild with rpm instead.
Note: This procedure does not
set up any passwords for MySQL accounts. After following the
procedure, proceed to Section 2.10, “Post-Installation Setup and Testing”, for
post-installation setup and testing.
A more detailed version of the preceding description for
installing MySQL from a source 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, or they
may have different names such as 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.
Unpack the distribution into the current directory:
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -
This command creates a directory named
mysql-VERSION.
With GNU tar, no separate invocation of
gunzip is necessary. You can use the
following alternative command to uncompress and extract the
distribution:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
Change location into the top-level directory of the unpacked
distribution:
shell> cd mysql-VERSION
Note that currently you must configure and build MySQL from
this top-level directory. You cannot build it in a different
directory.
Configure the release and compile everything:
shell> ./configure --prefix=/usr/local/mysql
shell> make
When you run configure, you might want to
specify other options. Run ./configure
--help for a list of options.
Section 2.9.2, “Typical configure Options”, discusses some of the
more useful options.
If configure fails and you are going to
send mail to a MySQL mailing list to ask for assistance,
please include any lines from
config.log that you think can help
solve the problem. Also include the last couple of lines of
output from configure. To file a bug
report, please use the instructions in
Section 1.8, “How to Report Bugs or Problems”.
If you want to set up an option file, use one of those
present in the support-files directory
as a template. For example:
shell> cp support-files/my-medium.cnf /etc/my.cnf
You might need to run these commands as
root.
If you want to configure support for
InnoDB tables, you should edit the
/etc/my.cnf file, remove the
# character before the option lines that
start with innodb_..., and modify the
option values to be what you want. See
Section 4.3.2, “Using Option Files”, and
Section 14.2.3, “InnoDB Configuration”.
Change location into the installation directory:
shell> cd /usr/local/mysql
If you haven't installed MySQL before, you must create the
MySQL grant tables:
shell> bin/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.
After using mysql_install_db to create
the grant tables for MySQL, you must restart the server
manually. The mysqld_safe command to do
this is shown in a later step.
Change the ownership of program binaries to
root and ownership of the data directory
to the user that you 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 var
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 want 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; see also Section 2.10.2.2, “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.14, “Perl Installation Notes”.
After everything has been installed, you should test your
distribution. To start the MySQL server, use the following
command:
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.10, “Post-Installation Setup and Testing”.
2.9.2. Typical configure Options
The configure script gives you a great deal
of control over how you configure a MySQL source distribution.
Typically you do this using options on the
configure command line. You can also affect
configure using certain environment
variables. See Appendix F, Environment Variables. For a
list of options supported by configure, run
this command:
shell> ./configure --help
Some of the more commonly used configure
options are described here:
To compile just the MySQL client libraries and client
programs and not the server, use the
--without-server option:
shell> ./configure --without-server
If you have no C++ compiler, some client programs such as
mysql cannot be compiled because they
require C++.. In this case, you can remove the code in
configure that tests for the C++ compiler
and then run ./configure with the
--without-server option. The compile step
should still try to build all clients, but you can ignore
any warnings about files such as
mysql.cc. (If make
stops, try make -k to tell it to continue
with the rest of the build even if errors occur.)
If you want to build the embedded MySQL library
(libmysqld.a), use the
--with-embedded-server option.
If you don't want your log files and database directories
located under /usr/local/var, use a
configure command something like one of
these:
The first command changes the installation prefix so that
everything is installed under
/usr/local/mysql rather than the
default of /usr/local. The second
command preserves the default installation prefix, but
overrides the default location for database directories
(normally /usr/local/var) and changes
it to /usr/local/mysql/data.
You can also specify the installation directory and data
directory locations at server startup time by using the
--basedir and --datadir
options. These can be given on the command line or in an
MySQL option file, although it is more common to use an
option file. See Section 4.3.2, “Using Option Files”.
If you are using Unix and you want the MySQL socket file
location to be somewhere other than the default location
(normally in the directory /tmp or
/var/run), use a
configure command like this:
If you want to compile statically linked programs (for
example, to make a binary distribution, to get better
performance, or to work around problems with some Red Hat
Linux distributions), run configure like
this:
If you are using gcc and don't have
libg++ or libstdc++
installed, you can tell configure to use
gcc as your C++ compiler:
shell> CC=gcc CXX=gcc ./configure
When you use gcc as your C++ compiler, it
does not attempt to link in libg++ or
libstdc++. This may be a good thing to do
even if you have those libraries installed. Some versions of
them have caused strange problems for MySQL users in the
past.
The following list indicates some compilers and environment
variable settings that are commonly used with each one.
In most cases, you can get a reasonably optimized MySQL
binary by using the options from the preceding list and
adding the following options to the
configure line:
If the build fails and produces errors about your compiler
or linker not being able to create the shared library
libmysqlclient.so.N
(where N is a version number),
you can work around this problem by giving the
--disable-shared option to
configure. In this case,
configure does not build a shared
libmysqlclient.so.N
library.
By default, MySQL uses the latin1 (cp1252
West European) character set. To change the default set, use
the --with-charset option:
shell> ./configure --with-charset=CHARSET
CHARSET may be one of
big5, cp1251,
cp1257, czech,
danish, dec8,
dos, euc_kr,
gb2312, gbk,
german1, hebrew,
hp8, hungarian,
koi8_ru, koi8_ukr,
latin1, latin2,
sjis, swe7,
tis620, ujis,
usa7, or win1251ukr.
See Section 5.11.1, “The Character Set Used for Data and Sorting”. (Additional character
sets might be available. Check the output from
./configure --help for the current list.)
The default collation may also be specified. MySQL uses the
latin1_swedish_ci collation by default.
To change this, use the --with-collation
option:
shell> ./configure --with-collation=COLLATION
To change both the character set and the collation, use both
the --with-charset and
--with-collation options. The collation
must be a legal collation for the character set. (Use the
SHOW COLLATION statement to determine
which collations are available for each character set.)
Warning: If you change
character sets after having created any tables, you must run
myisamchk -r -q
--set-collation=collation_nameon every MyISAM
table. Your indexes may be sorted incorrectly
otherwise. This can happen if you install MySQL, create some
tables, and then reconfigure MySQL to use a different
character set and reinstall it.
With the configure option
--with-extra-charsets=LIST,
you can define which additional character sets should be
compiled into the server. LIST is
one of the following:
A list of character set names separated by spaces
complex to include all character sets
that can't be dynamically loaded
all to include all character sets
into the binaries
To configure MySQL with debugging code, use the
--with-debug option:
shell> ./configure --with-debug
This causes a safe memory allocator to be included that can
find some errors and that provides output about what is
happening. See Section E.1, “Debugging a MySQL Server”.
If your client programs are using threads, you must compile
a thread-safe version of the MySQL client library with the
--enable-thread-safe-client configure
option. This creates a libmysqlclient_r
library with which you should link your threaded
applications. See Section 22.2.15, “How to Make a Threaded Client”.
It is possible to build MySQL 5.0 with large
table support using the --with-big-tables
option, beginning with MySQL 5.0.4.
This option causes the variables that store table row counts
to be declared as unsigned long long
rather than unsigned long. This enables
tables to hold up to approximately 1.844E+19
((232)2)
rows rather than 232 (~4.295E+09)
rows. Previously it was necessary to pass
-DBIG_TABLES to the compiler manually in
order to enable this feature.
2.9.3. Installing from the Development Source Tree
Caution: You should read this
section only if you are interested in helping us test our new
code. If you just want to get MySQL up and running on your
system, you should use a standard release distribution (either a
binary or source distribution).
To obtain our most recent development source tree, first
download and install the BitKeeper free client if you do not
have it. The client can be obtained from
http://www.bitmover.com/bk-client.shar.
To install the BitKeeper client on Unix, use these commands:
shell> sh bk-client.shar
shell> cd bk_client-1.1
shell> make all
shell> PATH=$PWD:$PATH
To install the BitKeeper client on Windows, use these
instructions:
Make sure gcc and make
have been installed under Cygwin. You can test this by
issuing which gcc and which
make commands. If either one is not installed, run
Cygwin's package manager, select gcc,
make, or both, and install them.
Under Cygwin, execute these commands:
shell> sh bk-client.shar
shell> cd bk_client-1.1
Then edit the Makefile and change the
line that reads $(CC) $(CFLAGS) -o sfio -lz
sfio.c to this:
$(CC) $(CFLAGS) -o sfio sfio.c -lz
Now run the make command and set the
path:
shell> make all
shell> PATH=$PWD:$PATH
The BitKeeper free client is shipped with its source code. The
only documentation available for the free client is the source
code itself.
After you have installed the BitKeeper client, you can access
the MySQL development source tree:
Change location to the directory you want to work from, and
then use the following command to make a local copy of the
MySQL 5.0 branch:
In the preceding example, the source tree is set up in the
mysql-5.0/ subdirectory of
your current directory.
The initial download of the source tree may take a while,
depending on the speed of your connection. Please be
patient.
You need GNU make,
autoconf 2.58 (or newer),
automake 1.8, libtool
1.5, and m4 to run the next set of
commands. Even though many operating systems come with their
own implementation of make, chances are
high that the compilation fails with strange error messages.
Therefore, it is highly recommended that you use GNU
make (sometimes named
gmake) instead.
Fortunately, a large number of operating systems ship with
the GNU toolchain preinstalled or supply installable
packages of these. In any case, they can also be downloaded
from the following locations:
To configure MySQL 5.0, you also need GNU
bison 1.75 or later. Older versions of
bison may report this error:
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded
Note: The maximum table size is not actually exceeded; the
error is caused by bugs in older versions of
bison.
The following example shows the typical commands required to
configure a source tree. The first cd
command changes location into the top-level directory of the
tree; replace mysql-5.0
with the appropriate directory name.
shell> cd mysql-5.0
shell> (cd bdb/dist; sh s_all)
shell> (cd innobase; autoreconf --force --install)
shell> autoreconf --force --install
shell> ./configure # Add your favorite options here
shell> make
Or you can use BUILD/autorun.sh as a
shortcut for the following sequence of commands:
The command lines that change directory into the
innobase and
bdb/dist directories are used to
configure the InnoDB and Berkeley DB
(BDB) storage engines. You can omit these
command lines if you to not require
InnoDB or BDB support.
If you get some strange errors during this stage, verify
that you really have libtool installed.
A collection of our standard configuration scripts is
located in the BUILD/ subdirectory. You
may find it more convenient to use the
BUILD/compile-pentium-debug script than
the preceding set of shell commands. To compile on a
different architecture, modify the script by removing flags
that are Pentium-specific.
When the build is done, run make install.
Be careful with this on a production machine; the command
may overwrite your live release installation. If you have
another installation of MySQL, we recommend that you run
./configure with different values for the
--prefix, --with-tcp-port,
and --unix-socket-path options than those
used for your production server.
Play hard with your new installation and try to make the new
features crash. Start by running make
test. See Section 24.1.2, “MySQL Test Suite”.
If you have gotten to the make stage, but
the distribution does not compile, please enter the problem
into our bugs database using the instructions given in
Section 1.8, “How to Report Bugs or Problems”. If you have installed the
latest versions of the required GNU tools, and they crash
trying to process our configuration files, please report
that also. However, if you execute
aclocal and get a command not
found error or a similar problem, do not report
it. Instead, make sure that all the necessary tools are
installed and that your PATH variable is
set correctly so that your shell can find them.
After initially copying the repository with
sfioball to obtain the source tree, you
should use update periodically to update
your local copy. To do this any time after you have set up
the repository, use this command:
shell> update bk://mysql.bkbits.net/mysql-5.0
You can examine the change history for the tree with all the
diffs by viewing the BK/ChangeLog file
in the source tree and looking at the
ChangeSet descriptions listed there. To
examine a particular changeset, you would have to use the
sfioball command to extract two
particular revisions of the source tree, and then use an
external diff command to compare them. If
you see some funny diffs or code that you have a question
about, do not hesitate to send email to the MySQL
internals mailing list. See
Section 1.7.1, “MySQL Mailing Lists”. Also, if you think you have
a better idea on how to do something, send an email message
to the list with a patch.
You can also browse changesets, comments, and source code
online. To browse this information for MySQL 5.0,
go to
http://mysql.bkbits.net:8080/mysql-5.0.
2.9.4. Dealing with Problems Compiling MySQL
All MySQL programs compile cleanly for us with no warnings on
Solaris or Linux using gcc. On other systems,
warnings may occur due to differences in system include files.
See Section 2.9.5, “MIT-pthreads Notes”, for warnings that may occur
when using MIT-pthreads. For other problems, check the following
list.
The solution to many problems involves reconfiguring. If you do
need to reconfigure, take note of the following:
If configure is run after it has
previously been run, it may use information that was
gathered during its previous invocation. This information is
stored in config.cache. When
configure starts up, it looks for that
file and reads its contents if it exists, on the assumption
that the information is still correct. That assumption is
invalid when you reconfigure.
Each time you run configure, you must run
make again to recompile. However, you may
want to remove old object files from previous builds first
because they were compiled using different configuration
options.
To prevent old configuration information or object files from
being used, run these commands before re-running
configure:
shell> rm config.cache
shell> make clean
Alternatively, you can run make distclean.
The following list describes some of the problems when compiling
MySQL that have been found to occur most often:
If you get errors such as the ones shown here when compiling
sql_yacc.cc, you probably have run out
of memory or swap space:
Internal compiler error: program cc1plus got fatal signal 11
Out of virtual memory
Virtual memory exhausted
The problem is that gcc requires a huge
amount of memory to compile sql_yacc.cc
with inline functions. Try running
configure with the
--with-low-memory option:
shell> ./configure --with-low-memory
This option causes -fno-inline to be added
to the compile line if you are using gcc
and -O0 if you are using something else.
You should try the --with-low-memory option
even if you have so much memory and swap space that you
think you can't possibly have run out. This problem has been
observed to occur even on systems with generous hardware
configurations, and the --with-low-memory
option usually fixes it.
By default, configure picks
c++ as the compiler name and GNU
c++ links with -lg++. If
you are using gcc, that behavior can
cause problems during configuration such as this:
configure: error: installation or configuration problem:
C++ compiler cannot create executables.
You might also observe problems during compilation related
to g++, libg++, or
libstdc++.
One cause of these problems is that you may not have
g++, or you may have
g++ but not libg++, or
libstdc++. Take a look at the
config.log file. It should contain the
exact reason why your C++ compiler didn't work. To work
around these problems, you can use gcc as
your C++ compiler. Try setting the environment variable
CXX to "gcc -O3". For
example:
shell> CXX="gcc -O3" ./configure
This works because gcc compiles C++
source files as well as g++ does, but
does not link in libg++ or
libstdc++ by default.
Another way to fix these problems is to install
g++, libg++, and
libstdc++. However, we recommend that you
not use libg++ or
libstdc++ with MySQL because this only
increases the binary size of mysqld
without providing any benefits. Some versions of these
libraries have also caused strange problems for MySQL users
in the past.
If your compile fails with errors such as any of the
following, you must upgrade your version of
make to GNU make:
making all in mit-pthreads
make: Fatal error in reader: Makefile, line 18:
Badly formed macro assignment
Or:
make: file `Makefile' line 18: Must be a separator (:
Or:
pthread.h: No such file or directory
Solaris and FreeBSD are known to have troublesome
make programs.
GNU make 3.75 is known to work.
If you want to define flags to be used by your C or C++
compilers, do so by adding the flags to the
CFLAGS and CXXFLAGS
environment variables. You can also specify the compiler
names this way using CC and
CXX. For example:
If you get errors such as those shown here when compiling
mysqld, configure did
not correctly detect the type of the last argument to
accept(),
getsockname(), or
getpeername():
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
type of the pointer value ''length'' is ''unsigned long'',
which is not compatible with ''int''.
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
To fix this, edit the config.h file
(which is generated by configure). Look
for these lines:
/* Define as the base type of the last arg to accept */
#define SOCKET_SIZE_TYPE XXX
Change XXX to size_t
or int, depending on your operating
system. (You must do this each time you run
configure because
configure regenerates
config.h.)
The sql_yacc.cc file is generated from
sql_yacc.yy. Normally, the build
process does not need to create
sql_yacc.cc because MySQL comes with a
pre-generated copy. However, if you do need to re-create it,
you might encounter this error:
"sql_yacc.yy", line xxx fatal: default action causes potential...
This is a sign that your version of yacc
is deficient. You probably need to install
bison (the GNU version of
yacc) and use that instead.
On Debian Linux 3.0, you need to install
gawk instead of the default
mawk if you want to compile MySQL with
Berkeley DB support.
If you need to debug mysqld or a MySQL
client, run configure with the
--with-debug option, and then recompile and
link your clients with the new client library. See
Section E.2, “Debugging a MySQL Client”.
If you get a compilation error on Linux (for example, SuSE
Linux 8.1 or Red Hat Linux 7.3) similar to the following
one, you probably do not have g++
installed:
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
incompatible pointer type
libmysql.c:1329: too few arguments to function `gethostbyname_r'
libmysql.c:1329: warning: assignment makes pointer from integer
without a cast
make[2]: *** [libmysql.lo] Error 1
By default, the configure script attempts
to determine the correct number of arguments by using
g++ (the GNU C++ compiler). This test
yields incorrect results if g++ is not
installed. There are two ways to work around this problem:
Make sure that the GNU C++ g++ is
installed. On some Linux distributions, the required
package is called gpp; on others, it
is named gcc-c++.
Use gcc as your C++ compiler by
setting the CXX environment variable
to gcc:
export CXX="gcc"
You must run configure again after making
either of those changes.
2.9.5. MIT-pthreads Notes
This section describes some of the issues involved in using
MIT-pthreads.
On Linux, you should not use MIT-pthreads.
Use the installed LinuxThreads implementation instead. See
Section 2.13.1, “Linux Notes”.
If your system does not provide native thread support, you
should build MySQL using the MIT-pthreads package. This includes
older FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and
some others. See Section 2.1.1, “Operating Systems Supported by MySQL”.
After downloading, extract this source archive into the top
level of the MySQL source directory. It creates a new
subdirectory named mit-pthreads.
On most systems, you can force MIT-pthreads to be used by
running configure with the
--with-mit-threads option:
shell> ./configure --with-mit-threads
Building in a non-source directory is not supported when
using MIT-pthreads because we want to minimize our changes
to this code.
The checks that determine whether to use MIT-pthreads occur
only during the part of the configuration process that deals
with the server code. If you have configured the
distribution using --without-server to
build only the client code, clients do not know whether
MIT-pthreads is being used and use Unix socket file
connections by default. Because Unix socket files do not
work under MIT-pthreads on some platforms, this means you
need to use -h or --host
with a value other than localhost when
you run client programs.
When MySQL is compiled using MIT-pthreads, system locking is
disabled by default for performance reasons. You can tell
the server to use system locking with the
--external-locking option. This is needed
only if you want to be able to run two MySQL servers against
the same data files, but that is not recommended, anyway.
Sometimes the pthread bind() command
fails to bind to a socket without any error message (at
least on Solaris). The result is that all connections to the
server fail. For example:
shell> mysqladmin version
mysqladmin: connect to server at '' failed;
error: 'Can't connect to mysql server on localhost (146)'
The solution to this problem is to kill the
mysqld server and restart it. This has
happened to us only when we have forcibly stopped the server
and restarted it immediately.
With MIT-pthreads, the sleep() system
call isn't interruptible with SIGINT
(break). This is noticeable only when you run
mysqladmin --sleep. You must wait for the
sleep() call to terminate before the
interrupt is served and the process stops.
When linking, you might receive warning messages like these
(at least on Solaris); they can be ignored:
ld: warning: symbol `_iob' has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
ld: warning: symbol `__iob' has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
Some other warnings also can be ignored:
implicit declaration of function `int strtoll(...)'
implicit declaration of function `int strtoul(...)'
We have not been able to make readline
work with MIT-pthreads. (This is not necessary, but may be
of interest to some.)
These instructions describe how to build binaries from source
for MySQL 5.0 on Windows. Instructions are provided
for building binaries from a standard source distribution or
from the BitKeeper tree that contains the latest development
source.
Note: The instructions here are
strictly for users who want to test MySQL on Windows from the
latest source distribution or from the BitKeeper tree. For
production use, MySQL AB does not advise using a MySQL server
built by yourself from source. Normally, it is best to use
precompiled binary distributions of MySQL that are built
specifically for optimal performance on Windows by MySQL AB.
Instructions for installing a binary distributions are available
in Section 2.3, “Installing MySQL on Windows”.
To build MySQL on Windows from source, you need the following
compiler and resources available on your Windows system:
You also need a MySQL source distribution for Windows. There are
two ways to obtain a source distribution:
Obtain a Windows source distribution packaged by MySQL AB for the
particular version of MySQL in which you are interested.
These are available from
http://dev.mysql.com/downloads/.
You can package a source distribution yourself from the
latest BitKeeper developer source tree. If you plan to do
this, you must create the package on a Unix system and then
transfer it to your Windows system. (Some of the
configuration and build steps require tools that work only
on Unix.) The BitKeeper approach thus requires:
A system running Unix, or a Unix-like system such as
Linux.
If you find something not working as expected, or you have
suggestions about ways to improve the current build process on
Windows, please send a message to the win32
mailing list. See Section 1.7.1, “MySQL Mailing Lists”.
2.9.6.1. Building MySQL Using VC++
Note: VC++ workspace files
for MySQL 4.1 and above are compatible with Microsoft Visual
Studio 7.1 and tested by MySQL AB staff before each release.
Follow this procedure to build MySQL:
Create a work directory (for example,
C:\workdir).
Unpack the source distribution in the aforementioned
directory using WinZip or another
Windows tool that can read .zip
files.
Start Visual Studio .Net 2003 (7.1).
From the File menu, select
Open Solution....
Open the mysql.sln solution you find
in the work directory.
From the Build menu, select
Configuration Manager....
In the Active Solution Configuration pop-up menu,
select the configuration to use. You likely want to use one of
nt (normal server, not for Windows 98/ME),
Max nt (more engines and features, not for 98/ME) or
Debug configuration.
From the Build menu, select
Build Solution.
Debug versions of the programs and libraries are placed in
the client_debug and
lib_debug directories. Release
versions of the programs and libraries are placed in the
client_release and
lib_release directories.
Test the server. The server built using the preceding
instructions expects that the MySQL base directory and
data directory are C:\mysql and
C:\mysql\data by default. If you want
to test your server using the source tree root directory
and its data directory as the base directory and data
directory, you need to tell the server their pathnames.
You can either do this on the command line with the
--basedir and --datadir
options, or by placing appropriate options in an option
file. (See Section 4.3.2, “Using Option Files”.) If you have an
existing data directory elsewhere that you want to use,
you can specify its pathname instead.
Start your server from the
client_release or
client_debug directory, depending on
which server you built or want to use. The general server startup
instructions are in
Section 2.3, “Installing MySQL on Windows”. You must adapt the
instructions appropriately if you want to use a different
base directory or data directory.
When the server is running in standalone fashion or as a
service based on your configuration, try to connect to it
from the mysql interactive command-line
utility that exists in your
client_release or
client_debug directory.
When you are satisfied that the programs you have built are
working correctly, stop the server. Then install MySQL as
follows:
Create the directories where you want to install MySQL.
For example, to install into
C:\mysql, use these commands:
2.9.6.2. Creating a Windows Source Package from the Latest Development Source
To create a Windows source package from the current BitKeeper
source tree, use the instructions here. This procedure must be
performed on a system running a Unix or Unix-like operating
system because some of the configuration and build steps
require tools that work only on Unix. For example, the
following procedure is known to work well on Linux.
Configure and build the distribution so that you have a
server binary to work with. One way to do this is to run
the following command in the top-level directory of your
source tree:
shell> ./BUILD/compile-pentium-max
After making sure that the build process completed
successfully, run the following utility script from
top-level directory of your source tree:
shell> ./scripts/make_win_src_distribution
This script creates a Windows source package to be used on
your Windows system. You can supply different options to
the script based on your needs. It accepts the following
options:
--help
Display a help message.
--debug
Print information about script operations, do not
create package.
--tmp
Specify the temporary location.
--suffix
The suffix name for the package.
--dirname
Directory name to copy files (intermediate).
--silent
Do not print verbose list of files processed.
--tar
Create tar.gz package instead of
.zip package.
By default, make_win_src_distribution
creates a Zip-format archive with the name
mysql-VERSION-win-src.zip,
where VERSION represents the
version of your MySQL source tree.
Copy or upload the Windows source package that you have
just created to your Windows machine. To compile it, use
the instructions in
Section 2.9.6.1, “Building MySQL Using VC++”.
2.9.7. Compiling MySQL Clients on Windows
In your source files, you should include
my_global.h before
mysql.h:
#include <my_global.h>
#include <mysql.h>
my_global.h includes any other files needed
for Windows compatibility (such as
windows.h) if you compile your program on
Windows.
You can either link your code with the dynamic
libmysql.lib library, which is just a
wrapper to load in libmysql.dll on demand,
or link with the static mysqlclient.lib
library.
The MySQL client libraries are compiled as threaded libraries,
so you should also compile your code to be multi-threaded.
After installing MySQL, there are some issues that you should
address. For example, on Unix, you should initialize the data
directory and create the MySQL grant tables. On all platforms, an
important security concern is that the initial accounts in the
grant tables have no passwords. You should assign passwords to
prevent unauthorized access to the MySQL server. Optionally, you
can create time zone tables to enable recognition of named time
zones.
The following sections include post-installation procedures that
are specific to Windows systems and to Unix systems. Another
section, Section 2.10.2.3, “Starting and Troubleshooting the MySQL Server”, applies to all
platforms; it describes what to do if you have trouble getting the
server to start. Section 2.10.3, “Securing the Initial MySQL Accounts”, also
applies to all platforms. You should follow its instructions to
make sure that you have properly protected your MySQL accounts by
assigning passwords to them.
On Windows, the data directory and the grant tables do not have
to be created. MySQL Windows distributions include the grant
tables with a set of preinitialized accounts in the
mysql database under the data directory. It
is unnecessary to run the mysql_install_db
script that is used on Unix. Regarding passwords, if you
installed MySQL using the Windows Installation Wizard, you may
have already assigned passwords to the accounts. (See
Section 2.3.3, “Using the MySQL Installation Wizard”.) Otherwise, use the
password-assignment procedure given in
Section 2.10.3, “Securing the Initial MySQL Accounts”.
Before setting up passwords, you might want to try running some
client programs to make sure that you can connect to the server
and that it is operating properly. Make sure that the server is
running (see Section 2.3.9, “Starting the Server for the First Time”), and
then issue the following commands to verify that you can
retrieve information from the server. The output should be
similar to what is shown here:
C:\> C:\mysql\bin\mysqlshow
+-----------+
| Databases |
+-----------+
| mysql |
| test |
+-----------+
C:\> C:\mysql\bin\mysqlshow mysql
Database: mysql
+---------------------------+
| Tables |
+---------------------------+
| columns_priv |
| db |
| func |
| help_category |
| help_keyword |
| help_relation |
| help_topic |
| host |
| proc |
| procs_priv |
| tables_priv |
| time_zone |
| time_zone_leap_second |
| time_zone_name |
| time_zone_transition |
| time_zone_transition_type |
| user |
+---------------------------+
C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql
+------+-------+------+
| host | db | user |
+------+-------+------+
| % | test% | |
+------+-------+------+
After installing MySQL on Unix, you need to initialize the grant
tables, start the server, and make sure that the server works
satisfactorily. You may also wish to arrange for the server to
be started and stopped automatically when your system starts and
stops. You should also assign passwords to the accounts in the
grant tables.
On Unix, the grant tables are set up by the
mysql_install_db program. For some
installation methods, this program is run for you automatically:
If you install MySQL on Linux using RPM distributions, the
server RPM runs mysql_install_db.
If you install MySQL on Mac OS X using a PKG distribution,
the installer runs mysql_install_db.
Otherwise, you will need to run
mysql_install_db yourself.
The following procedure describes how to initialize the grant
tables (if that has not previously been done) and then start the
server. It also suggests some commands that you can use to test
whether the server is accessible and working properly. For
information about starting and stopping the server
automatically, see Section 2.10.2.2, “Starting and Stopping MySQL Automatically”.
After you complete the procedure and have the server running,
you should assign passwords to the accounts created by
mysql_install_db. Instructions for doing so
are given in Section 2.10.3, “Securing the Initial MySQL Accounts”.
In the examples shown here, the server runs under the user ID of
the mysql login account. This assumes that
such an account exists. Either create the account if it does not
exist, or substitute the name of a different existing login
account that you plan to use for running the server.
Change location into the top-level directory of your MySQL
installation, represented here by
BASEDIR:
shell> cd BASEDIR
BASEDIR is likely to be something
like /usr/local/mysql or
/usr/local. The following steps assume
that you are located in this directory.
If necessary, run the mysql_install_db
program to set up the initial MySQL grant tables containing
the privileges that determine how users are allowed to
connect to the server. You'll need to do this if you used a
distribution type for which the installation procedure
doesn't run the program for you.
Typically, mysql_install_db needs to be
run only the first time you install MySQL, so you can skip
this step if you are upgrading an existing installation,
However, mysql_install_db does not
overwrite any existing privilege tables, so it should be
safe to run in any circumstances.
To initialize the grant tables, use one of the following
commands, depending on whether
mysql_install_db is located in the
bin or scripts
directory:
The mysql_install_db script creates the
server's data directory. Under the data directory, it
creates directories for 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 and anonymous-user accounts. The
accounts have no passwords initially. A description of their
initial privileges is given in
Section 2.10.3, “Securing the Initial MySQL Accounts”. 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_.
It is important to make sure that the database directories
and files are owned by the mysql login
account so that the server has read and write access to them
when you run it later. To ensure this, the
--user option should be used as shown if
you run mysql_install_db as
root. Otherwise, you should execute the
script while logged in as mysql, in which
case you can omit the --user option from
the command.
mysql_install_db creates several tables
in the mysql database, including
user, db,
host, tables_priv,
columns_priv, func,
and others. See Section 5.8, “The MySQL Access Privilege System”, for a
complete listing and description of these tables.
If you don't want to have the test
database, you can remove it with mysqladmin -u root
drop test after starting the server.
It is important that the MySQL server be run using an
unprivileged (non-root) login account. To
ensure this, the --user option should be
used as shown if you run mysql_safe as
system root. Otherwise, you should
execute the script while logged in to the system as
mysql, in which case you can omit the
--user option from the command.
If you neglected to create the grant tables before
proceeding to this step, the following message appears in
the error log file when you start the server:
Use mysqladmin to verify that the server
is running. The following commands provide simple tests to
check whether the server is up and responding to
connections:
shell> bin/mysqladmin version
shell> bin/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> bin/mysqladmin version
mysqladmin Ver 14.12 Distrib 5.0.25, for pc-linux-gnu on i686
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 5.0.25-Max
Protocol version 10
Connection Localhost via UNIX socket
UNIX socket /var/lib/mysql/mysql.sock
Uptime: 14 days 5 hours 5 min 21 sec
Threads: 1 Questions: 366 Slow queries: 0
Opens: 0 Flush tables: 1 Open tables: 19
Queries per second avg: 0.000
To see what else you can do with
mysqladmin, invoke it with the
--help option.
Verify that you can shut down the server:
shell> bin/mysqladmin -u root shutdown
Verify that you can start the server again. Do this by using
mysqld_safe or by invoking
mysqld directly. For example:
Run some simple tests to verify that you can retrieve
information from the server. The output should be similar to
what is shown here:
shell> bin/mysqlshow
+-----------+
| Databases |
+-----------+
| mysql |
| test |
+-----------+
shell> bin/mysqlshow mysql
Database: mysql
+---------------------------+
| Tables |
+---------------------------+
| columns_priv |
| db |
| func |
| help_category |
| help_keyword |
| help_relation |
| help_topic |
| host |
| proc |
| procs_priv |
| tables_priv |
| time_zone |
| time_zone_leap_second |
| time_zone_name |
| time_zone_transition |
| time_zone_transition_type |
| user |
+---------------------------+
shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql
+------+--------+------+
| host | db | user |
+------+--------+------+
| % | test | |
| % | test_% | |
+------+--------+------+
There is 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 requires the Perl DBI module that
provides a database-independent interface to the various
databases, and some other additional Perl modules:
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> perl 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. 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, execute this
command from the top-level directory of your source
distribution:
shell> mysql -vvf test < ./tests/auto_increment.tst
The expected result of the test can be found in the
./tests/auto_increment.res file.
At this point, you should have the server running. However,
none of the initial MySQL accounts have a password, so you
should assign passwords using the instructions found in
Section 2.10.3, “Securing the Initial MySQL Accounts”.
The MySQL 5.0 installation procedure creates time
zone tables in the mysql database. However,
you must populate the tables manually using the instructions in
Section 5.11.8, “MySQL Server Time Zone Support”.
2.10.2.1. Problems Running mysql_install_db
The purpose of the mysql_install_db script
is to generate new MySQL privilege tables. It does not
overwrite existing MySQL privilege tables, and it does not
affect any other data.
If you want to re-create your privilege tables, first stop the
mysqld server if it's running. Then rename
the mysql directory under the data
directory to save it, and then run
mysql_install_db. Suppose that your current
directory is the MySQL installation directory and that
mysql_install_db is located in the
bin directory and the data directory is
named data. To rename the
mysql database and re-run
mysql_install_db, use these commands.
When you run mysql_install_db, you might
encounter the following problems:
mysql_install_db
fails to 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 ended
In this case, you should examine the error 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 do not understand what happened, include the
log when you post a bug report. See
Section 1.8, “How to Report Bugs or Problems”.
There is a mysqld
process running
This indicates that the server is running, in which case
the grant tables have probably been created already. If
so, there is no need to run
mysql_install_db at all because it
needs to be run only once (when you install MySQL the
first time).
Installing a second
mysqld server does not work when one
server is running
This can happen when you have an existing MySQL
installation, but want to put a new installation in a
different location. For example, you might have a
production installation, but you want to create a second
installation for testing purposes. Generally the problem
that occurs when you try to run a second server is that it
tries to use a network interface that is in use by the
first server. In this case, you should see one of the
following error messages:
Can't start server: Bind on TCP/IP port:
Address already in use
Can't start server: Bind on unix socket...
You do not have write access to the
/tmp directory
If you do not have write access to create temporary files
or a Unix socket file in the default location (the
/tmp directory), an error occurs when
you run mysql_install_db or the
mysqld server.
You can specify different locations for the temporary
directory and Unix socket file by executing these commands
prior to starting mysql_install_db or
mysqld, where
some_tmp_dir is the full
pathname to some directory for which you have write
permission:
There are some alternatives to running the
mysql_install_db script provided in the
MySQL distribution:
If you want the initial privileges to be different from
the standard defaults, you can modify
mysql_install_db before you run it.
However, it is preferable to use GRANT
and REVOKE to change the privileges
after the grant tables have been set
up. In other words, you can run
mysql_install_db, and then use
mysql -u root mysql to connect to the
server as the MySQL root user so that
you can issue the necessary GRANT and
REVOKE statements.
If you want to install MySQL on several machines with the
same privileges, you can put the GRANT
and REVOKE statements in a file and
execute the file as a script using
mysql after running
mysql_install_db. For example:
By doing this, you can avoid having to issue the
statements manually on each machine.
It is possible to re-create the grant tables completely
after they have previously been created. You might want to
do this if you're just learning how to use
GRANT and REVOKE and
have made so many modifications after running
mysql_install_db that you want to wipe
out the tables and start over.
To re-create the grant tables, remove all the
.frm, .MYI, and
.MYD files in the
mysql database directory. Then run the
mysql_install_db script again.
You can start mysqld manually using the
--skip-grant-tables option and add the
privilege information yourself using
mysql:
shell> bin/mysqld_safe --user=mysql --skip-grant-tables &
shell> bin/mysql mysql
From mysql, manually execute the SQL
commands contained in mysql_install_db.
Make sure that you run mysqladmin
flush-privileges or mysqladmin
reload afterward to tell the server to reload
the grant tables.
Note that by not using
mysql_install_db, you not only have to
populate the grant tables manually, you also have to
create them first.
2.10.2.2. Starting and Stopping MySQL Automatically
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 versions of Windows that support services (such
as NT, 2000, XP, and 2003). The service can be set to
start the server automatically when Windows starts, or as
a manual service that you start on request. For
instructions, see Section 2.3.11, “Starting MySQL as a Windows Service”.
By invoking mysql.server. This script
is used primarily at system startup and shutdown on
systems that use System V-style run directories, where it
usually is installed under the name
mysql. The
mysql.server script starts the server
by invoking mysqld_safe. See
Section 5.4.2, “mysql.server — MySQL Server Startup Script”.
On Mac OS X, you can install a separate MySQL Startup Item
package to enable the automatic startup of MySQL on system
startup. The Startup Item starts the server by invoking
mysql.server. See
Section 2.5, “Installing MySQL on Mac OS X”, for details.
The mysqld_safe and
mysql.server scripts and the Mac OS X
Startup Item can be used to start the server manually, or
automatically at system startup time.
mysql.server and the Startup Item also can
be used to stop the server.
To start or stop the server manually using the
mysql.server script, invoke it with
start or stop arguments:
Before mysql.server starts the server, it
changes location to the MySQL installation directory, and then
invokes mysqld_safe. If you want the server
to run as some specific user, add an appropriate
user option to the
[mysqld] group of the
/etc/my.cnf option file, as shown later
in this section. (It is possible that you will need to edit
mysql.server if you've installed a binary
distribution of MySQL in a non-standard location. Modify it to
cd into the proper directory before it runs
mysqld_safe. If you do this, your modified
version of mysql.server may be overwritten
if you upgrade MySQL in the future, so you should make a copy
of your edited version that you can reinstall.)
mysql.server stop stops the server by
sending a signal to it. You can also stop the server manually
by executing mysqladmin shutdown.
To start and stop MySQL automatically on your server, you need
to add start and stop commands to the appropriate places in
your /etc/rc* files.
If you use the Linux server RPM package
(MySQL-server-VERSION.rpm),
the mysql.server script is installed in the
/etc/init.d directory with the name
mysql. You need not install it manually.
See Section 2.4, “Installing MySQL on Linux”, for more information on the
Linux RPM packages.
Some vendors provide RPM packages that install a startup
script under a different name such as
mysqld.
If you install MySQL from a source distribution or using a
binary distribution format that does not install
mysql.server automatically, you can install
it manually. The script can be found in the
support-files directory under the MySQL
installation directory or in a MySQL source tree.
To install mysql.server manually, copy it
to the /etc/init.d directory with the
name mysql, and then make it executable. Do
this by changing location into the appropriate directory where
mysql.server is located and executing these
commands:
Older Red Hat systems use the
/etc/rc.d/init.d directory rather than
/etc/init.d. Adjust the preceding
commands accordingly. Alternatively, first create
/etc/init.d as a symbolic link that
points to /etc/rc.d/init.d:
shell> cd /etc
shell> ln -s rc.d/init.d .
After installing the script, the commands needed to activate
it to run at system startup depend on your operating system.
On Linux, you can use chkconfig:
shell> chkconfig --add mysql
On some Linux systems, the following command also seems to be
necessary to fully enable the mysql script:
shell> chkconfig --level 345 mysql on
On FreeBSD, startup scripts generally should go in
/usr/local/etc/rc.d/. The
rc(8) manual page states that scripts in
this directory are executed only if their basename matches the
*.sh shell filename pattern. Any other
files or directories present within the directory are silently
ignored. In other words, on FreeBSD, you should install the
mysql.server script as
/usr/local/etc/rc.d/mysql.server.sh to
enable automatic startup.
As an alternative to the preceding setup, some operating
systems also use /etc/rc.local or
/etc/init.d/boot.local to start
additional services on startup. To start up MySQL using this
method, you could append a command like the one following to
the appropriate startup file:
The mysql.server script understands the
following options: basedir,
datadir, and pid-file.
If specified, they must be placed in an
option file, not on the command line.
mysql.server understands only
start and stop as
command-line arguments.
The following table shows which option groups the server and
each startup script read from option files:
Script
Option Groups
mysqld
[mysqld], [server],
[mysqld-major_version]
mysqld_safe
[mysqld], [server],
[mysqld_safe]
mysql.server
[mysqld], [mysql.server],
[server]
[mysqld-major_version]
means that groups with names like
[mysqld-4.1] and
[mysqld-5.0] are read by
servers having versions 4.1.x,
5.0.x, and so forth. This feature can be used to
specify options that can be read only by servers within a
given release series.
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 when using
MySQL 5.0.
If you have problems starting the server, here are some things
to try:
Check the error log to see why the server does not start.
Specify any special options needed by the storage engines
you are using.
Make sure that the server knows where to find the data
directory.
Make sure that the server can access the data directory.
The ownership and permissions of the data directory and
its contents must be set such that the server can read and
modify them.
Verify that the network interfaces the server wants to use
are available.
Some storage engines have options that control their behavior.
You can create a my.cnf file and specify
startup options for the engines that you plan to use. If you
are going to use storage engines that support transactional
tables (InnoDB, BDB,
NDB), be sure that you have them configured
the way you want before starting the server:
Storage engines will use default option values if you specify
none, but it is recommended that you review the available
options and specify explicit values for those for which the
defaults are not appropriate for your installation.
When the mysqld server starts, it changes
location to the data directory. This is where it expects to
find databases and where it expects to write log files. The
server also writes the pid (process ID) file in the data
directory.
The data directory location is hardwired in when the server is
compiled. This is where the server looks for the data
directory by default. If the data directory is located
somewhere else on your system, the server will not work
properly. You can determine what the default path settings are
by invoking mysqld with the
--verbose and --help
options.
If the default locations don't match the MySQL installation
layout on your system, you can override them by specifying
options to mysqld or
mysqld_safe on the command line or in an
option file.
To specify the location of the data directory explicitly, use
the --datadir option. However, normally you
can tell mysqld the location of the base
directory under which MySQL is installed and it looks for the
data directory there. You can do this with the
--basedir option.
To check the effect of specifying path options, invoke
mysqld with those options followed by the
--verbose and --help
options. For example, if you change location into the
directory where mysqld is installed and
then run the following command, it shows the effect of
starting the server with a base directory of
/usr/local:
You can specify other options such as
--datadir as well, but
--verbose and --help must be
the last options.
Once you determine the path settings you want, start the
server without --verbose and
--help.
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 host_name variables
host_name is the name of the MySQL
server host.
If you get Errcode 13 (which means
Permission denied) when starting
mysqld, this means that the privileges of
the data directory or its contents do not allow the server
access. In this case, you change the permissions for the
involved files and directories so that the server has the
right to use them. You can also start the server as
root, but this raises security issues and
should be avoided.
On Unix, change location into the data directory and check the
ownership of the data directory and its contents to make sure
the server has access. For example, if the data directory is
/usr/local/mysql/var, use this command:
shell> ls -la /usr/local/mysql/var
If the data directory or its files or subdirectories are not
owned by the login account that you use for running the
server, change their ownership to that account. If the account
is named mysql, use these commands:
shell> chown -R mysql /usr/local/mysql/var
shell> chgrp -R mysql /usr/local/mysql/var
If the server fails to start up correctly, check the error
log. Log files are located in the data directory (typically
C:\Program Files\MySQL\MySQL Server
5.0\data on Windows,
/usr/local/mysql/data for a Unix binary
distribution, and /usr/local/var for a
Unix source distribution). Look in the data directory for
files with names of the form
host_name.err
and
host_name.log,
where host_name is the name of your
server host. Then examine the last few lines of these files.
On Unix, you can use tail to display them:
The error log should contain information that indicates why
the server couldn't start. For example, you might see
something like this in the log:
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 did not start mysqld
with the --bdb-no-recover option and Berkeley
DB found something wrong with its own log files when it tried
to recover your databases. To be able to continue, you should
move the old Berkeley DB log files from the database directory
to some other place, where you can later examine them. The
BDB log files are named in sequence
beginning with log.0000000001, where the
number increases over time.
If you are running mysqld with
BDB table support and
mysqld dumps core at startup, this could be
due to problems with the BDB recovery log.
In this case, you can try starting mysqld
with --bdb-no-recover. If that helps, you
should remove all BDB log files from the
data directory and try starting mysqld
again without the --bdb-no-recover option.
If either of the following errors occur, it means that some
other program (perhaps another mysqld
server) is using the TCP/IP port or Unix socket file that
mysqld is trying to use:
Can't start server: Bind on TCP/IP port: Address already in use
Can't start server: Bind on unix socket...
Use ps to determine whether you have
another mysqld server running. If so, shut
down the server before starting mysqld
again. (If another server is running, and you really want to
run multiple servers, you can find information about how to do
so in Section 5.13, “Running Multiple MySQL Servers on the Same Machine”.)
If no other server is running, try to execute the command
telnet your_host_nametcp_ip_port_number. (The
default MySQL port number is 3306.) Then press Enter a couple
of times. If you don't get an error message like
telnet: Unable to connect to remote host: Connection
refused, some other program is using the TCP/IP port
that mysqld is trying to use. You'll need
to track down what program this is and disable it, or else
tell mysqld to listen to a different port
with the --port option. In this case, you'll
also need to specify the port number for client programs when
connecting to the server via TCP/IP.
Another reason the port might be inaccessible is that you have
a firewall running that blocks connections to it. If so,
modify the firewall settings to allow access to the port.
If the server starts but you can't connect to it, you should
make sure that you have an entry in
/etc/hosts that looks like this:
127.0.0.1 localhost
This problem occurs only on systems that do not have a working
thread library and for which MySQL must be configured to use
MIT-pthreads.
If you cannot get mysqld to start, you can
try to make a trace file to find the problem by using the
--debug option. See
Section E.1.2, “Creating Trace Files”.
2.10.3. Securing the Initial MySQL Accounts
Part of the MySQL installation process is to set up the
mysql database that contains the grant
tables:
Windows distributions contain preinitialized grant tables
that are installed automatically.
On Unix, the grant tables are populated by the
mysql_install_db program. Some
installation methods run this program for you. Others
require that you execute it manually. For details, see
Section 2.10.2, “Unix Post-Installation Procedures”.
The grant tables define the initial MySQL user accounts and
their access privileges. These accounts are set up as follows:
Accounts with the username root are
created. These are superuser accounts that can do anything.
The initial root account passwords are
empty, so anyone can connect to the MySQL server as
root — without a
password — and be granted all privileges.
On Windows, one root account is
created; this account allows connecting from the local
host only. The Windows installer will optionally create
an account allowing for connections from any host only
if the user selects the Enable root access
from remote machines option during
installation.
On Unix, both root accounts are for
connections from the local host. Connections must be
made from the local host by specifying a hostname of
localhost for one of the accounts, or
the actual hostname or IP number for the other.
Two anonymous-user accounts are created, each with an empty
username. The anonymous accounts have no password, so anyone
can use them to connect to the MySQL server.
On Windows, one anonymous account is for connections
from the local host. It has all privileges, just like
the root accounts. The other is for
connections from any host and has all privileges for the
test database and for other databases
with names that start with test.
On Unix, both anonymous accounts are for connections
from the local host. Connections must be made from the
local host by specifying a hostname of
localhost for one of the accounts, or
the actual hostname or IP number for the other. These
accounts have all privileges for the
test database and for other databases
with names that start with test_.
As noted, none of the initial accounts have passwords. This
means that your MySQL installation is unprotected until you do
something about it:
If you want to prevent clients from connecting as anonymous
users without a password, you should either assign a
password to each anonymous account or else remove the
accounts.
You should assign a password to each MySQL
root account.
The following instructions describe how to set up passwords for
the initial MySQL accounts, first for the anonymous accounts and
then for the root accounts. Replace
“newpwd” in the examples
with the actual password that you want to use. The instructions
also cover how to remove the anonymous accounts, should you
prefer not to allow anonymous access at all.
You might want to defer setting the passwords until later, so
that you don't need to specify them while you perform additional
setup or testing. However, be sure to set them before using your
installation for production purposes.
Anonymous Account Password
Assignment
To assign passwords to the anonymous accounts, connect to the
server as root and then use either
SET PASSWORD or UPDATE. In
either case, be sure to encrypt the password using the
PASSWORD() function.
To use SET PASSWORD on Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');
To use SET PASSWORD on Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace
host_name with the name of the server
host. This is the name that is specified in the
Host column of the
non-localhost record for
root in the user table. If
you don't know what hostname this is, issue the following
statement before using SET PASSWORD:
mysql> SELECT Host, User FROM mysql.user;
Look for the record that has root in the
User column and something other than
localhost in the Host
column. Then use that Host value in the
second SET PASSWORD statement.
The other way to assign passwords to the anonymous accounts is
by using UPDATE to modify the
user table directly. Connect to the server as
root and issue an UPDATE
statement that assigns a value to the
Password column of the appropriate
user table records. The procedure is the same
for Windows and Unix. The following UPDATE
statement assigns a password to both anonymous accounts at once:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
-> WHERE User = '';
mysql> FLUSH PRIVILEGES;
After you update the passwords in the user
table directly using UPDATE, you must tell
the server to re-read the grant tables with FLUSH
PRIVILEGES. Otherwise, the change goes unnoticed until
you restart the server.
Anonymous Account Removal
If you prefer to remove the anonymous accounts instead, do so as
follows:
shell> mysql -u root
mysql> DELETE FROM mysql.user WHERE User = '';
mysql> FLUSH PRIVILEGES;
The DELETE statement applies both to Windows
and to Unix. On Windows, if you want to remove only the
anonymous account that has the same privileges as
root, do this instead:
shell> mysql -u root
mysql> DELETE FROM mysql.user WHERE Host='localhost' AND User='';
mysql> FLUSH PRIVILEGES;
That account allows anonymous access but has full privileges, so
removing it improves security.
root Account Password
Assignment
You can assign passwords to the root accounts
in several ways. The following discussion demonstrates three
methods:
Use the SET PASSWORD statement
Use the mysqladmin command-line client
program
Use the UPDATE statement
To assign passwords using SET PASSWORD,
connect to the server as root and issue two
SET PASSWORD statements. Be sure to encrypt
the password using the PASSWORD() function.
For Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
For Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace
host_name with the name of the server
host. This is the same hostname that you used when you assigned
the anonymous account passwords.
To assign passwords to the root accounts
using mysqladmin, execute the following
commands:
These commands apply both to Windows and to Unix. In the second
command, replace host_name with the
name of the server host. The double quotes around the password
are not always necessary, but you should use them if the
password contains spaces or other characters that are special to
your command interpreter.
You can also use UPDATE to modify the
user table directly. The following
UPDATE statement assigns a password to both
root accounts at once:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
-> WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
The UPDATE statement applies both to Windows
and to Unix.
After the passwords have been set, you must supply the
appropriate password whenever you connect to the server. For
example, if you want to use mysqladmin to
shut down the server, you can do so using this command:
As a general rule, we recommend that when upgrading from one
release series to another, you should go to the next series rather
than skipping a series. For example, if you currently are running
MySQL 3.23 and wish to upgrade to a newer series, upgrade to MySQL
4.0 rather than to 4.1 or 5.0.
The following items form a checklist of things that you should do
whenever you perform an upgrade:
Before upgrading from MySQL 4.1 to
5.0, read Section 2.11.2, “Upgrading from MySQL 4.1 to 5.0”)
as well as Appendix D, MySQL Change History. These provide information
about features that are new in MySQL 5.0 or
differ from those found in MySQL 4.1. If you
wish to upgrade from a release series previous to MySQL
4.1, you should upgrade to each successive
release series in turn until you have reached MySQL
4.1, and then proceed with the upgrade to MySQL
5.0. For information on upgrading from MySQL
4.1 or earlier releases, see the
MySQL 3.23, 4.0, 4.1 Reference Manual.
Before you perform an upgrade, back up your databases,
including the mysql database that contains
the grant tables.
Some releases of MySQL introduce incompatible changes to
tables. (Our aim is to avoid these changes, but occasionally
they are necessary to correct problems that would be worse
than an incompatibility between releases.) Some releases of
MySQL introduce changes to the structure of the grant tables
to add new privileges or features.
To avoid problems due to such changes, after you upgrade to a
new version of MySQL, you should run
mysql_upgrade to check your tables (and
repair them if necessary), and to update your grant tables to
make sure that they have the current structure so that you can
take advantage of any new capabilities. See
Section 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
If you previously installed a MySQL-Max distribution that
includes a server named mysqld-max, and
then upgrade later to a non-Max version of MySQL,
mysqld_safe still attempts to run the old
mysqld-max server. If you perform such an
upgrade, you should remove the old
mysqld-max server manually to ensure that
mysqld_safe runs the new
mysqld server.
You can always move the MySQL format files and data files between
different versions on the same architecture as long as you stay
within versions for the same release series of MySQL. If you
change the character set when running MySQL, you must run
myisamchk -r -q
--set-collation=collation_name
on all MyISAM tables. Otherwise, your indexes
may not be ordered correctly, because changing the character set
may also change the sort order.
If you are cautious about using new versions, you can always
rename your old mysqld before installing a
newer one. For example, if you are using MySQL
4.1.13 and want to upgrade to 5.0.10,
rename your current server from mysqld to
mysqld-4.1.13. If your new
mysqld then does something unexpected, you can
simply shut it down and restart with your old
mysqld.
If, after an upgrade, you experience problems with recompiled
client programs, such as Commands out of sync
or unexpected core dumps, you probably have used old header or
library files when compiling your programs. In this case, you
should check the date for your mysql.h file
and libmysqlclient.a library to verify that
they are from the new MySQL distribution. If not, recompile your
programs with the new headers and libraries.
If problems occur, such as that the new mysqld
server does not start or that you cannot connect without a
password, verify that you do not have an old
my.cnf file from your previous installation.
You can check this with the --print-defaults
option (for example, mysqld --print-defaults).
If this command displays anything other than the program name, you
have an active my.cnf file that affects
server or client operation.
It is a good idea to rebuild and reinstall the Perl
DBD::mysql module whenever you install a new
release of MySQL. The same applies to other MySQL interfaces as
well, such as the PHP mysql extension and the
Python MySQLdb module.
2.11.1. Upgrading from MySQL 5.0 to 5.1
When upgrading a 5.0 installation to
5.0.10 or above note that it is
necessary to upgrade your grant tables.
Otherwise, creating stored procedures and functions might not
work. The procedure for doing this is described in
Section 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
2.11.2. Upgrading from MySQL 4.1 to 5.0
Note: It is good practice to
back up your data before installing any new version of software.
Although MySQL works very hard to ensure a high level of
quality, you should protect your data by making a backup. MySQL
generally recommends that you dump and reload your tables from
any previous version to upgrade to 5.0.
In general, you should do the following when upgrading from
MySQL 4.1 from 5.0:
Check the items in the change lists found later in this
section to see whether any of them might affect your
applications. Note particularly any that are marked
Incompatible change. These
result in incompatibilities with earlier versions of MySQL,
and may require your attention before you
upgrade.
Some releases of MySQL introduce incompatible changes to
tables. (Our aim is to avoid these changes, but occasionally
they are necessary to correct problems that would be worse
than an incompatibility between releases.) Some releases of
MySQL introduce changes to the structure of the grant tables
to add new privileges or features.
To avoid problems due to such changes, after you upgrade to
a new version of MySQL, you should check your tables (and
repair them if necessary), and update your grant tables to
make sure that they have the current structure so that you
can take advantage of any new capabilities. See
Section 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
MySQL 5.0 adds support for views. This support
requires extra privilege columns in the
mysql.user and
mysql.db tables. To create these columns,
you should run the mysql_upgrade program
as described in Section 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
Several visible behaviors have changed between MySQL
4.1 and MySQL 5.0 to make MySQL more
compatible with standard SQL. These changes may affect your
applications.
The following lists describe changes that may affect
applications and that you should watch out for when upgrading to
MySQL 5.0.
Server Changes:
Incompatible change: The
indexing order for end-space in TEXT
columns for InnoDB and
MyISAM tables has changed. Starting from
5.0.3, TEXT indexes are compared as
space-padded at the end (just as MySQL sorts
CHAR, VARCHAR and
TEXT fields). If you have a index on a
TEXT column, you should run
CHECK TABLE on it. If the check reports
errors, rebuild the indexes: Dump and reload the table if it
is an InnoDB table, or run
OPTIMIZE TABLE or REPAIR
TABLE if it is a MyISAM table.
Warning: Incompatible
change. For BINARY columns,
the pad value and how it is handled has changed as of MySQL
5.0.15. The pad value for inserts now is
0x00 rather than space, and there is no
stripping of the pad value for retrievals. For details, see
Section 11.4.2, “The BINARY and VARBINARY Types”.
Incompatible change: As of
MySQL 5.0.3, the server by default no longer loads
user-defined functions (UDFs) unless they have at least one
auxiliary symbol (for example, an
xxx_init or xxx_deinit
symbol) defined in addition to the main function symbol.
This behavior can be overridden with the
--allow-suspicious-udfs option. See
Section 24.2.4.6, “User-Defined Function Security Precautions”.
Incompatible change: The
update log has been removed in MySQL 5.0. If you had enabled
it previously, you should enable the binary log instead.
Incompatible change:
Support for the ISAM storage engine has
been removed in MySQL 5.0. If you have any
ISAM tables, you should convert them
before upgrading. For example, to
convert an ISAM table to use the
MyISAM storage engine, use this
statement:
ALTER TABLE tbl_name ENGINE = MyISAM;
Use a similar statement for every ISAM
table in each of your databases.
Incompatible change:
Support for RAID options in
MyISAM tables has been removed in MySQL
5.0. If you have tables that use these options, you should
convert them before upgrading. One way to do this is to dump
them with mysqldump, edit the dump file
to remove the RAID options in the
CREATE TABLE statements, and reload the
dump file. Another possibility is to use CREATE
TABLE new_tbl ... SELECT
raid_tbl to create a
new table from the RAID table. However,
the CREATE TABLE part of the statement
must contain sufficient information to re-create column
attributes as well as indexes, or column attributes may be
lost and indexes will not appear in the new table. See
Section 13.1.5, “CREATE TABLE Syntax”.
The .MYD files for
RAID tables in a given database are
stored under the database directory in subdirectories that
have names consisting of two hex digits in the range from
00 to ff. After
converting all tables that use RAID
options, these RAID-related
subdirectories still will exist but can be removed. Verify
that they are empty, and then remove them manually. (If they
are not empty, there is some RAID table
that has not been converted.)
Incompatible change:
Beginning with MySQL 5.0.12, natural joins and joins with
USING, including outer join variants, are
processed according to the SQL:2003 standard. The changes
include elimination of redundant output columns for
NATURAL joins and joins specified with a
USING clause and proper ordering of
output columns. The precedence of the comma operator also
now is lower compared to JOIN,
LEFT JOIN, and so forth.
These changes make MySQL more compliant with standard SQL.
However, they can result in different output columns for
some joins. Also, some queries that appeared to work
correctly prior to 5.0.12 must be rewritten to comply with
the standard. For details about the scope of the changes and
examples that show what query rewrites are necessary, see
Section 13.2.7.1, “JOIN Syntax”.
Incompatible change:
Previously, a lock wait timeout caused
InnoDB to roll back the entire current
transaction. As of MySQL 5.0.13, it rolls back only the most
recent SQL statement.
Incompatible change: The
namespace for triggers has changed in MySQL 5.0.10.
Previously, trigger names had to be unique per table. Now
they must be unique within the schema (database). An
implication of this change is that DROP
TRIGGER syntax now uses a schema name instead of a
table name (schema name is optional and, if omitted, the
current schema will be used).
When upgrading from a previous version of MySQL 5 to MySQL
5.0.10 or newer, you must drop all triggers and re-create
them or DROP TRIGGER will not work after
the upgrade. Here is a suggested procedure for doing this:
Upgrade to MySQL 5.0.10 or later to be able to access
trigger information in the
INFORMATION_SCHEMA.TRIGGERS table.
(It should work even for pre-5.0.10 triggers.)
Dump all trigger definitions using the following
SELECT statement:
SELECT CONCAT('CREATE TRIGGER ', t.TRIGGER_SCHEMA, '.', t.TRIGGER_NAME,
' ', t.ACTION_TIMING, ' ', t.EVENT_MANIPULATION, ' ON ',
t.EVENT_OBJECT_SCHEMA, '.', t.EVENT_OBJECT_TABLE,
' FOR EACH ROW ', t.ACTION_STATEMENT, '//' )
INTO OUTFILE '/tmp/triggers.sql'
FROM INFORMATION_SCHEMA.TRIGGERS AS t;
The statement uses INTO OUTFILE, so
you must have the FILE privilege. The
file will be created on the server host. Use a different
filename if you like. To be 100% safe, inspect the
trigger definitions in the
triggers.sql file, and perhaps make
a backup of the file.
Stop the server and drop all triggers by removing all
.TRG files in your database
directories. Change location to your data directory and
issue this command:
shell> rm */*.TRG
Start the server and re-create all triggers using the
triggers.sql file. For the file
created earlier, use these commands in the
mysql program:
Use the SHOW TRIGGERS statement to
check that all triggers were created successfully.
Incompatible change: As of
MySQL 5.0.15, the CHAR() function returns
a binary string rather than a string in the connection
character set. An optional USING
charset_name clause may
be used to produce a result in a specific character set
instead. Also, arguments larger than 256 produce multiple
characters. They are no longer interpreted modulo 256 to
produce a single character each. These changes may cause
some incompatibilities:
To perform a case-insensitive comparison, you can
produce a result string in a non-binary character set by
adding a USING clause or converting
the result:
mysql> SELECT CHAR(ORD('A') USING latin1) = 'a';
+-----------------------------------+
| CHAR(ORD('A') USING latin1) = 'a' |
+-----------------------------------+
| 1 |
+-----------------------------------+
mysql> SELECT CONVERT(CHAR(ORD('A')) USING latin1) = 'a';
+--------------------------------------------+
| CONVERT(CHAR(ORD('A')) USING latin1) = 'a' |
+--------------------------------------------+
| 1 |
+--------------------------------------------+
CREATE TABLE ... SELECT CHAR(...)
produces a VARBINARY column, not a
VARCHAR column. To produce a
VARCHAR column, use
USING or CONVERT()
as just described to convert the
CHAR() result into a non-binary
character set.
Previously, the following statements inserted the value
0x00410041 ('AA'
as a ucs2 string) into the table:
CREATE TABLE t (ucs2_column CHAR(2) CHARACTER SET ucs2);
INSERT INTO t VALUES (CHAR(0x41,0x41));
As of MySQL 5.0.15, the statements insert a single
ucs2 character with value
0x4141.
Incompatible change: By
default, integer subtraction involving an unsigned value
should produce an unsigned result. Tracking of the
“unsignedness” of an expression was improved in
MySQL 5.0.13. This means that, in some cases where an
unsigned subtraction would have resulted in a signed
integer, it now results in an unsigned integer. One context
in which this difference manifests itself is when a
subtraction involving an unsigned operand would be negative.
Suppose that i is a TINYINT
UNSIGNED column and has a value of 0. The server
evaluates the following expression using 64-bit unsigned
integer arithmetic with the following result:
mysql> SELECT i - 1 FROM t;
+----------------------+
| i - 1 |
+----------------------+
| 18446744073709551615 |
+----------------------+
If the expression is used in an UPDATE t SET i = i
- 1 statement, the expression is evaluated and the
result assigned to i according to the
usual rules for handling values outide the column range or 0
to 255. That is, the value is clipped to the nearest
endpoint of the range. However, the result is
version-specific:
Before MySQL 5.0.13, the expression is evaluated but is
treated as the equivalent 64-bit signed value (–1)
for the assignment. The value of –1 is clipped to
the nearest endpoint of the column range, resulting in a
value of 0:
mysql> UPDATE t SET i = i - 1; SELECT i FROM t;
+------+
| i |
+------+
| 0 |
+------+
As of MySQL 5.0.13, the expression is evaluated and
retains its unsigned attribute for the assignment. The
value of 18446744073709551615 is clipped to the nearest
endpoint of the column range, resulting in a value of
255:
mysql> UPDATE t SET i = i - 1; SELECT i FROM t;
+------+
| i |
+------+
| 255 |
+------+
To get the older behavior, use CAST() to
convert the expression result to a signed value:
UPDATE t SET i = CAST(i - 1 AS SIGNED);
Alternatively, set the
NO_UNSIGNED_SUBTRACTION SQL mode.
However, this will affect all integer subtractions involving
unsigned values.
Incompatible change: Before
MySQL 5.0.13, NOW() and
SYSDATE() return the same value (the time
at which the statement in which the function occurs begins
executing). As of MySQL 5.0.13, SYSDATE()
returns the time at which it it executes, which can differ
from the value returned by NOW(). For
information about the implications for binary logging and
replication, see the description for
SYSDATE() in
Section 12.5, “Date and Time Functions” and for
SET TIMESTAMP in
Section 13.5.3, “SET Syntax”. To restore the former behavior
for SYSDATE() and cause it to be an alias
for NOW(), start the server with the
--sysdate-is-now option (available as of
MySQL 5.0.20).
Incompatible change: Before
MySQL 5.0.13,
GREATEST(x,NULL)
and
LEAST(x,NULL)
return x when
x is a
non-NULL value. As of 5.0.3, both
functions return NULL if any argument is
NULL, the same as Oracle. This change can
cause problems for applications that rely on the old
behavior.
Incompatible change: Before
MySQL 4.1.13/5.0.8, conversion of
DATETIME values to numeric form by adding
zero produced a result in YYYYMMDDHHMMSS
format. The result of DATETIME+0 is now
in YYYYMMDDHHMMSS.000000 format.
Incompatible change: In
MySQL 4.1.12/5.0.6, the behavior of LOAD DATA
INFILE and SELECT ... INTO
OUTFILE has changed when the FIELDS
TERMINATED BY and FIELDS ENCLOSED
BY values both are empty. Formerly, a column was
read or written the display width of the column. For
example, INT(4) was read or written using
a field with a width of 4. Now columns are read and written
using a field width wide enough to hold all values in the
field. However, data files written before this change was
made might not be reloaded correctly with LOAD DATA
INFILE for MySQL 4.1.12/5.0.6 and up. This change
also affects data files read by
mysqlimport and written by
mysqldump --tab, which use LOAD
DATA INFILE and SELECT ... INTO
OUTFILE. For more information, see
Section 13.2.5, “LOAD DATA INFILE Syntax”.
Incompatible change: The
implementation of DECIMAL has changed in
MySQL 5.0.3. You should make your applications aware of this
change. For information about this change, and about
possible incompatibilities with old applications, see
Chapter 21, Precision Math.
DECIMAL columns are stored in a more
efficient format. To convert a table to use the new
DECIMAL type, you should do an
ALTER TABLE on it. (The ALTER
TABLE also will change the table's
VARCHAR columns to use the new
VARCHAR data type properties, described
in a separate item.)
A consequence of the change in handling of the
DECIMAL and NUMERIC
fixed-point data types is that the server is more strict to
follow standard SQL. For example, a data type of
DECIMAL(3,1) stores a maximum value of
99.9. Before MySQL 5.0.3, the server allowed larger numbers
to be stored. That is, it stored a value such as 100.0 as
100.0. As of MySQL 5.0.3, the server clips 100.0 to the
maximum allowable value of 99.9. If you have tables that
were created before MySQL 5.0.3 and that contain
floating-point data not strictly legal for the data type,
you should alter the data types of those columns. For
example:
ALTER TABLE tbl_name MODIFY col_name DECIMAL(4,1);
The behavior used by the server for
DECIMAL columns in a table depends on the
version of MySQL used to create the table. If your server is
from MySQL 5.0.3 or higher, but you have
DECIMAL columns in tables that were
created before 5.0.3, the old behavior still applies to
those columns. To convert the tables to the newer
DECIMAL format, dump them with
mysqldump and reload them.
Incompatible change: MySQL
5.0.3 and up uses precision math when calculating with
DECIMAL and integer columns (64 decimal
digits) and for rounding exact-value numbers. Rounding
behavior is well-defined, not dependent on the
implementation of the underlying C library. However, this
might result in incompatibilities for applications that rely
on the old behavior. (For example, inserting .5 into an
INT column results in 1 as of MySQL
5.0.3, but might be 0 in older versions.) For more
information about rounding behavior, see
Section 21.4, “Rounding Behavior”, and
Section 21.5, “Precision Math Examples”.
Incompatible change:
MyISAM and InnoDB
tables created with DECIMAL columns in
MySQL 5.0.3 to 5.0.5 will appear corrupt after an upgrade to
MySQL 5.0.6. (The same incompatibility will occur for these
tables created in MySQL 5.0.6 after a downgrade to MySQL
5.0.3 to 5.0.5.) If you have such tables, check and repair
them with mysql_upgrade after upgrading.
See Section 5.6.2, “mysql_upgrade — Check Tables for MySQL Upgrade”.
Incompatible change: Before
MySQL 5.0.2, SHOW STATUS returned global
status values. The default as of 5.0.2 is to return session
values, which is incompatible with previous versions. To
issue a SHOW STATUS statement that will
retrieve global status values for all versions of MySQL,
write it like this:
SHOW /*!50002 GLOBAL */ STATUS;
Incompatible change: User
variables are not case sensitive in MySQL 5.0.
In MySQL 4.1, SET @x = 0; SET @X = 1; SELECT
@x; created two variables and returned
0. In MySQL 5.0, it creates
one variable and returns 1. Replication
setups that rely on the old behavior may be affected by this
change.
As of MySQL 5.0.3, trailing spaces no longer are removed
from values stored in VARCHAR and
VARBINARY columns. The maximum lengths
for VARCHAR and
VARBINARY columns in MySQL 5.0.3 and
later are 65,535 characters and 65,535 bytes, respectively.
When a binary upgrade (filesystem-level copy of data files)
to MySQL 5.0 is performed for a table with a
VARBINARY column, the column is
space-padded to the full allowable width of the column. This
causes values in VARBINARY columns that
do not occupy the full width of the column to include extra
trailing spaces after the upgrade, which means that the data
in the column is different.
In addition, new rows inserted into a table upgraded in this
way will be space padded to the full width of the column.
This issue can be resolved as follows:
For each table containing VARBINARY
columns, execute the statement
ALTER TABLE table_name ENGINE=engine_name;
where table_name is the name
of the table and engine_name
is the name of the storage engine currently used by
table_name. In other words,
if the table named mytable uses the
MyISAM storage engine, then you would
use this statement:
ALTER TABLE mytable ENGINE=MYISAM;
This rebuilds the table so that it uses the 5.0
VARBINARY format.
Then you must remove all trailing spaces from any
VARBINARY column values. For each
VARBINARY column
varbinary_column, you should
perform the following statement (where
table_name is the name of the
table containing the VARBINARY
column):
UPDATE table_name SET varbinary_column = RTRIM(varbinary_column);
This is necessary and safe because trailing spaces are
stripped before 5.0.3, meaning that any trailing spaces
are erroneous.
This problem does not occur (and thus these two steps are
not required) for tables upgraded using the recommended
procedure of dumping tables prior to the upgrade and
reloading them afterwards.
Note: If you create a table
with new VARCHAR or
VARBINARY columns in MySQL 5.0.3 or
later, the table will not be usable if you downgrade to a
version older than 5.0.3. Dump the table with
mysqldump before downgrading and reload
it after downgrading.
Comparisons made between FLOAT or
DOUBLE values that happened to work in
MySQL 4.1 may not do so in 5.0. Values of these types are
imprecise in all MySQL versions, and you are
strongly advised to avoid such
comparisons as WHERE
col_name=some_double,
regardless of the MySQL version you are
using. See Section A.5.8, “Problems with Floating-Point Comparisons”.
MySQL 5.0.2 adds several SQL modes that allow stricter
control over rejecting records that have invalid or missing
values. See Section 5.2.5, “The Server SQL Mode”, and
Section 1.9.6.2, “Constraints on Invalid Data”. If you want to
enable this control but continue to use MySQL's capability
for storing incorrect dates such as
'2004-02-31', you should start the server
with
--sql_mode="TRADITIONAL,ALLOW_INVALID_DATES".
As of MySQL 5.0.2, the SCHEMA and
SCHEMAS keywords are accepted as synonyms
for DATABASE and
DATABASES, respectively. (While
“schemata” is grammatically correct and even
appears in some MySQL 5.0 system database and table names,
it cannot be used as a keyword.)
A new startup option named
innodb_table_locks was added that causes
LOCK TABLE to also acquire
InnoDB table locks. This option is
enabled by default. This can cause deadlocks in applications
that use AUTOCOMMIT=1 and LOCK
TABLES. If you application encounters deadlocks
after upgrading, you may need to add
innodb_table_locks=0 to your
my.cnf file.
C API Changes:
Incompatible change:
Because the MySQL 5.0 server has a new implementation of the
DECIMAL data type, a problem may occur if
the server is used by older clients that still are linked
against MySQL 4.1 client libraries. If a client uses the
binary client/server protocol to execute prepared statements
that generate result sets containing numeric values, an
error will be raised: 'Using unsupported buffer
type: 246'
This error occurs because the 4.1 client libraries do not
support the new MYSQL_TYPE_NEWDECIMAL
type value added in 5.0. There is no way to disable the new
DECIMAL data type on the server side. You
can avoid the problem by relinking the application with the
client libraries from MySQL 5.0.
Incompatible change: The
ER_WARN_DATA_TRUNCATED warning symbol was
renamed to WARN_DATA_TRUNCATED in MySQL
5.0.3.
The reconnect flag in the
MYSQL structure is set to 0 by
mysql_real_connect(). Only those client
programs which did not explicitly set this flag to 0 or 1
after mysql_real_connect() experience a
change. Having automatic reconnection enabled by default was
considered too dangerous (due to the fact that table locks,
temporary tables, user variables, and session variables are
lost after reconnection).
2.11.3. Copying MySQL Databases to Another Machine
You can copy the .frm,
.MYI, and .MYD files
for MyISAM tables between different
architectures that support the same floating-point format.
(MySQL takes care of any byte-swapping issues.) See
Section 14.1, “The MyISAM Storage Engine”.
In cases where you need to transfer databases between different
architectures, you can use mysqldump to
create a file containing SQL statements. You can then transfer
the file to the other machine and feed it as input to the
mysql client.
Use mysqldump --help to see what options are
available. If you are moving the data to a newer version of
MySQL, you should use mysqldump --opt to take
advantage of any optimizations that result in a dump file that
is smaller and can be processed more quickly.
The easiest (although not the fastest) way to move a database
between two machines is to run the following commands on the
machine on which the database is located:
You can also store the dump in a file, transfer the file to the
target machine, and then load the file into the database there.
For example, you can dump a database to a compressed file on the
source machine like this:
You can also use mysqldump and
mysqlimport to transfer the database. For
large tables, this is much faster than simply using
mysqldump. In the following commands,
DUMPDIR represents the full pathname
of the directory you use to store the output from
mysqldump.
First, create the directory for the output files and dump the
database:
Then transfer the files in the
DUMPDIR directory to some
corresponding directory on the target machine and load the files
into MySQL there:
shell> mysqladmin create db_name # create database
shell> cat DUMPDIR/*.sql | mysql db_name # create tables in database
shell> mysqlimport db_nameDUMPDIR/*.txt # load data into tables
Do not forget to copy the mysql database
because that is where the grant tables are stored. You might
have to run commands as the MySQL root user
on the new machine until you have the mysql
database in place.
After you import the mysql database on the
new machine, execute mysqladmin
flush-privileges so that the server reloads the grant
table information.
This section describes what you should do to downgrade to an older
MySQL version in the unlikely case that the previous version
worked better than the new one.
If you are downgrading within the same release series (for
example, from 4.1.13 to 4.1.12) the
general rule is that you just have to install the new binaries on
top of the old ones. There is no need to do anything with the
databases. As always, however, it is always a good idea to make a
backup.
The following items form a checklist of things you should do
whenever you perform a downgrade:
Read the upgrading section for the release series from which
you are downgrading to be sure that it does not have any
features you really need. Section 2.11, “Upgrading MySQL”.
If there is a downgrading section for that version, you should
read that as well.
In most cases, you can move the MySQL format files and data files
between different versions on the same architecture as long as you
stay within versions for the same release series of MySQL.
If you downgrade from one release series to another, there may be
incompatibilities in table storage formats. In this case, you can
use mysqldump to dump your tables before
downgrading. After downgrading, reload the dump file using
mysql or mysqlimport to
re-create your tables. For examples, see
Section 2.11.3, “Copying MySQL Databases to Another Machine”.
The normal symptom of a downward-incompatible table format change
when you downgrade is that you can't open tables. In that case,
use the following procedure:
Stop the older MySQL server that you are downgrading to.
Restart the newer MySQL server you are downgrading from.
Dump any tables that were inaccessible to the older server by
using mysqldump to create a dump file.
Stop the newer MySQL server and restart the older one.
Reload the dump file into the older server. Your tables should
be accessible.
2.12.1. Downgrading to MySQL 4.1
MySQL 4.1 does not support stored routines or triggers. If your
databases contain stored routines or triggers, prevent them from
being dumped when you use mysqldump by using
the --skip-routines and
--skip-triggers options. (See
Section 8.12, “mysqldump — A Database Backup Program”.)
MySQL 4.1 does not support views. If your databases contain
views, remove them with DROP VIEW before
using mysqldump. (See
Section 19.3, “DROP VIEW Syntax”.)
After downgrading from MySQL 5.0, you may see the following
information in the mysql.err file:
Incorrect information in file: './mysql/user.frm'
In this case, you can do the following:
Start MySQL 5.0.4 (or newer).
Run mysql_fix_privilege_tables, which
will change the mysql.user table to a
format that both MySQL 4.1 and 5.0 can use.
Stop the MySQL server.
Start MySQL 4.1.
If the preceding procedure fails, you should be able to do the
following instead:
Start MySQL 5.0.4 (or newer).
Run mysqldump --opt --add-drop-table mysql >
/tmp/mysql.dump.
This section discusses issues that have been found to occur on
Linux. The first few subsections describe general operating
system-related issues, problems that can occur when using binary
or source distributions, and post-installation issues. The
remaining subsections discuss problems that occur with Linux on
specific platforms.
Note that most of these problems occur on older versions of
Linux. If you are running a recent version, you may see none of
them.
2.13.1.1. Linux Operating System Notes
MySQL needs at least Linux version 2.0.
Warning: We have seen some
strange problems with Linux 2.2.14 and MySQL on SMP systems.
We also have reports from some MySQL users that they have
encountered serious stability problems using MySQL with kernel
2.2.14. If you are using this kernel, you should upgrade to
2.2.19 (or newer) or to a 2.4 kernel. If you have a
multiple-CPU box, you should seriously consider using 2.4
because it gives you a significant speed boost. Your system
should be more stable.
When using LinuxThreads, you should see a minimum of three
mysqld processes running. These are in fact
threads. There is one thread for the LinuxThreads manager, one
thread to handle connections, and one thread to handle alarms
and signals.
2.13.1.2. Linux Binary Distribution Notes
The Linux-Intel binary and RPM releases of MySQL are
configured for the highest possible speed. We are always
trying to use the fastest stable compiler available.
The binary release is linked with -static,
which means you do not normally need to worry about which
version of the system libraries you have. You need not install
LinuxThreads, either. A program linked with
-static is slightly larger than a dynamically
linked program, but also slightly faster (3-5%). However, one
problem with a statically linked program is that you can't use
user-defined functions (UDFs). If you are going to write or
use UDFs (this is something for C or C++ programmers only),
you must compile MySQL yourself using dynamic linking.
A known issue with binary distributions is that on older Linux
systems that use libc (such as Red Hat 4.x
or Slackware), you get some (non-fatal) issues with hostname
resolution. If your system uses libc rather
than glibc2, you probably will encounter
some difficulties with hostname resolution and
getpwnam(). This happens because
glibc (unfortunately) depends on some
external libraries to implement hostname resolution and
getpwent(), even when compiled with
-static. These problems manifest themselves
in two ways:
You may see the following error message when you run
mysql_install_db:
Sorry, the host 'xxxx' could not be looked up
You can deal with this by executing
mysql_install_db --force, which does
not execute the resolveip test in
mysql_install_db. The downside is that
you cannot use hostnames in the grant tables: except for
localhost, you must use IP numbers
instead. If you are using an old version of MySQL that
does not support --force, you must
manually remove the resolveip test in
mysql_install using a text editor.
You also may see the following error when you try to run
mysqld with the --user
option:
getpwnam: No such file or directory
To work around this problem, start
mysqld by using the
su command rather than by specifying
the --user option. This causes the system
itself to change the user ID of the
mysqld process so that
mysqld need not do so.
Another solution, which solves both problems, is not to use a
binary distribution. Obtain a MySQL source distribution (in
RPM or tar.gz format) and install that
instead.
On some Linux 2.2 versions, you may get the error
Resource temporarily unavailable when
clients make a great many new connections to a
mysqld server over TCP/IP. The problem is
that Linux has a delay between the time that you close a
TCP/IP socket and the time that the system actually frees it.
There is room for only a finite number of TCP/IP slots, so you
encounter the resource-unavailable error if clients attempt
too many new TCP/IP connections over a short period of time.
For example, you may see the error when you run the MySQL
test-connect benchmark over TCP/IP.
We have inquired about this problem a few times on different
Linux mailing lists but have never been able to find a
suitable resolution. The only known “fix” is for
clients to use persistent connections, or, if you are running
the database server and clients on the same machine, to use
Unix socket file connections rather than TCP/IP connections.
2.13.1.3. Linux Source Distribution Notes
The following notes regarding glibc apply
only to the situation when you build MySQL yourself. If you
are running Linux on an x86 machine, in most cases it is much
better for you to use our binary. We link our binaries against
the best patched version of glibc we can
find and with the best compiler options, in an attempt to make
it suitable for a high-load server. For a typical user, even
for setups with a lot of concurrent connections or tables
exceeding the 2GB limit, our binary is the best choice in most
cases. After reading the following text, if you are in doubt
about what to do, try our binary first to determine whether it
meets your needs. If you discover that it is not good enough,
you may want to try your own build. In that case, we would
appreciate a note about it so that we can build a better
binary next time.
MySQL uses LinuxThreads on Linux. If you are using an old
Linux version that doesn't have glibc2, you
must install LinuxThreads before trying to compile MySQL. You
can obtain LinuxThreads from
http://dev.mysql.com/downloads/os-linux.html.
Note that glibc versions before and
including version 2.1.1 have a fatal bug in
pthread_mutex_timedwait() handling, which
is used when INSERT DELAYED statements are
issued. We recommend that you not use INSERT
DELAYED before upgrading glibc.
Note that Linux kernel and the LinuxThread library can by
default handle a maximum of 1,024 threads. If you plan to have
more than 1,000 concurrent connections, you need to make some
changes to LinuxThreads, as follows:
Increase PTHREAD_THREADS_MAX in
sysdeps/unix/sysv/linux/bits/local_lim.h
to 4096 and decrease STACK_SIZE in
linuxthreads/internals.h to 256KB.
The paths are relative to the root of
glibc. (Note that MySQL is not stable
with 600-1000 connections if STACK_SIZE
is the default of 2MB.)
Recompile LinuxThreads to produce a new
libpthread.a library, and relink
MySQL against it.
There is another issue that greatly hurts MySQL performance,
especially on SMP systems. The mutex implementation in
LinuxThreads in glibc 2.1 is very poor for
programs with many threads that hold the mutex only for a
short time. This produces a paradoxical result: If you link
MySQL against an unmodified LinuxThreads, removing processors
from an SMP actually improves MySQL performance in many cases.
We have made a patch available for glibc
2.1.3 to correct this behavior
(http://dev.mysql.com/Downloads/Linux/linuxthreads-2.1-patch).
With glibc 2.2.2, MySQL uses the adaptive
mutex, which is much better than even the patched one in
glibc 2.1.3. Be warned, however, that under
some conditions, the current mutex code in
glibc 2.2.2 overspins, which hurts MySQL
performance. The likelihood that this condition occurs can be
reduced by re-nicing the mysqld process to
the highest priority. We have also been able to correct the
overspin behavior with a patch, available at
http://dev.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch.
It combines the correction of overspin, maximum number of
threads, and stack spacing all in one. You need to apply it in
the linuxthreads directory with
patch -p0
</tmp/linuxthreads-2.2.2.patch. We hope it is
included in some form in future releases of
glibc 2.2. In any case, if you link against
glibc 2.2.2, you still need to correct
STACK_SIZE and
PTHREAD_THREADS_MAX. We hope that the
defaults is corrected to some more acceptable values for
high-load MySQL setup in the future, so that the commands
needed to produce your own build can be reduced to
./configure; make; make install.
We recommend that you use these patches to build a special
static version of libpthread.a and use it
only for statically linking against MySQL. We know that these
patches are safe for MySQL and significantly improve its
performance, but we cannot say anything about their effects on
other applications. If you link other applications that
require LinuxThreads against the patched static version of the
library, or build a patched shared version and install it on
your system, you do so at your own risk.
If you experience any strange problems during the installation
of MySQL, or with some common utilities hanging, it is very
likely that they are either library or compiler related. If
this is the case, using our binary resolves them.
If you link your own MySQL client programs, you may see the
following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory
This problem can be avoided by one of the following methods:
Link clients with the
-Wl,r/full/path/to/libmysqlclient.so flag
rather than with -Lpath).
Copy libmysqclient.so to
/usr/lib.
Add the pathname of the directory where
libmysqlclient.so is located to the
LD_RUN_PATH environment variable before
running your client.
If you are using the Fujitsu compiler
(fcc/FCC), you may have some problems
compiling MySQL because the Linux header files are very
gcc oriented. The following
configure line should work with
fcc/FCC:
mysql.server can be found in the
support-files directory under the MySQL
installation directory or in a MySQL source tree. You can
install it as /etc/init.d/mysql for
automatic MySQL startup and shutdown. See
Section 2.10.2.2, “Starting and Stopping MySQL Automatically”.
If MySQL cannot open enough files or connections, it may be
that you have not configured Linux to handle enough files.
In Linux 2.2 and onward, you can check the number of allocated
file handles as follows:
If you have more than 16MB of memory, you should add something
like the following to your init scripts (for example,
/etc/init.d/boot.local on SuSE Linux):
You can also run the echo commands from the
command line as root, but these settings
are lost the next time your computer restarts.
Alternatively, you can set these parameters on startup by
using the sysctl tool, which is used by
many Linux distributions (including SuSE Linux 8.0 and later).
Put the following values into a file named
/etc/sysctl.conf:
# Increase some values for MySQL
fs.file-max = 65536
fs.dquot-max = 8192
fs.super-max = 1024
You should also add the following to
/etc/my.cnf:
[mysqld_safe]
open-files-limit=8192
This should allow the server a limit of 8,192 for the combined
number of connections and open files.
The STACK_SIZE constant in LinuxThreads
controls the spacing of thread stacks in the address space. It
needs to be large enough so that there is plenty of room for
each individual thread stack, but small enough to keep the
stack of some threads from running into the global
mysqld data. Unfortunately, as we have
experimentally discovered, the Linux implementation of
mmap() successfully unmaps a mapped region
if you ask it to map out an address currently in use, zeroing
out the data on the entire page instead of returning an error.
So, the safety of mysqld or any other
threaded application depends on the “gentlemanly”
behavior of the code that creates threads. The user must take
measures to make sure that the number of running threads at
any given time is sufficiently low for thread stacks to stay
away from the global heap. With mysqld, you
should enforce this behavior by setting a reasonable value for
the max_connections variable.
If you build MySQL yourself, you can patch LinuxThreads for
better stack use. See Section 2.13.1.3, “Linux Source Distribution Notes”. If
you do not want to patch LinuxThreads, you should set
max_connections to a value no higher than
500. It should be even less if you have a large key buffer,
large heap tables, or some other things that make
mysqld allocate a lot of memory, or if you
are running a 2.2 kernel with a 2GB patch. If you are using
our binary or RPM version, you can safely set
max_connections at 1500, assuming no large
key buffer or heap tables with lots of data. The more you
reduce STACK_SIZE in LinuxThreads the more
threads you can safely create. We recommend values between
128KB and 256KB.
If you use a lot of concurrent connections, you may suffer
from a “feature” in the 2.2 kernel that attempts
to prevent fork bomb attacks by penalizing a process for
forking or cloning a child. This causes MySQL not to scale
well as you increase the number of concurrent clients. On
single-CPU systems, we have seen this manifest as very slow
thread creation; it may take a long time to connect to MySQL
(as long as one minute), and it may take just as long to shut
it down. On multiple-CPU systems, we have observed a gradual
drop in query speed as the number of clients increases. In the
process of trying to find a solution, we have received a
kernel patch from one of our users who claimed it helped for
his site. This patch is available at
http://dev.mysql.com/Downloads/Patches/linux-fork.patch.
We have done rather extensive testing of this patch on both
development and production systems. It has significantly
improved MySQL performance without causing any problems and we
recommend it to our users who still run high-load servers on
2.2 kernels.
This issue has been fixed in the 2.4 kernel, so if you are not
satisfied with the current performance of your system, rather
than patching your 2.2 kernel, it might be easier to upgrade
to 2.4. On SMP systems, upgrading also gives you a nice SMP
boost in addition to fixing the fairness bug.
We have tested MySQL on the 2.4 kernel on a two-CPU machine
and found MySQL scales much better. There
was virtually no slowdown on query throughput all the way up
to 1,000 clients, and the MySQL scaling factor (computed as
the ratio of maximum throughput to the throughput for one
client) was 180%. We have observed similar results on a
four-CPU system: Virtually no slowdown as the number of
clients was increased up to 1,000, and a 300% scaling factor.
Based on these results, for a high-load SMP server using a 2.2
kernel, we definitely recommend upgrading to the 2.4 kernel at
this point.
We have discovered that it is essential to run the
mysqld process with the highest possible
priority on the 2.4 kernel to achieve maximum performance.
This can be done by adding a renice -20 $$
command to mysqld_safe. In our testing on a
four-CPU machine, increasing the priority resulted in a 60%
throughput increase with 400 clients.
We are currently also trying to collect more information on
how well MySQL performs with a 2.4 kernel on four-way and
eight-way systems. If you have access such a system and have
done some benchmarks, please send an email message to
<benchmarks@mysql.com> with the results. We will
review them for inclusion in the manual.
To get a core dump on Linux if mysqld dies
with a SIGSEGV signal, you can start
mysqld with the
--core-file option. Note that you also
probably need to raise the core file size by adding
ulimit -c 1000000 to
mysqld_safe or starting
mysqld_safe with
--core-file-size=1000000. See
Section 5.4.1, “mysqld_safe — MySQL Server Startup Script”.
2.13.1.5. Linux x86 Notes
MySQL requires libc 5.4.12 or newer. It is
known to work with libc 5.4.46.
glibc 2.0.6 and later should also work.
There have been some problems with the
glibc RPMs from Red Hat, so if you have
problems, check whether there are any updates. The
glibc 2.0.7-19 and 2.0.7-29 RPMs are known
to work.
If you are using Red Hat 8.0 or a new glibc
2.2.x library, you may see mysqld die in
gethostbyaddr(). This happens because the
new glibc library requires a stack size
greater than 128KB for this call. To fix the problem, start
mysqld with the
--thread-stack=192K option. (Use -O
thread_stack=192K before MySQL 4.) This stack size is
the default on MySQL 4.0.10 and above, so you should not see
the problem.
If you are using gcc 3.0 and above to
compile MySQL, you must install the
libstdc++v3 library before compiling MySQL;
if you don't do this, you get an error about a missing
__cxa_pure_virtual symbol during linking.
On some older Linux distributions,
configure may produce an error like this:
Syntax error in sched.h. Change _P to __P in the
/usr/include/sched.h file.
See the Installation chapter in the Reference Manual.
Just do what the error message says. Add an extra underscore
to the _P macro name that has only one
underscore, and then try again.
You may get some warnings when compiling. Those shown here can
be ignored:
mysqld.cc -o objs-thread/mysqld.o
mysqld.cc: In function `void init_signals()':
mysqld.cc:315: warning: assignment of negative value `-1' to
`long unsigned int'
mysqld.cc: In function `void * signal_hand(void *)':
mysqld.cc:346: warning: assignment of negative value `-1' to
`long unsigned int'
If mysqld always dumps core when it starts,
the problem may be that you have an old
/lib/libc.a. Try renaming it, and then
remove sql/mysqld and do a new
make install and try again. This problem
has been reported on some Slackware installations.
If you get the following error when linking
mysqld, it means that your
libg++.a is not installed correctly:
/usr/lib/libc.a(putc.o): In function `_IO_putc':
putc.o(.text+0x0): multiple definition of `_IO_putc'
You can avoid using libg++.a by running
configure like this:
shell> CXX=gcc ./configure
2.13.1.6. Linux SPARC Notes
In some implementations, readdir_r() is
broken. The symptom is that the SHOW
DATABASES statement always returns an empty set.
This can be fixed by removing
HAVE_READDIR_R from
config.h after configuring and before
compiling.
2.13.1.7. Linux Alpha Notes
We have tested MySQL 5.0 on Alpha with our
benchmarks and test suite, and it appears to work well.
We currently build the MySQL binary packages on SuSE Linux 7.0
for AXP, kernel 2.4.4-SMP, Compaq C compiler (V6.2-505) and
Compaq C++ compiler (V6.3-006) on a Compaq DS20 machine with
an Alpha EV6 processor.
You can find the preceding compilers at
http://www.support.compaq.com/alpha-tools/. By
using these compilers rather than gcc, we
get about 9-14% better MySQL performance.
For MySQL on Alpha, we use the -arch generic
flag to our compile options, which ensures that the binary
runs on all Alpha processors. We also compile statically to
avoid library problems. The configure
command looks like this:
Some known problems when running MySQL on Linux-Alpha:
Debugging threaded applications like MySQL does not work
with gdb 4.18. You should use
gdb 5.1 instead.
If you try linking mysqld statically
when using gcc, the resulting image
dumps core at startup time. In other words, do
not use
--with-mysqld-ldflags=-all-static with
gcc.
2.13.1.8. Linux PowerPC Notes
MySQL should work on MkLinux with the newest
glibc package (tested with
glibc 2.0.7).
2.13.1.9. Linux MIPS Notes
To get MySQL to work on Qube2 (Linux Mips), you need the
newest glibc libraries.
glibc-2.0.7-29C2 is known to work. You must
also use the egcs C++ compiler
(egcs 1.0.2-9, gcc
2.95.2 or newer).
2.13.1.10. Linux IA-64 Notes
To get MySQL to compile on Linux IA-64, we use the following
configure command for building with
gcc 2.96:
On IA-64, the MySQL client binaries use shared libraries. This
means that if you install our binary distribution at a
location other than /usr/local/mysql, you
need to add the path of the directory where you have
libmysqlclient.so installed either to the
/etc/ld.so.conf file or to the value of
your LD_LIBRARY_PATH environment variable.
RHEL4 comes with SELinux, which supports tighter access
control for processes. If SELinux is enabled
(SELINUX in
/etc/selinux/config is set to
enforcing, SELINUXTYPE
is set to either targeted or
strict), you might encounter problems
installing MySQL AB RPM packages.
On Mac OS X, tar cannot handle long
filenames. If you need to unpack a .tar.gz
distribution, use gnutar instead.
2.13.2.1. Mac OS X 10.x (Darwin)
MySQL should work without major problems on Mac OS X 10.x
(Darwin).
Known issues:
If you have problems with performance under heavy load,
try using the --skip-thread-priority
option to mysqld. This runs all threads
with the same priority. On Mac OS X, this gives better
performance, at least until Apple fixes its thread
scheduler.
The connection times (wait_timeout,
interactive_timeout and
net_read_timeout) values are not
honored.
This is probably a signal handling problem in the thread
library where the signal doesn't break a pending read and
we hope that a future update to the thread libraries will
fix this.
Our binary for Mac OS X is compiled on Darwin 6.3 with the
following configure line:
For current versions of Mac OS X Server, no operating system
changes are necessary before compiling MySQL. Compiling for
the Server platform is the same as for the client version of
Mac OS X.
For older versions (Mac OS X Server 1.2, a.k.a. Rhapsody), you
must first install a pthread package before trying to
configure MySQL.
On Solaris, you may run into trouble even before you get the
MySQL distribution unpacked, as the Solaris
tar cannot handle long filenames. This means
that you may see errors when you try to unpack MySQL.
Sun native threads work only on Solaris 2.5 and higher. For
Solaris 2.4 and earlier, MySQL automatically uses MIT-pthreads.
See Section 2.9.5, “MIT-pthreads Notes”.
If you get the following error from
configure, it means that you have something
wrong with your compiler installation:
checking for restartable system calls... configure: error can not
run test programs while cross compiling
In this case, you should upgrade your compiler to a newer
version. You may also be able to solve this problem by inserting
the following row into the config.cache
file:
If you are using Solaris on a SPARC, the recommended compiler is
gcc 2.95.2 or 3.2. You can find this at
http://gcc.gnu.org/. Note that
egcs 1.1.1 and gcc 2.8.1
do not work reliably on SPARC.
The recommended configure line when using
gcc 2.95.2 is:
If you have an UltraSPARC system, you can get 4% better
performance by adding -mcpu=v8
-Wa,-xarch=v8plusa to the CFLAGS and
CXXFLAGS environment variables.
If you have Sun's Forte 5.0 (or newer) compiler, you can run
configure like this:
To create a 64-bit Solaris binary using gcc,
add -m64 to CFLAGS and
CXXFLAGS and remove
--enable-assembler from the
configure line.
In the MySQL benchmarks, we obtained a 4% speed increase on
UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to
using gcc 3.2 with the -mcpu
flag.
If you create a 64-bit mysqld binary, it is
4% slower than the 32-bit binary, but can handle more threads
and memory.
When using Solaris 10 for x86_64, you should mount any
filesystems on which you intend to store
InnoDB files with the
forcedirectio option. (By default mounting is
done without this option.) Failing to do so will cause a
significant drop in performance when using the
InnoDB storage engine on this platform.
If you get a problem with fdatasync or
sched_yield, you can fix this by adding
LIBS=-lrt to the configure
line
For compilers older than WorkShop 5.3, you might have to edit
the configure script. Change this line:
#if !defined(__STDC__) || __STDC__ != 1
To this:
#if !defined(__STDC__)
If you turn on __STDC__ with the
-Xc option, the Sun compiler can't compile with
the Solaris pthread.h header file. This is
a Sun bug (broken compiler or broken include file).
If mysqld issues the following error message
when you run it, you have tried to compile MySQL with the Sun
compiler without enabling the -mt multi-thread
option:
libc internal error: _rmutex_unlock: rmutex not held
Add -mt to CFLAGS and
CXXFLAGS and recompile.
If you are using the SFW version of gcc
(which comes with Solaris 8), you must add
/opt/sfw/lib to the environment variable
LD_LIBRARY_PATH before running
configure.
If you are using the gcc available from
sunfreeware.com, you may have many problems.
To avoid this, you should recompile gcc and
GNU binutils on the machine where you are
running them.
If you get the following error when compiling MySQL with
gcc, it means that your
gcc is not configured for your version of
Solaris:
shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ...
./thr_alarm.c: In function `signal_hand':
./thr_alarm.c:556: too many arguments to function `sigwait'
The proper thing to do in this case is to get the newest version
of gcc and compile it with your current
gcc compiler. At least for Solaris 2.5,
almost all binary versions of gcc have old,
unusable include files that break all programs that use threads,
and possibly other programs as well.
Solaris does not provide static versions of all system libraries
(libpthreads and libdl),
so you cannot compile MySQL with --static. If
you try to do so, you get one of the following errors:
ld: fatal: library -ldl: not found
undefined reference to `dlopen'
cannot find -lrt
If you link your own MySQL client programs, you may see the
following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory
This problem can be avoided by one of the following methods:
Link clients with the
-Wl,r/full/path/to/libmysqlclient.so flag
rather than with -Lpath).
Copy libmysqclient.so to
/usr/lib.
Add the pathname of the directory where
libmysqlclient.so is located to the
LD_RUN_PATH environment variable before
running your client.
If you have problems with configure trying to
link with -lz when you don't have
zlib installed, you have two options:
If you want to be able to use the compressed communication
protocol, you need to get and install
zlib from ftp.gnu.org.
Run configure with the
--with-named-z-libs=no option when building
MySQL.
If you are using gcc and have problems with
loading user-defined functions (UDFs) into MySQL, try adding
-lgcc to the link line for the UDF.
If you would like MySQL to start automatically, you can copy
support-files/mysql.server to
/etc/init.d and create a symbolic link to
it named /etc/rc3.d/S99mysql.server.
If too many processes try to connect very rapidly to
mysqld, you should see this error in the
MySQL log:
Error in accept: Protocol error
You might try starting the server with the
--back_log=50 option as a workaround for this.
(Use -O back_log=50 before MySQL 4.)
Solaris doesn't support core files for
setuid() applications, so you can't get a
core file from mysqld if you are using the
--user option.
2.13.3.1. Solaris 2.7/2.8 Notes
Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and
2.8. Most of the Solaris 2.6 issues also apply for Solaris 2.7
and 2.8.
MySQL should be able to detect new versions of Solaris
automatically and enable workarounds for the following
problems.
Solaris 2.7 / 2.8 has some bugs in the include files. You may
see the following error when you use gcc:
/usr/include/widec.h:42: warning: `getwc' redefined
/usr/include/wchar.h:326: warning: this is the location of the previous
definition
If this occurs, you can fix the problem by copying
/usr/include/widec.h to
.../lib/gcc-lib/os/gcc-version/include and
changing line 41 from this:
Alternatively, you can edit
/usr/include/widec.h directly. Either
way, after you make the fix, you should remove
config.cache and run
configure again.
If you get the following errors when you run
make, it's because
configure didn't detect the
curses.h file (probably because of the
error in /usr/include/widec.h):
In file included from mysql.cc:50:
/usr/include/term.h:1060: syntax error before `,'
/usr/include/term.h:1081: syntax error before `;'
The solution to this problem is to do one of the following:
Configure with CFLAGS=-DHAVE_CURSES_H
CXXFLAGS=-DHAVE_CURSES_H ./configure.
Edit /usr/include/widec.h as
indicated in the preceding discussion and re-run
configure.
Remove the #define HAVE_TERM line from
the config.h file and run
make again.
If your linker cannot find -lz when linking
client programs, the problem is probably that your
libz.so file is installed in
/usr/local/lib. You can fix this problem
by one of the following methods:
Add /usr/local/lib to
LD_LIBRARY_PATH.
Add a link to libz.so from
/lib.
If you are using Solaris 8, you can install the optional
zlib from your Solaris 8 CD
distribution.
Run configure with the
--with-named-z-libs=no option when
building MySQL.
2.13.3.2. Solaris x86 Notes
On Solaris 8 on x86, mysqld dumps core if
you remove the debug symbols using strip.
If you are using gcc or
egcs on Solaris x86 and you experience
problems with core dumps under load, you should use the
following configure command:
This section provides information about using MySQL on variants
of BSD Unix.
2.13.4.1. FreeBSD Notes
FreeBSD 4.x or newer is recommended for running MySQL, because
the thread package is much more integrated. To get a secure
and stable system, you should use only FreeBSD kernels that
are marked -RELEASE.
The easiest (and preferred) way to install MySQL is to use the
mysql-server and
mysql-client ports available at
http://www.freebsd.org/. Using these ports
gives you the following benefits:
A working MySQL with all optimizations enabled that are
known to work on your version of FreeBSD.
Automatic configuration and build.
Startup scripts installed in
/usr/local/etc/rc.d.
The ability to use pkg_info -L to see
which files are installed.
The ability to use pkg_delete to remove
MySQL if you no longer want it on your machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x, and
native threads on FreeBSD 3 and up. It is possible to run with
native threads on some late 2.2.x versions, but you may
encounter problems shutting down mysqld.
Unfortunately, certain function calls on FreeBSD are not yet
fully thread-safe. Most notably, this includes the
gethostbyname() function, which is used by
MySQL to convert hostnames into IP addresses. Under certain
circumstances, the mysqld process suddenly
causes 100% CPU load and is unresponsive. If you encounter
this problem, try to start MySQL using the
--skip-name-resolve option.
Alternatively, you can link MySQL on FreeBSD 4.x against the
LinuxThreads library, which avoids a few of the problems that
the native FreeBSD thread implementation has. For a very good
comparison of LinuxThreads versus native threads, see Jeremy
Zawodny's article FreeBSD or Linux for your MySQL
Server? at
http://jeremy.zawodny.com/blog/archives/000697.html.
Known problem when using LinuxThreads on FreeBSD is:
The connection times (wait_timeout,
interactive_timeout and
net_read_timeout) values are not
honored. The symptom is that persistent connections can
hang for a very long time without getting closed down and
that a 'kill' for a thread will not take affect until the
thread does it a new command
This is probably a signal handling problem in the thread
library where the signal doesn't break a pending read.
This is supposed to be fixed in FreeBSD 5.0
The MySQL build process requires GNU make
(gmake) to work. If GNU
make is not available, you must install it
first before compiling MySQL.
The recommended way to compile and install MySQL on FreeBSD
with gcc (2.95.2 and up) is:
If you get an error from make install that
it can't find /usr/include/pthreads,
configure didn't detect that you need
MIT-pthreads. To fix this problem, remove
config.cache, and then re-run
configure with the
--with-mit-threads option.
Be sure that your name resolver setup is correct. Otherwise,
you may experience resolver delays or failures when connecting
to mysqld. Also make sure that the
localhost entry in the
/etc/hosts file is correct. The file
should start with a line similar to this:
127.0.0.1 localhost localhost.your.domain
FreeBSD is known to have a very low default file handle limit.
See Section A.2.17, “File Not Found”. Start the
server by using the --open-files-limit option
for mysqld_safe, or raise the limits for
the mysqld user in
/etc/login.conf and rebuild it with
cap_mkdb /etc/login.conf. Also be sure that
you set the appropriate class for this user in the password
file if you are not using the default (use chpass
mysqld-user-name). See
Section 5.4.1, “mysqld_safe — MySQL Server Startup Script”.
FreeBSD limits the size of a process to 512MB, even if you
have much more RAM available on the system. So you may get an
error such as this:
Out of memory (Needed 16391 bytes)
In current versions of FreeBSD (at least 4.x and greater), you
may increase this limit by adding the following entries to the
/boot/loader.conf file and rebooting the
machine (these are not settings that can be changed at run
time with the sysctl command):
For older versions of FreeBSD, you must recompile your kernel
to change the maximum data segment size for a process. In this
case, you should look at the MAXDSIZ option
in the LINT config file for more
information.
Try using ulimit -v 80000 and run
make again. If this doesn't work and you
are using bash, try switching to
csh or sh; some BSDI
users have reported problems with bash and
ulimit.
If you are using gcc, you may also use have
to use the --with-low-memory flag for
configure to be able to compile
sql_yacc.cc.
You can change the directory locations if you wish, or just
use the defaults by not specifying any locations.
If you have problems with performance under heavy load, try
using the --skip-thread-priority option to
mysqld. This runs all threads with the same
priority. On BSDI 3.1, this gives better performance, at least
until BSDI fixes its thread scheduler.
If you get the error virtual memory
exhausted while compiling, you should try using
ulimit -v 80000 and running
make again. If this doesn't work and you
are using bash, try switching to
csh or sh; some BSDI
users have reported problems with bash and
ulimit.
2.13.4.6. BSD/OS Version 4.x Notes
BSDI 4.x has some thread-related bugs. If you want to use
MySQL on this, you should install all thread-related patches.
At least M400-023 should be installed.
On some BSDI 4.x systems, you may get problems with shared
libraries. The symptom is that you can't execute any client
programs, for example, mysqladmin. In this
case, you need to reconfigure not to use shared libraries with
the --disable-shared option to configure.
Some customers have had problems on BSDI 4.0.1 that the
mysqld binary after a while can't open
tables. This occurs because some library/system-related bug
causes mysqld to change current directory
without having asked for that to happen.
The fix is to either upgrade MySQL to at least version 3.23.34
or, after running configure, remove the
line #define HAVE_REALPATH from
config.h before running
make.
Note that this means that you can't symbolically link a
database directories to another database directory or symbolic
link a table to another database on BSDI. (Making a symbolic
link to another disk is okay).
There are a couple of small problems when compiling MySQL on
HP-UX. We recommend that you use gcc
instead of the HP-UX native compiler, because
gcc produces better code.
We recommend using gcc 2.95 on HP-UX. Don't
use high optimization flags (such as -O6)
because they may not be safe on HP-UX.
The following configure line should work
with gcc 2.95:
This solves the problem of getting
EWOULDBLOCK from recv()
and EBADF from accept()
in threaded applications.
If you are using gcc 2.95.1 on an unpatched
HP-UX 11.x system, you may get the following error:
In file included from /usr/include/unistd.h:11,
from ../include/global.h:125,
from mysql_priv.h:15,
from item.cc:19:
/usr/include/sys/unistd.h:184: declaration of C function ...
/usr/include/sys/pthread.h:440: previous declaration ...
In file included from item.h:306,
from mysql_priv.h:158,
from item.cc:19:
The problem is that HP-UX does not define
pthreads_atfork() consistently. It has
conflicting prototypes in
/usr/include/sys/unistd.h:184 and
/usr/include/sys/pthread.h:440.
One solution is to copy
/usr/include/sys/unistd.h into
mysql/include and edit
unistd.h and change it to match the
definition in pthread.h. Look for this
line:
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
void (*child)());
Change it to look like this:
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
void (*child)(void));
After making the change, the following
configure line should work:
aCC: warning 901: unknown option: `-3': use +help for online
documentation
If you get the following error from
configure, verify that you don't have the
path to the K&R compiler before the path to the HP-UX C
and C++ compiler:
checking for cc option to accept ANSI C... no
configure: error: MySQL requires an ANSI C compiler (and a C++ compiler).
Try gcc. See the Installation chapter in the Reference Manual.
Another reason for not being able to compile is that you
didn't define the +DD64 flags as just
described.
Another possibility for HP-UX 11 is to use the MySQL binaries
provided at http://dev.mysql.com/downloads/, which we have
built and tested ourselves. We have also received reports that
the HP-UX 10.20 binaries supplied by MySQL can be run
successfully on HP-UX 11. If you encounter problems, you
should be sure to check your HP-UX patch level.
2.13.5.3. IBM-AIX notes
Automatic detection of xlC is missing from
Autoconf, so a number of variables need to be set before
running configure. The following example
uses the IBM compiler:
The preceding options are used to compile the MySQL
distribution that can be found at
http://www-frec.bull.com/.
If you change the -O3 to -O2
in the preceding configure line, you must
also remove the -qstrict option. This is a
limitation in the IBM C compiler.
If you are using gcc or
egcs to compile MySQL, you
must use the
-fno-exceptions flag, because the exception
handling in gcc/egcs is
not thread-safe! (This is tested with egcs
1.1.) There are also some known problems with IBM's assembler
that may cause it to generate bad code when used with
gcc.
We recommend the following configure line
with egcs and gcc 2.95
on AIX:
The -Wa,-many option is necessary for the
compile to be successful. IBM is aware of this problem but is
in no hurry to fix it because of the workaround that is
available. We don't know if the
-fno-exceptions is required with
gcc 2.95, but because MySQL doesn't use
exceptions and the option generates faster code, we recommend
that you should always use it with egcs /
gcc.
If you get a problem with assembler code, try changing the
-mcpu=xxx option
to match your CPU. Typically power2,
power, or powerpc may
need to be used. Alternatively, you might need to use
604 or 604e. We are not
positive but suspect that power would
likely be safe most of the time, even on a power2 machine.
If you don't know what your CPU is, execute a uname
-m command. It produces a string that looks like
000514676700, with a format of
xxyyyyyymmss where xx
and ss are always 00,
yyyyyy is a unique system ID and
mm is the ID of the CPU Planar. A chart of
these values can be found at
http://www16.boulder.ibm.com/pseries/en_US/cmds/aixcmds5/uname.htm.
This gives you a machine type and a machine model you can use
to determine what type of CPU you have.
If you have problems with signals (MySQL dies unexpectedly
under high load), you may have found an OS bug with threads
and signals. In this case, you can tell MySQL not to use
signals by configuring as follows:
This doesn't affect the performance of MySQL, but has the side
effect that you can't kill clients that are
“sleeping” on a connection with
mysqladmin kill or mysqladmin
shutdown. Instead, the client dies when it issues
its next command.
On some versions of AIX, linking with
libbind.a makes
getservbyname() dump core. This is an AIX
bug and should be reported to IBM.
For AIX 4.2.1 and gcc, you have to make the
following changes.
After configuring, edit config.h and
include/my_config.h and change the line
that says this:
#define HAVE_SNPRINTF 1
to this:
#undef HAVE_SNPRINTF
And finally, in mysqld.cc, you need to
add a prototype for initgroups().
#ifdef _AIX41
extern "C" int initgroups(const char *,int);
#endif
If you need to allocate a lot of memory to the
mysqld process, it's not enough to just use
ulimit -d unlimited. You may also have to
modify mysqld_safe to add a line something
like this:
The steps for compiling MySQL on AIX with
gcc 3.3.2 are similar to those for using
gcc 2.95 (in particular, the need to edit
config.h and
my_config.h after running
configure). However, before running
configure, you should also patch the
curses.h file as follows:
/opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/curses.h.ORIG
Mon Dec 26 02:17:28 2005
--- /opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/curses.h
Mon Dec 26 02:40:13 2005
***************
*** 2023,2029 ****
#endif /* _AIX32_CURSES */
! #if defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus) || defined
(__STRICT_ANSI__)
extern int delwin (WINDOW *);
extern int endwin (void);
extern int getcurx (WINDOW *);
--- 2023,2029 ----
#endif /* _AIX32_CURSES */
! #if 0 && (defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus)
|| defined
(__STRICT_ANSI__))
extern int delwin (WINDOW *);
extern int endwin (void);
extern int getcurx (WINDOW *);
2.13.5.4. SunOS 4 Notes
On SunOS 4, MIT-pthreads is needed to compile MySQL. This in
turn means you need GNU make.
Some SunOS 4 systems have problems with dynamic libraries and
libtool. You can use the following
configure line to avoid this problem:
When compiling readline, you may get
warnings about duplicate defines. These can be ignored.
When compiling mysqld, there are some
implicit declaration of function warnings.
These can be ignored.
2.13.5.5. Alpha-DEC-UNIX Notes (Tru64)
If you are using egcs 1.1.2 on Digital
Unix, you should upgrade to gcc 2.95.2,
because egcs on DEC has some serious bugs!
When compiling threaded programs under Digital Unix, the
documentation recommends using the -pthread
option for cc and cxx
and the -lmach -lexc libraries (in addition
to -lpthread). You should run
configure something like this:
When compiling mysqld, you may see a couple
of warnings like this:
mysqld.cc: In function void handle_connections()':
mysqld.cc:626: passing long unsigned int *' as argument 3 of
accept(int,sockadddr *, int *)'
You can safely ignore these warnings. They occur because
configure can detect only errors, not
warnings.
If you start the server directly from the command line, you
may have problems with it dying when you log out. (When you
log out, your outstanding processes receive a
SIGHUP signal.) If so, try starting the
server like this:
nohup mysqld [options] &
nohup causes the command following it to
ignore any SIGHUP signal sent from the
terminal. Alternatively, start the server by running
mysqld_safe, which invokes
mysqld using nohup for
you. See Section 5.4.1, “mysqld_safe — MySQL Server Startup Script”.
If you get a problem when compiling
mysys/get_opt.c, just remove the
#define _NO_PROTO line from the start of
that file.
If you are using Compaq's CC compiler, the following
configure line should work:
If you get a problem with libtool when
compiling with shared libraries as just shown, when linking
mysql, you should be able to get around
this by issuing these commands:
cd mysql
/bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \
-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \
-o mysql mysql.o readline.o sql_string.o completion_hash.o \
../readline/libreadline.a -lcurses \
../libmysql/.libs/libmysqlclient.so -lm
cd ..
gnumake
gnumake install
scripts/mysql_install_db
2.13.5.6. Alpha-DEC-OSF/1 Notes
If you have problems compiling and have DEC
CC and gcc installed,
try running configure like this:
On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix
V4.0 (Rev. 878)," the compiler had some strange behavior
(undefined asm symbols).
/bin/ld also appears to be broken (problems
with _exit undefined errors occurring while
linking mysqld). On this system, we have
managed to compile MySQL with the following
configure line, after replacing
/bin/ld with the version from OSF 4.0C:
If you have problems with signals (MySQL dies unexpectedly
under high load), you may have found an OS bug with threads
and signals. In this case, you can tell MySQL not to use
signals by configuring with:
This does not affect the performance of MySQL, but has the
side effect that you can't kill clients that are
“sleeping” on a connection with
mysqladmin kill or mysqladmin
shutdown. Instead, the client dies when it issues
its next command.
With gcc 2.95.2, you may encounter the
following compile error:
sql_acl.cc:1456: Internal compiler error in `scan_region',
at except.c:2566
Please submit a full bug report.
To fix this, you should change to the sql
directory and do a cut-and-paste of the last
gcc line, but change -O3
to -O0 (or add -O0
immediately after gcc if you don't have any
-O option on your compile line). After this
is done, you can just change back to the top-level directory
and run make again.
2.13.5.7. SGI Irix Notes
If you are using Irix 6.5.3 or newer,
mysqld is able to create threads only if
you run it as a user that has CAP_SCHED_MGT
privileges (such as root) or give the
mysqld server this privilege with the
following shell command:
You may have to undefine some symbols in
config.h after running
configure and before compiling.
In some Irix implementations, the alloca()
function is broken. If the mysqld server
dies on some SELECT statements, remove the
lines from config.h that define
HAVE_ALLOC and
HAVE_ALLOCA_H. If mysqladmin
create doesn't work, remove the line from
config.h that defines
HAVE_READDIR_R. You may have to remove the
HAVE_TERM_H line as well.
If you get the something like the following error when
compiling mysql.cc:
"/usr/include/curses.h", line 82: error(1084):
invalid combination of type
Type the following in the top-level directory of your MySQL
source tree:
extra/replace bool curses_bool < /usr/include/curses.h > include/curses.h
make
There have also been reports of scheduling problems. If only
one thread is running, performance is slow. Avoid this by
starting another client. This may lead to a two-to-tenfold
increase in execution speed thereafter for the other thread.
This is a poorly understood problem with Irix threads; you may
have to improvise to find solutions until this can be fixed.
If you are compiling with gcc, you can use
the following configure command:
The current port is tested only on
sco3.2v5.0.5,
sco3.2v5.0.6, and
sco3.2v5.0.7 systems. There has also been
progress on a port to sco3.2v4.2. Open
Server 5.0.8 (Legend) has native threads and allows files
greater than 2GB. The current maximum file size is 2GB.
We have been able to compile MySQL with the following
configure command on OpenServer with
gcc 2.95.3.
This development system requires the OpenServer Execution
Environment Supplement oss646B on OpenServer 5.0.6 and oss656B
and The OpenSource libraries found in gwxlibs. All OpenSource
tools are in the opensrc directory. They
are available at
ftp://ftp.sco.com/pub/openserver5/opensrc/.
We recommend using the latest production release of MySQL.
Follow this procedure to configure the Database Services
option. If you are unsure whether an application requires
this, see the documentation provided with the application.
Log in as root.
Enable the SUDS driver by editing the
/etc/conf/sdevice.d/suds file. Change
the N in the second field to a
Y.
Use mkdev aio or the Hardware/Kernel
Manager to enable support for asynchronous I/O and relink
the kernel. To allow users to lock down memory for use
with this type of I/O, update the aiomemlock(F) file. This
file should be updated to include the names of users that
can use AIO and the maximum amounts of memory they can
lock down.
Many applications use setuid binaries so that you need to
specify only a single user. See the documentation provided
with the application to determine whether this is the case
for your application.
After you complete this process, reboot the system to create a
new kernel incorporating these changes.
By default, the entries in
/etc/conf/cf.d/mtune are set as follows:
To make changes to the kernel, use the idtune
name parameter command.
idtune modifies the
/etc/conf/cf.d/stune file for you. For
example, to change SEMMS to
200, execute this command as
root:
# /etc/conf/bin/idtune SEMMNS 200
Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6
We recommend tuning the system, but the proper parameter
values to use depend on the number of users accessing the
application or database and size the of the database (that is,
the used buffer pool). The following kernel parameters can be
set with idtune:
SHMMAX (recommended setting: 128MB) and
SHMSEG (recommended setting: 15). These
parameters have an influence on the MySQL database engine
to create user buffer pools.
NOFILES and MAXUP
should be set to at least 2048.
MAXPROC should be set to at least
3000/4000 (depends on number of users) or more.
We also recommend using the following formulas to
calculate values for SEMMSL,
SEMMNS, and SEMMNU:
SEMMSL = 13
13 is what has been found to be the best for both Progress
and MySQL.
SEMMNS = SEMMSL × number of db servers to be run on the system
Set SEMMNS to the value of
SEMMSL multiplied by the number of
database servers (maximum) that you are running on the
system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the
value of SEMMNS. You could probably set
this to 75% of SEMMNS, but this is a
conservative estimate.
You need to at least install the SCO OpenServer Linker and
Application Development Libraries or the OpenServer
Development System to use gcc. You cannot
use the GCC Dev system without installing one of these.
FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip, or
using OpenServer 3.0 or Open Desktop 3.0 (OS 3.0 ODT 3.0) with
the SCO Development System installed using a good port of GCC
2.5.x. For ODT or OS 3.0, you need a good port of GCC 2.5.x.
There are a lot of problems without a good port. The port for
this product requires the SCO Unix Development system. Without
it, you are missing the libraries and the linker that is
needed. You also need
SCO-3.2v4.2-includes.tar.gz. This file
contains the changes to the SCO Development include files that
are needed to get MySQL to build. You need to replace the
existing system include files with these modified header
files. They can be obtained from
ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
To build FSU Pthreads on your system, all you should need to
do is run GNU make. The
Makefile in FSU-threads-3.14.tar.gz is
set up to make FSU-threads.
You can run ./configure in the
threads/src directory and select the SCO
OpenServer option. This command copies
Makefile.SCO5 to
Makefile. Then run
make.
To install in the default /usr/include
directory, log in as root, and then
cd to the thread/src
directory and run make install.
Remember that you must use GNU make to
build MySQL.
Note: If you don't start
mysqld_safe as root, you
should get only the default 110 open files per process.
mysqld writes a note about this in the log
file.
With SCO 3.2V4.2, you should use FSU Pthreads version 3.14 or
newer. The following configure command
should work:
You should unpack this file in the
include directory of your MySQL source
tree.
SCO development notes:
MySQL should automatically detect FSU Pthreads and link
mysqld with -lgthreads -lsocket
-lgthreads.
The SCO development libraries are re-entrant in FSU
Pthreads. SCO claims that its library functions are
re-entrant, so they must be re-entrant with FSU Pthreads.
FSU Pthreads on OpenServer tries to use the SCO scheme to
make re-entrant libraries.
FSU Pthreads (at least the version at
ftp::/ftp.zenez.com) comes linked with GNU
malloc. If you encounter problems with
memory usage, make sure that
gmalloc.o is included in
libgthreads.a and
libgthreads.so.
In FSU Pthreads, the following system calls are
pthreads-aware: read(),
write(), getmsg(),
connect(), accept(),select(), and
wait().
The CSSA-2001-SCO.35.2 (the patch is listed in custom as
erg711905-dscr_remap security patch (version 2.0.0))
breaks FSU threads and makes mysqld
unstable. You have to remove this one if you want to run
mysqld on an OpenServer 5.0.6 machine.
If you use SCO OpenServer 5, you may need to recompile FSU
pthreads with -DDRAFT7 in
CFLAGS. Otherwise,
InnoDB may hang at a
mysqld startup.
It's probably a good idea to install these patches before
trying to compile/use MySQL.
Beginning with Legend/OpenServer 6.0.0, there are native
threads and no 2GB file size limit.
2.13.5.9. SCO OpenServer 6.0.x Notes
OpenServer 6 includes these key improvements:
Larger file support up to 1 TB
Multiprocessor support increased from 4 to 32 processors
Increased memory support up to 64GB
Extending the power of UnixWare into OpenServer 6
Dramatic performance improvement
OpenServer 6.0.0 commands are organized as follows:
/bin is for commands that behave
exactly the same as on OpenServer 5.0.x.
/u95/bin is for commands that have
better standards conformance, for example Large File
System (LFS) support.
/udk/bin is for commands that behave
the same as on UnixWare 7.1.4. The default is for the LFS
support.
The following is a guide to setting PATH on
OpenServer 6. If the user wants the traditional OpenServer
5.0.x then PATH should be
/bin first. If the user wants LFS
support, the path should be
/u95/bin:/bin. If the user wants UnixWare
7 support first, the path would be
/udk/bin:/u95/bin:/bin:.
We recommend using the latest production release of MySQL.
Should you choose to use an older release of MySQL on
OpenServer 6.0.x, you must use a version of MySQL at least as
recent as 3.22.13 to get fixes for some portability and OS
problems.
MySQL distribution files with names of the following form are
tar archives of media are tar archives of
media images suitable for installation with the SCO Software
Manager (/etc/custom) on SCO OpenServer
6:
mysql-PRODUCT-5.0.25-sco-osr6-i686.VOLS.tar
A distribution where PRODUCT is
pro-cert is the Commercially licensed MySQL
Pro Certified server. A distribution where
PRODUCT is
pro-gpl-cert is the MySQL Pro Certified
server licensed under the terms of the General Public License
(GPL).
Select whichever distribution you wish to install and, after
download, extract the tar archive into an
empty directory. For example:
shell> mkdir /tmp/mysql-pro
shell> cd /tmp/mysql-pro
shell> tar xf /tmp/mysql-pro-cert-5.0.25-sco-osr6-i686.VOLS.tar
Alternatively, the SCO Software Manager can be displayed
graphically by clicking on the Software
Manager icon on the desktop, selecting
Software -> Install New, selecting the
host, selecting Media Images for the Media
Device, and entering /tmp/mysql-pro as
the Image Directory.
After installation, run mkdev mysql as the
root user to configure your newly installed
MySQL Pro Certified server.
Note: The installation
procedure for VOLS packages does not create the
mysql user and group that the package uses
by default. You should either create the
mysql user and group, or else select a
different user and group using an option in mkdev
mysql.
The version of Berkeley DB that comes with either UnixWare
7.1.4 or OpenServer 6.0.0 is not used when building MySQL.
MySQL instead uses its own version of Berkeley DB. The
configure command needs to build both a
static and a dynamic library in
src_directory/bdb/build_unix/,
but it does not with MySQL's own BDB
version. The workaround is as follows.
Configure as normal for MySQL.
cd bdb/build_unix/
cp -p Makefile Makefile.sav
Use same options and run
../dist/configure.
Run gmake.
cp -p Makefile.sav Makefile
Change location to the top source directory and run
gmake.
This allows both the shared and dynamic libraries to be made
and work.
By default, the maximum file size on a OpenServer 6.0.0 system
is 1TB. Some operating system utilities have a limitation of
2GB. The maximum possible file size on UnixWare 7 is 1TB with
VXFS or HTFS.
OpenServer 6 can be configured for large file support (file
sizes greater than 2GB) by tuning the UNIX kernel.
By default, the entries in
/etc/conf/cf.d/mtune are set as follows:
Value Default Min Max
----- ------- --- ---
SVMMLIM 0x9000000 0x1000000 0x7FFFFFFF
HVMMLIM 0x9000000 0x1000000 0x7FFFFFFF
To make changes to the kernel, use the idtune
name parameter command.
idtune modifies the
/etc/conf/cf.d/stune file for you. We
recommend setting the kernel values by executing the following
commands as root:
Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6
We recommend tuning the system, but the proper parameter
values to use depend on the number of users accessing the
application or database and size the of the database (that is,
the used buffer pool). The following kernel parameters can be
set with idtune:
SHMMAX (recommended setting: 128MB) and
SHMSEG (recommended setting: 15). These
parameters have an influence on the MySQL database engine
to create user buffer pools.
SFNOLIM and HFNOLIM
should be at maximum 2048.
NPROC should be set to at least
3000/4000 (depends on number of users).
We also recommend using the following formulas to
calculate values for SEMMSL,
SEMMNS, and SEMMNU:
SEMMSL = 13
13 is what has been found to be the best for both Progress
and MySQL.
SEMMNS = SEMMSL × number of db servers to be run on the system
Set SEMMNS to the value of
SEMMSL multiplied by the number of
database servers (maximum) that you are running on the
system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the
value of SEMMNS. You could probably set
this to 75% of SEMMNS, but this is a
conservative estimate.
2.13.5.10. SCO UnixWare 7.1.x and OpenUNIX 8.0.0 Notes
We recommend using the latest production release of MySQL.
Should you choose to use an older release of MySQL on UnixWare
7.1.x, you must use a version of MySQL at least as recent as
3.22.13 to get fixes for some portability and OS problems.
We have been able to compile MySQL with the following
configure command on UnixWare 7.1.x:
If you want to use gcc, you must use
gcc 2.95.3 or newer.
CC=gcc CXX=g++ ... ./configure ...
The version of Berkeley DB that comes with either UnixWare
7.1.4 or OpenServer 6.0.0 is not used when building MySQL.
MySQL instead uses its own version of Berkeley DB. The
configure command needs to build both a
static and a dynamic library in
src_directory/bdb/build_unix/,
but it does not with MySQL's own BDB
version. The workaround is as follows.
Configure as normal for MySQL.
cd bdb/build_unix/
cp -p Makefile Makefile.sav
Use same options and run
../dist/configure.
Run gmake.
cp -p Makefile.sav Makefile
Change to top source directory and run
gmake.
This allows both the shared and dynamic libraries to be made
and work.
The UnixWare 7 file size limit is 1 TB with VXFS. Some OS
utilities have a limitation of 2GB.
On UnixWare 7.1.4 you do not need to do anything to get large
file support, but to enable large file support on prior
versions of UnixWare 7.1.x, run fsadm.
By default, the entries in
/etc/conf/cf.d/mtune are set as follows:
Value Default Min Max
----- ------- --- ---
SVMMLIM 0x9000000 0x1000000 0x7FFFFFFF
HVMMLIM 0x9000000 0x1000000 0x7FFFFFFF
To make changes to the kernel, use the idtune
name parameter command.
idtune modifies the
/etc/conf/cf.d/stune file for you. We
recommend setting the kernel values by executing the following
commands as root:
Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6
We recommend tuning the system, but the proper parameter
values to use depend on the number of users accessing the
application or database and size the of the database (that is,
the used buffer pool). The following kernel parameters can be
set with idtune:
SHMMAX (recommended setting: 128MB) and
SHMSEG (recommended setting: 15). These
parameters have an influence on the MySQL database engine
to create user buffer pools.
SFNOLIM and HFNOLIM
should be at maximum 2048.
NPROC should be set to at least
3000/4000 (depends on number of users).
We also recommend using the following formulas to
calculate values for SEMMSL,
SEMMNS, and SEMMNU:
SEMMSL = 13
13 is what has been found to be the best for both Progress
and MySQL.
SEMMNS = SEMMSL × number of db servers to be run on the system
Set SEMMNS to the value of
SEMMSL multiplied by the number of
database servers (maximum) that you are running on the
system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the
value of SEMMNS. You could probably set
this to 75% of SEMMNS, but this is a
conservative estimate.
2.13.6. OS/2 Notes
MySQL uses quite a few open files. Because of this, you should
add something like the following to your
CONFIG.SYS file:
SET EMXOPT=-c -n -h1024
If you do not do this, you may encounter the following error:
File 'xxxx' not found (Errcode: 24)
When using MySQL with OS/2 Warp 3, FixPack 29 or above is
required. With OS/2 Warp 4, FixPack 4 or above is required. This
is a requirement of the Pthreads library. MySQL must be
installed on a partition with a type that supports long
filenames, such as HPFS, FAT32, and so on.
The INSTALL.CMD script must be run from
OS/2's own CMD.EXE and may not work with
replacement shells such as 4OS2.EXE.
The scripts/mysql-install-db script has
been renamed. It is called install.cmd and
is a REXX script, which sets up the default MySQL security
settings and creates the WorkPlace Shell icons for MySQL.
Dynamic module support is compiled in but not fully tested.
Dynamic modules should be compiled using the Pthreads runtime
library.
Note: Due to limitations in
OS/2, UDF module name stems must not exceed eight characters.
Modules are stored in the /mysql2/udf
directory; the safe-mysqld.cmd script puts
this directory in the BEGINLIBPATH
environment variable. When using UDF modules, specified
extensions are ignored---it is assumed to be
.udf. For example, in Unix, the shared
module might be named example.so and you
would load a function from it like this:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example.so';
In OS/2, the module would be named
example.udf, but you would not specify the
module extension:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example';
Perl support for MySQL is provided by means of the
DBI/DBD client interface.
The interface requires Perl 5.6.1 or later. It does not
work if you have an older version of Perl.
If you want to use transactions with Perl DBI, you need to have
DBD::mysql version 1.2216 or newer.
DBD::mysql 2.9003 or newer is recommended.
If you are using the MySQL 4.1 or newer client library, you must
use DBD::mysql 2.9003 or newer.
Perl support is not included with MySQL distributions. You can
obtain the necessary modules from
http://search.cpan.org for Unix, or by using the
ActiveState ppm program on Windows. The
following sections describe how to do this.
MySQL Perl support requires that you have installed MySQL client
programming support (libraries and header files). Most
installation methods install the necessary files. However, if
you installed MySQL from RPM files on Linux, be sure that you've
installed the developer RPM. The client programs are in the
client RPM, but client programming support is in the developer
RPM.
If you want to install Perl support, the files you need can be
obtained from the CPAN (Comprehensive Perl Archive Network) at
http://search.cpan.org.
The easiest way to install Perl modules on Unix is to use the
CPAN module. For example:
The DBD::mysql installation runs a number of
tests. These tests attempt to connect to the local MySQL server
using the default username and password. (The default username
is your login name on Unix, and ODBC on
Windows. The default password is “no password.”) If
you cannot connect to the server with those values (for example,
if your account has a password), the tests fail. You can use
force install DBD::mysql to ignore the failed
tests.
DBI requires the
Data::Dumper module. It may be installed; if
not, you should install it before installing
DBI.
It is also possible to download the module distributions in the
form of compressed tar archives and build the
modules manually. For example, to unpack and build a DBI
distribution, use a procedure such as this:
Unpack the distribution into the current directory:
shell> gunzip < DBI-VERSION.tar.gz | tar xvf -
This command creates a directory named
DBI-VERSION.
Change location into the top-level directory of the unpacked
distribution:
shell> cd DBI-VERSION
Build the distribution and compile everything:
shell> perl Makefile.PL
shell> make
shell> make test
shell> make install
The make test command is important because it
verifies that the module is working. Note that when you run that
command during the DBD::mysql installation to
exercise the interface code, the MySQL server must be running or
the test fails.
It is a good idea to rebuild and reinstall the
DBD::mysql distribution whenever you install
a new release of MySQL, particularly if you notice symptoms such
as that all your DBI scripts fail after you
upgrade MySQL.
This procedure should work with ActiveState Perl 5.6 or newer.
If you cannot get the procedure to work, you should install the
MyODBC driver instead and connect to the MySQL server through
ODBC:
use DBI;
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
die "Got error $DBI::errstr when connecting to $dsn\n";
2.14.3. Problems Using the Perl DBI/DBD
Interface
If Perl reports that it cannot find the
../mysql/mysql.so module, the problem is
probably that Perl cannot locate the
libmysqlclient.so shared library. You
should be able to fix this problem by one of the following
methods:
Compile the DBD::mysql distribution with
perl Makefile.PL -static -config rather
than perl Makefile.PL.
Copy libmysqlclient.so to the directory
where your other shared libraries are located (probably
/usr/lib or /lib).
Modify the -L options used to compile
DBD::mysql to reflect the actual location
of libmysqlclient.so.
On Linux, you can add the pathname of the directory where
libmysqlclient.so is located to the
/etc/ld.so.conf file.
Add the pathname of the directory where
libmysqlclient.so is located to the
LD_RUN_PATH environment variable. Some
systems use LD_LIBRARY_PATH instead.
Note that you may also need to modify the -L
options if there are other libraries that the linker fails to
find. For example, if the linker cannot find
libc because it is in
/lib and the link command specifies
-L/usr/lib, change the -L
option to -L/lib or add -L/lib
to the existing link command.
If you get the following errors from
DBD::mysql, you are probably using
gcc (or using an old binary compiled with
gcc):
/usr/bin/perl: can't resolve symbol '__moddi3'
/usr/bin/perl: can't resolve symbol '__divdi3'
Add -L/usr/lib/gcc-lib/... -lgcc to the link
command when the mysql.so library gets
built (check the output from make for
mysql.so when you compile the Perl client).
The -L option should specify the pathname of
the directory where libgcc.a is located on
your system.
Another cause of this problem may be that Perl and MySQL are not
both compiled with gcc. In this case, you can
solve the mismatch by compiling both with
gcc.
You may see the following error from
DBD::mysql when you run the tests:
t/00base............install_driver(mysql) failed:
Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
This means that you need to include the -lz
compression library on the link line. That can be done by
changing the following line in the file
lib/DBD/mysql/Install.pm:
$sysliblist .= " -lm";
Change that line to:
$sysliblist .= " -lm -lz";
After this, you must run make
realclean and then proceed with the installation from
the beginning.
If you want to install DBI on SCO, you have to edit the
Makefile in
DBI-xxx and each subdirectory. Note
that the following assumes gcc 2.95.2 or
newer:
These changes are necessary because the Perl dynaloader does not
load the DBI modules if they were compiled
with icc or cc.
If you want to use the Perl module on a system that does not
support dynamic linking (such as SCO), you can generate a static
version of Perl that includes DBI and
DBD::mysql. The way this works is that you
generate a version of Perl with the DBI code
linked in and install it on top of your current Perl. Then you
use that to build a version of Perl that additionally has the
DBD code linked in, and install that.
On SCO, you must have the following environment variables set:
First, create a Perl that includes a statically linked
DBI module by running these commands in the
directory where your DBI distribution is
located:
shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl
Then you must install the new Perl. The output of make
perl indicates the exact make
command you need to execute to perform the installation. On SCO,
this is make -f Makefile.aperl inst_perl
MAP_TARGET=perl.
Next, use the just-created Perl to create another Perl that also
includes a statically linked DBD::mysql by
running these commands in the directory where your
DBD::mysql distribution is located:
shell> perl Makefile.PL -static -config
shell> make
shell> make install
shell> make perl
Finally, you should install this new Perl. Again, the output of
make perl indicates the command to use.
