2
Chapter 2. Installing and Upgrading MySQL
4
This chapter describes how to obtain and install MySQL. A summary
5
of the procedure follows and later sections provide the details.
6
If you plan to upgrade an existing version of MySQL to a newer
7
version rather than install MySQL for the first time, see Section
8
2.4.1, "Upgrading MySQL," for information about upgrade procedures
9
and about issues that you should consider before upgrading.
11
If you are interested in migrating to MySQL from another database
12
system, you may wish to read Section A.8, "MySQL 5.1 FAQ ---
13
Migration," which contains answers to some common questions
14
concerning migration issues.
16
1. Determine whether MySQL runs and is supported on your
18
Please note that not all platforms are equally suitable for
19
running MySQL, and that not all platforms on which MySQL is
20
known to run are officially supported by Sun Microsystems,
23
2. Choose which distribution to install.
24
Several versions of MySQL are available, and most are
25
available in several distribution formats. You can choose from
26
pre-packaged distributions containing binary (precompiled)
27
programs or source code. When in doubt, use a binary
28
distribution. We also provide public access to our current
29
source tree for those who want to see our most recent
30
developments and help us test new code. To determine which
31
version and type of distribution you should use, see Section
32
2.1.2, "Choosing Which MySQL Distribution to Install."
34
3. Download the distribution that you want to install.
35
For instructions, see Section 2.1.3, "How to Get MySQL." To
36
verify the integrity of the distribution, use the instructions
37
in Section 2.1.4, "Verifying Package Integrity Using MD5
40
4. Install the distribution.
41
To install MySQL from a binary distribution, use the
42
instructions in Section 2.2, "Installing MySQL from Generic
43
Binaries on Unix/Linux."
44
To install MySQL from a source distribution or from the
45
current development source tree, use the instructions in
46
Section 2.3, "MySQL Installation Using a Source Distribution."
48
5. Perform any necessary post-installation setup.
49
After installing MySQL, read Section 2.13, "Post-Installation
50
Setup and Testing." This section contains important
51
information about making sure the MySQL server is working
52
properly. It also describes how to secure the initial MySQL
53
user accounts, which have no passwords until you assign
54
passwords. The section applies whether you install MySQL using
55
a binary or source distribution.
57
6. If you want to run the MySQL benchmark scripts, Perl support
58
for MySQL must be available. See Section 2.15, "Perl
61
2.1. General Installation Guidance
63
The immediately following sections contain the information
64
necessary to choose, download, and verify your distribution. The
65
instructions in later sections of the chapter describe how to
66
install the distribution that you choose. For binary
67
distributions, see the instructions at Section 2.2, "Installing
68
MySQL from Generic Binaries on Unix/Linux" or the corresponding
69
section for your platform if available. To build MySQL from
70
source, use the instructions in Section 2.3, "MySQL Installation
71
Using a Source Distribution."
73
2.1.1. Operating Systems Supported by MySQL Community Server
75
This section lists the operating systems on which MySQL Community
76
Server is known to run.
80
Sun Microsystems, Inc. does not necessarily provide official
81
support for all the platforms listed in this section. For
82
information about those platforms that are officially supported,
83
see http://www.mysql.com/support/supportedplatforms.html on the
86
We use GNU Autoconf, so it is possible to port MySQL to all modern
87
systems that have a C++ compiler and a working implementation of
88
POSIX threads. (Thread support is needed for the server. To
89
compile only the client code, the only requirement is a C++
92
MySQL has been reported to compile successfully on the following
93
combinations of operating system and thread package.
95
* AIX 4.x, 5.x with native threads. See Section 2.12,
96
"Installing MySQL on AIX." AIX 5.3 should be upgraded to
97
technology level 7 (5300-07).
99
* FreeBSD 5.x and up with native threads. See Section 2.10,
100
"Installing MySQL on FreeBSD."
102
* HP-UX 11.x with the native threads. See Section 2.11,
103
"Installing MySQL on HP-UX."
105
* Linux, builds on all fairly recent Linux distributions with
106
glibc 2.3. See Section 2.6, "Installing MySQL on Linux."
108
* Mac OS X. See Section 2.7, "Installing MySQL on Mac OS X."
110
* Solaris 2.8 on SPARC and x86, including support for native
111
threads. See Section 2.8.1, "Solaris Notes."
113
* Windows 2000, Windows XP, Windows Vista, Windows Server 2003,
114
and Windows Server 2008. See Section 2.5, "Installing MySQL on
117
MySQL has also been known to run on other systems in the past. See
118
Section 2.1, "General Installation Guidance." Some porting effort
119
might be required for current versions of MySQL on these systems.
121
Not all platforms are equally well-suited for running MySQL. How
122
well a certain platform is suited for a high-load mission-critical
123
MySQL server is determined by the following factors:
125
* General stability of the thread library. A platform may have
126
an excellent reputation otherwise, but MySQL is only as stable
127
as the thread library it calls, even if everything else is
130
* The capability of the kernel and the thread library to take
131
advantage of symmetric multi-processor (SMP) systems. In other
132
words, when a process creates a thread, it should be possible
133
for that thread to run on a CPU different from the original
136
* The capability of the kernel and the thread library to run
137
many threads that acquire and release a mutex over a short
138
critical region frequently without excessive context switches.
139
If the implementation of pthread_mutex_lock() is too anxious
140
to yield CPU time, this hurts MySQL tremendously. If this
141
issue is not taken care of, adding extra CPUs actually makes
144
* General file system stability and performance.
146
* Table size. If your tables are large, performance is affected
147
by the ability of the file system to deal with large files and
148
dealing with them efficiently.
150
* Our level of expertise here at Sun Microsystems, Inc. with the
151
platform. If we know a platform well, we enable
152
platform-specific optimizations and fixes at compile time. We
153
can also provide advice on configuring your system optimally
156
* The amount of testing we have done internally for similar
159
* The number of users that have run MySQL successfully on the
160
platform in similar configurations. If this number is high,
161
the likelihood of encountering platform-specific surprises is
164
2.1.2. Choosing Which MySQL Distribution to Install
166
When preparing to install MySQL, you should decide which version
167
to use. MySQL development occurs in several release series, and
168
you can pick the one that best fits your needs. After deciding
169
which version to install, you can choose a distribution format.
170
Releases are available in binary or source format.
172
2.1.2.1. Choosing Which Version of MySQL to Install
174
The first decision to make is whether you want to use a production
175
(stable) release or a development release. In the MySQL
176
development process, multiple release series co-exist, each at a
177
different stage of maturity:
179
* MySQL 5.5 is the current development release series.
181
* MySQL 5.1 is the current General Availability (Production)
182
release series. New releases are issued for bugfixes only; no
183
new features are being added that could affect stability.
185
* MySQL 5.0 is the previous stable (production-quality) release
186
series. MySQL 5.0 is now at the end of the product lifecycle.
187
Active development and support for this version has ended.
188
Extended support for MySQL 5.0 remains available. According to
189
the http://www.mysql.com/about/legal/lifecycle/, only Security
190
and Severity Level 1 issues are still being fixed for MySQL
193
* MySQL 4.1, 4.0, and 3.23 are old stable (production-quality)
194
release series. Active development and support for these
197
We do not believe in a complete code freeze because this prevents
198
us from making bugfixes and other fixes that must be done. By
199
"somewhat frozen" we mean that we may add small things that should
200
not affect anything that currently works in a production release.
201
Naturally, relevant bugfixes from an earlier series propagate to
204
Normally, if you are beginning to use MySQL for the first time or
205
trying to port it to some system for which there is no binary
206
distribution, go with the General Availability release series.
207
Currently, this is MySQL 5.1. All MySQL releases, even those from
208
development series, are checked with the MySQL benchmarks and an
209
extensive test suite before being issued.
211
If you are running an older system and want to upgrade, but do not
212
want to take the chance of having a nonseamless upgrade, you
213
should upgrade to the latest version in the same release series
214
you are using (where only the last part of the version number is
215
newer than yours). We have tried to fix only fatal bugs and make
216
only small, relatively "safe" changes to that version.
218
If you want to use new features not present in the production
219
release series, you can use a version from a development series.
220
Note that development releases are not as stable as production
223
If you want to use the very latest sources containing all current
224
patches and bugfixes, you can use one of our Bazaar repositories.
225
These are not "releases" as such, but are available as previews of
226
the code on which future releases are to be based.
228
The MySQL naming scheme uses release names that consist of three
229
numbers and a suffix; for example, mysql-5.0.14-rc. The numbers
230
within the release name are interpreted as follows:
232
* The first number (5) is the major version and describes the
233
file format. All MySQL 5 releases have the same file format.
235
* The second number (0) is the release level. Taken together,
236
the major version and release level constitute the release
239
* The third number (14) is the version number within the release
240
series. This is incremented for each new release. Usually you
241
want the latest version for the series you have chosen.
243
For each minor update, the last number in the version string is
244
incremented. When there are major new features or minor
245
incompatibilities with previous versions, the second number in the
246
version string is incremented. When the file format changes, the
247
first number is increased.
249
Release names also include a suffix to indicates the stability
250
level of the release. Releases within a series progress through a
251
set of suffixes to indicate how the stability level improves. The
252
possible suffixes are:
254
* alpha indicates that the release is for preview purposes only.
255
Known bugs should be documented in the News section (see
256
Appendix C, "MySQL Change History"). Most alpha releases
257
implement new commands and extensions. Active development that
258
may involve major code changes can occur in an alpha release.
259
However, we do conduct testing before issuing a release.
261
* beta indicates that the release is appropriate for use with
262
new development. Within beta releases, the features and
263
compatibility should remain consistent. However, beta releases
264
may contain numerous and major unaddressed bugs.
265
All APIs, externally visible structures, and columns for SQL
266
statements will not change during future beta, release
267
candidate, or production releases.
269
* rc indicates a Release Candidate. Release candidates are
270
believed to be stable, having passed all of MySQL's internal
271
testing, and with all known fatal runtime bugs fixed. However,
272
the release has not been in widespread use long enough to know
273
for sure that all bugs have been identified. Only minor fixes
274
are added. (A release candidate is what formerly was known as
277
* If there is no suffix, it indicates that the release is a
278
General Availability (GA) or Production release. GA releases
279
are stable, having successfully passed through all earlier
280
release stages and are believed to be reliable, free of
281
serious bugs, and suitable for use in production systems. Only
282
critical bugfixes are applied to the release.
284
MySQL uses a naming scheme that is slightly different from most
285
other products. In general, it is usually safe to use any version
286
that has been out for a couple of weeks without being replaced by
287
a new version within the same release series.
289
All releases of MySQL are run through our standard tests and
290
benchmarks to ensure that they are relatively safe to use. Because
291
the standard tests are extended over time to check for all
292
previously found bugs, the test suite keeps getting better.
294
All releases have been tested at least with these tools:
296
* An internal test suite
297
The mysql-test directory contains an extensive set of test
298
cases. We run these tests for every server binary. See Section
299
22.1.2, "MySQL Test Suite," for more information about this
302
* The MySQL benchmark suite
303
This suite runs a range of common queries. It is also a test
304
to determine whether the latest batch of optimizations
305
actually made the code faster. See Section 7.1.3, "The MySQL
308
We also test the newest MySQL version in our internal production
309
environment, on at least one machine. We have more than 100GB of
312
2.1.2.2. Choosing a Distribution Format
314
After choosing which version of MySQL to install, you should
315
decide whether to use a binary distribution or a source
316
distribution. In most cases, you should probably use a binary
317
distribution, if one exists for your platform. Binary
318
distributions are available in native format for many platforms,
319
such as RPM files for Linux or PKG package installers for Mac OS X
320
or Solaris. Distributions also are available as Zip archives or
321
compressed tar files.
323
Reasons to choose a binary distribution include the following:
325
* Binary distributions generally are easier to install than
326
source distributions.
328
* To satisfy different user requirements, we provide several
329
servers in binary distributions. mysqld is an optimized server
330
that is a smaller, faster binary. mysqld-debug is compiled
331
with debugging support.
332
Each of these servers is compiled from the same source
333
distribution, though with different configuration options. All
334
native MySQL clients can connect to servers from either MySQL
337
Under some circumstances, you may be better off installing MySQL
338
from a source distribution:
340
* You want to install MySQL at some explicit location. The
341
standard binary distributions are ready to run at any
342
installation location, but you might require even more
343
flexibility to place MySQL components where you want.
345
* You want to configure mysqld to ensure that features are
346
available that might not be included in the standard binary
347
distributions. Here is a list of the most common extra options
348
that you may want to use to ensure feature availability:
352
+ --with-named-z-libs (this is done for some of the
355
+ --with-debug[=full]
357
* You want to configure mysqld without some features that are
358
included in the standard binary distributions. For example,
359
distributions normally are compiled with support for all
360
character sets. If you want a smaller MySQL server, you can
361
recompile it with support for only the character sets you
364
* You have a special compiler (such as pgcc) or want to use
365
compiler options that are better optimized for your processor.
366
Binary distributions are compiled with options that should
367
work on a variety of processors from the same processor
370
* You want to use the latest sources from one of the Bazaar
371
repositories to have access to all current bugfixes. For
372
example, if you have found a bug and reported it to the MySQL
373
development team, the bugfix is committed to the source
374
repository and you can access it there. The bugfix does not
375
appear in a release until a release actually is issued.
377
* You want to read (or modify) the C and C++ code that makes up
378
MySQL. For this purpose, you should get a source distribution,
379
because the source code is always the ultimate manual.
381
* Source distributions contain more tests and examples than
382
binary distributions.
384
2.1.2.3. How and When Updates Are Released
386
MySQL is evolving quite rapidly and we want to share new
387
developments with other MySQL users. We try to produce a new
388
release whenever we have new and useful features that others also
389
seem to have a need for.
391
We also try to help users who request features that are easy to
392
implement. We take note of what our licensed users want, and we
393
especially take note of what our support customers want and try to
394
help them in this regard.
396
No one is required to download a new release. The News section
397
helps you determine whether the new release has something you
398
really want. See Appendix C, "MySQL Change History."
400
We use the following policy when updating MySQL:
402
* Enterprise Server releases are meant to appear every 18
403
months, supplemented by quarterly service packs and monthly
404
rapid updates. Community Server releases are meant to appear
407
* Releases are issued within each series. For each release, the
408
last number in the version is one more than the previous
409
release within the same series.
411
* Binary distributions for some platforms are made by us for
412
major releases. Other people may make binary distributions for
413
other systems, but probably less frequently.
415
* We make fixes available as soon as we have identified and
416
corrected small or noncritical but annoying bugs. The fixes
417
are available in source form immediately from our public
418
Bazaar repositories, and are included in the next release.
420
* If by any chance a security vulnerability or critical bug is
421
found in a release, our policy is to fix it in a new release
422
as soon as possible. (We would like other companies to do
425
2.1.3. How to Get MySQL
427
Check our downloads page at http://dev.mysql.com/downloads/ for
428
information about the current version of MySQL and for downloading
429
instructions. For a complete up-to-date list of MySQL download
430
mirror sites, see http://dev.mysql.com/downloads/mirrors.html. You
431
can also find information there about becoming a MySQL mirror site
432
and how to report a bad or out-of-date mirror.
434
Our main mirror is located at http://mirrors.sunsite.dk/mysql/.
436
2.1.4. Verifying Package Integrity Using MD5 Checksums or GnuPG
438
After you have downloaded the MySQL package that suits your needs
439
and before you attempt to install it, you should make sure that it
440
is intact and has not been tampered with. There are three means of
445
* Cryptographic signatures using GnuPG, the GNU Privacy Guard
447
* For RPM packages, the built-in RPM integrity verification
450
The following sections describe how to use these methods.
452
If you notice that the MD5 checksum or GPG signatures do not
453
match, first try to download the respective package one more time,
454
perhaps from another mirror site. If you repeatedly cannot
455
successfully verify the integrity of the package, please notify us
456
about such incidents, including the full package name and the
457
download site you have been using, at webmaster@mysql.com or
458
build@mysql.com. Do not report downloading problems using the
459
bug-reporting system.
461
2.1.4.1. Verifying the MD5 Checksum
463
After you have downloaded a MySQL package, you should make sure
464
that its MD5 checksum matches the one provided on the MySQL
465
download pages. Each package has an individual checksum that you
466
can verify with the following command, where package_name is the
467
name of the package you downloaded:
468
shell> md5sum package_name
471
shell> md5sum mysql-standard-5.1.45-linux-i686.tar.gz
472
aaab65abbec64d5e907dcd41b8699945 mysql-standard-5.1.45-linux-i686.ta
475
You should verify that the resulting checksum (the string of
476
hexadecimal digits) matches the one displayed on the download page
477
immediately below the respective package.
481
Make sure to verify the checksum of the archive file (for example,
482
the .zip or .tar.gz file) and not of the files that are contained
483
inside of the archive.
485
Note that not all operating systems support the md5sum command. On
486
some, it is simply called md5, and others do not ship it at all.
487
On Linux, it is part of the GNU Text Utilities package, which is
488
available for a wide range of platforms. You can download the
489
source code from http://www.gnu.org/software/textutils/ as well.
490
If you have OpenSSL installed, you can use the command openssl md5
491
package_name instead. A Windows implementation of the md5 command
492
line utility is available from http://www.fourmilab.ch/md5/.
493
winMd5Sum is a graphical MD5 checking tool that can be obtained
494
from http://www.nullriver.com/index/products/winmd5sum.
496
2.1.4.2. Signature Checking Using GnuPG
498
Another method of verifying the integrity and authenticity of a
499
package is to use cryptographic signatures. This is more reliable
500
than using MD5 checksums, but requires more work.
502
We sign MySQL downloadable packages with GnuPG (GNU Privacy
503
Guard). GnuPG is an Open Source alternative to the well-known
504
Pretty Good Privacy (PGP) by Phil Zimmermann. See
505
http://www.gnupg.org/ for more information about GnuPG and how to
506
obtain and install it on your system. Most Linux distributions
507
ship with GnuPG installed by default. For more information about
508
GnuPG, see http://www.openpgp.org/.
510
To verify the signature for a specific package, you first need to
511
obtain a copy of our public GPG build key, which you can download
512
from http://keyserver.pgp.com/. The key that you want to obtain is
513
named build@mysql.com. Alternatively, you can cut and paste the
514
key directly from the following text:
515
-----BEGIN PGP PUBLIC KEY BLOCK-----
516
Version: GnuPG v1.4.5 (GNU/Linux)
518
mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
519
RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
520
fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
521
BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
522
hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
523
K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
524
kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
525
QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
526
rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
527
a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
528
bT6IXQQTEQIAHQULBwoDBAMVAwIDFgIBAheABQJLcC5lBQkQ8/JZAAoJEIxxjTtQ
529
cuH1oD4AoIcOQ4EoGsZvy06D0Ei5vcsWEy8dAJ4g46i3WEcdSWxMhcBSsPz65sh5
530
lohMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
531
cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
532
YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
533
Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
534
xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
535
Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
536
7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
537
Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
538
/1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
539
a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
540
anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
541
I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
542
QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
543
6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
544
Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
545
n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
548
-----END PGP PUBLIC KEY BLOCK-----
550
To import the build key into your personal public GPG keyring, use
551
gpg --import. For example, if you have saved the key in a file
552
named mysql_pubkey.asc, the import command looks like this:
553
shell> gpg --import mysql_pubkey.asc
554
gpg: key 5072E1F5: public key "MySQL Package signing key (www.mysql.c
555
om) <build@mysql.com>" imported
556
gpg: Total number processed: 1
558
gpg: no ultimately trusted keys found
560
You can also download the key from the public keyserver using the
561
public key id, 5072E1F5:
562
shell> gpg --recv-keys 5072E1F5
563
gpg: requesting key 5072E1F5 from hkp server subkeys.pgp.net
564
gpg: key 5072E1F5: "MySQL Package signing key (www.mysql.com) <build@
565
mysql.com>" 2 new signatures
566
gpg: no ultimately trusted keys found
567
gpg: Total number processed: 1
568
gpg: new signatures: 2
570
If you want to import the key into your RPM configuration to
571
validate RPM install packages, you should be able to import the
573
shell> rpm --import mysql_pubkey.asc
575
If you experience problems, try exporting the key from gpg and
577
shell> gpg --export -a 5072e1f5 > 5072e1f5.asc
578
shell> rpm --import 5072e1f5.asc
580
Alternatively, rpm also supports loading the key directly from a
581
URL, and you cas use this manual page:
582
shell> rpm --import http://dev.mysql.com/doc/refman/5.1/en/checking-g
585
After you have downloaded and imported the public build key,
586
download your desired MySQL package and the corresponding
587
signature, which also is available from the download page. The
588
signature file has the same name as the distribution file with an
589
.asc extension, as shown by the examples in the following table.
590
Distribution file mysql-standard-5.1.45-linux-i686.tar.gz
591
Signature file mysql-standard-5.1.45-linux-i686.tar.gz.asc
593
Make sure that both files are stored in the same directory and
594
then run the following command to verify the signature for the
596
shell> gpg --verify package_name.asc
599
shell> gpg --verify mysql-standard-5.1.45-linux-i686.tar.gz.asc
600
gpg: Signature made Tue 12 Jul 2005 23:35:41 EST using DSA key ID 507
602
gpg: Good signature from "MySQL Package signing key (www.mysql.com) <
605
The Good signature message indicates that everything is all right.
606
You can ignore any insecure memory warning you might obtain.
608
See the GPG documentation for more information on how to work with
611
2.1.4.3. Signature Checking Using RPM
613
For RPM packages, there is no separate signature. RPM packages
614
have a built-in GPG signature and MD5 checksum. You can verify a
615
package by running the following command:
616
shell> rpm --checksig package_name.rpm
619
shell> rpm --checksig MySQL-server-5.1.45-0.glibc23.i386.rpm
620
MySQL-server-5.1.45-0.glibc23.i386.rpm: md5 gpg OK
624
If you are using RPM 4.1 and it complains about (GPG) NOT OK
625
(MISSING KEYS: GPG#5072e1f5), even though you have imported the
626
MySQL public build key into your own GPG keyring, you need to
627
import the key into the RPM keyring first. RPM 4.1 no longer uses
628
your personal GPG keyring (or GPG itself). Rather, it maintains
629
its own keyring because it is a system-wide application and a
630
user's GPG public keyring is a user-specific file. To import the
631
MySQL public key into the RPM keyring, first obtain the key as
632
described in Section 2.1.4.2, "Signature Checking Using GnuPG."
633
Then use rpm --import to import the key. For example, if you have
634
saved the public key in a file named mysql_pubkey.asc, import it
636
shell> rpm --import mysql_pubkey.asc
638
If you need to obtain the MySQL public key, see Section 2.1.4.2,
639
"Signature Checking Using GnuPG."
641
2.1.5. Installation Layouts
643
This section describes the default layout of the directories
644
created by installing binary or source distributions provided by
645
Sun Microsystems, Inc. A distribution provided by another vendor
646
might use a layout different from those shown here.
648
Installations created from our Linux RPM distributions result in
649
files under the following system directories.
650
Directory Contents of Directory
651
/usr/bin Client programs and scripts
652
/usr/sbin The mysqld server
653
/var/lib/mysql Log files, databases
654
/usr/share/info Manual in Info format
655
/usr/share/man Unix manual pages
656
/usr/include/mysql Include (header) files
657
/usr/lib/mysql Libraries
658
/usr/share/mysql Error message and character set files
659
/usr/share/sql-bench Benchmarks
661
On Unix, a tar file binary distribution is installed by unpacking
662
it at the installation location you choose (typically
663
/usr/local/mysql) and creates the following directories in that
665
Directory Contents of Directory
666
bin Client programs and the mysqld server
667
data Log files, databases
668
docs Manual in Info format
669
man Unix manual pages
670
include Include (header) files
672
scripts mysql_install_db
673
share/mysql Error message files
676
A source distribution is installed after you configure and compile
677
it. By default, the installation step installs files under
678
/usr/local, in the following subdirectories.
679
Directory Contents of Directory
680
bin Client programs and scripts
681
include/mysql Include (header) files
682
Docs Manual in Info, CHM formats
683
man Unix manual pages
685
libexec The mysqld server
686
share/mysql Error message files
687
sql-bench Benchmarks and crash-me test
688
var Databases and log files
690
Within its installation directory, the layout of a source
691
installation differs from that of a binary installation in the
694
* The mysqld server is installed in the libexec directory rather
695
than in the bin directory.
697
* The data directory is var rather than data.
699
* mysql_install_db is installed in the bin directory rather than
700
in the scripts directory.
702
* The header file and library directories are include/mysql and
703
lib/mysql rather than include and lib.
705
You can create your own binary installation from a compiled source
706
distribution by executing the scripts/make_binary_distribution
707
script from the top directory of the source distribution.
709
2.2. Installing MySQL from Generic Binaries on Unix/Linux
711
This section covers the installation of MySQL binary distributions
712
that are provided for various platforms in the form of compressed
713
tar files (files with a .tar.gz extension).
715
To obtain MySQL, see Section 2.1.3, "How to Get MySQL."
717
Sun Microsystems, Inc. provides a set of binary distributions of
718
MySQL. In addition to binaries provided in platform-specific
719
package formats, we offer binary distributions for a number of
720
platforms in the form of compressed tar files (.tar.gz files). For
721
Windows distributions, see Section 2.5, "Installing MySQL on
724
If you want to compile a debug version of MySQL from a source
725
distribution, you should add --with-debug or --with-debug=full to
726
the configure command used to configure the distribution and
727
remove any -fomit-frame-pointer options.
729
MySQL tar file binary distributions have names of the form
730
mysql-VERSION-OS.tar.gz, where VERSION is a number (for example,
731
5.1.45), and OS indicates the type of operating system for which
732
the distribution is intended (for example, pc-linux-i686).
734
In addition to these generic packages, we also offer binaries in
735
platform-specific package formats for selected platforms. See the
736
platform specific sections for more information, for more
737
information on how to install these.
739
You need the following tools to install a MySQL tar file binary
742
* GNU gunzip to uncompress the distribution.
744
* A reasonable tar to unpack the distribution. GNU tar is known
745
to work. Some operating systems come with a preinstalled
746
version of tar that is known to have problems. For example,
747
the tar provided with early versions of Mac OS X, SunOS 4.x,
748
Solaris 8, Solaris 9, Solaris 10 and OpenSolaris, and HP-UX
749
are known to have problems with long file names. On Mac OS X,
750
you can use the preinstalled gnutar program. On Solaris 10 and
751
OpenSolaris you can use the preinstalled gtar. On other
752
systems with a deficient tar, you should install GNU tar
755
If you run into problems and need to file a bug report, please use
756
the instructions in Section 1.7, "How to Report Bugs or Problems."
758
The basic commands that you must execute to install and use a
759
MySQL binary distribution are:
760
shell> groupadd mysql
761
shell> useradd -g mysql mysql
763
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
764
shell> ln -s full-path-to-mysql-VERSION-OS mysql
766
shell> chown -R mysql .
767
shell> chgrp -R mysql .
768
shell> scripts/mysql_install_db --user=mysql
769
shell> chown -R root .
770
shell> chown -R mysql data
771
shell> bin/mysqld_safe --user=mysql &
775
This procedure does not set up any passwords for MySQL accounts.
776
After following the procedure, proceed to Section 2.13,
777
"Post-Installation Setup and Testing."
779
A more detailed version of the preceding description for
780
installing a binary distribution follows:
782
1. Add a login user and group for mysqld to run as:
783
shell> groupadd mysql
784
shell> useradd -g mysql mysql
785
These commands add the mysql group and the mysql user. The
786
syntax for useradd and groupadd may differ slightly on
787
different versions of Unix, or they may have different names
788
such as adduser and addgroup.
789
You might want to call the user and group something else
790
instead of mysql. If so, substitute the appropriate name in
793
2. Pick the directory under which you want to unpack the
794
distribution and change location into it. In the following
795
example, we unpack the distribution under /usr/local. (The
796
instructions, therefore, assume that you have permission to
797
create files and directories in /usr/local. If that directory
798
is protected, you must perform the installation as root.)
801
3. Obtain a distribution file using the instructions in Section
802
2.1.3, "How to Get MySQL." For a given release, binary
803
distributions for all platforms are built from the same MySQL
806
4. Unpack the distribution, which creates the installation
807
directory. Then create a symbolic link to that directory:
808
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -
809
shell> ln -s full-path-to-mysql-VERSION-OS mysql
810
The tar command creates a directory named mysql-VERSION-OS.
811
The ln command makes a symbolic link to that directory. This
812
lets you refer more easily to the installation directory as
814
With GNU tar, no separate invocation of gunzip is necessary.
815
You can replace the first line with the following alternative
816
command to uncompress and extract the distribution:
817
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
819
5. Change location into the installation directory:
821
You will find several files and subdirectories in the mysql
822
directory. The most important for installation purposes are
823
the bin and scripts subdirectories:
825
+ The bin directory contains client programs and the
826
server. You should add the full path name of this
827
directory to your PATH environment variable so that your
828
shell finds the MySQL programs properly. See Section
829
2.14, "Environment Variables."
831
+ The scripts directory contains the mysql_install_db
832
script used to initialize the mysql database containing
833
the grant tables that store the server access
836
6. Ensure that the distribution contents are accessible to mysql.
837
If you unpacked the distribution as mysql, no further action
838
is required. If you unpacked the distribution as root, its
839
contents will be owned by root. Change its ownership to mysql
840
by executing the following commands as root in the
841
installation directory:
842
shell> chown -R mysql .
843
shell> chgrp -R mysql .
844
The first command changes the owner attribute of the files to
845
the mysql user. The second changes the group attribute to the
848
7. If you have not installed MySQL before, you must create the
849
MySQL data directory and initialize the grant tables:
850
shell> scripts/mysql_install_db --user=mysql
851
If you run the command as root, include the --user option as
852
shown. If you run the command while logged in as that user,
853
you can omit the --user option.
854
The command should create the data directory and its contents
855
with mysql as the owner.
856
After creating or updating the grant tables, you need to
857
restart the server manually.
859
8. Most of the MySQL installation can be owned by root if you
860
like. The exception is that the data directory must be owned
861
by mysql. To accomplish this, run the following commands as
862
root in the installation directory:
863
shell> chown -R root .
864
shell> chown -R mysql data
866
9. If you want MySQL to start automatically when you boot your
867
machine, you can copy support-files/mysql.server to the
868
location where your system has its startup files. More
869
information can be found in the support-files/mysql.server
870
script itself and in Section 2.13.1.2, "Starting and Stopping
871
MySQL Automatically."
872
10. You can set up new accounts using the bin/mysql_setpermission
873
script if you install the DBI and DBD::mysql Perl modules. See
874
Section 4.6.14, "mysql_setpermission --- Interactively Set
875
Permissions in Grant Tables." For Perl module installation
876
instructions, see Section 2.15, "Perl Installation Notes."
877
11. If you would like to use mysqlaccess and have the MySQL
878
distribution in some nonstandard location, you must change the
879
location where mysqlaccess expects to find the mysql client.
880
Edit the bin/mysqlaccess script at approximately line 18.
881
Search for a line that looks like this:
882
$MYSQL = '/usr/local/bin/mysql'; # path to mysql executable
883
Change the path to reflect the location where mysql actually
884
is stored on your system. If you do not do this, a Broken pipe
885
error will occur when you run mysqlaccess.
887
After everything has been unpacked and installed, you should test
888
your distribution. To start the MySQL server, use the following
890
shell> bin/mysqld_safe --user=mysql &
892
If you run the command as root, you must use the --user option as
893
shown. The value of the option is the name of the login account
894
that you created in the first step to use for running the server.
895
If you run the command while logged in as mysql, you can omit the
898
If the command fails immediately and prints mysqld ended, you can
899
find some information in the host_name.err file in the data
902
More information about mysqld_safe is given in Section 4.3.2,
903
"mysqld_safe --- MySQL Server Startup Script."
907
The accounts that are listed in the MySQL grant tables initially
908
have no passwords. After starting the server, you should set up
909
passwords for them using the instructions in Section 2.13,
910
"Post-Installation Setup and Testing."
912
2.3. MySQL Installation Using a Source Distribution
914
Before you proceed with an installation from source, first check
915
whether our binary is available for your platform and whether it
916
works for you. We put a great deal of effort into ensuring that
917
our binaries are built with the best possible options.
919
To obtain a source distribution for MySQL, Section 2.1.3, "How to
920
Get MySQL." If you want to build MySQL from source on Windows, see
921
Section 2.5.10, "Installing MySQL from Source on Windows."
923
MySQL source distributions are provided as compressed tar archives
924
and have names of the form mysql-VERSION.tar.gz, where VERSION is
925
a number like 5.1.45.
927
You need the following tools to build and install MySQL from
930
* GNU gunzip to uncompress the distribution.
932
* A reasonable tar to unpack the distribution. GNU tar is known
933
to work. Some operating systems come with a preinstalled
934
version of tar that is known to have problems. For example,
935
the tar provided with early versions of Mac OS X, SunOS 4.x,
936
Solaris 8, Solaris 9, Solaris 10 and OpenSolaris, and HP-UX
937
are known to have problems with long file names. On Mac OS X,
938
you can use the preinstalled gnutar program. On Solaris 10 and
939
OpenSolaris you can use the preinstalled gtar. On other
940
systems with a deficient tar, you should install GNU tar
943
* A working ANSI C++ compiler. GCC 3.2 or later, Sun Studio 10
944
or later, Visual Studio 2005 or later, and many current
945
vendor-supplied compilers are known to work.
947
* A good make program. GNU make is always recommended and is
948
sometimes required. (BSD make fails, and vendor-provided make
949
implementations may fail as well.) If you have problems, use
950
GNU make 3.75 or newer.
952
* libtool 1.5.24 or later is also recommended.
954
If you are using a version of gcc recent enough to understand the
955
-fno-exceptions option, it is very important that you use this
956
option. Otherwise, you may compile a binary that crashes randomly.
957
Also use -felide-constructors and -fno-rtti along with
958
-fno-exceptions. When in doubt, do the following:
959
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
960
-fno-exceptions -fno-rtti" ./configure \
961
--prefix=/usr/local/mysql --enable-assembler \
962
--with-mysqld-ldflags=-all-static
964
On most systems, this gives you a fast and stable binary.
966
If you run into problems and need to file a bug report, please use
967
the instructions in Section 1.7, "How to Report Bugs or Problems."
969
2.3.1. Source Installation Overview
971
The basic commands that you must execute to install a MySQL source
973
shell> groupadd mysql
974
shell> useradd -g mysql mysql
975
shell> gunzip < mysql-VERSION.tar.gz | tar -xvf -
976
shell> cd mysql-VERSION
977
shell> ./configure --prefix=/usr/local/mysql
980
shell> cp support-files/my-medium.cnf /etc/my.cnf
981
shell> cd /usr/local/mysql
982
shell> chown -R mysql .
983
shell> chgrp -R mysql .
984
shell> bin/mysql_install_db --user=mysql
985
shell> chown -R root .
986
shell> chown -R mysql var
987
shell> bin/mysqld_safe --user=mysql &
989
If you start from a source RPM, do the following:
990
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm
992
This makes a binary RPM that you can install. For older versions
993
of RPM, you may have to replace the command rpmbuild with rpm
998
This procedure does not set up any passwords for MySQL accounts.
999
After following the procedure, proceed to Section 2.13,
1000
"Post-Installation Setup and Testing," for post-installation setup
1003
A more detailed version of the preceding description for
1004
installing MySQL from a source distribution follows:
1006
1. Add a login user and group for mysqld to run as:
1007
shell> groupadd mysql
1008
shell> useradd -g mysql mysql
1009
These commands add the mysql group and the mysql user. The
1010
syntax for useradd and groupadd may differ slightly on
1011
different versions of Unix, or they may have different names
1012
such as adduser and addgroup.
1013
You might want to call the user and group something else
1014
instead of mysql. If so, substitute the appropriate name in
1015
the following steps.
1017
2. Perform the following steps as the mysql user, except as
1020
3. Pick the directory under which you want to unpack the
1021
distribution and change location into it.
1023
4. Obtain a distribution file using the instructions in Section
1024
2.1.3, "How to Get MySQL."
1026
5. Unpack the distribution into the current directory:
1027
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -
1028
This command creates a directory named mysql-VERSION.
1029
With GNU tar, no separate invocation of gunzip is necessary.
1030
You can use the following alternative command to uncompress
1031
and extract the distribution:
1032
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
1034
6. Change location into the top-level directory of the unpacked
1036
shell> cd mysql-VERSION
1037
Note that currently you must configure and build MySQL from
1038
this top-level directory. You cannot build it in a different
1041
7. Configure the release and compile everything:
1042
shell> ./configure --prefix=/usr/local/mysql
1044
When you run configure, you might want to specify other
1045
options. Run ./configure --help for a list of options. Section
1046
2.3.2, "Typical configure Options," discusses some of the more
1048
If configure fails and you are going to send mail to a MySQL
1049
mailing list to ask for assistance, please include any lines
1050
from config.log that you think can help solve the problem.
1051
Also include the last couple of lines of output from
1052
configure. To file a bug report, please use the instructions
1053
in Section 1.7, "How to Report Bugs or Problems."
1054
If the compile fails, see Section 2.3.4, "Dealing with
1055
Problems Compiling MySQL," for help.
1057
8. Install the distribution:
1059
You might need to run this command as root.
1060
If you want to set up an option file, use one of those present
1061
in the support-files directory as a template. For example:
1062
shell> cp support-files/my-medium.cnf /etc/my.cnf
1063
You might need to run this command as root.
1064
If you want to configure support for InnoDB tables, you should
1065
edit the /etc/my.cnf file, remove the # character before the
1066
option lines that start with innodb_..., and modify the option
1067
values to be what you want. See Section 4.2.3.3, "Using Option
1068
Files," and Section 13.6.2, "InnoDB Configuration."
1070
9. Change location into the installation directory:
1071
shell> cd /usr/local/mysql
1072
10. If you ran the make install command as root, the installed
1073
files will be owned by root. Ensure that the installation is
1074
accessible to mysql by executing the following commands as
1075
root in the installation directory:
1076
shell> chown -R mysql .
1077
shell> chgrp -R mysql .
1078
The first command changes the owner attribute of the files to
1079
the mysql user. The second changes the group attribute to the
1081
11. If you have not installed MySQL before, you must create the
1082
MySQL data directory and initialize the grant tables:
1083
shell> bin/mysql_install_db --user=mysql
1084
If you run the command as root, include the --user option as
1085
shown. If you run the command while logged in as mysql, you
1086
can omit the --user option.
1087
The command should create the data directory and its contents
1088
with mysql as the owner.
1089
After using mysql_install_db to create the grant tables for
1090
MySQL, you must restart the server manually. The mysqld_safe
1091
command to do this is shown in a later step.
1092
12. Most of the MySQL installation can be owned by root if you
1093
like. The exception is that the data directory must be owned
1094
by mysql. To accomplish this, run the following commands as
1095
root in the installation directory:
1096
shell> chown -R root .
1097
shell> chown -R mysql var
1098
13. If you want MySQL to start automatically when you boot your
1099
machine, you can copy support-files/mysql.server to the
1100
location where your system has its startup files. More
1101
information can be found in the support-files/mysql.server
1102
script itself; see also Section 2.13.1.2, "Starting and
1103
Stopping MySQL Automatically."
1104
14. You can set up new accounts using the bin/mysql_setpermission
1105
script if you install the DBI and DBD::mysql Perl modules. See
1106
Section 4.6.14, "mysql_setpermission --- Interactively Set
1107
Permissions in Grant Tables." For Perl module installation
1108
instructions, see Section 2.15, "Perl Installation Notes."
1110
After everything has been installed, you should test your
1111
distribution. To start the MySQL server, use the following
1113
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
1115
If you run the command as root, you should use the --user option
1116
as shown. The value of the option is the name of the login account
1117
that you created in the first step to use for running the server.
1118
If you run the command while logged in as that user, you can omit
1121
If the command fails immediately and prints mysqld ended, you can
1122
find some information in the host_name.err file in the data
1125
More information about mysqld_safe is given in Section 4.3.2,
1126
"mysqld_safe --- MySQL Server Startup Script."
1130
The accounts that are listed in the MySQL grant tables initially
1131
have no passwords. After starting the server, you should set up
1132
passwords for them using the instructions in Section 2.13,
1133
"Post-Installation Setup and Testing."
1135
2.3.2. Typical configure Options
1137
The configure script gives you a great deal of control over how
1138
you configure a MySQL source distribution. Typically you do this
1139
using options on the configure command line. You can also affect
1140
configure using certain environment variables. See Section 2.14,
1141
"Environment Variables." For a full list of options supported by
1142
configure, run this command:
1143
shell> ./configure --help
1145
A list of the available configure options is provided in the table
1148
Table 2.1. Build (configure) Reference
1149
Formats Description Default Introduced Removed
1150
--bindir=DIR User executables EPREFIX/bin
1151
--build=BUILD Configure for building on BUILD guessed
1152
--cache-file=FILE Cache test results in FILE disabled
1153
-C Alias for `--cache-file=config.cache'
1155
--datadir=DIR Read-only architecture-independent data PREFIX/share
1157
--disable-FEATURE Do not include FEATURE
1158
--disable-dependency-tracking Disable dependency tracking
1159
--disable-grant-options Disable GRANT options
1160
--disable-largefile Omit support for large files
1161
--disable-libtool-lock Disable libtool lock
1162
--disable-thread-safe-client Compile the client without threads
1164
--enable-FEATURE Enable FEATURE
1165
--enable-assembler Use assembler versions of some string functions
1167
--enable-debug-sync Compile in Debug Sync facility 5.1.41
1168
--enable-dependency-tracking Do not reject slow dependency
1170
--enable-fast-install Optimize for fast installation yes
1171
--enable-local-infile Enable LOAD DATA LOCAL INFILE disabled
1172
--enable-shared Build shared libraries yes
1173
--enable-static Build static libraries yes
1174
--enable-thread-safe-client Compile the client with threads
1175
--exec-prefix=EPREFIX Install architecture-dependent files in
1177
-h Display this help and exit
1179
--help=short Display options specific to this package
1180
--help=recursive Display the short help of all the included
1182
--host=HOST Cross-compile to build programs to run on HOST
1183
--includedir=DIR C header files PREFIX/include
1184
--infodir=DIR Info documentation PREFIX/info
1185
--libdir=DIR Object code libraries EPREFIX/lib
1186
--libexecdir=DIR Program executables EPREFIX/libexec
1187
--localstatedir=DIR Modifiable single-machine data PREFIX/var
1188
--mandir=DIR man documentation PREFIX/man
1189
-n Do not create output files
1191
--oldincludedir=DIR C header files for non-gcc /usr/include
1192
--prefix=PREFIX Install architecture-independent files in PREFIX
1194
--program-prefix=PREFIX Prepend PREFIX to installed program names
1196
--program-suffix=SUFFIX Append SUFFIX to installed program names
1198
--program-transform-name=PROGRAM run sed PROGRAM on installed
1200
-q Do not print `checking...' messages
1202
--sbindir=DIR System admin executables EPREFIX/sbin
1203
--sharedstatedir=DIR Modifiable architecture-independent data
1205
--srcdir=DIR Find the sources in DIR configure directory or ..
1206
--sysconfdir=DIR Read-only single-machine data PREFIX/etc
1207
--target=TARGET Configure for building compilers for TARGET
1208
-V Display version information and exit
1210
--with-PACKAGE Use PACKAGE
1211
--with-archive-storage-engine Enable the Archive Storage Engine no
1213
--with-atomic-ops Implement atomic operations using pthread
1214
rwlocks or atomic CPU instructions for multi-processor 5.1.12
1215
--with-berkeley-db Use BerkeleyDB located in DIR no
1216
--with-berkeley-db-includes Find Berkeley DB headers in DIR
1217
--with-berkeley-db-libs Find Berkeley DB libraries in DIR
1218
--with-big-tables Support tables with more than 4 G rows even on
1220
--with-blackhole-storage-engine Enable the Blackhole Storage
1222
--with-charset Default character set
1223
--with-client-ldflags Extra linking arguments for clients
1224
--with-collation Default collation
1225
--with-comment Comment about compilation environment
1226
--with-csv-storage-engine Enable the CSV Storage Engine yes
1227
--with-darwin-mwcc Use Metrowerks CodeWarrior wrappers on OS
1229
--with-debug Add debug code 5.1.7
1230
--with-debug=full Add debug code (adds memory checker, very slow)
1232
--with-embedded-privilege-control Build parts to check user's
1233
privileges (only affects embedded library)
1234
--with-embedded-server Build the embedded server
1235
--with-error-inject Enable error injection in MySQL Server
1237
--with-example-storage-engine Enable the Example Storage Engine no
1239
--with-extra-charsets Use charsets in addition to default
1240
--with-fast-mutexes Compile with fast mutexes enabled 5.1.5
1241
--with-federated-storage-engine Enable federated storage engine no
1243
--with-gnu-ld Assume the C compiler uses GNU ld no
1244
--with-innodb Enable innobase storage engine no 5.1.3 5.1.9
1245
--with-lib-ccflags Extra CC options for libraries
1246
--with-libwrap=DIR Compile in libwrap (tcp_wrappers) support
1247
--with-low-memory Try to use less memory to compile to avoid
1249
--with-machine-type Set the machine type, like "powerpc"
1250
--with-max-indexes=N Sets the maximum number of indexes per table
1252
--with-mysqld-ldflags Extra linking arguments for mysqld
1253
--with-mysqld-libs Extra libraries to link with for mysqld
1254
--with-mysqld-user What user the mysqld daemon shall be run as
1256
--with-mysqlmanager Build the mysqlmanager binary Build if server
1258
--with-named-curses-libs Use specified curses libraries
1259
--with-named-thread-libs Use specified thread libraries
1260
--with-ndb-ccflags Extra CC options for ndb compile
1261
--with-ndb-docs Include the NDB Cluster ndbapi and mgmapi
1263
--with-ndb-port Port for NDB Cluster management server
1264
--with-ndb-port-base Port for NDB Cluster management server
1265
--with-ndb-sci=DIR Provide MySQL with a custom location of sci
1267
--with-ndb-test Include the NDB Cluster ndbapi test programs
1268
--with-ndbcluster Include the NDB Cluster table handler no
1269
--with-openssl=DIR Include the OpenSSL support
1270
--with-openssl-includes Find OpenSSL headers in DIR
1271
--with-openssl-libs Find OpenSSL libraries in DIR
1272
--with-other-libc=DIR Link against libc and other standard
1273
libraries installed in the specified nonstandard location
1274
--with-pic Try to use only PIC/non-PIC objects Use both
1275
--with-plugin-PLUGIN Forces the named plugin to be linked into
1276
mysqld statically 5.1.11
1277
--with-plugins Plugins to include in mysqld none 5.1.11
1278
--with-pstack Use the pstack backtrace library
1279
--with-pthread Force use of pthread library
1280
--with-row-based-replication Include row-based replication 5.1.5
1282
--with-server-suffix Append value to the version string
1283
--with-ssl=DIR Include SSL support 5.1.11
1284
--with-system-type Set the system type, like "sun-solaris10"
1285
--with-tags Include additional configurations automatic
1286
--with-tcp-port Which port to use for MySQL services 3306
1287
--with-unix-socket-path Where to put the unix-domain socket
1288
--with-yassl Include the yaSSL support
1289
--with-zlib-dir=no|bundled|DIR Provide MySQL with a custom
1290
location of compression library
1291
--without-PACKAGE Do not use PACKAGE
1292
--without-bench Skip building of the benchmark suite
1293
--without-debug Build a production version without debugging code
1295
--without-docs Skip building of the documentation
1296
--without-extra-tools Skip building utilities in the tools
1298
--without-geometry Do not build geometry-related parts
1299
--without-libedit Use system libedit instead of bundled copy
1300
--without-man Skip building of the man pages
1301
--without-ndb-binlog Disable ndb binlog 5.1.6
1302
--without-ndb-debug Disable special ndb debug features
1303
--without-plugin-PLUGIN Exclude PLUGIN 5.1.11
1304
--without-query-cache Do not build query cache
1305
--without-readline Use system readline instead of bundled copy
1307
--without-row-based-replication Don't include row-based
1308
replication 5.1.7 5.1.14
1309
--without-server Only build the client
1310
--without-uca Skip building of the national Unicode collations
1312
Some of the configure options available are described here. For
1313
options that may be of use if you have difficulties building
1314
MySQL, see Section 2.3.4, "Dealing with Problems Compiling MySQL."
1316
* To compile just the MySQL client libraries and client programs
1317
and not the server, use the --without-server option:
1318
shell> ./configure --without-server
1319
If you have no C++ compiler, some client programs such as
1320
mysql cannot be compiled because they require C++.. In this
1321
case, you can remove the code in configure that tests for the
1322
C++ compiler and then run ./configure with the
1323
--without-server option. The compile step should still try to
1324
build all clients, but you can ignore any warnings about files
1325
such as mysql.cc. (If make stops, try make -k to tell it to
1326
continue with the rest of the build even if errors occur.)
1328
* If you want to build the embedded MySQL library (libmysqld.a),
1329
use the --with-embedded-server option.
1331
* If you don't want your log files and database directories
1332
located under /usr/local/var, use a configure command
1333
something like one of these:
1334
shell> ./configure --prefix=/usr/local/mysql
1335
shell> ./configure --prefix=/usr/local \
1336
--localstatedir=/usr/local/mysql/data
1337
The first command changes the installation prefix so that
1338
everything is installed under /usr/local/mysql rather than the
1339
default of /usr/local. The second command preserves the
1340
default installation prefix, but overrides the default
1341
location for database directories (normally /usr/local/var)
1342
and changes it to /usr/local/mysql/data.
1343
You can also specify the installation directory and data
1344
directory locations at server startup time by using the
1345
--basedir and --datadir options. These can be given on the
1346
command line or in an MySQL option file, although it is more
1347
common to use an option file. See Section 4.2.3.3, "Using
1350
* This option specifies the port number on which the server
1351
listens for TCP/IP connections. The default is port 3306. To
1352
listen on a different port, use a configure command like this:
1353
shell> ./configure --with-tcp-port=3307
1355
* If you are using Unix and you want the MySQL socket file
1356
location to be somewhere other than the default location
1357
(normally in the directory /tmp or /var/run), use a configure
1359
shell> ./configure \
1360
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
1361
The socket file name must be an absolute path name. You can
1362
also change the location of mysql.sock at server startup by
1363
using a MySQL option file. See Section B.5.4.5, "How to
1364
Protect or Change the MySQL Unix Socket File."
1366
* If you want to compile statically linked programs (for
1367
example, to make a binary distribution, to get better
1368
performance, or to work around problems with some Red Hat
1369
Linux distributions), run configure like this:
1370
shell> ./configure --with-client-ldflags=-all-static \
1371
--with-mysqld-ldflags=-all-static
1373
* If you are using gcc and don't have libg++ or libstdc++
1374
installed, you can tell configure to use gcc as your C++
1376
shell> CC=gcc CXX=gcc ./configure
1377
When you use gcc as your C++ compiler, it does not attempt to
1378
link in libg++ or libstdc++. This may be a good thing to do
1379
even if you have those libraries installed. Some versions of
1380
them have caused strange problems for MySQL users in the past.
1381
The following list indicates some compilers and environment
1382
variable settings that are commonly used with each one.
1385
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
1388
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
1389
-felide-constructors -fno-exceptions -fno-rtti"
1391
+ pgcc 2.90.29 or newer:
1392
CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \
1393
CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \
1394
-felide-constructors -fno-exceptions -fno-rtti"
1395
In most cases, you can get a reasonably optimized MySQL binary
1396
by using the options from the preceding list and adding the
1397
following options to the configure line:
1398
--prefix=/usr/local/mysql --enable-assembler \
1399
--with-mysqld-ldflags=-all-static
1400
The full configure line would, in other words, be something
1401
like the following for all recent gcc versions:
1402
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
1403
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
1404
--prefix=/usr/local/mysql --enable-assembler \
1405
--with-mysqld-ldflags=-all-static
1406
The binaries we provide on the MySQL Web site at
1407
http://dev.mysql.com/downloads/ are all compiled with full
1408
optimization and should be perfect for most users. See Section
1409
2.2, "Installing MySQL from Generic Binaries on Unix/Linux."
1410
There are some configuration settings you can tweak to build
1411
an even faster binary, but these are only for advanced users.
1412
See Section 7.5.1, "How Compiling and Linking Affects the
1414
If the build fails and produces errors about your compiler or
1415
linker not being able to create the shared library
1416
libmysqlclient.so.N (where N is a version number), you can
1417
work around this problem by giving the --disable-shared option
1418
to configure. In this case, configure does not build a shared
1419
libmysqlclient.so.N library.
1421
* By default, MySQL uses the latin1 (cp1252 West European)
1422
character set. To change the default set, use the
1423
--with-charset option:
1424
shell> ./configure --with-charset=CHARSET
1425
CHARSET may be one of binary, armscii8, ascii, big5, cp1250,
1426
cp1251, cp1256, cp1257, cp850, cp852, cp866, cp932, dec8,
1427
eucjpms, euckr, gb2312, gbk, geostd8, greek, hebrew, hp8,
1428
keybcs2, koi8r, koi8u, latin1, latin2, latin5, latin7, macce,
1429
macroman, sjis, swe7, tis620, ucs2, ujis, utf8. (Additional
1430
character sets might be available. Check the output from
1431
./configure --help for the current list.)
1432
The default collation may also be specified. MySQL uses the
1433
latin1_swedish_ci collation by default. To change this, use
1434
the --with-collation option:
1435
shell> ./configure --with-collation=COLLATION
1436
To change both the character set and the collation, use both
1437
the --with-charset and --with-collation options. The collation
1438
must be a legal collation for the character set. (Use the SHOW
1439
COLLATION statement to determine which collations are
1440
available for each character set.)
1441
With the configure option --with-extra-charsets=LIST, you can
1442
define which additional character sets should be compiled into
1443
the server. LIST is one of the following:
1445
+ A list of character set names separated by spaces
1447
+ complex to include all character sets that can't be
1450
+ all to include all character sets into the binaries
1451
Clients that want to convert characters between the server and
1452
the client should use the SET NAMES statement. See Section
1453
5.1.5, "Session System Variables," and Section 9.1.4,
1454
"Connection Character Sets and Collations."
1456
* To configure MySQL with debugging code, use the --with-debug
1458
shell> ./configure --with-debug
1459
This causes a safe memory allocator to be included that can
1460
find some errors and that provides output about what is
1461
happening. See MySQL Internals: Porting
1462
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
1463
As of MySQL 5.1.12, using --with-debug to configure MySQL with
1464
debugging support enables you to use the
1465
--debug="d,parser_debug" option when you start the server.
1466
This causes the Bison parser that is used to process SQL
1467
statements to dump a parser trace to the server's standard
1468
error output. Typically, this output is written to the error
1471
* To cause the Debug Sync facility to be compiled into the
1472
server, use the --enable-debug-sync option. This facility is
1473
used for testing and debugging. When compiled in, Debug Sync
1474
is disabled by default. To enable it, start mysqld with the
1475
--debug-sync-timeout=N option, where N is a timeout value
1476
greater than 0. (The default value is 0, which disables Debug
1477
Sync.) N becomes the default timeout for individual
1478
synchronization points.
1479
Debug Sync is also compiled in if you configure with the
1480
--with-debug option (which implies --enable-debug-sync),
1481
unless you also use the --disable-debug-sync option.
1482
For a description of the Debug Sync facility and how to use
1483
synchronization points, see MySQL Internals: Test
1485
(http://forge.mysql.com/wiki/MySQL_Internals_Test_Synchronizat
1487
The --enable-debug-sync and --disable-debug-sync options were
1488
added in MySQL 5.1.41.
1490
* If your client programs are using threads, you must compile a
1491
thread-safe version of the MySQL client library with the
1492
--enable-thread-safe-client configure option. This creates a
1493
libmysqlclient_r library with which you should link your
1494
threaded applications. See Section 21.9.16.2, "How to Make a
1497
* Some features require that the server be built with
1498
compression library support, such as the COMPRESS() and
1499
UNCOMPRESS() functions, and compression of the client/server
1500
protocol. The --with-zlib-dir=no|bundled|DIR option provides
1501
control over compression library support. The value no
1502
explicitly disables compression support. bundled causes the
1503
zlib library bundled in the MySQL sources to be used. A DIR
1504
path name specifies the directory in which to find the
1505
compression library sources.
1507
* It is possible to build MySQL with large table support using
1508
the --with-big-tables option.
1509
This option causes the variables that store table row counts
1510
to be declared as unsigned long long rather than unsigned
1511
long. This enables tables to hold up to approximately
1512
1.844E+19 ((2^32)^2) rows rather than 2^32 (~4.295E+09) rows.
1513
Previously it was necessary to pass -DBIG_TABLES to the
1514
compiler manually in order to enable this feature.
1516
* Run configure with the --disable-grant-options option to cause
1517
the --bootstrap, --skip-grant-tables, and --init-file options
1518
for mysqld to be disabled. For Windows, the configure.js
1519
script recognizes the DISABLE_GRANT_OPTIONS flag, which has
1520
the same effect. The capability is available as of MySQL
1523
* This option allows MySQL Community Server features to be
1524
enabled. Additional options may be required for individual
1525
features, such as --enable-profiling to enable statement
1526
profiling. This option was added in MySQL 5.1.24. It is
1527
enabled by default as of MySQL 5.1.28; to disable it, use
1528
--disable-community-features.
1530
* When given with --enable-community-features, the
1531
--enable-profiling option enables the statement profiling
1532
capability exposed by the SHOW PROFILE and SHOW PROFILES
1533
statements. (See Section 12.5.5.33, "SHOW PROFILES Syntax.")
1534
This option was added in MySQL 5.1.24. It is enabled by
1535
default as of MySQL 5.1.28; to disable it, use
1536
--disable-profiling.
1538
* See Section 2.1, "General Installation Guidance," for options
1539
that pertain to particular operating systems.
1541
* See Section 5.5.6.2, "Using SSL Connections," for options that
1542
pertain to configuring MySQL to support secure (encrypted)
1545
* Several configure options apply to plugin selection and
1547
--with-plugins=PLUGIN[,PLUGIN]...
1548
--with-plugins=GROUP
1549
--with-plugin-PLUGIN
1550
--without-plugin-PLUGIN
1551
PLUGIN is an individual plugin name such as csv or archive.
1552
As shorthand, GROUP is a configuration group name such as none
1553
(select no plugins) or all (select all plugins).
1554
You can build a plugin as static (compiled into the server) or
1555
dynamic (built as a dynamic library that must be installed
1556
using the INSTALL PLUGIN statement before it can be used).
1557
Some plugins might not support static or dynamic build.
1558
configure --help shows the following information pertaining to
1561
+ The plugin-related options
1563
+ The names of all available plugins
1565
+ For each plugin, a description of its purpose, which
1566
build types it supports (static or dynamic), and which
1567
plugin groups it is a part of.
1568
--with-plugins can take a list of one or more plugin names
1569
separated by commas, or a plugin group name. The named plugins
1570
are configured to be built as static plugins.
1571
--with-plugin-PLUGIN configures the given plugin to be built
1573
--without-plugin-PLUGIN disables the given plugin from being
1575
If a plugin is named both with a --with and --without option,
1576
the result is undefined.
1577
For any plugin that is not explicitly selected or disabled, it
1578
is selected to be built dynamically if it supports dynamic
1579
build, and not built if it does not support dynamic build.
1580
(Thus, in the case that no plugin options are given, all
1581
plugins that support dynamic build are selected to be built as
1582
dynamic plugins. Plugins that do not support dynamic build are
1585
2.3.3. Installing from the Development Source Tree
1589
You should read this section only if you are interested in helping
1590
us test our new code. If you just want to get MySQL up and running
1591
on your system, you should use a standard release distribution
1592
(either a binary or source distribution).
1594
To obtain the most recent development source tree, you must have
1595
Bazaar installed. You can obtain Bazaar from the Bazaar VCS Web
1596
site (http://bazaar-vcs.org). Bazaar is supported by any platform
1597
that supports Python, and is therefore compatible with any Linux,
1598
Unix, Windows or Mac OS X host. Instructions for downloading and
1599
installing Bazaar on the different platforms are available on the
1602
All MySQL projects are hosted on Launchpad
1603
(http://launchpad.net/). MySQL projects, including MySQL server,
1604
MySQL Workbench, and others are available from the Sun/MySQL
1605
Engineering (http://launchpad.net/~mysql) page. For the
1606
repositories related only to MySQL server, see the MySQL Server
1607
(http://launchpad.net/mysql-server) page.
1609
To build under Unix/Linux, you must have the following tools
1612
* GNU make, available from http://www.gnu.org/software/make/.
1613
Although some platforms come with their own make
1614
implementations, it is highly recommended that you use GNU
1615
make. It may already be available on your system as gmake.
1617
* autoconf 2.58 (or newer), available from
1618
http://www.gnu.org/software/autoconf/.
1620
* automake 1.8.1, available from
1621
http://www.gnu.org/software/automake/.
1623
* libtool 1.5, available from
1624
http://www.gnu.org/software/libtool/.
1626
* m4, available from http://www.gnu.org/software/m4/.
1628
* bison, available from http://www.gnu.org/software/bison/. You
1629
should use the latest version of bison where possible. Version
1630
1.75 and version 2.1 are known to work. There have been
1631
reported problems with bison 1.875. If you experience
1632
problems, upgrade to a later, rather than earlier, version.
1633
Versions of bison older than 1.75 may report this error:
1634
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded
1635
The maximum table size is not actually exceeded; the error is
1636
caused by bugs in older versions of bison.
1638
To build under Windows you must have Microsoft Visual C++ 2005
1639
Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio
1640
2005 (8.0) compiler system.
1642
Once the necessary tools are installed, you must create a local
1643
branch of the MySQL source code on your machine:
1645
1. To obtain a copy of the MySQL source code, you must create a
1646
new Bazaar branch. If you do not already have a Bazaar
1647
repository directory set up, you need to initialize a new
1649
shell> mkdir mysql-server
1650
shell> bzr init-repo --trees mysql-server
1652
2. Once you have an initialized directory, you can branch from
1653
the public MySQL server repositories to create a local source
1654
tree. To create a branch of a specific version:
1655
shell> cd mysql-server
1656
shell> bzr branch lp:mysql-server/5.1 mysql-5.1
1658
3. The initial download will take some time to complete,
1659
depending on the speed of your connection. Please be patient.
1660
Once you have downloaded the first tree, additional trees
1661
should take significantly less time to download.
1663
4. When building from the Bazaar branch, you may want to create a
1664
copy of your active branch so that you can make configuration
1665
and other changes without affecting the original branch
1666
contents. You can achieve this by branching from the original
1668
shell> bzr branch mysql-5.1 mysql-5.1-build
1670
5. To obtain changes made after you have set up the branch
1671
initially, update it using the pull option periodically. Use
1672
this command in the top-level directory of the local copy:
1674
You can examine the changeset comments for the tree by using
1675
the log option to bzr:
1677
You can also browse changesets, comments, and source code
1678
online. To browse this information for MySQL 5.1, go to the
1679
Launchpad MySQL Server (http://launchpad.net/mysql-server)
1681
If you see diffs (changes) or code that you have a question
1682
about, do not hesitate to send email to the MySQL internals
1683
mailing list. See Section 1.6.1, "MySQL Mailing Lists." Also,
1684
if you think you have a better idea on how to do something,
1685
send an email message to the list with a patch.
1687
After you have the local branch, you can build MySQL server from
1688
the source code. On Windows, the build process is different from
1689
Unix/Linux: see Section 2.5.10, "Installing MySQL from Source on
1692
On Unix/Linux, use the autoconf system to create the configure
1693
script so that you can configure the build environment before
1694
building. The following example shows the typical commands
1695
required to build MySQL from a source tree.
1697
1. Change location to the top-level directory of the source tree;
1698
replace mysql-5.1 with the appropriate directory name.
1701
2. Prepare the source tree for configuration.
1702
Prior to MySQL 5.1.12, you must separately configure the
1703
InnoDB storage engine. Run the following command from the main
1705
shell> (cd storage/innobase; autoreconf --force --install)
1706
You can omit the previous command for MySQL 5.1.12 and later,
1707
or if you do not require InnoDB support.
1708
Prepare the remainder of the source tree:
1709
shell> autoreconf --force --install
1710
As an alternative to the preceding autoreconf command, you can
1711
use BUILD/autorun.sh, which acts as a shortcut for the
1712
following sequence of commands:
1713
shell> aclocal; autoheader
1714
shell> libtoolize --automake --force
1715
shell> automake --force --add-missing; autoconf
1716
If you get some strange errors during this stage, verify that
1717
you have the correct version of libtool installed.
1719
3. Configure the source tree and compile MySQL:
1720
shell> ./configure # Add your favorite options here
1722
For a description of some configure options, see Section
1723
2.3.2, "Typical configure Options."
1724
A collection of our standard configuration scripts is located
1725
in the BUILD/ subdirectory. For example, you may find it more
1726
convenient to use the BUILD/compile-pentium-debug script than
1727
the preceding set of shell commands. To compile on a different
1728
architecture, modify the script by removing flags that are
1729
Pentium-specific, or use another script that may be more
1730
appropriate. These scripts are provided on an "as-is" basis.
1731
They are not officially maintained and their contents may
1732
change from release to release.
1734
4. When the build is done, run make install. Be careful with this
1735
on a production machine; the command may overwrite your live
1736
release installation. If you already have MySQL installed and
1737
do not want to overwrite it, run ./configure with values for
1738
the --prefix, --with-tcp-port, and --with-unix-socket-path
1739
options different from those used for your production server.
1741
5. Play hard with your new installation and try to make the new
1742
features crash. Start by running make test. See Section
1743
22.1.2, "MySQL Test Suite."
1745
6. If you have gotten to the make stage, but the distribution
1746
does not compile, please enter the problem into our bugs
1747
database using the instructions given in Section 1.7, "How to
1748
Report Bugs or Problems." If you have installed the latest
1749
versions of the required GNU tools, and they crash trying to
1750
process our configuration files, please report that also.
1751
However, if you get a command not found error or a similar
1752
problem for aclocal, configure, or other required tools, do
1753
not report it. Instead, make sure that all the required tools
1754
are installed and that your PATH variable is set correctly so
1755
that your shell can find them.
1757
2.3.4. Dealing with Problems Compiling MySQL
1759
All MySQL programs compile cleanly for us with no warnings on
1760
Solaris or Linux using gcc. On other systems, warnings may occur
1761
due to differences in system include files. See Section 2.3.5,
1762
"MIT-pthreads Notes," for warnings that may occur when using
1763
MIT-pthreads. For other problems, check the following list.
1765
The solution to many problems involves reconfiguring. If you do
1766
need to reconfigure, take note of the following:
1768
* If configure is run after it has previously been run, it may
1769
use information that was gathered during its previous
1770
invocation. This information is stored in config.cache. When
1771
configure starts up, it looks for that file and reads its
1772
contents if it exists, on the assumption that the information
1773
is still correct. That assumption is invalid when you
1776
* Each time you run configure, you must run make again to
1777
recompile. However, you may want to remove old object files
1778
from previous builds first because they were compiled using
1779
different configuration options.
1781
To prevent old configuration information or object files from
1782
being used, run these commands before re-running configure:
1783
shell> rm config.cache
1786
Alternatively, you can run make distclean.
1788
The following list describes some of the problems when compiling
1789
MySQL that have been found to occur most often:
1791
* If you get errors such as the ones shown here when compiling
1792
sql_yacc.cc, you probably have run out of memory or swap
1794
Internal compiler error: program cc1plus got fatal signal 11
1795
Out of virtual memory
1796
Virtual memory exhausted
1797
The problem is that gcc requires a huge amount of memory to
1798
compile sql_yacc.cc with inline functions. Try running
1799
configure with the --with-low-memory option:
1800
shell> ./configure --with-low-memory
1801
This option causes -fno-inline to be added to the compile line
1802
if you are using gcc and -O0 if you are using something else.
1803
You should try the --with-low-memory option even if you have
1804
so much memory and swap space that you think you can't
1805
possibly have run out. This problem has been observed to occur
1806
even on systems with generous hardware configurations, and the
1807
--with-low-memory option usually fixes it.
1809
* By default, configure picks c++ as the compiler name and GNU
1810
c++ links with -lg++. If you are using gcc, that behavior can
1811
cause problems during configuration such as this:
1812
configure: error: installation or configuration problem:
1813
C++ compiler cannot create executables.
1814
You might also observe problems during compilation related to
1815
g++, libg++, or libstdc++.
1816
One cause of these problems is that you may not have g++, or
1817
you may have g++ but not libg++, or libstdc++. Take a look at
1818
the config.log file. It should contain the exact reason why
1819
your C++ compiler didn't work. To work around these problems,
1820
you can use gcc as your C++ compiler. Try setting the
1821
environment variable CXX to "gcc -O3". For example:
1822
shell> CXX="gcc -O3" ./configure
1823
This works because gcc compiles C++ source files as well as
1824
g++ does, but does not link in libg++ or libstdc++ by default.
1825
Another way to fix these problems is to install g++, libg++,
1826
and libstdc++. However, do not use libg++ or libstdc++ with
1827
MySQL because this only increases the binary size of mysqld
1828
without providing any benefits. Some versions of these
1829
libraries have also caused strange problems for MySQL users in
1832
* If your compile fails with errors such as any of the
1833
following, you must upgrade your version of make to GNU make:
1834
making all in mit-pthreads
1835
make: Fatal error in reader: Makefile, line 18:
1836
Badly formed macro assignment
1838
make: file `Makefile' line 18: Must be a separator (:
1840
pthread.h: No such file or directory
1841
Solaris and FreeBSD are known to have troublesome make
1843
GNU make 3.75 is known to work.
1845
* If you want to define flags to be used by your C or C++
1846
compilers, do so by adding the flags to the CFLAGS and
1847
CXXFLAGS environment variables. You can also specify the
1848
compiler names this way using CC and CXX. For example:
1853
shell> export CC CFLAGS CXX CXXFLAGS
1854
See Section 2.2, "Installing MySQL from Generic Binaries on
1855
Unix/Linux," for a list of flag definitions that have been
1856
found to be useful on various systems.
1858
* If you get errors such as those shown here when compiling
1859
mysqld, configure did not correctly detect the type of the
1860
last argument to accept(), getsockname(), or getpeername():
1861
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
1862
type of the pointer value ''length'' is ''unsigned long'',
1863
which is not compatible with ''int''.
1864
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
1865
To fix this, edit the config.h file (which is generated by
1866
configure). Look for these lines:
1867
/* Define as the base type of the last arg to accept */
1868
#define SOCKET_SIZE_TYPE XXX
1869
Change XXX to size_t or int, depending on your operating
1870
system. (You must do this each time you run configure because
1871
configure regenerates config.h.)
1873
* The sql_yacc.cc file is generated from sql_yacc.yy. Normally,
1874
the build process does not need to create sql_yacc.cc because
1875
MySQL comes with a pre-generated copy. However, if you do need
1876
to re-create it, you might encounter this error:
1877
"sql_yacc.yy", line xxx fatal: default action causes potential...
1878
This is a sign that your version of yacc is deficient. You
1879
probably need to install bison (the GNU version of yacc) and
1882
* On Debian Linux 3.0, you need to install gawk instead of the
1885
* If you need to debug mysqld or a MySQL client, run configure
1886
with the --with-debug option, and then recompile and link your
1887
clients with the new client library. See MySQL Internals:
1888
Porting (http://forge.mysql.com/wiki/MySQL_Internals_Porting).
1890
* If you get a compilation error on Linux (for example, SuSE
1891
Linux 8.1 or Red Hat Linux 7.3) similar to the following one,
1892
you probably do not have g++ installed:
1893
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
1894
incompatible pointer type
1895
libmysql.c:1329: too few arguments to function `gethostbyname_r'
1896
libmysql.c:1329: warning: assignment makes pointer from integer
1898
make[2]: *** [libmysql.lo] Error 1
1899
By default, the configure script attempts to determine the
1900
correct number of arguments by using g++ (the GNU C++
1901
compiler). This test yields incorrect results if g++ is not
1902
installed. There are two ways to work around this problem:
1904
+ Make sure that the GNU C++ g++ is installed. On some
1905
Linux distributions, the required package is called gpp;
1906
on others, it is named gcc-c++.
1908
+ Use gcc as your C++ compiler by setting the CXX
1909
environment variable to gcc:
1911
You must run configure again after making either of those
1914
2.3.5. MIT-pthreads Notes
1916
This section describes some of the issues involved in using
1919
On Linux, you should not use MIT-pthreads. Use the installed
1920
LinuxThreads implementation instead. See Section 2.6, "Installing
1923
If your system does not provide native thread support, you should
1924
build MySQL using the MIT-pthreads package. This includes older
1925
FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some
1926
others. See Section 2.1, "General Installation Guidance."
1928
MIT-pthreads is not part of the MySQL 5.1 source distribution. If
1929
you require this package, you need to download it separately from
1930
http://dev.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.t
1933
After downloading, extract this source archive into the top level
1934
of the MySQL source directory. It creates a new subdirectory named
1937
* On most systems, you can force MIT-pthreads to be used by
1938
running configure with the --with-mit-threads option:
1939
shell> ./configure --with-mit-threads
1940
Building in a nonsource directory is not supported when using
1941
MIT-pthreads because we want to minimize our changes to this
1944
* The checks that determine whether to use MIT-pthreads occur
1945
only during the part of the configuration process that deals
1946
with the server code. If you have configured the distribution
1947
using --without-server to build only the client code, clients
1948
do not know whether MIT-pthreads is being used and use Unix
1949
socket file connections by default. Because Unix socket files
1950
do not work under MIT-pthreads on some platforms, this means
1951
you need to use -h or --host with a value other than localhost
1952
when you run client programs.
1954
* When MySQL is compiled using MIT-pthreads, system locking is
1955
disabled by default for performance reasons. You can tell the
1956
server to use system locking with the --external-locking
1957
option. This is needed only if you want to be able to run two
1958
MySQL servers against the same data files, but that is not
1959
recommended, anyway.
1961
* Sometimes the pthread bind() command fails to bind to a socket
1962
without any error message (at least on Solaris). The result is
1963
that all connections to the server fail. For example:
1964
shell> mysqladmin version
1965
mysqladmin: connect to server at '' failed;
1966
error: 'Can't connect to mysql server on localhost (146)'
1967
The solution to this problem is to kill the mysqld server and
1968
restart it. This has happened to us only when we have forcibly
1969
stopped the server and restarted it immediately.
1971
* With MIT-pthreads, the sleep() system call isn't interruptible
1972
with SIGINT (break). This is noticeable only when you run
1973
mysqladmin --sleep. You must wait for the sleep() call to
1974
terminate before the interrupt is served and the process
1977
* When linking, you might receive warning messages like these
1978
(at least on Solaris); they can be ignored:
1979
ld: warning: symbol `_iob' has differing sizes:
1980
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
1981
file /usr/lib/libc.so value=0x140);
1982
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
1983
ld: warning: symbol `__iob' has differing sizes:
1984
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
1985
file /usr/lib/libc.so value=0x140);
1986
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
1988
* Some other warnings also can be ignored:
1989
implicit declaration of function `int strtoll(...)'
1990
implicit declaration of function `int strtoul(...)'
1992
* We have not been able to make readline work with MIT-pthreads.
1993
(This is not necessary, but may be of interest to some.)
1995
2.4. Upgrading or Downgrading MySQL
1997
2.4.1. Upgrading MySQL
1999
As a general rule, to upgrade from one release series to another,
2000
you should go to the next series rather than skipping a series. To
2001
upgrade from a release series previous to MySQL 5.0, upgrade to
2002
each successive release series in turn until you have reached
2003
MySQL 5.0, and then proceed with the upgrade to MySQL 5.1. For
2004
example, if you currently are running MySQL 4.0 and wish to
2005
upgrade to a newer series, upgrade to MySQL 4.1 first before
2006
upgrading to 5.0, and so forth. For information on upgrading to
2007
MySQL 5.0, see the MySQL 5.0 Reference Manual; for earlier
2008
releases, see the MySQL 3.23, 4.0, 4.1 Reference Manual.
2010
If you perform a binary (in-place) upgrade without dumping and
2011
reloading tables, you cannot upgrade directly from MySQL 4.1 to
2012
5.1. This occurs due to an incompatible change in the MyISAM table
2013
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
2014
repair all MyISAM tables (see Section 2.4.4, "Rebuilding or
2015
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
2016
and check and repair your tables.
2018
To upgrade from MySQL 5.0 to 5.1, use the items in the following
2019
checklist as a guide:
2021
* Before any upgrade, back up your databases, including the
2022
mysql database that contains the grant tables. See Section
2023
6.2, "Database Backup Methods."
2025
* Read all the notes in Section 2.4.1.1, "Upgrading from MySQL
2026
5.0 to 5.1." These notes enable you to identify upgrade issues
2027
that apply to your current MySQL installation. Some
2028
incompatibilities discussed in that section require your
2029
attention before upgrading. Others should be dealt with after
2032
* Read Appendix C, "MySQL Change History" as well, which
2033
provides information about features that are new in MySQL 5.1
2034
or differ from those found in MySQL 5.0.
2036
* After you upgrade to a new version of MySQL, run mysql_upgrade
2037
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
2038
Upgrade"). This program checks your tables, and attempts to
2039
repair them if necessary. It also updates your grant tables to
2040
make sure that they have the current structure so that you can
2041
take advantage of any new capabilities. (Some releases of
2042
MySQL introduce changes to the structure of the grant tables
2043
to add new privileges or features.)
2045
* If you are running MySQL Server on Windows, see Section 2.5.7,
2046
"Upgrading MySQL on Windows."
2048
* If you are using replication, see Section 16.4.3, "Upgrading a
2049
Replication Setup," for information on upgrading your
2052
* If you are upgrading an installation originally produced by
2053
installing multiple RPM packages, it is best to upgrade all
2054
the packages, not just some. For example, if you previously
2055
installed the server and client RPMs, do not upgrade just the
2058
* As of MySQL 5.1.9, the mysqld-max server is included in binary
2059
distributions. There is no separate MySQL-Max distribution. As
2060
of MySQL 5.1.12, there is no mysqld-max server at all in
2061
binary distributions. They contain a server that includes the
2062
features previously included in mysqld-max.
2064
* If you have created a user-defined function (UDF) with a given
2065
name and upgrade MySQL to a version that implements a new
2066
built-in function with the same name, the UDF becomes
2067
inaccessible. To correct this, use DROP FUNCTION to drop the
2068
UDF, and then use CREATE FUNCTION to re-create the UDF with a
2069
different nonconflicting name. The same is true if the new
2070
version of MySQL implements a built-in function with the same
2071
name as an existing stored function. See Section 8.2.4,
2072
"Function Name Parsing and Resolution," for the rules
2073
describing how the server interprets references to different
2076
You can always move the MySQL format files and data files between
2077
different versions on systems with the same architecture as long
2078
as you stay within versions for the same release series of MySQL.
2080
If you are cautious about using new versions, you can always
2081
rename your old mysqld before installing a newer one. For example,
2082
if you are using MySQL 5.0.13 and want to upgrade to 5.1.10,
2083
rename your current server from mysqld to mysqld-5.0.13. If your
2084
new mysqld then does something unexpected, you can simply shut it
2085
down and restart with your old mysqld.
2087
If, after an upgrade, you experience problems with recompiled
2088
client programs, such as Commands out of sync or unexpected core
2089
dumps, you probably have used old header or library files when
2090
compiling your programs. In this case, you should check the date
2091
for your mysql.h file and libmysqlclient.a library to verify that
2092
they are from the new MySQL distribution. If not, recompile your
2093
programs with the new headers and libraries.
2095
If problems occur, such as that the new mysqld server does not
2096
start or that you cannot connect without a password, verify that
2097
you do not have an old my.cnf file from your previous
2098
installation. You can check this with the --print-defaults option
2099
(for example, mysqld --print-defaults). If this command displays
2100
anything other than the program name, you have an active my.cnf
2101
file that affects server or client operation.
2103
If your MySQL installation contains a large amount of data that
2104
might take a long time to convert after an in-place upgrade, you
2105
might find it useful to create a "dummy" database instance for
2106
assessing what conversions might be needed and the work involved
2107
to perform them. Make a copy of your MySQL instance that contains
2108
a full copy of the mysql database, plus all other databases
2109
without data. Run your upgrade procedure on this dummy instance to
2110
see what actions might be needed so that you can better evaluate
2111
the work involved when performing actual data conversion on your
2112
original database instance.
2114
It is a good idea to rebuild and reinstall the Perl DBD::mysql
2115
module whenever you install a new release of MySQL. The same
2116
applies to other MySQL interfaces as well, such as PHP mysql
2117
extensions and the Python MySQLdb module.
2119
2.4.1.1. Upgrading from MySQL 5.0 to 5.1
2121
After upgrading a 5.0 installation to 5.0.10 or above, it is
2122
necessary to upgrade your grant tables. Otherwise, creating stored
2123
procedures and functions might not work. To perform this upgrade,
2128
It is good practice to back up your data before installing any new
2129
version of software. Although MySQL works very hard to ensure a
2130
high level of quality, you should protect your data by making a
2133
To upgrade to 5.1 from any previous version, MySQL recommends that
2134
you dump your tables with mysqldump before upgrading and reload
2135
the dump file after upgrading.
2137
If you perform a binary (in-place) upgrade without dumping and
2138
reloading tables, you cannot upgrade directly from MySQL 4.1 to
2139
5.1. This occurs due to an incompatible change in the MyISAM table
2140
index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
2141
repair all MyISAM tables (see Section 2.4.4, "Rebuilding or
2142
Repairing Tables or Indexes"). Then upgrade from MySQL 5.0 to 5.1
2143
and check and repair your tables.
2145
In general, you should do the following when upgrading from MySQL
2148
* Read all the items in the following sections to see whether
2149
any of them might affect your applications:
2151
+ Section 2.4.1, "Upgrading MySQL," has general update
2154
+ The items in the change lists found later in this section
2155
enable you to identify upgrade issues that apply to your
2156
current MySQL installation.
2158
+ The MySQL 5.1 change history describes significant new
2159
features you can use in 5.1 or that differ from those
2160
found in MySQL 5.0. Some of these changes may result in
2161
incompatibilities. See Section C.1, "Changes in Release
2162
5.1.x (Production)."
2164
* Note particularly any changes that are marked Known issue or
2165
Incompatible change. These incompatibilities with earlier
2166
versions of MySQL may require your attention before you
2168
Our aim is to avoid these changes, but occasionally they are
2169
necessary to correct problems that would be worse than an
2170
incompatibility between releases. If any upgrade issue
2171
applicable to your installation involves an incompatibility
2172
that requires special handling, follow the instructions given
2173
in the incompatibility description. Often this will involve a
2174
dump and reload, or use of a statement such as CHECK TABLE or
2176
For dump and reload instructions, see Section 2.4.4,
2177
"Rebuilding or Repairing Tables or Indexes." Any procedure
2178
that involves REPAIR TABLE with the USE_FRM option must be
2179
done before upgrading. Use of this statement with a version of
2180
MySQL different from the one used to create the table (that
2181
is, using it after upgrading) may damage the table. See
2182
Section 12.5.2.6, "REPAIR TABLE Syntax."
2184
* After you upgrade to a new version of MySQL, run mysql_upgrade
2185
(see Section 4.4.8, "mysql_upgrade --- Check Tables for MySQL
2186
Upgrade"). This program checks your tables, and attempts to
2187
repair them if necessary. It also updates your grant tables to
2188
make sure that they have the current structure so that you can
2189
take advantage of any new capabilities. (Some releases of
2190
MySQL introduce changes to the structure of the grant tables
2191
to add new privileges or features.)
2193
* Check Section 2.4.3, "Checking Whether Tables or Indexes Must
2194
Be Rebuilt," to see whether changes to table formats or to
2195
character sets or collations were made between your current
2196
version of MySQL and the version to which you are upgrading.
2197
If so and these changes result in an incompatibility between
2198
MySQL versions, you will need to upgrade the affected tables
2199
using the instructions in Section 2.4.4, "Rebuilding or
2200
Repairing Tables or Indexes."
2202
* If you are running MySQL Server on Windows, see Section 2.5.7,
2203
"Upgrading MySQL on Windows."
2205
* If you are using replication, see Section 16.4.3, "Upgrading a
2206
Replication Setup," for information on upgrading your
2209
If your MySQL installation contains a large amount of data that
2210
might take a long time to convert after an in-place upgrade, you
2211
might find it useful to create a "dummy" database instance for
2212
assessing what conversions might be needed and the work involved
2213
to perform them. Make a copy of your MySQL instance that contains
2214
a full copy of the mysql database, plus all other databases
2215
without data. Run your upgrade procedure on this dummy instance to
2216
see what actions might be needed so that you can better evaluate
2217
the work involved when performing actual data conversion on your
2218
original database instance.
2220
MySQL Enterprise MySQL Enterprise subscribers will find more
2221
information about upgrading in the Knowledge Base articles found
2223
(https://kb.mysql.com/search.php?cat=search&category=41). Access
2224
to the MySQL Knowledge Base collection of articles is one of the
2225
advantages of subscribing to MySQL Enterprise. For more
2227
http://www.mysql.com/products/enterprise/advisors.html.
2229
The following lists describe changes that may affect applications
2230
and that you should watch out for when upgrading to MySQL 5.1.
2232
Configuration Changes:
2234
* Before MySQL 5.1.11, to build MySQL from source with SSL
2235
support enabled, you would invoke configure with either the
2236
--with-openssl or --with-yassl option. In MySQL 5.1.11, those
2237
options both have been replaced by the --with-ssl option. By
2238
default, --with-ssl causes the bundled yaSSL library to be
2239
used. To select OpenSSL instead, give the option as
2240
--with-ssl=path, where path is the directory where the OpenSSL
2241
header files and libraries are located.
2245
* Known issue: After a binary upgrade to MySQL 5.1 from a MySQL
2246
5.0 installation that contains ARCHIVE tables, accessing those
2247
tables will cause the server to crash, even if you have run
2248
mysql_upgrade or CHECK TABLE ... FOR UPGRADE. To work around
2249
this problem, use mysqldump to dump all ARCHIVE tables before
2250
upgrading, and reload them into MySQL 5.1 after upgrading.
2252
* Known issue: The fix for
2253
Bug#23491: http://bugs.mysql.com/bug.php?id=23491 introduced a
2254
problem with SHOW CREATE VIEW, which is used by mysqldump.
2255
This causes an incompatibility when upgrading from versions
2256
affected by that bug fix (MySQL 5.0.40 through 5.0.43, MySQL
2257
5.1.18 through 5.1.19): If you use mysqldump before upgrading
2258
from an affected version and reload the data after upgrading
2259
to a higher version, you must drop and recreate your views.
2261
* Known issue: Dumps performed by using mysqldump to generate a
2262
dump file before the upgrade and reloading the file after
2263
upgrading are subject to the following problem:
2264
Before MySQL 5.0.40, mysqldump displays SPATIAL index
2265
definitions using prefix lengths for the indexed columns.
2266
These prefix lengths are accepted in MySQL 5.0, but not as of
2267
MySQL 5.1. If you use mysqldump from versions of MySQL older
2268
than 5.0.40, any table containing SPATIAL indexes will cause
2269
an error when the dump file is reloaded into MySQL 5.1 or
2271
For example, a table definition might look like this when
2272
dumped in MySQL 5.0:
2274
`g` geometry NOT NULL,
2275
SPATIAL KEY `g` (`g`(32))
2276
) ENGINE=MyISAM DEFAULT CHARSET=latin1
2277
The SPATIAL index definition will not be accepted in MySQL
2278
5.1. To work around this, edit the dump file to remove the
2281
`g` geometry NOT NULL,
2282
SPATIAL KEY `g` (`g`)
2283
) ENGINE=MyISAM DEFAULT CHARSET=latin1
2284
Dump files can be large, so it may be preferable to dump table
2285
definitions and data separately to make it easier to edit the
2287
shell> mysqldump --no-data other_args > definitions.sql
2288
shell> mysqldump --no-create-info other_args > data.sql
2289
Then edit definitions.sql before reloading definitions.sql and
2290
data.sql, in that order.
2291
If you upgrade to a version of MySQL 5.0 higher than 5.0.40
2292
before upgrading to MySQL 5.1, this problem does not occur.
2294
* Known issue: Before MySQL 5.1.30, the CHECK TABLE ... FOR
2295
UPGRADE statement did not check for incompatible collation
2296
changes made in MySQL 5.1.24. (This also affects mysqlcheck
2297
and mysql_upgrade, which cause that statement to be executed.)
2298
Prior to the fix made in 5.1.30, a binary upgrade (performed
2299
without dumping tables with mysqldump before the upgrade and
2300
reloading the dump file after the upgrade) would corrupt
2301
tables. After the fix, CHECK TABLE ... FOR UPGRADE properly
2302
detects the problem and warns about tables that need repair.
2303
However, the fix is not backward compatible and can result in
2304
a downgrading problem under these circumstances:
2306
1. Perform a binary upgrade to a version of MySQL that
2309
2. Run CHECK TABLE ... FOR UPGRADE (or mysqlcheck or
2310
mysql_upgrade) to upgrade tables.
2312
3. Perform a binary downgrade to a version of MySQL that
2313
does not include the fix.
2314
The solution is to dump tables with mysqldump before the
2315
downgrade and reload the dump file after the downgrade.
2316
Alternatively, drop and recreate affected indexes.
2318
* Known issue: MySQL introduces encoding for table names that
2319
have non-ASCII characters (see Section 8.2.3, "Mapping of
2320
Identifiers to File Names"). After a binary upgrade from MySQL
2321
5.0 to 5.1 or higher, the server recognizes names that have
2322
non-ASCII characters and adds a #mysql50# prefix to them.
2323
As of MySQL 5.1.31, mysql_upgrade encodes these names by
2324
executing the following command:
2325
mysqlcheck --all-databases --check-upgrade --fix-db-names --fix-table
2327
Prior to MySQL 5.1.31, mysql_upgrade does not execute this
2328
command, so you should execute it manually if you have
2329
database or table names that contain nonalphanumeric
2331
Prior to MySQL 5.1.23, the mysqlcheck command does not perform
2332
the name encoding for views. To work around this problem, drop
2333
each affected view and recreate it.
2334
mysqlcheck cannot fix names that contain literal instances of
2335
the @ character that is used for encoding special characters.
2336
If you have databases or tables that contain this character,
2337
use mysqldump to dump them before upgrading to MySQL 5.1, and
2338
then reload the dump file after upgrading.
2340
* Known issue: When upgrading from MySQL 5.0 to versions of 5.1
2341
prior to 5.1.23, running mysqlcheck (or mysql_upgrade, which
2342
runs mysqlcheck) to upgrade tables fails for names that must
2343
be written as quoted identifiers. To work around this problem,
2344
rename each affected table to a name that does not require
2346
RENAME TABLE `tab``le_a` TO table_a;
2347
RENAME TABLE `table b` TO table_b;
2348
After renaming the tables, run the mysql_upgrade program. Then
2349
rename the tables back to their original names:
2350
RENAME TABLE table_a TO `tab``le_a`;
2351
RENAME TABLE table_b TO `table b`;
2353
* Known issue: In connection with view creation, the server
2354
created arc directories inside database directories and
2355
maintained useless copies of .frm files there. Creation and
2356
renaming procedures of those copies as well as creation of arc
2357
directories has been discontinued in MySQL 5.1.29.
2358
This change does cause a problem when downgrading to older
2359
server versions which manifests itself under these
2362
1. Create a view v_orig in MySQL 5.1.29 or higher.
2364
2. Rename the view to v_new and then back to v_orig.
2366
3. Downgrade to an older 5.1.x server and run mysql_upgrade.
2368
4. Try to rename v_orig to v_new again. This operation
2370
As a workaround to avoid this problem, use either of these
2373
+ Dump your data using mysqldump before downgrading and
2374
reload the dump file after downgrading.
2376
+ Instead of renaming a view after the downgrade, drop it
2379
* Incompatible change: Character set or collation changes were
2380
made in MySQL 5.1.21, 5.1.23, and 5.1.24 that may require
2381
table indexes to be rebuilt. For details, see Section 2.4.3,
2382
"Checking Whether Tables or Indexes Must Be Rebuilt."
2384
* Incompatible change: MySQL 5.1 implements support for a plugin
2385
API that allows the loading and unloading of components at
2386
runtime, without restarting the server. Section 22.2, "The
2387
MySQL Plugin Interface." The plugin API requires the
2388
mysql.plugin table. After upgrading from an older version of
2389
MySQL, you should run the mysql_upgrade command to create this
2390
table. See Section 4.4.8, "mysql_upgrade --- Check Tables for
2392
Plugins are installed in the directory named by the plugin_dir
2393
system variable. This variable also controls the location from
2394
which the server loads user-defined functions (UDFs), which is
2395
a change from earlier versions of MySQL. That is, all UDF
2396
library files now must be installed in the plugin directory.
2397
When upgrading from an older version of MySQL, you must
2398
migrate your UDF files to the plugin directory.
2400
* Incompatible change: The table_cache system variable has been
2401
renamed to table_open_cache. Any scripts that refer to
2402
table_cache must be updated to use the new name.
2404
* Incompatible change: In MySQL 5.1.36, options for loading
2405
plugins such as pluggable storage engines were changed from
2406
boolean to tristate format. The implementations overlap, but
2407
if you previously used options of the form --plugin_name=0 or
2408
--plugin_name=1, you should instead use --plugin_name=OFF or
2409
--plugin_name=ON, respectively. For details, see Section
2410
5.1.3, "Server Options for Loading Plugins."
2412
* Incompatible change: From MySQL 5.1.24 to 5.1.31, the UPDATE
2413
statement was changed such that assigning NULL to a NOT NULL
2414
column caused an error even when strict SQL mode was not
2415
enabled. The original behavior before MySQL 5.1.24 was that
2416
such assignments caused an error only in strict SQL mode, and
2417
otherwise set the column to the implicit default value for the
2418
column data type and generated a warning. (For information
2419
about implicit default values, see Section 10.1.4, "Data Type
2421
The change caused compatibility problems for applications that
2422
relied on the original behavior. It also caused replication
2423
problems between servers that had the original behavior and
2424
those that did not, for applications that assigned NULL to NOT
2425
NULL columns in UPDATE statements without strict SQL mode
2426
enabled. The change was reverted in MySQL 5.1.32 so that
2427
UPDATE again had the original behavior. Problems can still
2428
occur if you replicate between servers that have the modified
2429
UPDATE behavior and those that do not.
2431
* Incompatible change: As of MySQL 5.1.29, the default binary
2432
logging mode has been changed from MIXED to STATEMENT for
2433
compatibility with MySQL 5.0.
2435
* Incompatible change: In MySQL 5.1.25, a change was made to the
2436
way that the server handles prepared statements. This affects
2437
prepared statements processed at the SQL level (using the
2438
PREPARE statement) and those processed using the binary
2439
client-server protocol (using the mysql_stmt_prepare() C API
2441
Previously, changes to metadata of tables or views referred to
2442
in a prepared statement could cause a server crash when the
2443
statement was next executed, or perhaps an error at execute
2444
time with a crash occurring later. For example, this could
2445
happen after dropping a table and recreating it with a
2446
different definition.
2447
Now metadata changes to tables or views referred to by
2448
prepared statements are detected and cause automatic
2449
repreparation of the statement when it is next executed.
2450
Metadata changes occur for DDL statements such as those that
2451
create, drop, alter, rename, or truncate tables, or that
2452
analyze, optimize, or repair tables. Repreparation also occurs
2453
after referenced tables or views are flushed from the table
2454
definition cache, either implicitly to make room for new
2455
entries in the cache, or explicitly due to FLUSH TABLES.
2456
Repreparation is automatic, but to the extent that it occurs,
2457
performance of prepared statements is diminished.
2458
Table content changes (for example, with INSERT or UPDATE) do
2459
not cause repreparation, nor do SELECT statements.
2460
An incompatibility with previous versions of MySQL is that a
2461
prepared statement may now return a different set of columns
2462
or different column types from one execution to the next. For
2463
example, if the prepared statement is SELECT * FROM t1,
2464
altering t1 to contain a different number of columns causes
2465
the next execution to return a number of columns different
2466
from the previous execution.
2467
Older versions of the client library cannot handle this change
2468
in behavior. For applications that use prepared statements
2469
with the new server, an upgrade to the new client library is
2470
strongly recommended.
2471
Along with this change to statement repreparation, the default
2472
value of the table_definition_cache system variable has been
2473
increased from 128 to 256. The purpose of this increase is to
2474
lessen the chance that prepared statements will need
2475
repreparation due to referred-to tables/views having been
2476
flushed from the cache to make room for new entries.
2477
A new status variable, Com_stmt_reprepare, has been introduced
2478
to track the number of repreparations.
2480
* Incompatible change: As of MySQL 5.1.23, within a stored
2481
routine, it is no longer allowable to declare a cursor for a
2482
SHOW or DESCRIBE statement. This happened to work in some
2483
instances, but is no longer supported. In many cases, a
2484
workaround for this change is to use the cursor with a SELECT
2485
query to read from an INFORMATION_SCHEMA table that produces
2486
the same information as the SHOW statement.
2488
* Incompatible change: SHOW CREATE VIEW displays view
2489
definitions using an AS alias_name clause for each column. If
2490
a column is created from an expression, the default alias is
2491
the expression text, which can be quite long. As of MySQL
2492
5.1.23, aliases for column names in CREATE VIEW statements are
2493
checked against the maximum column length of 64 characters
2494
(not the maximum alias length of 256 characters). As a result,
2495
views created from the output of SHOW CREATE VIEW fail if any
2496
column alias exceeds 64 characters. This can cause problems
2497
for replication or loading dump files. For additional
2498
information and workarounds, see Section D.4, "Restrictions on
2501
* Incompatible change: Several issues were identified for stored
2502
programs (stored procedures and functions, triggers, and
2503
events) and views containing non-ASCII symbols. These issues
2504
involved conversion errors due to incomplete character set
2505
information when translating these objects to and from stored
2507
To address these problems, the representation for these
2508
objects was changed in MySQL 5.1.21. However, the fixes affect
2509
all stored programs and views. (For example, you will see
2510
warnings about "no creation context.") To avoid warnings from
2511
the server about the use of old definitions from any release
2512
prior to 5.1.21, you should dump stored programs and views
2513
with mysqldump after upgrading to 5.1.21 or higher, and then
2514
reload them to recreate them with new definitions. Invoke
2515
mysqldump with a --default-character-set option that names the
2516
non-ASCII character set that was used for the definitions when
2517
the objects were originally defined.
2519
* Incompatible change: As of MySQL 5.1.20, mysqld_safe supports
2520
error logging to syslog on systems that support the logger
2521
command. The new --syslog and --skip-syslog options can be
2522
used instead of the --log-error option to control logging
2523
behavior, as described in Section 4.3.2, "mysqld_safe ---
2524
MySQL Server Startup Script."
2525
In 5.1.21 and up, the default is --skip-syslog, which is
2526
compatible with the default behavior of writing an error log
2527
file for releases prior to 5.1.20.
2528
In 5.1.20 only, the following conditions apply: 1) The default
2529
is to use syslog, which is not compatible with releases prior
2530
to 5.1.20. 2) Logging to syslog may fail to operate correctly
2531
in some cases. For these reasons, avoid using MySQL 5.1.20.
2533
* Incompatible change: As of MySQL 5.1.18, the plugin interface
2534
and its handling of system variables was changed. Command-line
2535
options such as --skip-innodb now cause an error if InnoDB is
2536
not built-in or plugin-loaded. You should use
2537
--loose-skip-innodb if you do not want any error even if
2538
InnoDB is not available. The --loose prefix modifier should be
2539
used for all command-line options where you are uncertain
2540
whether the plugin exists and when you want the operation to
2541
proceed even if the option is necessarily ignored due to the
2542
absence of the plugin. (For a desecription of how --loose
2543
works, see Section 4.2.3.1, "Using Options on the Command
2546
* Incompatible change: As of MySQL 5.1.15, InnoDB rolls back
2547
only the last statement on a transaction timeout. A new
2548
option, --innodb_rollback_on_timeout, causes InnoDB to abort
2549
and roll back the entire transaction if a transaction timeout
2550
occurs (the same behavior as in MySQL 4.1).
2552
* Incompatible change: As of MySQL 5.1.15, the following
2553
conditions apply to enabling the read_only system variable:
2555
+ If you attempt to enable read_only while you have any
2556
explicit locks (acquired with LOCK TABLES or have a
2557
pending transaction, an error will occur.
2559
+ If other clients hold explicit table locks or have
2560
pending transactions, the attempt to enable read_only
2561
blocks until the locks are released and the transactions
2562
end. While the attempt to enable read_only is pending,
2563
requests by other clients for table locks or to begin
2564
transactions also block until read_only has been set.
2566
+ read_only can be enabled while you hold a global read
2567
lock (acquired with FLUSH TABLES WITH READ LOCK) because
2568
that does not involve table locks.
2569
Previously, the attempt to enable read_only would return
2570
immediately even if explicit locks or transactions were
2571
pending, so some data changes could occur for statements
2572
executing in the server at the same time.
2574
* Incompatible change: The number of function names affected by
2575
IGNORE_SPACE was reduced significantly in MySQL 5.1.13, from
2576
about 200 to about 30. (For details about IGNORE_SPACE, see
2577
Section 8.2.4, "Function Name Parsing and Resolution.") This
2578
change improves the consistency of parser operation. However,
2579
it also introduces the possibility of incompatibility for old
2580
SQL code that relies on the following conditions:
2582
+ IGNORE_SPACE is disabled.
2584
+ The presence or absence of whitespace following a
2585
function name is used to distinguish between a built-in
2586
function and stored function that have the same name (for
2587
example, PI() versus PI ()).
2588
For functions that are no longer affected by IGNORE_SPACE as
2589
of MySQL 5.1.13, that strategy no longer works. Either of the
2590
following approaches can be used if you have code that is
2591
subject to the preceding incompatibility:
2593
+ If a stored function has a name that conflicts with a
2594
built-in function, refer to the stored function with a
2595
schema name qualifier, regardless of whether whitespace
2596
is present. For example, write schema_name.PI() or
2599
+ Alternatively, rename the stored function to use a
2600
nonconflicting name and change invocations of the
2601
function to use the new name.
2603
* Incompatible change: For utf8 columns, the full-text parser
2604
incorrectly considered several nonword punctuation and
2605
whitespace characters as word characters, causing some
2606
searches to return incorrect results. The fix involves a
2607
change to the full-text parser in MySQL 5.1.12, so as of
2608
5.1.12, any tables that have FULLTEXT indexes on utf8 columns
2609
must be repaired with REPAIR TABLE:
2610
REPAIR TABLE tbl_name QUICK;
2612
* Incompatible change: Storage engines can be pluggable at
2613
runtime, so the distinction between disabled and invalid
2614
storage engines no longer applies. As of MySQL 5.1.12, this
2615
affects the NO_ENGINE_SUBSTITUTION SQL mode, as described in
2616
Section 5.1.8, "Server SQL Modes."
2618
* Incompatible change: The structure of FULLTEXT indexes has
2619
been changed in MySQL 5.1.6. After upgrading to MySQL 5.1.6 or
2620
greater, any tables that have FULLTEXT indexes must be
2621
repaired with REPAIR TABLE:
2622
REPAIR TABLE tbl_name QUICK;
2624
* Incompatible change: In MySQL 5.1.6, when log tables were
2625
implemented, the default log destination for the general query
2626
and slow query log was TABLE. As of MySQL 5.1.21, this default
2627
has been changed to FILE, which is compatible with MySQL 5.0,
2628
but incompatible with earlier releases of MySQL 5.1. If you
2629
are upgrading from MySQL 5.0 to 5.1.21 or higher, no logging
2630
option changes should be necessary. However, if you are
2631
upgrading from 5.1.6 through 5.1.20 to 5.1.21 or higher and
2632
were using TABLE logging, use the --log-output=TABLE option
2633
explicitly to preserve your server's table-logging behavior.
2635
* Incompatible change: For ENUM columns that had enumeration
2636
values containing commas, the commas were mapped to 0xff
2637
internally. However, this rendered the commas
2638
indistinguishable from true 0xff characters in the values.
2639
This no longer occurs. However, the fix requires that you dump
2640
and reload any tables that have ENUM columns containing true
2641
0xff in their values: Dump the tables using mysqldump with the
2642
current server before upgrading from a version of MySQL 5.1
2643
older than 5.1.15 to version 5.1.15 or newer.
2645
* As of MySQL 5.1.12, the lc_time_names system variable
2646
specifies the locale that controls the language used to
2647
display day and month names and abbreviations. This variable
2648
affects the output from the DATE_FORMAT(), DAYNAME() and
2649
MONTHNAME() functions. See Section 9.7, "MySQL Server Locale
2652
* As of MySQL 5.1.9, mysqld_safe no longer implicitly invokes
2653
mysqld-max if it exists. Instead, it invokes mysqld unless a
2654
--mysqld or --mysqld-version option is given to specify
2655
another server explicitly. If you previously relied on the
2656
implicit invocation of mysqld-max, you should use an
2657
appropriate option now. As of MySQL 5.1.12, there is no longer
2658
any separate mysqld-max server, so no change should be
2663
* Known issue: Prior to MySQL 5.1.17, the parser accepted
2664
invalid code in SQL condition handlers, leading to server
2665
crashes or unexpected execution behavior in stored programs.
2666
Specifically, the parser allowed a condition handler to refer
2667
to labels for blocks that enclose the handler declaration.
2668
This was incorrect because block label scope does not include
2669
the code for handlers declared within the labeled block.
2670
As of 5.1.17, the parser rejects this invalid construct, but
2671
if you perform a binary upgrade (without dumping and reloading
2672
your databases), existing handlers that contain the construct
2673
still are invalid and should be rewritten even if they appear
2674
to function as you expect.
2675
To find affected handlers, use mysqldump to dump all stored
2676
procedures and functions, triggers, and events. Then attempt
2677
to reload them into an upgraded server. Handlers that contain
2678
illegal label references will be rejected.
2679
For more information about condition handlers and writing them
2680
to avoid invalid jumps, see Section 12.8.4.2, "DECLARE for
2683
* Incompatible change: The parser accepted statements that
2684
contained /* ... */ that were not properly closed with */,
2685
such as SELECT 1 /* + 2. As of MySQL 5.1.23, statements that
2686
contain unclosed /*-comments now are rejected with a syntax
2688
This fix has the potential to cause incompatibilities. Because
2689
of Bug#26302: http://bugs.mysql.com/bug.php?id=26302, which
2690
caused the trailing */ to be truncated from comments in views,
2691
stored routines, triggers, and events, it is possible that
2692
objects of those types may have been stored with definitions
2693
that now will be rejected as syntactically invalid. Such
2694
objects should be dropped and re-created so that their
2695
definitions do not contain truncated comments.
2697
* Incompatible change: Multiple-table DELETE statements
2698
containing ambiguous aliases could have unintended side
2699
effects such as deleting rows from the wrong table. Example:
2700
DELETE FROM t1 AS a2 USING t1 AS a1 INNER JOIN t2 AS a2;
2701
As of MySQL 5.1.23, alias declarations can be declared only in
2702
the table_references part. Elsewhere in the statement, alias
2703
references are allowed but not alias declarations. Statements
2704
containing aliases that are no longer allowed must be
2707
* Incompatible change: As of MySQL 5.1.8, TYPE = engine_name is
2708
still accepted as a synonym for the ENGINE = engine_name table
2709
option but generates a warning. You should note that this
2710
option is not available in MySQL 5.1.7, and is removed
2711
altogether as of MySQL 5.4 and produces a syntax error.
2712
TYPE has been deprecated since MySQL 4.0.
2714
* Incompatible change: The namespace for triggers changed in
2715
MySQL 5.0.10. Previously, trigger names had to be unique per
2716
table. Now they must be unique within the schema (database).
2717
An implication of this change is that DROP TRIGGER syntax now
2718
uses a schema name instead of a table name (schema name is
2719
optional and, if omitted, the current schema will be used).
2720
When upgrading from a version of MySQL 5 older than 5.0.10 to
2721
MySQL 5.0.10 or newer, you must drop all triggers and
2722
re-create them or DROP TRIGGER will not work after the
2723
upgrade. Here is a suggested procedure for doing this:
2725
1. Upgrade to MySQL 5.0.10 or later to be able to access
2726
trigger information in the INFORMATION_SCHEMA.TRIGGERS
2727
table. (This should work even for pre-5.0.10 triggers.)
2729
2. Dump all trigger definitions using the following SELECT
2731
SELECT CONCAT('CREATE TRIGGER ', t.TRIGGER_SCHEMA, '.', t.TRIGGER_NAM
2733
' ', t.ACTION_TIMING, ' ', t.EVENT_MANIPULATION, ' ON '
2735
t.EVENT_OBJECT_SCHEMA, '.', t.EVENT_OBJECT_TABLE,
2736
' FOR EACH ROW ', t.ACTION_STATEMENT, '//' )
2737
INTO OUTFILE '/tmp/triggers.sql'
2738
FROM INFORMATION_SCHEMA.TRIGGERS AS t;
2739
The statement uses INTO OUTFILE, so you must have the
2740
FILE privilege. The file will be created on the server
2741
host. Use a different file name if you like. To be 100%
2742
safe, inspect the trigger definitions in the triggers.sql
2743
file, and perhaps make a backup of the file.
2745
3. Stop the server and drop all triggers by removing all
2746
.TRG files in your database directories. Change location
2747
to your data directory and issue this command:
2750
4. Start the server and re-create all triggers using the
2752
mysql> delimiter // ;
2753
mysql> source /tmp/triggers.sql //
2755
5. Check that all triggers were successfully created using
2756
the SHOW TRIGGERS statement.
2758
* Incompatible change: MySQL 5.1.6 introduces the TRIGGER
2759
privilege. Previously, the SUPER privilege was needed to
2760
create or drop triggers. Now those operations require the
2761
TRIGGER privilege. This is a security improvement because you
2762
no longer need to grant users the SUPER privilege to enable
2763
them to create triggers. However, the requirement that the
2764
account named in a trigger's DEFINER clause must have the
2765
SUPER privilege has changed to a requirement for the TRIGGER
2766
privilege. When upgrading from a previous version of MySQL 5.0
2767
or 5.1 to MySQL 5.1.6 or newer, be sure to update your grant
2768
tables by running mysql_upgrade. This will assign the TRIGGER
2769
privilege to all accounts that had the SUPER privilege. If you
2770
fail to update the grant tables, triggers may fail when
2771
activated. After updating the grant tables, you can revoke the
2772
SUPER privilege from those accounts that no longer otherwise
2775
* Some keywords may be reserved in MySQL 5.1 that were not
2776
reserved in MySQL 5.0. See Section 8.3, "Reserved Words."
2778
* The BACKUP TABLE, and RESTORE TABLE statements are deprecated.
2779
mysqldump or mysqlhotcopy can be used as alternatives.
2781
* The LOAD DATA FROM MASTER and LOAD TABLE FROM MASTER
2782
statements are deprecated. See Section 12.6.2.2, "LOAD DATA
2783
FROM MASTER Syntax," for recommended alternatives.
2785
* The INSTALL PLUGIN and UNINSTALL PLUGIN statements that are
2786
used for the plugin API are new. So is the WITH PARSER clause
2787
for FULLTEXT index creation that associates a parser plugin
2788
with a full-text index. Section 22.2, "The MySQL Plugin
2793
* Incompatible change: As of MySQL 5.1.7, the
2794
mysql_stmt_attr_get() C API function returns a boolean rather
2795
than an unsigned int for STMT_ATTR_UPDATE_MAX_LENGTH.
2796
(Bug#16144: http://bugs.mysql.com/bug.php?id=16144)
2798
2.4.2. Downgrading MySQL
2800
This section describes what you should do to downgrade to an older
2801
MySQL version in the unlikely case that the previous version
2802
worked better than the new one.
2804
If you are downgrading within the same release series (for
2805
example, from 5.0.13 to 5.0.12) the general rule is that you just
2806
have to install the new binaries on top of the old ones. There is
2807
no need to do anything with the databases. As always, however, it
2808
is always a good idea to make a backup.
2810
The following items form a checklist of things you should do
2811
whenever you perform a downgrade:
2813
* Read the upgrading section for the release series from which
2814
you are downgrading to be sure that it does not have any
2815
features you really need. See Section 2.4.1, "Upgrading
2818
* If there is a downgrading section for that version, you should
2821
* To see which new features were added between the version to
2822
which you are downgrading and your current version, see the
2823
change logs (Appendix C, "MySQL Change History").
2825
* Check Section 2.4.3, "Checking Whether Tables or Indexes Must
2826
Be Rebuilt," to see whether changes to table formats or to
2827
character sets or collations were made between your current
2828
version of MySQL and the version to which you are downgrading.
2829
If so and these changes result in an incompatibility between
2830
MySQL versions, you will need to downgrade the affected tables
2831
using the instructions in Section 2.4.4, "Rebuilding or
2832
Repairing Tables or Indexes."
2834
In most cases, you can move the MySQL format files and data files
2835
between different versions on the same architecture as long as you
2836
stay within versions for the same release series of MySQL.
2838
If you downgrade from one release series to another, there may be
2839
incompatibilities in table storage formats. In this case, use
2840
mysqldump to dump your tables before downgrading. After
2841
downgrading, reload the dump file using mysql or mysqlimport to
2842
re-create your tables. For examples, see Section 2.4.5, "Copying
2843
MySQL Databases to Another Machine."
2845
A typical symptom of a downward-incompatible table format change
2846
when you downgrade is that you cannot open tables. In that case,
2847
use the following procedure:
2849
1. Stop the older MySQL server that you are downgrading to.
2851
2. Restart the newer MySQL server you are downgrading from.
2853
3. Dump any tables that were inaccessible to the older server by
2854
using mysqldump to create a dump file.
2856
4. Stop the newer MySQL server and restart the older one.
2858
5. Reload the dump file into the older server. Your tables should
2861
It might also be the case that system tables in the mysql database
2862
have changed and that downgrading introduces some loss of
2863
functionality or requires some adjustments. Here are some
2866
* Trigger creation requires the TRIGGER privilege as of MySQL
2867
5.1. In MySQL 5.0, there is no TRIGGER privilege and SUPER is
2868
required instead. If you downgrade from MySQL 5.1 to 5.0, you
2869
will need to give the SUPER privilege to those accounts that
2870
had the TRIGGER privilege in 5.1.
2872
* Triggers were added in MySQL 5.0, so if you downgrade from 5.0
2873
to 4.1, you cannot use triggers at all.
2875
* The mysql.proc.comment column definition changed between MySQL
2876
5.1 and 5.5. After a downgrade from 5.5 to 5.1, this table is
2877
seen as corrupt and in need of repair. To workaround this
2878
problem, execute mysql_upgrade from the version of MySQL to
2879
which you downgraded.
2881
2.4.2.1. Downgrading to MySQL 5.0
2883
When downgrading to MySQL 5.0 from MySQL 5.1, you should keep in
2884
mind the following issues relating to features found in MySQL 5.1,
2885
but not in MySQL 5.0:
2887
* Partitioning. MySQL 5.0 does not support user-defined
2888
partitioning. If a table was created as a partitioned table in
2889
5.1 (or if an table created in a previous version of MySQL was
2890
altered to include partitions after an upgrade to 5.1), the
2891
table is accessible after downgrade only if you do one of the
2894
+ Export the table using mysqldump and then drop it in
2895
MySQL 5.1; import the table again following the downgrade
2898
+ Prior to the downgrade, remove the table's partitioning
2899
using ALTER TABLE table_name REMOVE PARTITIONING.
2901
* Event Scheduler. MySQL 5.0 does not support scheduled events.
2902
If your databases contain scheduled event definitions, you
2903
should prevent them from being dumped when you use mysqldump
2904
by using the --skip-events option. (See Section 4.5.4,
2905
"mysqldump --- A Database Backup Program.")
2907
* Stored routines. MySQL 5.1.21 added a number of new columns
2908
to the mysql.proc table in which stored routine definitions
2909
are stored. If you are downgrading from MySQL 5.1.21 or later
2910
to MySQL 5.0, you cannot import the MySQL 5.1 routine
2911
definitions into MySQL 5.0.46 or earlier using the dump of
2912
mysql.proc created by mysqldump (such as when using the
2913
--all-databases option). Instead, you should run mysqldump
2914
--routines prior to performing the downgrade and run the
2915
stored routines DDL statements following the downgrade.
2916
See Bug#11986: http://bugs.mysql.com/bug.php?id=11986,
2917
Bug#30029: http://bugs.mysql.com/bug.php?id=30029, and
2918
Bug#30660: http://bugs.mysql.com/bug.php?id=30660, for more
2921
* Triggers. Trigger creation requires the TRIGGER privilege as
2922
of MySQL 5.1. In MySQL 5.0, there is no TRIGGER privilege and
2923
SUPER is required instead. If you downgrade from MySQL 5.1 to
2924
5.0, you will need to give the SUPER privilege to those
2925
accounts that had the TRIGGER privilege in 5.1.
2927
2.4.3. Checking Whether Tables or Indexes Must Be Rebuilt
2929
A binary upgrade or downgrade is one that installs one version of
2930
MySQL "in place" over an existing version, without dumping and
2933
1. Stop the server for the existing version if it is running.
2935
2. Install a different version of MySQL. This is an upgrade if
2936
the new version is higher than the original version, a
2937
downgrade if the version is lower.
2939
3. Start the server for the new version.
2941
In many cases, the tables from the previous version of MySQL can
2942
be used without problem by the new version. However, sometimes
2943
changes occur that require tables or table indexes to be rebuilt,
2944
as described in this section. If you have tables that are affected
2945
by any of the issues described here, rebuild the tables or indexes
2946
as necessary using the instructions given in Section 2.4.4,
2947
"Rebuilding or Repairing Tables or Indexes."
2949
Table Incompatibilities
2951
After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation
2952
that contains ARCHIVE tables, accessing those tables causes the
2953
server to crash, even if you have run mysql_upgrade or CHECK TABLE
2954
... FOR UPGRADE. To work around this problem, use mysqldump to
2955
dump all ARCHIVE tables before upgrading, and reload them into
2956
MySQL 5.1 after upgrading. The same problem occurs for binary
2957
downgrades from MySQL 5.1 to 5.0.
2959
Index Incompatibilities
2961
If you perform a binary upgrade without dumping and reloading
2962
tables, you cannot upgrade directly from MySQL 4.1 to 5.1 or
2963
higher. This occurs due to an incompatible change in the MyISAM
2964
table index format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and
2965
repair all MyISAM tables. Then upgrade from MySQL 5.0 to 5.1 and
2966
check and repair your tables.
2968
Modifications to the handling of character sets or collations
2969
might change the character sort order, which causes the ordering
2970
of entries in any index that uses an affected character set or
2971
collation to be incorrect. Such changes result in several possible
2974
* Comparison results that differ from previous results
2976
* Inability to find some index values due to misordered index
2979
* Misordered ORDER BY results
2981
* Tables that CHECK TABLE reports as being in need of repair
2983
The solution to these problems is to rebuild any indexes that use
2984
an affected character set or collation, either by dropping and
2985
re-creating the indexes, or by dumping and reloading the entire
2986
table. For information about rebuilding indexes, see Section
2987
2.4.4, "Rebuilding or Repairing Tables or Indexes."
2989
To check whether a table has indexes that must be rebuilt, consult
2990
the following list. It indicates which versions of MySQL
2991
introduced character set or collation changes that require indexes
2992
to be rebuilt. Each entry indicates the version in which the
2993
change occurred and the character sets or collations that the
2994
change affects. If the change is associated with a particular bug
2995
report, the bug number is given.
2997
The list applies both for binary upgrades and downgrades. For
2998
example, Bug#27877: http://bugs.mysql.com/bug.php?id=27877 was
2999
fixed in MySQL 5.1.24 and 5.4.0, so it applies to upgrades from
3000
versions older than 5.1.24 to 5.1.24 or newer, and to downgrades
3001
from 5.1.24 or newer to versions older than 5.1.24.
3003
In many cases, you can use CHECK TABLE ... FOR UPGRADE to identify
3004
tables for which index rebuilding is required. (It will report:
3005
Table upgrade required. Please do "REPAIR TABLE `tbl_name`" or
3006
dump/reload to fix it!) In these cases, you can also use
3007
mysqlcheck --check-upgrade or mysql_upgrade, which execute CHECK
3008
TABLE. However, the use of CHECK TABLE applies only after
3009
upgrades, not downgrades. Also, CHECK TABLE is not applicable to
3010
all storage engines. For details about which storage engines CHECK
3011
TABLE supports, see Section 12.5.2.3, "CHECK TABLE Syntax."
3013
Changes that cause index rebuilding to be necessary:
3015
* MySQL 5.0.48, 5.1.21
3016
(Bug#29461: http://bugs.mysql.com/bug.php?id=29461)
3017
Affects indexes for columns that use any of these character
3018
sets: eucjpms, euc_kr, gb2312, latin7, macce, ujis
3019
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3020
as of MySQL 5.1.29, 5.4.0 (see
3021
Bug#39585: http://bugs.mysql.com/bug.php?id=39585).
3023
* MySQL 5.0.48, 5.1.23
3024
(Bug#27562: http://bugs.mysql.com/bug.php?id=27562)
3025
Affects indexes that use the ascii_general_ci collation for
3026
columns that contain any of these characters: '`' GRAVE
3027
ACCENT, '[' LEFT SQUARE BRACKET, '\' REVERSE SOLIDUS, ']'
3028
RIGHT SQUARE BRACKET, '~' TILDE
3029
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3030
as of MySQL 5.1.29, 5.4.0 (see
3031
Bug#39585: http://bugs.mysql.com/bug.php?id=39585).
3033
* MySQL 5.1.24, 5.4.0
3034
(Bug#27877: http://bugs.mysql.com/bug.php?id=27877)
3035
Affects indexes that use the utf8_general_ci or
3036
ucs2_general_ci collation for columns that contain 'Ć' LATIN
3037
SMALL LETTER SHARP S (German).
3038
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE
3039
as of MySQL 5.1.30, 5.4.0 (see
3040
Bug#40053: http://bugs.mysql.com/bug.php?id=40053).
3042
2.4.4. Rebuilding or Repairing Tables or Indexes
3044
This section describes how to rebuild a table. This can be
3045
necessitated by changes to MySQL such as how data types are
3046
handled or changes to character set handling. For example, an
3047
error in a collation might have been corrected, necessitating a
3048
table rebuild to update the indexes for character columns that use
3049
the collation. (For examples, see Section 2.4.3, "Checking Whether
3050
Tables or Indexes Must Be Rebuilt.") It might also be that a table
3051
repair or upgrade should be done as indicated by a table check
3052
operation such as that performed by CHECK TABLE, mysqlcheck, or
3055
Methods for rebuilding a table include dumping and reloading it,
3056
or using ALTER TABLE or REPAIR TABLE.
3060
If you are rebuilding tables because a different version of MySQL
3061
will not handle them after a binary (in-place) upgrade or
3062
downgrade, you must use the dump-and-reload method. Dump the
3063
tables before upgrading or downgrading using your original version
3064
of MySQL. Then reload the tables after upgrading or downgrading.
3066
If you use the dump-and-reload method of rebuilding tables only
3067
for the purpose of rebuilding indexes, you can perform the dump
3068
either before or after upgrading or downgrading. Reloading still
3069
must be done afterward.
3071
To rebuild a table by dumping and reloading it, use mysqldump to
3072
create a dump file and mysql to reload the file:
3073
shell> mysqldump db_name t1 > dump.sql
3074
shell> mysql db_name < dump.sql
3076
To rebuild all the tables in a single database, specify the
3077
database name without any following table name:
3078
shell> mysqldump db_name > dump.sql
3079
shell> mysql db_name < dump.sql
3081
To rebuild all tables in all databases, use the --all-databases
3083
shell> mysqldump --all-databases > dump.sql
3084
shell> mysql < dump.sql
3086
To rebuild a table with ALTER TABLE, use a "null" alteration; that
3087
is, an ALTER TABLE statement that "changes" the table to use the
3088
storage engine that it already has. For example, if t1 is a MyISAM
3089
table, use this statement:
3090
mysql> ALTER TABLE t1 ENGINE = MyISAM;
3092
If you are not sure which storage engine to specify in the ALTER
3093
TABLE statement, use SHOW CREATE TABLE to display the table
3096
If you must rebuild a table because a table checking operation
3097
indicates that the table is corrupt or needs an upgrade, you can
3098
use REPAIR TABLE if that statement supports the table's storage
3099
engine. For example, to repair a MyISAM table, use this statement:
3100
mysql> REPAIR TABLE t1;
3102
For storage engines such as InnoDB that REPAIR TABLE does not
3103
support, use mysqldump to create a dump file and mysql to reload
3104
the file, as described earlier.
3106
For specifics about which storage engines REPAIR TABLE supports,
3107
see Section 12.5.2.6, "REPAIR TABLE Syntax."
3109
mysqlcheck --repair provides command-line access to the REPAIR
3110
TABLE statement. This can be a more convenient means of repairing
3111
tables because you can use the --databases or --all-databases
3112
option to repair all tables in specific databases or all
3113
databases, respectively:
3114
shell> mysqlcheck --repair --databases db_name ...
3115
shell> mysqlcheck --repair --all-databases
3117
2.4.5. Copying MySQL Databases to Another Machine
3119
You can copy the .frm, .MYI, and .MYD files for MyISAM tables
3120
between different architectures that support the same
3121
floating-point format. (MySQL takes care of any byte-swapping
3122
issues.) See Section 13.5, "The MyISAM Storage Engine."
3124
In cases where you need to transfer databases between different
3125
architectures, you can use mysqldump to create a file containing
3126
SQL statements. You can then transfer the file to the other
3127
machine and feed it as input to the mysql client.
3129
Use mysqldump --help to see what options are available.
3131
The easiest (although not the fastest) way to move a database
3132
between two machines is to run the following commands on the
3133
machine on which the database is located:
3134
shell> mysqladmin -h 'other_hostname' create db_name
3135
shell> mysqldump db_name | mysql -h 'other_hostname' db_name
3137
If you want to copy a database from a remote machine over a slow
3138
network, you can use these commands:
3139
shell> mysqladmin create db_name
3140
shell> mysqldump -h 'other_hostname' --compress db_name | mysql db_na
3143
You can also store the dump in a file, transfer the file to the
3144
target machine, and then load the file into the database there.
3145
For example, you can dump a database to a compressed file on the
3146
source machine like this:
3147
shell> mysqldump --quick db_name | gzip > db_name.gz
3149
Transfer the file containing the database contents to the target
3150
machine and run these commands there:
3151
shell> mysqladmin create db_name
3152
shell> gunzip < db_name.gz | mysql db_name
3154
You can also use mysqldump and mysqlimport to transfer the
3155
database. For large tables, this is much faster than simply using
3156
mysqldump. In the following commands, DUMPDIR represents the full
3157
path name of the directory you use to store the output from
3160
First, create the directory for the output files and dump the
3162
shell> mkdir DUMPDIR
3163
shell> mysqldump --tab=DUMPDIR db_name
3165
Then transfer the files in the DUMPDIR directory to some
3166
corresponding directory on the target machine and load the files
3168
shell> mysqladmin create db_name # create database
3169
shell> cat DUMPDIR/*.sql | mysql db_name # create tables in databas
3171
shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables
3173
Do not forget to copy the mysql database because that is where the
3174
grant tables are stored. You might have to run commands as the
3175
MySQL root user on the new machine until you have the mysql
3178
After you import the mysql database on the new machine, execute
3179
mysqladmin flush-privileges so that the server reloads the grant
3182
2.5. Installing MySQL on Windows
3184
This section describes the process for installing MySQL on
3187
To run MySQL on Windows, you need the following:
3189
* A Windows operating system such as Windows 2000, Windows XP,
3190
Windows Vista, Windows Server 2003, or Windows Server 2008.
3191
Both 32-bit and 64-bit versions are supported.
3192
In addition to running MySQL as a standard application, you
3193
can also run the MySQL server as a Windows service. By using a
3194
service you can monitor and control the operation of the
3195
server through the standard Windows service management tools.
3196
For more information, see Section 2.5.5.6, "Starting MySQL as
3198
Generally, you should install MySQL on Windows using an
3199
account that has administrator rights. Otherwise, you may
3200
encounter problems with certain operations such as editing the
3201
PATH environment variable or accessing the Service Control
3202
Manager. Once installed, MySQL does not need to be executed
3203
using a user with Administrator privileges.
3205
* TCP/IP protocol support.
3207
* Enough space on the hard drive to unpack, install, and create
3208
the databases in accordance with your requirements (generally
3209
a minimum of 200 megabytes is recommended.)
3211
For a list of limitations within the Windows version of MySQL, see
3212
Section D.7.3, "Windows Platform Limitations."
3214
In addition to the MySQL Server package, you may need or want
3215
additional components to use MySQL with your application or
3216
development environment. These include, but are not limited to:
3218
* If you plan to connect to the MySQL server via ODBC, you need
3219
a Connector/ODBC driver. For more information, including
3220
installation and configuration instructions, see Section 21.1,
3221
"MySQL Connector/ODBC."
3223
* If you plan to use MySQL server with .NET applications, you
3224
need the Connector/NET driver. For more information, including
3225
installation and configuration instructions, see Section 21.2,
3226
"MySQL Connector/NET."
3228
MySQL distributions for Windows can be downloaded from
3229
http://dev.mysql.com/downloads/. See Section 2.1.3, "How to Get
3232
MySQL for Windows is available in several distribution formats,
3233
detailed below. Generally speaking, you should use a binary
3234
distribution that includes an installer. It is simpler to use than
3235
the others, and you need no additional tools to get MySQL up and
3236
running. The installer for the Windows version of MySQL, combined
3237
with a GUI Config Wizard, automatically installs MySQL, creates an
3238
option file, starts the server, and secures the default user
3241
* Binary installer distribution. The installable distribution
3242
comes packaged as a Microsoft Windows Installer (MSI) package
3243
that you can install manually or automatically on your
3244
systems. Two formats are available, an essentials package that
3245
contains all the files you need to install and configure
3246
MySQL, but no additional components, and a complete package
3247
that includes MySQL, configuration tools, benchmarks and other
3248
components. For more information on the specific differences,
3249
see Section 2.5.2, "Choosing An Installation Package"
3250
For instructions on installing MySQL using one of the MSI
3251
installation packages, see Section 2.5.3, "Installing MySQL
3252
with the MSI Package."
3254
* Standard binary distribution format packaged as a Zip file
3255
containing all of the necessary files that you unpack into
3256
your chosen location. This package contains all of the files
3257
in the full Windows MSI Installer package, but does not
3258
including an installation program.
3259
For instructions on installing MySQL using the Zip file, see
3260
Section 2.5.5, "Installing MySQL from a noinstall Zip
3263
* The source distribution contains all the code and support
3264
files for building the executables using the Visual Studio
3266
For instructions on building MySQL from source on Windows, see
3267
Section 2.5.10, "Installing MySQL from Source on Windows."
3269
MySQL on Windows considerations:
3271
* Large Table Support
3272
If you need tables with a size larger than 4GB, install MySQL
3273
on an NTFS or newer file system. Don't forget to use MAX_ROWS
3274
and AVG_ROW_LENGTH when you create tables. See Section
3275
12.1.17, "CREATE TABLE Syntax."
3277
* MySQL and Virus Checking Software
3278
Using virus scanning software such as Norton/Symantec
3279
Anti-Virus on directories containing MySQL data and temporary
3280
tables can cause issues, both in terms of the performance of
3281
MySQL and the virus-scanning software mis-identifying the
3282
contents of the files as containing spam. This is because of
3283
the fingerprinting mechanism used by the virus scanning
3284
software, and the way in which MySQL rapidly updates different
3285
files, which may be identified as a potential security risk.
3286
After installing MySQL Server, it is recommended that you
3287
disable virus scanning on the main directory (datadir) being
3288
used to store your MySQL table data. There is usually a system
3289
built into the virus scanning software to allow certain
3290
directories to be specifically ignored during virus scanning.
3291
In addition, by default, MySQL creates temporary files in the
3292
standard Windows temporary directory. To prevent the temporary
3293
files also being scanned, you should configure a separate
3294
temporary directory for MySQL temporary files and add this to
3295
the virus scanning exclusion list. To do this, add a
3296
configuration option for the tmpdir parameter to your my.ini
3297
configuration file. For more information, see Section 2.5.5.2,
3298
"Creating an Option File."
3300
2.5.1. Windows Installation Layout
3302
For MySQL 5.1 on Windows, the default installation directory is
3303
C:\Program Files\MySQL\MySQL Server 5.1. Some Windows users prefer
3304
to install in C:\mysql, the directory that formerly was used as
3305
the default. However, the layout of the subdirectories remains the
3308
For MySQL 5.1.23 and earlier, all of the files are located within
3309
this parent directory, using the following structure:
3311
Table 2.2. Installation Layout for Windows using MySQL 5.1.23 and
3313
Directory Contents of Directory
3314
bin Client programs and the mysqld server
3315
data Log files, databases
3316
Docs Manual in CHM format
3317
examples Example programs and scripts
3318
include Include (header) files
3320
scripts Utility scripts
3321
share Error message files
3323
For MySQL 5.1.24 and later, the default location of data directory
3324
was changed. The remainder of the directory structure remains the
3327
Table 2.3. Installation Layout for Windows using MySQL 5.1.24 and
3329
Directory Contents of Directory
3330
bin Client programs and the mysqld server
3331
C:\Documents and Settings\All Users\Application Data\MySQL Log
3333
Docs Manual in CHM format
3334
examples Example programs and scripts
3335
include Include (header) files
3337
scripts Utility scripts
3338
share Error message files
3340
2.5.2. Choosing An Installation Package
3342
For MySQL 5.1, there are three installation packages to choose
3343
from when installing MySQL on Windows:
3345
Feature Essentials Complete Zip (No-install)
3346
Installer Yes Yes No
3348
MySQL Server Instance Config Wizard Yes Yes No
3349
Test Suite No Yes Yes
3350
MySQL Server Yes Yes Yes
3351
MySQL Client Programs Yes Yes Yes
3352
C Headers/Libraries Yes Yes Yes
3353
Embedded Server No Optional Yes
3354
Scripts and Examples No Optional Yes
3358
* Yes indiciates that the component is installed by default.
3360
* No indicates that the component is not installed or included.
3362
* Optional indicates that the component is included with the
3363
package, but not installed unless explicitly requested using
3364
the Custom installation mode.
3366
The workflow for installing using the MSI installer is shown
3369
Figure 2.1. Installation Workflow for Windows using MSI
3370
Installation Workflow for Windows using MSI
3372
The workflow for installing using the MSI installer is shown
3375
Figure 2.2. Installation Workflow for Windows using Zip
3376
Installation Workflow for Windows using Zip
3380
For the Essentials and Complete packages in the MSI installer, you
3381
can select individual components to be installed by using the
3382
Custom mode, including disable the components confiurated for
3383
installation by default.
3385
Full details on the components are suggested uses are provided
3386
below for reference:
3388
* Windows Essentials --- this package has a file name similar to
3389
mysql-essential-5.1.45-win32.msi and is supplied as a
3390
Microsoft Installer (MSI) package. The package includes the
3391
minimum set of files needed to install MySQL on Windows,
3392
including the MySQL Server Instance Config Wizard. This
3393
package does not include optional components such as the
3394
embedded server, developer headers and libraries or benchmark
3396
To install using this package, see Section 2.5.3, "Installing
3397
MySQL with the MSI Package."
3399
* Windows MSI Installer (Complete) --- this package has a file
3400
name similar to mysql-5.1.45-win32.zip and contains all files
3401
needed for a complete Windows installation, including the
3402
MySQL Server Instance Config Wizard. This package includes
3403
optional components such as the embedded server and benchmark
3405
To install using this package, see Section 2.5.3, "Installing
3406
MySQL with the MSI Package."
3408
* Without installer --- this package has a file name similar to
3409
mysql-noinstall-5.1.45-win32.zip and contains all the files
3410
found in the Complete install package, with the exception of
3411
the MySQL Server Instance Config Wizard. This package does not
3412
include an automated installer, and must be manually installed
3415
The Essentials package is recommended for most users. Both the
3416
Essentials and Complete distributions are available as an .msi
3417
file for use with the Windows Installer. The Noinstall
3418
distribution is packaged as Zip archives. To use Zip archives, you
3419
must have a tool that can unpack .zip files.
3421
When using the MSI installers you can automate the installation
3422
process. For more information, see Section 2.5.3.2, "Installing
3423
MySQL Automatically using MSI." To automate the creation of a
3424
MySQL instance, see Section 2.5.4.13, "Creating an Instance from
3427
Your choice of install package affects the installation process
3428
you must follow. If you choose to install either the Essentials or
3429
Complete install packages, see Section 2.5.3, "Installing MySQL
3430
with the MSI Package." If you choose to install MySQL from the
3431
Noinstall archive, see Section 2.5.5, "Installing MySQL from a
3432
noinstall Zip Archive."
3434
2.5.3. Installing MySQL with the MSI Package
3436
The MSI package are designed to install and configure MySQL in
3437
such a way that you can immediately get started using MySQL.
3439
The MySQL Installation Wizard and MySQL Config Wizard are
3440
available in the Essentials and Complete install packages. They
3441
are recommended for most standard MySQL installations. Exceptions
3442
include users who need to install multiple instances of MySQL on a
3443
single server host and advanced users who want complete control of
3444
server configuration.
3446
* For information on installing using the GUI MSI installer
3447
process, see Section 2.5.3, "Installing MySQL with the MSI
3450
* For information on installing using the command line using the
3451
MSI package, see Section 2.5.3.2, "Installing MySQL
3452
Automatically using MSI."
3454
* If you have previously installed MySQL using the MSI package
3455
and want to remove MySQL, see Section 2.5.3.3, "Removing MySQL
3456
Installed from the MSI Package."
3458
The workflow sequence for using the installer is shown in the
3461
Figure 2.3. Installation Workflow for Windows using MSI Installer
3462
Installation Workflow for Windows using MSI Installer
3466
Microsoft Windows XP and later include a firewall which
3467
specifically blocks ports. If you plan on using MySQL through a
3468
network port then you should open and create an exception for this
3469
port before performing the installation. To check and if necessary
3470
add an exception to the firewall settings:
3472
1. First ensure that you are logged in as an Administrator or a
3473
user with Administrator privileges.
3475
2. Go to the Control Panel, and double click the Windows Firewall
3478
3. Choose the Allow a program through Windows Firewall option and
3479
click the Add port button.
3481
4. Enter MySQL into the Name text box and 3306 (or the port of
3482
your choice) into the Port number text box.
3484
5. Also ensure that the TCP protocol radio button is selected.
3486
6. If you wish, you can also limit access to the MySQL server by
3487
choosing the Change scope button.
3489
7. Confirm your choices by clicking the OK button.
3491
Additionally, when running the MySQL Installation Wizard on
3492
Windows Vista, ensure that you are logged in as a user with
3493
administrative rights.
3497
When using Windows Vista, you may want to disable User Account
3498
Control (UAC) before performing the installation. If you do not do
3499
so, then MySQL may be identified as a security risk, which will
3500
mean that you need to enable MySQL. You can disable the security
3501
checking by following these instructions:
3503
1. Open Control Panel.
3505
2. Under the User Accounts and Family Safety, select Add or
3506
remove user accounts.
3508
3. Click on the Got to the main User Accounts page link.
3510
4. Click on Turn User Account Control on or off. You may be
3511
prompted to provide permission to change this setting. Click
3514
5. Deselect or unceck the checkbox next to Use User Account
3515
Control (UAC) to help protect your computer. Click OK to save
3518
You will need to restart to complete the process. Click Restart
3519
Now to reboot the machine and apply the changes. You can then
3520
follow the instructions below for installing Windows.
3522
2.5.3.1. Using the MySQL Installation Wizard
3524
MySQL Installation Wizard is an installer for the MySQL server
3525
that uses the latest installer technologies for Microsoft Windows.
3526
The MySQL Installation Wizard, in combination with the MySQL
3527
Config Wizard, allows a user to install and configure a MySQL
3528
server that is ready for use immediately after installation.
3530
The MySQL Installation Wizard uses the standard Microsoft
3531
Installer Engine (MSI) system is the standard installer for all
3532
MySQL server distributions, version 4.1.5 and higher. Users of
3533
previous versions of MySQL need to shut down and remove their
3534
existing MySQL installations manually before installing MySQL with
3535
the MySQL Installation Wizard. See Section 2.5.3.1.6, "Upgrading
3536
MySQL with the Installation Wizard," for more information on
3537
upgrading from a previous version.
3539
If you are upgrading an installation from MySQL 5.1.31 or earlier
3540
to MySQL 5.1.32 or later, read the notes provided in Section
3541
2.5.3.1.6, "Upgrading MySQL with the Installation Wizard."
3543
The Microsoft Windows Installer Engine was updated with the
3544
release of Windows XP; those using a previous version of Windows
3545
can reference this Microsoft Knowledge Base article
3546
(http://support.microsoft.com/default.aspx?scid=kb;EN-US;292539)
3547
for information on upgrading to the latest version of the Windows
3550
In addition, Microsoft has introduced the WiX (Windows Installer
3551
XML) toolkit. This is the first highly acknowledged Open Source
3552
project from Microsoft. We have switched to WiX because it is an
3553
Open Source project and it allows us to handle the complete
3554
Windows installation process in a flexible manner using scripts.
3556
Improving the MySQL Installation Wizard depends on the support and
3557
feedback of users like you. If you find that the MySQL
3558
Installation Wizard is lacking some feature important to you, or
3559
if you discover a bug, please report it in our bugs database using
3560
the instructions given in Section 1.7, "How to Report Bugs or
3563
2.5.3.1.1. Downloading and Starting the MySQL Installation Wizard
3565
The MySQL installation packages can be downloaded from
3566
http://dev.mysql.com/downloads/. If the package you download is
3567
contained within a Zip archive, you need to extract the archive
3570
The process for starting the wizard depends on the contents of the
3571
installation package you download. If there is a setup.exe file
3572
present, double-click it to start the installation process. If
3573
there is an .msi file present, double-click it to start the
3574
installation process.
3576
2.5.3.1.2. Choosing an Install Type
3578
There are three installation types available: Typical, Complete,
3581
The Typical installation type installs the MySQL server, the mysql
3582
command-line client, and the command-line utilities. The
3583
command-line clients and utilities include mysqldump, myisamchk,
3584
and several other tools to help you manage the MySQL server.
3586
The Complete installation type installs all components included in
3587
the installation package. The full installation package includes
3588
components such as the embedded server library, the benchmark
3589
suite, support scripts, and documentation.
3591
The Custom installation type gives you complete control over which
3592
packages you wish to install and the installation path that is
3593
used. See Section 2.5.3.1.3, "The Custom Install Dialog," for more
3594
information on performing a custom install.
3596
If you choose the Typical or Complete installation types and click
3597
the Next button, you advance to the confirmation screen to verify
3598
your choices and begin the installation. If you choose the Custom
3599
installation type and click the Next button, you advance to the
3600
custom installation dialog, described in Section 2.5.3.1.3, "The
3601
Custom Install Dialog."
3603
2.5.3.1.3. The Custom Install Dialog
3605
If you wish to change the installation path or the specific
3606
components that are installed by the MySQL Installation Wizard,
3607
choose the Custom installation type.
3609
A tree view on the left side of the custom install dialog lists
3610
all available components. Components that are not installed have a
3611
red X icon; components that are installed have a gray icon. To
3612
change whether a component is installed, click on that component's
3613
icon and choose a new option from the drop-down list that appears.
3615
You can change the default installation path by clicking the
3616
Change... button to the right of the displayed installation path.
3618
After choosing your installation components and installation path,
3619
click the Next button to advance to the confirmation dialog.
3621
2.5.3.1.4. The Confirmation Dialog
3623
Once you choose an installation type and optionally choose your
3624
installation components, you advance to the confirmation dialog.
3625
Your installation type and installation path are displayed for you
3628
To install MySQL if you are satisfied with your settings, click
3629
the Install button. To change your settings, click the Back
3630
button. To exit the MySQL Installation Wizard without installing
3631
MySQL, click the Cancel button.
3633
After installation is complete, you have the option of registering
3634
with the MySQL web site. Registration gives you access to post in
3635
the MySQL forums at forums.mysql.com (http://forums.mysql.com),
3636
along with the ability to report bugs at bugs.mysql.com
3637
(http://bugs.mysql.com) and to subscribe to our newsletter. The
3638
final screen of the installer provides a summary of the
3639
installation and gives you the option to launch the MySQL Config
3640
Wizard, which you can use to create a configuration file, install
3641
the MySQL service, and configure security settings.
3643
2.5.3.1.5. Changes Made by MySQL Installation Wizard
3645
Once you click the Install button, the MySQL Installation Wizard
3646
begins the installation process and makes certain changes to your
3647
system which are described in the sections that follow.
3649
Changes to the Registry
3651
The MySQL Installation Wizard creates one Windows registry key in
3652
a typical install situation, located in
3653
HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB.
3655
The MySQL Installation Wizard creates a key named after the major
3656
version of the server that is being installed, such as MySQL
3657
Server 5.1. It contains two string values, Location and Version.
3658
The Location string contains the path to the installation
3659
directory. In a default installation it contains C:\Program
3660
Files\MySQL\MySQL Server 5.1\. The Version string contains the
3661
release number. For example, for an installation of MySQL Server
3662
5.1.45, the key contains a value of 5.1.45.
3664
These registry keys are used to help external tools identify the
3665
installed location of the MySQL server, preventing a complete scan
3666
of the hard-disk to determine the installation path of the MySQL
3667
server. The registry keys are not required to run the server, and
3668
if you install MySQL using the noinstall Zip archive, the registry
3669
keys are not created.
3671
Changes to the Start Menu
3673
The MySQL Installation Wizard creates a new entry in the Windows
3674
Start menu under a common MySQL menu heading named after the major
3675
version of MySQL that you have installed. For example, if you
3676
install MySQL 5.1, the MySQL Installation Wizard creates a MySQL
3677
Server 5.1 section in the Start menu.
3679
The following entries are created within the new Start menu
3682
* MySQL Command Line Client: This is a shortcut to the mysql
3683
command-line client and is configured to connect as the root
3684
user. The shortcut prompts for a root user password when you
3687
* MySQL Server Instance Config Wizard: This is a shortcut to the
3688
MySQL Config Wizard. Use this shortcut to configure a newly
3689
installed server, or to reconfigure an existing server.
3691
* MySQL Documentation: This is a link to the MySQL server
3692
documentation that is stored locally in the MySQL server
3693
installation directory. This option is not available when the
3694
MySQL server is installed using the Essentials installation
3697
Changes to the File System
3699
The MySQL Installation Wizard by default installs the MySQL 5.1
3700
server to C:\Program Files\MySQL\MySQL Server 5.1, where Program
3701
Files is the default location for applications in your system, and
3702
5.1 is the major version of your MySQL server. This is the
3703
recommended location for the MySQL server, replacing the former
3704
default location C:\mysql.
3706
By default, all MySQL applications are stored in a common
3707
directory at C:\Program Files\MySQL, where Program Files is the
3708
default location for applications in your Windows installation. A
3709
typical MySQL installation on a developer machine might look like
3711
C:\Program Files\MySQL\MySQL Server 5.1
3712
C:\Program Files\MySQL\MySQL Workbench 5.1 OSS
3714
This approach makes it easier to manage and maintain all MySQL
3715
applications installed on a particular system.
3717
In MySQL 5.1.23 and earlier, the default location for the data
3718
files used by MySQL is located within the corresponding MySQL
3719
Server installation directory. For MySQL 5.1.24 and later, the
3720
default location of the data directory is the AppData directory
3721
configured for the user that installed the MySQL application.
3723
2.5.3.1.6. Upgrading MySQL with the Installation Wizard
3725
The MySQL Installation Wizard can perform server upgrades
3726
automatically using the upgrade capabilities of MSI. That means
3727
you do not need to remove a previous installation manually before
3728
installing a new release. The installer automatically shuts down
3729
and removes the previous MySQL service before installing the new
3732
Automatic upgrades are available only when upgrading between
3733
installations that have the same major and minor version numbers.
3734
For example, you can upgrade automatically from MySQL 5.1.34 to
3735
MySQL 5.1.37, but not from MySQL 5.0 to MySQL 5.1.
3737
In MySQL 5.1.32 and later, the EXE version of the MSI installer
3738
packages were removed. When upgrading an existing MySQL
3739
installation from the old EXE based installer to the MSI based
3740
installer, please keep the following notes in mind:
3742
* The MSI installer will not identify an existing installation
3743
that was installed using the old EXE installer. This means
3744
that the installer will not stop the existing server, or
3745
detect that the existing password is required before
3746
installing the new version. To work around this:
3748
1. Stop the current server manually using net stop or
3749
mysqladmin shutdown.
3751
2. Remove the existing installation manually by using the
3752
Add/Remove Programs control panel. This will keep the
3753
existing configuration and data files, as these are not
3754
removed automatically.
3756
3. Install the new version of MySQL using the MSI installer.
3757
When running the installation, skip updating the security
3758
by deselecting the checkbox on the security screen.
3760
4. Complete the installation, and then start the server
3761
again. You should be able to login with your existing
3762
user and password credentials.
3764
* You can only upgrade the version and release using the MSI
3765
installer. For example, you can upgrade an open source
3766
installation with an open source installer. You cannot upgrade
3767
an open source installation using the enterprise installer.
3769
See Section 2.5.7, "Upgrading MySQL on Windows."
3771
2.5.3.2. Installing MySQL Automatically using MSI
3773
The Microsoft Installer (MSI) supports a both a quiet and a
3774
passive mode that can be used to install MySQL automatically
3775
without requireing intervention. You can use this either in
3776
scripts to automatically install MySQL or through a terminal
3777
connection such as Telnet where you do not have access to the
3778
standard Windows user interface. The MSI packages can also be used
3779
in combination with Microsoft's Group Policy system (part of
3780
Windows Server 2003 and Windows Server 2008) to install MySQL
3781
across multiple machines.
3783
To install MySQL from one of the MSI packages automatically from
3784
the command line (or within a script), you need to use the
3785
msiexec.exe tool. For example, to perform a quiet installation
3786
(which shows no dialog boxes or progress):
3787
shell> msiexec /i /quiet mysql-5.1.39.msi
3789
The /i indicates that you want to perform an installation. The
3790
/quiet option indicates that you want no interactive elements.
3792
To provide a dialog box showing the progress during installation,
3793
and the dialog boxes providing information on the installation and
3794
registration of MySQL, use /passive mode instead of /quiet:
3795
shell> msiexec /i /passive mysql-5.1.39.msi
3797
Regardless of the mode of the installation, installing the package
3798
in this manner performs a 'Typical' installation, and installs the
3799
default components into the standard location.
3801
You can also use this method to uninstall MySQL by using the
3802
/uninstall or /x options:
3803
shell> msiexec /x /quiet mysql-5.1.39.msi
3805
To install MySQL and configure a MySQL instance from the command
3806
line, see Section 2.5.4.13, "Creating an Instance from the Command
3809
For information on using MSI packages to install software
3810
automatically using Group Policy, see How to use Group Policy to
3811
remotely install software in Windows Server 2003
3812
(http://support.microsoft.com/kb/816102).
3814
2.5.3.3. Removing MySQL Installed from the MSI Package
3816
To uninstall a MySQL where you have used the MSI packages, you
3817
must use the Add/Remove Programs tool within Control Panel. To do
3820
1. Right click on the start menu and choose Control Panel.
3822
2. If the Control Panel is set to category mode (you will see
3823
Pick a category at the top of the Control Panel window),
3824
double click on Add or Remove Programs. If the Control is set
3825
to classic mode, doubgle click on the Add or Remove Programs
3828
3. Find MySQL in the list of installed software. MySQL Server is
3829
installed against major version numbers (MySQL 5.0, MySQL 5.1,
3830
etc.). Select the version that you want to remove and click
3833
4. You will be prompted to confirm the removal. Click Yes to
3836
When MySQL is removed using this method, only the installed
3837
components are removed. Any database information (including the
3838
tables and data), import or export files, log files, and binary
3839
logs produced during execution are kept in their configured
3842
2.5.4. MySQL Server Instance Config Wizard
3844
The MySQL Server Instance Config Wizard helps automate the process
3845
of configuring your server. It creates a custom MySQL
3846
configuration file (my.ini or my.cnf) by asking you a series of
3847
questions and then applying your responses to a template to
3848
generate the configuration file that is tuned to your
3851
The complete and essential MSI installation packages include the
3852
MySQL Server Instance Config Wizard in the MySQL 5.1 server. The
3853
MySQL Server Instance Config Wizard is only available for Windows.
3855
The workflow sequence for using the MySQL Server Instance Config
3856
Wizard is shown in the figure below:
3858
Figure 2.4. MySQL Server Instance Config Wizard Workflow
3859
MySQL Server Instance Config Wizard Workflow
3861
2.5.4.1. Starting the MySQL Server Instance Config Wizard
3863
The MySQL Server Instance Config Wizard is normally started as
3864
part of the installation process. You should only need to run the
3865
MySQL Server Instance Config Wizard again when you need to change
3866
the configuration parameters of your server.
3868
If you chose not to open a port prior to installing MySQL on
3869
Windows Vista, you can choose to use the MySQL Server Instance
3870
Config Wizard after installation. However, you must open a port in
3871
the Windows Firewall. To do this see the instructions given in
3872
Section 2.5.3.1.1, "Downloading and Starting the MySQL
3873
Installation Wizard." Rather than opening a port, you also have
3874
the option of adding MySQL as a program that bypasses the Windows
3875
Firewall. One or the other option is sufficient --- you need not
3876
do both. Additionally, when running the MySQL Server Config Wizard
3877
on Windows Vista ensure that you are logged in as a user with
3878
administrative rights.
3879
MySQL Server Instance Config Wizard
3881
You can launch the MySQL Config Wizard by clicking the MySQL
3882
Server Instance Config Wizard entry in the MySQL section of the
3885
Alternatively, you can navigate to the bin directory of your MySQL
3886
installation and launch the MySQLInstanceConfig.exe file directly.
3888
The MySQL Server Instance Config Wizard places the my.ini file in
3889
the installation directory for the MySQL server. This helps
3890
associate configuration files with particular server instances.
3892
To ensure that the MySQL server knows where to look for the my.ini
3893
file, an argument similar to this is passed to the MySQL server as
3894
part of the service installation:
3895
--defaults-file="C:\Program Files\MySQL\MySQL Server 5.1\my.ini"
3897
Here, C:\Program Files\MySQL\MySQL Server 5.1 is replaced with the
3898
installation path to the MySQL Server. The --defaults-file option
3899
instructs the MySQL server to read the specified file for
3900
configuration options when it starts.
3902
Apart from making changes to the my.ini file by running the MySQL
3903
Server Instance Config Wizard again, you can modify it by opening
3904
it with a text editor and making any necessary changes. You can
3905
also modify the server configuration with the
3906
http://www.mysql.com/products/administrator/ utility. For more
3907
information about server configuration, see Section 5.1.2, "Server
3910
MySQL clients and utilities such as the mysql and mysqldump
3911
command-line clients are not able to locate the my.ini file
3912
located in the server installation directory. To configure the
3913
client and utility applications, create a new my.ini file in the
3914
Windows installation directory (for example, C:\WINDOWS).
3916
Under Windows Server 2003, Windows Server 2000, Windows XP, and
3917
Windows Vista MySQL Server Instance Config Wizard will configure
3918
MySQL to work as a Windows service. To start and stop MySQL you
3919
use the Services application that is supplied as part of the
3920
Windows Administrator Tools.
3922
2.5.4.2. Choosing a Maintenance Option
3924
If the MySQL Server Instance Config Wizard detects an existing
3925
configuration file, you have the option of either reconfiguring
3926
your existing server, or removing the server instance by deleting
3927
the configuration file and stopping and removing the MySQL
3930
To reconfigure an existing server, choose the Re-configure
3931
Instance option and click the Next button. Any existing
3932
configuration file is not overwritten, but renamed (within the
3933
same directory) using a timestamp (Windows) or sequential number
3934
(Linux). To remove the existing server instance, choose the Remove
3935
Instance option and click the Next button.
3937
If you choose the Remove Instance option, you advance to a
3938
confirmation window. Click the Execute button. The MySQL Server
3939
Config Wizard stops and removes the MySQL service, and then
3940
deletes the configuration file. The server installation and its
3941
data folder are not removed.
3943
If you choose the Re-configure Instance option, you advance to the
3944
Configuration Type dialog where you can choose the type of
3945
installation that you wish to configure.
3947
2.5.4.3. Choosing a Configuration Type
3949
When you start the MySQL Server Instance Config Wizard for a new
3950
MySQL installation, or choose the Re-configure Instance option for
3951
an existing installation, you advance to the Configuration Type
3953
MySQL Server Instance Config Wizard: Configuration Type
3955
There are two configuration types available: Detailed
3956
Configuration and Standard Configuration. The Standard
3957
Configuration option is intended for new users who want to get
3958
started with MySQL quickly without having to make many decisions
3959
about server configuration. The Detailed Configuration option is
3960
intended for advanced users who want more fine-grained control
3961
over server configuration.
3963
If you are new to MySQL and need a server configured as a
3964
single-user developer machine, the Standard Configuration should
3965
suit your needs. Choosing the Standard Configuration option causes
3966
the MySQL Config Wizard to set all configuration options
3967
automatically with the exception of Service Options and Security
3970
The Standard Configuration sets options that may be incompatible
3971
with systems where there are existing MySQL installations. If you
3972
have an existing MySQL installation on your system in addition to
3973
the installation you wish to configure, the Detailed Configuration
3974
option is recommended.
3976
To complete the Standard Configuration, please refer to the
3977
sections on Service Options and Security Options in Section
3978
2.5.4.10, "The Service Options Dialog," and Section 2.5.4.11, "The
3979
Security Options Dialog," respectively.
3981
2.5.4.4. The Server Type Dialog
3983
There are three different server types available to choose from.
3984
The server type that you choose affects the decisions that the
3985
MySQL Server Instance Config Wizard makes with regard to memory,
3986
disk, and processor usage.
3987
MySQL Server Instance Config Wizard: Server Type
3989
* Developer Machine: Choose this option for a typical desktop
3990
workstation where MySQL is intended only for personal use. It
3991
is assumed that many other desktop applications are running.
3992
The MySQL server is configured to use minimal system
3995
* Server Machine: Choose this option for a server machine where
3996
the MySQL server is running alongside other server
3997
applications such as FTP, email, and Web servers. The MySQL
3998
server is configured to use a moderate portion of the system
4001
* Dedicated MySQL Server Machine: Choose this option for a
4002
server machine that is intended to run only the MySQL server.
4003
It is assumed that no other applications are running. The
4004
MySQL server is configured to use all available system
4009
By selecting one of the preconfigured configurations, the values
4010
and settings of various options in your my.cnf or my.ini will be
4011
altered accordingly. The default values and options as described
4012
in the reference manual may therefore be different to the options
4013
and values that were created during the execution of the Config
4016
2.5.4.5. The Database Usage Dialog
4018
The Database Usage dialog allows you to indicate the storage
4019
engines that you expect to use when creating MySQL tables. The
4020
option you choose determines whether the InnoDB storage engine is
4021
available and what percentage of the server resources are
4022
available to InnoDB.
4023
MySQL Server Instance Config Wizard: Usage Dialog
4025
* Multifunctional Database: This option enables both the InnoDB
4026
and MyISAM storage engines and divides resources evenly
4027
between the two. This option is recommended for users who use
4028
both storage engines on a regular basis.
4030
* Transactional Database Only: This option enables both the
4031
InnoDB and MyISAM storage engines, but dedicates most server
4032
resources to the InnoDB storage engine. This option is
4033
recommended for users who use InnoDB almost exclusively and
4034
make only minimal use of MyISAM.
4036
* Non-Transactional Database Only: This option disables the
4037
InnoDB storage engine completely and dedicates all server
4038
resources to the MyISAM storage engine. This option is
4039
recommended for users who do not use InnoDB.
4041
The Config Wizard uses a template to generate the server
4042
configuration file. The Database Usage dialog sets one of the
4043
following option strings:
4044
Multifunctional Database: MIXED
4045
Transactional Database Only: INNODB
4046
Non-Transactional Database Only: MYISAM
4048
When these options are processed through the default template
4049
(my-template.ini) the result is:
4050
Multifunctional Database:
4051
default-storage-engine=InnoDB
4054
Transactional Database Only:
4055
default-storage-engine=InnoDB
4058
Non-Transactional Database Only:
4059
default-storage-engine=MyISAM
4063
The _myisam_pct value is used to calculate the percentage of
4064
resources dedicated to MyISAM. The remaining resources are
4065
allocated to InnoDB.
4067
2.5.4.6. The InnoDB Tablespace Dialog
4069
Some users may want to locate the InnoDB tablespace files in a
4070
different location than the MySQL server data directory. Placing
4071
the tablespace files in a separate location can be desirable if
4072
your system has a higher capacity or higher performance storage
4073
device available, such as a RAID storage system.
4074
MySQL Server Instance Config Wizard: InnoDB Data Tablespace
4076
To change the default location for the InnoDB tablespace files,
4077
choose a new drive from the drop-down list of drive letters and
4078
choose a new path from the drop-down list of paths. To create a
4079
custom path, click the ... button.
4081
If you are modifying the configuration of an existing server, you
4082
must click the Modify button before you change the path. In this
4083
situation you must move the existing tablespace files to the new
4084
location manually before starting the server.
4086
2.5.4.7. The Concurrent Connections Dialog
4088
To prevent the server from running out of resources, it is
4089
important to limit the number of concurrent connections to the
4090
MySQL server that can be established. The Concurrent Connections
4091
dialog allows you to choose the expected usage of your server, and
4092
sets the limit for concurrent connections accordingly. It is also
4093
possible to set the concurrent connection limit manually.
4094
MySQL Server Instance Config Wizard: Connections
4096
* Decision Support (DSS)/OLAP: Choose this option if your server
4097
does not require a large number of concurrent connections. The
4098
maximum number of connections is set at 100, with an average
4099
of 20 concurrent connections assumed.
4101
* Online Transaction Processing (OLTP): Choose this option if
4102
your server requires a large number of concurrent connections.
4103
The maximum number of connections is set at 500.
4105
* Manual Setting: Choose this option to set the maximum number
4106
of concurrent connections to the server manually. Choose the
4107
number of concurrent connections from the drop-down box
4108
provided, or enter the maximum number of connections into the
4109
drop-down box if the number you desire is not listed.
4111
2.5.4.8. The Networking and Strict Mode Options Dialog
4113
Use the Networking Options dialog to enable or disable TCP/IP
4114
networking and to configure the port number that is used to
4115
connect to the MySQL server.
4116
MySQL Server Instance Config Wizard: Network Configuration
4118
TCP/IP networking is enabled by default. To disable TCP/IP
4119
networking, uncheck the box next to the Enable TCP/IP Networking
4122
Port 3306 is used by default. To change the port used to access
4123
MySQL, choose a new port number from the drop-down box or type a
4124
new port number directly into the drop-down box. If the port
4125
number you choose is in use, you are prompted to confirm your
4126
choice of port number.
4128
Set the Server SQL Mode to either enable or disable strict mode.
4129
Enabling strict mode (default) makes MySQL behave more like other
4130
database management systems. If you run applications that rely on
4131
MySQL's old "forgiving" behavior, make sure to either adapt those
4132
applications or to disable strict mode. For more information about
4133
strict mode, see Section 5.1.8, "Server SQL Modes."
4135
2.5.4.9. The Character Set Dialog
4137
The MySQL server supports multiple character sets and it is
4138
possible to set a default server character set that is applied to
4139
all tables, columns, and databases unless overridden. Use the
4140
Character Set dialog to change the default character set of the
4142
MySQL Server Instance Config Wizard: Character Set
4144
* Standard Character Set: Choose this option if you want to use
4145
latin1 as the default server character set. latin1 is used for
4146
English and many Western European languages.
4148
* Best Support For Multilingualism: Choose this option if you
4149
want to use utf8 as the default server character set. This is
4150
a Unicode character set that can store characters from many
4151
different languages.
4153
* Manual Selected Default Character Set / Collation: Choose this
4154
option if you want to pick the server's default character set
4155
manually. Choose the desired character set from the provided
4158
2.5.4.10. The Service Options Dialog
4160
On Windows platforms, the MySQL server can be installed as a
4161
Windows service. When installed this way, the MySQL server can be
4162
started automatically during system startup, and even restarted
4163
automatically by Windows in the event of a service failure.
4165
The MySQL Server Instance Config Wizard installs the MySQL server
4166
as a service by default, using the service name MySQL. If you do
4167
not wish to install the service, uncheck the box next to the
4168
Install As Windows Service option. You can change the service name
4169
by picking a new service name from the drop-down box provided or
4170
by entering a new service name into the drop-down box.
4174
Service names can include any legal character except forward (/)
4175
or backward (\) slashes, and must be less than 256 characters
4180
If you are installing multiple versions of MySQL onto the same
4181
machine, you must choose a different service name for each version
4182
that you install. If you do not choose a different service for
4183
each installed version then the service manager information will
4184
be inconsistent and this will cause problems when you try to
4185
uninstall a previous version.
4187
If you have already installed multiple versions using the same
4188
service name, you must manually edit the contents of the
4189
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services parameters
4190
within the Windows registry to update the association of the
4191
service name with the correct server version.
4193
Typically, when installing multiple versions you create a service
4194
name based on the version information. For example, you might
4195
install MySQL 5.x as mysql5, or specific versions such as MySQL
4196
5.1.30 as mysql50130.
4198
To install the MySQL server as a service but not have it started
4199
automatically at startup, uncheck the box next to the Launch the
4200
MySQL Server Automatically option.
4202
2.5.4.11. The Security Options Dialog
4204
The content of the security options portion of the MySQL Server
4205
Instance Configuration Wizard will depend on whether this is a new
4206
installation, or modifying an existing installation.
4208
* Setting the root password for a new installation
4209
It is strongly recommended that you set a root password for
4210
your MySQL server, and the MySQL Server Instance Config Wizard
4211
requires by default that you do so. If you do not wish to set
4212
a root password, uncheck the box next to the Modify Security
4214
MySQL Server Instance Config Wizard: Security
4216
* To set the root password, enter the desired password into both
4217
the New root password and Confirm boxes.
4218
Setting the root password for an existing installation
4219
If you are modifying the configuration of an existing
4220
configuration, or you are installing an upgrade and the MySQL
4221
Server Instance Configuration Wizard has detected an existing
4222
MySQL system, then you must enter the existing password for
4223
root before changing the configuration information.
4224
MySQL Server Instance Config Wizard: Security (Existing
4226
If you want to change the current root password, enter the
4227
desired new password into both the New root password and
4230
To allow root logins from across the network, check the box next
4231
to the Enable root access from remote machines option. This
4232
decreases the security of your root account.
4234
To create an anonymous user account, check the box next to the
4235
Create An Anonymous Account option. Creating an anonymous account
4236
can decrease server security and cause login and permission
4237
difficulties. For this reason, it is not recommended.
4239
2.5.4.12. The Confirmation Dialog
4241
The final dialog in the MySQL Server Instance Config Wizard is the
4242
Confirmation Dialog. To start the configuration process, click the
4243
Execute button. To return to a previous dialog, click the Back
4244
button. To exit the MySQL Server Instance Config Wizard without
4245
configuring the server, click the Cancel button.
4246
MySQL Server Instance Config Wizard: Confirmation
4248
After you click the Execute button, the MySQL Server Instance
4249
Config Wizard performs a series of tasks and displays the progress
4250
onscreen as the tasks are performed.
4252
The MySQL Server Instance Config Wizard first determines
4253
configuration file options based on your choices using a template
4254
prepared by MySQL developers and engineers. This template is named
4255
my-template.ini and is located in your server installation
4258
The MySQL Config Wizard then writes these options to the
4259
corresponding configuration file.
4261
If you chose to create a service for the MySQL server, the MySQL
4262
Server Instance Config Wizard creates and starts the service. If
4263
you are reconfiguring an existing service, the MySQL Server
4264
Instance Config Wizard restarts the service to apply your
4265
configuration changes.
4267
If you chose to set a root password, the MySQL Config Wizard
4268
connects to the server, sets your new root password, and applies
4269
any other security settings you may have selected.
4271
After the MySQL Server Instance Config Wizard has completed its
4272
tasks, it displays a summary. Click the Finish button to exit the
4273
MySQL Server Config Wizard.
4275
2.5.4.13. Creating an Instance from the Command Line
4277
In addition to using the GUI interface to the MySQL Server
4278
Instance Config Wizard, you can also create instances
4279
automatically from the command line.
4281
To use the MySQL Server Instance Config Wizard on the command
4282
line, you need to use the MySQLInstanceConfig.exe command that is
4283
installed with MySQL in the bin directory within the installation
4284
directory. MySQLInstanceConfig.exe takes a number of command-line
4285
arguments the set the properties that would normally be selected
4286
through the GUI interface, and then creates a new configuration
4287
file (my.ini) by combining these selections with a template
4288
configuration file to produce the working configuration file.
4290
The main command line options are provided in the table below.
4291
Some of the options are required, while some options are optional.
4293
Table 2.4. MySQL Server Instance Config Wizard Command Line
4297
-nPRODUCTNAME The name of the instance when installed
4298
-pPATH Path of the base directory for installation. This is
4299
equivalent to the directory when using the basedir configuration
4301
-vVERSION The version tag to use for this installation
4303
-i Install an instance
4304
-r Remove an instance
4305
-s Stop an existing instance
4306
-q Perform the operation quietly
4307
-lFILENAME Sae the installation progress in a logfile
4309
-tFILENAME Path to the template config file that will be used to
4310
generate the installed configuration file
4311
-cFILENAME Path to a config file to be generated
4313
The -t and -c options work together to set the configuration
4314
parameters for a new instance. The -t option specifies the
4315
template configuration file to use as the basic configuration,
4316
which are then merged with the configuration parameters generated
4317
by the MySQL Server Instance Config Wizard into the configuration
4318
file specified by the -c option.
4320
A sample template file, my-template.ini is provided in the
4321
toplevel MySQL installation directory. The file contains elements
4322
are replaced automatically by the MySQL Server Instance Config
4323
Wizard during configuration.
4325
If you specify a configuration file that already exists, the
4326
existing configuration file will be saved in the file with the
4327
original, with the date and time added. For example, the mysql.ini
4328
will be copied to mysql 2009-10-27 1646.ini.bak.
4330
The parameters that you can specify on the command line are listed
4333
Table 2.5. MySQL Server Instance Config Wizard Parameters
4334
Parameter Description
4335
ServiceName=$ Specify the name of the service to be created
4336
AddBinToPath={yes | no} Specifies whether to add the binary
4337
directory of MySQL to the standard PATH environment variable
4338
ServerType={DEVELOPMENT | SERVER | DEDICATED} Specify the server
4339
type. For more information, see Section 2.5.4.4, "The Server Type
4341
DatabaseType={MIXED | INNODB | MYISAM} Specify the default
4342
database type. For more information, see Section 2.5.4.5, "The
4343
Database Usage Dialog"
4344
ConnectionUsage={DSS | OLTP} Specify the type of connection
4345
support, this automates the setting for the number of concurrent
4346
connections (see the ConnectionCount parameter). For more
4347
information, see Section 2.5.4.7, "The Concurrent Connections
4349
ConnectionCount=# Specify the number of concurrent connections to
4350
support. For more information, see Section 2.5.4.4, "The Server
4352
SkipNetworking={yes | no} Specify whether network support should
4353
be supported. Specifying yes disables network access altogether
4354
Port=# Specify the network port number to use for network
4355
connections. For more information, see Section 2.5.4.8, "The
4356
Networking and Strict Mode Options Dialog"
4357
StrictMode={yes | no} Specify whether to use the strict SQL mode.
4358
For more information, see Section 2.5.4.8, "The Networking and
4359
Strict Mode Options Dialog"
4360
Charset=$ Specify the default character set. For more information,
4361
see Section 2.5.4.9, "The Character Set Dialog"
4362
RootPassword=$ Specify the root password
4363
RootCurrentPassword=$ Specify the current root password then
4364
stopping and/or reconfiguring an existing service
4368
When specifying options on the command line, you can enclose the
4369
entire command-line option and the value you are specifying using
4370
double quotes. This enables you to use spaces in the options. For
4371
example, "-cC:\mysql.ini".
4373
The following command installs a MySQL Server 5.1 instance from
4374
the directory C:\Program Files\MySQL\MySQL Server 5.1 using the
4375
service name MySQL51 and setting the root password to 1234.
4376
shell> MySQLInstanceConfig.exe -i -q "-lC:\mysql_install_log.txt" Ā»
4377
"-nMySQL Server 5.1" "-pC:\Program Files\MySQL\MySQL Server 5.1" -
4379
"-tmy-template.ini" "-cC:\mytest.ini" ServerType=DEVELOPMENT Datab
4381
ConnectionUsage=DSS Port=3311 ServiceName=MySQL51 RootPassword=123
4384
In the above example, a log file will be generated in
4385
mysql_install_log.txt containing the information about the
4386
instance creation process. The log file generated by the above
4387
example is shown below:
4388
Welcome to the MySQL Server Instance Configuration Wizard 1.0.16.0
4389
Date: 2009-10-27 17:07:21
4391
Installing service ...
4393
Product Name: MySQL Server 5.1
4395
Installation Path: C:\Program Files\MySQL\MySQL Server 5.1\
4397
Creating configuration file C:\mytest.ini using template my-template.
4407
default-character-set: latin1
4408
basedir: "C:/Program Files/MySQL/MySQL Server 5.1/"
4409
datadir: "C:/Program Files/MySQL/MySQL Server 5.1/Data/"
4412
Creating Windows service entry.
4413
Service name: "MySQL51"
4414
Parameters: "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --
4415
defaults-file="C:\mytest.ini" MySQL51.
4416
Windows service MySQL51 installed.
4418
When using the command-line, the return values in the following
4419
table indicate an error performing the specified option.
4421
Table 2.6. Return Value from MySQL Server Instance Config Wizard
4423
2 Configuration template file cannot be found
4424
3 The Windows service entry cannot be created
4425
4 Could not connect to the Service Control Manager
4426
5 The MySQL service cannot be started
4427
6 The MySQL service cannot be stopped
4428
7 The security settings cannot be applied
4429
8 The configuration file cannot be written
4430
9 The Windows service entry cannot be removed
4432
You can perform an installation of MySQL automatically using the
4433
MSI packe. For more information, see Section 2.5.3.2, "Installing
4434
MySQL Automatically using MSI."
4436
2.5.5. Installing MySQL from a noinstall Zip Archive
4438
Users who are installing from the noinstall package can use the
4439
instructions in this section to manually install MySQL. The
4440
process for installing MySQL from a Zip archive is as follows:
4442
1. Extract the archive to the desired install directory
4444
2. Create an option file
4446
3. Choose a MySQL server type
4448
4. Start the MySQL server
4450
5. Secure the default user accounts
4452
This process is described in the sections that follow.
4454
2.5.5.1. Extracting the Install Archive
4456
To install MySQL manually, do the following:
4458
1. If you are upgrading from a previous version please refer to
4459
Section 2.5.7, "Upgrading MySQL on Windows," before beginning
4460
the upgrade process.
4462
2. Make sure that you are logged in as a user with administrator
4465
3. Choose an installation location. Traditionally, the MySQL
4466
server is installed in C:\mysql. The MySQL Installation Wizard
4467
installs MySQL under C:\Program Files\MySQL. If you do not
4468
install MySQL at C:\mysql, you must specify the path to the
4469
install directory during startup or in an option file. See
4470
Section 2.5.5.2, "Creating an Option File."
4472
4. Extract the install archive to the chosen installation
4473
location using your preferred Zip archive tool. Some tools may
4474
extract the archive to a folder within your chosen
4475
installation location. If this occurs, you can move the
4476
contents of the subfolder into the chosen installation
4479
2.5.5.2. Creating an Option File
4481
If you need to specify startup options when you run the server,
4482
you can indicate them on the command line or place them in an
4483
option file. For options that are used every time the server
4484
starts, you may find it most convenient to use an option file to
4485
specify your MySQL configuration. This is particularly true under
4486
the following circumstances:
4488
* The installation or data directory locations are different
4489
from the default locations (C:\Program Files\MySQL\MySQL
4490
Server 5.1 and C:\Program Files\MySQL\MySQL Server 5.1\data).
4492
* You need to tune the server settings, such as memory, cache,
4493
or InnoDB configuration information.
4495
When the MySQL server starts on Windows, it looks for option files
4496
in several locations, such as the Windows directory, C:\, and the
4497
MySQL installation directory (for the full list of locations, see
4498
Section 4.2.3.3, "Using Option Files"). The Windows directory
4499
typically is named something like C:\WINDOWS. You can determine
4500
its exact location from the value of the WINDIR environment
4501
variable using the following command:
4504
MySQL looks for options in each location first in the my.ini file,
4505
and then in the my.cnf file. However, to avoid confusion, it is
4506
best if you use only one file. If your PC uses a boot loader where
4507
C: is not the boot drive, your only option is to use the my.ini
4508
file. Whichever option file you use, it must be a plain text file.
4510
You can also make use of the example option files included with
4511
your MySQL distribution; see Section 4.2.3.3.2, "Preconfigured
4514
An option file can be created and modified with any text editor,
4515
such as Notepad. For example, if MySQL is installed in E:\mysql
4516
and the data directory is in E:\mydata\data, you can create an
4517
option file containing a [mysqld] section to specify values for
4518
the basedir and datadir options:
4520
# set basedir to your installation path
4522
# set datadir to the location of your data directory
4523
datadir=E:/mydata/data
4525
Note that Windows path names are specified in option files using
4526
(forward) slashes rather than backslashes. If you do use
4527
backslashes, double them:
4529
# set basedir to your installation path
4531
# set datadir to the location of your data directory
4532
datadir=E:\\mydata\\data
4534
The rules for use of backslash in option file values are given in
4535
Section 4.2.3.3, "Using Option Files."
4537
MySQL Enterprise For expert advice on the start-up options
4538
appropriate to your circumstances, subscribe to the MySQL
4539
Enterprise Monitor. For more information, see
4540
http://www.mysql.com/products/enterprise/advisors.html.
4542
In MySQL 5.1.23 and earlier, the MySQL installer places the data
4543
directory directly under the directory where you install MySQL. On
4544
MySQL 5.1.24 and later, the data directory is located within the
4545
AppData directory for the user running MySQL.
4547
If you would like to use a data directory in a different location,
4548
you should copy the entire contents of the data directory to the
4549
new location. For example, if you want to use E:\mydata as the
4550
data directory instead, you must do two things:
4552
1. Move the entire data directory and all of its contents from
4553
the default location (for example C:\Program Files\MySQL\MySQL
4554
Server 5.1\data) to E:\mydata.
4556
2. Use a --datadir option to specify the new data directory
4557
location each time you start the server.
4559
2.5.5.3. Selecting a MySQL Server Type
4561
The following table shows the available servers for Windows in
4562
MySQL 5.1.20 and earlier.
4564
mysqld-nt Optimized binary with named-pipe support
4565
mysqld Optimized binary without named-pipe support
4566
mysqld-debug Like mysqld-nt, but compiled with full debugging and
4567
automatic memory allocation checking
4569
The following table shows the available servers for Windows in
4570
MySQL 5.1.21 and later.
4572
mysqld Optimized binary with named-pipe support
4573
mysqld-debug Like mysqld, but compiled with full debugging and
4574
automatic memory allocation checking
4576
All of the preceding binaries are optimized for modern Intel
4577
processors, but should work on any Intel i386-class or higher
4580
Each of the servers in a distribution support the same set of
4581
storage engines. The SHOW ENGINES statement displays which engines
4582
a given server supports.
4584
All Windows MySQL 5.1 servers have support for symbolic linking of
4585
database directories.
4587
MySQL supports TCP/IP on all Windows platforms. MySQL servers on
4588
Windows support named pipes as indicated in the following list.
4589
However, the default is to use TCP/IP regardless of platform.
4590
(Named pipes are slower than TCP/IP in many Windows
4593
Use of named pipes is subject to these conditions:
4595
* Named pipes are enabled only if you start the server with the
4596
--enable-named-pipe option. It is necessary to use this option
4597
explicitly because some users have experienced problems with
4598
shutting down the MySQL server when named pipes were used.
4600
* For MySQL 5.1.20 and earlier, named-pipe connections are
4601
allowed only by the mysqld-nt and mysqld-debug servers. For
4602
MySQL 5.1.21 and later, the mysqld and mysqld-debug servers
4603
both contain support for named-pipe connections.
4607
Most of the examples in this manual use mysqld as the server name.
4608
If you choose to use a different server, such as mysqld-nt or
4609
mysqld-debug, make the appropriate substitutions in the commands
4610
that are shown in the examples.
4612
2.5.5.4. Starting the Server for the First Time
4614
This section gives a general overview of starting the MySQL
4615
server. The following sections provide more specific information
4616
for starting the MySQL server from the command line or as a
4619
The information here applies primarily if you installed MySQL
4620
using the Noinstall version, or if you wish to configure and test
4621
MySQL manually rather than with the GUI tools.
4623
The examples in these sections assume that MySQL is installed
4624
under the default location of C:\Program Files\MySQL\MySQL Server
4625
5.1. Adjust the path names shown in the examples if you have MySQL
4626
installed in a different location.
4628
Clients have two options. They can use TCP/IP, or they can use a
4629
named pipe if the server supports named-pipe connections.
4631
MySQL for Windows also supports shared-memory connections if the
4632
server is started with the --shared-memory option. Clients can
4633
connect through shared memory by using the --protocol=MEMORY
4636
For information about which server binary to run, see Section
4637
2.5.5.3, "Selecting a MySQL Server Type."
4639
Testing is best done from a command prompt in a console window (or
4640
"DOS window"). In this way you can have the server display status
4641
messages in the window where they are easy to see. If something is
4642
wrong with your configuration, these messages make it easier for
4643
you to identify and fix any problems.
4645
To start the server, enter this command:
4646
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --console
4648
For a server that includes InnoDB support, you should see the
4649
messages similar to those following as it starts (the path names
4650
and sizes may differ):
4651
InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist:
4652
InnoDB: a new database to be created!
4653
InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
4654
InnoDB: Database physically writes the file full: wait...
4655
InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be creat
4657
InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
4658
InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be creat
4660
InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
4661
InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be creat
4663
InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
4664
InnoDB: Doublewrite buffer not found: creating new
4665
InnoDB: Doublewrite buffer created
4666
InnoDB: creating foreign key constraint system tables
4667
InnoDB: foreign key constraint system tables created
4668
011024 10:58:25 InnoDB: Started
4670
When the server finishes its startup sequence, you should see
4671
something like this, which indicates that the server is ready to
4672
service client connections:
4673
mysqld: ready for connections
4674
Version: '5.1.45' socket: '' port: 3306
4676
The server continues to write to the console any further
4677
diagnostic output it produces. You can open a new console window
4678
in which to run client programs.
4680
If you omit the --console option, the server writes diagnostic
4681
output to the error log in the data directory (C:\Program
4682
Files\MySQL\MySQL Server 5.1\data by default). The error log is
4683
the file with the .err extension.
4687
The accounts that are listed in the MySQL grant tables initially
4688
have no passwords. After starting the server, you should set up
4689
passwords for them using the instructions in Section 2.13,
4690
"Post-Installation Setup and Testing."
4692
2.5.5.5. Starting MySQL from the Windows Command Line
4694
The MySQL server can be started manually from the command line.
4695
This can be done on any version of Windows.
4697
To start the mysqld server from the command line, you should start
4698
a console window (or "DOS window") and enter this command:
4699
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld"
4701
The path to mysqld may vary depending on the install location of
4702
MySQL on your system.
4704
You can stop the MySQL server by executing this command:
4705
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqladmin" -u root
4710
If the MySQL root user account has a password, you need to invoke
4711
mysqladmin with the -p option and supply the password when
4714
This command invokes the MySQL administrative utility mysqladmin
4715
to connect to the server and tell it to shut down. The command
4716
connects as the MySQL root user, which is the default
4717
administrative account in the MySQL grant system. Note that users
4718
in the MySQL grant system are wholly independent from any login
4719
users under Windows.
4721
If mysqld doesn't start, check the error log to see whether the
4722
server wrote any messages there to indicate the cause of the
4723
problem. The error log is located in the C:\Program
4724
Files\MySQL\MySQL Server 5.1\data directory. It is the file with a
4725
suffix of .err. You can also try to start the server as mysqld
4726
--console; in this case, you may get some useful information on
4727
the screen that may help solve the problem.
4729
The last option is to start mysqld with the --standalone and
4730
--debug options. In this case, mysqld writes a log file
4731
C:\mysqld.trace that should contain the reason why mysqld doesn't
4732
start. See MySQL Internals: Porting
4733
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
4735
Use mysqld --verbose --help to display all the options that mysqld
4738
2.5.5.6. Starting MySQL as a Windows Service
4740
On Windows, the recommended way to run MySQL is to install it as a
4741
Windows service, whereby MySQL starts and stops automatically when
4742
Windows starts and stops. A MySQL server installed as a service
4743
can also be controlled from the command line using NET commands,
4744
or with the graphical Services utility. Generally, to install
4745
MySQL as a Windows service you should be logged in using an
4746
account that has administrator rights.
4748
The Services utility (the Windows Service Control Manager) can be
4749
found in the Windows Control Panel (under Administrative Tools on
4750
Windows 2000, XP, Vista and Server 2003). To avoid conflicts, it
4751
is advisable to close the Services utility while performing server
4752
installation or removal operations from the command line.
4754
Before installing MySQL as a Windows service, you should first
4755
stop the current server if it is running by using the following
4757
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqladmin"
4762
If the MySQL root user account has a password, you need to invoke
4763
mysqladmin with the -p option and supply the password when
4766
This command invokes the MySQL administrative utility mysqladmin
4767
to connect to the server and tell it to shut down. The command
4768
connects as the MySQL root user, which is the default
4769
administrative account in the MySQL grant system. Note that users
4770
in the MySQL grant system are wholly independent from any login
4771
users under Windows.
4773
Install the server as a service using this command:
4774
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --install
4776
The service-installation command does not start the server.
4777
Instructions for that are given later in this section.
4779
To make it easier to invoke MySQL programs, you can add the path
4780
name of the MySQL bin directory to your Windows system PATH
4781
environment variable:
4783
* On the Windows desktop, right-click on the My Computer icon,
4784
and select Properties.
4786
* Next select the Advanced tab from the System Properties menu
4787
that appears, and click the Environment Variables button.
4789
* Under System Variables, select Path, and then click the Edit
4790
button. The Edit System Variable dialogue should appear.
4792
* Place your cursor at the end of the text appearing in the
4793
space marked Variable Value. (Use the End key to ensure that
4794
your cursor is positioned at the very end of the text in this
4795
space.) Then enter the complete path name of your MySQL bin
4796
directory (for example, C:\Program Files\MySQL\MySQL Server
4797
5.1\bin), Note that there should be a semicolon separating
4798
this path from any values present in this field. Dismiss this
4799
dialogue, and each dialogue in turn, by clicking OK until all
4800
of the dialogues that were opened have been dismissed. You
4801
should now be able to invoke any MySQL executable program by
4802
typing its name at the DOS prompt from any directory on the
4803
system, without having to supply the path. This includes the
4804
servers, the mysql client, and all MySQL command-line
4805
utilities such as mysqladmin and mysqldump.
4806
You should not add the MySQL bin directory to your Windows
4807
PATH if you are running multiple MySQL servers on the same
4812
You must exercise great care when editing your system PATH by
4813
hand; accidental deletion or modification of any portion of the
4814
existing PATH value can leave you with a malfunctioning or even
4817
The following additional arguments can be used in MySQL 5.1 when
4818
installing the service:
4820
* You can specify a service name immediately following the
4821
--install option. The default service name is MySQL.
4823
* If a service name is given, it can be followed by a single
4824
option. By convention, this should be
4825
--defaults-file=file_name to specify the name of an option
4826
file from which the server should read options when it starts.
4827
The use of a single option other than --defaults-file is
4828
possible but discouraged. --defaults-file is more flexible
4829
because it enables you to specify multiple startup options for
4830
the server by placing them in the named option file.
4832
* You can also specify a --local-service option following the
4833
service name. This causes the server to run using the
4834
LocalService Windows account that has limited system
4835
privileges. This account is available only for Windows XP or
4836
newer. If both --defaults-file and --local-service are given
4837
following the service name, they can be in any order.
4839
For a MySQL server that is installed as a Windows service, the
4840
following rules determine the service name and option files that
4843
* If the service-installation command specifies no service name
4844
or the default service name (MySQL) following the --install
4845
option, the server uses the a service name of MySQL and reads
4846
options from the [mysqld] group in the standard option files.
4848
* If the service-installation command specifies a service name
4849
other than MySQL following the --install option, the server
4850
uses that service name. It reads options from the [mysqld]
4851
group and the group that has the same name as the service in
4852
the standard option files. This allows you to use the [mysqld]
4853
group for options that should be used by all MySQL services,
4854
and an option group with the service name for use by the
4855
server installed with that service name.
4857
* If the service-installation command specifies a
4858
--defaults-file option after the service name, the server
4859
reads options only from the [mysqld] group of the named file
4860
and ignores the standard option files.
4862
As a more complex example, consider the following command:
4863
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld"
4864
--install MySQL --defaults-file=C:\my-opts.cnf
4866
Here, the default service name (MySQL) is given after the
4867
--install option. If no --defaults-file option had been given,
4868
this command would have the effect of causing the server to read
4869
the [mysqld] group from the standard option files. However,
4870
because the --defaults-file option is present, the server reads
4871
options from the [mysqld] option group, and only from the named
4874
You can also specify options as Start parameters in the Windows
4875
Services utility before you start the MySQL service.
4877
Once a MySQL server has been installed as a service, Windows
4878
starts the service automatically whenever Windows starts. The
4879
service also can be started immediately from the Services utility,
4880
or by using a NET START MySQL command. The NET command is not case
4883
When run as a service, mysqld has no access to a console window,
4884
so no messages can be seen there. If mysqld does not start, check
4885
the error log to see whether the server wrote any messages there
4886
to indicate the cause of the problem. The error log is located in
4887
the MySQL data directory (for example, C:\Program
4888
Files\MySQL\MySQL Server 5.1\data). It is the file with a suffix
4891
When a MySQL server has been installed as a service, and the
4892
service is running, Windows stops the service automatically when
4893
Windows shuts down. The server also can be stopped manually by
4894
using the Services utility, the NET STOP MySQL command, or the
4895
mysqladmin shutdown command.
4897
You also have the choice of installing the server as a manual
4898
service if you do not wish for the service to be started
4899
automatically during the boot process. To do this, use the
4900
--install-manual option rather than the --install option:
4901
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --install-m
4904
To remove a server that is installed as a service, first stop it
4905
if it is running by executing NET STOP MySQL. Then use the
4906
--remove option to remove it:
4907
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqld" --remove
4909
If mysqld is not running as a service, you can start it from the
4910
command line. For instructions, see Section 2.5.5.5, "Starting
4911
MySQL from the Windows Command Line."
4913
Please see Section 2.5.6, "Troubleshooting a MySQL Installation
4914
Under Windows," if you encounter difficulties during installation.
4916
2.5.5.7. Testing The MySQL Installation
4918
You can test whether the MySQL server is working by executing any
4919
of the following commands:
4920
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqlshow"
4921
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqlshow" -u root
4923
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqladmin" version
4925
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysql" test
4929
By default, mysqlshow will try to connect using the ODBC user.
4930
This user is not created by default. You should specify a valid
4931
user, or root with the right password to check the operation of
4934
If mysqld is slow to respond to TCP/IP connections from client
4935
programs, there is probably a problem with your DNS. In this case,
4936
start mysqld with the --skip-name-resolve option and use only
4937
localhost and IP numbers in the Host column of the MySQL grant
4940
You can force a MySQL client to use a named-pipe connection rather
4941
than TCP/IP by specifying the --pipe or --protocol=PIPE option, or
4942
by specifying . (period) as the host name. Use the --socket option
4943
to specify the name of the pipe if you do not want to use the
4946
Note that if you have set a password for the root account, deleted
4947
the anonymous account, or created a new user account, then you
4948
must use the appropriate -u and -p options with the commands shown
4949
above in order to connect with the MySQL Server. See Section
4950
4.2.2, "Connecting to the MySQL Server."
4952
For more information about mysqlshow, see Section 4.5.6,
4953
"mysqlshow --- Display Database, Table, and Column Information."
4955
2.5.6. Troubleshooting a MySQL Installation Under Windows
4957
When installing and running MySQL for the first time, you may
4958
encounter certain errors that prevent the MySQL server from
4959
starting. The purpose of this section is to help you diagnose and
4960
correct some of these errors.
4962
Your first resource when troubleshooting server issues is the
4963
error log. The MySQL server uses the error log to record
4964
information relevant to the error that prevents the server from
4965
starting. The error log is located in the data directory specified
4966
in your my.ini file. The default data directory location is
4967
C:\Program Files\MySQL\MySQL Server 5.1\data. See Section 5.2.2,
4970
Another source of information regarding possible errors is the
4971
console messages displayed when the MySQL service is starting. Use
4972
the NET START MySQL command from the command line after installing
4973
mysqld as a service to see any error messages regarding the
4974
starting of the MySQL server as a service. See Section 2.5.5.6,
4975
"Starting MySQL as a Windows Service."
4977
The following examples show other common error messages you may
4978
encounter when installing MySQL and starting the server for the
4981
* If the MySQL server cannot find the mysql privileges database
4982
or other critical files, you may see these messages:
4983
System error 1067 has occurred.
4984
Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't
4986
These messages often occur when the MySQL base or data
4987
directories are installed in different locations than the
4988
default locations (C:\Program Files\MySQL\MySQL Server 5.1 and
4989
C:\Program Files\MySQL\MySQL Server 5.1\data, respectively).
4990
This situation may occur when MySQL is upgraded and installed
4991
to a new location, but the configuration file is not updated
4992
to reflect the new location. In addition, there may be old and
4993
new configuration files that conflict. Be sure to delete or
4994
rename any old configuration files when upgrading MySQL.
4995
If you have installed MySQL to a directory other than
4996
C:\Program Files\MySQL\MySQL Server 5.1, you need to ensure
4997
that the MySQL server is aware of this through the use of a
4998
configuration (my.ini) file. The my.ini file needs to be
4999
located in your Windows directory, typically C:\WINDOWS. You
5000
can determine its exact location from the value of the WINDIR
5001
environment variable by issuing the following command from the
5004
An option file can be created and modified with any text
5005
editor, such as Notepad. For example, if MySQL is installed in
5006
E:\mysql and the data directory is D:\MySQLdata, you can
5007
create the option file and set up a [mysqld] section to
5008
specify values for the basedir and datadir options:
5010
# set basedir to your installation path
5012
# set datadir to the location of your data directory
5013
datadir=D:/MySQLdata
5014
Note that Windows path names are specified in option files
5015
using (forward) slashes rather than backslashes. If you do use
5016
backslashes, double them:
5018
# set basedir to your installation path
5019
basedir=C:\\Program Files\\MySQL\\MySQL Server 5.1
5020
# set datadir to the location of your data directory
5021
datadir=D:\\MySQLdata
5022
The rules for use of backslash in option file values are given
5023
in Section 4.2.3.3, "Using Option Files."
5024
If you change the datadir value in your MySQL configuration
5025
file, you must move the contents of the existing MySQL data
5026
directory before restarting the MySQL server.
5027
See Section 2.5.5.2, "Creating an Option File."
5029
* If you reinstall or upgrade MySQL without first stopping and
5030
removing the existing MySQL service and install MySQL using
5031
the MySQL Config Wizard, you may see this error:
5032
Error: Cannot create Windows service for MySql. Error: 0
5033
This occurs when the Config Wizard tries to install the
5034
service and finds an existing service with the same name.
5035
One solution to this problem is to choose a service name other
5036
than mysql when using the configuration wizard. This allows
5037
the new service to be installed correctly, but leaves the
5038
outdated service in place. Although this is harmless, it is
5039
best to remove old services that are no longer in use.
5040
To permanently remove the old mysql service, execute the
5041
following command as a user with administrative privileges, on
5043
C:\> sc delete mysql
5044
[SC] DeleteService SUCCESS
5045
If the sc utility is not available for your version of
5046
Windows, download the delsrv utility from
5047
http://www.microsoft.com/windows2000/techinfo/reskit/tools/exi
5048
sting/delsrv-o.asp and use the delsrv mysql syntax.
5050
2.5.7. Upgrading MySQL on Windows
5052
This section lists some of the steps you should take when
5053
upgrading MySQL on Windows.
5055
1. Review Section 2.4.1, "Upgrading MySQL," for additional
5056
information on upgrading MySQL that is not specific to
5059
2. You should always back up your current MySQL installation
5060
before performing an upgrade. See Section 6.2, "Database
5063
3. Download the latest Windows distribution of MySQL from
5064
http://dev.mysql.com/downloads/.
5066
4. Before upgrading MySQL, you must stop the server. If the
5067
server is installed as a service, stop the service with the
5068
following command from the command prompt:
5070
If you are not running the MySQL server as a service, use the
5071
following command to stop it:
5072
C:\> "C:\Program Files\MySQL\MySQL Server 5.1\bin\mysqladmin" -u root
5076
If the MySQL root user account has a password, you need to
5077
invoke mysqladmin with the -p option and supply the password
5080
5. When upgrading to MySQL 5.1 from a version previous to 4.1.5,
5081
or when upgrading from a version of MySQL installed from a Zip
5082
archive to a version of MySQL installed with the MySQL
5083
Installation Wizard, you must manually remove the previous
5084
installation and MySQL service (if the server is installed as
5086
To remove the MySQL service, use the following command:
5087
C:\> C:\mysql\bin\mysqld --remove
5088
If you do not remove the existing service, the MySQL
5089
Installation Wizard may fail to properly install the new MySQL
5092
6. When upgrading from MySQL 5.1.23 to MySQL 5.1.24, the change
5093
in the default location of the data directory from a directory
5094
within the MySQL installation to the AppData folder means that
5095
you must manually copy the data files from your old
5096
installation to the new location.
5098
7. If you are using the MySQL Installation Wizard, start the
5099
wizard as described in Section 2.5.3.1, "Using the MySQL
5100
Installation Wizard."
5102
8. If you are installing MySQL from a Zip archive, extract the
5103
archive. You may either overwrite your existing MySQL
5104
installation (usually located at C:\mysql), or install it into
5105
a different directory, such as C:\mysql5. Overwriting the
5106
existing installation is recommended.
5108
9. If you were running MySQL as a Windows service and you had to
5109
remove the service earlier in this procedure, reinstall the
5110
service. (See Section 2.5.5.6, "Starting MySQL as a Windows
5112
10. Restart the server. For example, use NET START MySQL if you
5113
run MySQL as a service, or invoke mysqld directly otherwise.
5114
11. If you encounter errors, see Section 2.5.6, "Troubleshooting a
5115
MySQL Installation Under Windows."
5117
2.5.8. Windows Post-Installation Procedures
5119
On Windows, the data directory and the grant tables do not have to
5120
be created. MySQL Windows distributions include the grant tables
5121
with a set of preinitialized accounts in the mysql database under
5122
the data directory. It is unnecessary to run the mysql_install_db
5123
script that is used on Unix. Regarding passwords, if you installed
5124
MySQL using the Windows Installation Wizard, you may have already
5125
assigned passwords to the accounts. (See Section 2.5.3.1, "Using
5126
the MySQL Installation Wizard.") Otherwise, use the
5127
password-assignment procedure given in Section 2.13.2, "Securing
5128
the Initial MySQL Accounts."
5130
Before setting up passwords, you might want to try running some
5131
client programs to make sure that you can connect to the server
5132
and that it is operating properly. Make sure that the server is
5133
running (see Section 2.5.5.4, "Starting the Server for the First
5134
Time"), and then issue the following commands to verify that you
5135
can retrieve information from the server. The output should be
5136
similar to what is shown here:
5137
C:\> C:\mysql\bin\mysqlshow
5138
+--------------------+
5140
+--------------------+
5141
| information_schema |
5144
+--------------------+
5148
The above may not work if the correct user does not exist. If you
5149
installed using the MSI packages and used the MySQL Server
5150
Instance Config Wizard, then the root will haqve been created
5151
automatically with the password you supplied. In this case, you
5152
should use the -u and -p options where you will be prompted for
5157
The list of installed databases may vary, but will always include
5158
the minimum of mysql and information_schema. In most cases, the
5159
test database will also be installed automatically.
5161
If you specify the name of the database, then a list of the tables
5162
within a given database will be displayed:
5163
C:\> C:\mysql\bin\mysqlshow mysql
5165
+---------------------------+
5167
+---------------------------+
5185
| time_zone_leap_second |
5187
| time_zone_transition |
5188
| time_zone_transition_type |
5190
+---------------------------+
5193
C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql
5194
+------+-------+------+
5195
| host | db | user |
5196
+------+-------+------+
5198
+------+-------+------+
5200
You may need to specify a different directory from the one shown;
5201
if you used the Windows Installation Wizard, then the default
5202
directory is C:\Program Files\MySQL\MySQL Server 5.1, and the
5203
mysql and mysqlshow client programs are in C:\Program
5204
Files\MySQL\MySQL Server 5.1\bin. See Section 2.5.3.1, "Using the
5205
MySQL Installation Wizard," for more information.
5207
If you have already secured the initial MySQL accounts, you may
5208
need to use the -u and -p options to supply a user name and
5209
password to the mysqlshow and mysql client programs; otherwise the
5210
programs may fail with an error, or you may not be able to view
5211
all databases. For example, if you have assigned the password
5212
"secretpass" to the MySQL root account, then you can invoke
5213
mysqlshow and mysql as shown here:
5214
C:\> C:\mysql\bin\mysqlshow -uroot -psecretpass
5215
+--------------------+
5217
+--------------------+
5218
| information_schema |
5221
+--------------------+
5223
C:\> C:\mysql\bin\mysqlshow -uroot -psecretpass mysql
5225
+---------------------------+
5227
+---------------------------+
5245
| time_zone_leap_second |
5247
| time_zone_transition |
5248
| time_zone_transition_type |
5250
+---------------------------+
5253
C:\> C:\mysql\bin\mysql -uroot -psecretpass -e "SELECT Host,Db,User F
5255
+------+-------+------+
5256
| host | db | user |
5257
+------+-------+------+
5259
+------+-------+------+
5261
For more information about these programs, see Section 4.5.6,
5262
"mysqlshow --- Display Database, Table, and Column Information,"
5263
and Section 4.5.1, "mysql --- The MySQL Command-Line Tool."
5265
If you are running a version of Windows that supports services and
5266
you want the MySQL server to run automatically when Windows
5267
starts, see Section 2.5.5.6, "Starting MySQL as a Windows
5270
2.5.9. MySQL on Windows Compared to MySQL on Unix
5272
MySQL for Windows has proven itself to be very stable. The Windows
5273
version of MySQL has the same features as the corresponding Unix
5274
version, with the following exceptions:
5276
* Limited number of ports
5277
Windows systems have about 4,000 ports available for client
5278
connections, and after a connection on a port closes, it takes
5279
two to four minutes before the port can be reused. In
5280
situations where clients connect to and disconnect from the
5281
server at a high rate, it is possible for all available ports
5282
to be used up before closed ports become available again. If
5283
this happens, the MySQL server appears to be unresponsive even
5284
though it is running. Note that ports may be used by other
5285
applications running on the machine as well, in which case the
5286
number of ports available to MySQL is lower.
5287
For more information about this problem, see
5288
http://support.microsoft.com/default.aspx?scid=kb;en-us;196271
5292
MySQL depends on the pread() and pwrite() system calls to be
5293
able to mix INSERT and SELECT. Currently, we use mutexes to
5294
emulate pread() and pwrite(). We intend to replace the file
5295
level interface with a virtual interface in the future so that
5296
we can use the readfile()/writefile() interface to get more
5297
speed. The current implementation limits the number of open
5298
files that MySQL 5.1 can use to 2,048, which means that you
5299
cannot run as many concurrent threads on Windows as on Unix.
5302
MySQL uses a blocking read for each connection. That has the
5303
following implications if named-pipe connections are enabled:
5305
+ A connection is not disconnected automatically after
5306
eight hours, as happens with the Unix version of MySQL.
5308
+ If a connection hangs, it is not possible to break it
5309
without killing MySQL.
5311
+ mysqladmin kill does not work on a sleeping connection.
5313
+ mysqladmin shutdown cannot abort as long as there are
5314
sleeping connections.
5315
We plan to fix this problem in the future.
5318
While you are executing an ALTER TABLE statement, the table is
5319
locked from being used by other threads. This has to do with
5320
the fact that on Windows, you can't delete a file that is in
5321
use by another thread. In the future, we may find some way to
5322
work around this problem.
5324
* DATA DIRECTORY and INDEX DIRECTORY
5325
The DATA DIRECTORY and INDEX DIRECTORY options for CREATE
5326
TABLE are ignored on Windows, because Windows doesn't support
5327
symbolic links. These options also are ignored on systems that
5328
have a nonfunctional realpath() call.
5331
You cannot drop a database that is in use by another thread.
5333
* Case-insensitive names
5334
File names are not case sensitive on Windows, so MySQL
5335
database and table names are also not case sensitive on
5336
Windows. The only restriction is that database and table names
5337
must be specified using the same case throughout a given
5338
statement. See Section 8.2.2, "Identifier Case Sensitivity."
5340
* Directory and file names
5341
On Windows, MySQL Server supports only directory and file
5342
names that are compatible with the current ANSI code pages.
5343
For example, the following Japanese directory name will not
5344
work in the Western locale (code page 1252):
5345
datadir="C:/ē§ćć”ć®ćććøć§ćÆćć®ćć¼ćæ"
5346
The same limitation applies to directory and file names
5347
referred to in SQL statements, such as the data file path name
5348
in LOAD DATA INFILE.
5350
* The "\" path name separator character
5351
Path name components in Windows are separated by the "\"
5352
character, which is also the escape character in MySQL. If you
5353
are using LOAD DATA INFILE or SELECT ... INTO OUTFILE, use
5354
Unix-style file names with "/" characters:
5355
mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr;
5356
mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;
5357
Alternatively, you must double the "\" character:
5358
mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr;
5359
mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;
5361
* Problems with pipes
5362
Pipes do not work reliably from the Windows command-line
5363
prompt. If the pipe includes the character ^Z / CHAR(24),
5364
Windows thinks that it has encountered end-of-file and aborts
5366
This is mainly a problem when you try to apply a binary log as
5368
C:\> mysqlbinlog binary_log_file | mysql --user=root
5369
If you have a problem applying the log and suspect that it is
5370
because of a ^Z / CHAR(24) character, you can use the
5371
following workaround:
5372
C:\> mysqlbinlog binary_log_file --result-file=/tmp/bin.sql
5373
C:\> mysql --user=root --execute "source /tmp/bin.sql"
5374
The latter command also can be used to reliably read in any
5375
SQL file that may contain binary data.
5377
* Access denied for user error
5378
If MySQL cannot resolve your host name properly, you may get
5379
the following error when you attempt to run a MySQL client
5380
program to connect to a server running on the same machine:
5381
Access denied for user 'some_user'@'unknown'
5383
To fix this problem, you should create a file named
5384
\windows\hosts containing the following information:
5387
Here are some open issues for anyone who might want to help us
5388
improve MySQL on Windows:
5390
* Add macros to use the faster thread-safe increment/decrement
5391
methods provided by Windows.
5393
2.5.10. Installing MySQL from Source on Windows
5395
These instructions describe how to build binaries from source for
5396
MySQL 5.1 on Windows. Instructions are provided for building
5397
binaries from a standard source distribution or from the Bazaar
5398
tree that contains the latest development source.
5402
The instructions here are strictly for users who want to test
5403
MySQL on Microsoft Windows from the latest source distribution or
5404
from the Bazaar tree. For production use, we do not advise using a
5405
MySQL server built by yourself from source. Normally, it is best
5406
to use precompiled binary distributions of MySQL that are built
5407
specifically for optimal performance on Windows by Sun
5408
Microsystems, Inc. Instructions for installing binary
5409
distributions are available in Section 2.5, "Installing MySQL on
5412
To build MySQL on Windows from source, you must satisfy the
5413
following system, compiler, and resource requirements:
5415
* Windows 2000, Windows XP, or newer version.
5416
Windows Vista is supported when using Visual Studio 2005
5417
provided you have installed the following updates:
5419
+ Microsoft Visual Studio 2005 Professional Edition - ENU
5420
Service Pack 1 (KB926601)
5421
(http://support.microsoft.com/?kbid=926601)
5423
+ Security Update for Microsoft Visual Studio 2005
5424
Professional Edition - ENU (KB937061)
5425
(http://support.microsoft.com/?kbid=937061)
5427
+ Update for Microsoft Visual Studio 2005 Professional
5428
Edition - ENU (KB932232)
5429
(http://support.microsoft.com/?kbid=932232)
5431
* CMake, which can be downloaded from http://www.cmake.org.
5432
After installing, modify your path to include the cmake
5435
* Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net
5436
2003 (7.1), or Visual Studio 2005 (8.0) compiler system.
5438
* If you are using Visual C++ 2005 Express Edition, you must
5439
also install an appropriate Platform SDK. More information and
5440
links to downloads for various Windows platforms is available
5442
http://www.microsoft.com/downloads/details.aspx?familyid=0baf2
5443
b35-c656-4969-ace8-e4c0c0716adb.
5445
* If you are compiling from a Bazaar tree or making changes to
5446
the parser, you need bison for Windows, which can be
5448
http://gnuwin32.sourceforge.net/packages/bison.htm. Download
5449
the package labeled "Complete package, excluding sources".
5450
After installing the package, modify your path to include the
5451
bison binary and ensure that this binary is accessible from
5454
* Cygwin might be necessary if you want to run the test script
5455
or package the compiled binaries and support files into a Zip
5456
archive. (Cygwin is needed only to test or package the
5457
distribution, not to build it.) Cygwin is available from
5460
* 3GB to 5GB of disk space.
5462
The exact system requirements for Visual Studio can be found here:
5463
http://msdn.microsoft.com/vstudio/Previous/2003/sysreqs/default.as
5465
http://msdn.microsoft.com/vstudio/products/sysreqs/default.aspx
5467
You also need a MySQL source distribution for Windows, which can
5468
be obtained two ways:
5470
* Obtain a source distribution packaged by Sun Microsystems,
5471
Inc. These are available from http://dev.mysql.com/downloads/.
5473
* Package a source distribution yourself from the latest Bazaar
5474
developer source tree. For instructions on pulling the latest
5475
source files, see Section 2.3.3, "Installing from the
5476
Development Source Tree."
5478
If you find something not working as expected, or you have
5479
suggestions about ways to improve the current build process on
5480
Windows, please send a message to the win32 mailing list. See
5481
Section 1.6.1, "MySQL Mailing Lists."
5483
2.5.10.1. Building MySQL from Source Using CMake and Visual Studio
5485
You can build MySQL on Windows by using a combination of cmake and
5486
Microsoft Visual Studio .NET 2003 (7.1), Microsoft Visual Studio
5487
2005 (8.0), Microsoft Visual Studio 2008 (9.0) or Microsoft Visual
5488
C++ 2005 Express Edition. You must have the appropriate Microsoft
5489
Platform SDK installed.
5493
To compile from the source code on Windows you must use the
5494
standard source distribution (for example, mysql-5.1.45.tar.gz).
5495
You build from the same distribution as used to build MySQL on
5496
Unix, Linux and other platforms. Do not use the Windows Source
5497
distributions as they do not contain the necessary configuration
5498
script and other files.
5500
Follow this procedure to build MySQL:
5502
1. If you are installing from a packaged source distribution,
5503
create a work directory (for example, C:\workdir), and unpack
5504
the source distribution there using WinZip or another Windows
5505
tool that can read .zip files. This directory is the work
5506
directory in the following instructions.
5509
You must run the commands in the win directory from the
5510
top-level source directory. Do not change into the win
5511
directory, as the commands will not be executed correctly.
5513
2. Start a command shell. If you have not configured the PATH and
5514
other environment variables for all command shells, you may be
5515
able to start a command shell from the Start Menu within the
5516
Windows Visual Studio menu that contains the necessary
5517
environment changes.
5519
3. Within the command shell, navigate to the work directory and
5520
run the following command:
5521
C:\workdir>win\configure.js options
5522
If you have associated the .js file extension with an
5523
application such as a text editor, then you may need to use
5524
the following command to force configure.js to be executed as
5526
C:\workdir>cscript win\configure.js options
5527
These options are available for configure.js:
5529
+ WITH_INNOBASE_STORAGE_ENGINE: Enable the InnoDB storage
5532
+ WITH_PARTITION_STORAGE_ENGINE: Enable user-defined
5535
+ WITH_ARCHIVE_STORAGE_ENGINE: Enable the ARCHIVE storage
5538
+ WITH_BLACKHOLE_STORAGE_ENGINE: Enable the BLACKHOLE
5541
+ WITH_EXAMPLE_STORAGE_ENGINE: Enable the EXAMPLE storage
5544
+ WITH_FEDERATED_STORAGE_ENGINE: Enable the FEDERATED
5547
+ WITH_NDBCLUSTER_STORAGE_ENGINE (experimental): Enable the
5548
NDBCLUSTER storage engine in the MySQL server; cause
5549
binaries for the MySQL Cluster management and data node,
5550
management client, and other programs to be built.
5551
This option is supported only in MySQL Cluster NDB 7.0
5552
(NDBCLUSTER storage engine versions 6.4.0 and later)
5553
using the MySQL Cluster sources. It cannot be used to
5554
enable clustering support in other MySQL source trees or
5557
+ MYSQL_SERVER_SUFFIX=suffix: Server suffix, default none.
5559
+ COMPILATION_COMMENT=comment: Server comment, default
5560
"Source distribution".
5562
+ MYSQL_TCP_PORT=port: Server port, default 3306.
5564
+ DISABLE_GRANT_OPTIONS: Disables the --bootstrap,
5565
--skip-grant-tables, and --init-file options for mysqld.
5566
This option is available as of MySQL 5.1.15.
5567
For example (type the command on one line):
5568
C:\workdir>win\configure.js WITH_INNOBASE_STORAGE_ENGINE
5569
WITH_PARTITION_STORAGE_ENGINE MYSQL_SERVER_SUFFIX=-pro
5571
4. From the work directory, execute the win\build-vs9.bat
5572
(Windows Visual Studio 2008), win\build-vs8.bat (Windows
5573
Visual Studio 2005), or win\build-vs71.bat (Windows Visual
5574
Stidion 2003) script, depending on the version of Visual
5575
Studio you have installed. The script invokes CMake, which
5576
generates the mysql.sln solution file.
5577
You can also use the corresponding 64-bit file (for example
5578
win\build-vs8_x64.bat or win\build-vs9_x64.bat) to build the
5579
64-bit version of MySQL. However, you cannot build the 64-bit
5580
version with Visual Studio Express Edition. You must use
5581
Visual Studio 2005 (8.0) or higher.
5583
5. From the work directory, open the generated mysql.sln file
5584
with Visual Studio and select the proper configuration using
5585
the Configuration menu. The menu provides Debug, Release,
5586
RelwithDebInfo, MinRelInfo options. Then select Solution >
5587
Build to build the solution.
5588
Remember the configuration that you use in this step. It is
5589
important later when you run the test script because that
5590
script needs to know which configuration you used.
5592
6. Test the server. The server built using the preceding
5593
instructions expects that the MySQL base directory and data
5594
directory are C:\mysql and C:\mysql\data by default. If you
5595
want to test your server using the source tree root directory
5596
and its data directory as the base directory and data
5597
directory, you need to tell the server their path names. You
5598
can either do this on the command line with the --basedir and
5599
--datadir options, or by placing appropriate options in an
5600
option file. (See Section 4.2.3.3, "Using Option Files.") If
5601
you have an existing data directory elsewhere that you want to
5602
use, you can specify its path name instead.
5603
When the server is running in standalone fashion or as a
5604
service based on your configuration, try to connect to it from
5605
the mysql interactive command-line utility.
5606
You can also run the standard test script, mysql-test-run.pl.
5607
This script is written in Perl, so you'll need either Cygwin
5608
or ActiveState Perl to run it. You may also need to install
5609
the modules required by the script. To run the test script,
5610
change location into the mysql-test directory under the work
5611
directory, set the MTR_VS_CONFIG environment variable to the
5612
configuration you selected earlier (or use the --vs-config
5613
option), and invoke mysql-test-run.pl. For example (using
5614
Cygwin and the bash shell):
5615
shell> cd mysql-test
5616
shell> export MTR_VS_CONFIG=debug
5617
shell> ./mysql-test-run.pl --force --timer
5618
shell> ./mysql-test-run.pl --force --timer --ps-protocol
5620
When you are satisfied that the programs you have built are
5621
working correctly, stop the server. Now you can install the
5622
distribution. One way to do this is to use the make_win_bin_dist
5623
script in the scripts directory of the MySQL source distribution
5624
(see Section 4.4.2, "make_win_bin_dist --- Package MySQL
5625
Distribution as ZIP Archive"). This is a shell script, so you must
5626
have Cygwin installed if you want to use it. It creates a Zip
5627
archive of the built executables and support files that you can
5628
unpack in the location at which you want to install MySQL.
5630
It is also possible to install MySQL by copying directories and
5633
1. Create the directories where you want to install MySQL. For
5634
example, to install into C:\mysql, use these commands:
5636
C:\> mkdir C:\mysql\bin
5637
C:\> mkdir C:\mysql\data
5638
C:\> mkdir C:\mysql\share
5639
C:\> mkdir C:\mysql\scripts
5640
If you want to compile other clients and link them to MySQL,
5641
you should also create several additional directories:
5642
C:\> mkdir C:\mysql\include
5643
C:\> mkdir C:\mysql\lib
5644
C:\> mkdir C:\mysql\lib\debug
5645
C:\> mkdir C:\mysql\lib\opt
5646
If you want to benchmark MySQL, create this directory:
5647
C:\> mkdir C:\mysql\sql-bench
5648
Benchmarking requires Perl support. See Section 2.15, "Perl
5649
Installation Notes."
5651
2. From the work directory, copy into the C:\mysql directory the
5652
following files and directories:
5654
C:\workdir> mkdir C:\mysql
5655
C:\workdir> mkdir C:\mysql\bin
5656
C:\workdir> copy client\Release\*.exe C:\mysql\bin
5657
C:\workdir> copy sql\Release\mysqld.exe C:\mysql\bin\mysqld.exe
5658
C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E
5659
C:\workdir> xcopy share\*.* C:\mysql\share /E
5660
If you want to compile other clients and link them to MySQL,
5661
you should also copy several libraries and header files:
5662
C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\debug
5663
C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\debug
5664
C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\debug
5665
C:\workdir> copy lib\Release\mysqlclient.lib C:\mysql\lib\opt
5666
C:\workdir> copy lib\Release\libmysql.* C:\mysql\lib\opt
5667
C:\workdir> copy lib\Release\zlib.* C:\mysql\lib\opt
5668
C:\workdir> copy include\*.h C:\mysql\include
5669
C:\workdir> copy libmysql\libmysql.def C:\mysql\include
5672
If you have compiled a Debug, rather than Release solution,
5673
you can replace Release with Debug in the source file names
5675
If you want to benchmark MySQL, you should also do this:
5676
C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E
5678
After installation, set up and start the server in the same way as
5679
for binary Windows distributions. This includes creating the
5680
system tables by running mysql_install_db. For more information,
5681
see Section 2.5, "Installing MySQL on Windows."
5683
2.5.11. Compiling MySQL Clients on Windows
5685
In your source files, you should include my_global.h before
5687
#include <my_global.h>
5690
my_global.h includes any other files needed for Windows
5691
compatibility (such as windows.h) if you compile your program on
5694
You can either link your code with the dynamic libmysql.lib
5695
library, which is just a wrapper to load in libmysql.dll on
5696
demand, or link with the static mysqlclient.lib library.
5698
The MySQL client libraries are compiled as threaded libraries, so
5699
you should also compile your code to be multi-threaded.
5701
2.6. Installing MySQL on Linux
5703
The following sections covers the installation of Linux using
5704
RPMs. For information on using a generic binary package using tar,
5705
see Section 2.2, "Installing MySQL from Generic Binaries on
5706
Unix/Linux." For information on installing from source, see
5707
Section 2.3, "MySQL Installation Using a Source Distribution."
5709
mysql.server can be found in the support-files directory under the
5710
MySQL installation directory or in a MySQL source tree. You can
5711
install it as /etc/init.d/mysql for automatic MySQL startup and
5712
shutdown. See Section 2.13.1.2, "Starting and Stopping MySQL
5715
2.6.1. Installing MySQL from RPM Packages on Linux
5717
The recommended way to install MySQL on RPM-based Linux
5718
distributions is by using the RPM packages. The RPMs that we
5719
provide to the community should work on all versions of Linux that
5720
support RPM packages and use glibc 2.3. To obtain RPM packages,
5721
see Section 2.1.3, "How to Get MySQL."
5723
For non-RPM Linux distributions, you can install MySQL using a
5724
.tar.gz package. See Section 2.2, "Installing MySQL from Generic
5725
Binaries on Unix/Linux."
5727
We do provide some platform-specific RPMs; the difference between
5728
a platform-specific RPM and a generic RPM is that a
5729
platform-specific RPM is built on the targeted platform and is
5730
linked dynamically whereas a generic RPM is linked statically with
5735
RPM distributions of MySQL often are provided by other vendors. Be
5736
aware that they may differ in features and capabilities from those
5737
built by us, and that the instructions in this manual do not
5738
necessarily apply to installing them. The vendor's instructions
5739
should be consulted instead.
5741
In most cases, you need to install only the MySQL-server and
5742
MySQL-client packages to get a functional MySQL installation. The
5743
other packages are not required for a standard installation.
5745
RPMs for MySQL Cluster. Beginning with MySQL 5.1.24, standard
5746
MySQL server RPMs built by MySQL no longer provide support for the
5747
NDBCLUSTER storage engine. MySQL Cluster users wanting to upgrade
5748
MySQL 5.1.23 or earlier installations from RPMs built by MySQL
5749
should upgrade to MySQL Cluster NDB 6.2 or MySQL Cluster NDB 6.3;
5750
RPMs that should work with most Linux distributions are available
5751
for both of these release series.
5755
When upgrading a MySQL Cluster RPM installation, you must upgrade
5756
all installed RPMs, including the Server and Client RPMs.
5758
For more information about installing MySQL Cluster from RPMs, see
5759
Section 17.2.1, "MySQL Cluster Multi-Computer Installation."
5761
For upgrades, if your installation was originally produced by
5762
installing multiple RPM packages, it is best to upgrade all the
5763
packages, not just some. For example, if you previously installed
5764
the server and client RPMs, do not upgrade just the server RPM.
5766
The RPM packages shown in the following list are available. The
5767
names shown here use a suffix of .glibc23.i386.rpm, but particular
5768
packages can have different suffixes, described later.
5770
* MySQL-server-VERSION.glibc23.i386.rpm
5771
The MySQL server. You need this unless you only want to
5772
connect to a MySQL server running on another machine.
5774
* MySQL-client-VERSION.glibc23.i386.rpm
5775
The standard MySQL client programs. You probably always want
5776
to install this package.
5778
* MySQL-devel-VERSION.glibc23.i386.rpm
5779
The libraries and include files that are needed if you want to
5780
compile other MySQL clients, such as the Perl modules.
5782
* MySQL-debuginfo-VERSION.glibc23.i386.rpm
5783
This package contains debugging information. debuginfo RPMs
5784
are never needed to use MySQL software; this is true both for
5785
the server and for client programs. However, they contain
5786
additional information that might be needed by a debugger to
5789
* MySQL-shared-VERSION.glibc23.i386.rpm
5790
This package contains the shared libraries
5791
(libmysqlclient.so*) that certain languages and applications
5792
need to dynamically load and use MySQL. It contains
5793
single-threaded and thread-safe libraries. If you install this
5794
package, do not install the MySQL-shared-compat package.
5796
* MySQL-shared-compat-VERSION.glibc23.i386.rpm
5797
This package includes the shared libraries for MySQL 3.23,
5798
4.0, and so on, up to the current release. It contains
5799
single-threaded and thread-safe libraries. Install this
5800
package instead of MySQL-shared if you have applications
5801
installed that are dynamically linked against older versions
5802
of MySQL but you want to upgrade to the current version
5803
without breaking the library dependencies.
5805
* MySQL-shared-compat-advanced-gpl-VERSION.glibc23.i386.rpm,
5806
MySQL-shared-compat-advanced-VERSION.glibc23.i386.rpm
5807
These are like the MySQL-shared-compat package, but are for
5808
the "MySQL Enterprise Server - Advanced Edition" products.
5809
Install these packages rather than the normal
5810
MySQL-shared-compat package if you want to included shared
5811
client libraries for older MySQL versions.
5813
* MySQL-embedded-VERSION.glibc23.i386.rpm
5814
The embedded MySQL server library.
5816
* MySQL-ndb-management-VERSION.glibc23.i386.rpm,
5817
MySQL-ndb-storage-VERSION.glibc23.i386.rpm,
5818
MySQL-ndb-tools-VERSION.glibc23.i386.rpm,
5819
MySQL-ndb-extra-VERSION.glibc23.i386.rpm
5820
Packages that contain additional files for MySQL Cluster
5824
The MySQL-ndb-tools RPM requires a working installation of
5825
perl. Prior to MySQL 5.1.18, the DBI and HTML::Template
5826
packages were also required. See Section 2.15, "Perl
5827
Installation Notes," and Section 17.4.21, "ndb_size.pl ---
5828
NDBCLUSTER Size Requirement Estimator," for more information.
5830
* MySQL-test-VERSION.glibc23.i386.rpm
5831
This package includes the MySQL test suite.
5833
* MySQL-VERSION.src.rpm
5834
This contains the source code for all of the previous
5835
packages. It can also be used to rebuild the RPMs on other
5836
architectures (for example, Alpha or SPARC).
5838
The suffix of RPM package names (following the VERSION value) has
5839
the following syntax:
5842
The PLATFORM and CPU values indicate the type of system for which
5843
the package is built. PLATFORM indicates the platform and CPU
5844
indicates the processor type or family.
5846
All packages are dynamically linked against glibc 2.3. The
5847
PLATFORM value indicates whether the package is platform
5848
independent or intended for a specific platform, as shown in the
5850
glibc23 Platform independent, should run on any Linux distribution
5851
that supports glibc 2.3
5852
rhel3, rhel4 Red Hat Enterprise Linux 3 or 4
5853
sles9, sles10 SuSE Linux Enterprise Server 9 or 10
5855
In MySQL 5.1, only glibc23 packages are available currently.
5857
The CPU value indicates the processor type or family for which the
5859
i386 x86 processor, 386 and up
5860
i586 x86 processor, Pentium and up
5861
x86_64 64-bit x86 processor
5862
ia64 Itanium (IA-64) processor
5864
To see all files in an RPM package (for example, a MySQL-server
5865
RPM), run a command like this:
5866
shell> rpm -qpl MySQL-server-VERSION.glibc23.i386.rpm
5868
To perform a standard minimal installation, install the server and
5870
shell> rpm -i MySQL-server-VERSION.glibc23.i386.rpm
5871
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
5873
To install only the client programs, install just the client RPM:
5874
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm
5876
RPM provides a feature to verify the integrity and authenticity of
5877
packages before installing them. If you would like to learn more
5878
about this feature, see Section 2.1.4, "Verifying Package
5879
Integrity Using MD5 Checksums or GnuPG."
5881
The server RPM places data under the /var/lib/mysql directory. The
5882
RPM also creates a login account for a user named mysql (if one
5883
does not exist) to use for running the MySQL server, and creates
5884
the appropriate entries in /etc/init.d/ to start the server
5885
automatically at boot time. (This means that if you have performed
5886
a previous installation and have made changes to its startup
5887
script, you may want to make a copy of the script so that you
5888
don't lose it when you install a newer RPM.) See Section 2.13.1.2,
5889
"Starting and Stopping MySQL Automatically," for more information
5890
on how MySQL can be started automatically on system startup.
5892
If you want to install the MySQL RPM on older Linux distributions
5893
that do not support initialization scripts in /etc/init.d
5894
(directly or via a symlink), you should create a symbolic link
5895
that points to the location where your initialization scripts
5896
actually are installed. For example, if that location is
5897
/etc/rc.d/init.d, use these commands before installing the RPM to
5898
create /etc/init.d as a symbolic link that points there:
5900
shell> ln -s rc.d/init.d .
5902
However, all current major Linux distributions should support the
5903
new directory layout that uses /etc/init.d, because it is required
5904
for LSB (Linux Standard Base) compliance.
5906
If the RPM files that you install include MySQL-server, the mysqld
5907
server should be up and running after installation. You should be
5908
able to start using MySQL.
5910
If something goes wrong, you can find more information in the
5911
binary installation section. See Section 2.2, "Installing MySQL
5912
from Generic Binaries on Unix/Linux."
5916
The accounts that are listed in the MySQL grant tables initially
5917
have no passwords. After starting the server, you should set up
5918
passwords for them using the instructions in Section 2.13,
5919
"Post-Installation Setup and Testing."
5921
During RPM installation, a user named mysql and a group named
5922
mysql are created on the system. This is done using the useradd,
5923
groupadd, and usermod commands. Those commands require appropriate
5924
administrative privileges, which is ensured for locally managed
5925
users and groups (as listed in the /etc/passwd and /etc/group
5926
files) by the RPM installation process being run by root.
5928
For nonlocal user management (LDAP, NIS, and so forth), the
5929
administrative tools may require additional authentication (such
5930
as a password), and will fail if the installing user does not
5931
provide this authentication. Even if they fail, the RPM
5932
installation will not abort but succeed, and this is intentional.
5933
If they failed, some of the intended transfer of ownership may be
5934
missing, and it is recommended that the system administrator then
5935
manually ensures some appropriate user andgroup exists and
5936
manually transfers ownership following the actions in the RPM spec
5939
2.7. Installing MySQL on Mac OS X
5941
MySQL for Mac OS X is available in a number of different forms:
5943
* Native Package Installer format, which uses the native Mac OS
5944
X installer to walk you through the installation of MySQL. For
5945
more information, see Section 2.7.1, "Installing MySQL Using
5946
the Installation Package." You can use the package installer
5947
with Mac OS X 10.3 and later, and available for both PowerPC
5948
and Intel architectures, and both 32-bit and 64-bit
5949
architectures. There is no Universal Binary available using
5950
the package installation method. The user you use to perform
5951
the installation must have administrator privileges.
5953
* Tar package format, which uses a file packaged using the Unix
5954
tar and gzip commands. To use this method, you will need to
5955
open a Terminal window. You do not need administrator
5956
privileges using this method, as you can install the MySQL
5957
server anywhere using this method. For more information on
5958
using this method, you can use the generic instructions for
5959
using a tarball, Section 2.2, "Installing MySQL from Generic
5960
Binaries on Unix/Linux."You can use the package installer with
5961
Mac OS X 10.3 and later, and available for both PowerPC and
5962
Intel architectures, and both 32-bit and 64-bit architectures.
5963
A Universal Binary, incorporating both Power PC and Intel
5964
architectures and 32-bit and 64-bit binaries is available.
5965
In addition to the core installation, the Package Installer
5966
also includes Section 2.7.2, "Installing the MySQL Startup
5967
Item" and Section 2.7.3, "Installing and Using the MySQL
5968
Preference Pane," both of which simplify the management of
5971
* Mac OS X server includes a version of MySQL as standard. If
5972
you want to use a more recent version than that supplied with
5973
the Mac OS X server release, you can make use of the package
5974
or tar formats. For more information on using the MySQL
5975
bundled with Mac OS X, see Section 2.7.4, "Using MySQL on Mac
5978
For additional information on using MySQL on Mac OS X, see Section
5979
2.7.5, "MySQL Installation on Mac OS X Notes."
5981
2.7.1. Installing MySQL Using the Installation Package
5983
You can install MySQL on Mac OS X 10.3.x ("Panther") or newer
5984
using a Mac OS X binary package in PKG format instead of the
5985
binary tarball distribution. Please note that older versions of
5986
Mac OS X (for example, 10.1.x or 10.2.x) are not supported by this
5989
The package is located inside a disk image (.dmg) file that you
5990
first need to mount by double-clicking its icon in the Finder. It
5991
should then mount the image and display its contents.
5995
Before proceeding with the installation, be sure to shut down all
5996
running MySQL server instances by either using the MySQL Manager
5997
Application (on Mac OS X Server) or via mysqladmin shutdown on the
6000
When installing from the package version, you should also install
6001
the MySQL Preference Pane, which will allow you to control the
6002
startup and execution of your MySQL server from System
6003
Preferences. For more information, see Section 2.7.3, "Installing
6004
and Using the MySQL Preference Pane."
6006
When installing using the package installer, the files are
6007
installed into a directory within /usr/local matching the name of
6008
the installation version and platform. For example, the installer
6009
file mysql-5.1.39-osx10.5-x86_64.pkg installs MySQL into
6010
/usr/local/mysql-5.1.39-osx10.5-x86_64 . The installation layout
6011
of the directory is as shown in the following table:
6012
Directory Contents of Directory
6013
bin Client programs and the mysqld server
6014
data Log files, databases
6015
docs Manual in Info format
6016
include Include (header) files
6018
man Unix manual pages
6019
mysql-test MySQL test suite
6020
scripts Contains the mysql_install_db script
6021
share/mysql Error message files
6022
sql-bench Benchmarks
6023
support-files Scripts and sample configuration files
6024
/tmp/mysql.sock The location of the MySQL Unix socket
6026
During the package installer process, a symbolic link from
6027
/usr/local/mysql to the version/platform specific directory
6028
created during installation will be created automatically.
6030
1. Download and open the MySQL package installer, which is
6031
provided on a disk image (.dmg). Double-click to open the disk
6032
image, which includes the main MySQL installation package, the
6033
MySQLStartupItem.pkg installation package, and the
6036
2. Double-click on the MySQL installer package. It will be named
6037
according to the version of MySQL you have downloaded. For
6038
example, if you have downloaded MySQL 5.1.39, double-click
6039
mysql-5.1.39-osx10.5-x86.pkg.
6041
3. You will be presented with the openin installer dialog. Click
6042
Continue to begihn installation.
6043
MySQL Package Installer: Step 1
6045
4. A copy of the installation instructions and other important
6046
information relevant to this installation are display. Click
6049
5. If you have downloaded the community version of MySQL, you
6050
will be shown a copy of the relevent GNU General Public
6051
License. Click Continue .
6053
6. Select the drive you want to use to install the MySQL Startup
6054
Item. The drive must have a valid, bootable, Mac OS X
6055
operating system installed. Click Continue.
6056
MySQL Package Installer: Step 4
6058
7. You will be asked to confirm the details of the installation,
6059
including the space required for the installation. To change
6060
the drive on which the startup item is installed you can click
6061
either Go Back or Change Install Location.... To install the
6062
startup item, click Install.
6064
8. Once the installation has been completed successfully, you
6065
will be given an Install Succeeded message.
6067
Once you have completed the basic installation, you must complete
6068
the post-installation steps as specifed in Section 2.13,
6069
"Post-Installation Setup and Testing."
6071
For convenience, you may also want to install the Section 2.7.2,
6072
"Installing the MySQL Startup Item" and Section 2.7.3, "Installing
6073
and Using the MySQL Preference Pane."
6075
2.7.2. Installing the MySQL Startup Item
6077
The MySQL Installation Package includes a startup item that can be
6078
used to automatically startup and shutdown MySQL during boot.
6080
To install the MySQL Startup Item:
6082
1. Download and open the MySQL package installer, which is
6083
provided on a disk image (.dmg). Double-click to open the disk
6084
image, which includes the main MySQL installation package, the
6085
MySQLStartupItem.pkg installation package, and the
6088
2. Double-click on the MySQLStartItem.pkg file to start the
6089
installation process.
6091
3. You will be presented with the Install MySQL Startup Item
6093
MySQL Startup Item Installer: Step 1
6094
Click Continue to continue the installation process.
6096
4. A copy of the installation instructions and other important
6097
information relevant to this installation are display. Click
6100
5. Select the drive you want to use to install the MySQL Startup
6101
Item. The drive must have a valid, bootable, Mac OS X
6102
operating system installed. Click Continue.
6103
MySQL Startup Item Installer: Step 3
6105
6. You will be asked to confirm the details of the installation.
6106
To change the drive on which the startup item is installed you
6107
can click either Go Back or Change Install Location.... To
6108
install the startup item, click Install.
6110
7. Once the installation has been completed successfully, you
6111
will be given an Install Succeeded message.
6112
MySQL Startup Item Installer: Step 5
6114
The Startup Item for MySQL is installed into
6115
/Library/StartupItems/MySQLCOM. The Startup Item installation adds
6116
a variable MYSQLCOM=-YES- to the system configuration file
6117
/etc/hostconfig. If you want to disable the automatic startup of
6118
MySQL, simply change this variable to MYSQLCOM=-NO-.
6120
After the installation, you can start up MySQL by running the
6121
following commands in a terminal window. You must have
6122
administrator privileges to perform this task.
6124
If you have installed the Startup Item, use this command to start
6126
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start
6128
You may be prompted for your password to complete the startup.
6130
If you have installed the Startup Item, use this command to stop
6132
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM stop
6134
You may be prompted for your password to complete the shutdown.
6136
2.7.3. Installing and Using the MySQL Preference Pane
6138
The MySQL Package installer disk image also includes a custom
6139
MySQL Preference Pane that enables you to start, stop and control
6140
automated startup during boot of your MySQL installation.
6142
To install the MySQL Preference Pane:
6144
1. Download and open the MySQL package installer package, which
6145
is provided on a disk image (.dmg). Double-click to open the
6146
disk image, which includes the main MySQL installation
6147
package, the MySQLStartupItem.pkg installation package, and
6150
2. Double click on MySQL.prefPane. The MySQL System Preferences
6153
3. If this is the first time you have installed the preference
6154
pane, you will be asked to confirm installation and whether
6155
you want to install the preference pane for all users, or only
6156
the current user. To install the preference pane for all users
6157
you will need administrator privileges. If necessary, you will
6158
be prompted for the username and password for a user with
6159
administrator privileges.
6161
4. If you already have the MySQL Preference Pane installed, you
6162
will be asked to confirm whether you want to overwrite the
6163
existing MySQL Preference Pane.
6167
The MySQL Preference Pane only starts and stops MySQL installation
6168
installed from the MySQL package installation that have been
6169
installed in the default location.
6171
Once the MySQL Preference Pane has been installed, you can control
6172
your MySQL server instance using the preference pane. To use the
6173
preference pane, open the System Preferences... from the Apple
6174
menu. Select the MySQL preference pane by clicking on the MySQL
6175
logo within the Other section of the preference panes list.
6176
MySQL Preference Pane
6178
The MySQL Preference Pane shows the current status of the MySQL
6179
server, showing stopped (in red) if the server is not running and
6180
running (in green) if the server has already been started. The
6181
preference pane will also show the current setting for whether the
6182
MySQL server has been set to start up automatically.
6184
* To start MySQL using the preference pane:
6185
Click Start MySQL Server. You may be prompted for the username
6186
and password of a user with administrator privileges to start
6189
* To stop MySQL using the preference pane:
6190
Click Stop MySQL Server. You may be prompted for the username
6191
and password of a user with administrator privileges to
6192
shutdown the MySQL server.
6194
* To automatically start the MySQL server when the system boots:
6195
Check the checkbox next to Automatically Start MySQL Server on
6198
* To disable the automatic starting of the MySQL server when the
6200
Uncheck the checkbox next to Automatically Start MySQL Server
6203
You can close the System Preferences... once you have completed
6206
2.7.4. Using MySQL on Mac OS X Server
6208
If you are running Mac OS X Server, a version of MySQL should
6209
already be installed. The following table shows the versions of
6210
MySQL that ship with Mac OS X Server versions.
6211
Mac OS X Server Version MySQL Version
6213
10.2.3-10.2.6 3.23.53
6220
The installation layout of MySQL on Mac OS X Server is as shown in
6222
Directory Contents of Directory
6223
/usr/bin Client programs
6224
/var/mysql Log files, databases
6225
/usr/libexec The mysqld server
6226
/usr/share/man Unix manual pages
6227
/usr/share/mysql/mysql-test MySQL test suite
6228
/usr/share/mysql Contains the mysql_install_db script
6229
/var/mysql/mysql.sock The location of the MySQL Unix socket
6233
The MySQL server bundled with Mac OS X Server does not include the
6234
MySQL client libraries and header files required if you want to
6235
access and use MySQL from a third-party driver, such as Perl DBI
6236
or PHP. For more information on obtaining and installing MySQL
6237
libraries, see Mac OS X Server version 10.5: MySQL libraries
6238
available for download (http://support.apple.com/kb/TA25017).
6239
Alternatively, you can ignore the bundled MySQL server and install
6240
MySQL from the package or tarball installation.
6242
For more information on managing the bundled MySQL instance in Mac
6243
OS X Server 10.5, see Mac OS X Server: Web Technologies
6244
Administration For Version 10.5 Leopard
6245
(http://images.apple.com/server/macosx/docs/Web_Technologies_Admin
6246
_v10.5.pdf). For more information on managing the bundled MySQL
6247
instance in Mac OS X Server 10.6, see Mac OS X Server: Web
6248
Technologies Administration Version 10.6 Snow Leopard
6249
(http://manuals.info.apple.com/en_US/WebTech_v10.6.pdf).
6251
2.7.5. MySQL Installation on Mac OS X Notes
6253
You should keep the following issues and notes in mind:
6255
* The default location for the MySQL Unix socket is different on
6256
Mac OS X and Mac OS X Server depending on the installation
6257
type you chose. The default locations by installation are as
6260
Package Installer from MySQL /tmp/mysql.sock
6261
Tarball from MySQL /tmp/mysql.sock
6262
MySQL Bundled with Mac OS X Server /var/mysql/mysql.sock
6263
To prevent issues, you should either change the configuration
6264
of the socket used within your application (for example,
6265
changing php.ini), or you should configure the socket location
6266
using a MySQL configuration file and the socket option. For
6267
more information, see Section 5.1.2, "Server Command Options."
6269
* You may need (or want) to create a specific mysql user to own
6270
the MySQL directory and data. On Mac OS X 10.4 and lower you
6271
can do this by using the Netinfo Manager application, located
6272
within the Utilities folder within the Applications folder. On
6273
Mac OS X 10.5 and later you can do this through the Directory
6274
Utility. From Mac OS X 10.5 and later (including Mac OS X
6275
Server 10.5) the mysql should already exist. For use in single
6276
user mode, an entry for _mysql (note the underscore prefix)
6277
should already exist within the system /etc/passwd file.
6279
* Due to a bug in the Mac OS X package installer, you may see
6280
this error message in the destination disk selection dialog:
6281
You cannot install this software on this disk. (null)
6282
If this error occurs, simply click the Go Back button once to
6283
return to the previous screen. Then click Continue to advance
6284
to the destination disk selection again, and you should be
6285
able to choose the destination disk correctly. We have
6286
reported this bug to Apple and it is investigating this
6289
* Because the MySQL package installer installs the MySQL
6290
contents into a version and platform specific directory, you
6291
can use this to upgrade and migrate your database between
6292
versions. You will need to either copy the data directory from
6293
the old version to the new version, or alternatively specify
6294
an alternative datadir value to set location of the data
6297
* You might want to add aliases to your shell's resource file to
6298
make it easier to access commonly used programs such as mysql
6299
and mysqladmin from the command line. The syntax for bash is:
6300
alias mysql=/usr/local/mysql/bin/mysql
6301
alias mysqladmin=/usr/local/mysql/bin/mysqladmin
6303
alias mysql /usr/local/mysql/bin/mysql
6304
alias mysqladmin /usr/local/mysql/bin/mysqladmin
6305
Even better, add /usr/local/mysql/bin to your PATH environment
6306
variable. You can do this by modifying the appropriate startup
6307
file for your shell. For more information, see Section 4.2.1,
6308
"Invoking MySQL Programs."
6310
* After you have copied over the MySQL database files from the
6311
previous installation and have successfully started the new
6312
server, you should consider removing the old installation
6313
files to save disk space. Additionally, you should also remove
6314
older versions of the Package Receipt directories located in
6315
/Library/Receipts/mysql-VERSION.pkg.
6317
2.8. Installing MySQL on Solaris
6319
To obtain a binary MySQL distribution for Solaris in tarball or
6320
PKG format, http://dev.mysql.com/downloads/mysql/5.1.html.
6322
If you install MySQL using a binary tarball distribution on
6323
Solaris, you may run into trouble even before you get the MySQL
6324
distribution unpacked, as the Solaris tar cannot handle long file
6325
names. This means that you may see errors when you try to unpack
6328
If this occurs, you must use GNU tar (gtar) to unpack the
6331
You can install MySQL on Solaris using a binary package in PKG
6332
format instead of the binary tarball distribution. Before
6333
installing using the binary PKG format, you should create the
6334
mysql user and group, for example:
6336
useradd -g mysql mysql
6338
Some basic PKG-handling commands follow:
6341
pkgadd -d package_name.pkg
6343
* To remove a package:
6346
* To get a full list of installed packages:
6349
* To get detailed information for a package:
6350
pkginfo -l package_name
6352
* To list the files belonging to a package:
6353
pkgchk -v package_name
6355
* To get packaging information for an arbitrary file:
6356
pkgchk -l -p file_name
6358
2.8.1. Solaris Notes
6360
For information about installing MySQL on Solaris using PKG
6361
distributions, see Section 2.8, "Installing MySQL on Solaris."
6363
On Solaris, you may run into trouble even before you get the MySQL
6364
distribution unpacked, as the Solaris tar cannot handle long file
6365
names. This means that you may see errors when you try to unpack
6368
If this occurs, you must use GNU tar (gtar) to unpack the
6371
If you have an UltraSPARC system, you can get 4% better
6372
performance by adding -mcpu=v8 -Wa,-xarch=v8plusa to the CFLAGS
6373
and CXXFLAGS environment variables.
6375
If you have Sun's Forte 5.0 (or newer) compiler, you can run
6376
configure like this:
6377
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
6378
CXX=CC CXXFLAGS="-noex -mt" \
6379
./configure --prefix=/usr/local/mysql --enable-assembler
6381
To create a 64-bit binary with Sun's Forte compiler, use the
6382
following configuration options:
6383
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
6384
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
6385
./configure --prefix=/usr/local/mysql --enable-assembler
6387
To create a 64-bit Solaris binary using gcc, add -m64 to CFLAGS
6388
and CXXFLAGS and remove --enable-assembler from the configure
6391
In the MySQL benchmarks, we obtained a 4% speed increase on
6392
UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to
6393
using gcc 3.2 with the -mcpu flag.
6395
If you create a 64-bit mysqld binary, it is 4% slower than the
6396
32-bit binary, but can handle more threads and memory.
6398
When using Solaris 10 for x86_64, you should mount any file
6399
systems on which you intend to store InnoDB files with the
6400
forcedirectio option. (By default mounting is done without this
6401
option.) Failing to do so will cause a significant drop in
6402
performance when using the InnoDB storage engine on this platform.
6404
If you get a problem with fdatasync or sched_yield, you can fix
6405
this by adding LIBS=-lrt to the configure line
6407
Solaris does not provide static versions of all system libraries
6408
(libpthreads and libdl), so you cannot compile MySQL with
6409
--static. If you try to do so, you get one of the following
6411
ld: fatal: library -ldl: not found
6412
undefined reference to `dlopen'
6415
If you link your own MySQL client programs, you may see the
6416
following error at runtime:
6417
ld.so.1: fatal: libmysqlclient.so.#:
6418
open failed: No such file or directory
6420
This problem can be avoided by one of the following methods:
6422
* Link clients with the -Wl,r/full/path/to/libmysqlclient.so
6423
flag rather than with -Lpath).
6425
* Copy libmysqclient.so to /usr/lib.
6427
* Add the path name of the directory where libmysqlclient.so is
6428
located to the LD_RUN_PATH environment variable before running
6431
If you have problems with configure trying to link with -lz when
6432
you don't have zlib installed, you have two options:
6434
* If you want to be able to use the compressed communication
6435
protocol, you need to get and install zlib from ftp.gnu.org.
6437
* Run configure with the --with-named-z-libs=no option when
6440
If you are using gcc and have problems with loading user-defined
6441
functions (UDFs) into MySQL, try adding -lgcc to the link line for
6444
If you would like MySQL to start automatically, you can copy
6445
support-files/mysql.server to /etc/init.d and create a symbolic
6446
link to it named /etc/rc3.d/S99mysql.server.
6448
If too many processes try to connect very rapidly to mysqld, you
6449
should see this error in the MySQL log:
6450
Error in accept: Protocol error
6452
You might try starting the server with the --back_log=50 option as
6453
a workaround for this. (Use -O back_log=50 before MySQL 4.)
6455
To configure the generation of core files on Solaris you should
6456
use the coreadm command. Because of the security implications of
6457
generating a core on a setuid() application, by default, Solaris
6458
does not support core files on setuid() programs. However, you can
6459
modify this behavior using coreadm. If you enable setuid() core
6460
files for the current user, they will be generated using the mode
6461
600 and owned by the superuser.
6463
2.9. Installing MySQL on i5/OS
6465
The i5/OS POWER MySQL package was created in cooperation with IBM.
6466
MySQL works within the Portable Application Solution Environment
6467
(PASE) on the System i series of hardware and will also provide
6468
database services for the Zend Core for i5/OS.
6470
MySQL for i5/OS is provided both as a tar file and as a save file
6471
(.savf) package that can be downloaded and installed directly
6472
without any additional installation steps required. To install
6473
MySQL using the tar file, see Section 2.2, "Installing MySQL from
6474
Generic Binaries on Unix/Linux."
6476
MySQL is only supported on i5/OS V5R4 or later releases. The i5/OS
6477
PASE must be installed for MySQL to operate. You must be able to
6478
login as a user in *SECOFR class.
6480
You should the installation notes and tips for i5/OS before
6481
starting installation. See i5/OS Installation Notes.
6483
Before Installation:
6487
The installation package will use an existing configuration if you
6488
have previously installed MySQL (which is identified by looking
6489
for the file /etc/my.cnf). The values for the data directory
6490
(DATADIR) and owner of the MySQL files (USRPRF) specified during
6491
the installation will be ignored, and the values determined from
6492
the /etc/my.cnf will be used instead.
6494
If you want to change these parameters during a new install, you
6495
should temporarily rename /etc/my.cnf, install MySQL using the new
6496
parameters you want to use, and then merge your previous
6497
/etc/my.cnf configuration settings with the new /etc/my.cnf file
6498
that is created during installation.
6500
* You must have a user profile with PASE with suitable
6501
privileges. The user should be within the *SECOFR class, such
6502
as the QSECOFR user ID. You can use the WRKUSRPRF command to
6503
check your user profile.
6505
* For network connections to MySQL, you must have TCP/IP
6506
enabled. You should also check the following:
6508
+ Ensure that a name has defined for the system. Run the
6509
Configure TCP/IP (CFGTCP) command and select option 12
6510
(Change TCP/IP domain information) to display this
6511
setting. Make sure that a value is listed in the Host
6514
+ Make sure that the system has a loopback entry which
6515
represents the localhost or 127.0.0.1.
6517
+ Ensure that the IP address of the IBM i machine is mapped
6518
correctly to the host name.
6520
To install MySQL on i5/OS, follow these steps:
6522
1. On the System i machine, create a save file that will be used
6523
to receive the downloaded installation save file. The file
6524
should be located within the General Purpose Library (QGPL):
6525
CRTSAVF FILE(QGPL/MYSQLINST) TESXT('MySQL Save file')
6527
2. Download the MySQL installation save file in 32-bit
6528
(mysql-5.1.39-i5os-power-32bit.savf) or 64-bit
6529
(mysql-5.1.39-i5os-power-64bit.savf) from MySQL Downloads
6530
(http://dev.mysql.com/downloads).
6532
3. You need to FTP the downloaded .savf file directly into the
6533
QGPL/MYSQLINST file on the System i server. You can do this
6534
through FTP using the following steps after logging in to the
6538
ftp> put mysql-5.1.39-i5os-power.savf mysqlinst
6540
4. Log into the System i server using a user in the *SECOFR
6541
class, such as the QSECOFR user ID.
6543
5. You need to restore the installation library stored in the
6545
RSTLIB MYSQLINST DEV(*SAVF) SAVF(QGPL/MYSQLINST) MBROPT(*ALL) ALWOBJD
6549
You can ignore the security changes-type message at the bottom
6550
of the installation panel.
6552
6. Once you have finished restoring the MYSQLINST library, check
6553
that all the necessary objects for installation are on the
6554
system by using the Display Library (DSPLIB) command:
6555
DSPLIB LIB(MYSQLINST)
6557
7. You need to execute the installation command,
6558
MYSQLINST/INSMYSQL. You can specify three parameter settings
6559
during installation:
6561
+ DIR('/QOpenSys/usr/local/mysql') sets the installation
6562
location for the MySQL files. The directory will be
6563
created if it does not already exist.
6565
+ DATADIR('/QOpenSys/usr/local/mysql/data') sets the
6566
location of the directory that will be used to store the
6567
database files and binary logs. The default setting is
6568
/QOpenSys/usr/local/mysql/data. Note that if the
6569
installer detects an existing installation (due to the
6570
existence of /etc/my.cnf), then the existing setting will
6571
be used instead of the default.
6573
+ USRPRF(MYSQL) sets the user profile that will own the
6574
files that are installed. The profile will be created if
6575
it does not already exist.
6578
You should choose an appropriate user for using the MySQL
6579
server installation. The user will be used whenever you
6580
need to do any administration on the MySQL server.
6581
Once you have set the appropriate parameters, you can begin
6583
The installation copies all the necessary files into a
6584
directory matching the DIR configuration value; sets the
6585
ownership on those files, sets up the MySQL environment and
6586
creates the MySQL configuration file (in /etc/my.cnf)
6587
completing all the steps in a typical binary installation
6588
process automatically. If this is a new installation of MySQL,
6589
or if the installer detects that this is a new version
6590
(because the /etc/my.cnf file does not exist), then the
6591
initial core MySQL databases will also be created during
6593
Once the installation has been completed, you will get a
6594
notice advising you to set the password for the root user. For
6595
more information, Section 2.13, "Post-Installation Setup and
6598
8. Once the installation has completed, you can delete the
6600
DLTLIB LIB(MYSQLINST)
6602
Upgrading an existing MySQL instance
6604
You need to execute the upgrade command, MYSQLINST/UPGMYSQL.
6608
You cannot use MYSQLINST/UPGMYSQL to upgrade between major
6609
versions of MySQL (for example from 5.0 to 5.1). For information
6610
and advice on migrating between major versions you can use the
6611
advice provided in Section 2.4.1.1, "Upgrading from MySQL 5.0 to
6614
You must specify 6 parameters to perform an upgrade:
6616
* DIR('/QOpenSys/usr/local/') --- sets the installation location
6617
for the MySQL files. The directory will be created if it does
6618
not already exist. This is the directory that the MySQL server
6619
will be installed into, inside a directory with a name
6620
matching the version and release. For example, if installing
6621
MySQL 5.1.39 with the DIR set to /QOpenSys/usr/local/ would
6622
result in /QOpenSys/usr/local/mysql-5.1.39-i5os-power64 and a
6623
symbolic link to this directory will be created in
6624
/QOpenSys/usr/local/mysql.
6626
* DATADIR('/QOpenSys/mysql/data') --- sets the location of the
6627
directory that will be upgraded.
6629
* USRPRF('MYSQL') --- sets the user profile that will own the
6630
files that are installed. The profile will be created if it
6631
does not already exist; if it is created as part of the
6632
upgrade process, it will be disabled initially. You may wish
6633
to enable this user profile so that it can be used to start
6634
the MySQL server later. It is best practice to use the one
6635
previously created during the first installation.
6637
* MYSQLUSR('root user') --- any user account in the current
6638
MySQL server with SUPER privileges.
6640
* PASSWORD('root user password') --- the password for the above
6641
account. This is necessary as the upgrade starts the MySQL
6642
server to upgrade the tables and the password is need to be
6643
able to shutdown the MySQL server.
6645
* CURINST('path to previous install') --- the full path to the
6646
installation that is being upgraded. For example an
6647
installation in /QOpenSys/usr/local/ will be
6648
/QOpenSys/usr/local/msyql-5.1.30-i5os-power64. Failure to
6649
specify this option may result in corruption of your existing
6653
MYSQLINST/UPGMYSQL DIR('/QOpenSys/usr/local/') DATADIR('/QOpenSys/mys
6655
USERPRF(MYSQL) MYSQLUSR('root') PASSWORD('root') CURINST('/QOpen
6656
Sys/usr/local/mysql-5.1.30-i5os-power64')
6658
You should receive a Program Message indicating UPGRADE
6659
SUCCESSFUL! upon completion or an error message if there is a
6660
problem.You can view the upgrade programs progression and the
6661
error in the text file upgrade.log in the installation directory.
6665
1. Log into the System i server using the user profile create or
6666
specified during installation. By default, this is MYSQL.
6669
You should start mysqld_safe using a user that in the PASE
6670
environment has the id=0 (the equivalent of the standard Unix
6671
root user). If you do not use a user with this ID then the
6672
system will be unable to change the user when executing mysqld
6673
as set using --user option. If this happens, mysqld may be
6674
unable to read the files located within the MySQL data
6675
directory and the execution will fail.
6677
2. Enter the PASE environment using call qp2term.
6679
3. Start the MySQL server by changing to the installation
6680
directory and running mysqld_safe, specifying the user name
6681
used to install the server. The installer conveniently
6682
installs a symbolic link to the installation directory
6683
(mysql-5.0.42-i5os-power-32bit) as /opt/mysql/mysql:
6684
> cd /opt/mysql/mysql
6685
> bin/mysqld_safe --user=mysql &
6686
You should see a message similar to the following:
6687
Starting mysqld daemon with databases Ā»
6688
from /opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data
6690
If you are having problems starting MySQL server, see Section
6691
2.13.1.3, "Starting and Troubleshooting the MySQL Server."
6695
1. Log into the System i server using the user profile create or
6696
specified during installation. By default, this is MYSQL.
6698
2. Enter the PASE environment using call qp2term.
6700
3. Stop the MySQL server by changing into the installation
6701
directory and running mysqladmin, specifying the user name
6702
used to install the server:
6703
> cd /opt/mysql/mysql
6704
> bin/mysqladmin -u root shutdown
6705
If the session that you started and stopped MySQL are the
6706
same, you may get the log output from mysqld:
6707
STOPPING server from pid file Ā»
6708
/opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data/I5DBX.R
6710
070718 10:34:20 mysqld ended
6711
If the sessions used to start and stop MySQL are different,
6712
you will not receive any confirmation of the shutdown.
6716
* A problem has been identified with the installation process on
6717
DBCS systems. If you are having problems install MySQL on a
6718
DBCS system, you need to change your job's coded character set
6719
identifier (CSSID) to 37 (EBCDIC) before executing the install
6720
command, INSMYSQL. To do this, determine your existing CSSID
6721
(using DSPJOB and selecting option 2), execute CHGJOB
6722
CSSID(37), run INSMYSQL to install MySQL and then execute
6723
CHGJOB again with your original CSSID.
6725
* If you want to use the Perl scripts that are included with
6726
MySQL, you need to download the iSeries Tools for Developers
6728
http://www-03.ibm.com/servers/enable/site/porting/tools/.
6730
2.10. Installing MySQL on FreeBSD
6732
This section provides information about using MySQL on variants of
6735
The easiest (and preferred) way to install MySQL is to use the
6736
mysql-server and mysql-client ports available at
6737
http://www.freebsd.org/. Using these ports gives you the following
6740
* A working MySQL with all optimizations enabled that are known
6741
to work on your version of FreeBSD.
6743
* Automatic configuration and build.
6745
* Startup scripts installed in /usr/local/etc/rc.d.
6747
* The ability to use pkg_info -L to see which files are
6750
* The ability to use pkg_delete to remove MySQL if you no longer
6751
want it on your machine.
6753
The MySQL build process requires GNU make (gmake) to work. If GNU
6754
make is not available, you must install it first before compiling
6757
The recommended way to compile and install MySQL on FreeBSD with
6758
gcc (2.95.2 and up) is:
6759
CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
6760
CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
6761
-felide-constructors -fno-strength-reduce" \
6762
./configure --prefix=/usr/local/mysql --enable-assembler
6766
bin/mysql_install_db --user=mysql
6769
FreeBSD is known to have a very low default file handle limit. See
6770
Section B.5.2.18, "'File' Not Found and Similar Errors." Start the
6771
server by using the --open-files-limit option for mysqld_safe, or
6772
raise the limits for the mysqld user in /etc/login.conf and
6773
rebuild it with cap_mkdb /etc/login.conf. Also be sure that you
6774
set the appropriate class for this user in the password file if
6775
you are not using the default (use chpass mysqld-user-name). See
6776
Section 4.3.2, "mysqld_safe --- MySQL Server Startup Script."
6778
In current versions of FreeBSD (at least 4.x and greater), you may
6779
increase the limit on the amount of memory available for a process
6780
by adding the following entries to the /boot/loader.conf file and
6781
rebooting the machine (these are not settings that can be changed
6782
at run time with the sysctl command):
6783
kern.maxdsiz="1073741824" # 1GB
6784
kern.dfldsiz="1073741824" # 1GB
6785
kern.maxssiz="134217728" # 128MB
6787
For older versions of FreeBSD, you must recompile your kernel to
6788
change the maximum data segment size for a process. In this case,
6789
you should look at the MAXDSIZ option in the LINT config file for
6792
If you get problems with the current date in MySQL, setting the TZ
6793
variable should help. See Section 2.14, "Environment Variables."
6795
2.11. Installing MySQL on HP-UX
6797
If you install MySQL using a binary tarball distribution on HP-UX,
6798
you may run into trouble even before you get the MySQL
6799
distribution unpacked, as the HP-UX tar cannot handle long file
6800
names. This means that you may see errors when you try to unpack
6803
If this occurs, you must use GNU tar (gtar) to unpack the
6806
Because of some critical bugs in the standard HP-UX libraries, you
6807
should install the following patches before trying to run MySQL on
6809
PHKL_22840 Streams cumulative
6810
PHNE_22397 ARPA cumulative
6812
This solves the problem of getting EWOULDBLOCK from recv() and
6813
EBADF from accept() in threaded applications.
6815
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system, you
6816
may get the following error:
6817
In file included from /usr/include/unistd.h:11,
6818
from ../include/global.h:125,
6819
from mysql_priv.h:15,
6821
/usr/include/sys/unistd.h:184: declaration of C function ...
6822
/usr/include/sys/pthread.h:440: previous declaration ...
6823
In file included from item.h:306,
6824
from mysql_priv.h:158,
6827
The problem is that HP-UX does not define pthreads_atfork()
6828
consistently. It has conflicting prototypes in
6829
/usr/include/sys/unistd.h:184 and /usr/include/sys/pthread.h:440.
6831
One solution is to copy /usr/include/sys/unistd.h into
6832
mysql/include and edit unistd.h and change it to match the
6833
definition in pthread.h. Look for this line:
6834
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
6837
Change it to look like this:
6838
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void)
6840
void (*child)(void));
6842
After making the change, the following configure line should work:
6843
CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \
6844
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \
6845
./configure --prefix=/usr/local/mysql --disable-shared
6847
If you are using HP-UX compiler, you can use the following command
6848
(which has been tested with cc B.11.11.04):
6849
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
6850
--with-extra-character-set=complex
6852
You can ignore any errors of the following type:
6853
aCC: warning 901: unknown option: `-3': use +help for online
6856
If you get the following error from configure, verify that you
6857
don't have the path to the K&R compiler before the path to the
6858
HP-UX C and C++ compiler:
6859
checking for cc option to accept ANSI C... no
6860
configure: error: MySQL requires an ANSI C compiler (and a C++ compil
6862
Try gcc. See the Installation chapter in the Reference Manual.
6864
Another reason for not being able to compile is that you didn't
6865
define the +DD64 flags as just described.
6867
Another possibility for HP-UX 11 is to use the MySQL binaries
6868
provided at http://dev.mysql.com/downloads/, which we have built
6869
and tested ourselves. We have also received reports that the HP-UX
6870
10.20 binaries supplied by MySQL can be run successfully on HP-UX
6871
11. If you encounter problems, you should be sure to check your
6874
2.12. Installing MySQL on AIX
6876
Automatic detection of xlC is missing from Autoconf, so a number
6877
of variables need to be set before running configure. The
6878
following example uses the IBM compiler:
6879
export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
6880
export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
6881
export CFLAGS="-I /usr/local/include"
6882
export LDFLAGS="-L /usr/local/lib"
6883
export CPPFLAGS=$CFLAGS
6884
export CXXFLAGS=$CFLAGS
6886
./configure --prefix=/usr/local \
6887
--localstatedir=/var/mysql \
6888
--sbindir='/usr/local/bin' \
6889
--libexecdir='/usr/local/bin' \
6890
--enable-thread-safe-client \
6891
--enable-large-files
6893
The preceding options are used to compile the MySQL distribution
6894
that can be found at http://www-frec.bull.com/.
6896
If you change the -O3 to -O2 in the preceding configure line, you
6897
must also remove the -qstrict option. This is a limitation in the
6900
If you are using gcc to compile MySQL, you must use the
6901
-fno-exceptions flag, because the exception handling in gcc is not
6902
thread-safe! There are also some known problems with IBM's
6903
assembler that may cause it to generate bad code when used with
6906
Use the following configure line with gcc 2.95 on AIX:
6907
CC="gcc -pipe -mcpu=power -Wa,-many" \
6908
CXX="gcc -pipe -mcpu=power -Wa,-many" \
6909
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \
6910
./configure --prefix=/usr/local/mysql --with-low-memory
6912
The -Wa,-many option is necessary for the compile to be
6913
successful. IBM is aware of this problem but is in no hurry to fix
6914
it because of the workaround that is available. We don't know if
6915
the -fno-exceptions is required with gcc 2.95, but because MySQL
6916
doesn't use exceptions and the option generates faster code, you
6917
should always use it with gcc.
6919
If you get a problem with assembler code, try changing the
6920
-mcpu=xxx option to match your CPU. Typically power2, power, or
6921
powerpc may need to be used. Alternatively, you might need to use
6922
604 or 604e. We are not positive but suspect that power would
6923
likely be safe most of the time, even on a power2 machine.
6925
If you don't know what your CPU is, execute a uname -m command. It
6926
produces a string that looks like 000514676700, with a format of
6927
xxyyyyyymmss where xx and ss are always 00, yyyyyy is a unique
6928
system ID and mm is the ID of the CPU Planar. A chart of these
6929
values can be found at
6930
http://www16.boulder.ibm.com/pseries/en_US/cmds/aixcmds5/uname.htm
6933
This gives you a machine type and a machine model you can use to
6934
determine what type of CPU you have.
6936
If you have problems with threads on AIX 5.3, you should upgrade
6937
AIX 5.3 to technology level 7 (5300-07).
6939
If you have problems with signals (MySQL dies unexpectedly under
6940
high load), you may have found an OS bug with threads and signals.
6941
In this case, you can tell MySQL not to use signals by configuring
6943
CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
6944
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
6945
-DDONT_USE_THR_ALARM" \
6946
./configure --prefix=/usr/local/mysql --with-debug \
6949
This doesn't affect the performance of MySQL, but has the side
6950
effect that you can't kill clients that are "sleeping" on a
6951
connection with mysqladmin kill or mysqladmin shutdown. Instead,
6952
the client dies when it issues its next command.
6954
On some versions of AIX, linking with libbind.a makes
6955
getservbyname() dump core. This is an AIX bug and should be
6958
For AIX 4.2.1 and gcc, you have to make the following changes.
6960
After configuring, edit config.h and include/my_config.h and
6961
change the line that says this:
6962
#define HAVE_SNPRINTF 1
6965
#undef HAVE_SNPRINTF
6967
And finally, in mysqld.cc, you need to add a prototype for
6970
extern "C" int initgroups(const char *,int);
6973
For 32-bit binaries, if you need to allocate a lot of memory to
6974
the mysqld process, it is not enough to just use ulimit -d
6975
unlimited. You may also have to modify mysqld_safe to add a line
6976
something like this:
6977
export LDR_CNTRL='MAXDATA=0x80000000'
6979
You can find more information about using a lot of memory at
6980
http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lr
6983
Users of AIX 4.3 should use gmake instead of the make utility
6986
As of AIX 4.1, the C compiler has been unbundled from AIX as a
6987
separate product. gcc 3.3.2 can be obtained here:
6988
ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/gc
6991
The steps for compiling MySQL on AIX with gcc 3.3.2 are similar to
6992
those for using gcc 2.95 (in particular, the need to edit config.h
6993
and my_config.h after running configure). However, before running
6994
configure, you should also patch the curses.h file as follows:
6995
/opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/curses
6997
Mon Dec 26 02:17:28 2005
6998
--- /opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/cu
7000
Mon Dec 26 02:40:13 2005
7005
#endif /* _AIX32_CURSES */
7006
! #if defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus) || de
7009
extern int delwin (WINDOW *);
7010
extern int endwin (void);
7011
extern int getcurx (WINDOW *);
7015
#endif /* _AIX32_CURSES */
7016
! #if 0 && (defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus)
7019
extern int delwin (WINDOW *);
7020
extern int endwin (void);
7021
extern int getcurx (WINDOW *);
7023
2.13. Post-Installation Setup and Testing
7025
After installing MySQL, there are some issues that you should
7026
address. For example, on Unix, you should initialize the data
7027
directory and create the MySQL grant tables. On all platforms, an
7028
important security concern is that the initial accounts in the
7029
grant tables have no passwords. You should assign passwords to
7030
prevent unauthorized access to the MySQL server. Optionally, you
7031
can create time zone tables to enable recognition of named time
7034
The following sections include post-installation procedures that
7035
are specific to Windows systems and to Unix systems. Another
7036
section, Section 2.13.1.3, "Starting and Troubleshooting the MySQL
7037
Server," applies to all platforms; it describes what to do if you
7038
have trouble getting the server to start. Section 2.13.2,
7039
"Securing the Initial MySQL Accounts," also applies to all
7040
platforms. You should follow its instructions to make sure that
7041
you have properly protected your MySQL accounts by assigning
7044
When you are ready to create additional user accounts, you can
7045
find information on the MySQL access control system and account
7046
management in Section 5.4, "The MySQL Access Privilege System,"
7047
and Section 5.5, "MySQL User Account Management."
7049
2.13.1. Unix Post-Installation Procedures
7051
After installing MySQL on Unix, you need to initialize the grant
7052
tables, start the server, and make sure that the server works
7053
satisfactorily. You may also wish to arrange for the server to be
7054
started and stopped automatically when your system starts and
7055
stops. You should also assign passwords to the accounts in the
7058
On Unix, the grant tables are set up by the mysql_install_db
7059
program. For some installation methods, this program is run for
7062
* If you install MySQL on Linux using RPM distributions, the
7063
server RPM runs mysql_install_db.
7065
* If you install MySQL on Mac OS X using a PKG distribution, the
7066
installer runs mysql_install_db.
7068
Otherwise, you'll need to run mysql_install_db yourself.
7070
The following procedure describes how to initialize the grant
7071
tables (if that has not previously been done) and then start the
7072
server. It also suggests some commands that you can use to test
7073
whether the server is accessible and working properly. For
7074
information about starting and stopping the server automatically,
7075
see Section 2.13.1.2, "Starting and Stopping MySQL Automatically."
7077
After you complete the procedure and have the server running, you
7078
should assign passwords to the accounts created by
7079
mysql_install_db. Instructions for doing so are given in Section
7080
2.13.2, "Securing the Initial MySQL Accounts."
7082
In the examples shown here, the server runs under the user ID of
7083
the mysql login account. This assumes that such an account exists.
7084
Either create the account if it does not exist, or substitute the
7085
name of a different existing login account that you plan to use
7086
for running the server.
7088
1. Change location into the top-level directory of your MySQL
7089
installation, represented here by BASEDIR:
7091
BASEDIR is likely to be something like /usr/local/mysql or
7092
/usr/local. The following steps assume that you are located in
7095
2. If necessary, run the mysql_install_db program to set up the
7096
initial MySQL grant tables containing the privileges that
7097
determine how users are allowed to connect to the server.
7098
You'll need to do this if you used a distribution type for
7099
which the installation procedure doesn't run the program for
7101
Typically, mysql_install_db needs to be run only the first
7102
time you install MySQL, so you can skip this step if you are
7103
upgrading an existing installation, However, mysql_install_db
7104
does not overwrite any existing privilege tables, so it should
7105
be safe to run in any circumstances.
7106
To initialize the grant tables, use one of the following
7107
commands, depending on whether mysql_install_db is located in
7108
the bin or scripts directory:
7109
shell> bin/mysql_install_db --user=mysql
7110
shell> scripts/mysql_install_db --user=mysql
7111
It might be necessary to specify other options such as
7112
--basedir or --datadir if mysql_install_db does not use the
7113
correct locations for the installation directory or data
7114
directory. For example:
7115
shell> bin/mysql_install_db --user=mysql \
7116
--basedir=/opt/mysql/mysql \
7117
--datadir=/opt/mysql/mysql/data
7118
The mysql_install_db script creates the server's data
7119
directory. Under the data directory, it creates directories
7120
for the mysql database that holds all database privileges and
7121
the test database that you can use to test MySQL. The script
7122
also creates privilege table entries for root and
7123
anonymous-user accounts. The accounts have no passwords
7124
initially. A description of their initial privileges is given
7125
in Section 2.13.2, "Securing the Initial MySQL Accounts."
7126
Briefly, these privileges allow the MySQL root user to do
7127
anything, and allow anybody to create or use databases with a
7128
name of test or starting with test_.
7129
It is important to make sure that the database directories and
7130
files are owned by the mysql login account so that the server
7131
has read and write access to them when you run it later. To
7132
ensure this, the --user option should be used as shown if you
7133
run mysql_install_db as root. Otherwise, you should execute
7134
the script while logged in as mysql, in which case you can
7135
omit the --user option from the command.
7136
mysql_install_db creates several tables in the mysql database,
7137
including user, db, host, tables_priv, columns_priv, func, and
7138
others. See Section 5.4, "The MySQL Access Privilege System,"
7139
for a complete listing and description of these tables.
7140
If you don't want to have the test database, you can remove it
7141
with mysqladmin -u root drop test after starting the server.
7142
If you have trouble with mysql_install_db at this point, see
7143
Section 2.13.1.1, "Problems Running mysql_install_db."
7145
3. Start the MySQL server:
7146
shell> bin/mysqld_safe --user=mysql &
7147
It is important that the MySQL server be run using an
7148
unprivileged (non-root) login account. To ensure this, the
7149
--user option should be used as shown if you run mysqld_safe
7150
as system root. Otherwise, you should execute the script while
7151
logged in to the system as mysql, in which case you can omit
7152
the --user option from the command.
7153
Further instructions for running MySQL as an unprivileged user
7154
are given in Section 5.3.6, "How to Run MySQL as a Normal
7156
If you neglected to create the grant tables before proceeding
7157
to this step, the following message appears in the error log
7158
file when you start the server:
7159
mysqld: Can't find file: 'host.frm'
7160
If you have other problems starting the server, see Section
7161
2.13.1.3, "Starting and Troubleshooting the MySQL Server."
7163
4. Use mysqladmin to verify that the server is running. The
7164
following commands provide simple tests to check whether the
7165
server is up and responding to connections:
7166
shell> bin/mysqladmin version
7167
shell> bin/mysqladmin variables
7168
The output from mysqladmin version varies slightly depending
7169
on your platform and version of MySQL, but should be similar
7171
shell> bin/mysqladmin version
7172
mysqladmin Ver 14.12 Distrib 5.1.45, for pc-linux-gnu on i686
7175
Server version 5.1.45
7177
Connection Localhost via UNIX socket
7178
UNIX socket /var/lib/mysql/mysql.sock
7179
Uptime: 14 days 5 hours 5 min 21 sec
7181
Threads: 1 Questions: 366 Slow queries: 0
7182
Opens: 0 Flush tables: 1 Open tables: 19
7183
Queries per second avg: 0.000
7184
To see what else you can do with mysqladmin, invoke it with
7187
5. Verify that you can shut down the server:
7188
shell> bin/mysqladmin -u root shutdown
7190
6. Verify that you can start the server again. Do this by using
7191
mysqld_safe or by invoking mysqld directly. For example:
7192
shell> bin/mysqld_safe --user=mysql --log &
7193
If mysqld_safe fails, see Section 2.13.1.3, "Starting and
7194
Troubleshooting the MySQL Server."
7196
7. Run some simple tests to verify that you can retrieve
7197
information from the server. The output should be similar to
7199
shell> bin/mysqlshow
7207
shell> bin/mysqlshow mysql
7209
+---------------------------+
7211
+---------------------------+
7224
| time_zone_leap_second |
7226
| time_zone_transition |
7227
| time_zone_transition_type |
7229
+---------------------------+
7231
shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql
7232
+------+--------+------+
7233
| host | db | user |
7234
+------+--------+------+
7237
+------+--------+------+
7239
8. There is a benchmark suite in the sql-bench directory (under
7240
the MySQL installation directory) that you can use to compare
7241
how MySQL performs on different platforms. The benchmark suite
7242
is written in Perl. It requires the Perl DBI module that
7243
provides a database-independent interface to the various
7244
databases, and some other additional Perl modules:
7249
These modules can be obtained from CPAN
7250
(http://www.cpan.org/). See also Section 2.15.1, "Installing
7252
The sql-bench/Results directory contains the results from many
7253
runs against different databases and platforms. To run all
7254
tests, execute these commands:
7256
shell> perl run-all-tests
7257
If you don't have the sql-bench directory, you probably
7258
installed MySQL using RPM files other than the source RPM.
7259
(The source RPM includes the sql-bench benchmark directory.)
7260
In this case, you must first install the benchmark suite
7261
before you can use it. There are separate benchmark RPM files
7262
named mysql-bench-VERSION.i386.rpm that contain benchmark code
7264
If you have a source distribution, there are also tests in its
7265
tests subdirectory that you can run. For example, to run
7266
auto_increment.tst, execute this command from the top-level
7267
directory of your source distribution:
7268
shell> mysql -vvf test < ./tests/auto_increment.tst
7269
The expected result of the test can be found in the
7270
./tests/auto_increment.res file.
7272
9. At this point, you should have the server running. However,
7273
none of the initial MySQL accounts have a password, so you
7274
should assign passwords using the instructions found in
7275
Section 2.13.2, "Securing the Initial MySQL Accounts."
7277
The MySQL 5.1 installation procedure creates time zone tables in
7278
the mysql database. However, you must populate the tables manually
7279
using the instructions in Section 9.6, "MySQL Server Time Zone
7282
2.13.1.1. Problems Running mysql_install_db
7284
The purpose of the mysql_install_db script is to generate new
7285
MySQL privilege tables. It does not overwrite existing MySQL
7286
privilege tables, and it does not affect any other data.
7288
If you want to re-create your privilege tables, first stop the
7289
mysqld server if it is running. Then rename the mysql directory
7290
under the data directory to save it, and then run
7291
mysql_install_db. Suppose that your current directory is the MySQL
7292
installation directory and that mysql_install_db is located in the
7293
bin directory and the data directory is named data. To rename the
7294
mysql database and re-run mysql_install_db, use these commands.
7295
shell> mv data/mysql data/mysql.old
7296
shell> bin/mysql_install_db --user=mysql
7298
When you run mysql_install_db, you might encounter the following
7301
* mysql_install_db fails to install the grant tables
7302
You may find that mysql_install_db fails to install the grant
7303
tables and terminates after displaying the following messages:
7304
Starting mysqld daemon with databases from XXXXXX
7306
In this case, you should examine the error log file very
7307
carefully. The log should be located in the directory XXXXXX
7308
named by the error message and should indicate why mysqld
7309
didn't start. If you do not understand what happened, include
7310
the log when you post a bug report. See Section 1.7, "How to
7311
Report Bugs or Problems."
7313
* There is a mysqld process running
7314
This indicates that the server is running, in which case the
7315
grant tables have probably been created already. If so, there
7316
is no need to run mysql_install_db at all because it needs to
7317
be run only once (when you install MySQL the first time).
7319
* Installing a second mysqld server does not work when one
7321
This can happen when you have an existing MySQL installation,
7322
but want to put a new installation in a different location.
7323
For example, you might have a production installation, but you
7324
want to create a second installation for testing purposes.
7325
Generally the problem that occurs when you try to run a second
7326
server is that it tries to use a network interface that is in
7327
use by the first server. In this case, you should see one of
7328
the following error messages:
7329
Can't start server: Bind on TCP/IP port:
7330
Address already in use
7331
Can't start server: Bind on unix socket...
7332
For instructions on setting up multiple servers, see Section
7333
5.6, "Running Multiple MySQL Servers on the Same Machine."
7335
* You do not have write access to the /tmp directory
7336
If you do not have write access to create temporary files or a
7337
Unix socket file in the default location (the /tmp directory),
7338
an error occurs when you run mysql_install_db or the mysqld
7340
You can specify different locations for the temporary
7341
directory and Unix socket file by executing these commands
7342
prior to starting mysql_install_db or mysqld, where
7343
some_tmp_dir is the full path name to some directory for which
7344
you have write permission:
7345
shell> TMPDIR=/some_tmp_dir/
7346
shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysql.sock
7347
shell> export TMPDIR MYSQL_UNIX_PORT
7348
Then you should be able to run mysql_install_db and start the
7349
server with these commands:
7350
shell> bin/mysql_install_db --user=mysql
7351
shell> bin/mysqld_safe --user=mysql &
7352
If mysql_install_db is located in the scripts directory,
7353
modify the first command to scripts/mysql_install_db.
7354
See Section B.5.4.5, "How to Protect or Change the MySQL Unix
7355
Socket File," and Section 2.14, "Environment Variables."
7357
There are some alternatives to running the mysql_install_db script
7358
provided in the MySQL distribution:
7360
* If you want the initial privileges to be different from the
7361
standard defaults, you can modify mysql_install_db before you
7362
run it. However, it is preferable to use GRANT and REVOKE to
7363
change the privileges after the grant tables have been set up.
7364
In other words, you can run mysql_install_db, and then use
7365
mysql -u root mysql to connect to the server as the MySQL root
7366
user so that you can issue the necessary GRANT and REVOKE
7368
If you want to install MySQL on several machines with the same
7369
privileges, you can put the GRANT and REVOKE statements in a
7370
file and execute the file as a script using mysql after
7371
running mysql_install_db. For example:
7372
shell> bin/mysql_install_db --user=mysql
7373
shell> bin/mysql -u root < your_script_file
7374
By doing this, you can avoid having to issue the statements
7375
manually on each machine.
7377
* It is possible to re-create the grant tables completely after
7378
they have previously been created. You might want to do this
7379
if you're just learning how to use GRANT and REVOKE and have
7380
made so many modifications after running mysql_install_db that
7381
you want to wipe out the tables and start over.
7382
To re-create the grant tables, remove all the .frm, .MYI, and
7383
.MYD files in the mysql database directory. Then run the
7384
mysql_install_db script again.
7386
* You can start mysqld manually using the --skip-grant-tables
7387
option and add the privilege information yourself using mysql:
7388
shell> bin/mysqld_safe --user=mysql --skip-grant-tables &
7389
shell> bin/mysql mysql
7390
From mysql, manually execute the SQL commands contained in
7391
mysql_install_db. Make sure that you run mysqladmin
7392
flush-privileges or mysqladmin reload afterward to tell the
7393
server to reload the grant tables.
7394
Note that by not using mysql_install_db, you not only have to
7395
populate the grant tables manually, you also have to create
7398
2.13.1.2. Starting and Stopping MySQL Automatically
7400
Generally, you start the mysqld server in one of these ways:
7402
* Invoke mysqld directly. This works on any platform.
7404
* Run the MySQL server as a Windows service. The service can be
7405
set to start the server automatically when Windows starts, or
7406
as a manual service that you start on request. For
7407
instructions, see Section 2.5.5.6, "Starting MySQL as a
7410
* Invoke mysqld_safe, which tries to determine the proper
7411
options for mysqld and then runs it with those options. This
7412
script is used on Unix and Unix-like systems. See Section
7413
4.3.2, "mysqld_safe --- MySQL Server Startup Script."
7415
* Invoke mysql.server. This script is used primarily at system
7416
startup and shutdown on systems that use System V-style run
7417
directories, where it usually is installed under the name
7418
mysql. The mysql.server script starts the server by invoking
7419
mysqld_safe. See Section 4.3.3, "mysql.server --- MySQL Server
7422
* On Mac OS X, install a separate MySQL Startup Item package to
7423
enable the automatic startup of MySQL on system startup. The
7424
Startup Item starts the server by invoking mysql.server. See
7425
Section 2.7, "Installing MySQL on Mac OS X," for details.
7427
The mysqld_safe and mysql.server scripts and the Mac OS X Startup
7428
Item can be used to start the server manually, or automatically at
7429
system startup time. mysql.server and the Startup Item also can be
7430
used to stop the server.
7432
To start or stop the server manually using the mysql.server
7433
script, invoke it with start or stop arguments:
7434
shell> mysql.server start
7435
shell> mysql.server stop
7437
Before mysql.server starts the server, it changes location to the
7438
MySQL installation directory, and then invokes mysqld_safe. If you
7439
want the server to run as some specific user, add an appropriate
7440
user option to the [mysqld] group of the /etc/my.cnf option file,
7441
as shown later in this section. (It is possible that you will need
7442
to edit mysql.server if you've installed a binary distribution of
7443
MySQL in a nonstandard location. Modify it to change location into
7444
the proper directory before it runs mysqld_safe. If you do this,
7445
your modified version of mysql.server may be overwritten if you
7446
upgrade MySQL in the future, so you should make a copy of your
7447
edited version that you can reinstall.)
7449
mysql.server stop stops the server by sending a signal to it. You
7450
can also stop the server manually by executing mysqladmin
7453
To start and stop MySQL automatically on your server, you need to
7454
add start and stop commands to the appropriate places in your
7457
If you use the Linux server RPM package
7458
(MySQL-server-VERSION.rpm), the mysql.server script is installed
7459
in the /etc/init.d directory with the name mysql. You need not
7460
install it manually. See Section 2.6.1, "Installing MySQL from RPM
7461
Packages on Linux," for more information on the Linux RPM
7464
Some vendors provide RPM packages that install a startup script
7465
under a different name such as mysqld.
7467
If you install MySQL from a source distribution or using a binary
7468
distribution format that does not install mysql.server
7469
automatically, you can install it manually. The script can be
7470
found in the support-files directory under the MySQL installation
7471
directory or in a MySQL source tree.
7473
To install mysql.server manually, copy it to the /etc/init.d
7474
directory with the name mysql, and then make it executable. Do
7475
this by changing location into the appropriate directory where
7476
mysql.server is located and executing these commands:
7477
shell> cp mysql.server /etc/init.d/mysql
7478
shell> chmod +x /etc/init.d/mysql
7480
Older Red Hat systems use the /etc/rc.d/init.d directory rather
7481
than /etc/init.d. Adjust the preceding commands accordingly.
7482
Alternatively, first create /etc/init.d as a symbolic link that
7483
points to /etc/rc.d/init.d:
7485
shell> ln -s rc.d/init.d .
7487
After installing the script, the commands needed to activate it to
7488
run at system startup depend on your operating system. On Linux,
7489
you can use chkconfig:
7490
shell> chkconfig --add mysql
7492
On some Linux systems, the following command also seems to be
7493
necessary to fully enable the mysql script:
7494
shell> chkconfig --level 345 mysql on
7496
On FreeBSD, startup scripts generally should go in
7497
/usr/local/etc/rc.d/. The rc(8) manual page states that scripts in
7498
this directory are executed only if their basename matches the
7499
*.sh shell file name pattern. Any other files or directories
7500
present within the directory are silently ignored. In other words,
7501
on FreeBSD, you should install the mysql.server script as
7502
/usr/local/etc/rc.d/mysql.server.sh to enable automatic startup.
7504
As an alternative to the preceding setup, some operating systems
7505
also use /etc/rc.local or /etc/init.d/boot.local to start
7506
additional services on startup. To start up MySQL using this
7507
method, you could append a command like the one following to the
7508
appropriate startup file:
7509
/bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'
7511
For other systems, consult your operating system documentation to
7512
see how to install startup scripts.
7514
You can add options for mysql.server in a global /etc/my.cnf file.
7515
A typical /etc/my.cnf file might look like this:
7517
datadir=/usr/local/mysql/var
7518
socket=/var/tmp/mysql.sock
7523
basedir=/usr/local/mysql
7525
The mysql.server script supports the following options: basedir,
7526
datadir, and pid-file. If specified, they must be placed in an
7527
option file, not on the command line. mysql.server supports only
7528
start and stop as command-line arguments.
7530
The following table shows which option groups the server and each
7531
startup script read from option files.
7532
Script Option Groups
7533
mysqld [mysqld], [server], [mysqld-major_version]
7534
mysqld_safe [mysqld], [server], [mysqld_safe]
7535
mysql.server [mysqld], [mysql.server], [server]
7537
[mysqld-major_version] means that groups with names like
7538
[mysqld-5.0] and [mysqld-5.1] are read by servers having versions
7539
5.0.x, 5.1.x, and so forth. This feature can be used to specify
7540
options that can be read only by servers within a given release
7543
For backward compatibility, mysql.server also reads the
7544
[mysql_server] group and mysqld_safe also reads the [safe_mysqld]
7545
group. However, you should update your option files to use the
7546
[mysql.server] and [mysqld_safe] groups instead when using MySQL
7549
See Section 4.2.3.3, "Using Option Files."
7551
2.13.1.3. Starting and Troubleshooting the MySQL Server
7553
This section provides troubleshooting suggestions for problems
7554
starting the server on Unix. If you are using Windows, see Section
7555
2.5.6, "Troubleshooting a MySQL Installation Under Windows."
7557
If you have problems starting the server, here are some things to
7560
* Check the error log to see why the server does not start.
7562
* Specify any special options needed by the storage engines you
7565
* Make sure that the server knows where to find the data
7568
* Make sure that the server can access the data directory. The
7569
ownership and permissions of the data directory and its
7570
contents must be set such that the server can read and modify
7573
* Verify that the network interfaces the server wants to use are
7576
Some storage engines have options that control their behavior. You
7577
can create a my.cnf file and specify startup options for the
7578
engines that you plan to use. If you are going to use storage
7579
engines that support transactional tables (InnoDB, NDB), be sure
7580
that you have them configured the way you want before starting the
7583
* If you are using InnoDB tables, see Section 13.6.2, "InnoDB
7586
* If you are using MySQL Cluster, see Section 17.3, "MySQL
7587
Cluster Configuration."
7589
MySQL Enterprise For expert advice on start-up options appropriate
7590
to your circumstances, subscribe to The MySQL Enterprise Monitor.
7591
For more information, see
7592
http://www.mysql.com/products/enterprise/advisors.html.
7594
Storage engines will use default option values if you specify
7595
none, but it is recommended that you review the available options
7596
and specify explicit values for those for which the defaults are
7597
not appropriate for your installation.
7599
When the mysqld server starts, it changes location to the data
7600
directory. This is where it expects to find databases and where it
7601
expects to write log files. The server also writes the pid
7602
(process ID) file in the data directory.
7604
The data directory location is hardwired in when the server is
7605
compiled. This is where the server looks for the data directory by
7606
default. If the data directory is located somewhere else on your
7607
system, the server will not work properly. You can determine what
7608
the default path settings are by invoking mysqld with the
7609
--verbose and --help options.
7611
If the default locations don't match the MySQL installation layout
7612
on your system, you can override them by specifying options to
7613
mysqld or mysqld_safe on the command line or in an option file.
7615
To specify the location of the data directory explicitly, use the
7616
--datadir option. However, normally you can tell mysqld the
7617
location of the base directory under which MySQL is installed and
7618
it looks for the data directory there. You can do this with the
7621
To check the effect of specifying path options, invoke mysqld with
7622
those options followed by the --verbose and --help options. For
7623
example, if you change location into the directory where mysqld is
7624
installed and then run the following command, it shows the effect
7625
of starting the server with a base directory of /usr/local:
7626
shell> ./mysqld --basedir=/usr/local --verbose --help
7628
You can specify other options such as --datadir as well, but
7629
--verbose and --help must be the last options.
7631
Once you determine the path settings you want, start the server
7632
without --verbose and --help.
7634
If mysqld is currently running, you can find out what path
7635
settings it is using by executing this command:
7636
shell> mysqladmin variables
7639
shell> mysqladmin -h host_name variables
7641
host_name is the name of the MySQL server host.
7643
If you get Errcode 13 (which means Permission denied) when
7644
starting mysqld, this means that the privileges of the data
7645
directory or its contents do not allow the server access. In this
7646
case, you change the permissions for the involved files and
7647
directories so that the server has the right to use them. You can
7648
also start the server as root, but this raises security issues and
7651
On Unix, change location into the data directory and check the
7652
ownership of the data directory and its contents to make sure the
7653
server has access. For example, if the data directory is
7654
/usr/local/mysql/var, use this command:
7655
shell> ls -la /usr/local/mysql/var
7657
If the data directory or its files or subdirectories are not owned
7658
by the login account that you use for running the server, change
7659
their ownership to that account. If the account is named mysql,
7661
shell> chown -R mysql /usr/local/mysql/var
7662
shell> chgrp -R mysql /usr/local/mysql/var
7664
If it possible that even with correct ownership, MySQL may fail to
7665
start up if there is other security software running on your
7666
system that manages application access to various parts of the
7667
file system. In this case, you may need to reconfigure that
7668
software to enable mysqld to access the directories it uses during
7671
If the server fails to start up correctly, check the error log.
7672
Log files are located in the data directory (typically C:\Program
7673
Files\MySQL\MySQL Server 5.1\data on Windows,
7674
/usr/local/mysql/data for a Unix binary distribution, and
7675
/usr/local/var for a Unix source distribution). Look in the data
7676
directory for files with names of the form host_name.err and
7677
host_name.log, where host_name is the name of your server host.
7678
Then examine the last few lines of these files. On Unix, you can
7679
use tail to display them:
7680
shell> tail host_name.err
7681
shell> tail host_name.log
7683
The error log should contain information that indicates why the
7684
server couldn't start.
7686
If either of the following errors occur, it means that some other
7687
program (perhaps another mysqld server) is using the TCP/IP port
7688
or Unix socket file that mysqld is trying to use:
7689
Can't start server: Bind on TCP/IP port: Address already in use
7690
Can't start server: Bind on unix socket...
7692
Use ps to determine whether you have another mysqld server
7693
running. If so, shut down the server before starting mysqld again.
7694
(If another server is running, and you really want to run multiple
7695
servers, you can find information about how to do so in Section
7696
5.6, "Running Multiple MySQL Servers on the Same Machine.")
7698
If no other server is running, try to execute the command telnet
7699
your_host_name tcp_ip_port_number. (The default MySQL port number
7700
is 3306.) Then press Enter a couple of times. If you don't get an
7701
error message like telnet: Unable to connect to remote host:
7702
Connection refused, some other program is using the TCP/IP port
7703
that mysqld is trying to use. You'll need to track down what
7704
program this is and disable it, or else tell mysqld to listen to a
7705
different port with the --port option. In this case, you'll also
7706
need to specify the port number for client programs when
7707
connecting to the server via TCP/IP.
7709
Another reason the port might be inaccessible is that you have a
7710
firewall running that blocks connections to it. If so, modify the
7711
firewall settings to allow access to the port.
7713
If the server starts but you can't connect to it, you should make
7714
sure that you have an entry in /etc/hosts that looks like this:
7717
This problem occurs only on systems that do not have a working
7718
thread library and for which MySQL must be configured to use
7721
If you cannot get mysqld to start, you can try to make a trace
7722
file to find the problem by using the --debug option. See MySQL
7724
(http://forge.mysql.com/wiki/MySQL_Internals_Porting).
7726
2.13.2. Securing the Initial MySQL Accounts
7728
Part of the MySQL installation process is to set up the mysql
7729
database that contains the grant tables:
7731
* Windows distributions contain preinitialized grant tables that
7732
are installed automatically.
7734
* On Unix, the grant tables are populated by the
7735
mysql_install_db program. Some installation methods run this
7736
program for you. Others require that you execute it manually.
7737
For details, see Section 2.13.1, "Unix Post-Installation
7740
The grant tables define the initial MySQL user accounts and their
7741
access privileges. These accounts are set up as follows:
7743
* Accounts with the user name root are created. These are
7744
superuser accounts that can do anything. The initial root
7745
account passwords are empty, so anyone can connect to the
7746
MySQL server as root --- without a password --- and be granted
7749
+ On Windows, one root account is created; this account
7750
allows connecting from the local host only. The Windows
7751
installer will optionally create an account allowing for
7752
connections from any host only if the user selects the
7753
Enable root access from remote machines option during
7756
+ On Unix, both root accounts are for connections from the
7757
local host. Connections must be made from the local host
7758
by specifying a host name of localhost for one of the
7759
accounts, or the actual host name or IP number for the
7762
* Two anonymous-user accounts are created, each with an empty
7763
user name. The anonymous accounts have no password, so anyone
7764
can use them to connect to the MySQL server.
7766
+ On Windows, one anonymous account is for connections from
7767
the local host. It has no global privileges. (Before
7768
MySQL 5.1.16, it has all global privileges, just like the
7769
root accounts.) The other is for connections from any
7770
host and has all privileges for the test database and for
7771
other databases with names that start with test.
7773
+ On Unix, both anonymous accounts are for connections from
7774
the local host. Connections must be made from the local
7775
host by specifying a host name of localhost for one of
7776
the accounts, or the actual host name or IP number for
7777
the other. These accounts have all privileges for the
7778
test database and for other databases with names that
7781
As noted, none of the initial accounts have passwords. This means
7782
that your MySQL installation is unprotected until you do something
7785
* If you want to prevent clients from connecting as anonymous
7786
users without a password, you should either assign a password
7787
to each anonymous account or else remove the accounts.
7789
* You should assign a password to each MySQL root account.
7791
The following instructions describe how to set up passwords for
7792
the initial MySQL accounts, first for the anonymous accounts and
7793
then for the root accounts. Replace "newpwd" in the examples with
7794
the actual password that you want to use. The instructions also
7795
cover how to remove the anonymous accounts, should you prefer not
7796
to allow anonymous access at all.
7798
You might want to defer setting the passwords until later, so that
7799
you don't need to specify them while you perform additional setup
7800
or testing. However, be sure to set them before using your
7801
installation for production purposes.
7803
Anonymous Account Password Assignment
7805
To assign passwords to the anonymous accounts, connect to the
7806
server as root and then use either SET PASSWORD or UPDATE. In
7807
either case, be sure to encrypt the password using the PASSWORD()
7810
To use SET PASSWORD on Windows, do this:
7811
shell> mysql -u root
7812
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7813
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');
7815
To use SET PASSWORD on Unix, do this:
7816
shell> mysql -u root
7817
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
7818
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
7820
In the second SET PASSWORD statement, replace host_name with the
7821
name of the server host. This is the name that is specified in the
7822
Host column of the non-localhost record for root in the user
7823
table. If you don't know what host name this is, issue the
7824
following statement before using SET PASSWORD:
7825
mysql> SELECT Host, User FROM mysql.user;
7827
Look for the record that has root in the User column and something
7828
other than localhost in the Host column. Then use that Host value
7829
in the second SET PASSWORD statement.
7831
Anonymous Account Removal
7833
If you prefer to remove the anonymous accounts instead, do so as
7835
shell> mysql -u root
7836
mysql> DROP USER '';
7838
The DROP statement applies both to Windows and to Unix. On
7839
Windows, if you want to remove only the anonymous account that has
7840
the same privileges as root, do this instead:
7841
shell> mysql -u root
7842
mysql> DROP USER ''@'localhost';
7844
That account allows anonymous access but has full privileges, so
7845
removing it improves security.
7847
root Account Password Assignment
7849
You can assign passwords to the root accounts in several ways. The
7850
following discussion demonstrates three methods:
7852
* Use the SET PASSWORD statement
7854
* Use the mysqladmin command-line client program
7856
* Use the UPDATE statement
7858
To assign passwords using SET PASSWORD, connect to the server as
7859
root and issue SET PASSWORD statements. Be sure to encrypt the
7860
password using the PASSWORD() function.
7862
For Windows, do this:
7863
shell> mysql -u root
7864
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
7865
mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
7868
shell> mysql -u root
7869
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
7870
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
7872
In the second SET PASSWORD statement, replace host_name with the
7873
name of the server host. This is the same host name that you used
7874
when you assigned the anonymous account passwords.
7876
If the user table contains an account with User and Host values of
7877
'root' and '127.0.0.1', use an additional SET PASSWORD statement
7878
to set that account's password:
7879
mysql> SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('newpwd');
7881
To assign passwords to the root accounts using mysqladmin, execute
7882
the following commands:
7883
shell> mysqladmin -u root password "newpwd"
7884
shell> mysqladmin -u root -h host_name password "newpwd"
7886
These commands apply both to Windows and to Unix. In the second
7887
command, replace host_name with the name of the server host. The
7888
double quotes around the password are not always necessary, but
7889
you should use them if the password contains spaces or other
7890
characters that are special to your command interpreter.
7892
The mysqladmin method of setting the root account passwords does
7893
not set the password for the 'root'@'127.0.0.1' account. To do so,
7894
use SET PASSWORD as shown earlier.
7896
You can also use UPDATE to modify the user table directly. The
7897
following UPDATE statement assigns a password to all root
7899
shell> mysql -u root
7900
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
7901
-> WHERE User = 'root';
7902
mysql> FLUSH PRIVILEGES;
7904
The UPDATE statement applies both to Windows and to Unix.
7906
After the passwords have been set, you must supply the appropriate
7907
password whenever you connect to the server. For example, if you
7908
want to use mysqladmin to shut down the server, you can do so
7910
shell> mysqladmin -u root -p shutdown
7911
Enter password: (enter root password here)
7915
If you forget your root password after setting it up, Section
7916
B.5.4.1, "How to Reset the Root Password," covers the procedure
7919
To set up additional accounts, you can use the GRANT statement.
7920
For instructions, see Section 5.5.2, "Adding User Accounts."
7922
2.14. Environment Variables
7924
This section lists all the environment variables that are used
7925
directly or indirectly by MySQL. Most of these can also be found
7926
in other places in this manual.
7928
Note that any options on the command line take precedence over
7929
values specified in option files and environment variables, and
7930
values in option files take precedence over values in environment
7933
In many cases, it is preferable to use an option file instead of
7934
environment variables to modify the behavior of MySQL. See Section
7935
4.2.3.3, "Using Option Files."
7936
Variable Description
7937
CXX The name of your C++ compiler (for running configure).
7938
CC The name of your C compiler (for running configure).
7939
CFLAGS Flags for your C compiler (for running configure).
7940
CXXFLAGS Flags for your C++ compiler (for running configure).
7941
DBI_USER The default user name for Perl DBI.
7942
DBI_TRACE Trace options for Perl DBI.
7943
HOME The default path for the mysql history file is
7944
$HOME/.mysql_history.
7945
LD_RUN_PATH Used to specify the location of libmysqlclient.so.
7946
MYSQL_DEBUG Debug trace options when debugging.
7947
MYSQL_GROUP_SUFFIX Option group suffix value (like specifying
7948
--defaults-group-suffix).
7949
MYSQL_HISTFILE The path to the mysql history file. If this
7950
variable is set, its value overrides the default for
7951
$HOME/.mysql_history.
7952
MYSQL_HOME The path to the directory in which the server-specific
7953
my.cnf file resides (as of MySQL 5.0.3).
7954
MYSQL_HOST The default host name used by the mysql command-line
7956
MYSQL_PS1 The command prompt to use in the mysql command-line
7958
MYSQL_PWD The default password when connecting to mysqld. Note
7959
that using this is insecure. See Section 5.3.2.2, "End-User
7960
Guidelines for Password Security."
7961
MYSQL_TCP_PORT The default TCP/IP port number.
7962
MYSQL_UNIX_PORT The default Unix socket file name; used for
7963
connections to localhost.
7964
PATH Used by the shell to find MySQL programs.
7965
TMPDIR The directory where temporary files are created.
7966
TZ This should be set to your local time zone. See Section
7967
B.5.4.6, "Time Zone Problems."
7968
UMASK The user-file creation mode when creating files. See note
7970
UMASK_DIR The user-directory creation mode when creating
7971
directories. See note following table.
7972
USER The default user name on Windows and NetWare used when
7973
connecting to mysqld.
7975
The UMASK and UMASK_DIR variables, despite their names, are used
7976
as modes, not masks:
7978
* If UMASK is set, mysqld uses ($UMASK | 0600) as the mode for
7979
file creation, so that newly created files have a mode in the
7980
range from 0600 to 0666 (all values octal).
7982
* If UMASK_DIR is set, mysqld uses ($UMASK_DIR | 0700) as the
7983
base mode for directory creation, which then is AND-ed with
7984
~(~$UMASK & 0666), so that newly created directories have a
7985
mode in the range from 0700 to 0777 (all values octal). The
7986
AND operation may remove read and write permissions from the
7987
directory mode, but not execute permissions.
7989
MySQL assumes that the value for UMASK or UMASK_DIR is in octal if
7990
it starts with a zero.
7992
2.15. Perl Installation Notes
7994
Perl support for MySQL is provided by means of the DBI/DBD client
7995
interface. The interface requires Perl 5.6.0, and 5.6.1 or later
7996
is preferred. DBI does not work if you have an older version of
7999
If you want to use transactions with Perl DBI, you need to have
8000
DBD::mysql 2.0900. If you are using the MySQL 4.1 or newer client
8001
library, you must use DBD::mysql 2.9003 or newer. Support for
8002
server-side prepared statements requires DBD::mysql 3.0009 or
8005
Perl support is not included with MySQL distributions. You can
8006
obtain the necessary modules from http://search.cpan.org for Unix,
8007
or by using the ActiveState ppm program on Windows. The following
8008
sections describe how to do this.
8010
Perl support for MySQL must be installed if you want to run the
8011
MySQL benchmark scripts; see Section 7.1.3, "The MySQL Benchmark
8012
Suite." It is also required for the MySQL Cluster ndb_size.pl
8013
utility; see Section 17.4.21, "ndb_size.pl --- NDBCLUSTER Size
8014
Requirement Estimator."
8016
2.15.1. Installing Perl on Unix
8018
MySQL Perl support requires that you have installed MySQL client
8019
programming support (libraries and header files). Most
8020
installation methods install the necessary files. However, if you
8021
installed MySQL from RPM files on Linux, be sure that you've
8022
installed the developer RPM. The client programs are in the client
8023
RPM, but client programming support is in the developer RPM.
8025
If you want to install Perl support, the files you need can be
8026
obtained from the CPAN (Comprehensive Perl Archive Network) at
8027
http://search.cpan.org.
8029
The easiest way to install Perl modules on Unix is to use the CPAN
8030
module. For example:
8031
shell> perl -MCPAN -e shell
8033
cpan> install DBD::mysql
8035
The DBD::mysql installation runs a number of tests. These tests
8036
attempt to connect to the local MySQL server using the default
8037
user name and password. (The default user name is your login name
8038
on Unix, and ODBC on Windows. The default password is "no
8039
password.") If you cannot connect to the server with those values
8040
(for example, if your account has a password), the tests fail. You
8041
can use force install DBD::mysql to ignore the failed tests.
8043
DBI requires the Data::Dumper module. It may be installed; if not,
8044
you should install it before installing DBI.
8046
It is also possible to download the module distributions in the
8047
form of compressed tar archives and build the modules manually.
8048
For example, to unpack and build a DBI distribution, use a
8049
procedure such as this:
8051
1. Unpack the distribution into the current directory:
8052
shell> gunzip < DBI-VERSION.tar.gz | tar xvf -
8053
This command creates a directory named DBI-VERSION.
8055
2. Change location into the top-level directory of the unpacked
8057
shell> cd DBI-VERSION
8059
3. Build the distribution and compile everything:
8060
shell> perl Makefile.PL
8065
The make test command is important because it verifies that the
8066
module is working. Note that when you run that command during the
8067
DBD::mysql installation to exercise the interface code, the MySQL
8068
server must be running or the test fails.
8070
It is a good idea to rebuild and reinstall the DBD::mysql
8071
distribution whenever you install a new release of MySQL,
8072
particularly if you notice symptoms such as that all your DBI
8073
scripts fail after you upgrade MySQL.
8075
If you do not have access rights to install Perl modules in the
8076
system directory or if you want to install local Perl modules, the
8077
following reference may be useful:
8078
http://servers.digitaldaze.com/extensions/perl/modules.html#module
8081
Look under the heading "Installing New Modules that Require
8082
Locally Installed Modules."
8084
2.15.2. Installing ActiveState Perl on Windows
8086
On Windows, you should do the following to install the MySQL DBD
8087
module with ActiveState Perl:
8089
1. Get ActiveState Perl from
8090
http://www.activestate.com/Products/ActivePerl/ and install
8093
2. Open a console window (a "DOS window").
8095
3. If necessary, set the HTTP_proxy variable. For example, you
8096
might try a setting like this:
8097
set HTTP_proxy=my.proxy.com:3128
8099
4. Start the PPM program:
8100
C:\> C:\perl\bin\ppm.pl
8102
5. If you have not previously done so, install DBI:
8105
6. If this succeeds, run the following command:
8106
ppm> install DBD-mysql
8108
This procedure should work with ActiveState Perl 5.6 or newer.
8110
If you cannot get the procedure to work, you should install the
8111
MyODBC driver instead and connect to the MySQL server through
8114
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
8115
die "Got error $DBI::errstr when connecting to $dsn\n";
8117
2.15.3. Problems Using the Perl DBI/DBD Interface
8119
If Perl reports that it cannot find the ../mysql/mysql.so module,
8120
the problem is probably that Perl cannot locate the
8121
libmysqlclient.so shared library. You should be able to fix this
8122
problem by one of the following methods:
8124
* Compile the DBD::mysql distribution with perl Makefile.PL
8125
-static -config rather than perl Makefile.PL.
8127
* Copy libmysqlclient.so to the directory where your other
8128
shared libraries are located (probably /usr/lib or /lib).
8130
* Modify the -L options used to compile DBD::mysql to reflect
8131
the actual location of libmysqlclient.so.
8133
* On Linux, you can add the path name of the directory where
8134
libmysqlclient.so is located to the /etc/ld.so.conf file.
8136
* Add the path name of the directory where libmysqlclient.so is
8137
located to the LD_RUN_PATH environment variable. Some systems
8138
use LD_LIBRARY_PATH instead.
8140
Note that you may also need to modify the -L options if there are
8141
other libraries that the linker fails to find. For example, if the
8142
linker cannot find libc because it is in /lib and the link command
8143
specifies -L/usr/lib, change the -L option to -L/lib or add -L/lib
8144
to the existing link command.
8146
If you get the following errors from DBD::mysql, you are probably
8147
using gcc (or using an old binary compiled with gcc):
8148
/usr/bin/perl: can't resolve symbol '__moddi3'
8149
/usr/bin/perl: can't resolve symbol '__divdi3'
8151
Add -L/usr/lib/gcc-lib/... -lgcc to the link command when the
8152
mysql.so library gets built (check the output from make for
8153
mysql.so when you compile the Perl client). The -L option should
8154
specify the path name of the directory where libgcc.a is located
8157
Another cause of this problem may be that Perl and MySQL are not
8158
both compiled with gcc. In this case, you can solve the mismatch
8159
by compiling both with gcc.
8161
You may see the following error from DBD::mysql when you run the
8163
t/00base............install_driver(mysql) failed:
8164
Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mys
8166
../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
8167
uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 16
8170
This means that you need to include the -lz compression library on
8171
the link line. That can be done by changing the following line in
8172
the file lib/DBD/mysql/Install.pm:
8173
$sysliblist .= " -lm";
8175
Change that line to:
8176
$sysliblist .= " -lm -lz";
8178
After this, you must run make realclean and then proceed with the
8179
installation from the beginning.
8181
If you want to install DBI on SCO, you have to edit the Makefile
8182
in DBI-xxx and each subdirectory. Note that the following assumes
8183
gcc 2.95.2 or newer:
8186
CCCDLFLAGS = -KPIC -W1,-Bexport CCCDLFLAGS = -fpic
8187
CCDLFLAGS = -wl,-Bexport CCDLFLAGS =
8189
LD = ld LD = gcc -G -fpic
8190
LDDLFLAGS = -G -L/usr/local/lib LDDLFLAGS = -L/usr/local/lib
8191
LDFLAGS = -belf -L/usr/local/lib LDFLAGS = -L/usr/local/lib
8193
LD = ld LD = gcc -G -fpic
8194
OPTIMISE = -Od OPTIMISE = -O1
8197
CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include
8200
CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include
8202
These changes are necessary because the Perl dynaloader does not
8203
load the DBI modules if they were compiled with icc or cc.
8205
If you want to use the Perl module on a system that does not
8206
support dynamic linking (such as SCO), you can generate a static
8207
version of Perl that includes DBI and DBD::mysql. The way this
8208
works is that you generate a version of Perl with the DBI code
8209
linked in and install it on top of your current Perl. Then you use
8210
that to build a version of Perl that additionally has the DBD code
8211
linked in, and install that.
8213
On SCO, you must have the following environment variables set:
8214
LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib
8217
LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
8218
/usr/progressive/lib:/usr/skunk/lib
8219
LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
8220
/usr/progressive/lib:/usr/skunk/lib
8221
MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\
8224
First, create a Perl that includes a statically linked DBI module
8225
by running these commands in the directory where your DBI
8226
distribution is located:
8227
shell> perl Makefile.PL -static -config
8232
Then you must install the new Perl. The output of make perl
8233
indicates the exact make command you need to execute to perform
8234
the installation. On SCO, this is make -f Makefile.aperl inst_perl
8237
Next, use the just-created Perl to create another Perl that also
8238
includes a statically linked DBD::mysql by running these commands
8239
in the directory where your DBD::mysql distribution is located:
8240
shell> perl Makefile.PL -static -config
8245
Finally, you should install this new Perl. Again, the output of
8246
make perl indicates the command to use.
added
removed
INSTALL-SOURCE
