704
701
2.1.5. Installation Layouts
706
This section describes the default layout of the directories
707
created by installing binary or source distributions provided by
708
Sun Microsystems, Inc. A distribution provided by another vendor
709
might use a layout different from those shown here.
711
Installations created from our Linux RPM distributions result in
712
files under the following system directories.
713
Directory Contents of Directory
714
/usr/bin Client programs and scripts
715
/usr/sbin The mysqld server
716
/var/lib/mysql Log files, databases
717
/usr/share/info Manual in Info format
718
/usr/share/man Unix manual pages
719
/usr/include/mysql Include (header) files
720
/usr/lib/mysql Libraries
721
/usr/share/mysql Error message and character set files
722
/usr/share/sql-bench Benchmarks
724
On Unix, a tar file binary distribution is installed by unpacking
725
it at the installation location you choose (typically
726
/usr/local/mysql) and creates the following directories in that
728
Directory Contents of Directory
729
bin Client programs and the mysqld server
730
data Log files, databases
731
docs Manual in Info format
732
man Unix manual pages
733
include Include (header) files
735
scripts mysql_install_db
736
share/mysql Error message files
739
A source distribution is installed after you configure and compile
740
it. By default, the installation step installs files under
741
/usr/local, in the following subdirectories.
742
Directory Contents of Directory
743
bin Client programs and scripts
744
include/mysql Include (header) files
745
Docs Manual in Info, CHM formats
746
man Unix manual pages
748
libexec The mysqld server
749
share/mysql Error message files
750
sql-bench Benchmarks and crash-me test
751
var Databases and log files
753
Within its installation directory, the layout of a source
754
installation differs from that of a binary installation in the
757
* The mysqld server is installed in the libexec directory rather
758
than in the bin directory.
760
* The data directory is var rather than data.
762
* mysql_install_db is installed in the bin directory rather than
763
in the scripts directory.
765
* The header file and library directories are include/mysql and
766
lib/mysql rather than include and lib.
768
You can create your own binary installation from a compiled source
769
distribution by executing the scripts/make_binary_distribution
770
script from the top directory of the source distribution.
703
The installation layout differs for different installation types
704
(for example, native packages, binary tarballs, and source
705
tarballs), which can lead to confusion when managing different
706
systems or using different installation sources. The individual
707
layouts are given in the corresponding installation type or
708
platform chapter, as described following. Note that the layout of
709
installations from vendors other than Oracle may differ from these
712
* Section 2.3.1, "MySQL Installation Layout on Microsoft
715
* Section 2.11.1, "MySQL Layout for Source Installation"
717
* Section 2.2, "MySQL Installation Layout for Generic Unix/Linux
720
* Section 2.5.1, "MySQL Installation Layout for Linux RPM"
722
* Section 2.4.2, "MySQL Installation Layout on Mac OS X"
724
2.1.6. Compiler-Specific Build Characteristics
726
In some cases, the compiler used to build MySQL affects the
727
features available for use. The notes in this section apply for
728
binary distributions provided by Oracle Corporation or that you
729
compile yourself from source.
731
icc (Intel C++ Compiler) Builds
733
A server built with icc has these characteristics:
735
* SSL support is not included.
737
* InnoDB Plugin is not included.
772
739
2.2. Installing MySQL from Generic Binaries on Unix/Linux
774
This section covers the installation of MySQL binary distributions
775
that are provided for various platforms in the form of compressed
776
tar files (files with a .tar.gz extension). See Section 2.2,
777
"Installing MySQL from Generic Binaries on Unix/Linux," for a
741
Oracle provides a set of binary distributions of MySQL. These
742
include binary distributions in the form of compressed tar files
743
(files with a .tar.gz extension) for a number of platforms, as
744
well as binaries in platform-specific package formats for selected
747
This section covers the installation of MySQL from a compressed
748
tar file binary distribution. For other platform-specific package
749
formats, see the other platform-specific sections. For example,
750
for Windows distributions, see Section 2.3, "Installing MySQL on
780
753
To obtain MySQL, see Section 2.1.3, "How to Get MySQL."
782
Sun Microsystems, Inc. provides a set of binary distributions of
783
MySQL. In addition to binaries provided in platform-specific
784
package formats, we offer binary distributions for a number of
785
platforms in the form of compressed tar files (.tar.gz files). For
786
Windows distributions, see Section 2.5, "Installing MySQL on
789
If you want to compile a debug version of MySQL from a source
790
distribution, you should add --with-debug or --with-debug=full to
791
the configure command used to configure the distribution and
792
remove any -fomit-frame-pointer options.
794
MySQL tar file binary distributions have names of the form
795
mysql-VERSION-OS.tar.gz, where VERSION is a number (for example,
796
5.1.41), and OS indicates the type of operating system for which
797
the distribution is intended (for example, pc-linux-i686).
799
In addition to these generic packages, we also offer binaries in
800
platform-specific package formats for selected platforms. See the
801
platform specific sections for more information, for more
802
information on how to install these.
804
You need the following tools to install a MySQL tar file binary
807
* GNU gunzip to uncompress the distribution.
809
* A reasonable tar to unpack the distribution. GNU tar is known
810
to work. Some operating systems come with a preinstalled
811
version of tar that is known to have problems. For example,
812
the tar provided with early versions of Mac OS X, SunOS 4.x,
813
Solaris 8, Solaris 9, Solaris 10 and OpenSolaris, and HP-UX
814
are known to have problems with long file names. On Mac OS X,
815
you can use the preinstalled gnutar program. On Solaris 10 and
816
OpenSolaris you can use the preinstalled gtar. On other
817
systems with a deficient tar, you should install GNU tar
820
If you run into problems and need to file a bug report, please use
821
the instructions in Section 1.6, "How to Report Bugs or Problems."
823
The basic commands that you must execute to install and use a
824
MySQL binary distribution are:
825
shell> groupadd mysql
826
shell> useradd -g mysql mysql
828
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
829
shell> ln -s full-path-to-mysql-VERSION-OS mysql
831
shell> chown -R mysql .
832
shell> chgrp -R mysql .
833
shell> scripts/mysql_install_db --user=mysql
834
shell> chown -R root .
835
shell> chown -R mysql data
836
shell> bin/mysqld_safe --user=mysql &
840
This procedure does not set up any passwords for MySQL accounts.
841
After following the procedure, proceed to Section 2.13,
842
"Post-Installation Setup and Testing."
844
A more detailed version of the preceding description for
845
installing a binary distribution follows:
847
1. Add a login user and group for mysqld to run as:
848
shell> groupadd mysql
849
shell> useradd -g mysql mysql
850
These commands add the mysql group and the mysql user. The
851
syntax for useradd and groupadd may differ slightly on
852
different versions of Unix, or they may have different names
853
such as adduser and addgroup.
854
You might want to call the user and group something else
855
instead of mysql. If so, substitute the appropriate name in
858
2. Pick the directory under which you want to unpack the
859
distribution and change location into it. In the following
860
example, we unpack the distribution under /usr/local. (The
861
instructions, therefore, assume that you have permission to
862
create files and directories in /usr/local. If that directory
863
is protected, you must perform the installation as root.)
866
3. Obtain a distribution file using the instructions in Section
867
2.1.3, "How to Get MySQL." For a given release, binary
868
distributions for all platforms are built from the same MySQL
871
4. Unpack the distribution, which creates the installation
872
directory. Then create a symbolic link to that directory:
873
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
874
shell> ln -s full-path-to-mysql-VERSION-OS mysql
875
The tar command creates a directory named mysql-VERSION-OS.
876
The ln command makes a symbolic link to that directory. This
877
lets you refer more easily to the installation directory as
879
With GNU tar, no separate invocation of gunzip is necessary.
880
You can replace the first line with the following alternative
881
command to uncompress and extract the distribution:
882
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
884
5. Change location into the installation directory:
886
You will find several files and subdirectories in the mysql
887
directory. The most important for installation purposes are
888
the bin and scripts subdirectories:
890
+ The bin directory contains client programs and the
891
server. You should add the full path name of this
892
directory to your PATH environment variable so that your
893
shell finds the MySQL programs properly. See Section
894
2.14, "Environment Variables."
896
+ The scripts directory contains the mysql_install_db
897
script used to initialize the mysql database containing
898
the grant tables that store the server access
901
6. Ensure that the distribution contents are accessible to mysql.
902
If you unpacked the distribution as mysql, no further action
903
is required. If you unpacked the distribution as root, its
904
contents will be owned by root. Change its ownership to mysql
905
by executing the following commands as root in the
906
installation directory:
907
shell> chown -R mysql .
908
shell> chgrp -R mysql .
909
The first command changes the owner attribute of the files to
910
the mysql user. The second changes the group attribute to the
913
7. If you have not installed MySQL before, you must create the
914
MySQL data directory and initialize the grant tables:
915
shell> scripts/mysql_install_db --user=mysql
916
If you run the command as root, include the --user option as
917
shown. If you run the command while logged in as that user,
918
you can omit the --user option.
919
The command should create the data directory and its contents
920
with mysql as the owner.
921
After creating or updating the grant tables, you need to
922
restart the server manually.
924
8. Most of the MySQL installation can be owned by root if you
925
like. The exception is that the data directory must be owned
926
by mysql. To accomplish this, run the following commands as
927
root in the installation directory:
928
shell> chown -R root .
929
shell> chown -R mysql data
931
9. If you want MySQL to start automatically when you boot your
932
machine, you can copy support-files/mysql.server to the
933
location where your system has its startup files. More
934
information can be found in the support-files/mysql.server
935
script itself and in Section 2.13.1.2, "Starting and Stopping
936
MySQL Automatically."
937
10. You can set up new accounts using the bin/mysql_setpermission
938
script if you install the DBI and DBD::mysql Perl modules. See
939
Section 4.6.14, "mysql_setpermission --- Interactively Set
940
Permissions in Grant Tables." For Perl module installation
941
instructions, see Section 2.15, "Perl Installation Notes."
942
11. If you would like to use mysqlaccess and have the MySQL
943
distribution in some nonstandard location, you must change the
944
location where mysqlaccess expects to find the mysql client.
945
Edit the bin/mysqlaccess script at approximately line 18.
946
Search for a line that looks like this:
947
$MYSQL = '/usr/local/bin/mysql'; # path to mysql executable
948
Change the path to reflect the location where mysql actually
949
is stored on your system. If you do not do this, a Broken pipe
950
error will occur when you run mysqlaccess.
952
After everything has been unpacked and installed, you should test
953
your distribution. To start the MySQL server, use the following
955
shell> bin/mysqld_safe --user=mysql &
957
If you run the command as root, you must use the --user option as
958
shown. The value of the option is the name of the login account
959
that you created in the first step to use for running the server.
960
If you run the command while logged in as mysql, you can omit the
963
If the command fails immediately and prints mysqld ended, you can
964
find some information in the host_name.err file in the data
967
More information about mysqld_safe is given in Section 4.3.2,
968
"mysqld_safe --- MySQL Server Startup Script."
972
The accounts that are listed in the MySQL grant tables initially
973
have no passwords. After starting the server, you should set up
974
passwords for them using the instructions in Section 2.13,
975
"Post-Installation Setup and Testing."
977
2.3. MySQL Installation Using a Source Distribution
979
Before you proceed with an installation from source, first check
980
whether our binary is available for your platform and whether it
981
works for you. We put a great deal of effort into ensuring that
982
our binaries are built with the best possible options.
984
To obtain a source distribution for MySQL, Section 2.1.3, "How to
985
Get MySQL." If you want to build MySQL from source on Windows, see
986
Section 2.5.10, "Installing MySQL from Source on Windows."
988
MySQL source distributions are provided as compressed tar archives
989
and have names of the form mysql-VERSION.tar.gz, where VERSION is
990
a number like 5.1.41.
992
You need the following tools to build and install MySQL from
995
* GNU gunzip to uncompress the distribution.
997
* A reasonable tar to unpack the distribution. GNU tar is known
998
to work. Some operating systems come with a preinstalled
999
version of tar that is known to have problems. For example,
1000
the tar provided with early versions of Mac OS X, SunOS 4.x,
1001
Solaris 8, Solaris 9, Solaris 10 and OpenSolaris, and HP-UX
1002
are known to have problems with long file names. On Mac OS X,
1003
you can use the preinstalled gnutar program. On Solaris 10 and
1004
OpenSolaris you can use the preinstalled gtar. On other
1005
systems with a deficient tar, you should install GNU tar
1008
* A working ANSI C++ compiler. gcc 2.95.2 or later, SGI C++, and
1009
SunPro C++ are some of the compilers that are known to work.
1010
libg++ is not needed when using gcc. gcc 2.7.x has a bug that
1011
makes it impossible to compile some perfectly legal C++ files,
1012
such as sql/sql_base.cc. If you have only gcc 2.7.x, you must
1013
upgrade your gcc to be able to compile MySQL. gcc 2.8.1 is
1014
also known to have problems on some platforms, so it should be
1015
avoided if a newer compiler exists for the platform. gcc
1016
2.95.2 or later is recommended.
1018
* A good make program. GNU make is always recommended and is
1019
sometimes required. (BSD make fails, and vendor-provided make
1020
implementations may fail as well.) If you have problems, use
1021
GNU make 3.75 or newer.
1023
* libtool 1.5.24 or later is also recommended.
1025
If you are using a version of gcc recent enough to understand the
1026
-fno-exceptions option, it is very important that you use this
1027
option. Otherwise, you may compile a binary that crashes randomly.
1028
Also use -felide-constructors and -fno-rtti along with
1029
-fno-exceptions. When in doubt, do the following:
1030
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
1031
-fno-exceptions -fno-rtti" ./configure \
1032
--prefix=/usr/local/mysql --enable-assembler \
1033
--with-mysqld-ldflags=-all-static
1035
On most systems, this gives you a fast and stable binary.
1037
If you run into problems and need to file a bug report, please use
1038
the instructions in Section 1.6, "How to Report Bugs or Problems."
1040
2.3.1. Source Installation Overview
1042
The basic commands that you must execute to install a MySQL source
1044
shell> groupadd mysql
1045
shell> useradd -g mysql mysql
1046
shell> gunzip < mysql-VERSION.tar.gz | tar -xvf -
1047
shell> cd mysql-VERSION
1048
shell> ./configure --prefix=/usr/local/mysql
1051
shell> cp support-files/my-medium.cnf /etc/my.cnf
1052
shell> cd /usr/local/mysql
1053
shell> chown -R mysql .
1054
shell> chgrp -R mysql .
1055
shell> bin/mysql_install_db --user=mysql
1056
shell> chown -R root .
1057
shell> chown -R mysql var
1058
shell> bin/mysqld_safe --user=mysql &
1060
If you start from a source RPM, do the following:
1061
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm
1063
This makes a binary RPM that you can install. For older versions
1064
of RPM, you may have to replace the command rpmbuild with rpm
1069
This procedure does not set up any passwords for MySQL accounts.
1070
After following the procedure, proceed to Section 2.13,
1071
"Post-Installation Setup and Testing," for post-installation setup
1074
A more detailed version of the preceding description for
1075
installing MySQL from a source distribution follows:
1077
1. Add a login user and group for mysqld to run as:
1078
shell> groupadd mysql
1079
shell> useradd -g mysql mysql
1080
These commands add the mysql group and the mysql user. The
1081
syntax for useradd and groupadd may differ slightly on
1082
different versions of Unix, or they may have different names
1083
such as adduser and addgroup.
1084
You might want to call the user and group something else
1085
instead of mysql. If so, substitute the appropriate name in
1086
the following steps.
1088
2. Perform the following steps as the mysql user, except as
1091
3. Pick the directory under which you want to unpack the
1092
distribution and change location into it.
1094
4. Obtain a distribution file using the instructions in Section
1095
2.1.3, "How to Get MySQL."
1097
5. Unpack the distribution into the current directory:
1098
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -
1099
This command creates a directory named mysql-VERSION.
1100
With GNU tar, no separate invocation of gunzip is necessary.
1101
You can use the following alternative command to uncompress
1102
and extract the distribution:
1103
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
1105
6. Change location into the top-level directory of the unpacked
1107
shell> cd mysql-VERSION
1108
Note that currently you must configure and build MySQL from
1109
this top-level directory. You cannot build it in a different
1112
7. Configure the release and compile everything:
1113
shell> ./configure --prefix=/usr/local/mysql
1115
When you run configure, you might want to specify other
1116
options. Run ./configure --help for a list of options. Section
1117
2.3.2, "Typical configure Options," discusses some of the more
1119
If configure fails and you are going to send mail to a MySQL
1120
mailing list to ask for assistance, please include any lines
1121
from config.log that you think can help solve the problem.
1122
Also include the last couple of lines of output from
1123
configure. To file a bug report, please use the instructions
1124
in Section 1.6, "How to Report Bugs or Problems."
1125
If the compile fails, see Section 2.3.4, "Dealing with
1126
Problems Compiling MySQL," for help.
1128
8. Install the distribution:
1130
You might need to run this command as root.
1131
If you want to set up an option file, use one of those present
1132
in the support-files directory as a template. For example:
1133
shell> cp support-files/my-medium.cnf /etc/my.cnf
1134
You might need to run this command as root.
1135
If you want to configure support for InnoDB tables, you should
1136
edit the /etc/my.cnf file, remove the # character before the
1137
option lines that start with innodb_..., and modify the option
1138
values to be what you want. See Section 4.2.3.3, "Using Option
1139
Files," and Section 13.6.2, "InnoDB Configuration."
1141
9. Change location into the installation directory:
1142
shell> cd /usr/local/mysql
1143
10. If you ran the make install command as root, the installed
1144
files will be owned by root. Ensure that the installation is
1145
accessible to mysql by executing the following commands as
1146
root in the installation directory:
1147
shell> chown -R mysql .
1148
shell> chgrp -R mysql .
1149
The first command changes the owner attribute of the files to
1150
the mysql user. The second changes the group attribute to the
1152
11. If you have not installed MySQL before, you must create the
1153
MySQL data directory and initialize the grant tables:
1154
shell> bin/mysql_install_db --user=mysql
1155
If you run the command as root, include the --user option as
1156
shown. If you run the command while logged in as mysql, you
1157
can omit the --user option.
1158
The command should create the data directory and its contents
1159
with mysql as the owner.
1160
After using mysql_install_db to create the grant tables for
1161
MySQL, you must restart the server manually. The mysqld_safe
1162
command to do this is shown in a later step.
1163
12. Most of the MySQL installation can be owned by root if you
1164
like. The exception is that the data directory must be owned
1165
by mysql. To accomplish this, run the following commands as
1166
root in the installation directory:
1167
shell> chown -R root .
1168
shell> chown -R mysql var
1169
13. If you want MySQL to start automatically when you boot your
1170
machine, you can copy support-files/mysql.server to the
1171
location where your system has its startup files. More
1172
information can be found in the support-files/mysql.server
1173
script itself; see also Section 2.13.1.2, "Starting and
1174
Stopping MySQL Automatically."
1175
14. You can set up new accounts using the bin/mysql_setpermission
1176
script if you install the DBI and DBD::mysql Perl modules. See
1177
Section 4.6.14, "mysql_setpermission --- Interactively Set
1178
Permissions in Grant Tables." For Perl module installation
1179
instructions, see Section 2.15, "Perl Installation Notes."
1181
After everything has been installed, you should test your
1182
distribution. To start the MySQL server, use the following
1184
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
1186
If you run the command as root, you should use the --user option
1187
as shown. The value of the option is the name of the login account
1188
that you created in the first step to use for running the server.
1189
If you run the command while logged in as that user, you can omit
1192
If the command fails immediately and prints mysqld ended, you can
1193
find some information in the host_name.err file in the data
1196
More information about mysqld_safe is given in Section 4.3.2,
1197
"mysqld_safe --- MySQL Server Startup Script."
1201
The accounts that are listed in the MySQL grant tables initially
1202
have no passwords. After starting the server, you should set up
1203
passwords for them using the instructions in Section 2.13,
1204
"Post-Installation Setup and Testing."
1206
2.3.2. Typical configure Options
1208
The configure script gives you a great deal of control over how
1209
you configure a MySQL source distribution. Typically you do this
1210
using options on the configure command line. You can also affect
1211
configure using certain environment variables. See Section 2.14,
1212
"Environment Variables." For a full list of options supported by
1213
configure, run this command:
1214
shell> ./configure --help
1216
A list of the available configure options is provided in the table
1219
Table 2.1. Build (configure) Reference
1220
Formats Description Default Introduced Removed
1221
--bindir=DIR User executables EPREFIX/bin
1222
--build=BUILD Configure for building on BUILD guessed
1223
--cache-file=FILE Cache test results in FILE disabled
1224
-C Alias for `--cache-file=config.cache'
1226
--datadir=DIR Read-only architecture-independent data PREFIX/share
1228
--disable-FEATURE Do not include FEATURE
1229
--disable-dependency-tracking Disable dependency tracking
1230
--disable-grant-options Disable GRANT options
1231
--disable-largefile Omit support for large files
1232
--disable-libtool-lock Disable libtool lock
1233
--disable-thread-safe-client Compile the client without threads
1235
--enable-FEATURE Enable FEATURE
1236
--enable-assembler Use assembler versions of some string functions
1238
--enable-debug-sync Compile in Debug Sync facility 5.1.41
1239
--enable-dependency-tracking Do not reject slow dependency
1241
--enable-fast-install Optimize for fast installation yes
1242
--enable-local-infile Enable LOAD DATA LOCAL INFILE disabled
1243
--enable-shared Build shared libraries yes
1244
--enable-static Build static libraries yes
1245
--enable-thread-safe-client Compile the client with threads
1246
--exec-prefix=EPREFIX Install architecture-dependent files in
1248
-h Display this help and exit
1250
--help=short Display options specific to this package
1251
--help=recursive Display the short help of all the included
1253
--host=HOST Cross-compile to build programs to run on HOST
1254
--includedir=DIR C header files PREFIX/include
1255
--infodir=DIR Info documentation PREFIX/info
1256
--libdir=DIR Object code libraries EPREFIX/lib
1257
--libexecdir=DIR Program executables EPREFIX/libexec
1258
--localstatedir=DIR Modifiable single-machine data PREFIX/var
1259
--mandir=DIR man documentation PREFIX/man
1260
-n Do not create output files
1262
--oldincludedir=DIR C header files for non-gcc /usr/include
1263
--prefix=PREFIX Install architecture-independent files in PREFIX
1265
--program-prefix=PREFIX Prepend PREFIX to installed program names
1267
--program-suffix=SUFFIX Append SUFFIX to installed program names
1269
--program-transform-name=PROGRAM run sed PROGRAM on installed
1271
-q Do not print `checking...' messages
1273
--sbindir=DIR System admin executables EPREFIX/sbin
1274
--sharedstatedir=DIR Modifiable architecture-independent data
1276
--srcdir=DIR Find the sources in DIR configure directory or ..
1277
--sysconfdir=DIR Read-only single-machine data PREFIX/etc
1278
--target=TARGET Configure for building compilers for TARGET
1279
-V Display version information and exit
1281
--with-PACKAGE Use PACKAGE
1282
--with-archive-storage-engine Enable the Archive Storage Engine no
1284
--with-atomic-ops Implement atomic operations using pthread
1285
rwlocks or atomic CPU instructions for multi-processor 5.1.12
1286
--with-berkeley-db Use BerkeleyDB located in DIR no
1287
--with-berkeley-db-includes Find Berkeley DB headers in DIR
1288
--with-berkeley-db-libs Find Berkeley DB libraries in DIR
1289
--with-big-tables Support tables with more than 4 G rows even on
1291
--with-blackhole-storage-engine Enable the Blackhole Storage
1293
--with-charset Default character set
1294
--with-client-ldflags Extra linking arguments for clients
1295
--with-collation Default collation
1296
--with-comment Comment about compilation environment
1297
--with-csv-storage-engine Enable the CSV Storage Engine yes
1298
--with-darwin-mwcc Use Metrowerks CodeWarrior wrappers on OS
1300
--with-debug Add debug code 5.1.7
1301
--with-debug=full Add debug code (adds memory checker, very slow)
1303
--with-embedded-privilege-control Build parts to check user's
1304
privileges (only affects embedded library)
1305
--with-embedded-server Build the embedded server
1306
--with-error-inject Enable error injection in MySQL Server
1308
--with-example-storage-engine Enable the Example Storage Engine no
1310
--with-extra-charsets Use charsets in addition to default
1311
--with-fast-mutexes Compile with fast mutexes enabled 5.1.5
1312
--with-federated-storage-engine Enable federated storage engine no
1314
--with-gnu-ld Assume the C compiler uses GNU ld no
1315
--with-innodb Enable innobase storage engine no 5.1.3 5.1.9
1316
--with-lib-ccflags Extra CC options for libraries
1317
--with-libwrap=DIR Compile in libwrap (tcp_wrappers) support
1318
--with-low-memory Try to use less memory to compile to avoid
1320
--with-machine-type Set the machine type, like "powerpc"
1321
--with-max-indexes=N Sets the maximum number of indexes per table
1323
--with-mysqld-ldflags Extra linking arguments for mysqld
1324
--with-mysqld-libs Extra libraries to link with for mysqld
1325
--with-mysqld-user What user the mysqld daemon shall be run as
1327
--with-mysqlmanager Build the mysqlmanager binary Build if server
1329
--with-named-curses-libs Use specified curses libraries
1330
--with-named-thread-libs Use specified thread libraries
1331
--with-ndb-ccflags Extra CC options for ndb compile
1332
--with-ndb-docs Include the NDB Cluster ndbapi and mgmapi
1334
--with-ndb-port Port for NDB Cluster management server
1335
--with-ndb-port-base Port for NDB Cluster management server
1336
--with-ndb-sci=DIR Provide MySQL with a custom location of sci
1338
--with-ndb-test Include the NDB Cluster ndbapi test programs
1339
--with-ndbcluster Include the NDB Cluster table handler no
1340
--with-openssl=DIR Include the OpenSSL support
1341
--with-openssl-includes Find OpenSSL headers in DIR
1342
--with-openssl-libs Find OpenSSL libraries in DIR
1343
--with-other-libc=DIR Link against libc and other standard
1344
libraries installed in the specified nonstandard location
1345
--with-pic Try to use only PIC/non-PIC objects Use both
1346
--with-plugin-PLUGIN Forces the named plugin to be linked into
1347
mysqld statically 5.1.11
1348
--with-plugins Plugins to include in mysqld none 5.1.11
1349
--with-pstack Use the pstack backtrace library
1350
--with-pthread Force use of pthread library
1351
--with-row-based-replication Include row-based replication 5.1.5
1353
--with-server-suffix Append value to the version string
1354
--with-ssl=DIR Include SSL support 5.1.11
1355
--with-system-type Set the system type, like "sun-solaris10"
1356
--with-tags Include additional configurations automatic
1357
--with-tcp-port Which port to use for MySQL services 3306
1358
--with-unix-socket-path Where to put the unix-domain socket
1359
--with-yassl Include the yaSSL support
1360
--with-zlib-dir=no|bundled|DIR Provide MySQL with a custom
1361
location of compression library
1362
--without-PACKAGE Do not use PACKAGE
1363
--without-bench Skip building of the benchmark suite
1364
--without-debug Build a production version without debugging code
1366
--without-docs Skip building of the documentation
1367
--without-extra-tools Skip building utilities in the tools
1369
--without-geometry Do not build geometry-related parts
1370
--without-libedit Use system libedit instead of bundled copy
1371
--without-man Skip building of the man pages
1372
--without-ndb-binlog Disable ndb binlog 5.1.6
1373
--without-ndb-debug Disable special ndb debug features
1374
--without-plugin-PLUGIN Exclude PLUGIN 5.1.11
1375
--without-query-cache Do not build query cache
1376
--without-readline Use system readline instead of bundled copy
1378
--without-row-based-replication Don't include row-based
1379
replication 5.1.7 5.1.14
1380
--without-server Only build the client
1381
--without-uca Skip building of the national Unicode collations
1383
Some of the configure options available are described here. For
1384
options that may be of use if you have difficulties building
1385
MySQL, see Section 2.3.4, "Dealing with Problems Compiling MySQL."
1387
* To compile just the MySQL client libraries and client programs
1388
and not the server, use the --without-server option:
1389
shell> ./configure --without-server
1390
If you have no C++ compiler, some client programs such as
1391
mysql cannot be compiled because they require C++.. In this
1392
case, you can remove the code in configure that tests for the
1393
C++ compiler and then run ./configure with the
1394
--without-server option. The compile step should still try to
1395
build all clients, but you can ignore any warnings about files
1396
such as mysql.cc. (If make stops, try make -k to tell it to
1397
continue with the rest of the build even if errors occur.)
1399
* If you want to build the embedded MySQL library (libmysqld.a),
1400
use the --with-embedded-server option.
1402
* If you don't want your log files and database directories
1403
located under /usr/local/var, use a configure command
1404
something like one of these:
1405
shell> ./configure --prefix=/usr/local/mysql
1406
shell> ./configure --prefix=/usr/local \
1407
--localstatedir=/usr/local/mysql/data
1408
The first command changes the installation prefix so that
1409
everything is installed under /usr/local/mysql rather than the
1410
default of /usr/local. The second command preserves the
1411
default installation prefix, but overrides the default
1412
location for database directories (normally /usr/local/var)
1413
and changes it to /usr/local/mysql/data.
1414
You can also specify the installation directory and data
1415
directory locations at server startup time by using the
1416
--basedir and --datadir options. These can be given on the
1417
command line or in an MySQL option file, although it is more
1418
common to use an option file. See Section 4.2.3.3, "Using
1421
* This option specifies the port number on which the server
1422
listens for TCP/IP connections. The default is port 3306. To
1423
listen on a different port, use a configure command like this:
1424
shell> ./configure --with-tcp-port=3307
1426
* If you are using Unix and you want the MySQL socket file
1427
location to be somewhere other than the default location
1428
(normally in the directory /tmp or /var/run), use a configure
1430
shell> ./configure \
1431
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
1432
The socket file name must be an absolute path name. You can
1433
also change the location of mysql.sock at server startup by
1434
using a MySQL option file. See Section B.5.4.5, "How to
1435
Protect or Change the MySQL Unix Socket File."
1437
* If you want to compile statically linked programs (for
1438
example, to make a binary distribution, to get better
1439
performance, or to work around problems with some Red Hat
1440
Linux distributions), run configure like this:
1441
shell> ./configure --with-client-ldflags=-all-static \
1442
--with-mysqld-ldflags=-all-static
1444
* If you are using gcc and don't have libg++ or libstdc++
1445
installed, you can tell configure to use gcc as your C++
1447
shell> CC=gcc CXX=gcc ./configure
1448
When you use gcc as your C++ compiler, it does not attempt to
1449
link in libg++ or libstdc++. This may be a good thing to do
1450
even if you have those libraries installed. Some versions of
1451
them have caused strange problems for MySQL users in the past.
1452
The following list indicates some compilers and environment
1453
variable settings that are commonly used with each one.
1456
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
1459
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
1460
-felide-constructors -fno-exceptions -fno-rtti"
1462
+ pgcc 2.90.29 or newer:
1463
CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \
1464
CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \
1465
-felide-constructors -fno-exceptions -fno-rtti"
1466
In most cases, you can get a reasonably optimized MySQL binary
1467
by using the options from the preceding list and adding the
1468
following options to the configure line:
1469
--prefix=/usr/local/mysql --enable-assembler \
1470
--with-mysqld-ldflags=-all-static
1471
The full configure line would, in other words, be something
1472
like the following for all recent gcc versions:
1473
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
1474
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
1475
--prefix=/usr/local/mysql --enable-assembler \
1476
--with-mysqld-ldflags=-all-static
1477
The binaries we provide on the MySQL Web site at
1478
http://dev.mysql.com/downloads/ are all compiled with full
1479
optimization and should be perfect for most users. See Section
1480
2.2, "Installing MySQL from Generic Binaries on Unix/Linux."
1481
There are some configuration settings you can tweak to build
1482
an even faster binary, but these are only for advanced users.
1483
See Section 7.5.1, "How Compiling and Linking Affects the
1485
If the build fails and produces errors about your compiler or
1486
linker not being able to create the shared library
1487
libmysqlclient.so.N (where N is a version number), you can
1488
work around this problem by giving the --disable-shared option
1489
to configure. In this case, configure does not build a shared
1490
libmysqlclient.so.N library.
1492
* By default, MySQL uses the latin1 (cp1252 West European)
1493
character set. To change the default set, use the
1494
--with-charset option:
1495
shell> ./configure --with-charset=CHARSET
1496
CHARSET may be one of binary, armscii8, ascii, big5, cp1250,
1497
cp1251, cp1256, cp1257, cp850, cp852, cp866, cp932, dec8,
1498
eucjpms, euckr, gb2312, gbk, geostd8, greek, hebrew, hp8,
1499
keybcs2, koi8r, koi8u, latin1, latin2, latin5, latin7, macce,
1500
macroman, sjis, swe7, tis620, ucs2, ujis, utf8. See Section
1501
9.2, "The Character Set Used for Data and Sorting."
1502
(Additional character sets might be available. Check the
1503
output from ./configure --help for the current list.)
1504
The default collation may also be specified. MySQL uses the
1505
latin1_swedish_ci collation by default. To change this, use
1506
the --with-collation option:
1507
shell> ./configure --with-collation=COLLATION
1508
To change both the character set and the collation, use both
1509
the --with-charset and --with-collation options. The collation
1510
must be a legal collation for the character set. (Use the SHOW
1511
COLLATION statement to determine which collations are
1512
available for each character set.)
1513
With the configure option --with-extra-charsets=LIST, you can
1514
define which additional character sets should be compiled into
1515
the server. LIST is one of the following:
1517
+ A list of character set names separated by spaces
1519
+ complex to include all character sets that can't be
1522
+ all to include all character sets into the binaries
1523
Clients that want to convert characters between the server and
1524
the client should use the SET NAMES statement. See Section
1525
5.1.5, "Session System Variables," and Section 9.1.4,
1526
"Connection Character Sets and Collations."
1528
* To configure MySQL with debugging code, use the --with-debug
1530
shell> ./configure --with-debug
1531
This causes a safe memory allocator to be included that can
1532
find some errors and that provides output about what is
1533
happening. See MySQL Internals: Porting
1534
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
1535
As of MySQL 5.1.12, using --with-debug to configure MySQL with
1536
debugging support enables you to use the
1537
--debug="d,parser_debug" option when you start the server.
1538
This causes the Bison parser that is used to process SQL
1539
statements to dump a parser trace to the server's standard
1540
error output. Typically, this output is written to the error
1543
* To cause the Debug Sync facility to be compiled into the
1544
server, use the --enable-debug-sync option. This facility is
1545
used for testing and debugging. When compiled in, Debug Sync
1546
is disabled by default. To enable it, start mysqld with the
1547
--debug-sync-timeout=N option, where N is a timeout value
1548
greater than 0. (The default value is 0, which disables Debug
1549
Sync.) N becomes the default timeout for individual
1550
synchronization points.
1551
Debug Sync is also compiled in if you configure with the
1552
--with-debug option (which implies --enable-debug-sync),
1553
unless you also use the --disable-debug-sync option.
1554
For a description of the Debug Sync facility and how to use
1555
synchronization points, see MySQL Internals: Test
1557
(http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronizat
1559
The --enable-debug-sync and --disable-debug-sync options were
1560
added in MySQL 5.1.41.
1562
* If your client programs are using threads, you must compile a
1563
thread-safe version of the MySQL client library with the
1564
--enable-thread-safe-client configure option. This creates a
1565
libmysqlclient_r library with which you should link your
1566
threaded applications. See Section 21.9.16.2, "How to Make a
1569
* Some features require that the server be built with
1570
compression library support, such as the COMPRESS() and
1571
UNCOMPRESS() functions, and compression of the client/server
1572
protocol. The --with-zlib-dir=no|bundled|DIR option provides
1573
control over compression library support. The value no
1574
explicitly disables compression support. bundled causes the
1575
zlib library bundled in the MySQL sources to be used. A DIR
1576
path name specifies the directory in which to find the
1577
compression library sources.
1579
* It is possible to build MySQL with large table support using
1580
the --with-big-tables option.
1581
This option causes the variables that store table row counts
1582
to be declared as unsigned long long rather than unsigned
1583
long. This enables tables to hold up to approximately
1584
1.844E+19 ((2^32)^2) rows rather than 2^32 (~4.295E+09) rows.
1585
Previously it was necessary to pass -DBIG_TABLES to the
1586
compiler manually in order to enable this feature.
1588
* Run configure with the --disable-grant-options option to cause
1589
the --bootstrap, --skip-grant-tables, and --init-file options
1590
for mysqld to be disabled. For Windows, the configure.js
1591
script recognizes the DISABLE_GRANT_OPTIONS flag, which has
1592
the same effect. The capability is available as of MySQL
1595
* This option allows MySQL Community Server features to be
1596
enabled. Additional options may be required for individual
1597
features, such as --enable-profiling to enable statement
1598
profiling. This option was added in MySQL 5.1.24. It is
1599
enabled by default as of MySQL 5.1.28; to disable it, use
1600
--disable-community-features.
1602
* When given with --enable-community-features, the
1603
--enable-profiling option enables the statement profiling
1604
capability exposed by the SHOW PROFILE and SHOW PROFILES
1605
statements. (See Section 12.5.5.33, "SHOW PROFILES Syntax.")
1606
This option was added in MySQL 5.1.24. It is enabled by
1607
default as of MySQL 5.1.28; to disable it, use
1608
--disable-profiling.
1610
* See Section 2.1, "General Installation Guidance," for options
1611
that pertain to particular operating systems.
1613
* See Section 5.5.7.2, "Using SSL Connections," for options that
1614
pertain to configuring MySQL to support secure (encrypted)
1617
* Several configure options apply to plugin selection and
1619
--with-plugins=PLUGIN[,PLUGIN]...
1620
--with-plugins=GROUP
1621
--with-plugin-PLUGIN
1622
--without-plugin-PLUGIN
1623
PLUGIN is an individual plugin name such as csv or archive.
1624
As shorthand, GROUP is a configuration group name such as none
1625
(select no plugins) or all (select all plugins).
1626
You can build a plugin as static (compiled into the server) or
1627
dynamic (built as a dynamic library that must be installed
1628
using the INSTALL PLUGIN statement before it can be used).
1629
Some plugins might not support static or dynamic build.
1630
configure --help shows the following information pertaining to
1633
+ The plugin-related options
1635
+ The names of all available plugins
1637
+ For each plugin, a description of its purpose, which
1638
build types it supports (static or dynamic), and which
1639
plugin groups it is a part of.
1640
--with-plugins can take a list of one or more plugin names
1641
separated by commas, or a plugin group name. The named plugins
1642
are configured to be built as static plugins.
1643
--with-plugin-PLUGIN configures the given plugin to be built
1645
--without-plugin-PLUGIN disables the given plugin from being
1647
If a plugin is named both with a --with and --without option,
1648
the result is undefined.
1649
For any plugin that is not explicitly selected or disabled, it
1650
is selected to be built dynamically if it supports dynamic
1651
build, and not built if it does not support dynamic build.
1652
(Thus, in the case that no plugin options are given, all
1653
plugins that support dynamic build are selected to be built as
1654
dynamic plugins. Plugins that do not support dynamic build are
1657
2.3.3. Installing from the Development Source Tree
1661
You should read this section only if you are interested in helping
1662
us test our new code. If you just want to get MySQL up and running
1663
on your system, you should use a standard release distribution
1664
(either a binary or source distribution).
1666
To obtain the most recent development source tree, you must have
1667
Bazaar installed. You can obtain Bazaar from the Bazaar VCS
1668
Website (http://bazaar-vcs.org). Bazaar is supported by any
1669
platform that supports Python, and is therefore compatible with
1670
any Linux, Unix, Windows or Mac OS X host. Instructions for
1671
downloading and installing Bazaar on the different platforms are
1672
available on the Bazaar website.
1674
All MySQL projects are hosted on Launchpad
1675
(http://launchpad.net/). MySQL projects, including MySQL server,
1676
MySQL Workbench, and others are available from the Sun/MySQL
1677
Engineering (http://launchpad.net/~mysql) page. For the
1678
repositories related only to MySQL server, see the MySQL Server
1679
(http://launchpad.net/mysql-server) page.
1681
To build under Unix/Linux, you must have the following tools
1684
* GNU make, available from http://www.gnu.org/software/make/.
1685
Although some platforms come with their own make
1686
implementations, it is highly recommended that you use GNU
1687
make. It may already be available on your system as gmake.
1689
* autoconf 2.58 (or newer), available from
1690
http://www.gnu.org/software/autoconf/.
1692
* automake 1.8.1, available from
1693
http://www.gnu.org/software/automake/.
1695
* libtool 1.5, available from
1696
http://www.gnu.org/software/libtool/.
1698
* m4, available from http://www.gnu.org/software/m4/.
1700
* bison, available from http://www.gnu.org/software/bison/. You
1701
should use the latest version of bison where possible. Version
1702
1.75 and version 2.1 are known to work. There have been
1703
reported problems with bison 1.875. If you experience
1704
problems, upgrade to a later, rather than earlier, version.
1705
Versions of bison older than 1.75 may report this error:
1706
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded
1707
The maximum table size is not actually exceeded; the error is
1708
caused by bugs in older versions of bison.
1710
To build under Windows you must have Microsoft Visual C++ 2005
1711
Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio
1712
2005 (8.0) compiler system.
1714
Once the necessary tools are installed, you must create a local
1715
branch of the MySQL source code on your machine:
1717
1. To obtain a copy of the MySQL source code, you must create a
1718
new Bazaar branch. If you do not already have a Bazaar
1719
repository directory set up, you need to initialize a new
1721
shell> mkdir mysql-server
1722
shell> bzr init-repo --trees mysql-server
1724
2. Once you have an initialized directory, you can branch from
1725
the public MySQL server repositories to create a local source
1726
tree. To create a branch of a specific version:
1727
shell> cd mysql-server
1728
shell> bzr branch lp:mysql-server/5.1 mysql-5.1
1730
3. The initial download will take some time to complete,
1731
depending on the speed of your connection. Please be patient.
1732
Once you have downloaded the first tree, additional trees
1733
should take significantly less time to download.
1735
4. When building from the Bazaar branch, you may want to create a
1736
copy of your active branch so that you can make configuration
1737
and other changes without affecting the original branch
1738
contents. You can achieve this by branching from the original
1740
shell> bzr branch mysql-5.1 mysql-5.1-build
1742
5. To obtain changes made after you have set up the branch
1743
initially, update it using the pull option periodically. Use
1744
this command in the top-level directory of the local copy:
1746
You can examine the changeset comments for the tree by using
1747
the log option to bzr:
1749
You can also browse changesets, comments, and source code
1750
online. To browse this information for MySQL 5.1, go to the
1751
Launchpad MySQL Server (http://launchpad.net/mysql-server)
1753
If you see diffs (changes) or code that you have a question
1754
about, do not hesitate to send email to the MySQL internals
1755
mailing list. See Section 1.5.1, "MySQL Mailing Lists." Also,
1756
if you think you have a better idea on how to do something,
1757
send an email message to the list with a patch.
1759
After you have the local branch, you can build MySQL server from
1760
the source code. On Windows, the build process is different from
1761
Unix/Linux: see Section 2.5.10, "Installing MySQL from Source on
1764
On Unix/Linux, use the autoconf system to create the configure
1765
script so that you can configure the build environment before
1766
building. The following example shows the typical commands
1767
required to build MySQL from a source tree.
1769
1. Change location to the top-level directory of the source tree;
1770
replace mysql-5.1 with the appropriate directory name.
1773
2. Prepare the source tree for configuration.
1774
Prior to MySQL 5.1.12, you must separately configure the
1775
InnoDB storage engine. Run the following command from the main
1777
shell> (cd storage/innobase; autoreconf --force --install)
1778
You can omit the previous command for MySQL 5.1.12 and later,
1779
or if you do not require InnoDB support.
1780
Prepare the remainder of the source tree:
1781
shell> autoreconf --force --install
1782
As an alternative to the preceding autoreconf command, you can
1783
use BUILD/autorun.sh, which acts as a shortcut for the
1784
following sequence of commands:
1785
shell> aclocal; autoheader
1786
shell> libtoolize --automake --force
1787
shell> automake --force --add-missing; autoconf
1788
If you get some strange errors during this stage, verify that
1789
you have the correct version of libtool installed.
1791
3. Configure the source tree and compile MySQL:
1792
shell> ./configure # Add your favorite options here
1794
For a description of some configure options, see Section
1795
2.3.2, "Typical configure Options."
1796
A collection of our standard configuration scripts is located
1797
in the BUILD/ subdirectory. For example, you may find it more
1798
convenient to use the BUILD/compile-pentium-debug script than
1799
the preceding set of shell commands. To compile on a different
1800
architecture, modify the script by removing flags that are
1801
Pentium-specific, or use another script that may be more
1802
appropriate. These scripts are provided on an "as-is" basis.
1803
They are not officially maintained and their contents may
1804
change from release to release.
1806
4. When the build is done, run make install. Be careful with this
1807
on a production machine; the command may overwrite your live
1808
release installation. If you already have MySQL installed and
1809
do not want to overwrite it, run ./configure with values for
1810
the --prefix, --with-tcp-port, and --with-unix-socket-path
1811
options different from those used for your production server.
1813
5. Play hard with your new installation and try to make the new
1814
features crash. Start by running make test. See Section
1815
22.1.2, "MySQL Test Suite."
1817
6. If you have gotten to the make stage, but the distribution
1818
does not compile, please enter the problem into our bugs
1819
database using the instructions given in Section 1.6, "How to
1820
Report Bugs or Problems." If you have installed the latest
1821
versions of the required GNU tools, and they crash trying to
1822
process our configuration files, please report that also.
1823
However, if you get a command not found error or a similar
1824
problem for aclocal, configure, or other required tools, do
1825
not report it. Instead, make sure that all the required tools
1826
are installed and that your PATH variable is set correctly so
1827
that your shell can find them.
1829
2.3.4. Dealing with Problems Compiling MySQL
1831
All MySQL programs compile cleanly for us with no warnings on
1832
Solaris or Linux using gcc. On other systems, warnings may occur
1833
due to differences in system include files. See Section 2.3.5,
1834
"MIT-pthreads Notes," for warnings that may occur when using
1835
MIT-pthreads. For other problems, check the following list.
1837
The solution to many problems involves reconfiguring. If you do
1838
need to reconfigure, take note of the following:
1840
* If configure is run after it has previously been run, it may
1841
use information that was gathered during its previous
1842
invocation. This information is stored in config.cache. When
1843
configure starts up, it looks for that file and reads its
1844
contents if it exists, on the assumption that the information
1845
is still correct. That assumption is invalid when you
1848
* Each time you run configure, you must run make again to
1849
recompile. However, you may want to remove old object files
1850
from previous builds first because they were compiled using
1851
different configuration options.
1853
To prevent old configuration information or object files from
1854
being used, run these commands before re-running configure:
1855
shell> rm config.cache
1858
Alternatively, you can run make distclean.
1860
The following list describes some of the problems when compiling
1861
MySQL that have been found to occur most often:
1863
* If you get errors such as the ones shown here when compiling
1864
sql_yacc.cc, you probably have run out of memory or swap
1866
Internal compiler error: program cc1plus got fatal signal 11
1867
Out of virtual memory
1868
Virtual memory exhausted
1869
The problem is that gcc requires a huge amount of memory to
1870
compile sql_yacc.cc with inline functions. Try running
1871
configure with the --with-low-memory option:
1872
shell> ./configure --with-low-memory
1873
This option causes -fno-inline to be added to the compile line
1874
if you are using gcc and -O0 if you are using something else.
1875
You should try the --with-low-memory option even if you have
1876
so much memory and swap space that you think you can't
1877
possibly have run out. This problem has been observed to occur
1878
even on systems with generous hardware configurations, and the
1879
--with-low-memory option usually fixes it.
1881
* By default, configure picks c++ as the compiler name and GNU
1882
c++ links with -lg++. If you are using gcc, that behavior can
1883
cause problems during configuration such as this:
1884
configure: error: installation or configuration problem:
1885
C++ compiler cannot create executables.
1886
You might also observe problems during compilation related to
1887
g++, libg++, or libstdc++.
1888
One cause of these problems is that you may not have g++, or
1889
you may have g++ but not libg++, or libstdc++. Take a look at
1890
the config.log file. It should contain the exact reason why
1891
your C++ compiler didn't work. To work around these problems,
1892
you can use gcc as your C++ compiler. Try setting the
1893
environment variable CXX to "gcc -O3". For example:
1894
shell> CXX="gcc -O3" ./configure
1895
This works because gcc compiles C++ source files as well as
1896
g++ does, but does not link in libg++ or libstdc++ by default.
1897
Another way to fix these problems is to install g++, libg++,
1898
and libstdc++. However, do not use libg++ or libstdc++ with
1899
MySQL because this only increases the binary size of mysqld
1900
without providing any benefits. Some versions of these
1901
libraries have also caused strange problems for MySQL users in
1904
* If your compile fails with errors such as any of the
1905
following, you must upgrade your version of make to GNU make:
1906
making all in mit-pthreads
1907
make: Fatal error in reader: Makefile, line 18:
1908
Badly formed macro assignment
1910
make: file `Makefile' line 18: Must be a separator (:
1912
pthread.h: No such file or directory
1913
Solaris and FreeBSD are known to have troublesome make
1915
GNU make 3.75 is known to work.
1917
* If you want to define flags to be used by your C or C++
1918
compilers, do so by adding the flags to the CFLAGS and
1919
CXXFLAGS environment variables. You can also specify the
1920
compiler names this way using CC and CXX. For example:
1925
shell> export CC CFLAGS CXX CXXFLAGS
1926
See Section 2.2, "Installing MySQL from Generic Binaries on
1927
Unix/Linux," for a list of flag definitions that have been
1928
found to be useful on various systems.
1930
* If you get errors such as those shown here when compiling
1931
mysqld, configure did not correctly detect the type of the
1932
last argument to accept(), getsockname(), or getpeername():
1933
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
1934
type of the pointer value ''length'' is ''unsigned long'',
1935
which is not compatible with ''int''.
1936
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
1937
To fix this, edit the config.h file (which is generated by
1938
configure). Look for these lines:
1939
/* Define as the base type of the last arg to accept */
1940
#define SOCKET_SIZE_TYPE XXX
1941
Change XXX to size_t or int, depending on your operating
1942
system. (You must do this each time you run configure because
1943
configure regenerates config.h.)
1945
* The sql_yacc.cc file is generated from sql_yacc.yy. Normally,
1946
the build process does not need to create sql_yacc.cc because
1947
MySQL comes with a pre-generated copy. However, if you do need
1948
to re-create it, you might encounter this error:
1949
"sql_yacc.yy", line xxx fatal: default action causes potential...
1950
This is a sign that your version of yacc is deficient. You
1951
probably need to install bison (the GNU version of yacc) and
1954
* On Debian Linux 3.0, you need to install gawk instead of the
1957
* If you need to debug mysqld or a MySQL client, run configure
1958
with the --with-debug option, and then recompile and link your
1959
clients with the new client library. See MySQL Internals:
1960
Porting (http://forge.mysql.com/wiki/MySQL_Internals_Porting).
1962
* If you get a compilation error on Linux (for example, SuSE
1963
Linux 8.1 or Red Hat Linux 7.3) similar to the following one,
1964
you probably do not have g++ installed:
1965
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
1966
incompatible pointer type
1967
libmysql.c:1329: too few arguments to function `gethostbyname_r'
1968
libmysql.c:1329: warning: assignment makes pointer from integer
1970
make[2]: *** [libmysql.lo] Error 1
1971
By default, the configure script attempts to determine the
1972
correct number of arguments by using g++ (the GNU C++
1973
compiler). This test yields incorrect results if g++ is not
1974
installed. There are two ways to work around this problem:
1976
+ Make sure that the GNU C++ g++ is installed. On some
1977
Linux distributions, the required package is called gpp;
1978
on others, it is named gcc-c++.
1980
+ Use gcc as your C++ compiler by setting the CXX
1981
environment variable to gcc:
1983
You must run configure again after making either of those
1986
2.3.5. MIT-pthreads Notes
1988
This section describes some of the issues involved in using
1991
On Linux, you should not use MIT-pthreads. Use the installed
1992
LinuxThreads implementation instead. See Section 2.6, "Installing
1995
If your system does not provide native thread support, you should
1996
build MySQL using the MIT-pthreads package. This includes older
1997
FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some
1998
others. See Section 2.1, "General Installation Guidance."
2000
MIT-pthreads is not part of the MySQL 5.1 source distribution. If
2001
you require this package, you need to download it separately from
2002
http://dev.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.t
2005
After downloading, extract this source archive into the top level
2006
of the MySQL source directory. It creates a new subdirectory named
2009
* On most systems, you can force MIT-pthreads to be used by
2010
running configure with the --with-mit-threads option:
2011
shell> ./configure --with-mit-threads
2012
Building in a nonsource directory is not supported when using
2013
MIT-pthreads because we want to minimize our changes to this
2016
* The checks that determine whether to use MIT-pthreads occur
2017
only during the part of the configuration process that deals
2018
with the server code. If you have configured the distribution
2019
using --without-server to build only the client code, clients
2020
do not know whether MIT-pthreads is being used and use Unix
2021
socket file connections by default. Because Unix socket files
2022
do not work under MIT-pthreads on some platforms, this means
2023
you need to use -h or --host with a value other than localhost
2024
when you run client programs.
2026
* When MySQL is compiled using MIT-pthreads, system locking is
2027
disabled by default for performance reasons. You can tell the
2028
server to use system locking with the --external-locking
2029
option. This is needed only if you want to be able to run two
2030
MySQL servers against the same data files, but that is not
2031
recommended, anyway.
2033
* Sometimes the pthread bind() command fails to bind to a socket
2034
without any error message (at least on Solaris). The result is
2035
that all connections to the server fail. For example:
2036
shell> mysqladmin version
2037
mysqladmin: connect to server at '' failed;
2038
error: 'Can't connect to mysql server on localhost (146)'
2039
The solution to this problem is to kill the mysqld server and
2040
restart it. This has happened to us only when we have forcibly
2041
stopped the server and restarted it immediately.
2043
* With MIT-pthreads, the sleep() system call isn't interruptible
2044
with SIGINT (break). This is noticeable only when you run
2045
mysqladmin --sleep. You must wait for the sleep() call to
2046
terminate before the interrupt is served and the process
2049
* When linking, you might receive warning messages like these
2050
(at least on Solaris); they can be ignored:
2051
ld: warning: symbol `_iob' has differing sizes:
2052
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
2053
file /usr/lib/libc.so value=0x140);
2054
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
2055
ld: warning: symbol `__iob' has differing sizes:
2056
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
2057
file /usr/lib/libc.so value=0x140);
2058
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
2060
* Some other warnings also can be ignored:
2061
implicit declaration of function `int strtoll(...)'
2062
implicit declaration of function `int strtoul(...)'
2064
* We have not been able to make readline work with MIT-pthreads.
2065
(This is not necessary, but may be of interest to some.)
2067
2.4. Upgrading or Downgrading MySQL
2069
2.4.1. Upgrading MySQL
2071
As a general rule, to upgrade from one release series to another,
2072
you should go to the next series rather than skipping a series. To
2073
upgrade from a release series previous to MySQL 5.0, upgrade to
2074
each successive release series in turn until you have reached
2075
MySQL 5.0, and then proceed with the upgrade to MySQL 5.1. For
2076
example, if you currently are running MySQL 4.0 and wish to
2077
upgrade to a newer series, upgrade to MySQL 4.1 first before
2078
upgrading to 5.0, and so forth. For information on upgrading to
2079
MySQL 5.0, see the MySQL 5.0 Reference Manual; for earlier
2080
releases, see the MySQL 3.23, 4.0, 4.1 Reference Manual.
2082
If you perform a binary (in-place) upgrade without dumping and
2083
reloading tables, you cannot upgrade directly from MySQL 4.1 to
2084
5.1. This occurs due to an incompatible change in the MyISAM table
2085
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
2086
repair all MyISAM tables (see Section 2.4.4, "Rebuilding or
2087
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
2088
and check and repair your tables.
2090
To upgrade from MySQL 5.0 to 5.1, use the items in the following
2091
checklist as a guide:
2093
* Before any upgrade, back up your databases, including the
2094
mysql database that contains the grant tables. See Section
2095
6.1, "Database Backup Methods."
2097
* Read all the notes in Section 2.4.1.1, "Upgrading from MySQL
2098
5.0 to 5.1." These notes enable you to identify upgrade issues
2099
that apply to your current MySQL installation. Some
2100
incompatibilities discussed in that section require your
2101
attention before upgrading. Others should be dealt with after
2104
* Read Appendix C, "MySQL Change History" as well, which
2105
provides information about features that are new in MySQL 5.1
2106
or differ from those found in MySQL 5.0.
2108
* After you upgrade to a new version of MySQL, run mysql_upgrade
2109
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
2110
Upgrade"). This program checks your tables, and attempts to
2111
repair them if necessary. It also updates your grant tables to
2112
make sure that they have the current structure so that you can
2113
take advantage of any new capabilities. (Some releases of
2114
MySQL introduce changes to the structure of the grant tables
2115
to add new privileges or features.)
2117
* If you are running MySQL Server on Windows, see Section 2.5.7,
2118
"Upgrading MySQL on Windows."
2120
* If you are using replication, see Section 16.3.3, "Upgrading a
2121
Replication Setup," for information on upgrading your
2124
* If you are upgrading an installation originally produced by
2125
installing multiple RPM packages, it is best to upgrade all
2126
the packages, not just some. For example, if you previously
2127
installed the server and client RPMs, do not upgrade just the
2130
* As of MySQL 5.1.9, the mysqld-max server is included in binary
2131
distributions. There is no separate MySQL-Max distribution. As
2132
of MySQL 5.1.12, there is no mysqld-max server at all in
2133
binary distributions. They contain a server that includes the
2134
features previously included in mysqld-max.
2136
* If you have created a user-defined function (UDF) with a given
2137
name and upgrade MySQL to a version that implements a new
2138
built-in function with the same name, the UDF becomes
2139
inaccessible. To correct this, use DROP FUNCTION to drop the
2140
UDF, and then use CREATE FUNCTION to re-create the UDF with a
2141
different nonconflicting name. The same is true if the new
2142
version of MySQL implements a built-in function with the same
2143
name as an existing stored function. See Section 8.2.4,
2144
"Function Name Parsing and Resolution," for the rules
2145
describing how the server interprets references to different
2148
You can always move the MySQL format files and data files between
2149
different versions on systems with the same architecture as long
2150
as you stay within versions for the same release series of MySQL.
2152
If you are cautious about using new versions, you can always
2153
rename your old mysqld before installing a newer one. For example,
2154
if you are using MySQL 5.0.13 and want to upgrade to 5.1.10,
2155
rename your current server from mysqld to mysqld-5.0.13. If your
2156
new mysqld then does something unexpected, you can simply shut it
2157
down and restart with your old mysqld.
2159
If, after an upgrade, you experience problems with recompiled
2160
client programs, such as Commands out of sync or unexpected core
2161
dumps, you probably have used old header or library files when
2162
compiling your programs. In this case, you should check the date
2163
for your mysql.h file and libmysqlclient.a library to verify that
2164
they are from the new MySQL distribution. If not, recompile your
2165
programs with the new headers and libraries.
2167
If problems occur, such as that the new mysqld server does not
2168
start or that you cannot connect without a password, verify that
2169
you do not have an old my.cnf file from your previous
2170
installation. You can check this with the --print-defaults option
2171
(for example, mysqld --print-defaults). If this command displays
2172
anything other than the program name, you have an active my.cnf
2173
file that affects server or client operation.
2175
If your MySQL installation contains a large amount of data that
2176
might take a long time to convert after an in-place upgrade, you
2177
might find it useful to create a "dummy" database instance for
2178
assessing what conversions might be needed and the work involved
2179
to perform them. Make a copy of your MySQL instance that contains
2180
a full copy of the mysql database, plus all other databases
2181
without data. Run your upgrade procedure on this dummy instance to
2182
see what actions might be needed so that you can better evaluate
2183
the work involved when performing actual data conversion on your
2184
original database instance.
2186
It is a good idea to rebuild and reinstall the Perl DBD::mysql
2187
module whenever you install a new release of MySQL. The same
2188
applies to other MySQL interfaces as well, such as PHP mysql
2189
extensions and the Python MySQLdb module.
2191
2.4.1.1. Upgrading from MySQL 5.0 to 5.1
2193
After upgrading a 5.0 installation to 5.0.10 or above, it is
2194
necessary to upgrade your grant tables. Otherwise, creating stored
2195
procedures and functions might not work. To perform this upgrade,
2200
It is good practice to back up your data before installing any new
2201
version of software. Although MySQL works very hard to ensure a
2202
high level of quality, you should protect your data by making a
2205
To upgrade to 5.1 from any previous version, MySQL recommends that
2206
you dump your tables with mysqldump before upgrading and reload
2207
the dump file after upgrading.
2209
If you perform a binary (in-place) upgrade without dumping and
2210
reloading tables, you cannot upgrade directly from MySQL 4.1 to
2211
5.1. This occurs due to an incompatible change in the MyISAM table
2212
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
2213
repair all MyISAM tables (see Section 2.4.4, "Rebuilding or
2214
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
2215
and check and repair your tables.
2217
In general, you should do the following when upgrading from MySQL
2220
* Read all the items in the following sections to see whether
2221
any of them might affect your applications:
2223
+ Section 2.4.1, "Upgrading MySQL," has general update
2226
+ The items in the change lists found later in this section
2227
enable you to identify upgrade issues that apply to your
2228
current MySQL installation.
2230
+ The MySQL 5.1 change history describes significant new
2231
features you can use in 5.1 or that differ from those
2232
found in MySQL 5.0. Some of these changes may result in
2233
incompatibilities. See Section C.1, "Changes in Release
2234
5.1.x (Production)."
2236
* Note particularly any changes that are marked Known issue or
2237
Incompatible change. These incompatibilities with earlier
2238
versions of MySQL may require your attention before you
2240
Our aim is to avoid these changes, but occasionally they are
2241
necessary to correct problems that would be worse than an
2242
incompatibility between releases. If any upgrade issue
2243
applicable to your installation involves an incompatibility
2244
that requires special handling, follow the instructions given
2245
in the incompatibility description. Often this will involve a
2246
dump and reload, or use of a statement such as CHECK TABLE or
2248
For dump and reload instructions, see Section 2.4.4,
2249
"Rebuilding or Repairing Tables or Indexes." Any procedure
2250
that involves REPAIR TABLE with the USE_FRM option must be
2251
done before upgrading. Use of this statement with a version of
2252
MySQL different from the one used to create the table (that
2253
is, using it after upgrading) may damage the table. See
2254
Section 12.5.2.6, "REPAIR TABLE Syntax."
2256
* After you upgrade to a new version of MySQL, run mysql_upgrade
2257
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
2258
Upgrade"). This program checks your tables, and attempts to
2259
repair them if necessary. It also updates your grant tables to
2260
make sure that they have the current structure so that you can
2261
take advantage of any new capabilities. (Some releases of
2262
MySQL introduce changes to the structure of the grant tables
2263
to add new privileges or features.)
2265
* Check Section 2.4.3, "Checking Whether Tables or Indexes Must
2266
Be Rebuilt," to see whether changes to table formats or to
2267
character sets or collations were made between your current
2268
version of MySQL and the version to which you are upgrading.
2269
If so and these changes result in an incompatibility between
2270
MySQL versions, you will need to upgrade the affected tables
2271
using the instructions in Section 2.4.4, "Rebuilding or
2272
Repairing Tables or Indexes."
2274
* If you are running MySQL Server on Windows, see Section 2.5.7,
2275
"Upgrading MySQL on Windows."
2277
* If you are using replication, see Section 16.3.3, "Upgrading a
2278
Replication Setup," for information on upgrading your
2281
If your MySQL installation contains a large amount of data that
2282
might take a long time to convert after an in-place upgrade, you
2283
might find it useful to create a "dummy" database instance for
2284
assessing what conversions might be needed and the work involved
2285
to perform them. Make a copy of your MySQL instance that contains
2286
a full copy of the mysql database, plus all other databases
2287
without data. Run your upgrade procedure on this dummy instance to
2288
see what actions might be needed so that you can better evaluate
2289
the work involved when performing actual data conversion on your
2290
original database instance.
2292
MySQL Enterprise MySQL Enterprise subscribers will find more
2293
information about upgrading in the Knowledge Base articles found
2295
(https://kb.mysql.com/search.php?cat=search&category=41). Access
2296
to the MySQL Knowledge Base collection of articles is one of the
2297
advantages of subscribing to MySQL Enterprise. For more
2299
http://www.mysql.com/products/enterprise/advisors.html.
2301
The following lists describe changes that may affect applications
2302
and that you should watch out for when upgrading to MySQL 5.1.
2304
Configuration Changes:
2306
* Before MySQL 5.1.11, to build MySQL from source with SSL
2307
support enabled, you would invoke configure with either the
2308
--with-openssl or --with-yassl option. In MySQL 5.1.11, those
2309
options both have been replaced by the --with-ssl option. By
2310
default, --with-ssl causes the bundled yaSSL library to be
2311
used. To select OpenSSL instead, give the option as
2312
--with-ssl=path, where path is the directory where the OpenSSL
2313
header files and libraries are located.
2317
* Known issue: After a binary upgrade to MySQL 5.1 from a MySQL
2318
5.0 installation that contains ARCHIVE tables, accessing those
2319
tables will cause the server to crash, even if you have run
2320
mysql_upgrade or CHECK TABLE ... FOR UPGRADE. To work around
2321
this problem, use mysqldump to dump all ARCHIVE tables before
2322
upgrading, and reload them into MySQL 5.1 after upgrading.
2324
* Known issue: The fix for
2325
Bug#23491: http://bugs.mysql.com/23491 introduced a problem
2326
with SHOW CREATE VIEW, which is used by mysqldump. This causes
2327
an incompatibility when upgrading from versions affected by
2328
that bug fix (MySQL 5.0.40 through 5.0.43, MySQL 5.1.18
2329
through 5.1.19): If you use mysqldump before upgrading from an
2330
affected version and reload the data after upgrading to a
2331
higher version, you must drop and recreate your views.
2333
* Known issue: Dumps performed by using mysqldump to generate a
2334
dump file before the upgrade and reloading the file after
2335
upgrading are subject to the following problem:
2336
Before MySQL 5.0.40, mysqldump displays SPATIAL index
2337
definitions using prefix lengths for the indexed columns.
2338
These prefix lengths are accepted in MySQL 5.0, but not as of
2339
MySQL 5.1. If you use mysqldump from versions of MySQL older
2340
than 5.0.40, any table containing SPATIAL indexes will cause
2341
an error when the dump file is reloaded into MySQL 5.1 or
2343
For example, a table definition might look like this when
2344
dumped in MySQL 5.0:
2346
`g` geometry NOT NULL,
2347
SPATIAL KEY `g` (`g`(32))
2348
) ENGINE=MyISAM DEFAULT CHARSET=latin1
2349
The SPATIAL index definition will not be accepted in MySQL
2350
5.1. To work around this, edit the dump file to remove the
2353
`g` geometry NOT NULL,
2354
SPATIAL KEY `g` (`g`)
2355
) ENGINE=MyISAM DEFAULT CHARSET=latin1
2356
Dump files can be large, so it may be preferable to dump table
2357
definitions and data separately to make it easier to edit the
2359
shell> mysqldump --no-data other_args > definitions.sql
2360
shell> mysqldump --no-create-info other_args > data.sql
2361
Then edit definitions.sql before reloading definitions.sql and
2362
data.sql, in that order.
2363
If you upgrade to a version of MySQL 5.0 higher than 5.0.40
2364
before upgrading to MySQL 5.1, this problem does not occur.
2366
* Known issue: Before MySQL 5.1.30, the CHECK TABLE ... FOR
2367
UPGRADE statement did not check for incompatible collation
2368
changes made in MySQL 5.1.24. (This also affects mysqlcheck
2369
and mysql_upgrade, which cause that statement to be executed.)
2370
Prior to the fix made in 5.1.30, a binary upgrade (performed
2371
without dumping tables with mysqldump before the upgrade and
2372
reloading the dump file after the upgrade) would corrupt
2373
tables. After the fix, CHECK TABLE ... FOR UPGRADE properly
2374
detects the problem and warns about tables that need repair.
2375
However, the fix is not backward compatible and can result in
2376
a downgrading problem under these circumstances:
2378
1. Perform a binary upgrade to a version of MySQL that
2381
2. Run CHECK TABLE ... FOR UPGRADE (or mysqlcheck or
2382
mysql_upgrade) to upgrade tables.
2384
3. Perform a binary downgrade to a version of MySQL that
2385
does not include the fix.
2386
The solution is to dump tables with mysqldump before the
2387
downgrade and reload the dump file after the downgrade.
2388
Alternatively, drop and recreate affected indexes.
2390
* Known issue: MySQL introduces encoding for table names that
2391
have non-ASCII characters (see Section 8.2.3, "Mapping of
2392
Identifiers to File Names"). After a binary upgrade from MySQL
2393
5.0 to 5.1 or higher, the server recognizes names that have
2394
non-ASCII characters and adds a #mysql50# prefix to them.
2395
As of MySQL 5.1.31, mysql_upgrade encodes these names by
2396
executing the following command:
2397
mysqlcheck --all-databases --check-upgrade --fix-db-names --fix-table
2399
Prior to MySQL 5.1.31, mysql_upgrade does not execute this
2400
command, so you should execute it manually if you have
2401
database or table names that contain nonalphanumeric
2403
Prior to MySQL 5.1.23, the mysqlcheck command does not perform
2404
the name encoding for views. To work around this problem, drop
2405
each affected view and recreate it.
2406
mysqlcheck cannot fix names that contain literal instances of
2407
the @ character that is used for encoding special characters.
2408
If you have databases or tables that contain this character,
2409
use mysqldump to dump them before upgrading to MySQL 5.1, and
2410
then reload the dump file after upgrading.
2412
* Known issue: When upgrading from MySQL 5.0 to versions of 5.1
2413
prior to 5.1.23, running mysqlcheck (or mysql_upgrade, which
2414
runs mysqlcheck) to upgrade tables fails for names that must
2415
be written as quoted identifiers. To work around this problem,
2416
rename each affected table to a name that does not require
2418
RENAME TABLE `tab``le_a` TO table_a;
2419
RENAME TABLE `table b` TO table_b;
2420
After renaming the tables, run the mysql_upgrade program. Then
2421
rename the tables back to their original names:
2422
RENAME TABLE table_a TO `tab``le_a`;
2423
RENAME TABLE table_b TO `table b`;
2425
* Known issue: In connection with view creation, the server
2426
created arc directories inside database directories and
2427
maintained useless copies of .frm files there. Creation and
2428
renaming procedures of those copies as well as creation of arc
2429
directories has been discontinued in MySQL 5.1.29.
2430
This change does cause a problem when downgrading to older
2431
server versions which manifests itself under these
2434
1. Create a view v_orig in MySQL 5.1.29 or higher.
2436
2. Rename the view to v_new and then back to v_orig.
2438
3. Downgrade to an older 5.1.x server and run mysql_upgrade.
2440
4. Try to rename v_orig to v_new again. This operation
2442
As a workaround to avoid this problem, use either of these
2445
+ Dump your data using mysqldump before downgrading and
2446
reload the dump file after downgrading.
2448
+ Instead of renaming a view after the downgrade, drop it
2451
* Incompatible change: Character set or collation changes were
2452
made in MySQL 5.1.21, 5.1.23, and 5.1.24 that may require
2453
table indexes to be rebuilt. For details, see Section 2.4.3,
2454
"Checking Whether Tables or Indexes Must Be Rebuilt."
2456
* Incompatible change: MySQL 5.1 implements support for a plugin
2457
API that allows the loading and unloading of components at
2458
runtime, without restarting the server. Section 22.2, "The
2459
MySQL Plugin Interface." The plugin API requires the
2460
mysql.plugin table. After upgrading from an older version of
2461
MySQL, you should run the mysql_upgrade command to create this
2462
table. See Section 4.4.8, "mysql_upgrade --- Check Tables for
2464
Plugins are installed in the directory named by the plugin_dir
2465
system variable. This variable also controls the location from
2466
which the server loads user-defined functions (UDFs), which is
2467
a change from earlier versions of MySQL. That is, all UDF
2468
library files now must be installed in the plugin directory.
2469
When upgrading from an older version of MySQL, you must
2470
migrate your UDF files to the plugin directory.
2472
* Incompatible change: The table_cache system variable has been
2473
renamed to table_open_cache. Any scripts that refer to
2474
table_cache must be updated to use the new name.
2476
* Incompatible change: In MySQL 5.1.36, options for loading
2477
plugins such as pluggable storage engines were changed from
2478
boolean to tristate format. The implementations overlap, but
2479
if you previously used options of the form --plugin_name=0 or
2480
--plugin_name=1, you should instead use --plugin_name=OFF or
2481
--plugin_name=ON, respectively. For details, see Section
2482
5.1.3, "Server Options for Loading Plugins."
2484
* Incompatible change: From MySQL 5.1.24 to 5.1.31, the UPDATE
2485
statement was changed such that assigning NULL to a NOT NULL
2486
column caused an error even when strict SQL mode was not
2487
enabled. The original behavior before MySQL 5.1.24 was that
2488
such assignments caused an error only in strict SQL mode, and
2489
otherwise set the column to the implicit default value for the
2490
column data type and generated a warning. (For information
2491
about implicit default values, see Section 10.1.4, "Data Type
2493
The change caused compatibility problems for applications that
2494
relied on the original behavior. It also caused replication
2495
problems between servers that had the original behavior and
2496
those that did not, for applications that assigned NULL to NOT
2497
NULL columns in UPDATE statements without strict SQL mode
2498
enabled. The change was reverted in MySQL 5.1.32 so that
2499
UPDATE again had the original behavior. Problems can still
2500
occur if you replicate between servers that have the modified
2501
UPDATE behavior and those that do not.
2503
* Incompatible change: As of MySQL 5.1.29, the default binary
2504
logging mode has been changed from MIXED to STATEMENT for
2505
compatibility with MySQL 5.0.
2507
* Incompatible change: In MySQL 5.1.25, a change was made to the
2508
way that the server handles prepared statements. This affects
2509
prepared statements processed at the SQL level (using the
2510
PREPARE statement) and those processed using the binary
2511
client-server protocol (using the mysql_stmt_prepare() C API
2513
Previously, changes to metadata of tables or views referred to
2514
in a prepared statement could cause a server crash when the
2515
statement was next executed, or perhaps an error at execute
2516
time with a crash occurring later. For example, this could
2517
happen after dropping a table and recreating it with a
2518
different definition.
2519
Now metadata changes to tables or views referred to by
2520
prepared statements are detected and cause automatic
2521
repreparation of the statement when it is next executed.
2522
Metadata changes occur for DDL statements such as those that
2523
create, drop, alter, rename, or truncate tables, or that
2524
analyze, optimize, or repair tables. Repreparation also occurs
2525
after referenced tables or views are flushed from the table
2526
definition cache, either implicitly to make room for new
2527
entries in the cache, or explicitly due to FLUSH TABLES.
2528
Repreparation is automatic, but to the extent that it occurs,
2529
performance of prepared statements is diminished.
2530
Table content changes (for example, with INSERT or UPDATE) do
2531
not cause repreparation, nor do SELECT statements.
2532
An incompatibility with previous versions of MySQL is that a
2533
prepared statement may now return a different set of columns
2534
or different column types from one execution to the next. For
2535
example, if the prepared statement is SELECT * FROM t1,
2536
altering t1 to contain a different number of columns causes
2537
the next execution to return a number of columns different
2538
from the previous execution.
2539
Older versions of the client library cannot handle this change
2540
in behavior. For applications that use prepared statements
2541
with the new server, an upgrade to the new client library is
2542
strongly recommended.
2543
Along with this change to statement repreparation, the default
2544
value of the table_definition_cache system variable has been
2545
increased from 128 to 256. The purpose of this increase is to
2546
lessen the chance that prepared statements will need
2547
repreparation due to referred-to tables/views having been
2548
flushed from the cache to make room for new entries.
2549
A new status variable, Com_stmt_reprepare, has been introduced
2550
to track the number of repreparations.
2552
* Incompatible change: As of MySQL 5.1.23, within a stored
2553
routine, it is no longer allowable to declare a cursor for a
2554
SHOW or DESCRIBE statement. This happened to work in some
2555
instances, but is no longer supported. In many cases, a
2556
workaround for this change is to use the cursor with a SELECT
2557
query to read from an INFORMATION_SCHEMA table that produces
2558
the same information as the SHOW statement.
2560
* Incompatible change: SHOW CREATE VIEW displays view
2561
definitions using an AS alias_name clause for each column. If
2562
a column is created from an expression, the default alias is
2563
the expression text, which can be quite long. As of MySQL
2564
5.1.23, aliases for column names in CREATE VIEW statements are
2565
checked against the maximum column length of 64 characters
2566
(not the maximum alias length of 256 characters). As a result,
2567
views created from the output of SHOW CREATE VIEW fail if any
2568
column alias exceeds 64 characters. This can cause problems
2569
for replication or loading dump files. For additional
2570
information and workarounds, see Section D.4, "Restrictions on
2573
* Incompatible change: Several issues were identified for stored
2574
programs (stored procedures and functions, triggers, and
2575
events) and views containing non-ASCII symbols. These issues
2576
involved conversion errors due to incomplete character set
2577
information when translating these objects to and from stored
2579
To address these problems, the representation for these
2580
objects was changed in MySQL 5.1.21. However, the fixes affect
2581
all stored programs and views. (For example, you will see
2582
warnings about "no creation context.") To avoid warnings from
2583
the server about the use of old definitions from any release
2584
prior to 5.1.21, you should dump stored programs and views
2585
with mysqldump after upgrading to 5.1.21 or higher, and then
2586
reload them to recreate them with new definitions. Invoke
2587
mysqldump with a --default-character-set option that names the
2588
non-ASCII character set that was used for the definitions when
2589
the objects were originally defined.
2591
* Incompatible change: As of MySQL 5.1.20, mysqld_safe supports
2592
error logging to syslog on systems that support the logger
2593
command. The new --syslog and --skip-syslog options can be
2594
used instead of the --log-error option to control logging
2595
behavior, as described in Section 4.3.2, "mysqld_safe ---
2596
MySQL Server Startup Script."
2597
In 5.1.21 and up, the default is --skip-syslog, which is
2598
compatible with the default behavior of writing an error log
2599
file for releases prior to 5.1.20.
2600
In 5.1.20 only, the following conditions apply: 1) The default
2601
is to use syslog, which is not compatible with releases prior
2602
to 5.1.20. 2) Logging to syslog may fail to operate correctly
2603
in some cases. For these reasons, avoid using MySQL 5.1.20.
2605
* Incompatible change: As of MySQL 5.1.18, the plugin interface
2606
and its handling of system variables was changed. Command-line
2607
options such as --skip-innodb now cause an error if InnoDB is
2608
not built-in or plugin-loaded. You should use
2609
--loose-skip-innodb if you do not want any error even if
2610
InnoDB is not available. The --loose prefix modifier should be
2611
used for all command-line options where you are uncertain
2612
whether the plugin exists and when you want the operation to
2613
proceed even if the option is necessarily ignored due to the
2614
absence of the plugin. (For a desecription of how --loose
2615
works, see Section 4.2.3.1, "Using Options on the Command
2618
* Incompatible change: As of MySQL 5.1.15, InnoDB rolls back
2619
only the last statement on a transaction timeout. A new
2620
option, --innodb_rollback_on_timeout, causes InnoDB to abort
2621
and roll back the entire transaction if a transaction timeout
2622
occurs (the same behavior as in MySQL 4.1).
2624
* Incompatible change: As of MySQL 5.1.15, the following
2625
conditions apply to enabling the read_only system variable:
2627
+ If you attempt to enable read_only while you have any
2628
explicit locks (acquired with LOCK TABLES or have a
2629
pending transaction, an error will occur.
2631
+ If other clients hold explicit table locks or have
2632
pending transactions, the attempt to enable read_only
2633
blocks until the locks are released and the transactions
2634
end. While the attempt to enable read_only is pending,
2635
requests by other clients for table locks or to begin
2636
transactions also block until read_only has been set.
2638
+ read_only can be enabled while you hold a global read
2639
lock (acquired with FLUSH TABLES WITH READ LOCK) because
2640
that does not involve table locks.
2641
Previously, the attempt to enable read_only would return
2642
immediately even if explicit locks or transactions were
2643
pending, so some data changes could occur for statements
2644
executing in the server at the same time.
2646
* Incompatible change: The number of function names affected by
2647
IGNORE_SPACE was reduced significantly in MySQL 5.1.13, from
2648
about 200 to about 30. (For details about IGNORE_SPACE, see
2649
Section 8.2.4, "Function Name Parsing and Resolution.") This
2650
change improves the consistency of parser operation. However,
2651
it also introduces the possibility of incompatibility for old
2652
SQL code that relies on the following conditions:
2654
+ IGNORE_SPACE is disabled.
2656
+ The presence or absence of whitespace following a
2657
function name is used to distinguish between a built-in
2658
function and stored function that have the same name (for
2659
example, PI() versus PI ()).
2660
For functions that are no longer affected by IGNORE_SPACE as
2661
of MySQL 5.1.13, that strategy no longer works. Either of the
2662
following approaches can be used if you have code that is
2663
subject to the preceding incompatibility:
2665
+ If a stored function has a name that conflicts with a
2666
built-in function, refer to the stored function with a
2667
schema name qualifier, regardless of whether whitespace
2668
is present. For example, write schema_name.PI() or
2671
+ Alternatively, rename the stored function to use a
2672
nonconflicting name and change invocations of the
2673
function to use the new name.
2675
* Incompatible change: For utf8 columns, the full-text parser
2676
incorrectly considered several nonword punctuation and
2677
whitespace characters as word characters, causing some
2678
searches to return incorrect results. The fix involves a
2679
change to the full-text parser in MySQL 5.1.12, so as of
2680
5.1.12, any tables that have FULLTEXT indexes on utf8 columns
2681
must be repaired with REPAIR TABLE:
2682
REPAIR TABLE tbl_name QUICK;
2684
* Incompatible change: Storage engines can be pluggable at
2685
runtime, so the distinction between disabled and invalid
2686
storage engines no longer applies. As of MySQL 5.1.12, this
2687
affects the NO_ENGINE_SUBSTITUTION SQL mode, as described in
2688
Section 5.1.8, "Server SQL Modes."
2690
* Incompatible change: The structure of FULLTEXT indexes has
2691
been changed in MySQL 5.1.6. After upgrading to MySQL 5.1.6 or
2692
greater, any tables that have FULLTEXT indexes must be
2693
repaired with REPAIR TABLE:
2694
REPAIR TABLE tbl_name QUICK;
2696
* Incompatible change: In MySQL 5.1.6, when log tables were
2697
implemented, the default log destination for the general query
2698
and slow query log was TABLE. As of MySQL 5.1.21, this default
2699
has been changed to FILE, which is compatible with MySQL 5.0,
2700
but incompatible with earlier releases of MySQL 5.1. If you
2701
are upgrading from MySQL 5.0 to 5.1.21 or higher, no logging
2702
option changes should be necessary. However, if you are
2703
upgrading from 5.1.6 through 5.1.20 to 5.1.21 or higher and
2704
were using TABLE logging, use the --log-output=TABLE option
2705
explicitly to preserve your server's table-logging behavior.
2707
* Incompatible change: For ENUM columns that had enumeration
2708
values containing commas, the commas were mapped to 0xff
2709
internally. However, this rendered the commas
2710
indistinguishable from true 0xff characters in the values.
2711
This no longer occurs. However, the fix requires that you dump
2712
and reload any tables that have ENUM columns containing true
2713
0xff in their values: Dump the tables using mysqldump with the
2714
current server before upgrading from a version of MySQL 5.1
2715
older than 5.1.15 to version 5.1.15 or newer.
2717
* As of MySQL 5.1.12, the lc_time_names system variable
2718
specifies the locale that controls the language used to
2719
display day and month names and abbreviations. This variable
2720
affects the output from the DATE_FORMAT(), DAYNAME() and
2721
MONTHNAME() functions. See Section 9.8, "MySQL Server Locale
2724
* As of MySQL 5.1.9, mysqld_safe no longer implicitly invokes
2725
mysqld-max if it exists. Instead, it invokes mysqld unless a
2726
--mysqld or --mysqld-version option is given to specify
2727
another server explicitly. If you previously relied on the
2728
implicit invocation of mysqld-max, you should use an
2729
appropriate option now. As of MySQL 5.1.12, there is no longer
2730
any separate mysqld-max server, so no change should be
2735
* Known issue: Prior to MySQL 5.1.17, the parser accepted
2736
invalid code in SQL condition handlers, leading to server
2737
crashes or unexpected execution behavior in stored programs.
2738
Specifically, the parser allowed a condition handler to refer
2739
to labels for blocks that enclose the handler declaration.
2740
This was incorrect because block label scope does not include
2741
the code for handlers declared within the labeled block.
2742
As of 5.1.17, the parser rejects this invalid construct, but
2743
if you perform a binary upgrade (without dumping and reloading
2744
your databases), existing handlers that contain the construct
2745
still are invalid and should be rewritten even if they appear
2746
to function as you expect.
2747
To find affected handlers, use mysqldump to dump all stored
2748
procedures and functions, triggers, and events. Then attempt
2749
to reload them into an upgraded server. Handlers that contain
2750
illegal label references will be rejected.
2751
For more information about condition handlers and writing them
2752
to avoid invalid jumps, see Section 12.8.4.2, "DECLARE for
2755
* Incompatible change: The parser accepted statements that
2756
contained /* ... */ that were not properly closed with */,
2757
such as SELECT 1 /* + 2. As of MySQL 5.1.23, statements that
2758
contain unclosed /*-comments now are rejected with a syntax
2760
This fix has the potential to cause incompatibilities. Because
2761
of Bug#26302: http://bugs.mysql.com/26302, which caused the
2762
trailing */ to be truncated from comments in views, stored
2763
routines, triggers, and events, it is possible that objects of
2764
those types may have been stored with definitions that now
2765
will be rejected as syntactically invalid. Such objects should
2766
be dropped and re-created so that their definitions do not
2767
contain truncated comments.
2769
* Incompatible change: Multiple-table DELETE statements
2770
containing ambiguous aliases could have unintended side
2771
effects such as deleting rows from the wrong table. Example:
2772
DELETE FROM t1 AS a2 USING t1 AS a1 INNER JOIN t2 AS a2;
2773
As of MySQL 5.1.23, alias declarations can be declared only in
2774
the table_references part. Elsewhere in the statement, alias
2775
references are allowed but not alias declarations. Statements
2776
containing aliases that are no longer allowed must be
2779
* Incompatible change: As of MySQL 5.1.8, TYPE = engine_name is
2780
still accepted as a synonym for the ENGINE = engine_name table
2781
option but generates a warning. You should note that this
2782
option is not available in MySQL 5.1.7, and is removed
2783
altogether as of MySQL 5.4 and produces a syntax error.
2784
TYPE has been deprecated since MySQL 4.0.
2786
* Incompatible change: The namespace for triggers changed in
2787
MySQL 5.0.10. Previously, trigger names had to be unique per
2788
table. Now they must be unique within the schema (database).
2789
An implication of this change is that DROP TRIGGER syntax now
2790
uses a schema name instead of a table name (schema name is
2791
optional and, if omitted, the current schema will be used).
2792
When upgrading from a version of MySQL 5 older than 5.0.10 to
2793
MySQL 5.0.10 or newer, you must drop all triggers and
2794
re-create them or DROP TRIGGER will not work after the
2795
upgrade. Here is a suggested procedure for doing this:
2797
1. Upgrade to MySQL 5.0.10 or later to be able to access
2798
trigger information in the INFORMATION_SCHEMA.TRIGGERS
2799
table. (This should work even for pre-5.0.10 triggers.)
2801
2. Dump all trigger definitions using the following SELECT
2803
SELECT CONCAT('CREATE TRIGGER ', t.TRIGGER_SCHEMA, '.', t.TRIGGER_NAM
2805
' ', t.ACTION_TIMING, ' ', t.EVENT_MANIPULATION, ' ON '
2807
t.EVENT_OBJECT_SCHEMA, '.', t.EVENT_OBJECT_TABLE,
2808
' FOR EACH ROW ', t.ACTION_STATEMENT, '//' )
2809
INTO OUTFILE '/tmp/triggers.sql'
2810
FROM INFORMATION_SCHEMA.TRIGGERS AS t;
2811
The statement uses INTO OUTFILE, so you must have the
2812
FILE privilege. The file will be created on the server
2813
host. Use a different file name if you like. To be 100%
2814
safe, inspect the trigger definitions in the triggers.sql
2815
file, and perhaps make a backup of the file.
2817
3. Stop the server and drop all triggers by removing all
2818
.TRG files in your database directories. Change location
2819
to your data directory and issue this command:
2822
4. Start the server and re-create all triggers using the
2824
mysql> delimiter // ;
2825
mysql> source /tmp/triggers.sql //
2827
5. Check that all triggers were successfully created using
2828
the SHOW TRIGGERS statement.
2830
* Incompatible change: MySQL 5.1.6 introduces the TRIGGER
2831
privilege. Previously, the SUPER privilege was needed to
2832
create or drop triggers. Now those operations require the
2833
TRIGGER privilege. This is a security improvement because you
2834
no longer need to grant users the SUPER privilege to enable
2835
them to create triggers. However, the requirement that the
2836
account named in a trigger's DEFINER clause must have the
2837
SUPER privilege has changed to a requirement for the TRIGGER
2838
privilege. When upgrading from a previous version of MySQL 5.0
2839
or 5.1 to MySQL 5.1.6 or newer, be sure to update your grant
2840
tables by running mysql_upgrade. This will assign the TRIGGER
2841
privilege to all accounts that had the SUPER privilege. If you
2842
fail to update the grant tables, triggers may fail when
2843
activated. After updating the grant tables, you can revoke the
2844
SUPER privilege from those accounts that no longer otherwise
2847
* Some keywords may be reserved in MySQL 5.1 that were not
2848
reserved in MySQL 5.0. See Section 8.3, "Reserved Words."
2850
* The BACKUP TABLE, and RESTORE TABLE statements are deprecated.
2851
mysqldump or mysqlhotcopy can be used as alternatives.
2853
* The LOAD DATA FROM MASTER and LOAD TABLE FROM MASTER
2854
statements are deprecated. See Section 12.6.2.2, "LOAD DATA
2855
FROM MASTER Syntax," for recommended alternatives.
2857
* The INSTALL PLUGIN and UNINSTALL PLUGIN statements that are
2858
used for the plugin API are new. So is the WITH PARSER clause
2859
for FULLTEXT index creation that associates a parser plugin
2860
with a full-text index. Section 22.2, "The MySQL Plugin
2865
* Incompatible change: As of MySQL 5.1.7, the
2866
mysql_stmt_attr_get() C API function returns a boolean rather
2867
than an unsigned int for STMT_ATTR_UPDATE_MAX_LENGTH.
2868
(Bug#16144: http://bugs.mysql.com/16144)
2870
2.4.2. Downgrading MySQL
2872
This section describes what you should do to downgrade to an older
2873
MySQL version in the unlikely case that the previous version
2874
worked better than the new one.
2876
If you are downgrading within the same release series (for
2877
example, from 5.0.13 to 5.0.12) the general rule is that you just
2878
have to install the new binaries on top of the old ones. There is
2879
no need to do anything with the databases. As always, however, it
2880
is always a good idea to make a backup.
2882
The following items form a checklist of things you should do
2883
whenever you perform a downgrade:
2885
* Read the upgrading section for the release series from which
2886
you are downgrading to be sure that it does not have any
2887
features you really need. See Section 2.4.1, "Upgrading
2890
* If there is a downgrading section for that version, you should
2893
* To see which new features were added between the version to
2894
which you are downgrading and your current version, see the
2895
change logs (Appendix C, "MySQL Change History").
2897
* Check Section 2.4.3, "Checking Whether Tables or Indexes Must
2898
Be Rebuilt," to see whether changes to table formats or to
2899
character sets or collations were made between your current
2900
version of MySQL and the version to which you are downgrading.
2901
If so and these changes result in an incompatibility between
2902
MySQL versions, you will need to downgrade the affected tables
2903
using the instructions in Section 2.4.4, "Rebuilding or
2904
Repairing Tables or Indexes."
2906
In most cases, you can move the MySQL format files and data files
2907
between different versions on the same architecture as long as you
2908
stay within versions for the same release series of MySQL.
2910
If you downgrade from one release series to another, there may be
2911
incompatibilities in table storage formats. In this case, use
2912
mysqldump to dump your tables before downgrading. After
2913
downgrading, reload the dump file using mysql or mysqlimport to
2914
re-create your tables. For examples, see Section 2.4.5, "Copying
2915
MySQL Databases to Another Machine."
2917
A typical symptom of a downward-incompatible table format change
2918
when you downgrade is that you cannot open tables. In that case,
2919
use the following procedure:
2921
1. Stop the older MySQL server that you are downgrading to.
2923
2. Restart the newer MySQL server you are downgrading from.
2925
3. Dump any tables that were inaccessible to the older server by
2926
using mysqldump to create a dump file.
2928
4. Stop the newer MySQL server and restart the older one.
2930
5. Reload the dump file into the older server. Your tables should
2933
It might also be the case that the structure of the system tables
2934
in the mysql database has changed and that downgrading introduces
2935
some loss of functionality or requires some adjustments. Here are
2938
* Trigger creation requires the TRIGGER privilege as of MySQL
2939
5.1. In MySQL 5.0, there is no TRIGGER privilege and SUPER is
2940
required instead. If you downgrade from MySQL 5.1 to 5.0, you
2941
will need to give the SUPER privilege to those accounts that
2942
had the TRIGGER privilege in 5.1.
2944
* Triggers were added in MySQL 5.0, so if you downgrade from 5.0
2945
to 4.1, you cannot use triggers at all.
2947
2.4.2.1. Downgrading to MySQL 5.0
2949
When downgrading to MySQL 5.0 from MySQL 5.1, you should keep in
2950
mind the following issues relating to features found in MySQL 5.1,
2951
but not in MySQL 5.0:
2953
* Partitioning. MySQL 5.0 does not support user-defined
2954
partitioning. If a table was created as a partitioned table in
2955
5.1 (or if an table created in a previous version of MySQL was
2956
altered to include partitions after an upgrade to 5.1), the
2957
table is accessible after downgrade only if you do one of the
2960
+ Export the table using mysqldump and then drop it in
2961
MySQL 5.1; import the table again following the downgrade
2964
+ Prior to the downgrade, remove the table's partitioning
2965
using ALTER TABLE table_name REMOVE PARTITIONING.
2967
* Event Scheduler. MySQL 5.0 does not support scheduled events.
2968
If your databases contain scheduled event definitions, you
2969
should prevent them from being dumped when you use mysqldump
2970
by using the --skip-events option. (See Section 4.5.4,
2971
"mysqldump --- A Database Backup Program.")
2973
* Stored routines. MySQL 5.1.21 added a number of new columns
2974
to the mysql.proc table in which stored routine definitions
2975
are stored. If you are downgrading from MySQL 5.1.21 or later
2976
to MySQL 5.0, you cannot import the MySQL 5.1 routine
2977
definitions into MySQL 5.0.46 or earlier using the dump of
2978
mysql.proc created by mysqldump (such as when using the
2979
--all-databases option). Instead, you should run mysqldump
2980
--routines prior to performing the downgrade and run the
2981
stored routines DDL statements following the downgrade.
2982
See Bug#11986: http://bugs.mysql.com/11986,
2983
Bug#30029: http://bugs.mysql.com/30029, and
2984
Bug#30660: http://bugs.mysql.com/30660, for more information.
2986
* Triggers. Trigger creation requires the TRIGGER privilege as
2987
of MySQL 5.1. In MySQL 5.0, there is no TRIGGER privilege and
2988
SUPER is required instead. If you downgrade from MySQL 5.1 to
2989
5.0, you will need to give the SUPER privilege to those
2990
accounts that had the TRIGGER privilege in 5.1.
2992
2.4.3. Checking Whether Tables or Indexes Must Be Rebuilt
2994
A binary upgrade or downgrade is one that installs one version of
2995
MySQL "in place" over an existing version, without dumping and
2998
1. Stop the server for the existing version if it is running.
3000
2. Install a different version of MySQL. This is an upgrade if
3001
the new version is higher than the original version, a
3002
downgrade if the version is lower.
3004
3. Start the server for the new version.
3006
In many cases, the tables from the previous version of MySQL can
3007
be used without problem by the new version. However, sometimes
3008
changes occur that require tables or table indexes to be rebuilt,
3009
as described in this section. If you have tables that are affected
3010
by any of the issues described here, rebuild the tables or indexes
3011
as necessary using the instructions given in Section 2.4.4,
3012
"Rebuilding or Repairing Tables or Indexes."
3014
Table Incompatibilities
3016
After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation
3017
that contains ARCHIVE tables, accessing those tables causes the
3018
server to crash, even if you have run mysql_upgrade or CHECK TABLE
3019
... FOR UPGRADE. To work around this problem, use mysqldump to
3020
dump all ARCHIVE tables before upgrading, and reload them into
3021
MySQL 5.1 after upgrading. The same problem occurs for binary
3022
downgrades from MySQL 5.1 to 5.0.
3024
Index Incompatibilities
3026
If you perform a binary upgrade without dumping and reloading
3027
tables, you cannot upgrade directly from MySQL 4.1 to 5.1 or
3028
higher. This occurs due to an incompatible change in the MyISAM
3029
table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
3030
repair all MyISAM tables. Then upgrade from MySQL 5.0 to 5.1 and
3031
check and repair your tables.
3033
Modifications to the handling of character sets or collations
3034
might change the character sort order, which causes the ordering
3035
of entries in any index that uses an affected character set or
3036
collation to be incorrect. Such changes result in several possible
3039
* Comparison results that differ from previous results
3041
* Inability to find some index values due to misordered index
3044
* Misordered ORDER BY results
3046
* Tables that CHECK TABLE reports as being in need of repair
3048
The solution to these problems is to rebuild any indexes that use
3049
an affected character set or collation, either by dropping and
3050
re-creating the indexes, or by dumping and reloading the entire
3051
table. For information about rebuilding indexes, see Section
3052
2.4.4, "Rebuilding or Repairing Tables or Indexes."
3054
To check whether a table has indexes that must be rebuilt, consult
3055
the following list. It indicates which versions of MySQL
3056
introduced character set or collation changes that require indexes
3057
to be rebuilt. Each entry indicates the version in which the
3058
change occurred and the character sets or collations that the
3059
change affects. If the change is associated with a particular bug
3060
report, the bug number is given.
3062
The list applies both for binary upgrades and downgrades. For
3063
example, Bug#27877: http://bugs.mysql.com/27877 was fixed in MySQL
3064
5.1.24 and 5.4.0, so it applies to upgrades from versions older
3065
than 5.1.24 to 5.1.24 or newer, and to downgrades from 5.1.24 or
3066
newer to versions older than 5.1.24.
3068
In many cases, you can use CHECK TABLE ... FOR UPGRADE to identify
3069
tables for which index rebuilding is required. (It will report:
3070
Table upgrade required. Please do "REPAIR TABLE `tbl_name`" or
3071
dump/reload to fix it!) In these cases, you can also use
3072
mysqlcheck --check-upgrade or mysql_upgrade, which execute CHECK
3073
TABLE. However, the use of CHECK TABLE applies only after
3074
upgrades, not downgrades. Also, CHECK TABLE is not applicable to
3075
all storage engines. For details about which storage engines CHECK
3076
TABLE supports, see Section 12.5.2.3, "CHECK TABLE Syntax."
3078
Changes that cause index rebuilding to be necessary:
3080
* MySQL 5.0.48, 5.1.21 (Bug#29461: http://bugs.mysql.com/29461)
3081
Affects indexes for columns that use any of these character
3082
sets: eucjpms, euc_kr, gb2312, latin7, macce, ujis
3083
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3084
as of MySQL 5.1.29, 5.4.0 (see
3085
Bug#39585: http://bugs.mysql.com/39585).
3087
* MySQL 5.0.48, 5.1.23 (Bug#27562: http://bugs.mysql.com/27562)
3088
Affects indexes that use the ascii_general_ci collation for
3089
columns that contain any of these characters: '`' GRAVE
3090
ACCENT, '[' LEFT SQUARE BRACKET, '\' REVERSE SOLIDUS, ']'
3091
RIGHT SQUARE BRACKET, '~' TILDE
3092
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3093
as of MySQL 5.1.29, 5.4.0 (see
3094
Bug#39585: http://bugs.mysql.com/39585).
3096
* MySQL 5.1.24, 5.4.0 (Bug#27877: http://bugs.mysql.com/27877)
3097
Affects indexes that use the utf8_general_ci or
3098
ucs2_general_ci collation for columns that contain 'Ć' LATIN
3099
SMALL LETTER SHARP S (German).
3100
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3101
as of MySQL 5.1.30, 5.4.0 (see
3102
Bug#40053: http://bugs.mysql.com/40053).
3104
2.4.4. Rebuilding or Repairing Tables or Indexes
3106
This section describes how to rebuild a table. This can be
3107
necessitated by changes to MySQL such as how data types are
3108
handled or changes to character set handling. For example, an
3109
error in a collation might have been corrected, necessitating a
3110
table rebuild to rebuild the indexes for character columns that
3111
use the collation. It might also be that a table repair or upgrade
3112
should be done as indicated by a table check operation such as
3113
that performed by CHECK TABLE, mysqlcheck, or mysql_upgrade.
3115
Methods for rebuilding a table include dumping and reloading it,
3116
or using ALTER TABLE or REPAIR TABLE.
3120
If you are rebuilding tables because a different version of MySQL
3121
will not handle them after a binary (in-place) upgrade or
3122
downgrade, you must use the dump-and-reload method. Dump the
3123
tables before upgrading or downgrading (using your original
3124
version of MySQL), and reload the tables after upgrading or
3125
downgrading (after installing the new version).
3127
If you use the dump-and-reload method of rebuilding tables only
3128
for the purpose of rebuilding indexes, you can perform the dump
3129
either before or after upgrading or downgrading. Reloading still
3130
must be done afterward.
3132
To re-create a table by dumping and reloading it, use mysqldump to
3133
create a dump file and mysql to reload the file:
3134
shell> mysqldump db_name t1 > dump.sql
3135
shell> mysql db_name < dump.sql
3137
To recreate all the tables in a single database, specify the
3138
database name without any following table name:
3139
shell> mysqldump db_name > dump.sql
3140
shell> mysql db_name < dump.sql
3142
To recreate all tables in all databases, use the --all-databases
3144
shell> mysqldump --all-databases > dump.sql
3145
shell> mysql < dump.sql
3147
To rebuild a table with ALTER TABLE, use a "null" alteration; that
3148
is, an ALTER TABLE statement that "changes" the table to use the
3149
storage engine that it already has. For example, if t1 is a MyISAM
3150
table, use this statement:
3151
mysql> ALTER TABLE t1 ENGINE = MyISAM;
3153
If you are not sure which storage engine to specify in the ALTER
3154
TABLE statement, use SHOW CREATE TABLE to display the table
3157
If you must rebuild a table because a table checking operation
3158
indicates that the table is corrupt or needs an upgrade, you can
3159
use REPAIR TABLE if that statement supports the table's storage
3160
engine. For example, to repair a MyISAM table, use this statement:
3161
mysql> REPAIR TABLE t1;
3163
For storage engines such as InnoDB that REPAIR TABLE does not
3164
support, use mysqldump to create a dump file and mysql to reload
3165
the file, as described earlier.
3167
For specifics about which storage engines REPAIR TABLE supports,
3168
see Section 12.5.2.6, "REPAIR TABLE Syntax."
3170
mysqlcheck --repair provides command-line access to the REPAIR
3171
TABLE statement. This can be a more convenient means of repairing
3172
tables because you can use the --databases or --all-databases
3173
option to repair all tables in specific databases or all
3174
databases, respectively:
3175
shell> mysqlcheck --repair --databases db_name ...
3176
shell> mysqlcheck --repair --all-databases
3178
2.4.5. Copying MySQL Databases to Another Machine
3180
You can copy the .frm, .MYI, and .MYD files for MyISAM tables
3181
between different architectures that support the same
3182
floating-point format. (MySQL takes care of any byte-swapping
3183
issues.) See Section 13.5, "The MyISAM Storage Engine."
3185
In cases where you need to transfer databases between different
3186
architectures, you can use mysqldump to create a file containing
3187
SQL statements. You can then transfer the file to the other
3188
machine and feed it as input to the mysql client.
3190
Use mysqldump --help to see what options are available.
3192
The easiest (although not the fastest) way to move a database
3193
between two machines is to run the following commands on the
3194
machine on which the database is located:
3195
shell> mysqladmin -h 'other_hostname' create db_name
3196
shell> mysqldump db_name | mysql -h 'other_hostname' db_name
3198
If you want to copy a database from a remote machine over a slow
3199
network, you can use these commands:
3200
shell> mysqladmin create db_name
3201
shell> mysqldump -h 'other_hostname' --compress db_name | mysql db_na
3204
You can also store the dump in a file, transfer the file to the
3205
target machine, and then load the file into the database there.
3206
For example, you can dump a database to a compressed file on the
3207
source machine like this:
3208
shell> mysqldump --quick db_name | gzip > db_name.gz
3210
Transfer the file containing the database contents to the target
3211
machine and run these commands there:
3212
shell> mysqladmin create db_name
3213
shell> gunzip < db_name.gz | mysql db_name
3215
You can also use mysqldump and mysqlimport to transfer the
3216
database. For large tables, this is much faster than simply using
3217
mysqldump. In the following commands, DUMPDIR represents the full
3218
path name of the directory you use to store the output from
3221
First, create the directory for the output files and dump the
3223
shell> mkdir DUMPDIR
3224
shell> mysqldump --tab=DUMPDIR db_name
3226
Then transfer the files in the DUMPDIR directory to some
3227
corresponding directory on the target machine and load the files
3229
shell> mysqladmin create db_name # create database
3230
shell> cat DUMPDIR/*.sql | mysql db_name # create tables in databas
3232
shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables
3234
Do not forget to copy the mysql database because that is where the
3235
grant tables are stored. You might have to run commands as the
3236
MySQL root user on the new machine until you have the mysql
3239
After you import the mysql database on the new machine, execute
3240
mysqladmin flush-privileges so that the server reloads the grant
3243
2.5. Installing MySQL on Windows
3245
This section describes the process for installing MySQL on
3248
To run MySQL on Windows, you need the following:
3250
* A Windows operating system such as Windows 2000, Windows XP,
3251
Windows Vista, Windows Server 2003, or Windows Server 2008.
3252
Both 32-bit and 64-bit versions are supported.
3253
In addition to running MySQL as a standard application, you
3254
can also run the MySQL server as a Windows service. By using a
3255
service you can monitor and control the operation of the
3256
server through the standard Windows service management tools.
3257
For more information, see Section 2.5.5.6, "Starting MySQL as
3259
Generally, you should install MySQL on Windows using an
3260
account that has administrator rights. Otherwise, you may
3261
encounter problems with certain operations such as editing the
3262
PATH environment variable or accessing the Service Control
3263
Manager. Once installed, MySQL does not need to be executed
3264
using a user with Administrator privileges.
3266
* TCP/IP protocol support.
3268
* Enough space on the hard drive to unpack, install, and create
3269
the databases in accordance with your requirements (generally
3270
a minimum of 200 megabytes is recommended.)
755
MySQL compressed tar file binary distributions have names of the
756
form mysql-VERSION-OS.tar.gz, where VERSION is a number (for
757
example, 5.1.62), and OS indicates the type of operating system
758
for which the distribution is intended (for example, pc-linux-i686
761
To install MySQL from a compressed tar file binary distribution,
762
your system must have GNU gunzip to uncompress the distribution
763
and a reasonable tar to unpack it. If your tar program supports
764
the z option, it can both uncompress and unpack the file.
766
GNU tar is known to work. The standard tar provided with some
767
operating systems is not able to unpack the long file names in the
768
MySQL distribution. You should download and install GNU tar, or if
769
available, use a preinstalled version of GNU tar. Usually this is
770
available as gnutar, gtar, or as tar within a GNU or Free Software
771
directory, such as /usr/sfw/bin or /usr/local/bin. GNU tar is
772
available from http://www.gnu.org/software/tar/.
775
If you have previously installed MySQL using your operating system
776
native package management system, such as yum or apt-get, you may
777
experience problems installing using a native binary. Make sure
778
your previous MySQL previous installation has been removed
779
entirely (using your package management system), and that any
780
additional files, such as old versions of your data files, have
781
also been removed. You should also check the existence of
782
configuration files such as /etc/my.cnf or the /etc/mysql
783
directory have been deleted.
785
If you run into problems and need to file a bug report, please use
786
the instructions in Section 1.7, "How to Report Bugs or Problems."
788
On Unix, to install a compressed tar file binary distribution,
789
unpack it at the installation location you choose (typically
790
/usr/local/mysql). This creates the directories shown in the
793
Table 2.2. MySQL Installation Layout for Generic Unix/Linux Binary
795
Directory Contents of Directory
796
bin Client programs and the mysqld server
797
data Log files, databases
798
docs Manual in Info format
799
man Unix manual pages
800
include Include (header) files
802
scripts mysql_install_db
803
share Miscellaneous support files, including error messages,
804
sample configuration files, SQL for database installation
807
Debug versions of the mysqld binary are available as mysqld-debug.
808
To compile your own debug version of MySQL from a source
809
distribution, use the appropriate configuration options to enable
810
debugging support. For more information on compiling from source,
811
see Section 2.11, "Installing MySQL from Source."
813
To install and use a MySQL binary distribution, the basic command
814
sequence looks like this:
815
shell> groupadd mysql
816
shell> useradd -r -g mysql mysql
818
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
819
shell> ln -s full-path-to-mysql-VERSION-OS mysql
821
shell> chown -R mysql .
822
shell> chgrp -R mysql .
823
shell> scripts/mysql_install_db --user=mysql
824
shell> chown -R root .
825
shell> chown -R mysql data
826
# Next command is optional
827
shell> cp support-files/my-medium.cnf /etc/my.cnf
828
shell> bin/mysqld_safe --user=mysql &
829
# Next command is optional
830
shell> cp support-files/mysql.server /etc/init.d/mysql.server
832
A more detailed version of the preceding description for
833
installing a binary distribution follows.
836
This procedure assumes that you have root (administrator) access
837
to your system. Alternatively, you can prefix each command using
838
the sudo (Linux) or pfexec (OpenSolaris) command.
840
The procedure does not set up any passwords for MySQL accounts.
841
After following the procedure, proceed to Section 2.12,
842
"Postinstallation Setup and Testing."
844
Create a mysql User and Group
846
If your system does not already have a user and group for mysqld
847
to run as, you may need to create one. The following commands add
848
the mysql group and the mysql user. You might want to call the
849
user and group something else instead of mysql. If so, substitute
850
the appropriate name in the following instructions. The syntax for
851
useradd and groupadd may differ slightly on different versions of
852
Unix, or they may have different names such as adduser and
854
shell> groupadd mysql
855
shell> useradd -r -g mysql mysql
859
Because the user is required only for ownership purposes, not
860
login purposes, the useradd command uses the -r option to create a
861
user that does not have login permissions to your server host.
862
Omit this option to permit logins for the user (or if your useradd
863
does not support the option).
865
Obtain and Unpack the Distribution
867
Pick the directory under which you want to unpack the distribution
868
and change location into it. The example here unpacks the
869
distribution under /usr/local. The instructions, therefore, assume
870
that you have permission to create files and directories in
871
/usr/local. If that directory is protected, you must perform the
872
installation as root.
875
Obtain a distribution file using the instructions in Section
876
2.1.3, "How to Get MySQL." For a given release, binary
877
distributions for all platforms are built from the same MySQL
880
Unpack the distribution, which creates the installation directory.
881
Then create a symbolic link to that directory. tar can uncompress
882
and unpack the distribution if it has z option support:
883
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
884
shell> ln -s full-path-to-mysql-VERSION-OS mysql
886
The tar command creates a directory named mysql-VERSION-OS. The ln
887
command makes a symbolic link to that directory. This enables you
888
to refer more easily to the installation directory as
891
If your tar does not have z option support, use gunzip to unpack
892
the distribution and tar to unpack it. Replace the preceding tar
893
command with the following alternative command to uncompress and
894
extract the distribution:
895
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
897
Perform Postinstallation Setup
899
The remainder of the installation process involves setting up the
900
configuration file, creating the core databases, and starting the
901
MySQL server. For instructions, see Section 2.12,
902
"Postinstallation Setup and Testing."
905
The accounts that are listed in the MySQL grant tables initially
906
have no passwords. After starting the server, you should set up
907
passwords for them using the instructions in Section 2.12,
908
"Postinstallation Setup and Testing."
910
2.3. Installing MySQL on Microsoft Windows
912
MySQL for Microsoft Windows is available in a number of different
913
forms. A Microsoft Windows operating system such as Windows 2000,
914
Windows XP, Windows Vista, Windows 7, Windows Server 2003, or
915
Windows Server 2008. Both 32-bit and 64-bit versions are
918
In addition to running MySQL as a standard application, you can
919
also run the MySQL server as a Windows service. By using a service
920
you can monitor and control the operation of the server through
921
the standard Windows service management tools. For more
922
information, see Section 2.3.5.7, "Starting MySQL Server as a
923
Microsoft Windows Service."
925
Generally, you should install MySQL on Windows using an account
926
that has administrator rights. Otherwise, you may encounter
927
problems with certain operations such as editing the PATH
928
environment variable or accessing the Service Control Manager.
929
Once installed, MySQL does not need to be executed using a user
930
with Administrator privileges.
3272
932
For a list of limitations within the Windows version of MySQL, see
3273
Section D.7.3, "Windows Platform Limitations."
933
Section E.7.5, "Windows Platform Limitations."
3275
935
In addition to the MySQL Server package, you may need or want
3276
936
additional components to use MySQL with your application or
3277
937
development environment. These include, but are not limited to:
3279
* If you plan to connect to the MySQL server via ODBC, you need
3280
a Connector/ODBC driver. For more information, including
3281
installation and configuration instructions, see Section 21.1,
939
* If you plan to connect to the MySQL server using ODBC, you
940
need a Connector/ODBC driver. For more information, including
941
installation and configuration instructions, see Section 20.1,
3282
942
"MySQL Connector/ODBC."
3284
944
* If you plan to use MySQL server with .NET applications, you
3285
need the Connector/NET driver. For more information, including
3286
installation and configuration instructions, see Section 21.2,
3287
"MySQL Connector/NET."
945
need the Connector/Net driver. For more information, including
946
installation and configuration instructions, see Section 20.2,
947
"MySQL Connector/Net."
3289
949
MySQL distributions for Windows can be downloaded from
3290
950
http://dev.mysql.com/downloads/. See Section 2.1.3, "How to Get
5232
| time_zone_leap_second |
5234
| time_zone_transition |
5235
| time_zone_transition_type |
5237
+---------------------------+
5240
C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql
5241
+------+-------+------+
5242
| host | db | user |
5243
+------+-------+------+
5245
+------+-------+------+
5247
You may need to specify a different directory from the one shown;
5248
if you used the Windows Installation Wizard, then the default
5249
directory is C:\Program Files\MySQL\MySQL Server 5.1, and the
5250
mysql and mysqlshow client programs are in C:\Program
5251
Files\MySQL\MySQL Server 5.1\bin. See Section 2.5.3.1, "Using the
5252
MySQL Installation Wizard," for more information.
5254
If you have already secured the initial MySQL accounts, you may
5255
need to use the -u and -p options to supply a user name and
5256
password to the mysqlshow and mysql client programs; otherwise the
5257
programs may fail with an error, or you may not be able to view
5258
all databases. For example, if you have assigned the password
5259
"secretpass" to the MySQL root account, then you can invoke
5260
mysqlshow and mysql as shown here:
5261
C:\> C:\mysql\bin\mysqlshow -uroot -psecretpass
5262
+--------------------+
5264
+--------------------+
5265
| information_schema |
5268
+--------------------+
5270
C:\> C:\mysql\bin\mysqlshow -uroot -psecretpass mysql
5272
+---------------------------+
5274
+---------------------------+
5292
| time_zone_leap_second |
5294
| time_zone_transition |
5295
| time_zone_transition_type |
5297
+---------------------------+
5300
C:\> C:\mysql\bin\mysql -uroot -psecretpass -e "SELECT Host,Db,User F
5302
+------+-------+------+
5303
| host | db | user |
5304
+------+-------+------+
5306
+------+-------+------+
5308
For more information about these programs, see Section 4.5.6,
2993
| time_zone_leap_second |
2995
| time_zone_transition |
2996
| time_zone_transition_type |
2998
+---------------------------+
3000
Use the mysql program to select information from a table in the
3002
C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM mysql.db"
3003
+------+--------+------+
3004
| host | db | user |
3005
+------+--------+------+
3008
+------+--------+------+
3010
For more information about mysqlshow and mysql, see Section 4.5.6,
5309
3011
"mysqlshow --- Display Database, Table, and Column Information,"
5310
3012
and Section 4.5.1, "mysql --- The MySQL Command-Line Tool."
5312
If you are running a version of Windows that supports services and
5313
you want the MySQL server to run automatically when Windows
5314
starts, see Section 2.5.5.6, "Starting MySQL as a Windows
5317
2.5.9. MySQL on Windows Compared to MySQL on Unix
5319
MySQL for Windows has proven itself to be very stable. The Windows
5320
version of MySQL has the same features as the corresponding Unix
5321
version, with the following exceptions:
5323
* Limited number of ports
5324
Windows systems have about 4,000 ports available for client
5325
connections, and after a connection on a port closes, it takes
5326
two to four minutes before the port can be reused. In
5327
situations where clients connect to and disconnect from the
5328
server at a high rate, it is possible for all available ports
5329
to be used up before closed ports become available again. If
5330
this happens, the MySQL server appears to be unresponsive even
5331
though it is running. Note that ports may be used by other
5332
applications running on the machine as well, in which case the
5333
number of ports available to MySQL is lower.
5334
For more information about this problem, see
5335
http://support.microsoft.com/default.aspx?scid=kb;en-us;196271
5339
MySQL depends on the pread() and pwrite() system calls to be
5340
able to mix INSERT and SELECT. Currently, we use mutexes to
5341
emulate pread() and pwrite(). We intend to replace the file
5342
level interface with a virtual interface in the future so that
5343
we can use the readfile()/writefile() interface to get more
5344
speed. The current implementation limits the number of open
5345
files that MySQL 5.1 can use to 2,048, which means that you
5346
cannot run as many concurrent threads on Windows as on Unix.
5349
MySQL uses a blocking read for each connection. That has the
5350
following implications if named-pipe connections are enabled:
5352
+ A connection is not disconnected automatically after
5353
eight hours, as happens with the Unix version of MySQL.
5355
+ If a connection hangs, it is not possible to break it
5356
without killing MySQL.
5358
+ mysqladmin kill does not work on a sleeping connection.
5360
+ mysqladmin shutdown cannot abort as long as there are
5361
sleeping connections.
5362
We plan to fix this problem in the future.
5365
While you are executing an ALTER TABLE statement, the table is
5366
locked from being used by other threads. This has to do with
5367
the fact that on Windows, you can't delete a file that is in
5368
use by another thread. In the future, we may find some way to
5369
work around this problem.
5371
* DATA DIRECTORY and INDEX DIRECTORY
5372
The DATA DIRECTORY and INDEX DIRECTORY options for CREATE
5373
TABLE are ignored on Windows, because Windows doesn't support
5374
symbolic links. These options also are ignored on systems that
5375
have a nonfunctional realpath() call.
5378
You cannot drop a database that is in use by another thread.
5380
* Case-insensitive names
5381
File names are not case sensitive on Windows, so MySQL
5382
database and table names are also not case sensitive on
5383
Windows. The only restriction is that database and table names
5384
must be specified using the same case throughout a given
5385
statement. See Section 8.2.2, "Identifier Case Sensitivity."
5387
* Directory and file names
5388
On Windows, MySQL Server supports only directory and file
5389
names that are compatible with the current ANSI code pages.
5390
For example, the following Japanese directory name will not
5391
work in the Western locale (code page 1252):
5392
datadir="C:/ē»“åŗē¾ē§å
³äŗäøęē»“åŗē¾ē§"
5393
The same limitation applies to directory and file names
5394
referred to in SQL statements, such as the data file path name
5395
in LOAD DATA INFILE.
5397
* The "\" path name separator character
5398
Path name components in Windows are separated by the "\"
5399
character, which is also the escape character in MySQL. If you
5400
are using LOAD DATA INFILE or SELECT ... INTO OUTFILE, use
5401
Unix-style file names with "/" characters:
5402
mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr;
5403
mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;
5404
Alternatively, you must double the "\" character:
5405
mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr;
5406
mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;
5408
* Problems with pipes
5409
Pipes do not work reliably from the Windows command-line
5410
prompt. If the pipe includes the character ^Z / CHAR(24),
5411
Windows thinks that it has encountered end-of-file and aborts
5413
This is mainly a problem when you try to apply a binary log as
5415
C:\> mysqlbinlog binary_log_file | mysql --user=root
5416
If you have a problem applying the log and suspect that it is
5417
because of a ^Z / CHAR(24) character, you can use the
5418
following workaround:
5419
C:\> mysqlbinlog binary_log_file --result-file=/tmp/bin.sql
5420
C:\> mysql --user=root --execute "source /tmp/bin.sql"
5421
The latter command also can be used to reliably read in any
5422
SQL file that may contain binary data.
5424
* Access denied for user error
5425
If MySQL cannot resolve your host name properly, you may get
5426
the following error when you attempt to run a MySQL client
5427
program to connect to a server running on the same machine:
5428
Access denied for user 'some_user'@'unknown'
5430
To fix this problem, you should create a file named
5431
\windows\hosts containing the following information:
5434
Here are some open issues for anyone who might want to help us
5435
improve MySQL on Windows:
5437
* Add macros to use the faster thread-safe increment/decrement
5438
methods provided by Windows.
5440
2.5.10. Installing MySQL from Source on Windows
5442
These instructions describe how to build binaries from source for
5443
MySQL 5.1 on Windows. Instructions are provided for building
5444
binaries from a standard source distribution or from the Bazaar
5445
tree that contains the latest development source.
5449
The instructions here are strictly for users who want to test
5450
MySQL on Microsoft Windows from the latest source distribution or
5451
from the Bazaar tree. For production use, we do not advise using a
5452
MySQL server built by yourself from source. Normally, it is best
5453
to use precompiled binary distributions of MySQL that are built
5454
specifically for optimal performance on Windows by Sun
5455
Microsystems, Inc. Instructions for installing binary
5456
distributions are available in Section 2.5, "Installing MySQL on
5459
To build MySQL on Windows from source, you must satisfy the
5460
following system, compiler, and resource requirements:
5462
* Windows 2000, Windows XP, or newer version.
5463
Windows Vista is supported when using Visual Studio 2005
5464
provided you have installed the following updates:
5466
+ Microsoft Visual Studio 2005 Professional Edition - ENU
5467
Service Pack 1 (KB926601)
5468
(http://support.microsoft.com/?kbid=926601)
5470
+ Security Update for Microsoft Visual Studio 2005
5471
Professional Edition - ENU (KB937061)
5472
(http://support.microsoft.com/?kbid=937061)
5474
+ Update for Microsoft Visual Studio 2005 Professional
5475
Edition - ENU (KB932232)
5476
(http://support.microsoft.com/?kbid=932232)
5478
* CMake, which can be downloaded from http://www.cmake.org.
5479
After installing, modify your path to include the cmake
5482
* Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net
5483
2003 (7.1), or Visual Studio 2005 (8.0) compiler system.
5485
* If you are using Visual C++ 2005 Express Edition, you must
5486
also install an appropriate Platform SDK. More information and
5487
links to downloads for various Windows platforms is available
5489
http://www.microsoft.com/downloads/details.aspx?familyid=0baf2
5490
b35-c656-4969-ace8-e4c0c0716adb.
5492
* If you are compiling from a Bazaar tree or making changes to
5493
the parser, you need bison for Windows, which can be
5495
http://gnuwin32.sourceforge.net/packages/bison.htm. Download
5496
the package labeled "Complete package, excluding sources".
5497
After installing the package, modify your path to include the
5498
bison binary and ensure that this binary is accessible from
5501
* Cygwin might be necessary if you want to run the test script
5502
or package the compiled binaries and support files into a Zip
5503
archive. (Cygwin is needed only to test or package the
5504
distribution, not to build it.) Cygwin is available from
5507
* 3GB to 5GB of disk space.
5509
The exact system requirements for Visual Studio can be found here:
5510
http://msdn.microsoft.com/vstudio/Previous/2003/sysreqs/default.as
5512
http://msdn.microsoft.com/vstudio/products/sysreqs/default.aspx
5514
You also need a MySQL source distribution for Windows, which can
5515
be obtained two ways:
5517
* Obtain a source distribution packaged by Sun Microsystems,
5518
Inc. These are available from http://dev.mysql.com/downloads/.
5520
* Package a source distribution yourself from the latest Bazaar
5521
developer source tree. For instructions on pulling the latest
5522
source files, see Section 2.3.3, "Installing from the
5523
Development Source Tree."
5525
If you find something not working as expected, or you have
5526
suggestions about ways to improve the current build process on
5527
Windows, please send a message to the win32 mailing list. See
5528
Section 1.5.1, "MySQL Mailing Lists."
5530
2.5.10.1. Building MySQL from Source Using CMake and Visual Studio
5532
You can build MySQL on Windows by using a combination of cmake and
5533
Microsoft Visual Studio .NET 2003 (7.1), Microsoft Visual Studio
5534
2005 (8.0) or Microsoft Visual C++ 2005 Express Edition. You must
5535
have the appropriate Microsoft Platform SDK installed.
5539
To compile from the source code on Windows you must use the
5540
standard source distribution (for example, mysql-5.1.41.tar.gz).
5541
You build from the same distribution as used to build MySQL on
5542
Unix, Linux and other platforms. Do not use the Windows Source
5543
distributions as they do not contain the necessary configuration
5544
script and other files.
5546
Follow this procedure to build MySQL:
5548
1. If you are installing from a packaged source distribution,
5549
create a work directory (for example, C:\workdir), and unpack
5550
the source distribution there using WinZip or another Windows
5551
tool that can read .zip files. This directory is the work
5552
directory in the following instructions.
5554
2. Using a command shell, navigate to the work directory and run
5555
the following command:
5556
C:\workdir>win\configure.js options
5557
If you have associated the .js file extension with an
5558
application such as a text editor, then you may need to use
5559
the following command to force configure.js to be executed as
5561
C:\workdir>cscript win\configure.js options
5562
These options are available for configure.js:
5564
+ WITH_INNOBASE_STORAGE_ENGINE: Enable the InnoDB storage
5567
+ WITH_PARTITION_STORAGE_ENGINE: Enable user-defined
5570
+ WITH_ARCHIVE_STORAGE_ENGINE: Enable the ARCHIVE storage
5573
+ WITH_BLACKHOLE_STORAGE_ENGINE: Enable the BLACKHOLE
5576
+ WITH_EXAMPLE_STORAGE_ENGINE: Enable the EXAMPLE storage
5579
+ WITH_FEDERATED_STORAGE_ENGINE: Enable the FEDERATED
5582
+ WITH_NDBCLUSTER_STORAGE_ENGINE (experimental): Enable the
5583
NDBCLUSTER storage engine in the MySQL server; cause
5584
binaries for the MySQL Cluster management and data node,
5585
management client, and other programs to be built.
5586
This option is supported only in MySQL Cluster NDB 7.0
5587
(NDBCLUSTER storage engine versions 6.4.0 and later)
5588
using the MySQL Cluster sources. It cannot be used to
5589
enable clustering support in other MySQL source trees or
5592
+ MYSQL_SERVER_SUFFIX=suffix: Server suffix, default none.
5594
+ COMPILATION_COMMENT=comment: Server comment, default
5595
"Source distribution".
5597
+ MYSQL_TCP_PORT=port: Server port, default 3306.
5599
+ DISABLE_GRANT_OPTIONS: Disables the --bootstrap,
5600
--skip-grant-tables, and --init-file options for mysqld.
5601
This option is available as of MySQL 5.1.15.
5602
For example (type the command on one line):
5603
C:\workdir>win\configure.js WITH_INNOBASE_STORAGE_ENGINE
5604
WITH_PARTITION_STORAGE_ENGINE MYSQL_SERVER_SUFFIX=-pro
5606
3. From the work directory, execute the win\build-vs8.bat or
5607
win\build-vs71.bat file, depending on the version of Visual
5608
Studio you have installed. The script invokes CMake, which
5609
generates the mysql.sln solution file.
5610
You can also use win\build-vs8_x64.bat to build the 64-bit
5611
version of MySQL. However, you cannot build the 64-bit version
5612
with Visual Studio Express Edition. You must use Visual Studio
5613
2005 (8.0) or higher.
5615
4. From the work directory, open the generated mysql.sln file
5616
with Visual Studio and select the proper configuration using
5617
the Configuration menu. The menu provides Debug, Release,
5618
RelwithDebInfo, MinRelInfo options. Then select Solution >
5619
Build to build the solution.
5620
Remember the configuration that you use in this step. It is
5621
important later when you run the test script because that
5622
script needs to know which configuration you used.
5624
5. Test the server. The server built using the preceding
5625
instructions expects that the MySQL base directory and data
5626
directory are C:\mysql and C:\mysql\data by default. If you
5627
want to test your server using the source tree root directory
5628
and its data directory as the base directory and data
5629
directory, you need to tell the server their path names. You
5630
can either do this on the command line with the --basedir and
5631
--datadir options, or by placing appropriate options in an
5632
option file. (See Section 4.2.3.3, "Using Option Files.") If
5633
you have an existing data directory elsewhere that you want to
5634
use, you can specify its path name instead.
5635
When the server is running in standalone fashion or as a
5636
service based on your configuration, try to connect to it from
5637
the mysql interactive command-line utility.
5638
You can also run the standard test script, mysql-test-run.pl.
5639
This script is written in Perl, so you'll need either Cygwin
5640
or ActiveState Perl to run it. You may also need to install
5641
the modules required by the script. To run the test script,
5642
change location into the mysql-test directory under the work
5643
directory, set the MTR_VS_CONFIG environment variable to the
5644
configuration you selected earlier (or use the --vs-config
5645
option), and invoke mysql-test-run.pl. For example (using
5646
Cygwin and the bash shell):
5647
shell> cd mysql-test
5648
shell> export MTR_VS_CONFIG=debug
5649
shell> ./mysql-test-run.pl --force --timer
5650
shell> ./mysql-test-run.pl --force --timer --ps-protocol
5652
When you are satisfied that the programs you have built are
5653
working correctly, stop the server. Now you can install the
5654
distribution. One way to do this is to use the make_win_bin_dist
5655
script in the scripts directory of the MySQL source distribution
5656
(see Section 4.4.2, "make_win_bin_dist --- Package MySQL
5657
Distribution as ZIP Archive"). This is a shell script, so you must
5658
have Cygwin installed if you want to use it. It creates a Zip
5659
archive of the built executables and support files that you can
5660
unpack in the location at which you want to install MySQL.
5662
It is also possible to install MySQL by copying directories and
5665
1. Create the directories where you want to install MySQL. For
5666
example, to install into C:\mysql, use these commands:
5668
C:\> mkdir C:\mysql\bin
5669
C:\> mkdir C:\mysql\data
5670
C:\> mkdir C:\mysql\share
5671
C:\> mkdir C:\mysql\scripts
5672
If you want to compile other clients and link them to MySQL,
5673
you should also create several additional directories:
5674
C:\> mkdir C:\mysql\include
5675
C:\> mkdir C:\mysql\lib
5676
C:\> mkdir C:\mysql\lib\debug
5677
C:\> mkdir C:\mysql\lib\opt
5678
If you want to benchmark MySQL, create this directory:
5679
C:\> mkdir C:\mysql\sql-bench
5680
Benchmarking requires Perl support. See Section 2.15, "Perl
5681
Installation Notes."
5683
2. From the work directory, copy into the C:\mysql directory the
5684
following directories:
5686
C:\workdir> copy client_release\*.exe C:\mysql\bin
5687
C:\workdir> copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.ex
5689
C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E
5690
C:\workdir> xcopy share\*.* C:\mysql\share /E
5691
If you want to compile other clients and link them to MySQL,
5692
you should also copy several libraries and header files:
5693
C:\workdir> copy lib_debug\mysqlclient.lib C:\mysql\lib\debug
5694
C:\workdir> copy lib_debug\libmysql.* C:\mysql\lib\debug
5695
C:\workdir> copy lib_debug\zlib.* C:\mysql\lib\debug
5696
C:\workdir> copy lib_release\mysqlclient.lib C:\mysql\lib\opt
5697
C:\workdir> copy lib_release\libmysql.* C:\mysql\lib\opt
5698
C:\workdir> copy lib_release\zlib.* C:\mysql\lib\opt
5699
C:\workdir> copy include\*.h C:\mysql\include
5700
C:\workdir> copy libmysql\libmysql.def C:\mysql\include
5701
If you want to benchmark MySQL, you should also do this:
5702
C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E
5704
After installation, set up and start the server in the same way as
5705
for binary Windows distributions. See Section 2.5, "Installing
5708
2.5.11. Compiling MySQL Clients on Windows
5710
In your source files, you should include my_global.h before
5712
#include <my_global.h>
5715
my_global.h includes any other files needed for Windows
5716
compatibility (such as windows.h) if you compile your program on
5719
You can either link your code with the dynamic libmysql.lib
5720
library, which is just a wrapper to load in libmysql.dll on
5721
demand, or link with the static mysqlclient.lib library.
5723
The MySQL client libraries are compiled as threaded libraries, so
5724
you should also compile your code to be multi-threaded.
5726
2.6. Installing MySQL on Linux
5728
The following sections covers the installation of Linux using
5729
RPMs. For information on using a generic binary package using tar,
5730
see Section 2.2, "Installing MySQL from Generic Binaries on
5731
Unix/Linux." For information on installing from source, see
5732
Section 2.3, "MySQL Installation Using a Source Distribution."
5734
mysql.server can be found in the support-files directory under the
5735
MySQL installation directory or in a MySQL source tree. You can
5736
install it as /etc/init.d/mysql for automatic MySQL startup and
5737
shutdown. See Section 2.13.1.2, "Starting and Stopping MySQL
5740
2.6.1. Installing MySQL from RPM Packages on Linux
5742
The recommended way to install MySQL on RPM-based Linux
5743
distributions is by using the RPM packages. The RPMs that we
5744
provide to the community should work on all versions of Linux that
5745
support RPM packages and use glibc 2.3. To obtain RPM packages,
5746
see Section 2.1.3, "How to Get MySQL."
5748
For non-RPM Linux distributions, you can install MySQL using a
5749
.tar.gz package. See Section 2.2, "Installing MySQL from Generic
5750
Binaries on Unix/Linux."
5752
We do provide some platform-specific RPMs; the difference between
5753
a platform-specific RPM and a generic RPM is that a
5754
platform-specific RPM is built on the targeted platform and is
5755
linked dynamically whereas a generic RPM is linked statically with
5760
RPM distributions of MySQL often are provided by other vendors. Be
5761
aware that they may differ in features and capabilities from those
5762
built by us, and that the instructions in this manual do not
5763
necessarily apply to installing them. The vendor's instructions
5764
should be consulted instead.
5766
In most cases, you need to install only the MySQL-server and
5767
MySQL-client packages to get a functional MySQL installation. The
5768
other packages are not required for a standard installation.
5770
RPMs for MySQL Cluster. Beginning with MySQL 5.1.24, standard
5771
MySQL server RPMs built by MySQL no longer provide support for the
5772
NDBCLUSTER storage engine. MySQL Cluster users wanting to upgrade
5773
MySQL 5.1.23 or earlier installations from RPMs built by MySQL
5774
should upgrade to MySQL Cluster NDB 6.2 or MySQL Cluster NDB 6.3;
5775
RPMs that should work with most Linux distributions are available
5776
for both of these release series.
5780
When upgrading a MySQL Cluster RPM installation, you must upgrade
5781
all installed RPMs, including the Server and Client RPMs.
5783
For more information about installing MySQL Cluster from RPMs, see
5784
Section 17.2.1, "MySQL Cluster Multi-Computer Installation."
5786
For upgrades, if your installation was originally produced by
5787
installing multiple RPM packages, it is best to upgrade all the
5788
packages, not just some. For example, if you previously installed
5789
the server and client RPMs, do not upgrade just the server RPM.
5791
The RPM packages shown in the following list are available. The
5792
names shown here use a suffix of .glibc23.i386.rpm, but particular
5793
packages can have different suffixes, described later.
5795
* MySQL-server-VERSION.glibc23.i386.rpm
5796
The MySQL server. You need this unless you only want to
5797
connect to a MySQL server running on another machine.
5799
* MySQL-client-VERSION.glibc23.i386.rpm
5800
The standard MySQL client programs. You probably always want
5801
to install this package.
5803
* MySQL-devel-VERSION.glibc23.i386.rpm
5804
The libraries and include files that are needed if you want to
5805
compile other MySQL clients, such as the Perl modules.
5807
* MySQL-debuginfo-VERSION.glibc23.i386.rpm
5808
This package contains debugging information. debuginfo RPMs
5809
are never needed to use MySQL software; this is true both for
5810
the server and for client programs. However, they contain
5811
additional information that might be needed by a debugger to
5814
* MySQL-shared-VERSION.glibc23.i386.rpm
5815
This package contains the shared libraries
5816
(libmysqlclient.so*) that certain languages and applications
5817
need to dynamically load and use MySQL. It contains
5818
single-threaded and thread-safe libraries. If you install this
5819
package, do not install the MySQL-shared-compat package.
5821
* MySQL-shared-compat-VERSION.glibc23.i386.rpm
5822
This package includes the shared libraries for MySQL 3.23,
5823
4.0, and so on, up to the current release. It contains
5824
single-threaded and thread-safe libraries. Install this
5825
package instead of MySQL-shared if you have applications
5826
installed that are dynamically linked against older versions
5827
of MySQL but you want to upgrade to the current version
5828
without breaking the library dependencies.
5830
* MySQL-shared-compat-advanced-gpl-VERSION.glibc23.i386.rpm,
5831
MySQL-shared-compat-advanced-VERSION.glibc23.i386.rpm
5832
These are like the MySQL-shared-compat package, but are for
5833
the "MySQL Enterprise Server - Advanced Edition" products.
5834
Install these packages rather than the normal
5835
MySQL-shared-compat package if you want to included shared
5836
client libraries for older MySQL versions.
5838
* MySQL-embedded-VERSION.glibc23.i386.rpm
5839
The embedded MySQL server library.
5841
* MySQL-ndb-management-VERSION.glibc23.i386.rpm,
5842
MySQL-ndb-storage-VERSION.glibc23.i386.rpm,
5843
MySQL-ndb-tools-VERSION.glibc23.i386.rpm,
5844
MySQL-ndb-extra-VERSION.glibc23.i386.rpm
5845
Packages that contain additional files for MySQL Cluster
5849
The MySQL-ndb-tools RPM requires a working installation of
5850
perl. Prior to MySQL 5.1.18, the DBI and HTML::Template
5851
packages were also required. See Section 2.15, "Perl
5852
Installation Notes," and Section 17.4.21, "ndb_size.pl ---
5853
NDBCLUSTER Size Requirement Estimator," for more information.
5855
* MySQL-test-VERSION.glibc23.i386.rpm
5856
This package includes the MySQL test suite.
5858
* MySQL-VERSION.src.rpm
5859
This contains the source code for all of the previous
5860
packages. It can also be used to rebuild the RPMs on other
5861
architectures (for example, Alpha or SPARC).
5863
The suffix of RPM package names (following the VERSION value) has
5864
the following syntax:
5867
The PLATFORM and CPU values indicate the type of system for which
5868
the package is built. PLATFORM indicates the platform and CPU
5869
indicates the processor type or family.
5871
All packages are dynamically linked against glibc 2.3. The
5872
PLATFORM value indicates whether the package is platform
5873
independent or intended for a specific platform, as shown in the
5875
glibc23 Platform independent, should run on any Linux distribution
5876
that supports glibc 2.3
5877
rhel3, rhel4 Red Hat Enterprise Linux 3 or 4
5878
sles9, sles10 SuSE Linux Enterprise Server 9 or 10
5880
In MySQL 5.1, only glibc23 packages are available currently.
5882
The CPU value indicates the processor type or family for which the
5884
i386 x86 processor, 386 and up
5885
i586 x86 processor, Pentium and up
5886
x86_64 64-bit x86 processor
5887
ia64 Itanium (IA-64) processor
5889
To see all files in an RPM package (for example, a MySQL-server
5890
RPM), run a command like this:
5891
shell> rpm -qpl MySQL-server-VERSION.glibc23.i386.rpm
5893
To perform a standard minimal installation, install the server and
5895
shell> rpm -i MySQL-server-VERSION.glibc23.i386.rpm
5896
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
5898
To install only the client programs, install just the client RPM:
5899
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
5901
RPM provides a feature to verify the integrity and authenticity of
5902
packages before installing them. If you would like to learn more
5903
about this feature, see Section 2.1.4, "Verifying Package
5904
Integrity Using MD5 Checksums or GnuPG."
5906
The server RPM places data under the /var/lib/mysql directory. The
5907
RPM also creates a login account for a user named mysql (if one
5908
does not exist) to use for running the MySQL server, and creates
5909
the appropriate entries in /etc/init.d/ to start the server
5910
automatically at boot time. (This means that if you have performed
5911
a previous installation and have made changes to its startup
5912
script, you may want to make a copy of the script so that you
5913
don't lose it when you install a newer RPM.) See Section 2.13.1.2,
5914
"Starting and Stopping MySQL Automatically," for more information
5915
on how MySQL can be started automatically on system startup.
5917
If you want to install the MySQL RPM on older Linux distributions
5918
that do not support initialization scripts in /etc/init.d
5919
(directly or via a symlink), you should create a symbolic link
5920
that points to the location where your initialization scripts
5921
actually are installed. For example, if that location is
5922
/etc/rc.d/init.d, use these commands before installing the RPM to
5923
create /etc/init.d as a symbolic link that points there:
5925
shell> ln -s rc.d/init.d .
5927
However, all current major Linux distributions should support the
5928
new directory layout that uses /etc/init.d, because it is required
5929
for LSB (Linux Standard Base) compliance.
5931
If the RPM files that you install include MySQL-server, the mysqld
5932
server should be up and running after installation. You should be
5933
able to start using MySQL.
5935
If something goes wrong, you can find more information in the
5936
binary installation section. See Section 2.2, "Installing MySQL
5937
from Generic Binaries on Unix/Linux."
5941
The accounts that are listed in the MySQL grant tables initially
5942
have no passwords. After starting the server, you should set up
5943
passwords for them using the instructions in Section 2.13,
5944
"Post-Installation Setup and Testing."
5946
During RPM installation, a user named mysql and a group named
5947
mysql are created on the system. This is done using the useradd,
5948
groupadd, and usermod commands. Those commands require appropriate
5949
administrative privileges, which is ensured for locally managed
5950
users and groups (as listed in the /etc/passwd and /etc/group
5951
files) by the RPM installation process being run by root.
5953
For nonlocal user management (LDAP, NIS, and so forth), the
5954
administrative tools may require additional authentication (such
5955
as a password), and will fail if the installing user does not
5956
provide this authentication. Even if they fail, the RPM
5957
installation will not abort but succeed, and this is intentional.
5958
If they failed, some of the intended transfer of ownership may be
5959
missing, and it is recommended that the system administrator then
5960
manually ensures some appropriate user andgroup exists and
5961
manually transfers ownership following the actions in the RPM spec
5964
2.7. Installing MySQL on Mac OS X
3014
If you are running a version of Windows that supports services,
3015
you can set up the MySQL server to run automatically when Windows
3016
starts. See Section 2.3.5.7, "Starting MySQL Server as a Microsoft
3019
2.4. Installing MySQL on Mac OS X
5966
3021
MySQL for Mac OS X is available in a number of different forms:
5968
3023
* Native Package Installer format, which uses the native Mac OS
5969
3024
X installer to walk you through the installation of MySQL. For
5970
more information, see Section 2.7.1, "Installing MySQL Using
5971
the Installation Package." You can use the package installer
5972
with Mac OS X 10.3 and later, and available for both PowerPC
5973
and Intel architectures, and both 32-bit and 64-bit
3025
more information, see Section 2.4.2, "Installing MySQL on Mac
3026
OS X Using Native Packages." You can use the package installer
3027
with Mac OS X 10.3 and later, and the package is available for
3028
both PowerPC and Intel architectures, and 32-bit and 64-bit
5974
3029
architectures. There is no Universal Binary available using
5975
3030
the package installation method. The user you use to perform
5976
3031
the installation must have administrator privileges.
6245
The installation layout of MySQL on Mac OS X Server is as shown in
6247
Directory Contents of Directory
6248
/usr/bin Client programs
6249
/var/mysql Log files, databases
6250
/usr/libexec The mysqld server
6251
/usr/share/man Unix manual pages
3366
The following table shows the installation layout of MySQL on Mac
3369
Table 2.14. MySQL Directory Layout for Preinstalled MySQL
3370
installations on Mac OS X Server
3371
Directory Contents of Directory
3372
/usr/bin Client programs
3373
/var/mysql Log files, databases
3374
/usr/libexec The mysqld server
3375
/usr/share/man Unix manual pages
6252
3376
/usr/share/mysql/mysql-test MySQL test suite
6253
/usr/share/mysql Contains the mysql_install_db script
6254
/var/mysql/mysql.sock The location of the MySQL Unix socket
6258
The MySQL server bundled with Mac OS X Server does not include the
6259
MySQL client libraries and header files required if you want to
6260
access and use MySQL from a third-party driver, such as Perl DBI
6261
or PHP. For more information on obtaining and installing MySQL
6262
libraries, see Mac OS X Server version 10.5: MySQL libraries
6263
available for download (http://support.apple.com/kb/TA25017).
6264
Alternatively, you can ignore the bundled MySQL server and install
6265
MySQL from the package or tarball installation.
6267
For more information on managing the bundled MySQL instance in Mac
6268
OS X Server 10.5, see Mac OS X Server: Web Technologies
6269
Administration For Version 10.5 Leopard
6270
(http://images.apple.com/server/macosx/docs/Web_Technologies_Admin
6271
_v10.5.pdf). For more information on managing the bundled MySQL
6272
instance in Mac OS X Server 10.6, see Mac OS X Server: Web
6273
Technologies Administration Version 10.6 Snow Leopard
6274
(http://manuals.info.apple.com/en_US/WebTech_v10.6.pdf).
6276
2.7.5. MySQL Installation on Mac OS X Notes
6278
You should keep the following issues and notes in mind:
6280
* The default location for the MySQL Unix socket is different on
6281
Mac OS X and Mac OS X Server depending on the installation
6282
type you chose. The default locations by installation are as
6285
Package Installer from MySQL /tmp/mysql.sock
6286
Tarball from MySQL /tmp/mysql.sock
6287
MySQL Bundled with Mac OS X Server /var/mysql/mysql.sock
6288
To prevent issues, you should either change the configuration
6289
of the socket used within your application (for example,
6290
changing php.ini), or you should configure the socket location
6291
using a MySQL configuration file and the socket option. For
6292
more information, see Section 5.1.2, "Server Command Options."
6294
* You may need (or want) to create a specific mysql user to own
6295
the MySQL directory and data. On Mac OS X 10.4 and lower you
6296
can do this by using the Netinfo Manager application, located
6297
within the Utilities folder within the Applications folder. On
6298
Mac OS X 10.5 and later you can do this through the Directory
6299
Utility. From Mac OS X 10.5 and later (including Mac OS X
6300
Server 10.5) the mysql should already exist. For use in single
6301
user mode, an entry for _mysql (note the underscore prefix)
6302
should already exist within the system /etc/passwd file.
6304
* Due to a bug in the Mac OS X package installer, you may see
6305
this error message in the destination disk selection dialog:
6306
You cannot install this software on this disk. (null)
6307
If this error occurs, simply click the Go Back button once to
6308
return to the previous screen. Then click Continue to advance
6309
to the destination disk selection again, and you should be
6310
able to choose the destination disk correctly. We have
6311
reported this bug to Apple and it is investigating this
6314
* Because the MySQL package installer installs the MySQL
6315
contents into a version and platform specific directory, you
6316
can use this to upgrade and migrate your database between
6317
versions. You will need to either copy the data directory from
6318
the old version to the new version, or alternatively specify
6319
an alternative datadir value to set location of the data
6322
* You might want to add aliases to your shell's resource file to
6323
make it easier to access commonly used programs such as mysql
6324
and mysqladmin from the command line. The syntax for bash is:
6325
alias mysql=/usr/local/mysql/bin/mysql
6326
alias mysqladmin=/usr/local/mysql/bin/mysqladmin
6328
alias mysql /usr/local/mysql/bin/mysql
6329
alias mysqladmin /usr/local/mysql/bin/mysqladmin
6330
Even better, add /usr/local/mysql/bin to your PATH environment
6331
variable. You can do this by modifying the appropriate startup
6332
file for your shell. For more information, see Section 4.2.1,
6333
"Invoking MySQL Programs."
6335
* After you have copied over the MySQL database files from the
6336
previous installation and have successfully started the new
6337
server, you should consider removing the old installation
6338
files to save disk space. Additionally, you should also remove
6339
older versions of the Package Receipt directories located in
6340
/Library/Receipts/mysql-VERSION.pkg.
6342
2.8. Installing MySQL on Solaris
3377
/usr/share/mysql Miscellaneous support files, including error
3378
messages, character set files, sample configuration files, SQL for
3379
database installation
3380
/var/mysql/mysql.sock Location of the MySQL Unix socket
3382
Additional Resources
3385
* For more information on managing the bundled MySQL instance in
3386
Mac OS X Server 10.5, see Mac OS X Server: Web Technologies
3387
Administration For Version 10.5 Leopard
3388
(http://images.apple.com/server/macosx/docs/Web_Technologies_A
3391
* For more information on managing the bundled MySQL instance in
3392
Mac OS X Server 10.6, see Mac OS X Server: Web Technologies
3393
Administration Version 10.6 Snow Leopard
3394
(http://manuals.info.apple.com/en_US/WebTech_v10.6.pdf).
3396
* The MySQL server bundled with Mac OS X Server does not include
3397
the MySQL client libraries and header files required to access
3398
and use MySQL from a third-party driver, such as Perl DBI or
3399
PHP. For more information on obtaining and installing MySQL
3400
libraries, see Mac OS X Server version 10.5: MySQL libraries
3401
available for download (http://support.apple.com/kb/TA25017).
3402
Alternatively, you can ignore the bundled MySQL server and
3403
install MySQL from the package or tarball installation.
3405
2.5. Installing MySQL on Linux
3407
Linux supports a number of different solutions for installing
3408
MySQL. The recommended method is to use one of the distributions
3409
from Oracle. If you choose this method, there are three options
3412
* Installing from a generic binary package in .tar.gz format.
3413
See Section 2.2, "Installing MySQL from Generic Binaries on
3414
Unix/Linux" for more information.
3416
* Extracting and compiling MySQL from a source distribution. For
3417
detailed instructions, see Section 2.11, "Installing MySQL
3420
* Installing using a pre-compiled RPM package. For more
3421
information on using the RPM solution, see Section 2.5.1,
3422
"Installing MySQL from RPM Packages on Linux."
3424
As an alternative, you can use the native package manager within
3425
your Linux distribution to automatically download and install
3426
MySQL for you. Native package installations can take of the
3427
download and dependencies required to run MySQL, but the MySQL
3428
version will often be some way behind the currently available
3429
release. You will also normally be unable to install developmental
3430
releases, as these are not usually made available in the native
3431
repository. For more information on using the native package
3432
installers, see Section 2.5.2, "Installing MySQL on Linux using
3433
Native Package Manager."
3436
For many Linux installations, you will want to set up MySQL to be
3437
started automatically when your machine starts. Many of the native
3438
package installations perform this operation for you, but for
3439
source, binary and RPM solutions you may need to set this up
3440
separately. The required script, mysql.server, can be found in the
3441
support-files directory under the MySQL installation directory or
3442
in a MySQL source tree. You can install it as /etc/init.d/mysql
3443
for automatic MySQL startup and shutdown. See Section 2.12.1.2,
3444
"Starting and Stopping MySQL Automatically."
3446
2.5.1. Installing MySQL from RPM Packages on Linux
3448
The recommended way to install MySQL on RPM-based Linux
3449
distributions is by using the RPM packages. The RPMs that we
3450
provide to the community should work on all versions of Linux that
3451
support RPM packages and use glibc 2.3. To obtain RPM packages,
3452
see Section 2.1.3, "How to Get MySQL."
3454
For non-RPM Linux distributions, you can install MySQL using a
3455
.tar.gz package. See Section 2.2, "Installing MySQL from Generic
3456
Binaries on Unix/Linux."
3458
Installations created from our Linux RPM distributions result in
3459
files under the following system directories.
3461
Table 2.15. MySQL Installation Layout for Linux RPM
3462
Directory Contents of Directory
3463
/usr/bin Client programs and scripts
3464
/usr/sbin The mysqld server
3465
/var/lib/mysql Log files, databases
3466
/usr/share/info Manual in Info format
3467
/usr/share/man Unix manual pages
3468
/usr/include/mysql Include (header) files
3469
/usr/lib/mysql Libraries
3470
/usr/share/mysql Miscellaneous support files, including error
3471
messages, character set files, sample configuration files, SQL for
3472
database installation
3473
/usr/share/sql-bench Benchmarks
3476
RPM distributions of MySQL are also provided by other vendors. Be
3477
aware that they may differ from those built by us in features,
3478
capabilities, and conventions (including communication setup), and
3479
that the instructions in this manual do not necessarily apply to
3480
installing them. The vendor's instructions should be consulted
3483
In most cases, you need to install only the MySQL-server and
3484
MySQL-client packages to get a functional MySQL installation. The
3485
other packages are not required for a standard installation.
3487
RPMs for MySQL Cluster. Beginning with MySQL 5.1.24, standard
3488
MySQL server RPMs built by MySQL no longer provide support for the
3489
NDBCLUSTER storage engine. MySQL Cluster users should check the
3490
MySQL Cluster Downloads page at
3491
http://dev.mysql.com/downloads/cluster/ for RPMs that should work
3492
with most Linux distributions for both of these release series.
3495
When upgrading a MySQL Cluster RPM installation, you must upgrade
3496
all installed RPMs, including the Server and Client RPMs.
3498
For more information about installing MySQL Cluster from RPMs, see
3499
Section 16.2.1.2, "Installing MySQL Cluster from RPM."
3501
For upgrades, if your installation was originally produced by
3502
installing multiple RPM packages, it is best to upgrade all the
3503
packages, not just some. For example, if you previously installed
3504
the server and client RPMs, do not upgrade just the server RPM.
3506
The RPM packages shown in the following list are available. The
3507
names shown here use a suffix of .glibc23.i386.rpm, but particular
3508
packages can have different suffixes, described later.
3510
* MySQL-server-VERSION.glibc23.i386.rpm
3511
The MySQL server. You need this unless you only want to
3512
connect to a MySQL server running on another machine.
3514
* MySQL-client-VERSION.glibc23.i386.rpm
3515
The standard MySQL client programs. You probably always want
3516
to install this package.
3518
* MySQL-devel-VERSION.glibc23.i386.rpm
3519
The libraries and include files that are needed if you want to
3520
compile other MySQL clients, such as the Perl modules.
3522
* MySQL-debuginfo-VERSION.glibc23.i386.rpm
3523
This package contains debugging information. It is specific to
3524
Red Hat Enterprise Linux. debuginfo RPMs are never needed to
3525
use MySQL software; this is true both for the server and for
3526
client programs. However, they contain additional information
3527
that might be needed by a debugger to analyze a crash.
3529
* MySQL-shared-VERSION.glibc23.i386.rpm
3530
This package contains the shared libraries
3531
(libmysqlclient.so*) that certain languages and applications
3532
need to dynamically load and use MySQL. It contains
3533
single-threaded and thread-safe libraries. If you install this
3534
package, do not install the MySQL-shared-compat package.
3536
* MySQL-shared-compat-VERSION.glibc23.i386.rpm
3537
This package includes the shared libraries for older releases,
3538
up to the current release. It contains single-threaded and
3539
thread-safe libraries. Install this package instead of
3540
MySQL-shared if you have applications installed that are
3541
dynamically linked against older versions of MySQL but you
3542
want to upgrade to the current version without breaking the
3543
library dependencies.
3545
* MySQL-shared-compat-advanced-gpl-VERSION.glibc23.i386.rpm,
3546
MySQL-shared-compat-advanced-VERSION.glibc23.i386.rpm
3547
These are like the MySQL-shared-compat package, but are for
3548
the "MySQL Enterprise Server - Advanced Edition" products.
3549
Install these packages rather than the normal
3550
MySQL-shared-compat package if you want to included shared
3551
client libraries for older MySQL versions.
3553
* MySQL-embedded-VERSION.glibc23.i386.rpm
3554
The embedded MySQL server library.
3556
* MySQL-ndb-management-VERSION.glibc23.i386.rpm,
3557
MySQL-ndb-storage-VERSION.glibc23.i386.rpm,
3558
MySQL-ndb-tools-VERSION.glibc23.i386.rpm,
3559
MySQL-ndb-extra-VERSION.glibc23.i386.rpm
3560
Packages that contain additional files for MySQL Cluster
3563
The MySQL-ndb-tools RPM requires a working installation of
3564
perl. Prior to MySQL 5.1.18, the DBI and HTML::Template
3565
packages were also required. See Section 2.15, "Perl
3566
Installation Notes," and Section 16.4.21, "ndb_size.pl ---
3567
NDBCLUSTER Size Requirement Estimator," for more information.
3569
* MySQL-test-VERSION.glibc23.i386.rpm
3570
This package includes the MySQL test suite.
3572
* MySQL-VERSION.src.rpm
3573
This contains the source code for all of the previous
3574
packages. It can also be used to rebuild the RPMs on other
3575
architectures (for example, Alpha or SPARC).
3577
The suffix of RPM package names (following the VERSION value) has
3578
the following syntax:
3581
The PLATFORM and CPU values indicate the type of system for which
3582
the package is built. PLATFORM indicates the platform and CPU
3583
indicates the processor type or family.
3585
All packages are dynamically linked against glibc 2.3. The
3586
PLATFORM value indicates whether the package is platform
3587
independent or intended for a specific platform, as shown in the
3590
Table 2.16. MySQL Linux Installation Packages
3591
PLATFORM Value Intended Use
3592
glibc23 Platform independent, should run on any Linux distribution
3593
that supports glibc 2.3
3594
rhel4, rhel5 Red Hat Enterprise Linux 4 or 5
3595
sles10, sles11 SuSE Linux Enterprise Server 10 or 11
3597
In MySQL 5.1, only glibc23 packages are available currently.
3599
The CPU value indicates the processor type or family for which the
3602
Table 2.17. MySQL Installation Packages for Linux CPU Identifier
3603
CPU Value Intended Processor Type or Family
3604
i386, i586, i686 Pentium processor or better, 32 bit
3605
x86_64 64-bit x86 processor
3606
ia64 Itanium (IA-64) processor
3608
To see all files in an RPM package (for example, a MySQL-server
3609
RPM), run a command like this:
3610
shell> rpm -qpl MySQL-server-VERSION.glibc23.i386.rpm
3612
To perform a standard minimal installation, install the server and
3614
shell> rpm -i MySQL-server-VERSION.glibc23.i386.rpm
3615
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
3617
To install only the client programs, install just the client RPM:
3618
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
3620
RPM provides a feature to verify the integrity and authenticity of
3621
packages before installing them. If you would like to learn more
3622
about this feature, see Section 2.1.4, "Verifying Package
3623
Integrity Using MD5 Checksums or GnuPG."
3625
The server RPM places data under the /var/lib/mysql directory. The
3626
RPM also creates a login account for a user named mysql (if one
3627
does not exist) to use for running the MySQL server, and creates
3628
the appropriate entries in /etc/init.d/ to start the server
3629
automatically at boot time. (This means that if you have performed
3630
a previous installation and have made changes to its startup
3631
script, you may want to make a copy of the script so that you do
3632
not lose it when you install a newer RPM.) See Section 2.12.1.2,
3633
"Starting and Stopping MySQL Automatically," for more information
3634
on how MySQL can be started automatically on system startup.
3636
In MySQL 5.1.49 and later, during an upgrade installation using
3637
the RPM packages, if the MySQL server is running when the upgrade
3638
occurs, the MySQL server is stopped, the upgrade occurs, and the
3639
MySQL server is restarted. If the MySQL server is not already
3640
running when the RPM upgrade occurs, the MySQL server is not
3641
started at the end of the installation.
3643
If something goes wrong, you can find more information in the
3644
binary installation section. See Section 2.2, "Installing MySQL
3645
from Generic Binaries on Unix/Linux."
3648
The accounts that are listed in the MySQL grant tables initially
3649
have no passwords. After starting the server, you should set up
3650
passwords for them using the instructions in Section 2.12,
3651
"Postinstallation Setup and Testing."
3653
During RPM installation, a user named mysql and a group named
3654
mysql are created on the system. This is done using the useradd,
3655
groupadd, and usermod commands. Those commands require appropriate
3656
administrative privileges, which is required for locally managed
3657
users and groups (as listed in the /etc/passwd and /etc/group
3658
files) by the RPM installation process being run by root.
3660
If you log in as the mysql user, you may find that MySQL displays
3661
"Invalid (old?) table or database name" errors that mention
3662
.mysqlgui, lost+found, .mysqlgui, .bash_history, .fonts.cache-1,
3663
.lesshst, .mysql_history, .profile, .viminfo, and similar files
3664
created by MySQL or operating system utilities. You can safely
3665
ignore these error messages or remove the files or directories
3666
that cause them if you do not need them.
3668
For nonlocal user management (LDAP, NIS, and so forth), the
3669
administrative tools may require additional authentication (such
3670
as a password), and will fail if the installing user does not
3671
provide this authentication. Even if they fail, the RPM
3672
installation will not abort but succeed, and this is intentional.
3673
If they failed, some of the intended transfer of ownership may be
3674
missing, and it is recommended that the system administrator then
3675
manually ensures some appropriate user and group exists and
3676
manually transfers ownership following the actions in the RPM spec
3679
2.5.2. Installing MySQL on Linux using Native Package Manager
3681
Many Linux distributions include a version of the MySQL server,
3682
client tools, and development components into the standard package
3683
management system built into distributions such as Fedora, Debian,
3684
Ubuntu, and Gentoo. This section provides basic instructions for
3685
installing MySQL using these systems.
3688
Native package installations can take care of the download and
3689
dependencies required to run MySQL, but the MySQL version will
3690
often be some way behind the currently available release. You will
3691
also normally be unable to install developmental releases, as
3692
these are not usually made available in the native repository.
3694
Distribution specific instructions are shown below:
3696
* Red Hat Linux, Fedora, CentOS
3697
For Red Hat and similar distributions, the MySQL distribution
3698
is divided into a number of separate packages, mysql for the
3699
client tools, mysql-server for the server and associated
3700
tools, and mysql-libs for the libraries. The libraries are
3701
required if you want to provide connectivity from different
3702
languages and environments such as Perl, Python and others.
3703
To install, use the yum command to specify the packages that
3704
you want to install. For example:
3705
root-shell> yum install mysql mysql-server mysql-libs mysql-server
3706
Loaded plugins: presto, refresh-packagekit
3707
Setting up Install Process
3708
Resolving Dependencies
3709
--> Running transaction check
3710
---> Package mysql.x86_64 0:5.1.48-2.fc13 set to be updated
3711
---> Package mysql-libs.x86_64 0:5.1.48-2.fc13 set to be updated
3712
---> Package mysql-server.x86_64 0:5.1.48-2.fc13 set to be updated
3713
--> Processing Dependency: perl-DBD-MySQL for package: mysql-server-5
3715
--> Running transaction check
3716
---> Package perl-DBD-MySQL.x86_64 0:4.017-1.fc13 set to be updated
3717
--> Finished Dependency Resolution
3719
Dependencies Resolved
3721
=====================================================================
3723
Package Arch Version Repository
3725
=====================================================================
3728
mysql x86_64 5.1.48-2.fc13 updates
3730
mysql-libs x86_64 5.1.48-2.fc13 updates
3732
mysql-server x86_64 5.1.48-2.fc13 updates
3734
Installing for dependencies:
3735
perl-DBD-MySQL x86_64 4.017-1.fc13 updates
3739
=====================================================================
3741
Install 4 Package(s)
3742
Upgrade 0 Package(s)
3744
Total download size: 10 M
3745
Installed size: 30 M
3747
Downloading Packages:
3748
Setting up and reading Presto delta metadata
3749
Processing delta metadata
3750
Package(s) data still to download: 10 M
3751
(1/4): mysql-5.1.48-2.fc13.x86_64.rpm | 889 kB
3753
(2/4): mysql-libs-5.1.48-2.fc13.x86_64.rpm | 1.2 MB
3755
(3/4): mysql-server-5.1.48-2.fc13.x86_64.rpm | 8.1 MB
3757
(4/4): perl-DBD-MySQL-4.017-1.fc13.x86_64.rpm | 136 kB
3759
---------------------------------------------------------------------
3761
Total 201 kB/s | 10 MB
3763
Running rpm_check_debug
3764
Running Transaction Test
3765
Transaction Test Succeeded
3767
Installing : mysql-libs-5.1.48-2.fc13.x86_64
3769
Installing : mysql-5.1.48-2.fc13.x86_64
3771
Installing : perl-DBD-MySQL-4.017-1.fc13.x86_64
3773
Installing : mysql-server-5.1.48-2.fc13.x86_64
3777
mysql.x86_64 0:5.1.48-2.fc13 mysql-libs.x86_64 0:5.1.48-
3779
mysql-server.x86_64 0:5.1.48-2.fc13
3781
Dependency Installed:
3782
perl-DBD-MySQL.x86_64 0:4.017-1.fc13
3786
MySQL and the MySQL server should now be installed. A sample
3787
configuration file is installed into /etc/my.cnf. An init
3788
script, to start and stop the server, will have been installed
3789
into /etc/init.d/mysqld. To start the MySQL server use
3791
root-shell> service mysqld start
3792
To enable the server to be started and stopped automatically
3793
during boot, use chkconfig:
3794
root-shell> chkconfig --levels 235 mysqld on
3795
Which enables the MySQL server to be started (and stopped)
3796
automatically at the specified the run levels.
3797
The database tables will have been automatically created for
3798
you, if they do not already exist. You should, however, run
3799
mysql_secure_installation to set the root passwords on your
3802
* Debian, Ubuntu, Kubuntu
3803
On Debian and related distributions, there are two packages,
3804
mysql-client and mysql-server, for the client and server
3805
components respectively. You should specify an explicit
3806
version, for example mysql-client-5.1, to ensure that you
3807
install the version of MySQL that you want.
3808
To download and install, including any dependencies, use the
3809
apt-get command, specifying the packages that you want to
3812
Before installing, make sure that you update your apt-get
3813
index files to ensure you are downloading the latest available
3815
A sample installation of the MySQL packages might look like
3816
this (some sections trimmed for clarity):
3817
root-shell> apt-get install mysql-client-5.1 mysql-server-5.1
3818
Reading package lists... Done
3819
Building dependency tree
3820
Reading state information... Done
3821
The following packages were automatically installed and are no longer
3823
linux-headers-2.6.28-11 linux-headers-2.6.28-11-generic
3824
Use 'apt-get autoremove' to remove them.
3825
The following extra packages will be installed:
3826
bsd-mailx libdbd-mysql-perl libdbi-perl libhtml-template-perl
3827
libmysqlclient15off libmysqlclient16 libnet-daemon-perl libplrpc-pe
3829
mysql-common postfix
3831
dbishell libipc-sharedcache-perl tinyca procmail postfix-mysql post
3833
postfix-ldap postfix-pcre sasl2-bin resolvconf postfix-cdb
3834
The following NEW packages will be installed
3835
bsd-mailx libdbd-mysql-perl libdbi-perl libhtml-template-perl
3836
libmysqlclient15off libmysqlclient16 libnet-daemon-perl libplrpc-pe
3838
mysql-client-5.1 mysql-common mysql-server-5.1 postfix
3839
0 upgraded, 13 newly installed, 0 to remove and 182 not upgraded.
3840
Need to get 1907kB/25.3MB of archives.
3841
After this operation, 59.5MB of additional disk space will be used.
3842
Do you want to continue [Y/n]? Y
3843
Get: 1 http://gb.archive.ubuntu.com jaunty-updates/main mysql-common
3844
5.1.30really5.0.75-0ubuntu10.5 [63.6kB]
3845
Get: 2 http://gb.archive.ubuntu.com jaunty-updates/main libmysqlclien
3846
t15off 5.1.30really5.0.75-0ubuntu10.5 [1843kB]
3847
Fetched 1907kB in 9s (205kB/s)
3849
Preconfiguring packages ...
3850
Selecting previously deselected package mysql-common.
3851
(Reading database ... 121260 files and directories currently installe
3854
Processing 1 added doc-base file(s)...
3855
Registering documents with scrollkeeper...
3856
Setting up libnet-daemon-perl (0.43-1) ...
3857
Setting up libplrpc-perl (0.2020-1) ...
3858
Setting up libdbi-perl (1.607-1) ...
3859
Setting up libmysqlclient15off (5.1.30really5.0.75-0ubuntu10.5) ...
3861
Setting up libdbd-mysql-perl (4.008-1) ...
3862
Setting up libmysqlclient16 (5.1.31-1ubuntu2) ...
3864
Setting up mysql-client-5.1 (5.1.31-1ubuntu2) ...
3866
Setting up mysql-server-5.1 (5.1.31-1ubuntu2) ...
3868
* Stopping MySQL database server mysqld
3870
100825 11:46:15 InnoDB: Started; log sequence number 0 46409
3871
100825 11:46:15 InnoDB: Starting shutdown...
3872
100825 11:46:17 InnoDB: Shutdown completed; log sequence number 0 46
3874
100825 11:46:17 [Warning] Forcing shutdown of 1 plugins
3876
* Starting MySQL database server mysqld
3879
* Checking for corrupt, not cleanly closed and upgrade needing table
3882
Processing triggers for libc6 ...
3883
ldconfig deferred processing now taking place
3885
The apt-get command will install a number of packages,
3886
including the MySQL server, in order to provide the typical
3887
tools and application environment. This can mean that you
3888
install a large number of packages in addition to the main
3890
During installation, the initial database will be created, and
3891
you will be prompted for the MySQL root password (and
3892
confirmation). A configuration file will have been created in
3893
/etc/mysql/my.cnf. An init script will have been created in
3895
The server will already be started. You can manually start and
3896
stop the server using:
3897
root-shell> service mysql [start|stop]
3898
The service will automatically be added to the 2, 3 and 4 run
3899
levels, with stop scripts in the single, shutdown and restart
3903
As a source-based distribution, installing MySQL on Gentoo
3904
involves downloading the source, patching the Gentoo
3905
specifics, and then compiling the MySQL server and installing
3906
it. This process is handled automatically by the emerge
3907
command. Depending on the version of MySQL that you want to
3908
install, you may need to unmask the specific version that you
3909
want for your chosen platform.
3910
The MySQL server and client tools are provided within a single
3911
package, dev-db/mysql. You can obtain a list of the versions
3912
available to install by looking at the portage directory for
3914
root-shell> ls /usr/portage/dev-db/mysql/mysql-5.1*
3915
mysql-5.1.39-r1.ebuild
3916
mysql-5.1.44-r1.ebuild
3917
mysql-5.1.44-r2.ebuild
3918
mysql-5.1.44-r3.ebuild
3920
mysql-5.1.45-r1.ebuild
3923
To install a specific MySQL version, you must specify the
3924
entire atom. For example:
3925
root-shell> emerge =dev-db/mysql-5.1.46
3926
A simpler alternative is to use the virtual/mysql-5.1 package,
3927
which will install the latest version:
3928
root-shell> emerge =virtual/mysql-5.1
3929
If the package is masked (because it is not tested or
3930
certified for the current platform), use the ACCEPT_KEYWORDS
3931
environment variable. For example:
3932
root-shell> ACCEPT_KEYWORDS="~x86" emerge =virtual/mysql-5.1
3933
After installation, you should create a new database using
3934
mysql_install_db, and set the password for the root user on
3935
MySQL. You can use the configuration interface to set the
3936
password and create the initial database:
3937
root-shell> emerge --config =dev-db/mysql-5.1.46
3938
A sample configuration file will have been created for you in
3939
/etc/mysql/my.cnf, and an init script will have been created
3940
in /etc/init.d/mysql.
3941
To enable MySQL to start automatically at the normal (default)
3942
run levels, you can use:
3943
root-shell> rc-update add default mysql
3945
2.6. Installing MySQL on Solaris and OpenSolaris
3947
MySQL on Solaris and OpenSolaris is available in a number of
3950
* For information on installing using the native Solaris PKG
3951
format, see Section 2.6.1, "Installing MySQL on Solaris using
3954
* On OpenSolaris, the standard package repositories include
3955
MySQL packages specially built for OpenSolaris that include
3956
entries for the Service Management Framework (SMF) to enable
3957
control of the installation using the SMF administration
3958
commands. For more information, see Section 2.6.2, "Installing
3959
MySQL on OpenSolaris using IPS."
3961
* To use a standard tar binary installation, use the notes
3962
provided in Section 2.2, "Installing MySQL from Generic
3963
Binaries on Unix/Linux." Check the notes and hints at the end
3964
of this section for Solaris specific notes that you may need
3965
before or after installation.
3967
* For information on installing MySQL on Solaris or OpenSolaris
3968
using a source distribution, first check the Solaris advice,
3969
Section 2.11.8, "Notes on Installing MySQL on Solaris from
3970
Source." For detailed instructions on installing from source,
3971
see Section 2.11, "Installing MySQL from Source."
6344
3973
To obtain a binary MySQL distribution for Solaris in tarball or
6345
3974
PKG format, http://dev.mysql.com/downloads/mysql/5.1.html.
6347
If you install MySQL using a binary tarball distribution on
6348
Solaris, you may run into trouble even before you get the MySQL
6349
distribution unpacked, as the Solaris tar cannot handle long file
6350
names. This means that you may see errors when you try to unpack
6353
If this occurs, you must use GNU tar (gtar) to unpack the
6356
You can install MySQL on Solaris using a binary package in PKG
6357
format instead of the binary tarball distribution. Before
6358
installing using the binary PKG format, you should create the
6359
mysql user and group, for example:
3976
Additional notes to be aware of when installing and using MySQL on
3979
* If you want to use MySQL with the mysql user and group, use
3980
the groupadd and useradd commands:
6361
3982
useradd -g mysql mysql
6363
Some basic PKG-handling commands follow:
6366
pkgadd -d package_name.pkg
6368
* To remove a package:
6371
* To get a full list of installed packages:
6374
* To get detailed information for a package:
6375
pkginfo -l package_name
6377
* To list the files belonging to a package:
6378
pkgchk -v package_name
6380
* To get packaging information for an arbitrary file:
6381
pkgchk -l -p file_name
6383
2.8.1. Solaris Notes
6385
For information about installing MySQL on Solaris using PKG
6386
distributions, see Section 2.8, "Installing MySQL on Solaris."
6388
On Solaris, you may run into trouble even before you get the MySQL
6389
distribution unpacked, as the Solaris tar cannot handle long file
6390
names. This means that you may see errors when you try to unpack
6393
If this occurs, you must use GNU tar (gtar) to unpack the
6396
If you have an UltraSPARC system, you can get 4% better
6397
performance by adding -mcpu=v8 -Wa,-xarch=v8plusa to the CFLAGS
6398
and CXXFLAGS environment variables.
6400
If you have Sun's Forte 5.0 (or newer) compiler, you can run
6401
configure like this:
6402
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
6403
CXX=CC CXXFLAGS="-noex -mt" \
6404
./configure --prefix=/usr/local/mysql --enable-assembler
6406
To create a 64-bit binary with Sun's Forte compiler, use the
6407
following configuration options:
6408
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
6409
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
6410
./configure --prefix=/usr/local/mysql --enable-assembler
6412
To create a 64-bit Solaris binary using gcc, add -m64 to CFLAGS
6413
and CXXFLAGS and remove --enable-assembler from the configure
6416
In the MySQL benchmarks, we obtained a 4% speed increase on
6417
UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to
6418
using gcc 3.2 with the -mcpu flag.
6420
If you create a 64-bit mysqld binary, it is 4% slower than the
6421
32-bit binary, but can handle more threads and memory.
6423
When using Solaris 10 for x86_64, you should mount any file
6424
systems on which you intend to store InnoDB files with the
6425
forcedirectio option. (By default mounting is done without this
6426
option.) Failing to do so will cause a significant drop in
6427
performance when using the InnoDB storage engine on this platform.
6429
If you get a problem with fdatasync or sched_yield, you can fix
6430
this by adding LIBS=-lrt to the configure line
6432
Solaris does not provide static versions of all system libraries
6433
(libpthreads and libdl), so you cannot compile MySQL with
6434
--static. If you try to do so, you get one of the following
6436
ld: fatal: library -ldl: not found
6437
undefined reference to `dlopen'
6440
If you link your own MySQL client programs, you may see the
6441
following error at runtime:
6442
ld.so.1: fatal: libmysqlclient.so.#:
6443
open failed: No such file or directory
6445
This problem can be avoided by one of the following methods:
6447
* Link clients with the -Wl,r/full/path/to/libmysqlclient.so
6448
flag rather than with -Lpath).
6450
* Copy libmysqclient.so to /usr/lib.
6452
* Add the path name of the directory where libmysqlclient.so is
6453
located to the LD_RUN_PATH environment variable before running
6456
If you have problems with configure trying to link with -lz when
6457
you don't have zlib installed, you have two options:
6459
* If you want to be able to use the compressed communication
6460
protocol, you need to get and install zlib from ftp.gnu.org.
6462
* Run configure with the --with-named-z-libs=no option when
6465
If you are using gcc and have problems with loading user-defined
6466
functions (UDFs) into MySQL, try adding -lgcc to the link line for
6469
If you would like MySQL to start automatically, you can copy
6470
support-files/mysql.server to /etc/init.d and create a symbolic
6471
link to it named /etc/rc3.d/S99mysql.server.
6473
If too many processes try to connect very rapidly to mysqld, you
6474
should see this error in the MySQL log:
3984
* If you install MySQL using a binary tarball distribution on
3985
Solaris, you may run into trouble even before you get the
3986
MySQL distribution unpacked, as the Solaris tar cannot handle
3987
long file names. This means that you may see errors when you
3988
try to unpack MySQL.
3989
If this occurs, you must use GNU tar (gtar) to unpack the
3990
distribution. In Solaris 10 and OpenSolaris gtar is normally
3991
located in /usr/sfw/bin/gtar, but may not be included in the
3992
default path definition.
3994
* When using Solaris 10 for x86_64, you should mount any file
3995
systems on which you intend to store InnoDB files with the
3996
forcedirectio option. (By default mounting is done without
3997
this option.) Failing to do so will cause a significant drop
3998
in performance when using the InnoDB storage engine on this
4001
* If you would like MySQL to start automatically, you can copy
4002
support-files/mysql.server to /etc/init.d and create a
4003
symbolic link to it named /etc/rc3.d/S99mysql.server.
4005
* If too many processes try to connect very rapidly to mysqld,
4006
you should see this error in the MySQL log:
6475
4007
Error in accept: Protocol error
6477
You might try starting the server with the --back_log=50 option as
6478
a workaround for this. (Use -O back_log=50 before MySQL 4.)
6480
To configure the generation of core files on Solaris you should
6481
use the coreadm command. Because of the security implications of
6482
generating a core on a setuid() application, by default, Solaris
6483
does not support core files on setuid() programs. However, you can
6484
modify this behavior using coreadm. If you enable setuid() core
6485
files for the current user, they will be generated using the mode
6486
600 and owned by the superuser.
6488
2.9. Installing MySQL on i5/OS
4008
You might try starting the server with the --back_log=50
4009
option as a workaround for this.
4011
* To configure the generation of core files on Solaris you
4012
should use the coreadm command. Because of the security
4013
implications of generating a core on a setuid() application,
4014
by default, Solaris does not support core files on setuid()
4015
programs. However, you can modify this behavior using coreadm.
4016
If you enable setuid() core files for the current user, they
4017
will be generated using the mode 600 and owned by the
4020
2.6.1. Installing MySQL on Solaris using a Solaris PKG
4022
You can install MySQL on Solaris and OpenSolaris using a binary
4023
package using the native Solaris PKG format instead of the binary
4024
tarball distribution.
4026
To use this package, download the corresponding
4027
mysql-VERSION-solaris10-PLATFORM.pkg.gz file, then decompress it.
4029
shell> gunzip mysql-5.1.62-solaris10-x86_64.pkg.gz
4031
To install a new package, use pkgadd and follow the onscreen
4032
prompts. You must have root privileges to perform this operation:
4033
shell> pkgadd -d mysql-5.1.62-solaris10-x86_64.pkg
4035
The following packages are available:
4036
1 mysql MySQL Community Server (GPL)
4039
Select package(s) you wish to process (or 'all' to process
4040
all packages). (default: all) [?,??,q]:
4042
The PKG installer installs all of the files and tools needed, and
4043
then initializes your database if one does not exist. To complete
4044
the installation, you should set the root password for MySQL as
4045
provided in the instructions at the end of the installation.
4046
Alternatively, you can run the mysql_secure_installation script
4047
that comes with the installation.
4049
The default installation directory is /opt/mysql. You can only
4050
change the root path of the installation when using pkgadd, which
4051
can be used to install MySQL in a different Solaris zone. If you
4052
need to install in a specific directory, use the binary tar file.
4054
The pkg installer copies a suitable startup script for MySQL into
4055
/etc/init.d/mysql. To enable MySQL to startup and shutdown
4056
automatically, you should create a link between this file and the
4057
init script directories. For example, to ensure safe startup and
4058
shutdown of MySQL you could use the following commands to add the
4060
shell> ln /etc/init.d/mysql /etc/rc3.d/S91mysql
4061
shell> ln /etc/init.d/mysql /etc/rc0.d/K02mysql
4063
To remove MySQL, the installed package name is mysql. You can use
4064
this in combination with the pkgrm command to remove the
4067
To upgrade when using the Solaris package file format, you must
4068
remove the existing installation before installing the updated
4069
package. Removal of the package does not delete the existing
4070
database information, only the server, binaries and support files.
4071
The typical upgrade sequence is therefore:
4072
shell> mysqladmin shutdown
4074
shell> pkgadd -d mysql-5.1.62-solaris10-x86_64.pkg
4075
shell> mysql_upgrade
4076
shell> mysqld_safe &
4078
You should check the notes in Section 2.13, "Upgrading or
4079
Downgrading MySQL" before performing any upgrade.
4081
2.6.2. Installing MySQL on OpenSolaris using IPS
4083
OpenSolaris includes standard packages for MySQL in the core
4084
repository. The MySQL packages are based on a specific release of
4085
MySQL and updated periodically. For the latest release you must
4086
use either the native Solaris PKG, tar, or source installations.
4087
The native OpenSolaris packages include SMF files so that you can
4088
easily control your MySQL installation, including automatic
4089
startup and recovery, using the native service management tools.
4091
To install MySQL on OpenSolaris, use the pkg command. You will
4092
need to be logged in as root, or use the pfexec tool, as shown in
4094
shell> pfexec pkg install SUNWmysql51
4096
The package set installs three individual packages,
4097
SUNWmysql51lib, which contains the MySQL client libraries;
4098
SUNWmysql51r which contains the root components, including SMF and
4099
configuration files; and SUNWmysql51u which contains the scripts,
4100
binary tools and other files. You can install these packages
4101
individually if you only need the corresponding components.
4103
The MySQL files are installed into /usr/mysql which symbolic links
4104
for the sub directories (bin, lib, etc.) to a version specific
4105
directory. For MySQL 5.1, the full installation is located in
4106
/usr/mysql/5.1. The default data directory is /var/mysql/5.1/data.
4107
The configuration file is installed in /etc/mysql/5.1/my.cnf. This
4108
layout permits multiple versions of MySQL to be installed, without
4109
overwriting the data and binaries from other versions.
4111
Once installed, you must run mysql_install_db to initialize the
4112
database, and use the mysql_secure_installation to secure your
4115
Using SMF to manage your MySQL installation
4117
Once installed, you can start and stop your MySQL server using the
4118
installed SMF configuration. The service name is mysql, or if you
4119
have multiple versions installed, you should use the full version
4120
name, for example mysql:version_51. To start and enable MySQL to
4121
be started at boot time:
4122
shell> svcadm enable mysql
4124
To disable MySQL from starting during boot time, and shut the
4125
MySQL server down if it is running, use:
4126
shell> svcadm disable mysql
4128
To restart MySQL, for example after a configuration file changes,
4129
use the restart option:
4130
shell> svcadm restart mysql
4132
You can also use SMF to configure the data directory and enable
4133
full 64-bit mode. For example, to set the data directory used by
4136
svc:> select mysql:version_51
4137
svc:/application/database/mysql:version_51> setprop mysql/data=/data0
4141
By default, the 32-bit binaries are used. To enable the 64-bit
4142
server on 64-bit platforms, set the enable_64bit parameter. For
4144
svc:/application/database/mysql:version_51> setprop mysql/enable_64bi
4147
You need to refresh the SMF after settings these options:
4148
shell> svcadm refresh mysql
4150
2.7. Installing MySQL on IBM AIX
4152
MySQL for IBM AIX is available in a number of different forms:
4154
* Using a binary tarball distribution provided at
4155
http://dev.mysql.com/downloads/. Please read the general notes
4156
on AIX installation before continuing. For more information on
4157
binary installations, see Section 2.2, "Installing MySQL from
4158
Generic Binaries on Unix/Linux."
4160
* Using a source tarball and compiling MySQL. Please read the
4161
general notes on AIX installation before continuing. You
4162
should also check the instructions on building on AIX from
4163
source. For general information on building from source, see
4164
Section 2.11, "Installing MySQL from Source."
4166
2.7.1. General Notes on Installing MySQL on AIX
4168
General notes on using MySQL on IBM AIX:
4170
* If you have problems with threads on AIX 5.3, you should
4171
upgrade AIX 5.3 to technology level 7 (5300-07).
4173
2.8. Installing MySQL on HP-UX
4175
MySQL for HP-UX is available in a number of different forms:
4177
* Using a DEPOT distribution provided at
4178
http://dev.mysql.com/downloads/. Please read the general notes
4179
on HP-UX installation before continuing. For more information
4180
on DEPOT installations, see Section 2.8.2, "Installing MySQL
4181
on HP-UX using DEPOT."
4183
* Using a binary tarball distribution provided at
4184
http://dev.mysql.com/downloads/. Please read the general notes
4185
on HP-UX installation before continuing. For more information
4186
on binary installations, see Section 2.2, "Installing MySQL
4187
from Generic Binaries on Unix/Linux."
4189
* Using a source tarball and compiling MySQL. Please read the
4190
general notes on HP-UX installation before continuing. You
4191
should also check the instructions on building on HP-UX from
4192
source. For general information on building from source, see
4193
Section 2.11, "Installing MySQL from Source."
4195
2.8.1. General Notes on Installing MySQL on HP-UX
4197
Some additional notes on installing and using MySQL on HP-UX:
4199
* If you install MySQL using a binary tarball distribution on
4200
HP-UX, you may run into trouble even before you get the MySQL
4201
distribution unpacked, as the HP-UX tar cannot handle long
4202
file names. This means that you may see errors when you try to
4204
If this occurs, you must use GNU tar (gtar) to unpack the
4207
* Because of some critical bugs in the standard HP-UX libraries,
4208
you should install the following patches before trying to run
4209
MySQL on HP-UX 11.0:
4210
PHKL_22840 Streams cumulative
4211
PHNE_22397 ARPA cumulative
4212
This solves the problem of getting EWOULDBLOCK from recv() and
4213
EBADF from accept() in threaded applications.
4215
2.8.2. Installing MySQL on HP-UX using DEPOT
4217
The HP-UX DEPOT format packages can be installed using the
4218
swinstall command. You should install the ncurses and zlib
4219
libraries before installing the MySQL DEPOT package. You can use
4220
the free software depothelper tool to install these packages and
4221
any dependencies for you automatically.
4223
To install using the MySQL DEPOT packages, follow this guide:
4225
1. Download the MySQL DEPOT package from
4226
http://dev.mysql.com/downloads/. You must decompress the
4227
package before installation:
4228
root-shell> gunzip mysql-5.1.48-hpux11.31-ia64-64bit.depot.gz
4230
2. Install the DEPOT package using swinstall:
4231
root-shell> swinstall -s mysql-5.1.49-hpux11.31-ia64-64bit.depot
4232
MySQL will be installed into a directory matching the depot
4233
package name, within /usr/local. For convenience, you may want
4234
to create a symbolic link to the installed directory, for
4236
root-shell> ln -s mysql-5.1.49-hpux11.31-ia64-64bit mysql
4238
3. Your package is now installed. You should complete the
4239
configuration of MySQL by creating a user and group:
4240
root-shell> /usr/sbin/groupadd mysql
4241
root-shell> /usr/sbin/useradd -g mysql -d /var/lib/mysql/ -s /bin/fal
4244
4. Create the standard database using the new user/group you have
4245
created, and set the permissions:
4246
root-shell> cd /usr/local/
4247
root-shell> scripts/mysql_install_db --user=mysql
4248
root-shell> chown -R root .
4249
root-shell> chown -R mysql data
4251
5. Finally, secure your new installation by setting the root
4252
passwords, and then start your MySQL server using the mysql
4254
root-shell> mysql_secure_installation
4255
root-shell> mysqld_safe --user=mysql &
4257
2.9. Installing MySQL on FreeBSD
4259
This section provides information about installing MySQL on
4260
variants of FreeBSD Unix.
4262
You can install MySQL on FreeBSD by using the binary distribution
4263
provided by Oracle. For more information, see Section 2.2,
4264
"Installing MySQL from Generic Binaries on Unix/Linux."
4266
The easiest (and preferred) way to install MySQL is to use the
4267
mysql-server and mysql-client ports available at
4268
http://www.freebsd.org/. Using these ports gives you the following
4271
* A working MySQL with all optimizations enabled that are known
4272
to work on your version of FreeBSD.
4274
* Automatic configuration and build.
4276
* Startup scripts installed in /usr/local/etc/rc.d.
4278
* The ability to use pkg_info -L to see which files are
4281
* The ability to use pkg_delete to remove MySQL if you no longer
4282
want it on your machine.
4284
The MySQL build process requires GNU make (gmake) to work. If GNU
4285
make is not available, you must install it first before compiling
4288
To install using the ports system:
4289
# cd /usr/ports/databases/mysql51-server
4292
# cd /usr/ports/databases/mysql51-client
4296
The standard port installation places the server into
4297
/usr/local/libexec/mysqld, with the startup script for the MySQL
4298
server placed in /usr/local/etc/rc.d/mysql-server.
4300
Some additional notes on the BSD implementation:
4302
* To remove MySQL after installation using the ports system:
4303
# cd /usr/ports/databases/mysql51-server
4306
# cd /usr/ports/databases/mysql51-client
4310
* If you get problems with the current date in MySQL, setting
4311
the TZ variable should help. See Section 2.14, "Environment
4314
2.10. Installing MySQL on i5/OS
6490
4316
The i5/OS POWER MySQL package was created in cooperation with IBM.
6491
4317
MySQL works within the Portable Application Solution Environment
6743
4573
(5799-PTL). See
6744
4574
http://www-03.ibm.com/servers/enable/site/porting/tools/.
6746
2.10. Installing MySQL on FreeBSD
6748
This section provides information about using MySQL on variants of
6751
The easiest (and preferred) way to install MySQL is to use the
6752
mysql-server and mysql-client ports available at
6753
http://www.freebsd.org/. Using these ports gives you the following
6756
* A working MySQL with all optimizations enabled that are known
6757
to work on your version of FreeBSD.
6759
* Automatic configuration and build.
6761
* Startup scripts installed in /usr/local/etc/rc.d.
6763
* The ability to use pkg_info -L to see which files are
6766
* The ability to use pkg_delete to remove MySQL if you no longer
6767
want it on your machine.
6769
The MySQL build process requires GNU make (gmake) to work. If GNU
6770
make is not available, you must install it first before compiling
6773
The recommended way to compile and install MySQL on FreeBSD with
6774
gcc (2.95.2 and up) is:
6775
CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
6776
CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
6777
-felide-constructors -fno-strength-reduce" \
6778
./configure --prefix=/usr/local/mysql --enable-assembler
6782
bin/mysql_install_db --user=mysql
6785
FreeBSD is known to have a very low default file handle limit. See
6786
Section B.5.2.18, "'File' Not Found and Similar Errors." Start the
6787
server by using the --open-files-limit option for mysqld_safe, or
6788
raise the limits for the mysqld user in /etc/login.conf and
6789
rebuild it with cap_mkdb /etc/login.conf. Also be sure that you
6790
set the appropriate class for this user in the password file if
6791
you are not using the default (use chpass mysqld-user-name). See
6792
Section 4.3.2, "mysqld_safe --- MySQL Server Startup Script."
6794
In current versions of FreeBSD (at least 4.x and greater), you may
6795
increase the limit on the amount of memory available for a process
6796
by adding the following entries to the /boot/loader.conf file and
6797
rebooting the machine (these are not settings that can be changed
6798
at run time with the sysctl command):
6799
kern.maxdsiz="1073741824" # 1GB
6800
kern.dfldsiz="1073741824" # 1GB
6801
kern.maxssiz="134217728" # 128MB
6803
For older versions of FreeBSD, you must recompile your kernel to
6804
change the maximum data segment size for a process. In this case,
6805
you should look at the MAXDSIZ option in the LINT config file for
6808
If you get problems with the current date in MySQL, setting the TZ
6809
variable should help. See Section 2.14, "Environment Variables."
6811
2.11. Installing MySQL on HP-UX
6813
If you install MySQL using a binary tarball distribution on HP-UX,
6814
you may run into trouble even before you get the MySQL
6815
distribution unpacked, as the HP-UX tar cannot handle long file
6816
names. This means that you may see errors when you try to unpack
6819
If this occurs, you must use GNU tar (gtar) to unpack the
6822
Because of some critical bugs in the standard HP-UX libraries, you
6823
should install the following patches before trying to run MySQL on
6825
PHKL_22840 Streams cumulative
6826
PHNE_22397 ARPA cumulative
6828
This solves the problem of getting EWOULDBLOCK from recv() and
6829
EBADF from accept() in threaded applications.
6831
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system, you
6832
may get the following error:
6833
In file included from /usr/include/unistd.h:11,
6834
from ../include/global.h:125,
6835
from mysql_priv.h:15,
6837
/usr/include/sys/unistd.h:184: declaration of C function ...
6838
/usr/include/sys/pthread.h:440: previous declaration ...
6839
In file included from item.h:306,
6840
from mysql_priv.h:158,
6843
The problem is that HP-UX does not define pthreads_atfork()
6844
consistently. It has conflicting prototypes in
6845
/usr/include/sys/unistd.h:184 and /usr/include/sys/pthread.h:440.
6847
One solution is to copy /usr/include/sys/unistd.h into
6848
mysql/include and edit unistd.h and change it to match the
6849
definition in pthread.h. Look for this line:
6850
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
6853
Change it to look like this:
6854
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void)
6856
void (*child)(void));
6858
After making the change, the following configure line should work:
6859
CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
6860
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
6861
./configure --prefix=/usr/local/mysql --disable-shared
6863
If you are using HP-UX compiler, you can use the following command
6864
(which has been tested with cc B.11.11.04):
6865
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
6866
--with-extra-character-set=complex
6868
You can ignore any errors of the following type:
6869
aCC: warning 901: unknown option: `-3': use +help for online
6872
If you get the following error from configure, verify that you
6873
don't have the path to the K&R compiler before the path to the
6874
HP-UX C and C++ compiler:
6875
checking for cc option to accept ANSI C... no
6876
configure: error: MySQL requires an ANSI C compiler (and a C++ compil
6878
Try gcc. See the Installation chapter in the Reference Manual.
6880
Another reason for not being able to compile is that you didn't
6881
define the +DD64 flags as just described.
6883
Another possibility for HP-UX 11 is to use the MySQL binaries
6884
provided at http://dev.mysql.com/downloads/, which we have built
6885
and tested ourselves. We have also received reports that the HP-UX
6886
10.20 binaries supplied by MySQL can be run successfully on HP-UX
6887
11. If you encounter problems, you should be sure to check your
6890
2.12. Installing MySQL on AIX
6892
Automatic detection of xlC is missing from Autoconf, so a number
6893
of variables need to be set before running configure. The
6894
following example uses the IBM compiler:
4576
2.11. Installing MySQL from Source
4578
Building MySQL from the source code enables you to customize build
4579
parameters, compiler optimizations, and installation location. For
4580
a list of systems on which MySQL is known to run, see Section
4581
2.1.1, "Operating Systems Supported by MySQL Community Server."
4583
Before you proceed with an installation from source, check whether
4584
we produce a precompiled binary distribution for your platform and
4585
whether it works for you. We put a great deal of effort into
4586
ensuring that our binaries are built with the best possible
4587
options for optimal performance. Instructions for installing
4588
binary distributions are available in Section 2.2, "Installing
4589
MySQL from Generic Binaries on Unix/Linux."
4591
To obtain a source distribution for MySQL, see Section 2.1.3, "How
4592
to Get MySQL." MySQL source distributions are available as
4593
compressed tar files, Zip archives, or RPM packages. Distribution
4594
files have names of the form mysql-VERSION.tar.gz,
4595
mysql-VERSION.zip, or mysql-VERSION.rpm, where VERSION is a number
4598
To perform a MySQL installation using the source code:
4600
* To build MySQL from source on Unix-like systems, including
4601
Linux, commercial Unix, BSD, Mac OS X and others using a
4602
.tar.gz or RPM-based source code distribution, see Section
4603
2.11.2, "Installing MySQL from a Standard Source
4606
* To build MySQL from source on Windows (Windows XP or newer
4607
required), see Section 2.11.7, "Installing MySQL from Source
4610
* For information on building from one of our development trees,
4611
see Section 2.11.3, "Installing MySQL from a Development
4614
* For information on using the configure command to specify the
4615
source build parameters, including links to platform specific
4616
parameters that you might need, see Section 2.11.4, "MySQL
4617
Source-Configuration Options."
4619
To install MySQL from source, your system must have the following
4622
* GNU gunzip to uncompress the distribution and a reasonable tar
4623
to unpack it (if you use a .tar.gz distribution), or WinZip or
4624
another tool that can read .zip files (if you use a .zip
4626
GNU tar is known to work. The standard tar provided with some
4627
operating systems is not able to unpack the long file names in
4628
the MySQL distribution. You should download and install GNU
4629
tar, or if available, use a preinstalled version of GNU tar.
4630
Usually this is available as gnutar, gtar, or as tar within a
4631
GNU or Free Software directory, such as /usr/sfw/bin or
4632
/usr/local/bin. GNU tar is available from
4633
http://www.gnu.org/software/tar/.
4635
* A working ANSI C++ compiler. GCC 3.4.6 or later, Sun Studio 10
4636
or later, Visual Studio 2005 or later, and many current
4637
vendor-supplied compilers are known to work.
4639
* A good make program. Although some platforms come with their
4640
own make implementations, it is highly recommended that you
4641
use GNU make 3.75 or newer. It may already be available on
4642
your system as gmake. GNU make is available from
4643
http://www.gnu.org/software/make/.
4645
* libtool 1.5, available from
4646
http://www.gnu.org/software/libtool/. 1.5.24 or later is
4649
If you run into problems and need to file a bug report, please use
4650
the instructions in Section 1.7, "How to Report Bugs or Problems."
4652
2.11.1. MySQL Layout for Source Installation
4654
By default, when you install MySQL after compiling it from a
4655
source distribution, the installation step installs files under
4656
/usr/local. Components are installed in the directories shown in
4657
the following table. To configure particular installation
4658
locations, use the options described at Section 2.11.4, "MySQL
4659
Source-Configuration Options."
4661
Table 2.18. MySQL Layout for Installation from Source
4662
Directory Contents of Directory
4663
bin Client programs and scripts
4664
include/mysql Include (header) files
4665
Docs Manual in Info format
4666
man Unix manual pages
4668
libexec The mysqld server
4669
share/mysql Miscellaneous support files, including error messages,
4670
sample configuration files, SQL for database installation
4671
sql-bench Benchmarks
4672
var Log files, databases
4674
Within its installation directory, the layout of a source
4675
installation differs from that of a binary installation in the
4678
* The mysqld server is installed in the libexec directory rather
4679
than in the bin directory.
4681
* The data directory is var rather than data.
4683
* mysql_install_db is installed in the bin directory rather than
4684
in the scripts directory.
4686
* The header file and library directories are include/mysql and
4687
lib/mysql rather than include and lib.
4689
2.11.2. Installing MySQL from a Standard Source Distribution
4691
To install MySQL from source, first configure, build, and install
4692
from a source package. Then follow the same postinstallation setup
4693
sequence as for a binary installation.
4695
If you start from a source RPM, use the following command to make
4696
a binary RPM that you can install. If you do not have rpmbuild,
4698
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm
4700
The result is one or more binary RPM packages that you install as
4701
indicated in Section 2.5.1, "Installing MySQL from RPM Packages on
4704
The sequence for installation from a compressed tar file source
4705
distribution is similar to the process for installing from a
4706
generic binary distribution that is detailed in Section 2.2,
4707
"Installing MySQL from Generic Binaries on Unix/Linux." For a
4708
MySQL .tar.gz source distribution, the basic installation command
4709
sequence looks like this:
4710
# Preconfiguration setup
4711
shell> groupadd mysql
4712
shell> useradd -g mysql mysql
4713
# Beginning of source-build specific instructions
4714
shell> tar zxvf mysql-VERSION.tar.gz
4715
shell> cd mysql-VERSION
4716
shell> ./configure --prefix=/usr/local/mysql
4719
# End of source-build specific instructions
4720
# Postinstallation setup
4721
shell> cd /usr/local/mysql
4722
shell> chown -R mysql .
4723
shell> chgrp -R mysql .
4724
shell> bin/mysql_install_db --user=mysql
4725
shell> chown -R root .
4726
shell> chown -R mysql var
4727
# Next command is optional
4728
shell> cp support-files/my-medium.cnf /etc/my.cnf
4729
shell> bin/mysqld_safe --user=mysql &
4730
# Next command is optional
4731
shell> cp support-files/mysql.server /etc/init.d/mysql.server
4733
A more detailed version of the source-build specific instructions
4734
is shown following. Perform the following steps as the mysql user,
4738
The procedure shown here does not set up any passwords for MySQL
4739
accounts. After following the procedure, proceed to Section 2.12,
4740
"Postinstallation Setup and Testing," for postinstallation setup
4743
1. Set up the mysql user and group that will be used to run and
4744
execute the MySQL server and own the database directory. For
4745
details, see Creating a mysql System User and Group, in
4746
Section 2.2, "Installing MySQL from Generic Binaries on
4749
2. Pick the directory under which you want to unpack the
4750
distribution and change location into it.
4752
3. Obtain a distribution file using the instructions in Section
4753
2.1.3, "How to Get MySQL."
4755
4. Unpack the distribution into the current directory. tar can
4756
uncompress and unpack the distribution if it has z option
4758
shell> tar zxvf /path/to/mysql-VERSION.tar.gz
4759
This command creates a directory named mysql-VERSION.
4760
If your tar does not have z option support, use gunzip to
4761
unpack the distribution and tar to unpack it:
4762
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -
4764
5. Change location into the top-level directory of the unpacked
4766
shell> cd mysql-VERSION
4768
6. Configure the source directory:
4769
shell> ./configure --prefix=/usr/local/mysql
4770
When you run configure, you might want to specify other
4771
options. For example, if you need to debug mysqld or a MySQL
4772
client, run configure with the --with-debug option, and then
4773
recompile and link your clients with the new client library.
4774
See MySQL Internals: Porting
4775
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
4776
Run ./configure --help for a list of options. Section 2.11.4,
4777
"MySQL Source-Configuration Options," discusses some of the
4778
more useful options.
4779
If configure fails and you are going to send mail to a MySQL
4780
mailing list to ask for assistance, please include any lines
4781
from config.log that you think can help solve the problem.
4782
Also include the last couple of lines of output from
4783
configure. To file a bug report, please use the instructions
4784
in Section 1.7, "How to Report Bugs or Problems."
4786
7. Compile the source distribution:
4788
Use gmake instead on systems where you are using GNU make and
4789
it has been installed as gmake.
4790
If the compile fails, see Section 2.11.5, "Dealing with
4791
Problems Compiling MySQL," for help.
4793
8. Install the distribution:
4795
You might need to run this command as root.
4797
The remainder of the installation process, including setting up
4798
the configuration file, creating the core databases, and starting
4799
the MySQL server, are identical to the remainder of the process as
4800
shown in Generic Binary Install.
4802
After everything has been installed, test the distribution. To
4803
start the MySQL server, use the following command:
4804
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
4806
If you run the command as root, you should use the --user option
4807
as shown. The option value is the name of the login account that
4808
you created in the first step to use for running the server. If
4809
you run the mysqld_safe command while logged in as that user, you
4810
can omit the --user option.
4812
If the command fails immediately and prints mysqld ended, look for
4813
information in the error log (which by default is the
4814
host_name.err file in the data directory).
4816
For more information about mysqld_safe, see Section 4.3.2,
4817
"mysqld_safe --- MySQL Server Startup Script."
4819
To make it more convenient to invoke programs installed in
4820
/usr/local/mysql/bin, you can add that directory to your PATH
4821
environment variable setting. That enables you to run a program by
4822
typing only its name, not its entire path name. See Section 4.2.4,
4823
"Setting Environment Variables."
4826
The accounts that are listed in the MySQL grant tables initially
4827
have no passwords. After starting the server, you should set up
4828
passwords for them using the instructions in Section 2.12,
4829
"Postinstallation Setup and Testing."
4831
2.11.3. Installing MySQL from a Development Source Tree
4833
This section discusses how to install MySQL from the latest
4834
development source code. Development trees have not necessarily
4835
received the same level of testing as standard release
4836
distributions, so this installation method is usually required
4837
only if you need the most recent code changes. Do not use a
4838
development tree for production systems. If your goal is simply to
4839
get MySQL up and running on your system, you should use a standard
4840
release distribution (either a binary or source distribution). See
4841
Section 2.1.3, "How to Get MySQL."
4843
To obtain the source tree, you must have Bazaar installed. The
4844
Bazaar VCS Web site (http://bazaar-vcs.org) has instructions for
4845
downloading and installing Bazaar on different platforms. Bazaar
4846
is supported on any platform that supports Python, and is
4847
therefore compatible with any Linux, Unix, Windows, or Mac OS X
4850
MySQL development projects are hosted on Launchpad
4851
(http://launchpad.net/). MySQL projects, including MySQL Server,
4852
MySQL Workbench, and others are available from the Oracle/MySQL
4853
Engineering (http://launchpad.net/~mysql) page. For the
4854
repositories related only to MySQL Server, see the MySQL Server
4855
(http://launchpad.net/mysql-server) page.
4857
For information about using Bazaar with MySQL, see
4858
http://forge.mysql.com/wiki/MySQL_Bazaar_Howto.
4860
To build under Unix/Linux, you must have the following tools
4863
* A good make program. Although some platforms come with their
4864
own make implementations, it is highly recommended that you
4865
use GNU make 3.75 or newer. It may already be available on
4866
your system as gmake. GNU make is available from
4867
http://www.gnu.org/software/make/.
4869
* autoconf 2.58 (or newer), available from
4870
http://www.gnu.org/software/autoconf/.
4872
* automake 1.8.1, available from
4873
http://www.gnu.org/software/automake/.
4875
* libtool 1.5, available from
4876
http://www.gnu.org/software/libtool/. 1.5.24 or later is
4879
* m4, available from http://www.gnu.org/software/m4/.
4881
* bison, available from http://www.gnu.org/software/bison/. You
4882
should use the latest version of bison where possible.
4883
Versions 1.75 and 2.1 are known to work. There have been
4884
reported problems with bison 1.875. If you experience
4885
problems, upgrade to a later, rather than earlier, version.
4887
To build under Windows you must have Microsoft Visual C++ 2005
4888
Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio
4889
2005 (8.0) compiler system.
4891
Once the necessary tools are installed, create a local branch of
4892
the MySQL development tree on your machine using this procedure:
4894
1. To obtain a copy of the MySQL source code, you must create a
4895
new Bazaar branch. If you do not already have a Bazaar
4896
repository directory set up, you must initialize a new
4898
shell> mkdir mysql-server
4899
shell> bzr init-repo --trees mysql-server
4900
This is a one-time operation.
4902
2. Assuming that you have an initialized repository directory,
4903
you can branch from the public MySQL server repositories to
4904
create a local source tree. To create a branch of a specific
4906
shell> cd mysql-server
4907
shell> bzr branch lp:mysql-server/5.1 mysql-5.1
4908
This is a one-time operation per source tree. You can branch
4909
the source trees for several versions of MySQL under the
4910
mysql-server directory.
4912
3. The initial download will take some time to complete,
4913
depending on the speed of your connection. Please be patient.
4914
Once you have downloaded the first tree, additional trees
4915
should take significantly less time to download.
4917
4. When building from the Bazaar branch, you may want to create a
4918
copy of your active branch so that you can make configuration
4919
and other changes without affecting the original branch
4920
contents. You can achieve this by branching from the original
4922
shell> bzr branch mysql-5.1 mysql-5.1-build
4924
5. To obtain changes made after you have set up the branch
4925
initially, update it using the pull option periodically. Use
4926
this command in the top-level directory of the local copy:
4928
To examine the changeset comments for the tree, use the log
4931
You can also browse changesets, comments, and source code
4932
online at the Launchpad MySQL Server
4933
(http://launchpad.net/mysql-server) page.
4934
If you see diffs (changes) or code that you have a question
4935
about, do not hesitate to send email to the MySQL internals
4936
mailing list. See Section 1.6.1, "MySQL Mailing Lists." If you
4937
think you have a better idea on how to do something, send an
4938
email message to the list with a patch.
4940
After you have the local branch, you can build MySQL server from
4941
the source code. On Windows, the build process is different from
4942
Unix/Linux: see Section 2.11.7, "Installing MySQL from Source on
4945
On Unix/Linux, use the autoconf system to create the configure
4946
script so that you can configure the build environment before
4947
building. The following example shows the typical commands
4948
required to build MySQL from a source tree.
4950
1. Change location to the top-level directory of the source tree;
4951
replace mysql-5.1 with the appropriate directory name.
4954
2. Prepare the source tree for configuration.
4955
Prior to MySQL 5.1.12, you must separately configure the
4956
InnoDB storage engine. Run the following command from the main
4958
shell> (cd storage/innobase; autoreconf --force --install)
4959
You can omit the previous command for MySQL 5.1.12 and later,
4960
or if you do not require InnoDB support.
4961
Prepare the remainder of the source tree:
4962
shell> autoreconf --force --install
4963
As an alternative to the preceding autoreconf command, you can
4964
use BUILD/autorun.sh, which acts as a shortcut for the
4965
following sequence of commands:
4966
shell> aclocal; autoheader
4967
shell> libtoolize --automake --force
4968
shell> automake --force --add-missing; autoconf
4969
If you get some strange errors during this stage, verify that
4970
you have the correct version of libtool installed.
4972
3. Configure the source tree and compile MySQL:
4973
shell> ./configure # Add your favorite options here
4975
For a description of some configure options, see Section
4976
2.11.4, "MySQL Source-Configuration Options."
4977
A collection of configuration scripts is located in the BUILD/
4978
subdirectory. For example, you may find it more convenient to
4979
use the BUILD/compile-pentium-debug script than the preceding
4980
set of shell commands. To compile on a different architecture,
4981
modify the script by removing flags that are Pentium-specific,
4982
or use another script that may be more appropriate. These
4983
scripts are provided on an "as-is" basis. They are not
4984
supported and their contents may change from release to
4987
4. When the build is done, run make install. Be careful with this
4988
on a production machine; the installation command may
4989
overwrite your live release installation. If you already have
4990
MySQL installed and do not want to overwrite it, run
4991
./configure with values for the --prefix, --with-tcp-port, and
4992
--with-unix-socket-path options different from those used by
4993
your production server. For additional information about
4994
preventing multiple servers from interfering with each other,
4995
see Section 5.6, "Running Multiple MySQL Instances on One
4998
5. Play hard with your new installation. For example, try to make
4999
new features crash. Start by running make test. See Section
5000
21.1.2, "The MySQL Test Suite."
5002
6. If you have gotten to the make stage, but the distribution
5003
does not compile, please enter the problem into our bugs
5004
database using the instructions given in Section 1.7, "How to
5005
Report Bugs or Problems." If you have installed the latest
5006
versions of the required tools, and they crash trying to
5007
process our configuration files, please report that also.
5008
However, if you get a command not found error or a similar
5009
problem for required tools, do not report it. Instead, make
5010
sure that all the required tools are installed and that your
5011
PATH variable is set correctly so that your shell can find
5014
2.11.4. MySQL Source-Configuration Options
5016
The configure script provides a great deal of control over how you
5017
configure a MySQL source distribution. Typically, you do this
5018
using options on the configure command line. For a full list of
5019
options supported by configure, run this command:
5020
shell> ./configure --help
5022
You can also affect configure using certain environment variables.
5023
See Section 2.14, "Environment Variables."
5025
The following table shows the available configure options.
5027
Table 2.19. MySQL Source-Configuration Option Reference
5029
Formats Description Default Introduced Removed
5030
--bindir=DIR User executables EPREFIX/bin
5031
--build=BUILD Configure for building on BUILD guessed
5032
--cache-file=FILE Cache test results in FILE disabled
5033
-C Alias for `--cache-file=config.cache'
5035
--datadir=DIR Read-only architecture-independent data PREFIX/share
5037
--disable-FEATURE Do not include FEATURE
5038
--disable-community-features Disable additional features provided
5039
by the community 5.1.28
5040
--disable-dependency-tracking Disable dependency tracking
5041
--disable-grant-options Disable GRANT options
5042
--disable-largefile Omit support for large files
5043
--disable-libtool-lock Disable libtool lock
5044
--disable-thread-safe-client Compile the client without threads
5046
--enable-FEATURE Enable FEATURE
5047
--enable-assembler Use assembler versions of some string functions
5049
--enable-debug-sync Compile in Debug Sync facility 5.1.41
5050
--enable-dependency-tracking Do not reject slow dependency
5052
--enable-fast-install Optimize for fast installation yes
5053
--enable-local-infile Enable LOCAL for LOAD DATA INFILE disabled
5055
--enable-profiling Build a version with query profiling code
5057
--enable-shared Build shared libraries yes
5058
--enable-static Build static libraries yes
5059
--enable-thread-safe-client Compile the client with threads
5061
--exec-prefix=EPREFIX Install architecture-dependent files in
5063
-h Display this help and exit
5065
--help=short Display options specific to this package
5066
--help=recursive Display the short help of all the included
5068
--host=HOST Cross-compile to build programs to run on HOST
5069
--includedir=DIR C header files PREFIX/include
5070
--infodir=DIR Info documentation PREFIX/info
5071
--libdir=DIR Object code libraries EPREFIX/lib
5072
--libexecdir=DIR Program executables EPREFIX/libexec
5073
--localstatedir=DIR Modifiable single-machine data PREFIX/var
5074
--mandir=DIR man documentation PREFIX/man
5075
-n Do not create output files
5077
--oldincludedir=DIR C header files for non-gcc /usr/include
5078
--prefix=PREFIX Install architecture-independent files in PREFIX
5080
--program-prefix=PREFIX Prepend PREFIX to installed program names
5082
--program-suffix=SUFFIX Append SUFFIX to installed program names
5084
--program-transform-name=PROGRAM run sed PROGRAM on installed
5086
-q Do not print `checking...' messages
5088
--sbindir=DIR System administrative executables EPREFIX/sbin
5089
--sharedstatedir=DIR Modifiable architecture-independent data
5091
--srcdir=DIR Find the sources in DIR configure directory or ..
5092
--sysconfdir=DIR Read-only single-machine data PREFIX/etc
5093
--target=TARGET Configure for building compilers for TARGET
5094
-V Display version information and exit
5096
--with-PACKAGE Use PACKAGE
5097
--with-archive-storage-engine Enable the Archive Storage Engine no
5099
--with-atomic-ops Implement atomic operations using pthread
5100
rwlocks or atomic CPU instructions for multi-processor 5.1.12
5101
--with-berkeley-db Use BerkeleyDB located in DIR no 5.1.11
5102
--with-berkeley-db-includes Find Berkeley DB headers in DIR
5104
--with-berkeley-db-libs Find Berkeley DB libraries in DIR 5.1.11
5105
--with-big-tables Support tables with more than 4 G rows even on
5107
--with-blackhole-storage-engine Enable the Blackhole Storage
5109
--with-charset Default character set
5110
--with-client-ldflags Extra linking arguments for clients
5111
--with-collation Default collation
5112
--with-comment Comment about compilation environment
5113
--with-csv-storage-engine Enable the CSV Storage Engine yes
5115
--with-darwin-mwcc Use Metrowerks CodeWarrior wrappers on OS
5117
--with-debug Add debug code 5.1.7
5118
--with-debug=full Add debug code (adds memory checker, very slow)
5120
--with-embedded-privilege-control Build parts to check user's
5121
privileges (only affects embedded library)
5122
--with-embedded-server Build the embedded server
5123
--with-error-inject Enable error injection in MySQL Server 5.1.11
5125
--with-example-storage-engine Enable the Example Storage Engine no
5127
--with-extra-charsets Use charsets in addition to default
5128
--with-fast-mutexes Compile with fast mutexes enabled 5.1.5
5129
--with-federated-storage-engine Enable federated storage engine no
5131
--with-gnu-ld Assume the C compiler uses GNU ld no
5132
--with-innodb Enable innobase storage engine no 5.1.3 5.1.9
5133
--with-lib-ccflags Extra CC options for libraries
5134
--with-libwrap=DIR Compile in libwrap (tcp_wrappers) support
5135
--with-low-memory Try to use less memory to compile to avoid
5137
--with-machine-type Set the machine type, like "powerpc"
5138
--with-max-indexes=N Sets the maximum number of indexes per table
5140
--with-mysqld-ldflags Extra linking arguments for mysqld
5141
--with-mysqld-libs Extra libraries to link with for mysqld
5142
--with-mysqld-user What user the mysqld daemon shall be run as
5143
--with-mysqlmanager Build the mysqlmanager binary Build if server
5145
--with-named-curses-libs Use specified curses libraries
5146
--with-named-thread-libs Use specified thread libraries
5147
--with-ndb-ccflags Extra CC options for ndb compile
5148
--with-ndb-docs Include the NDB Cluster ndbapi and mgmapi
5150
--with-ndb-port Port for NDB Cluster management server
5151
--with-ndb-port-base Port for NDB Cluster management server
5152
--with-ndb-sci=DIR Provide MySQL with a custom location of sci
5154
--with-ndb-test Include the NDB Cluster ndbapi test programs
5155
--with-ndbcluster Include the NDB Cluster table handler no 5.1.9
5156
--with-openssl=DIR Include the OpenSSL support 5.1.9
5157
--with-openssl-includes Find OpenSSL headers in DIR 5.1.9
5158
--with-openssl-libs Find OpenSSL libraries in DIR 5.1.9
5159
--with-other-libc=DIR Link against libc and other standard
5160
libraries installed in the specified nonstandard location
5161
--with-pic Try to use only PIC/non-PIC objects Use both
5162
--with-plugin-PLUGIN Forces the named plugin to be linked into
5163
mysqld statically 5.1.11
5164
--with-plugins Plugins to include in mysqld none 5.1.11
5165
--with-pstack Use the pstack backtrace library 5.1.54
5166
--with-pthread Force use of pthread library
5167
--with-row-based-replication Include row-based replication 5.1.5
5169
--with-server-suffix Append value to the version string
5170
--with-ssl=DIR Include SSL support 5.1.11
5171
--with-system-type Set the system type, like "sun-solaris10"
5172
--with-tags Include additional configurations automatic
5173
--with-tcp-port Which port to use for MySQL services 3306
5174
--with-unix-socket-path Where to put the unix-domain socket
5175
--with-yassl Include the yaSSL support 5.1.9
5176
--with-zlib-dir=no|bundled|DIR Provide MySQL with a custom
5177
location of compression library
5178
--without-PACKAGE Do not use PACKAGE
5179
--without-bench Skip building of the benchmark suite 5.1.11
5180
--without-debug Build a production version without debugging code
5182
--without-docs Skip building of the documentation
5183
--without-extra-tools Skip building utilities in the tools
5185
--without-geometry Do not build geometry-related parts
5186
--without-libedit Use system libedit instead of bundled copy
5187
--without-man Skip building of the man pages
5188
--without-ndb-binlog Disable ndb binlog 5.1.6
5189
--without-ndb-debug Disable special ndb debug features
5190
--without-plugin-PLUGIN Exclude PLUGIN 5.1.11
5191
--without-query-cache Do not build query cache
5192
--without-readline Use system readline instead of bundled copy
5193
--without-row-based-replication Don't include row-based
5194
replication 5.1.7 5.1.14
5195
--without-server Only build the client
5196
--without-uca Skip building of the national Unicode collations
5198
If you are using a version of gcc recent enough to understand the
5199
-fno-exceptions option, it is very important that you use this
5200
option. Otherwise, you may compile a binary that crashes randomly.
5201
Also use -felide-constructors and -fno-rtti along with
5202
-fno-exceptions. When in doubt, do the following:
5203
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
5204
-fno-exceptions -fno-rtti" ./configure \
5205
--prefix=/usr/local/mysql --enable-assembler \
5206
--with-mysqld-ldflags=-all-static
5208
On most systems, this gives you a fast and stable binary.
5210
When compiling from source, you should also be aware of any
5211
platform specific considerations that may influence and impact the
5212
build process. Knowing and applying this information will help to
5213
ensure you get the best performance and most stable binary for
5214
your chosen platform. For more information, use the following
5217
* Section 2.11.9, "Notes on Installing MySQL on AIX from Source"
5219
* Section 2.11.10, "Notes on Installing MySQL on HP-UX from
5222
* Section 2.11.8, "Notes on Installing MySQL on Solaris from
5225
Some of the configure options available are described here. For
5226
options that may be of use if you have difficulties building
5227
MySQL, see Section 2.11.5, "Dealing with Problems Compiling
5230
Many options configure compile-time defaults that can be
5231
overridden at server startup. For example, the --prefix,
5232
--with-tcp-port, and with-unix-socket-path options that configure
5233
the default installation base directory location, TCP/IP port
5234
number, and Unix socket file can be changed at server startup with
5235
the --basedir, --port, and --socket options for mysqld.
5237
* To compile just the MySQL client libraries and client programs
5238
and not the server, use the --without-server option:
5239
shell> ./configure --without-server
5240
If you have no C++ compiler, some client programs such as
5241
mysql cannot be compiled because they require C++. In this
5242
case, you can remove the code in configure that tests for the
5243
C++ compiler and then run ./configure with the
5244
--without-server option. The compile step should still try to
5245
build all clients, but you can ignore any warnings about files
5246
such as mysql.cc. (If make stops, try make -k to tell it to
5247
continue with the rest of the build even if errors occur.)
5249
* To build the embedded MySQL library (libmysqld.a), use the
5250
--with-embedded-server option.
5252
* To place your log files and database directories elsewhere
5253
than under /usr/local/var, use a configure command something
5255
shell> ./configure --prefix=/usr/local/mysql
5256
shell> ./configure --prefix=/usr/local \
5257
--localstatedir=/usr/local/mysql/data
5258
The first command changes the installation prefix so that
5259
everything is installed under /usr/local/mysql rather than the
5260
default of /usr/local. The second command preserves the
5261
default installation prefix, but overrides the default
5262
location for database directories (normally /usr/local/var)
5263
and changes it to /usr/local/mysql/data.
5264
You can also specify the installation directory and data
5265
directory locations at server startup time by using the
5266
--basedir and --datadir options. These can be given on the
5267
command line or in an MySQL option file, although it is more
5268
common to use an option file. See Section 4.2.3.3, "Using
5271
* The --with-tcp-port option specifies the port number on which
5272
the server listens for TCP/IP connections. The default is port
5273
3306. To listen on a different port, use a configure command
5275
shell> ./configure --with-tcp-port=3307
5277
* On Unix, if you want the MySQL socket file location to be
5278
somewhere other than the default location (normally in the
5279
directory /tmp or /var/run), use a configure command like
5281
shell> ./configure \
5282
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
5283
The socket file name must be an absolute path name. You can
5284
also change the location of mysql.sock at server startup by
5285
using a MySQL option file. See Section C.5.4.5, "How to
5286
Protect or Change the MySQL Unix Socket File."
5288
* To compile statically linked programs (for example, to make a
5289
binary distribution, to get better performance, or to work
5290
around problems with some Red Hat Linux distributions), run
5291
configure like this:
5292
shell> ./configure --with-client-ldflags=-all-static \
5293
--with-mysqld-ldflags=-all-static
5295
* If you are using gcc and do not have libg++ or libstdc++
5296
installed, you can tell configure to use gcc as your C++
5298
shell> CC=gcc CXX=gcc ./configure
5299
When you use gcc as your C++ compiler, it does not attempt to
5300
link in libg++ or libstdc++. This may be a good thing to do
5301
even if you have those libraries installed. Some versions of
5302
them have caused strange problems for MySQL users in the past.
5303
In most cases, you can get a reasonably optimized MySQL binary
5304
by using the following options on the configure line:
5305
--prefix=/usr/local/mysql --enable-assembler \
5306
--with-mysqld-ldflags=-all-static
5307
The full configure line would, in other words, be something
5308
like the following for all recent gcc versions:
5309
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
5310
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
5311
--prefix=/usr/local/mysql --enable-assembler \
5312
--with-mysqld-ldflags=-all-static
5313
The binaries we provide on the MySQL Web site at
5314
http://dev.mysql.com/downloads/ are all compiled with full
5315
optimization and should work well for most users. See Section
5316
2.2, "Installing MySQL from Generic Binaries on Unix/Linux."
5318
* If the build fails and produces errors about your compiler or
5319
linker not being able to create the shared library
5320
libmysqlclient.so.N (where N is a version number), you can
5321
work around this problem by giving the --disable-shared option
5322
to configure. In this case, configure does not build a shared
5323
libmysqlclient.so.N library.
5325
* By default, MySQL uses the latin1 (cp1252 West European)
5326
character set. To change the default set, use the
5327
--with-charset option:
5328
shell> ./configure --with-charset=CHARSET
5329
CHARSET may be one of binary, armscii8, ascii, big5, cp1250,
5330
cp1251, cp1256, cp1257, cp850, cp852, cp866, cp932, dec8,
5331
eucjpms, euckr, gb2312, gbk, geostd8, greek, hebrew, hp8,
5332
keybcs2, koi8r, koi8u, latin1, latin2, latin5, latin7, macce,
5333
macroman, sjis, swe7, tis620, ucs2, ujis, utf8. (Additional
5334
character sets might be available. Check the output from
5335
./configure --help for the current list.)
5336
The default collation may also be specified. MySQL uses the
5337
latin1_swedish_ci collation by default. To change this, use
5338
the --with-collation option:
5339
shell> ./configure --with-collation=COLLATION
5340
To change both the character set and the collation, use both
5341
the --with-charset and --with-collation options. The collation
5342
must be a legal collation for the character set. (Use the SHOW
5343
COLLATION statement to determine which collations are
5344
available for each character set.)
5345
With the configure option --with-extra-charsets=LIST, you can
5346
define which additional character sets should be compiled into
5347
the server. LIST is one of the following:
5349
+ A list of character set names separated by spaces
5351
+ complex to include all character sets that can't be
5354
+ all to include all character sets into the binaries
5355
Clients that want to convert characters between the server and
5356
the client should use the SET NAMES statement. See Section
5357
9.1.4, "Connection Character Sets and Collations."
5359
* To configure MySQL with debugging code, use the --with-debug
5361
shell> ./configure --with-debug
5362
This causes a safe memory allocator to be included that can
5363
find some errors and that provides output about what is
5364
happening. See MySQL Internals: Porting
5365
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
5366
As of MySQL 5.1.12, using --with-debug to configure MySQL with
5367
debugging support enables you to use the
5368
--debug="d,parser_debug" option when you start the server.
5369
This causes the Bison parser that is used to process SQL
5370
statements to dump a parser trace to the server's standard
5371
error output. Typically, this output is written to the error
5374
* To cause the Debug Sync facility to be compiled into the
5375
server, use the --enable-debug-sync option. This facility is
5376
used for testing and debugging. When compiled in, Debug Sync
5377
is disabled by default at runtime. To enable it, start mysqld
5378
with the --debug-sync-timeout=N option, where N is a timeout
5379
value greater than 0. (The default value is 0, which disables
5380
Debug Sync.) N becomes the default timeout for individual
5381
synchronization points.
5382
Debug Sync is also compiled in if you configure with the
5383
--with-debug option (which implies --enable-debug-sync),
5384
unless you also use the --disable-debug-sync option.
5385
For a description of the Debug Sync facility and how to use
5386
synchronization points, see MySQL Internals: Test
5388
(http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronizat
5390
The --enable-debug-sync and --disable-debug-sync options were
5391
added in MySQL 5.1.41.
5393
* If your client programs are using threads, you must compile a
5394
thread-safe version of the MySQL client library with the
5395
--enable-thread-safe-client configure option. This creates a
5396
libmysqlclient_r library with which you should link your
5397
threaded applications. See Section 20.9.16.2, "How to Write a
5400
* Some features require that the server be built with
5401
compression library support, such as the COMPRESS() and
5402
UNCOMPRESS() functions, and compression of the client/server
5403
protocol. The --with-zlib-dir=no|bundled|DIR option provides
5404
control over compression library support. The value no
5405
explicitly disables compression support. bundled causes the
5406
zlib library bundled in the MySQL sources to be used. A DIR
5407
path name specifies the directory in which to find the
5408
compression library sources.
5410
* It is possible to build MySQL with large table support using
5411
the --with-big-tables option.
5412
This option causes the variables that store table row counts
5413
to be declared as unsigned long long rather than unsigned
5414
long. This enables tables to hold up to approximately
5415
1.844E+19 ((2^32)^2) rows rather than 2^32 (~4.295E+09) rows.
5416
Previously it was necessary to pass -DBIG_TABLES to the
5417
compiler manually in order to enable this feature.
5419
* Run configure with the --disable-grant-options option to cause
5420
the --bootstrap, --skip-grant-tables, and --init-file options
5421
for mysqld to be disabled. For Windows, the configure.js
5422
script recognizes the DISABLE_GRANT_OPTIONS flag, which has
5423
the same effect. The capability is available as of MySQL
5426
* This option allows MySQL Community Server features to be
5427
enabled. Additional options may be required for individual
5428
features, such as --enable-profiling to enable statement
5429
profiling. This option was added in MySQL 5.1.24. It is
5430
enabled by default as of MySQL 5.1.28; to disable it, use
5431
--disable-community-features.
5433
* When given with --enable-community-features, the
5434
--enable-profiling option enables the statement profiling
5435
capability exposed by the SHOW PROFILE and SHOW PROFILES
5436
statements. (See Section 12.7.5.33, "SHOW PROFILES Syntax.")
5437
This option was added in MySQL 5.1.24. It is enabled by
5438
default as of MySQL 5.1.28; to disable it, use
5439
--disable-profiling.
5441
* See Section 2.1, "General Installation Guidance," for options
5442
that pertain to particular operating systems.
5444
* See Section 5.5.6.2, "Using SSL Connections," for options that
5445
pertain to configuring MySQL to support secure (encrypted)
5448
* Several configure options apply to plugin selection and
5450
--with-plugins=PLUGIN[,PLUGIN]...
5451
--with-plugins=GROUP
5452
--with-plugin-PLUGIN
5453
--without-plugin-PLUGIN
5454
PLUGIN is an individual plugin name such as csv or archive.
5455
As shorthand, GROUP is a configuration group name such as none
5456
(select no plugins) or all (select all plugins).
5457
You can build a plugin as static (compiled into the server) or
5458
dynamic (built as a dynamic library that must be installed
5459
using the INSTALL PLUGIN statement or the --plugin-load option
5460
before it can be used). Some plugins might not support static
5462
configure --help shows the following information pertaining to
5465
+ The plugin-related options
5467
+ The names of all available plugins
5469
+ For each plugin, a description of its purpose, which
5470
build types it supports (static or dynamic), and which
5471
plugin groups it is a part of.
5472
--with-plugins can take a list of one or more plugin names
5473
separated by commas, or a plugin group name. The named plugins
5474
are configured to be built as static plugins.
5475
--with-plugin-PLUGIN configures the given plugin to be built
5477
--without-plugin-PLUGIN disables the given plugin from being
5479
If a plugin is named both with a --with and --without option,
5480
the result is undefined.
5481
For any plugin that is not explicitly selected or disabled, it
5482
is selected to be built dynamically if it supports dynamic
5483
build, and not built if it does not support dynamic build.
5484
(Thus, in the case that no plugin options are given, all
5485
plugins that support dynamic build are selected to be built as
5486
dynamic plugins. Plugins that do not support dynamic build are
5489
2.11.5. Dealing with Problems Compiling MySQL
5491
All MySQL programs compile cleanly for us with no warnings on
5492
Solaris or Linux using gcc. On other systems, warnings may occur
5493
due to differences in system include files. For other problems,
5494
check the following list.
5496
The solution to many problems involves reconfiguring. If you do
5497
need to reconfigure, take note of the following:
5499
* If configure is run after it has previously been run, it may
5500
use information that was gathered during its previous
5501
invocation. This information is stored in config.cache. When
5502
configure starts up, it looks for that file and reads its
5503
contents if it exists, on the assumption that the information
5504
is still correct. That assumption is invalid when you
5507
* Each time you run configure, you must run make again to
5508
recompile. However, you may want to remove old object files
5509
from previous builds first because they were compiled using
5510
different configuration options.
5512
To prevent old configuration information or object files from
5513
being used, run these commands before re-running configure:
5514
shell> rm config.cache
5517
Alternatively, you can run make distclean.
5519
The following list describes some of the problems that have been
5520
found to occur most often when compiling MySQL:
5522
* If you get errors such as the ones shown here when compiling
5523
sql_yacc.cc, you probably have run out of memory or swap
5525
Internal compiler error: program cc1plus got fatal signal 11
5526
Out of virtual memory
5527
Virtual memory exhausted
5528
The problem is that gcc requires a huge amount of memory to
5529
compile sql_yacc.cc with inline functions. Try running
5530
configure with the --with-low-memory option:
5531
shell> ./configure --with-low-memory
5532
This option causes -fno-inline to be added to the compile line
5533
if you are using gcc and -O0 if you are using something else.
5534
You should try the --with-low-memory option even if you have
5535
so much memory and swap space that you think you can't
5536
possibly have run out. This problem has been observed to occur
5537
even on systems with generous hardware configurations, and the
5538
--with-low-memory option usually fixes it.
5540
* By default, configure picks c++ as the compiler name and GNU
5541
c++ links with -lg++. If you are using gcc, that behavior can
5542
cause problems during configuration such as this:
5543
configure: error: installation or configuration problem:
5544
C++ compiler cannot create executables.
5545
You might also observe problems during compilation related to
5546
g++, libg++, or libstdc++.
5547
One cause of these problems is that you may not have g++, or
5548
you may have g++ but not libg++, or libstdc++. Take a look at
5549
the config.log file. It should contain the exact reason why
5550
your C++ compiler did not work. To work around these problems,
5551
you can use gcc as your C++ compiler. Try setting the
5552
environment variable CXX to "gcc -O3". For example:
5553
shell> CXX="gcc -O3" ./configure
5554
This works because gcc compiles C++ source files as well as
5555
g++ does, but does not link in libg++ or libstdc++ by default.
5556
Another way to fix these problems is to install g++, libg++,
5557
and libstdc++. However, do not use libg++ or libstdc++ with
5558
MySQL because this only increases the binary size of mysqld
5559
without providing any benefits. Some versions of these
5560
libraries have also caused strange problems for MySQL users in
5563
* To define flags to be used by your C or C++ compilers, specify
5564
them using the CFLAGS and CXXFLAGS environment variables. You
5565
can also specify the compiler names this way using CC and CXX.
5571
shell> export CC CFLAGS CXX CXXFLAGS
5572
To see what flags you might need to specify, invoke
5573
mysql_config with the --cflags option.
5575
* If you get errors such as those shown here when compiling
5576
mysqld, configure did not correctly detect the type of the
5577
last argument to accept(), getsockname(), or getpeername():
5578
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
5579
type of the pointer value ''length'' is ''unsigned long'',
5580
which is not compatible with ''int''.
5581
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
5582
To fix this, edit the config.h file (which is generated by
5583
configure). Look for these lines:
5584
/* Define as the base type of the last arg to accept */
5585
#define SOCKET_SIZE_TYPE XXX
5586
Change XXX to size_t or int, depending on your operating
5587
system. (You must do this each time you run configure because
5588
configure regenerates config.h.)
5590
* If your compile fails with errors such as any of the
5591
following, you must upgrade your version of make to GNU make:
5592
make: Fatal error in reader: Makefile, line 18:
5593
Badly formed macro assignment
5595
make: file `Makefile' line 18: Must be a separator (:
5597
pthread.h: No such file or directory
5598
Solaris and FreeBSD are known to have troublesome make
5600
GNU make 3.75 is known to work.
5602
* The sql_yacc.cc file is generated from sql_yacc.yy. Normally,
5603
the build process does not need to create sql_yacc.cc because
5604
MySQL comes with a pregenerated copy. However, if you do need
5605
to re-create it, you might encounter this error:
5606
"sql_yacc.yy", line xxx fatal: default action causes potential...
5607
This is a sign that your version of yacc is deficient. You
5608
probably need to install bison (the GNU version of yacc) and
5610
Versions of bison older than 1.75 may report this error:
5611
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded
5612
The maximum table size is not actually exceeded; the error is
5613
caused by bugs in older versions of bison.
5615
* On Debian Linux 3.0, you need to install gawk instead of the
5618
* If you get a compilation error on Linux (for example, SuSE
5619
Linux 8.1 or Red Hat Linux 7.3) similar to the following one,
5620
you probably do not have g++ installed:
5621
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
5622
incompatible pointer type
5623
libmysql.c:1329: too few arguments to function `gethostbyname_r'
5624
libmysql.c:1329: warning: assignment makes pointer from integer
5626
make[2]: *** [libmysql.lo] Error 1
5627
By default, the configure script attempts to determine the
5628
correct number of arguments by using g++ (the GNU C++
5629
compiler). This test yields incorrect results if g++ is not
5630
installed. There are two ways to work around this problem:
5632
+ Make sure that the GNU C++ g++ is installed. On some
5633
Linux distributions, the required package is called gpp;
5634
on others, it is named gcc-c++.
5636
+ Use gcc as your C++ compiler by setting the CXX
5637
environment variable to gcc:
5639
You must run configure again after making either of those
5642
For information about acquiring or updating tools, see the system
5643
requirements in Section 2.11, "Installing MySQL from Source."
5645
2.11.6. Compiling and Linking an Optimized mysqld Server
5647
Most of the following tests were performed on Linux with the MySQL
5648
benchmarks, but they should give some indication for other
5649
operating systems and workloads.
5651
You obtain the fastest executables when you link with -static.
5653
By using better compiler and compilation options, you can obtain a
5654
10% to 30% speed increase in applications. This is particularly
5655
important if you compile the MySQL server yourself.
5657
When we tested both the Cygnus CodeFusion and Fujitsu compilers,
5658
neither was sufficiently bug-free to enable MySQL to be compiled
5659
with optimizations enabled.
5661
The standard MySQL binary distributions are compiled with support
5662
for all character sets. When you compile MySQL yourself, include
5663
support only for the character sets that you are going to use.
5664
This is controlled by the --with-charset option to configure.
5666
Here is a list of some measurements that we have made:
5668
* If you link dynamically (without -static), the result is 13%
5669
slower on Linux. Note that you still can use a dynamically
5670
linked MySQL library for your client applications. It is the
5671
server that is most critical for performance.
5673
* For a connection from a client to a server running on the same
5674
host, if you connect using TCP/IP rather than a Unix socket
5675
file, performance is 7.5% slower. (On Unix, if you connect to
5676
the host name localhost, MySQL uses a socket file by default.)
5678
* For TCP/IP connections from a client to a server, connecting
5679
to a remote server on another host is 8% to 11% slower than
5680
connecting to a server on the same host, even for connections
5681
faster than 100Mb/s Ethernet.
5683
* When running our benchmark tests using secure connections (all
5684
data encrypted with internal SSL support) performance was 55%
5685
slower than with unencrypted connections.
5687
* On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is
5688
4% faster than one compiled with gcc 3.2.
5690
* On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is
5691
4% faster in 32-bit mode than in 64-bit mode.
5693
* Compiling on Linux-x86 using gcc without frame pointers
5694
(-fomit-frame-pointer or -fomit-frame-pointer -ffixed-ebp)
5695
makes mysqld 1% to 4% faster.
5697
2.11.7. Installing MySQL from Source on Windows
5699
These instructions describe how to build binaries from source for
5700
MySQL 5.1 on Windows. Instructions are provided for building
5701
binaries from a standard source distribution or from the Bazaar
5702
tree that contains the latest development source.
5705
The instructions here are strictly for users who want to test
5706
MySQL on Microsoft Windows from the latest source distribution or
5707
from the Bazaar tree. For production use, we do not advise using a
5708
MySQL server built by yourself from source. Normally, it is best
5709
to use precompiled binary distributions of MySQL that are built
5710
specifically for optimal performance on Windows by Oracle
5711
Corporation. Instructions for installing binary distributions are
5712
available in Section 2.3, "Installing MySQL on Microsoft Windows."
5714
To build MySQL on Windows from source, you must satisfy the
5715
following system, compiler, and resource requirements:
5717
* Windows 2000, Windows XP, or newer version.
5718
Windows Vista is supported when using Visual Studio 2005
5719
provided you have installed the following updates:
5721
+ Microsoft Visual Studio 2005 Professional Edition - ENU
5722
Service Pack 1 (KB926601)
5723
(http://support.microsoft.com/?kbid=926601)
5725
+ Security Update for Microsoft Visual Studio 2005
5726
Professional Edition - ENU (KB937061)
5727
(http://support.microsoft.com/?kbid=937061)
5729
+ Update for Microsoft Visual Studio 2005 Professional
5730
Edition - ENU (KB932232)
5731
(http://support.microsoft.com/?kbid=932232)
5733
* CMake, which can be downloaded from http://www.cmake.org.
5734
After installing, modify your PATH environment variable to
5735
include the directory where cmake is located.
5737
* Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net
5738
2003 (7.1), or Visual Studio 2005 (8.0) compiler system.
5740
* If you are using Visual C++ 2005 Express Edition, you must
5741
also install an appropriate Platform SDK. More information and
5742
links to downloads for various Windows platforms is available
5744
http://www.microsoft.com/downloads/details.aspx?familyid=0baf2
5745
b35-c656-4969-ace8-e4c0c0716adb.
5747
* If you are compiling from a Bazaar tree or making changes to
5748
the parser, you need bison for Windows, which can be
5750
http://gnuwin32.sourceforge.net/packages/bison.htm. Download
5751
the package labeled "Complete package, excluding sources".
5752
After installing the package, modify your PATH environment
5753
variable to include the directory where bison is located.
5755
On Windows, the default location for bison is the C:\Program
5756
Files\GnuWin32 directory. Some utilities, including m4, may
5757
fail to find bison because of the space in the directory name.
5758
You can resolve this by installing into a directory that does
5759
not contain a space; for example C:\GnuWin32.
5761
* Cygwin might be necessary if you want to run the test script
5762
or package the compiled binaries and support files into a Zip
5763
archive. (Cygwin is needed only to test or package the
5764
distribution, not to build it.) Cygwin is available from
5767
* 3GB to 5GB of disk space.
5769
You also need a MySQL source distribution for Windows, which can
5770
be obtained two ways:
5772
* Obtain a source distribution packaged by Oracle Corporation.
5773
These are available from http://dev.mysql.com/downloads/.
5775
* Package a source distribution yourself from the latest Bazaar
5776
developer source tree. For instructions on pulling the latest
5777
source files, see Section 2.11.3, "Installing MySQL from a
5778
Development Source Tree."
5780
If you find something not working as expected, or you have
5781
suggestions about ways to improve the current build process on
5782
Windows, please send a message to the win32 mailing list. See
5783
Section 1.6.1, "MySQL Mailing Lists."
5786
To compile from the source code on Windows you must use the
5787
standard source distribution (for example, mysql-5.1.62.zip) or
5788
mysql-5.1.62.tar.gz). You build from the same distribution as used
5789
to build MySQL on Unix, Linux and other platforms. Do not use the
5790
Windows Source distributions as they do not contain the necessary
5791
configuration script and other files.
5793
Follow this procedure to build MySQL:
5795
1. If you are installing from a packaged source distribution,
5796
create a work directory (for example, C:\workdir), and unpack
5797
the source distribution there using WinZip or another Windows
5798
tool that can read .zip files. This directory is the work
5799
directory in the following instructions.
5801
Commands that are located in the win directory should be
5802
executed from the top-level source directory. Do not change
5803
location into the win directory, as the commands will not
5806
2. Start a command shell. If you have not configured the PATH and
5807
other environment variables for all command shells, you may be
5808
able to start a command shell from the Start Menu within the
5809
Windows Visual Studio menu that contains the necessary
5810
environment changes.
5812
3. Within the command shell, navigate to the work directory and
5813
run the following command:
5814
C:\workdir>win\configure.js options
5815
If you have associated the .js file extension with an
5816
application such as a text editor, then you may need to use
5817
the following command to force configure.js to be executed as
5819
C:\workdir>cscript win\configure.js options
5820
These options are available for configure.js:
5822
+ WITH_INNOBASE_STORAGE_ENGINE: Enable the InnoDB storage
5825
+ WITH_PARTITION_STORAGE_ENGINE: Enable user-defined
5828
+ WITH_ARCHIVE_STORAGE_ENGINE: Enable the ARCHIVE storage
5831
+ WITH_BLACKHOLE_STORAGE_ENGINE: Enable the BLACKHOLE
5834
+ WITH_EXAMPLE_STORAGE_ENGINE: Enable the EXAMPLE storage
5837
+ WITH_FEDERATED_STORAGE_ENGINE: Enable the FEDERATED
5840
+ WITH_NDBCLUSTER_STORAGE_ENGINE: Enable the NDBCLUSTER
5841
storage engine in the MySQL server; cause binaries for
5842
the MySQL Cluster management and data node, management
5843
client, and other programs to be built.
5844
This option is supported only in MySQL Cluster NDB 7.0
5845
and later (NDBCLUSTER storage engine versions 6.4.0 and
5846
later) using the MySQL Cluster sources. It cannot be used
5847
to enable clustering support in other MySQL source trees
5850
+ MYSQL_SERVER_SUFFIX=suffix: Server suffix, default none.
5852
+ COMPILATION_COMMENT=comment: Server comment, default
5853
"Source distribution".
5855
+ MYSQL_TCP_PORT=port: Server port, default 3306.
5857
+ DISABLE_GRANT_OPTIONS: Disables the --bootstrap,
5858
--skip-grant-tables, and --init-file options for mysqld.
5859
This option is available as of MySQL 5.1.15.
5860
For example (type the command on one line):
5861
C:\workdir>win\configure.js WITH_INNOBASE_STORAGE_ENGINE
5862
WITH_PARTITION_STORAGE_ENGINE MYSQL_SERVER_SUFFIX=-pro
5864
4. From the work directory, execute the win\build-vs9.bat
5865
(Windows Visual Studio 2008), win\build-vs8.bat (Windows
5866
Visual Studio 2005), or win\build-vs71.bat (Windows Visual
5867
Studio 2003) script, depending on the version of Visual Studio
5868
you have installed. The script invokes CMake, which generates
5869
the mysql.sln solution file.
5870
You can also use the corresponding 64-bit file (for example
5871
win\build-vs8_x64.bat or win\build-vs9_x64.bat) to build the
5872
64-bit version of MySQL. However, you cannot build the 64-bit
5873
version with Visual Studio Express Edition. You must use
5874
Visual Studio 2005 (8.0) or higher.
5876
5. From the work directory, open the generated mysql.sln file
5877
with Visual Studio and select the proper configuration using
5878
the Configuration menu. The menu provides Debug, Release,
5879
RelwithDebInfo, MinRelInfo options. Then select Solution >
5880
Build to build the solution.
5881
Remember the configuration that you use in this step. It is
5882
important later when you run the test script because that
5883
script needs to know which configuration you used.
5885
6. Test the server. The server built using the preceding
5886
instructions expects that the MySQL base directory and data
5887
directory are C:\mysql and C:\mysql\data by default. If you
5888
want to test your server using the source tree root directory
5889
and its data directory as the base directory and data
5890
directory, you need to tell the server their path names. You
5891
can either do this on the command line with the --basedir and
5892
--datadir options, or by placing appropriate options in an
5893
option file. (See Section 4.2.3.3, "Using Option Files.") If
5894
you have an existing data directory elsewhere that you want to
5895
use, you can specify its path name instead.
5896
When the server is running in standalone fashion or as a
5897
service based on your configuration, try to connect to it from
5898
the mysql interactive command-line utility.
5899
You can also run the standard test script, mysql-test-run.pl.
5900
This script is written in Perl, so you'll need either Cygwin
5901
or ActiveState Perl to run it. You may also need to install
5902
the modules required by the script. To run the test script,
5903
change location into the mysql-test directory under the work
5904
directory, set the MTR_VS_CONFIG environment variable to the
5905
configuration you selected earlier (or use the --vs-config
5906
option), and invoke mysql-test-run.pl. For example (using
5907
Cygwin and the bash shell):
5908
shell> cd mysql-test
5909
shell> export MTR_VS_CONFIG=debug
5910
shell> ./mysql-test-run.pl --force --timer
5911
shell> ./mysql-test-run.pl --force --timer --ps-protocol
5913
When you are satisfied that the programs you have built are
5914
working correctly, stop the server. Now you can install the
5915
distribution. One way to do this is to use the make_win_bin_dist
5916
script in the scripts directory of the MySQL source distribution
5917
(see Section 4.4.2, "make_win_bin_dist --- Package MySQL
5918
Distribution as Zip Archive"). This is a shell script, so you must
5919
have Cygwin installed if you want to use it. It creates a Zip
5920
archive of the built executables and support files that you can
5921
unpack in the location at which you want to install MySQL.
5923
It is also possible to install MySQL by copying directories and
5926
1. Create the directories where you want to install MySQL. For
5927
example, to install into C:\mysql, use these commands:
5929
C:\> mkdir C:\mysql\bin
5930
C:\> mkdir C:\mysql\data
5931
C:\> mkdir C:\mysql\share
5932
C:\> mkdir C:\mysql\scripts
5933
If you want to compile other clients and link them to MySQL,
5934
you should also create several additional directories:
5935
C:\> mkdir C:\mysql\include
5936
C:\> mkdir C:\mysql\lib
5937
C:\> mkdir C:\mysql\lib\debug
5938
C:\> mkdir C:\mysql\lib\opt
5939
If you want to benchmark MySQL, create this directory:
5940
C:\> mkdir C:\mysql\sql-bench
5941
Benchmarking requires Perl support for MySQL. See Section
5942
2.15, "Perl Installation Notes."
5944
2. From the work directory, copy into the C:\mysql directory the
5945
following files and directories:
5947
C:\workdir> mkdir C:\mysql
5948
C:\workdir> mkdir C:\mysql\bin
5949
C:\workdir> copy client\Release\*.exe C:\mysql\bin
5950
C:\workdir> copy sql\Release\mysqld.exe C:\mysql\bin\mysqld.exe
5951
C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E
5952
C:\workdir> xcopy share\*.* C:\mysql\share /E
5953
If you want to compile other clients and link them to MySQL,
5954
you should also copy several libraries and header files:
5955
C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\debug
5956
C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\debug
5957
C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\debug
5958
C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\opt
5959
C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\opt
5960
C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\opt
5961
C:\workdir> copy include\*.h C:\mysql\include
5962
C:\workdir> copy libmysql\libmysql.def C:\mysql\include
5964
If you have compiled a Debug solution, rather than a Release
5965
solution, install it by replacing Release with Debug in the
5966
source file names just shown.
5967
If you want to benchmark MySQL, you should also do this:
5968
C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E
5970
After installation, set up and start the server in the same way as
5971
for binary Windows distributions. This includes creating the
5972
system tables by running mysql_install_db. For more information,
5973
see Section 2.3, "Installing MySQL on Microsoft Windows."
5975
2.11.8. Notes on Installing MySQL on Solaris from Source
5977
When building MySQL on Solaris you can use either the Sun Studio
5978
or GNU cc compilers. For more information on specific notes and
5979
environments, use the following hints.
5981
* When building you should ensure that your PATH variable
5982
includes the necessary tools, including ar for building
5983
libraries. Some tools are located in /usr/ccs/bin.
5985
* When running configure, you should specify the C and C++
5986
compiler explicitly to ensure that the right C compiler
5987
combination is used:
5988
CC=gcc CXX=g++ ./configure
5990
* For detailed information on performance tuning your MySQL
5991
installation for Solaris, you can use the information from
5993
(http://blogs.sun.com/krishs/entry/sun_studio_compiler_options
5994
_for) and the Sun Solaris MySQL Performance Tuning
5995
(http://developers.sun.com/solaris/articles/mysql_perf_tune.ht
5998
* If you have an UltraSPARC system, you can get 4% better
5999
performance by adding -mcpu=v8 -Wa,-xarch=v8plusa to the
6000
CFLAGS and CXXFLAGS environment variables.
6002
* If you have Sun's Forte 5.00 (or newer) or Sun Studio
6003
compiler, you can run configure like this:
6004
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
6005
CXX=CC CXXFLAGS="-noex -mt" \
6006
./configure --prefix=/usr/local/mysql --enable-assembler
6008
* To create a 64-bit SPARC binary with Sun's Forte or Sun Studio
6009
compiler, use the following configuration options:
6010
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
6011
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
6012
./configure --prefix=/usr/local/mysql --enable-assembler
6013
To create a 64-bit Solaris binary using gcc, add -m64 to
6014
CFLAGS and CXXFLAGS and remove --enable-assembler from the
6016
In the MySQL benchmarks, we obtained a 4% speed increase on
6017
UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to
6018
using gcc 3.2 with the -mcpu flag.
6019
If you create a 64-bit mysqld binary, it is 4% slower than the
6020
32-bit binary, but can handle more threads and memory.
6022
* If you get a problem with fdatasync or sched_yield, you can
6023
fix this by adding LIBS=-lrt to the configure line
6025
* Solaris does not provide static versions of all system
6026
libraries (libpthreads and libdl), so you cannot compile MySQL
6027
with --static. If you try to do so, you get one of the
6029
ld: fatal: library -ldl: not found
6030
undefined reference to `dlopen'
6033
* If you link your own MySQL client programs, you may see the
6034
following error at runtime:
6035
ld.so.1: fatal: libmysqlclient.so.#:
6036
open failed: No such file or directory
6037
To avoid this problem, use one of the following methods:
6039
+ Use the crle tool to add the directory containing the
6040
libmysqlclient library file to the list of standard
6041
library directories. You need administrator privileges to
6042
do this. Make sure you update the library information,
6043
rather than replace it with the new path. For example,
6044
the following command adds the directory to the list of
6045
standard directories searched for libraries.
6046
crle -u -l /usr/local/mysql/lib
6047
For 64-bit libraries, add the -64 option:
6048
crle -64 -u -l /usr/local/mysql/lib
6050
+ Link clients with the
6051
-Wl,r/full/path/to/libmysqlclient.so flag rather than
6054
+ Copy libmysqclient.so to /usr/lib.
6056
+ Add the path name of the directory where
6057
libmysqlclient.so is located to the LD_RUN_PATH
6058
environment variable before running your client.
6060
* If you have problems with configure trying to link with -lz
6061
when you do not have zlib installed, you have two options:
6063
+ If you want to be able to use the compressed
6064
communication protocol, obtain and install zlib from
6067
+ To build without zlib, run configure with the
6068
--with-named-z-libs=no option when building MySQL.
6070
* If you are using gcc and have problems with loading
6071
user-defined functions (UDFs) into MySQL, try adding -lgcc to
6072
the link line for the UDF.
6074
2.11.9. Notes on Installing MySQL on AIX from Source
6076
General notes on building MySQL from source on IBM AIX:
6078
* Automatic xlC detection is missing from Autoconf, so a number
6079
of variables need to be set before running configure. The
6080
following example uses the IBM compiler:
6895
6081
export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
6896
6082
export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
6897
6083
export CFLAGS="-I /usr/local/include"
7709
6939
running. If so, shut down the server before starting mysqld again.
7710
6940
(If another server is running, and you really want to run multiple
7711
6941
servers, you can find information about how to do so in Section
7712
5.6, "Running Multiple MySQL Servers on the Same Machine.")
6942
5.6, "Running Multiple MySQL Instances on One Machine.")
7714
6944
If no other server is running, try to execute the command telnet
7715
6945
your_host_name tcp_ip_port_number. (The default MySQL port number
7716
is 3306.) Then press Enter a couple of times. If you don't get an
6946
is 3306.) Then press Enter a couple of times. If you do not get an
7717
6947
error message like telnet: Unable to connect to remote host:
7718
6948
Connection refused, some other program is using the TCP/IP port
7719
that mysqld is trying to use. You'll need to track down what
6949
that mysqld is trying to use. You will need to track down what
7720
6950
program this is and disable it, or else tell mysqld to listen to a
7721
different port with the --port option. In this case, you'll also
6951
different port with the --port option. In this case, you will also
7722
6952
need to specify the port number for client programs when
7723
connecting to the server via TCP/IP.
6953
connecting to the server using TCP/IP.
7725
6955
Another reason the port might be inaccessible is that you have a
7726
6956
firewall running that blocks connections to it. If so, modify the
7727
firewall settings to allow access to the port.
6957
firewall settings to permit access to the port.
7729
If the server starts but you can't connect to it, you should make
6959
If the server starts but you cannot connect to it, you should make
7730
6960
sure that you have an entry in /etc/hosts that looks like this:
7731
6961
127.0.0.1 localhost
7733
This problem occurs only on systems that do not have a working
7734
thread library and for which MySQL must be configured to use
7737
6963
If you cannot get mysqld to start, you can try to make a trace
7738
6964
file to find the problem by using the --debug option. See MySQL
7739
6965
Internals: Porting
7740
6966
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
7742
2.13.2. Securing the Initial MySQL Accounts
6968
2.12.2. Securing the Initial MySQL Accounts
7744
6970
Part of the MySQL installation process is to set up the mysql
7745
6971
database that contains the grant tables:
7747
* Windows distributions contain preinitialized grant tables that
7748
are installed automatically.
7750
* On Unix, the grant tables are populated by the
7751
mysql_install_db program. Some installation methods run this
7752
program for you. Others require that you execute it manually.
7753
For details, see Section 2.13.1, "Unix Post-Installation
7756
The grant tables define the initial MySQL user accounts and their
7757
access privileges. These accounts are set up as follows:
7759
* Accounts with the user name root are created. These are
7760
superuser accounts that can do anything. The initial root
7761
account passwords are empty, so anyone can connect to the
7762
MySQL server as root --- without a password --- and be granted
7765
+ On Windows, one root account is created; this account
7766
allows connecting from the local host only. The Windows
7767
installer will optionally create an account allowing for
7768
connections from any host only if the user selects the
7769
Enable root access from remote machines option during
7772
+ On Unix, both root accounts are for connections from the
7773
local host. Connections must be made from the local host
7774
by specifying a host name of localhost for one of the
7775
accounts, or the actual host name or IP number for the
7778
* Two anonymous-user accounts are created, each with an empty
6973
* Windows distributions contain preinitialized grant tables.
6975
* On Unix, the mysql_install_db program populates the grant
6976
tables. Some installation methods run this program for you.
6977
Others require that you execute it manually. For details, see
6978
Section 2.12.1, "Unix Postinstallation Procedures."
6980
The mysql.user grant table defines the initial MySQL user accounts
6981
and their access privileges:
6983
* Some accounts have the user name root. These are superuser
6984
accounts that have all privileges and can do anything. The
6985
initial root account passwords are empty, so anyone can
6986
connect to the MySQL server as root without a password and be
6987
granted all privileges.
6989
+ On Windows, root accounts are created that permit
6990
connections from the local host only. Connections can be
6991
made by specifying the host name localhost or the IP
6992
address 127.0.0.1. If the user selects the Enable root
6993
access from remote machines option during installation,
6994
the Windows installer creates another root account that
6995
permits connections from any host.
6997
+ On Unix, each root account permits connections from the
6998
local host. Connections can be made by specifying the
6999
host name localhost, the IP address 127.0.0.1, or the
7000
actual host name or IP address.
7001
An attempt to connect to the host 127.0.0.1 normally resolves
7002
to the localhost account. However, this fails if the server is
7003
run with the --skip-name-resolve option, so the 127.0.0.1
7004
account is useful in that case.
7006
* Some accounts are for anonymous users. These have an empty
7779
7007
user name. The anonymous accounts have no password, so anyone
7780
7008
can use them to connect to the MySQL server.
7782
+ On Windows, one anonymous account is for connections from
7783
the local host. It has no global privileges. (Before
7784
MySQL 5.1.16, it has all global privileges, just like the
7785
root accounts.) The other is for connections from any
7786
host and has all privileges for the test database and for
7787
other databases with names that start with test.
7789
+ On Unix, both anonymous accounts are for connections from
7790
the local host. Connections must be made from the local
7791
host by specifying a host name of localhost for one of
7792
the accounts, or the actual host name or IP number for
7793
the other. These accounts have all privileges for the
7794
test database and for other databases with names that
7797
As noted, none of the initial accounts have passwords. This means
7798
that your MySQL installation is unprotected until you do something
7010
+ On Windows, there is one anonymous account that permits
7011
connections from the local host. Connections can be made
7012
by specifying a host name of localhost. The account has
7013
no global privileges. (Before MySQL 5.1.16, it has all
7014
global privileges, just like the root accounts.)
7016
+ On Unix, each anonymous account permits connections from
7017
the local host. Connections can be made by specifying a
7018
host name of localhost for one of the accounts, or the
7019
actual host name or IP address for the other.
7021
To display which accounts exist in the mysql.user table and check
7022
whether their passwords are empty, use the following statement:
7023
mysql> SELECT User, Host, Password FROM mysql.user;
7024
+------+--------------------+----------+
7025
| User | Host | Password |
7026
+------+--------------------+----------+
7027
| root | localhost | |
7028
| root | myhost.example.com | |
7029
| root | 127.0.0.1 | |
7031
| | myhost.example.com | |
7032
+------+--------------------+----------+
7034
This output indicates that there are several root and
7035
anonymous-user accounts, none of which have passwords. The output
7036
might differ on your system, but the presence of accounts with
7037
empty passwords means that your MySQL installation is unprotected
7038
until you do something about it:
7040
* You should assign a password to each MySQL root account.
7801
7042
* If you want to prevent clients from connecting as anonymous
7802
7043
users without a password, you should either assign a password
7803
7044
to each anonymous account or else remove the accounts.
7805
* You should assign a password to each MySQL root account.
7046
In addition, the mysql.db table contains rows that permit all
7047
accounts to access the test database and other databases with
7048
names that start with test_. This is true even for accounts that
7049
otherwise have no special privileges such as the default anonymous
7050
accounts. This is convenient for testing but inadvisable on
7051
production servers. Administrators who want database access
7052
restricted only to accounts that have permissions granted
7053
explicitly for that purpose should remove these mysql.db table
7807
7056
The following instructions describe how to set up passwords for
7808
the initial MySQL accounts, first for the anonymous accounts and
7809
then for the root accounts. Replace "newpwd" in the examples with
7810
the actual password that you want to use. The instructions also
7811
cover how to remove the anonymous accounts, should you prefer not
7812
to allow anonymous access at all.
7814
You might want to defer setting the passwords until later, so that
7815
you don't need to specify them while you perform additional setup
7057
the initial MySQL accounts, first for the root accounts, then for
7058
the anonymous accounts. The instructions also cover how to remove
7059
the anonymous accounts, should you prefer not to permit anonymous
7060
access at all, and describe how to remove permissive access to
7061
test databases. Replace newpwd in the examples with the password
7062
that you want to use. Replace host_name with the name of the
7063
server host. You can determine this name from the output of the
7064
preceding SELECT statement. For the output shown, host_name is
7068
For additional information about setting passwords, see Section
7069
5.5.5, "Assigning Account Passwords." If you forget your root
7070
password after setting it, see Section C.5.4.1, "How to Reset the
7073
You might want to defer setting the passwords until later, to
7074
avoid the need to specify them while you perform additional setup
7816
7075
or testing. However, be sure to set them before using your
7817
7076
installation for production purposes.
7819
Anonymous Account Password Assignment
7821
To assign passwords to the anonymous accounts, connect to the
7822
server as root and then use either SET PASSWORD or UPDATE. In
7823
either case, be sure to encrypt the password using the PASSWORD()
7826
To use SET PASSWORD on Windows, do this:
7827
shell> mysql -u root
7828
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7829
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');
7831
To use SET PASSWORD on Unix, do this:
7832
shell> mysql -u root
7833
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7834
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
7836
In the second SET PASSWORD statement, replace host_name with the
7837
name of the server host. This is the name that is specified in the
7838
Host column of the non-localhost record for root in the user
7839
table. If you don't know what host name this is, issue the
7840
following statement before using SET PASSWORD:
7841
mysql> SELECT Host, User FROM mysql.user;
7843
Look for the record that has root in the User column and something
7844
other than localhost in the Host column. Then use that Host value
7845
in the second SET PASSWORD statement.
7847
Anonymous Account Removal
7849
If you prefer to remove the anonymous accounts instead, do so as
7851
shell> mysql -u root
7852
mysql> DROP USER '';
7854
The DROP statement applies both to Windows and to Unix. On
7855
Windows, if you want to remove only the anonymous account that has
7856
the same privileges as root, do this instead:
7857
shell> mysql -u root
7858
mysql> DROP USER ''@'localhost';
7860
That account allows anonymous access but has full privileges, so
7861
removing it improves security.
7863
root Account Password Assignment
7865
You can assign passwords to the root accounts in several ways. The
7866
following discussion demonstrates three methods:
7078
To set up additional accounts, see Section 5.5.2, "Adding User
7081
Assigning root Account Passwords
7083
The root account passwords can be set several ways. The following
7084
discussion demonstrates three methods:
7868
7086
* Use the SET PASSWORD statement
7088
* Use the UPDATE statement
7870
7090
* Use the mysqladmin command-line client program
7872
* Use the UPDATE statement
7874
7092
To assign passwords using SET PASSWORD, connect to the server as
7875
root and issue SET PASSWORD statements. Be sure to encrypt the
7876
password using the PASSWORD() function.
7093
root and issue a SET PASSWORD statement for each root account
7094
listed in the mysql.user table. Be sure to encrypt the password
7095
using the PASSWORD() function.
7878
7097
For Windows, do this:
7879
7098
shell> mysql -u root
7880
7099
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
7100
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('newpwd');
7881
7101
mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
7103
The last statement is unnecessary if the mysql.user table has no
7104
root account with a host value of %.
7883
7106
For Unix, do this:
7884
7107
shell> mysql -u root
7885
7108
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
7109
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('newpwd');
7886
7110
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
7888
In the second SET PASSWORD statement, replace host_name with the
7889
name of the server host. This is the same host name that you used
7890
when you assigned the anonymous account passwords.
7112
You can also use a single statement that assigns a password to all
7113
root accounts by using UPDATE to modify the mysql.user table
7114
directly. This method works on any platform:
7115
shell> mysql -u root
7116
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
7117
-> WHERE User = 'root';
7118
mysql> FLUSH PRIVILEGES;
7892
If the user table contains an account with User and Host values of
7893
'root' and '127.0.0.1', use an additional SET PASSWORD statement
7894
to set that account's password:
7895
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('newpwd');
7120
The FLUSH statement causes the server to reread the grant tables.
7121
Without it, the password change remains unnoticed by the server
7122
until you restart it.
7897
7124
To assign passwords to the root accounts using mysqladmin, execute
7898
7125
the following commands:
7899
7126
shell> mysqladmin -u root password "newpwd"
7900
7127
shell> mysqladmin -u root -h host_name password "newpwd"
7902
These commands apply both to Windows and to Unix. In the second
7903
command, replace host_name with the name of the server host. The
7904
double quotes around the password are not always necessary, but
7129
Those commands apply both to Windows and to Unix. The double
7130
quotation marks around the password are not always necessary, but
7905
7131
you should use them if the password contains spaces or other
7906
7132
characters that are special to your command interpreter.
7908
7134
The mysqladmin method of setting the root account passwords does
7909
not set the password for the 'root'@'127.0.0.1' account. To do so,
7910
use SET PASSWORD as shown earlier.
7912
You can also use UPDATE to modify the user table directly. The
7913
following UPDATE statement assigns a password to all root
7915
shell> mysql -u root
7916
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
7917
-> WHERE User = 'root';
7918
mysql> FLUSH PRIVILEGES;
7920
The UPDATE statement applies both to Windows and to Unix.
7922
After the passwords have been set, you must supply the appropriate
7923
password whenever you connect to the server. For example, if you
7924
want to use mysqladmin to shut down the server, you can do so
7135
not work for the 'root'@'127.0.0.1' account. Use the SET PASSWORD
7136
method shown earlier.
7138
After the root passwords have been set, you must supply the
7139
appropriate password whenever you connect as root to the server.
7140
For example, to shut down the server with mysqladmin, use this
7926
7142
shell> mysqladmin -u root -p shutdown
7927
7143
Enter password: (enter root password here)
7931
If you forget your root password after setting it up, Section
7932
B.5.4.1, "How to Reset the Root Password," covers the procedure
7935
To set up additional accounts, you can use the GRANT statement.
7936
For instructions, see Section 5.5.2, "Adding User Accounts."
7145
Assigning Anonymous Account Passwords
7147
The mysql commands in the following instructions include a -p
7148
option based on the assumption that you have set the root account
7149
passwords using the preceding instructions and must specify that
7150
password when connecting to the server.
7152
To assign passwords to the anonymous accounts, connect to the
7153
server as root, then use either SET PASSWORD or UPDATE. Be sure to
7154
encrypt the password using the PASSWORD() function.
7156
To use SET PASSWORD on Windows, do this:
7157
shell> mysql -u root -p
7158
Enter password: (enter root password here)
7159
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7161
To use SET PASSWORD on Unix, do this:
7162
shell> mysql -u root -p
7163
Enter password: (enter root password here)
7164
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7165
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
7167
To set the anonymous-user account passwords with a single UPDATE
7168
statement, do this (on any platform):
7169
shell> mysql -u root -p
7170
Enter password: (enter root password here)
7171
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
7173
mysql> FLUSH PRIVILEGES;
7175
The FLUSH statement causes the server to reread the grant tables.
7176
Without it, the password change remains unnoticed by the server
7177
until you restart it.
7179
Removing Anonymous Accounts
7181
If you prefer to remove any anonymous accounts rather than
7182
assigning them passwords, do so as follows on Windows:
7183
shell> mysql -u root -p
7184
Enter password: (enter root password here)
7185
mysql> DROP USER ''@'localhost';
7187
On Unix, remove the anonymous accounts like this:
7188
shell> mysql -u root -p
7189
Enter password: (enter root password here)
7190
mysql> DROP USER ''@'localhost';
7191
mysql> DROP USER ''@'host_name';
7193
Securing Test Databases
7195
By default, the mysql.db table contains rows that permit access by
7196
any user to the test database and other databases with names that
7197
start with test_. (These rows have an empty User column value,
7198
which for access-checking purposes matches any user name.) This
7199
means that such databases can be used even by accounts that
7200
otherwise possess no privileges. If you want to remove any-user
7201
access to test databases, do so as follows:
7202
shell> mysql -u root -p
7203
Enter password: (enter root password here)
7204
mysql> DELETE FROM mysql.db WHERE Db LIKE 'test%';
7205
mysql> FLUSH PRIVILEGES;
7207
The FLUSH statement causes the server to reread the grant tables.
7208
Without it, the privilege change remains unnoticed by the server
7209
until you restart it.
7211
With the preceding change, only users who have global database
7212
privileges or privileges granted explicitly for the test database
7213
can use it. However, if you do not want the database to exist at
7215
mysql> DROP DATABASE test;
7219
On Windows, you can also perform the process described in this
7220
section using the Configuration Wizard (see Section 2.3.4.11,
7221
"MySQL Server Instance Config Wizard: The Security Options
7222
Dialog"). On other platforms, the MySQL distribution includes
7223
mysql_secure_installation, a command-line utility that automates
7224
much of the process of securing a MySQL installation.
7226
2.13. Upgrading or Downgrading MySQL
7228
2.13.1. Upgrading MySQL
7230
As a general rule, to upgrade from one release series to another,
7231
you should go to the next series rather than skipping a series. To
7232
upgrade from a release series previous to MySQL 5.0, upgrade to
7233
each successive release series in turn until you have reached
7234
MySQL 5.0, and then proceed with the upgrade to MySQL 5.1. For
7235
example, if you currently are running MySQL 4.1 and wish to
7236
upgrade to a newer series, upgrade to MySQL 5.0 first before
7237
upgrading to 5.1, and so forth. For information on upgrading to
7238
MySQL 5.0, see the MySQL 5.0 Reference Manual; for earlier
7239
releases, see the MySQL 3.23, 4.0, 4.1 Reference Manual.
7241
If you perform a binary (in-place) upgrade without dumping and
7242
reloading tables, you cannot upgrade directly from MySQL 4.1 to
7243
5.1. This occurs due to an incompatible change in the MyISAM table
7244
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
7245
repair all MyISAM tables (see Section 2.13.4, "Rebuilding or
7246
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
7247
and check and repair your tables.
7249
To upgrade from MySQL 5.0 to 5.1, use the items in the following
7250
checklist as a guide:
7252
* Before any upgrade, back up your databases, including the
7253
mysql database that contains the grant tables. See Section
7254
6.2, "Database Backup Methods."
7256
* Read all the notes in Section 2.13.1.1, "Upgrading from MySQL
7257
5.0 to 5.1." These notes enable you to identify upgrade issues
7258
that apply to your current MySQL installation. Some
7259
incompatibilities discussed in that section require your
7260
attention before upgrading. Others should be dealt with after
7263
* Read Appendix D, "MySQL Change History" as well, which
7264
provides information about features that are new in MySQL 5.1
7265
or differ from those found in MySQL 5.0.
7267
* After upgrading to a new version of MySQL, run mysql_upgrade
7268
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
7269
Upgrade"). This program checks your tables, and attempts to
7270
repair them if necessary. It also updates your grant tables to
7271
make sure that they have the current structure so that you can
7272
take advantage of any new capabilities. (Some releases of
7273
MySQL introduce changes to the structure of the grant tables
7274
to add new privileges or features.)
7275
mysql_upgrade does not upgrade the contents of the help
7276
tables. For upgrade instructions, see Section 5.1.8,
7279
* If you run MySQL Server on Windows, see Section 2.3.7,
7280
"Upgrading MySQL Server on Microsoft Windows."
7282
* If you use replication, see Section 15.4.3, "Upgrading a
7283
Replication Setup," for information on upgrading your
7286
* If you upgrade an installation originally produced by
7287
installing multiple RPM packages, it is best to upgrade all
7288
the packages, not just some. For example, if you previously
7289
installed the server and client RPMs, do not upgrade just the
7292
* As of MySQL 5.1.9, the mysqld-max server is included in binary
7293
distributions. There is no separate MySQL-Max distribution. As
7294
of MySQL 5.1.12, there is no mysqld-max server at all in
7295
binary distributions. They contain a server that includes the
7296
features previously included in mysqld-max.
7298
* If you have created a user-defined function (UDF) with a given
7299
name and upgrade MySQL to a version that implements a new
7300
built-in function with the same name, the UDF becomes
7301
inaccessible. To correct this, use DROP FUNCTION to drop the
7302
UDF, and then use CREATE FUNCTION to re-create the UDF with a
7303
different nonconflicting name. The same is true if the new
7304
version of MySQL implements a built-in function with the same
7305
name as an existing stored function. See Section 8.2.4,
7306
"Function Name Parsing and Resolution," for the rules
7307
describing how the server interprets references to different
7310
You can always move the MySQL format files and data files between
7311
different versions on systems with the same architecture as long
7312
as you stay within versions for the same release series of MySQL.
7314
If you are cautious about using new versions, you can always
7315
rename your old mysqld before installing a newer one. For example,
7316
if you are using MySQL 5.0.13 and want to upgrade to 5.1.10,
7317
rename your current server from mysqld to mysqld-5.0.13. If your
7318
new mysqld then does something unexpected, you can simply shut it
7319
down and restart with your old mysqld.
7321
If, after an upgrade, you experience problems with compiled client
7322
programs, such as Commands out of sync or unexpected core dumps,
7323
you probably have used old header or library files when compiling
7324
your programs. In this case, you should check the date for your
7325
mysql.h file and libmysqlclient.a library to verify that they are
7326
from the new MySQL distribution. If not, recompile your programs
7327
with the new headers and libraries. Recompilation might also be
7328
necessary for programs compiled against the shared client library
7329
if the library major version number has changed (for example from
7330
libmysqlclient.so.15 to libmysqlclient.so.16.
7332
If problems occur, such as that the new mysqld server does not
7333
start or that you cannot connect without a password, verify that
7334
you do not have an old my.cnf file from your previous
7335
installation. You can check this with the --print-defaults option
7336
(for example, mysqld --print-defaults). If this command displays
7337
anything other than the program name, you have an active my.cnf
7338
file that affects server or client operation.
7340
If your MySQL installation contains a large amount of data that
7341
might take a long time to convert after an in-place upgrade, you
7342
might find it useful to create a "dummy" database instance for
7343
assessing what conversions might be needed and the work involved
7344
to perform them. Make a copy of your MySQL instance that contains
7345
a full copy of the mysql database, plus all other databases
7346
without data. Run your upgrade procedure on this dummy instance to
7347
see what actions might be needed so that you can better evaluate
7348
the work involved when performing actual data conversion on your
7349
original database instance.
7351
It is a good idea to rebuild and reinstall the Perl DBD::mysql
7352
module whenever you install a new release of MySQL. The same
7353
applies to other MySQL interfaces as well, such as PHP mysql
7354
extensions and the Python MySQLdb module.
7356
2.13.1.1. Upgrading from MySQL 5.0 to 5.1
7358
After upgrading a 5.0 installation to 5.0.10 or above, it is
7359
necessary to upgrade your grant tables. Otherwise, creating stored
7360
procedures and functions might not work. To perform this upgrade,
7364
It is good practice to back up your data before installing any new
7365
version of software. Although MySQL works very hard to ensure a
7366
high level of quality, you should protect your data by making a
7369
To upgrade to 5.1 from any previous version, MySQL recommends that
7370
you dump your tables with mysqldump before upgrading and reload
7371
the dump file after upgrading.
7373
If you perform a binary (in-place) upgrade without dumping and
7374
reloading tables, you cannot upgrade directly from MySQL 4.1 to
7375
5.1. This occurs due to an incompatible change in the MyISAM table
7376
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
7377
repair all MyISAM tables (see Section 2.13.4, "Rebuilding or
7378
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
7379
and check and repair your tables.
7381
In general, you should do the following when upgrading from MySQL
7384
* Read all the items in the following sections to see whether
7385
any of them might affect your applications:
7387
+ Section 2.13.1, "Upgrading MySQL," has general update
7390
+ The items in the change lists found later in this section
7391
enable you to identify upgrade issues that apply to your
7392
current MySQL installation.
7394
+ The MySQL 5.1 change history describes significant new
7395
features you can use in 5.1 or that differ from those
7396
found in MySQL 5.0. Some of these changes may result in
7397
incompatibilities. See Section D.1, "Changes in Release
7398
5.1.x (Production)."
7399
Note particularly any changes that are marked Known issue or
7400
Incompatible change. These incompatibilities with earlier
7401
versions of MySQL may require your attention before you
7402
upgrade. Our aim is to avoid these changes, but occasionally
7403
they are necessary to correct problems that would be worse
7404
than an incompatibility between releases. If any upgrade issue
7405
applicable to your installation involves an incompatibility
7406
that requires special handling, follow the instructions given
7407
in the incompatibility description. Often this will involve
7408
dumping and reloading tables, or use of a statement such as
7409
CHECK TABLE or REPAIR TABLE.
7410
For dump and reload instructions, see Section 2.13.4,
7411
"Rebuilding or Repairing Tables or Indexes." Any procedure
7412
that involves REPAIR TABLE with the USE_FRM option must be
7413
done before upgrading. Use of this statement with a version of
7414
MySQL different from the one used to create the table (that
7415
is, using it after upgrading) may damage the table. See
7416
Section 12.7.2.6, "REPAIR TABLE Syntax."
7418
* Before upgrading to a new version of MySQL, Section 2.13.3,
7419
"Checking Whether Tables or Indexes Must Be Rebuilt," to see
7420
whether changes to table formats or to character sets or
7421
collations were made between your current version of MySQL and
7422
the version to which you are upgrading. If so and these
7423
changes result in an incompatibility between MySQL versions,
7424
you will need to upgrade the affected tables using the
7425
instructions in Section 2.13.4, "Rebuilding or Repairing
7428
* After upgrading to a new version of MySQL, run mysql_upgrade
7429
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
7430
Upgrade"). This program checks your tables, and attempts to
7431
repair them if necessary. It also updates your grant tables to
7432
make sure that they have the current structure so that you can
7433
take advantage of any new capabilities. (Some releases of
7434
MySQL introduce changes to the structure of the grant tables
7435
to add new privileges or features.)
7436
mysql_upgrade does not upgrade the contents of the help
7437
tables. For upgrade instructions, see Section 5.1.8,
7440
* If you run MySQL Server on Windows, see Section 2.3.7,
7441
"Upgrading MySQL Server on Microsoft Windows."
7443
* If you use replication, see Section 15.4.3, "Upgrading a
7444
Replication Setup," for information on upgrading your
7447
If your MySQL installation contains a large amount of data that
7448
might take a long time to convert after an in-place upgrade, you
7449
might find it useful to create a "dummy" database instance for
7450
assessing what conversions might be needed and the work involved
7451
to perform them. Make a copy of your MySQL instance that contains
7452
a full copy of the mysql database, plus all other databases
7453
without data. Run your upgrade procedure on this dummy instance to
7454
see what actions might be needed so that you can better evaluate
7455
the work involved when performing actual data conversion on your
7456
original database instance.
7458
The following lists describe changes that may affect applications
7459
and that you should watch out for when upgrading from MySQL 5.0 to
7462
Configuration Changes
7465
* Before MySQL 5.1.11, to build MySQL from source with SSL
7466
support enabled, you would invoke configure with either the
7467
--with-openssl or --with-yassl option. In MySQL 5.1.11, those
7468
options both have been replaced by the --with-ssl option. By
7469
default, --with-ssl causes the bundled yaSSL library to be
7470
used. To select OpenSSL instead, give the option as
7471
--with-ssl=path, where path is the directory where the OpenSSL
7472
header files and libraries are located.
7477
* Known issue: mysql_upgrade attempts to to upgrade tables that
7478
are incompatible with the current version of MySQL. (It
7479
invokes mysqlcheck to check tables and, if necessary, repair
7480
them.) However this can fail for storage engines that do not
7481
support REPAIR TABLE, such as InnoDB, and leave tables in a
7482
nonupgradable state.
7483
To work around this problem, use ALTER TABLE tbl_name
7484
ENGINE=InnoDB to perform a "null" alter operation that
7487
* Known issue: After a binary upgrade to MySQL 5.1 from a MySQL
7488
5.0 installation that contains ARCHIVE tables:
7490
+ Before MySQL 5.1.42, accessing those tables will cause
7491
the server to crash, even if you have run mysql_upgrade
7492
or CHECK TABLE ... FOR UPGRADE.
7494
+ As of MySQL 5.1.42, the server will not open 5.0 ARCHIVE
7496
In either case, the solution is to use mysqldump to dump all
7497
5.0 ARCHIVE tables before upgrading, and reload them into
7498
MySQL 5.1 after upgrading. This problem is fixed in MySQL
7499
5.6.4: The server can open ARCHIVE tables created in MySQL
7500
5.0. However, it remains the recommended upgrade procedure to
7501
dump 5.0 ARCHIVE tables before upgrading and reload them after
7504
* Known issue: The fix for Bug #23491 introduced a problem with
7505
SHOW CREATE VIEW, which is used by mysqldump. This causes an
7506
incompatibility when upgrading from versions affected by that
7507
bug fix (MySQL 5.0.40 through 5.0.43, MySQL 5.1.18 through
7508
5.1.19): If you use mysqldump before upgrading from an
7509
affected version and reload the data after upgrading to a
7510
higher version, you must drop and recreate your views.
7512
* Known issue: Dumps performed by using mysqldump to generate a
7513
dump file before the upgrade and reloading the file after
7514
upgrading are subject to the following problem:
7515
Before MySQL 5.0.40, mysqldump displays SPATIAL index
7516
definitions using prefix lengths for the indexed columns.
7517
These prefix lengths are accepted in MySQL 5.0, but not as of
7518
MySQL 5.1. If you use mysqldump from versions of MySQL older
7519
than 5.0.40, any table containing SPATIAL indexes will cause
7520
an error when the dump file is reloaded into MySQL 5.1 or
7522
For example, a table definition might look like this when
7523
dumped in MySQL 5.0:
7525
`g` geometry NOT NULL,
7526
SPATIAL KEY `g` (`g`(32))
7527
) ENGINE=MyISAM DEFAULT CHARSET=latin1
7528
The SPATIAL index definition will not be accepted in MySQL
7529
5.1. To work around this, edit the dump file to remove the
7532
`g` geometry NOT NULL,
7533
SPATIAL KEY `g` (`g`)
7534
) ENGINE=MyISAM DEFAULT CHARSET=latin1
7535
Dump files can be large, so it may be preferable to dump table
7536
definitions and data separately to make it easier to edit the
7538
shell> mysqldump --no-data other_args > definitions.sql
7539
shell> mysqldump --no-create-info other_args > data.sql
7540
Then edit definitions.sql before reloading definitions.sql and
7541
data.sql, in that order.
7542
If you upgrade to a version of MySQL 5.0 higher than 5.0.40
7543
before upgrading to MySQL 5.1, this problem does not occur.
7545
* Known issue: Before MySQL 5.1.30, the CHECK TABLE ... FOR
7546
UPGRADE statement did not check for incompatible collation
7547
changes made in MySQL 5.1.24. (This also affects mysqlcheck
7548
and mysql_upgrade, which cause that statement to be executed.)
7549
Prior to the fix made in 5.1.30, a binary upgrade (performed
7550
without dumping tables with mysqldump before the upgrade and
7551
reloading the dump file after the upgrade) would corrupt
7552
tables. After the fix, CHECK TABLE ... FOR UPGRADE properly
7553
detects the problem and warns about tables that need repair.
7554
However, the fix is not backward compatible and can result in
7555
a downgrading problem under these circumstances:
7557
1. Perform a binary upgrade to a version of MySQL that
7560
2. Run CHECK TABLE ... FOR UPGRADE (or mysqlcheck or
7561
mysql_upgrade) to upgrade tables.
7563
3. Perform a binary downgrade to a version of MySQL that
7564
does not include the fix.
7565
The solution is to dump tables with mysqldump before the
7566
downgrade and reload the dump file after the downgrade.
7567
Alternatively, drop and recreate affected indexes.
7569
* Known issue: MySQL introduces encoding for table names that
7570
have non-ASCII characters (see Section 8.2.3, "Mapping of
7571
Identifiers to File Names"). After a binary upgrade from MySQL
7572
5.0 to 5.1 or higher, the server recognizes names that have
7573
non-ASCII characters and adds a #mysql50# prefix to them.
7574
As of MySQL 5.1.31, mysql_upgrade encodes these names by
7575
executing the following command:
7576
mysqlcheck --all-databases --check-upgrade --fix-db-names --fix-table
7578
Prior to MySQL 5.1.31, mysql_upgrade does not execute this
7579
command, so you should execute it manually if you have
7580
database or table names that contain nonalphanumeric
7582
Prior to MySQL 5.1.23, the mysqlcheck command does not perform
7583
the name encoding for views. To work around this problem, drop
7584
each affected view and recreate it.
7585
mysqlcheck cannot fix names that contain literal instances of
7586
the @ character that is used for encoding special characters.
7587
If you have databases or tables that contain this character,
7588
use mysqldump to dump them before upgrading to MySQL 5.1, and
7589
then reload the dump file after upgrading.
7591
* Known issue: When upgrading from MySQL 5.0 to versions of 5.1
7592
prior to 5.1.23, running mysqlcheck (or mysql_upgrade, which
7593
runs mysqlcheck) to upgrade tables fails for names that must
7594
be written as quoted identifiers. To work around this problem,
7595
rename each affected table to a name that does not require
7597
RENAME TABLE `tab``le_a` TO table_a;
7598
RENAME TABLE `table b` TO table_b;
7599
After renaming the tables, run the mysql_upgrade program. Then
7600
rename the tables back to their original names:
7601
RENAME TABLE table_a TO `tab``le_a`;
7602
RENAME TABLE table_b TO `table b`;
7604
* Known issue: In connection with view creation, the server
7605
created arc directories inside database directories and
7606
maintained useless copies of .frm files there. Creation and
7607
renaming procedures of those copies as well as creation of arc
7608
directories has been discontinued in MySQL 5.1.29.
7609
This change does cause a problem when downgrading to older
7610
server versions which manifests itself under these
7613
1. Create a view v_orig in MySQL 5.1.29 or higher.
7615
2. Rename the view to v_new and then back to v_orig.
7617
3. Downgrade to an older 5.1.x server and run mysql_upgrade.
7619
4. Try to rename v_orig to v_new again. This operation
7621
As a workaround to avoid this problem, use either of these
7624
+ Dump your data using mysqldump before downgrading and
7625
reload the dump file after downgrading.
7627
+ Instead of renaming a view after the downgrade, drop it
7630
* Incompatible change: As of MySQL 5.5.6, handling of CREATE
7631
TABLE IF NOT EXISTS ... SELECT statements has been changed for
7632
the case that the destination table already exists:
7634
+ Previously, for CREATE TABLE IF NOT EXISTS ... SELECT,
7635
MySQL produced a warning that the table exists, but
7636
inserted the rows and wrote the statement to the binary
7637
log anyway. By contrast, CREATE TABLE ... SELECT (without
7638
IF NOT EXISTS) failed with an error, but MySQL inserted
7639
no rows and did not write the statement to the binary
7642
+ MySQL now handles both statements the same way when the
7643
destination table exists, in that neither statement
7644
inserts rows or is written to the binary log. The
7645
difference between them is that MySQL produces a warning
7646
when IF NOT EXISTS is present and an error when it is
7648
This change in handling of IF NOT EXISTS results in an
7649
incompatibility for statement-based replication from a MySQL
7650
5.1 master with the original behavior and a MySQL 5.5 slave
7651
with the new behavior. Suppose that CREATE TABLE IF NOT EXISTS
7652
... SELECT is executed on the master and the destination table
7653
exists. The result is that rows are inserted on the master but
7654
not on the slave. (Row-based replication does not have this
7656
To address this issue, statement-based binary logging for
7657
CREATE TABLE IF NOT EXISTS ... SELECT is changed in MySQL 5.1
7660
+ If the destination table does not exist, there is no
7661
change: The statement is logged as is.
7663
+ If the destination table does exist, the statement is
7664
logged as the equivalent pair of CREATE TABLE IF NOT
7665
EXISTS and INSERT ... SELECT statements. (If the SELECT
7666
in the original statement is preceded by IGNORE or
7667
REPLACE, the INSERT becomes INSERT IGNORE or REPLACE,
7669
This change provides forward compatibility for statement-based
7670
replication from MySQL 5.1 to 5.5 because when the destination
7671
table exists, the rows will be inserted on both the master and
7672
slave. To take advantage of this compatibility measure, the
7673
5.1 server must be at least 5.1.51 and the 5.5 server must be
7675
To upgrade an existing 5.1-to-5.5 replication scenario,
7676
upgrade the master first to 5.1.51 or higher. Note that this
7677
differs from the usual replication upgrade advice of upgrading
7679
A workaround for applications that wish to achieve the
7680
original effect (rows inserted regardless of whether the
7681
destination table exists) is to use CREATE TABLE IF NOT EXISTS
7682
and INSERT ... SELECT statements rather than CREATE TABLE IF
7683
NOT EXISTS ... SELECT statements.
7684
Along with the change just described, the following related
7685
change was made: Previously, if an existing view was named as
7686
the destination table for CREATE TABLE IF NOT EXISTS ...
7687
SELECT, rows were inserted into the underlying base table and
7688
the statement was written to the binary log. As of MySQL
7689
5.1.51 and 5.5.6, nothing is inserted or logged.
7691
* Incompatible change: Prior to MySQL 5.1.51, if you flushed the
7692
logs using FLUSH LOGS or mysqladmin flush-logs and mysqld was
7693
writing the error log to a file (for example, if it was
7694
started with the --log-error option), it renames the current
7695
log file with the suffix -old, then created a new empty log
7696
file. This had the problem that a second log-flushing
7697
operation thus caused the original error log file to be lost
7698
unless you saved it under a different name. For example, you
7699
could use the following commands to save the file:
7700
shell> mysqladmin flush-logs
7701
shell> mv host_name.err-old backup-directory
7702
To avoid the preceding file-loss problem, no renaming occurs
7703
as of MySQL 5.1.51; the server merely closes and reopens the
7704
log file. To rename the file, you can do so manually before
7705
flushing. Then flushing the logs reopens a new file with the
7706
original file name. For example, you can rename the file and
7707
create a new one using the following commands:
7708
shell> mv host_name.err host_name.err-old
7709
shell> mysqladmin flush-logs
7710
shell> mv host_name.err-old backup-directory
7712
* Incompatible change: Character set or collation changes were
7713
made in MySQL 5.1.21, 5.1.23, and 5.1.24 that may require
7714
table indexes to be rebuilt. For details, see Section 2.13.3,
7715
"Checking Whether Tables or Indexes Must Be Rebuilt."
7717
* Incompatible change: MySQL 5.1 implements support for a plugin
7718
API that enables the loading and unloading of components at
7719
runtime, without restarting the server. Section 21.2, "The
7720
MySQL Plugin API." The plugin API requires the mysql.plugin
7721
table. After upgrading from an older version of MySQL, you
7722
should run the mysql_upgrade command to create this table. See
7723
Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
7725
Plugins are installed in the directory named by the plugin_dir
7726
system variable. This variable also controls the location from
7727
which the server loads user-defined functions (UDFs), which is
7728
a change from earlier versions of MySQL. That is, all UDF
7729
library files now must be installed in the plugin directory.
7730
When upgrading from an older version of MySQL, you must
7731
migrate your UDF files to the plugin directory.
7733
* Incompatible change: The table_cache system variable has been
7734
renamed to table_open_cache. Any scripts that refer to
7735
table_cache must be updated to use the new name.
7737
* Incompatible change: In MySQL 5.1.36, options for loading
7738
plugins such as pluggable storage engines were changed from
7739
boolean to tristate format. The implementations overlap, but
7740
if you previously used options of the form --plugin_name=0 or
7741
--plugin_name=1, you should instead use --plugin_name=OFF or
7742
--plugin_name=ON, respectively. For details, see Section
7743
5.1.7.1, "Installing and Uninstalling Plugins."
7745
* Incompatible change: From MySQL 5.1.24 to 5.1.31, the UPDATE
7746
statement was changed such that assigning NULL to a NOT NULL
7747
column caused an error even when strict SQL mode was not
7748
enabled. The original behavior before MySQL 5.1.24 was that
7749
such assignments caused an error only in strict SQL mode, and
7750
otherwise set the column to the implicit default value for the
7751
column data type and generated a warning. (For information
7752
about implicit default values, see Section 10.1.4, "Data Type
7754
The change caused compatibility problems for applications that
7755
relied on the original behavior. It also caused replication
7756
problems between servers that had the original behavior and
7757
those that did not, for applications that assigned NULL to NOT
7758
NULL columns in UPDATE statements without strict SQL mode
7759
enabled. The change was reverted in MySQL 5.1.32 so that
7760
UPDATE again had the original behavior. Problems can still
7761
occur if you replicate between servers that have the modified
7762
UPDATE behavior and those that do not.
7764
* Incompatible change: As of MySQL 5.1.29, the default binary
7765
logging mode has been changed from MIXED to STATEMENT for
7766
compatibility with MySQL 5.0.
7768
* Incompatible change: In MySQL 5.1.25, a change was made to the
7769
way that the server handles prepared statements. This affects
7770
prepared statements processed at the SQL level (using the
7771
PREPARE statement) and those processed using the binary
7772
client/server protocol (using the mysql_stmt_prepare() C API
7774
Previously, changes to metadata of tables or views referred to
7775
in a prepared statement could cause a server crash when the
7776
statement was next executed, or perhaps an error at execute
7777
time with a crash occurring later. For example, this could
7778
happen after dropping a table and recreating it with a
7779
different definition.
7780
Now metadata changes to tables or views referred to by
7781
prepared statements are detected and cause automatic
7782
repreparation of the statement when it is next executed.
7783
Metadata changes occur for DDL statements such as those that
7784
create, drop, alter, rename, or truncate tables, or that
7785
analyze, optimize, or repair tables. Repreparation also occurs
7786
after referenced tables or views are flushed from the table
7787
definition cache, either implicitly to make room for new
7788
entries in the cache, or explicitly due to FLUSH TABLES.
7789
Repreparation is automatic, but to the extent that it occurs,
7790
performance of prepared statements is diminished.
7791
Table content changes (for example, with INSERT or UPDATE) do
7792
not cause repreparation, nor do SELECT statements.
7793
An incompatibility with previous versions of MySQL is that a
7794
prepared statement may now return a different set of columns
7795
or different column types from one execution to the next. For
7796
example, if the prepared statement is SELECT * FROM t1,
7797
altering t1 to contain a different number of columns causes
7798
the next execution to return a number of columns different
7799
from the previous execution.
7800
Older versions of the client library cannot handle this change
7801
in behavior. For applications that use prepared statements
7802
with the new server, an upgrade to the new client library is
7803
strongly recommended.
7804
Along with this change to statement repreparation, the default
7805
value of the table_definition_cache system variable has been
7806
increased from 128 to 256. The purpose of this increase is to
7807
lessen the chance that prepared statements will need
7808
repreparation due to referred-to tables/views having been
7809
flushed from the cache to make room for new entries.
7810
A new status variable, Com_stmt_reprepare, has been introduced
7811
to track the number of repreparations.
7813
* Incompatible change: The -, *, and / operators and the
7814
functions POW() and EXP() could misbehave when used with
7815
floating-point numbers. Previously they might return +INF,
7816
-INF, or NaN in cases of numeric overflow (including that
7817
caused by division by zero) or when invalid arguments were
7818
used. As of MySQL 5.1.24, NULL is returned in all such cases.
7820
* Incompatible change: As of MySQL 5.1.23, within a stored
7821
routine, it is no longer permissible to declare a cursor for a
7822
SHOW or DESCRIBE statement. This happened to work in some
7823
instances, but is no longer supported. In many cases, a
7824
workaround for this change is to use the cursor with a SELECT
7825
query to read from an INFORMATION_SCHEMA table that produces
7826
the same information as the SHOW statement.
7828
* Incompatible change: SHOW CREATE VIEW displays view
7829
definitions using an AS alias_name clause for each column. If
7830
a column is created from an expression, the default alias is
7831
the expression text, which can be quite long. As of MySQL
7832
5.1.23, aliases for column names in CREATE VIEW statements are
7833
checked against the maximum column length of 64 characters
7834
(not the maximum alias length of 256 characters). As a result,
7835
views created from the output of SHOW CREATE VIEW fail if any
7836
column alias exceeds 64 characters. This can cause problems
7837
for replication or loading dump files. For additional
7838
information and workarounds, see Section E.4, "Restrictions on
7841
* Incompatible change: Several issues were identified for stored
7842
programs (stored procedures and functions, triggers, and
7843
events) and views containing non-ASCII symbols. These issues
7844
involved conversion errors due to incomplete character set
7845
information when translating these objects to and from stored
7847
To address these problems, the representation for these
7848
objects was changed in MySQL 5.1.21. However, the fixes affect
7849
all stored programs and views. (For example, you will see
7850
warnings about "no creation context.") To avoid warnings from
7851
the server about the use of old definitions from any release
7852
prior to 5.1.21, you should dump stored programs and views
7853
with mysqldump after upgrading to 5.1.21 or higher, and then
7854
reload them to recreate them with new definitions. Invoke
7855
mysqldump with a --default-character-set option that names the
7856
non-ASCII character set that was used for the definitions when
7857
the objects were originally created.
7858
Upgrading for triggers in particular must be handled
7859
carefully, for two reasons:
7861
+ The output from mysqldump does not contain a DROP TRIGGER
7862
statement preceding each CREATE TRIGGER statement, so
7863
reloading the dump file will fail to re-create the
7864
triggers unless you manually drop them after generating
7865
the dump file and before reloading it.
7867
+ If you are upgrading from a very old version of MySQL 5.0
7868
(before 5.0.10), the trigger upgrade procedure is
7869
different because triggers for those versions were
7870
created using a different namespace (trigger names had to
7871
be unique per table, rather than per schema as is true
7872
now). For instructions on upgrading triggers from old 5.0
7873
versions, see Upgrading from MySQL 4.1 to 5.0
7874
(http://dev.mysql.com/doc/refman/5.0/en/upgrading-from-pr
7875
evious-series.html).
7876
Assuming that you are upgrading from MySQL 5.0.10 to 5.1.20 to
7877
MySQL 5.1.21 or later, use the following procedure to upgrade
7880
+ Use mysqldump to generate a dump file that contains the
7881
trigger definitions:
7882
mysqldump --triggers--no-create-db --no-data
7883
--no-create-info --all-databases > triggers.sql
7884
You might need to add options to specify connection
7885
parameters, such as --user or --password. Also, if you
7886
are updating from a version of MySQL 5.1 older than
7887
5.1.21, you may need to include a --default-character-set
7888
option that specifies the non-ASCII character set that
7889
was used for the definitions when the triggers were
7891
Otherwise, invoke mysqldump with exactly the preceding
7892
options to avoid generating a dump file that will not
7893
have the intended effect when reloaded. For example, if
7894
you omit the --no-create-db option, your databases will
7895
be removed and recreated with no contents when you reload
7898
+ Drop existing triggers. To see which triggers exist, use
7900
SELECT TRIGGER_SCHEMA, EVENT_OBJECT_TABLE, TRIGGER_NAME
7901
FROM INFORMATION_SCHEMA.TRIGGERS;
7902
To generate DROP TRIGGERS statements for the triggers,
7904
SELECT CONCAT('DROP TRIGGER ', TRIGGER_SCHEMA, '.', TRIGGER_NAME, ';'
7906
FROM INFORMATION_SCHEMA.TRIGGERS
7907
INTO OUTFILE '/tmp/drop_triggers.sql';
7908
The statement uses INTO OUTFILE, so you must have the
7909
FILE privilege. The file will be created on the server
7910
host. Use a different file name if you like. To be 100%
7911
safe, inspect the trigger definitions in the
7912
drop_triggers.sql file, and perhaps make a backup of the
7913
file. Then execute the statements in the file:
7914
mysql --force < /tmp/drop_triggers.sql
7916
+ Recreate the triggers by reloading the dump file created
7918
mysql --force < triggers.sql
7920
* Incompatible change: As of MySQL 5.1.20, mysqld_safe supports
7921
error logging to syslog on systems that support the logger
7922
command. The new --syslog and --skip-syslog options can be
7923
used instead of the --log-error option to control logging
7924
behavior, as described in Section 4.3.2, "mysqld_safe ---
7925
MySQL Server Startup Script."
7926
In 5.1.21 and up, the default is --skip-syslog, which is
7927
compatible with the default behavior of writing an error log
7928
file for releases prior to 5.1.20.
7929
In 5.1.20 only, the following conditions apply: 1) The default
7930
is to use syslog, which is not compatible with releases prior
7931
to 5.1.20. 2) Logging to syslog may fail to operate correctly
7932
in some cases. For these reasons, avoid using MySQL 5.1.20.
7934
* Incompatible change: As of MySQL 5.1.18, the plugin interface
7935
and its handling of system variables was changed. Command-line
7936
options such as --skip-innodb now cause an error if InnoDB is
7937
not built-in or plugin-loaded. You should use
7938
--loose-skip-innodb if you do not want any error even if
7939
InnoDB is not available. The --loose prefix modifier should be
7940
used for all command-line options where you are uncertain
7941
whether the plugin exists and when you want the operation to
7942
proceed even if the option is necessarily ignored due to the
7943
absence of the plugin. (For a desecription of how --loose
7944
works, see Section 4.2.3.1, "Using Options on the Command
7947
* Incompatible change: As of MySQL 5.1.15, InnoDB rolls back
7948
only the last statement on a transaction timeout. A new
7949
option, --innodb_rollback_on_timeout, causes InnoDB to abort
7950
and roll back the entire transaction if a transaction timeout
7951
occurs (the same behavior as in MySQL 4.1).
7953
* Incompatible change: As of MySQL 5.1.15, the following
7954
conditions apply to enabling the read_only system variable:
7956
+ If you attempt to enable read_only while you have any
7957
explicit locks (acquired with LOCK TABLES or have a
7958
pending transaction, an error will occur.
7960
+ If other clients hold explicit table locks or have
7961
pending transactions, the attempt to enable read_only
7962
blocks until the locks are released and the transactions
7963
end. While the attempt to enable read_only is pending,
7964
requests by other clients for table locks or to begin
7965
transactions also block until read_only has been set.
7967
+ read_only can be enabled while you hold a global read
7968
lock (acquired with FLUSH TABLES WITH READ LOCK) because
7969
that does not involve table locks.
7970
Previously, the attempt to enable read_only would return
7971
immediately even if explicit locks or transactions were
7972
pending, so some data changes could occur for statements
7973
executing in the server at the same time.
7975
* Incompatible change: The number of function names affected by
7976
IGNORE_SPACE was reduced significantly in MySQL 5.1.13, from
7977
about 200 to about 30. (For details about IGNORE_SPACE, see
7978
Section 8.2.4, "Function Name Parsing and Resolution.") This
7979
change improves the consistency of parser operation. However,
7980
it also introduces the possibility of incompatibility for old
7981
SQL code that relies on the following conditions:
7983
+ IGNORE_SPACE is disabled.
7985
+ The presence or absence of whitespace following a
7986
function name is used to distinguish between a built-in
7987
function and stored function that have the same name (for
7988
example, PI() versus PI ()).
7989
For functions that are no longer affected by IGNORE_SPACE as
7990
of MySQL 5.1.13, that strategy no longer works. Either of the
7991
following approaches can be used if you have code that is
7992
subject to the preceding incompatibility:
7994
+ If a stored function has a name that conflicts with a
7995
built-in function, refer to the stored function with a
7996
schema name qualifier, regardless of whether whitespace
7997
is present. For example, write schema_name.PI() or
8000
+ Alternatively, rename the stored function to use a
8001
nonconflicting name and change invocations of the
8002
function to use the new name.
8004
* Incompatible change: For utf8 columns, the full-text parser
8005
incorrectly considered several nonword punctuation and
8006
whitespace characters as word characters, causing some
8007
searches to return incorrect results. The fix involves a
8008
change to the full-text parser in MySQL 5.1.12, so as of
8009
5.1.12, any tables that have FULLTEXT indexes on utf8 columns
8010
must be repaired with REPAIR TABLE:
8011
REPAIR TABLE tbl_name QUICK;
8013
* Incompatible change: Storage engines can be pluggable at
8014
runtime, so the distinction between disabled and invalid
8015
storage engines no longer applies. As of MySQL 5.1.12, this
8016
affects the NO_ENGINE_SUBSTITUTION SQL mode, as described in
8017
Section 5.1.6, "Server SQL Modes."
8019
* Incompatible change: The structure of FULLTEXT indexes has
8020
been changed in MySQL 5.1.6. After upgrading to MySQL 5.1.6 or
8021
greater, any tables that have FULLTEXT indexes must be
8022
repaired with REPAIR TABLE:
8023
REPAIR TABLE tbl_name QUICK;
8025
* Incompatible change: In MySQL 5.1.6, when log tables were
8026
implemented, the default log destination for the general query
8027
and slow query log was TABLE. As of MySQL 5.1.21, this default
8028
has been changed to FILE, which is compatible with MySQL 5.0,
8029
but incompatible with earlier releases of MySQL 5.1. If you
8030
are upgrading from MySQL 5.0 to 5.1.21 or higher, no logging
8031
option changes should be necessary. However, if you are
8032
upgrading from 5.1.6 through 5.1.20 to 5.1.21 or higher and
8033
were using TABLE logging, use the --log-output=TABLE option
8034
explicitly to preserve your server's table-logging behavior.
8036
* Incompatible change: In very old versions of MySQL (prior to
8037
4.1), the TIMESTAMP data type supported a display width, which
8038
was silenty ignored beginning with MySQL 4.1. This is
8039
deprecated in MySQL 5.1, and removed altogether in MySQL 5.5.
8040
These changes in behavior can lead to two problem scenarios
8041
when trying to use TIMESTAMP(N) columns with a MySQL 5.5 or
8044
+ When importing a dump file (for example, one created
8045
using mysqldump) created in a MySQL 5.0 or earlier server
8046
into a server from a newer release series, a CREATE TABLE
8047
or ALTER TABLE statement containing TIMESTAMP(N) causes
8048
the import to fail with a syntax error.
8049
To fix this problem, edit the dump file in a text editor
8050
to replace any instances of TIMESTAMP(N) with TIMESTAMP
8051
prior to importing the file. Be sure to use a plain text
8052
editor for this, and not a word processor; otherwise, the
8053
result is almost certain to be unusable for importing
8054
into the MySQL server.
8056
+ When trying replicate any CREATE TABLE or ALTER TABLE
8057
statement containing TIMESTAMP(N) from a master MySQL
8058
server that supports the TIMESTAMP(N) syntax to a MySQL
8059
5.5.3 or newer slave, the statement causes replication to
8060
fail. Similarly, when you try to restore from a binary
8061
log written by a server that supports TIMESTAMP(N) to a
8062
MySQL 5.5.3 or newer server, any CREATE TABLE or ALTER
8063
TABLE statement containing TIMESTAMP(N) causes the backup
8064
to fail. This holds true regardless of the logging
8066
It may be possible to fix such issues using a hex editor,
8067
by replacing any width arguments used with TIMESTAMP, and
8068
the parentheses containing them, with space characters
8069
(hexadecimal 20). Be sure to use a programmer's binary
8070
hex editor and not a regular text editor or word
8071
processor for this; otherwise, the result is almost
8072
certain to be a corrupted binary log file. To guard
8073
against accidental corruption of the binary log, you
8074
should always work on a copy of the file rather than the
8076
You should try to handle potential issues of these types
8077
proactively by updating with ALTER TABLE any TIMESTAMP(N)
8078
columns in your databases so that they use TIMESTAMP instead,
8079
before performing any upgrades.
8081
* Incompatible change: For ENUM columns that had enumeration
8082
values containing commas, the commas were mapped to 0xff
8083
internally. However, this rendered the commas
8084
indistinguishable from true 0xff characters in the values.
8085
This no longer occurs. However, the fix requires that you dump
8086
and reload any tables that have ENUM columns containing true
8087
0xff in their values: Dump the tables using mysqldump with the
8088
current server before upgrading from a version of MySQL 5.1
8089
older than 5.1.15 to version 5.1.15 or newer.
8091
* As of MySQL 5.1.12, the lc_time_names system variable
8092
specifies the locale that controls the language used to
8093
display day and month names and abbreviations. This variable
8094
affects the output from the DATE_FORMAT(), DAYNAME() and
8095
MONTHNAME() functions. See Section 9.7, "MySQL Server Locale
8098
* As of MySQL 5.1.9, mysqld_safe no longer implicitly invokes
8099
mysqld-max if it exists. Instead, it invokes mysqld unless a
8100
--mysqld or --mysqld-version option is given to specify
8101
another server explicitly. If you previously relied on the
8102
implicit invocation of mysqld-max, you should use an
8103
appropriate option now. As of MySQL 5.1.12, there is no longer
8104
any separate mysqld-max server, so no change should be
8110
* Known issue: Prior to MySQL 5.1.17, the parser accepted
8111
invalid code in SQL condition handlers, leading to server
8112
crashes or unexpected execution behavior in stored programs.
8113
Specifically, the parser permitted a condition handler to
8114
refer to labels for blocks that enclose the handler
8115
declaration. This was incorrect because block label scope does
8116
not include the code for handlers declared within the labeled
8118
As of 5.1.17, the parser rejects this invalid construct, but
8119
if you perform a binary upgrade (without dumping and reloading
8120
your databases), existing handlers that contain the construct
8121
still are invalid and should be rewritten even if they appear
8122
to function as you expect.
8123
To find affected handlers, use mysqldump to dump all stored
8124
procedures and functions, triggers, and events. Then attempt
8125
to reload them into an upgraded server. Handlers that contain
8126
illegal label references will be rejected.
8127
For more information about condition handlers and writing them
8128
to avoid invalid jumps, see Section 12.6.7.2, "DECLARE ...
8131
* Incompatible change: The parser accepted statements that
8132
contained /* ... */ that were not properly closed with */,
8133
such as SELECT 1 /* + 2. As of MySQL 5.1.23, statements that
8134
contain unclosed /*-comments now are rejected with a syntax
8136
This fix has the potential to cause incompatibilities. Because
8137
of Bug #26302, which caused the trailing */ to be truncated
8138
from comments in views, stored routines, triggers, and events,
8139
it is possible that objects of those types may have been
8140
stored with definitions that now will be rejected as
8141
syntactically invalid. Such objects should be dropped and
8142
re-created so that their definitions do not contain truncated
8145
* Incompatible change: Multiple-table DELETE statements
8146
containing ambiguous aliases could have unintended side
8147
effects such as deleting rows from the wrong table. Examples:
8148
DELETE FROM t1 AS a2 USING t1 AS a1 INNER JOIN t2 AS a2;
8149
DELETE t1 AS a2 FROM t1 AS a1 INNER JOIN t2 AS a2;
8150
To avoid ambiguity, declaration of aliases other than in the
8151
table_references part of the statement should be avoided:
8152
DELETE FROM t1 USING t1 AS a1 INNER JOIN t2 AS a2;
8153
DELETE t1 FROM t1 AS a1 INNER JOIN t2 AS a2;
8154
As of MySQL 5.1.23, alias declarations outside the
8155
table_references part of the statement are disallowed for the
8156
USING variant of multiple-table DELETE syntax. (In MySQL 5.5,
8157
alias declarations outside table_references are disallowed for
8158
all multiple-table DELETE statements.) Statements containing
8159
aliases that are no longer permitted must be rewritten.
8161
* Incompatible change: As of MySQL 5.1.8, TYPE = engine_name is
8162
still accepted as a synonym for the ENGINE = engine_name table
8163
option but generates a warning. You should note that this
8164
option is not available in MySQL 5.1.7, and is removed
8165
altogether in MySQL 5.5 and produces a syntax error.
8166
TYPE has been deprecated since MySQL 4.0.
8168
* Incompatible change: MySQL 5.1.6 introduces the TRIGGER
8169
privilege. Previously, the SUPER privilege was needed to
8170
create or drop triggers. Now those operations require the
8171
TRIGGER privilege. This is a security improvement because you
8172
no longer need to grant users the SUPER privilege to enable
8173
them to create triggers. However, the requirement that the
8174
account named in a trigger's DEFINER clause must have the
8175
SUPER privilege has changed to a requirement for the TRIGGER
8176
privilege. When upgrading from a previous version of MySQL 5.0
8177
or 5.1 to MySQL 5.1.6 or newer, be sure to update your grant
8178
tables by running mysql_upgrade. This will assign the TRIGGER
8179
privilege to all accounts that had the SUPER privilege. If you
8180
fail to update the grant tables, triggers may fail when
8181
activated. After updating the grant tables, you can revoke the
8182
SUPER privilege from those accounts that no longer otherwise
8185
* Some keywords may be reserved in MySQL 5.1 that were not
8186
reserved in MySQL 5.0. See Section 8.3, "Reserved Words."
8188
* The BACKUP TABLE, and RESTORE TABLE statements are deprecated.
8189
mysqldump or mysqlhotcopy can be used as alternatives.
8191
* The LOAD DATA FROM MASTER and LOAD TABLE FROM MASTER
8192
statements are deprecated. See Section 12.4.2.2, "LOAD DATA
8193
FROM MASTER Syntax," for recommended alternatives.
8195
* The INSTALL PLUGIN and UNINSTALL PLUGIN statements that are
8196
used for the plugin API are new. So is the WITH PARSER clause
8197
for FULLTEXT index creation that associates a parser plugin
8198
with a full-text index. Section 21.2, "The MySQL Plugin API."
8203
* Incompatible change: As of MySQL 5.1.7, the
8204
mysql_stmt_attr_get() C API function returns a boolean rather
8205
than an unsigned int for STMT_ATTR_UPDATE_MAX_LENGTH. (Bug
8208
2.13.2. Downgrading MySQL
8210
This section describes what you should do to downgrade to an older
8211
MySQL version in the unlikely case that the previous version
8212
worked better than the new one.
8214
If you are downgrading within the same release series (for
8215
example, from 5.0.13 to 5.0.12) the general rule is that you just
8216
have to install the new binaries on top of the old ones. There is
8217
no need to do anything with the databases. As always, however, it
8218
is always a good idea to make a backup.
8220
The following items form a checklist of things you should do
8221
whenever you perform a downgrade:
8223
* Read the upgrading section for the release series from which
8224
you are downgrading to be sure that it does not have any
8225
features you really need. See Section 2.13.1, "Upgrading
8228
* If there is a downgrading section for that version, you should
8231
* To see which new features were added between the version to
8232
which you are downgrading and your current version, see the
8233
change logs (Appendix D, "MySQL Change History").
8235
* Check Section 2.13.3, "Checking Whether Tables or Indexes Must
8236
Be Rebuilt," to see whether changes to table formats or to
8237
character sets or collations were made between your current
8238
version of MySQL and the version to which you are downgrading.
8239
If so and these changes result in an incompatibility between
8240
MySQL versions, you will need to downgrade the affected tables
8241
using the instructions in Section 2.13.4, "Rebuilding or
8242
Repairing Tables or Indexes."
8244
In most cases, you can move the MySQL format files and data files
8245
between different versions on the same architecture as long as you
8246
stay within versions for the same release series of MySQL.
8248
If you downgrade from one release series to another, there may be
8249
incompatibilities in table storage formats. In this case, use
8250
mysqldump to dump your tables before downgrading. After
8251
downgrading, reload the dump file using mysql or mysqlimport to
8252
re-create your tables. For examples, see Section 2.13.5, "Copying
8253
MySQL Databases to Another Machine."
8255
A typical symptom of a downward-incompatible table format change
8256
when you downgrade is that you cannot open tables. In that case,
8257
use the following procedure:
8259
1. Stop the older MySQL server that you are downgrading to.
8261
2. Restart the newer MySQL server you are downgrading from.
8263
3. Dump any tables that were inaccessible to the older server by
8264
using mysqldump to create a dump file.
8266
4. Stop the newer MySQL server and restart the older one.
8268
5. Reload the dump file into the older server. Your tables should
8271
It might also be the case that system tables in the mysql database
8272
have changed and that downgrading introduces some loss of
8273
functionality or requires some adjustments. Here are some
8276
* Trigger creation requires the TRIGGER privilege as of MySQL
8277
5.1. In MySQL 5.0, there is no TRIGGER privilege and SUPER is
8278
required instead. If you downgrade from MySQL 5.1 to 5.0, you
8279
will need to give the SUPER privilege to those accounts that
8280
had the TRIGGER privilege in 5.1.
8282
* Triggers were added in MySQL 5.0, so if you downgrade from 5.0
8283
to 4.1, you cannot use triggers at all.
8285
* The mysql.proc.comment column definition changed between MySQL
8286
5.1 and 5.5. After a downgrade from 5.5 to 5.1, this table is
8287
seen as corrupt and in need of repair. To workaround this
8288
problem, execute mysql_upgrade from the version of MySQL to
8289
which you downgraded.
8291
2.13.2.1. Downgrading to MySQL 5.0
8293
When downgrading to MySQL 5.0 from MySQL 5.1, you should keep in
8294
mind the following issues relating to features found in MySQL 5.1,
8295
but not in MySQL 5.0:
8297
* Partitioning. MySQL 5.0 does not support user-defined
8298
partitioning. If a table was created as a partitioned table in
8299
5.1 (or if an table created in a previous version of MySQL was
8300
altered to include partitions after an upgrade to 5.1), the
8301
table is accessible after downgrade only if you do one of the
8304
+ Export the table using mysqldump and then drop it in
8305
MySQL 5.1; import the table again following the downgrade
8308
+ Prior to the downgrade, remove the table's partitioning
8309
using ALTER TABLE table_name REMOVE PARTITIONING.
8311
* Event Scheduler. MySQL 5.0 does not support scheduled events.
8312
If your databases contain scheduled event definitions, you
8313
should prevent them from being dumped when you use mysqldump
8314
by using the --skip-events option. (See Section 4.5.4,
8315
"mysqldump --- A Database Backup Program.")
8317
* Stored routines. MySQL 5.1.21 added a number of new columns
8318
to the mysql.proc table in which stored routine definitions
8319
are stored. If you are downgrading from MySQL 5.1.21 or later
8320
to MySQL 5.0, you cannot import the MySQL 5.1 routine
8321
definitions into MySQL 5.0.46 or earlier using the dump of
8322
mysql.proc created by mysqldump (such as when using the
8323
--all-databases option). Instead, you should run mysqldump
8324
--routines prior to performing the downgrade and run the
8325
stored routines DDL statements following the downgrade.
8326
See Bug #11986, Bug #30029, and Bug #30660, for more
8329
* Triggers. Trigger creation requires the TRIGGER privilege as
8330
of MySQL 5.1. In MySQL 5.0, there is no TRIGGER privilege and
8331
SUPER is required instead. If you downgrade from MySQL 5.1 to
8332
5.0, you will need to give the SUPER privilege to those
8333
accounts that had the TRIGGER privilege in 5.1.
8335
2.13.3. Checking Whether Tables or Indexes Must Be Rebuilt
8337
A binary upgrade or downgrade is one that installs one version of
8338
MySQL "in place" over an existing version, without dumping and
8341
1. Stop the server for the existing version if it is running.
8343
2. Install a different version of MySQL. This is an upgrade if
8344
the new version is higher than the original version, a
8345
downgrade if the version is lower.
8347
3. Start the server for the new version.
8349
In many cases, the tables from the previous version of MySQL can
8350
be used without problem by the new version. However, sometimes
8351
changes occur that require tables or table indexes to be rebuilt,
8352
as described in this section. If you have tables that are affected
8353
by any of the issues described here, rebuild the tables or indexes
8354
as necessary using the instructions given in Section 2.13.4,
8355
"Rebuilding or Repairing Tables or Indexes."
8357
Table Incompatibilities
8359
After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation
8360
that contains ARCHIVE tables:
8362
* Before MySQL 5.1.42, accessing those tables will cause the
8363
server to crash, even if you have run mysql_upgrade or CHECK
8364
TABLE ... FOR UPGRADE.
8366
* As of MySQL 5.1.42, the server will not open 5.0 ARCHIVE
8369
In either case, the solution is to use mysqldump to dump all 5.0
8370
ARCHIVE tables before upgrading, and reload them into MySQL 5.1
8371
after upgrading. This problem is fixed in MySQL 5.6.4: The server
8372
can open ARCHIVE tables created in MySQL 5.0. However, it remains
8373
the recommended upgrade procedure to dump 5.0 ARCHIVE tables
8374
before upgrading and reload them after upgrading.
8376
Index Incompatibilities
8378
If you perform a binary upgrade without dumping and reloading
8379
tables, you cannot upgrade directly from MySQL 4.1 to 5.1 or
8380
higher. This occurs due to an incompatible change in the MyISAM
8381
table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
8382
repair all MyISAM tables. Then upgrade from MySQL 5.0 to 5.1 and
8383
check and repair your tables.
8385
Modifications to the handling of character sets or collations
8386
might change the character sort order, which causes the ordering
8387
of entries in any index that uses an affected character set or
8388
collation to be incorrect. Such changes result in several possible
8391
* Comparison results that differ from previous results
8393
* Inability to find some index values due to misordered index
8396
* Misordered ORDER BY results
8398
* Tables that CHECK TABLE reports as being in need of repair
8400
The solution to these problems is to rebuild any indexes that use
8401
an affected character set or collation, either by dropping and
8402
re-creating the indexes, or by dumping and reloading the entire
8403
table. For information about rebuilding indexes, see Section
8404
2.13.4, "Rebuilding or Repairing Tables or Indexes."
8406
To check whether a table has indexes that must be rebuilt, consult
8407
the following list. It indicates which versions of MySQL
8408
introduced character set or collation changes that require indexes
8409
to be rebuilt. Each entry indicates the version in which the
8410
change occurred and the character sets or collations that the
8411
change affects. If the change is associated with a particular bug
8412
report, the bug number is given.
8414
The list applies both for binary upgrades and downgrades. For
8415
example, Bug #27877 was fixed in MySQL 5.1.24 and 5.4.0, so it
8416
applies to upgrades from versions older than 5.1.24 to 5.1.24 or
8417
newer, and to downgrades from 5.1.24 or newer to versions older
8420
In many cases, you can use CHECK TABLE ... FOR UPGRADE to identify
8421
tables for which index rebuilding is required. (It will report:
8422
Table upgrade required. Please do "REPAIR TABLE `tbl_name`" or
8423
dump/reload to fix it!) In these cases, you can also use
8424
mysqlcheck --check-upgrade or mysql_upgrade, which execute CHECK
8425
TABLE. However, the use of CHECK TABLE applies only after
8426
upgrades, not downgrades. Also, CHECK TABLE is not applicable to
8427
all storage engines. For details about which storage engines CHECK
8428
TABLE supports, see Section 12.7.2.3, "CHECK TABLE Syntax."
8430
Changes that cause index rebuilding to be necessary:
8432
* MySQL 5.0.48, 5.1.21 (Bug #29461)
8433
Affects indexes for columns that use any of these character
8434
sets: eucjpms, euc_kr, gb2312, latin7, macce, ujis
8435
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
8436
as of MySQL 5.1.29, 5.4.0 (see Bug #39585).
8438
* MySQL 5.0.48, 5.1.23 (Bug #27562)
8439
Affects indexes that use the ascii_general_ci collation for
8440
columns that contain any of these characters: '`' GRAVE
8441
ACCENT, '[' LEFT SQUARE BRACKET, '\' REVERSE SOLIDUS, ']'
8442
RIGHT SQUARE BRACKET, '~' TILDE
8443
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
8444
as of MySQL 5.1.29, 5.4.0 (see Bug #39585).
8446
* MySQL 5.1.24, 5.4.0 (Bug #27877)
8447
Affects indexes that use the utf8_general_ci or
8448
ucs2_general_ci collation for columns that contain 'Ć' LATIN
8449
SMALL LETTER SHARP S (German).
8450
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
8451
as of MySQL 5.1.30, 5.4.0 (see Bug #40053).
8453
2.13.4. Rebuilding or Repairing Tables or Indexes
8455
This section describes how to rebuild a table. This can be
8456
necessitated by changes to MySQL such as how data types are
8457
handled or changes to character set handling. For example, an
8458
error in a collation might have been corrected, necessitating a
8459
table rebuild to update the indexes for character columns that use
8460
the collation. (For examples, see Section 2.13.3, "Checking
8461
Whether Tables or Indexes Must Be Rebuilt.") It might also be that
8462
a table repair or upgrade should be done as indicated by a table
8463
check operation such as that performed by CHECK TABLE, mysqlcheck,
8466
Methods for rebuilding a table include dumping and reloading it,
8467
or using ALTER TABLE or REPAIR TABLE.
8470
If you are rebuilding tables because a different version of MySQL
8471
will not handle them after a binary (in-place) upgrade or
8472
downgrade, you must use the dump-and-reload method. Dump the
8473
tables before upgrading or downgrading using your original version
8474
of MySQL. Then reload the tables after upgrading or downgrading.
8476
If you use the dump-and-reload method of rebuilding tables only
8477
for the purpose of rebuilding indexes, you can perform the dump
8478
either before or after upgrading or downgrading. Reloading still
8479
must be done afterward.
8481
To rebuild a table by dumping and reloading it, use mysqldump to
8482
create a dump file and mysql to reload the file:
8483
shell> mysqldump db_name t1 > dump.sql
8484
shell> mysql db_name < dump.sql
8486
To rebuild all the tables in a single database, specify the
8487
database name without any following table name:
8488
shell> mysqldump db_name > dump.sql
8489
shell> mysql db_name < dump.sql
8491
To rebuild all tables in all databases, use the --all-databases
8493
shell> mysqldump --all-databases > dump.sql
8494
shell> mysql < dump.sql
8496
To rebuild a table with ALTER TABLE, use a "null" alteration; that
8497
is, an ALTER TABLE statement that "changes" the table to use the
8498
storage engine that it already has. For example, if t1 is a MyISAM
8499
table, use this statement:
8500
mysql> ALTER TABLE t1 ENGINE = MyISAM;
8502
If you are not sure which storage engine to specify in the ALTER
8503
TABLE statement, use SHOW CREATE TABLE to display the table
8506
If you must rebuild a table because a table checking operation
8507
indicates that the table is corrupt or needs an upgrade, you can
8508
use REPAIR TABLE if that statement supports the table's storage
8509
engine. For example, to repair a MyISAM table, use this statement:
8510
mysql> REPAIR TABLE t1;
8512
For storage engines such as InnoDB that REPAIR TABLE does not
8513
support, use mysqldump to create a dump file and mysql to reload
8514
the file, as described earlier.
8516
For specifics about which storage engines REPAIR TABLE supports,
8517
see Section 12.7.2.6, "REPAIR TABLE Syntax."
8519
mysqlcheck --repair provides command-line access to the REPAIR
8520
TABLE statement. This can be a more convenient means of repairing
8521
tables because you can use the --databases or --all-databases
8522
option to repair all tables in specific databases or all
8523
databases, respectively:
8524
shell> mysqlcheck --repair --databases db_name ...
8525
shell> mysqlcheck --repair --all-databases
8527
2.13.5. Copying MySQL Databases to Another Machine
8529
You can copy the .frm, .MYI, and .MYD files for MyISAM tables
8530
between different architectures that support the same
8531
floating-point format. (MySQL takes care of any byte-swapping
8532
issues.) See Section 13.5, "The MyISAM Storage Engine."
8534
In cases where you need to transfer databases between different
8535
architectures, you can use mysqldump to create a file containing
8536
SQL statements. You can then transfer the file to the other
8537
machine and feed it as input to the mysql client.
8539
Use mysqldump --help to see what options are available.
8541
The easiest (although not the fastest) way to move a database
8542
between two machines is to run the following commands on the
8543
machine on which the database is located:
8544
shell> mysqladmin -h 'other_hostname' create db_name
8545
shell> mysqldump db_name | mysql -h 'other_hostname' db_name
8547
If you want to copy a database from a remote machine over a slow
8548
network, you can use these commands:
8549
shell> mysqladmin create db_name
8550
shell> mysqldump -h 'other_hostname' --compress db_name | mysql db_na
8553
You can also store the dump in a file, transfer the file to the
8554
target machine, and then load the file into the database there.
8555
For example, you can dump a database to a compressed file on the
8556
source machine like this:
8557
shell> mysqldump --quick db_name | gzip > db_name.gz
8559
Transfer the file containing the database contents to the target
8560
machine and run these commands there:
8561
shell> mysqladmin create db_name
8562
shell> gunzip < db_name.gz | mysql db_name
8564
You can also use mysqldump and mysqlimport to transfer the
8565
database. For large tables, this is much faster than simply using
8566
mysqldump. In the following commands, DUMPDIR represents the full
8567
path name of the directory you use to store the output from
8570
First, create the directory for the output files and dump the
8572
shell> mkdir DUMPDIR
8573
shell> mysqldump --tab=DUMPDIR db_name
8575
Then transfer the files in the DUMPDIR directory to some
8576
corresponding directory on the target machine and load the files
8578
shell> mysqladmin create db_name # create database
8579
shell> cat DUMPDIR/*.sql | mysql db_name # create tables in databas
8581
shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables
8583
Do not forget to copy the mysql database because that is where the
8584
grant tables are stored. You might have to run commands as the
8585
MySQL root user on the new machine until you have the mysql
8588
After you import the mysql database on the new machine, execute
8589
mysqladmin flush-privileges so that the server reloads the grant
7938
8592
2.14. Environment Variables
added
removed
INSTALL-SOURCE
