The MySQL (R) software delivers a very fast, multi-threaded, multi-user, and robust SQL (Structured Query Language) database server. MySQL Server is intended for mission-critical, heavy-load production systems as well as for embedding into mass-deployed software. MySQL is a registered trademark of MySQL AB.
The MySQL software is Dual Licensed. Users can choose to use the MySQL software as an Open Source product under the terms of the GNU General Public License (http://www.fsf.org/licenses/) or can purchase a standard commercial license from MySQL AB. See http://www.mysql.com/company/legal/licensing/ for more information on our licensing policies.
The following list describes some sections of particular interest in this manual:
Important:
Reports of errors (often called ``bugs''), as well as questions and comments, should be sent to http://bugs.mysql.com. See section 1.4.1.3 How to Report Bugs or Problems.
If you have found a sensitive security bug in MySQL Server, please let us know immediately by sending an email message to security@mysql.com.
This is the Reference Manual for the MySQL Database System. It documents MySQL up to Version 4.1.11, but is also applicable for older versions of the MySQL software (such as 3.23 or 4.0-production) because functional changes are indicated with reference to a version number.
Because this manual serves as a reference, it does not provide general instruction on SQL or relational database concepts. It also does not teach you how to use your operating system or command-line interpreter.
The MySQL Database Software is under constant development, and the Reference Manual is updated frequently as well. The most recent version of the manual is available online in searchable form at http://dev.mysql.com/doc/. Other formats also are available, including HTML, PDF, and Windows CHM versions.
The primary document is the Texinfo file.
The HTML version is produced automatically using a modified version of
texi2html.
The plain text and Info versions are produced with makeinfo.
The PostScript version is produced using texi2dvi and dvips.
The PDF version is produced with pdftex.
If you have any suggestions concerning additions or corrections to this manual, please send them to the documentation team at docs@mysql.com.
This manual was initially written by David Axmark and Michael ``Monty'' Widenius. It is maintained by the MySQL Documentation Team, consisting of Paul DuBois, Stefan Hinz, Mike Hillyer, Jon Stephens, and Russell Dyer. For the many other contributors, see section B Credits.
The copyright (2004) to this manual is owned by the Swedish company MySQL AB. MySQL and the MySQL logo are (registered) trademarks of MySQL AB. Other trademarks and registered trademarks referred to in this manual are the property of their respective owners, and are used for identification purposes only.
This manual uses certain typographical conventions:
constant
mysqladmin works, invoke it with the
--help option.''
When commands are shown that are meant to be executed from within a particular
program, the program is indicated by a prompt shown before the command. For
example, shell> indicates a command that you execute from your login
shell, and mysql> indicates a statement that you execute from the
mysql client program:
shell> type a shell command here mysql> type a mysql statement here
The ``shell'' is your command interpreter. On Unix, this is typically a
program such as sh or csh. On Windows, the equivalent program is
command.com or cmd.exe, typically run in a console window.
When you enter a command or statement shown in an example, do not type the prompt shown in the example.
Database, table, and column names must often be substituted into statements. To indicate that such substitution is necessary, this manual uses db_name, tbl_name, and col_name. For example, you might see a statement like this:
mysql> SELECT col_name FROM db_name.tbl_name;
This means that if you were to enter a similar statement, you would supply your own database, table, and column names, perhaps like this:
mysql> SELECT author_name FROM biblio_db.author_list;
SQL keywords are not case sensitive and may be written in uppercase or lowercase. This manual uses uppercase.
In syntax descriptions, square brackets (`[' and `]') are used
to indicate optional words or clauses. For example, in the following
statement, IF EXISTS is optional:
DROP TABLE [IF EXISTS] tbl_name
When a syntax element consists of a number of alternatives, the alternatives are separated by vertical bars (`|'). When one member from a set of choices may be chosen, the alternatives are listed within square brackets (`[' and `]'):
TRIM([[BOTH | LEADING | TRAILING] [remstr] FROM] str)
When one member from a set of choices must be chosen, the alternatives are listed within braces (`{' and `}'):
{DESCRIBE | DESC} tbl_name [col_name | wild]
An ellipsis (...) indicates the omission of a section of a statement,
typically to provide a shorter version of more complex syntax. For example,
INSERT ... SELECT is shorthand for the form of INSERT statement
that is followed by a SELECT statement.
An ellipsis can also indicate that the preceding syntax element of a statement may be repeated. In the following example, multiple reset_option values may be given, with each of those after the first preceded by commas:
RESET reset_option [,reset_option] ...
Commands for setting shell variables are shown using Bourne shell syntax. For example, the sequence to set an environment variable and run a command looks like this in Bourne shell syntax:
shell> VARNAME=value some_command
If you are using csh or tcsh, you must issue commands somewhat
differently. You would execute the sequence just shown like this:
shell> setenv VARNAME value shell> some_command
MySQL, the most popular Open Source SQL database management system, is developed, distributed, and supported by MySQL AB. MySQL AB is a commercial company, founded by the MySQL developers. It is a second generation Open Source company that unites Open Source values and methodology with a successful business model.
The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL software and MySQL AB.
The official way to pronounce ``MySQL'' is ``My Ess Que Ell'' (not ``my sequel''), but we don't mind if you pronounce it as ``my sequel'' or in some other localized way.
We started out with the intention of using mSQL to connect to our
tables using our own fast low-level (ISAM) routines. However, after some
testing, we came to the conclusion that mSQL was not fast enough or
flexible enough for our needs. This resulted in a new SQL interface to our
database but with almost the same API interface as mSQL. This API was
designed to allow third-party code that was written for use with mSQL to
be ported easily for use with MySQL.
The derivation of the name MySQL is not clear. Our base directory and a large number of our libraries and tools have had the prefix ``my'' for well over 10 years. However, co-founder Monty Widenius's daughter is also named My. Which of the two gave its name to MySQL is still a mystery, even for us.
The name of the MySQL Dolphin (our logo) is ``Sakila,'' which was chosen by the founders of MySQL AB from a huge list of names suggested by users in our ``Name the Dolphin'' contest. The winning name was submitted by Ambrose Twebaze, an Open Source software developer from Swaziland, Africa. According to Ambrose, the name Sakila has its roots in SiSwati, the local language of Swaziland. Sakila is also the name of a town in Arusha, Tanzania, near Ambrose's country of origin, Uganda.
The following list describes some of the important characteristics of the MySQL Database Software. See also section 1.3 MySQL Development Roadmap for more information about current and upcoming features.
MyISAM) with index compression.
FLOAT, DOUBLE, CHAR, VARCHAR,
TEXT, BLOB, DATE, TIME, DATETIME,
TIMESTAMP, YEAR, SET, ENUM, and OpenGIS spatial
types.
See section 11 Column Types.
SELECT and WHERE
clauses of queries. For example:
mysql> SELECT CONCAT(first_name, ' ', last_name)
-> FROM citizen
-> WHERE income/dependents > 10000 AND age > 30;
GROUP BY and
ORDER BY clauses. Support
for group functions (COUNT(),
COUNT(DISTINCT ...),
AVG(), STD(),
SUM(), MAX(), MIN(), and GROUP_CONCAT()).
LEFT OUTER JOIN and RIGHT OUTER JOIN with both standard
SQL and ODBC syntax.
DELETE, INSERT, REPLACE, and UPDATE return
the number of rows that were changed (affected). It is possible to return
the number of rows matched instead by setting a flag when connecting to the
server.
SHOW command can be used to retrieve
information about databases, tables, and indexes. The EXPLAIN command
can be used to determine how the optimizer resolves a query.
ABS is a valid column name. The only restriction is that for a
function call, no spaces are allowed between the function name and the
`(' that follows it. See section 9.6 Treatment of Reserved Words in MySQL.
CHAR, VARCHAR,
BLOB, or TEXT column types.
--shared-memory option. Clients can
connect through shared memory by using the --protocol=memory option.
latin1 (ISO-8859-1), german, big5, ujis,
and more. For example,
the Scandinavian characters `â', `ä' and `ö' are
allowed in table and column names.
Unicode support is available as of MySQL 4.1.
mysqlcheck client. MySQL also includes
myisamchk, a very fast command-line utility for performing these
operations on MyISAM tables.
See section 5 Database Administration.
--help or -?
options to obtain online assistance.
This section addresses the questions, ``How stable is MySQL Server?'' and, ``Can I depend on MySQL Server in this project?'' We will try to clarify these issues and answer some important questions that concern many potential users. The information in this section is based on data gathered from the mailing lists, which are very active in identifying problems as well as reporting types of use.
The original code stems back to the early 1980s. It provides a stable code
base, and the ISAM table format used by the original storage engine
remains backward-compatible.
At TcX, the predecessor of MySQL AB, MySQL code has worked
in projects since mid-1996, without any problems.
When the MySQL Database Software initially was released to a wider public,
our new users quickly found some pieces of untested code. Each new release
since then has had fewer portability problems, even though each new release
has also had many new features.
Each release of the MySQL Server has been usable. Problems have occurred only when users try code from the ``gray zones.'' Naturally, new users don't know what the gray zones are; this section therefore attempts to document those areas that are currently known. The descriptions mostly deal with Version 3.23, 4.0 and 4.1 of MySQL Server. All known and reported bugs are fixed in the latest version, with the exception of those listed in the bugs section, which are design-related. See section 1.5.7 Known Errors and Design Deficiencies in MySQL.
The MySQL Server design is multi-layered with independent modules. Some of the newer modules are listed here with an indication of how well-tested each of them is:
InnoDB tables (Stable)
InnoDB transactional storage engine has been declared
stable in the MySQL 3.23 tree, starting from version 3.23.49.
InnoDB is being used in large, heavy-load production systems.
BDB tables (Stable)
Berkeley DB code is very stable, but we are still improving
the BDB transactional storage engine interface in MySQL Server.
MyODBC 3.51 (Stable)
MyODBC 3.51 uses ODBC SDK 3.51 and is in wide production use.
Some issues brought up appear to be application-related and independent of
the ODBC driver or underlying database server.
MySQL 3.22 had a 4GB (4 gigabyte) limit on table size. With the
MyISAM storage engine in MySQL 3.23, the maximum table
size was increased to 8 million terabytes (2 ^ 63 bytes). With this larger
allowed table size, the maximum effective table size for MySQL
databases is usually determined by operating system constraints
on file sizes, not by MySQL internal limits.
The InnoDB storage engine maintains InnoDB tables within a
tablespace that can be created from several files. This allows a
table to exceed the maximum individual file size. The tablespace can include
raw disk partitions, which allows extremely large tables. The maximum
tablespace size is 64TB.
The following table lists some examples of operating system file-size limits. This is only a rough guide and is not intended to be definitive. For the most up-to-date information, be sure to check the documentation specific to your operating system.
| Operating System | File-size Limit |
| Linux 2.2-Intel 32-bit | 2GB (LFS: 4GB) |
| Linux 2.4 | (using ext3 filesystem) 4TB |
| Solaris 9/10 | 16TB |
| NetWare w/NSS filesystem | 8TB |
| win32 w/ FAT/FAT32 | 2GB/4GB |
| win32 w/ NTFS | 2TB (possibly larger) |
| MacOS X w/ HFS+ | 2TB |
On Linux 2.2, you can get MyISAM tables larger than 2GB in size by
using the Large File Support (LFS) patch for the ext2 filesystem. On Linux
2.4, patches also exist for ReiserFS to get support for big files (up to 2TB). Most
current Linux distributions are based on kernel 2.4 and include all
the required LFS patches. With JFS and XFS, petabyte and larger files
are possible on Linux. However, the maximum available file size still depends
on several factors, one of them being the filesystem used to store MySQL tables.
For a detailed overview about LFS in Linux, have a look at Andreas Jaeger's Large File Support in Linux page at http://www.suse.de/~aj/linux_lfs.html.
Windows users please note: FAT and VFAT (FAT32) are not considered suitable for production use with MySQL. Use NTFS instead.
By default, MySQL creates MyISAM tables with an internal
structure that allows a maximum size of about 4GB. You can
check the maximum table size for a table with the SHOW TABLE STATUS
statement or with myisamchk -dv tbl_name.
See section 13.5.4 SHOW Syntax.
If you need a MyISAM table that is larger than 4GB in size (and your
operating system supports large files), the CREATE TABLE statement
allows AVG_ROW_LENGTH and MAX_ROWS options.
See section 13.2.6 CREATE TABLE Syntax.
You can also change these options with ALTER TABLE after the table has
been created, to increase the table's maximum allowable size.
See section 13.2.2 ALTER TABLE Syntax.
Other ways to work around file-size limits for MyISAM tables are as
follows:
myisampack to
compress it. myisampack usually compresses a table by at
least 50%, so you can have, in effect, much bigger tables.
myisampack also can merge multiple tables into a single table.
See section 8.2 myisampack, the MySQL Compressed Read-only Table Generator.
MERGE library that allows
you to handle a collection of MyISAM tables that have identical
structure as a single MERGE table.
See section 14.2 The MERGE Storage Engine.
The MySQL Server itself has no problems with Year 2000 (Y2K) compliance:
2037 for TIMESTAMP values. For DATE and DATETIME
values, dates through the year 9999 are accepted.
YEAR column type
can store years 0 and 1901 to 2155 in one byte and
display them using two or four digits.
All two-digit years are considered to be in the range
1970 to 2069, which means that if you store 01 in a
YEAR column, MySQL Server treats it as 2001.
The following simple demonstration illustrates that MySQL Server
has no problems with DATE or DATETIME values through the year
9999, and no problems with TIMESTAMP values until after the year 2030:
mysql> DROP TABLE IF EXISTS y2k;
Query OK, 0 rows affected (0.01 sec)
mysql> CREATE TABLE y2k (date DATE,
-> date_time DATETIME,
-> time_stamp TIMESTAMP);
Query OK, 0 rows affected (0.01 sec)
mysql> INSERT INTO y2k VALUES
-> ('1998-12-31','1998-12-31 23:59:59',19981231235959),
-> ('1999-01-01','1999-01-01 00:00:00',19990101000000),
-> ('1999-09-09','1999-09-09 23:59:59',19990909235959),
-> ('2000-01-01','2000-01-01 00:00:00',20000101000000),
-> ('2000-02-28','2000-02-28 00:00:00',20000228000000),
-> ('2000-02-29','2000-02-29 00:00:00',20000229000000),
-> ('2000-03-01','2000-03-01 00:00:00',20000301000000),
-> ('2000-12-31','2000-12-31 23:59:59',20001231235959),
-> ('2001-01-01','2001-01-01 00:00:00',20010101000000),
-> ('2004-12-31','2004-12-31 23:59:59',20041231235959),
-> ('2005-01-01','2005-01-01 00:00:00',20050101000000),
-> ('2030-01-01','2030-01-01 00:00:00',20300101000000),
-> ('2040-01-01','2040-01-01 00:00:00',20400101000000),
-> ('9999-12-31','9999-12-31 23:59:59',99991231235959);
Query OK, 14 rows affected (0.01 sec)
Records: 14 Duplicates: 0 Warnings: 2
mysql> SELECT * FROM y2k;
+------------+---------------------+----------------+
| date | date_time | time_stamp |
+------------+---------------------+----------------+
| 1998-12-31 | 1998-12-31 23:59:59 | 19981231235959 |
| 1999-01-01 | 1999-01-01 00:00:00 | 19990101000000 |
| 1999-09-09 | 1999-09-09 23:59:59 | 19990909235959 |
| 2000-01-01 | 2000-01-01 00:00:00 | 20000101000000 |
| 2000-02-28 | 2000-02-28 00:00:00 | 20000228000000 |
| 2000-02-29 | 2000-02-29 00:00:00 | 20000229000000 |
| 2000-03-01 | 2000-03-01 00:00:00 | 20000301000000 |
| 2000-12-31 | 2000-12-31 23:59:59 | 20001231235959 |
| 2001-01-01 | 2001-01-01 00:00:00 | 20010101000000 |
| 2004-12-31 | 2004-12-31 23:59:59 | 20041231235959 |
| 2005-01-01 | 2005-01-01 00:00:00 | 20050101000000 |
| 2030-01-01 | 2030-01-01 00:00:00 | 20300101000000 |
| 2040-01-01 | 2040-01-01 00:00:00 | 00000000000000 |
| 9999-12-31 | 9999-12-31 23:59:59 | 00000000000000 |
+------------+---------------------+----------------+
14 rows in set (0.00 sec)
The final two TIMESTAMP column values are zero because the
year values (2040, 9999) exceed the TIMESTAMP maximum. The
TIMESTAMP data type, which is used to store the current time,
supports values that range from 19700101000000 to
20300101000000 on 32-bit machines (signed value). On 64-bit
machines, TIMESTAMP handles values up to 2106 (unsigned
value).
Although MySQL Server itself is Y2K-safe, you may run into
problems if you use it with applications that are not Y2K-safe.
For example, many old applications store or manipulate years using
two-digit values (which are ambiguous) rather than four-digit values.
This problem may be compounded by applications that use
values such as 00 or 99 as ``missing'' value indicators.
Unfortunately, these problems may be difficult to fix because different
applications may be written by different programmers, each of whom may
use a different set of conventions and date-handling functions.
Thus, even though MySQL Server has no Y2K problems, it is the application's responsibility to provide unambiguous input. See section 11.3.4 Y2K Issues and Date Types for MySQL Server's rules for dealing with ambiguous date input data that contains two-digit year values.
This section provides a snapshot of the MySQL development roadmap, including major features implemented or planned for MySQL 4.0, 4.1, 5.0, and 5.1. The following sections provide information for each release series.
The current production release series is MySQL 4.1, which was declared stable for production use as of Version 4.1.7, released in October 2004. The previous production release series is MySQL 4.0, which was declared stable for production use as of Version 4.0.12, released in March 2003. Production status means that future 4.1 and 4.0 development is limited only to bugfixes. For the older MySQL 3.23 series, only critical bugfixes are made.
Active MySQL development currently is taking place in the MySQL 5.0 release series, this means that new features are being added there. MySQL 5.0 is available in alpha status.
Before upgrading from one release series to the next, please see the notes at section 2.10 Upgrading MySQL.
Plans for some of the most requested features are summarized in the following table.
| Feature | MySQL Series |
| Unions | 4.0 |
| Subqueries | 4.1 |
| R-trees | 4.1 (for MyISAM tables)
|
| Stored procedures | 5.0 |
| Views | 5.0 |
| Cursors | 5.0 |
| Foreign keys | 5.1 (implemented in 3.23 for InnoDB)
|
| Triggers | 5.0 and 5.1 |
| Full outer join | 5.1 |
| Constraints | 5.1 |
MySQL Server 4.0 is available in production status.
MySQL 4.0 is available for download at http://dev.mysql.com/ and from our mirrors. MySQL 4.0 has been tested by a large number of users and is in production use at many large sites.
The major new features of MySQL Server 4.0 are geared toward our existing business and community users, enhancing the MySQL database software as the solution for mission-critical, heavy-load database systems. Other new features target the users of embedded databases.
INSERT statements, searching on
packed indexes, full-text searching (using FULLTEXT indexes), and
COUNT(DISTINCT).
InnoDB storage engine as standard
InnoDB storage engine is offered as a standard feature of the
MySQL server. This means full support for ACID transactions, foreign
keys with cascading UPDATE and DELETE, and row-level locking
are standard features.
See section 15 The InnoDB Storage Engine.
FULLTEXT search properties of MySQL Server 4.0 enables
FULLTEXT indexing of large text masses with both binary
and natural-language searching logic. You can customize minimal word
length and define your own stop word lists in any human language,
enabling a new set of applications to be built with MySQL Server.
See section 12.6 Full-Text Search Functions.
UNION statement, a standard SQL feature.
TRUNCATE TABLE (as in Oracle).
latin1_de, which ensures that the
German sorting order sorts words with umlauts in the same order
as do German telephone books.
mysqld parameters (startup options) can be set without taking
down the server. This is a convenient feature for database administrators
(DBAs).
See section 13.5.3 SET Syntax.
DELETE and UPDATE statements have been added.
MyISAM storage engine supports symbolic
linking at the table level (and not just the database level as before).
SQL_CALC_FOUND_ROWS and FOUND_ROWS() are new functions that make it
possible to find out the number of rows a SELECT query that includes a
LIMIT clause would have returned without that clause.
The news section of this manual includes a more in-depth list of features. See section D.3 Changes in release 4.0.x (Production).
The libmysqld embedded server library makes MySQL Server suitable for
a vastly expanded realm of applications. By using this library, developers can
embed MySQL Server into various applications and electronics devices, where
the end user has no knowledge of there actually being an underlying
database. Embedded MySQL Server is ideal for use behind
the scenes in Internet appliances, public kiosks, turnkey
hardware/software combination units, high performance Internet
servers, self-contained databases distributed on CD-ROM, and so on.
Many users of libmysqld benefit from the MySQL
Dual Licensing. For those not wishing to be bound by the GPL,
the software is also made available under a commercial license.
See http://www.mysql.com/company/legal/licensing/ for more information
on the licensing policy of MySQL AB.
The embedded MySQL library uses the same interface as the normal
client library, so it is convenient and easy to use.
See section 22.2.16 libmysqld, the Embedded MySQL Server Library.
On Windows there are two different libraries:
libmysqld.lib | Dynamic library for threaded applications. |
mysqldemb.lib | Static library for not threaded applications. |
MySQL Server 4.0 laid the foundation for new features implemented in MySQL 4.1, such as subqueries and Unicode support, and for the work on stored procedures being done in version 5.0. These features come at the top of the wish list of many of our customers. Well-known for its stability, speed, and ease of use, MySQL Server is able to fulfill the requirement checklists of very demanding buyers.
MySQL Server 4.1 is currently in production status, and binaries are available for download at http://dev.mysql.com/downloads/mysql/4.1.html. All binary releases pass our extensive test suite without any errors on the platforms on which we test. See section D.2 Changes in release 4.1.x (Production).
For those wishing to use the most recent development source for MySQL 4.1, we also make our BitKeeper repositories publicly available. See section 2.8.3 Installing from the Development Source Tree.
This section lists features implemented in MySQL 4.1. Features that are available in MySQL 5.0 are described in section C.1 New Features Planned for 5.0.
SELECT statement nested within another statement.
A ``derived table'' (an unnamed view) is a subquery in the FROM clause
of another statement.
See section 13.1.8 Subquery Syntax.
BTREE indexing is supported for HEAP tables,
significantly improving response time for non-exact searches.
CREATE TABLE tbl_name2 LIKE tbl_name1 allows you to create, with
a single statement, a new table with a structure exactly like that of an
existing table.
MyISAM storage engine supports
OpenGIS spatial types for storing geographical data.
See section 18 Spatial Extensions in MySQL.
SHOW WARNINGS shows warnings for the last command.
See section 13.5.4.20 SHOW WARNINGS Syntax.
utf8 and ucs2 character sets.
HELP command that can be used
to get help information for SQL statements.
The advantage of having this information on the server side is that the
information is always applicable to the particular server version that you
actually are using.
Because this information is available by issuing an SQL statement, any client
can be written to access it.
For example, the help command of the mysql command-line client
has been modified to have this capability.
INSERT ... ON DUPLICATE KEY UPDATE ... syntax has been
implemented. This allows you to UPDATE an existing row if the
INSERT would have caused a duplicate in a PRIMARY or
UNIQUE index.
See section 13.1.4 INSERT Syntax.
GROUP_CONCAT()
adds the extremely useful capability of concatenating column values from
grouped rows into a single result string.
See section 12.9 Functions and Modifiers for Use with GROUP BY Clauses.
The news section of this manual includes a more in-depth list of features. See section D.2 Changes in release 4.1.x (Production).
New development for MySQL is focused on the 5.0 release, featuring stored procedures, views (including updatable views), rudimentary triggers, and other new features. See section C.1 New Features Planned for 5.0.
For those wishing to take a look at the bleeding edge of MySQL development, we make our BitKeeper repository for MySQL version 5.0 publicly available. See section 2.8.3 Installing from the Development Source Tree. As of December 2003, binary builds of version 5.0 have also been available.
This section introduces the MySQL mailing lists and provides guidelines as to how the lists should be used. When you subscribe to a mailing list, you receive all postings to the list as email messages. You can also send your own questions and answers to the list.
To subscribe to or unsubscribe from any of the mailing lists described in this section, visit http://lists.mysql.com/. For most of them, you can select the regular version of the list where you get individual messages, or a digest version where you get one large message per day.
Please do not send messages about subscribing or unsubscribing to any of the mailing lists, because such messages are distributed automatically to thousands of other users.
Your local site may have many subscribers to a MySQL mailing list.
If so, the site may have a local mailing list, so that messages sent from
lists.mysql.com to your site are propagated to the local list. In such
cases, please contact your system administrator to be added to or dropped
from the local MySQL list.
If you wish to have traffic for a mailing list go to a separate mailbox in
your mail program, set up a filter based on the message headers. You can
use either the List-ID: or Delivered-To: headers to identify
list messages.
The MySQL mailing lists are as follows:
announce
mysql
bugs
internals
mysqldoc
benchmarks
packagers
java
win32
myodbc
gui-tools
MySQL
Administrator and the MySQL Control Center graphical client.
cluster
dotnet
plusplus
perl
DBD::mysql.
If you're unable to get an answer to your questions from a MySQL mailing list, one option is to purchase support from MySQL AB. This puts you in direct contact with MySQL developers.
The following table shows some MySQL mailing lists in languages other than English. These lists are not operated by MySQL AB.
mysql-france-subscribe@yahoogroups.com
list@tinc.net
subscribe mysql your@email.address to this list.
mysql-de-request@lists.4t2.com
subscribe mysql-de your@email.address to this list.
You can find information about this mailing list at
http://www.4t2.com/mysql/.
mysql-br-request@listas.linkway.com.br
subscribe mysql-br your@email.address to this list.
mysql-alta@elistas.net
subscribe mysql your@email.address to this list.
Before posting a bug report or question, please do the following:
If you can't find an answer in the manual or the archives, check with your local MySQL expert. If you still can't find an answer to your question, please follow the guidelines on sending mail to a MySQL mailing list, outlined in the next section, before contacting us.
The normal place to report bugs is http://bugs.mysql.com/, which is the address for our bugs database. This database is public, and can be browsed and searched by anyone. If you log in to the system, you can enter new reports.
Writing a good bug report takes patience, but doing it right the first time saves time both for us and for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the bug in the next release. This section helps you write your report correctly so that you don't waste your time doing things that may not help us much or at all.
We encourage everyone to use the mysqlbug script to generate a bug
report (or a report about any problem). mysqlbug can be
found in the `scripts' directory (source distribution) and in the
`bin' directory under your MySQL installation directory (binary distribution).
If you are unable to use mysqlbug (for example, if you are running
on Windows), it is still vital that you include all the necessary information
noted in this section (most importantly, a description of the operating system
and the MySQL version).
The mysqlbug script helps you generate a report by determining much
of the following information automatically, but if something important is
missing, please include it with your message. Please read this section
carefully and make sure that all the information described here is included
in your report.
Preferably, you should test the problem using the latest production or
development version of MySQL Server before posting. Anyone should be
able to repeat the bug by just using mysql test < script_file on the
included test case or by running the shell or Perl script that is included in the
bug report.
All bugs posted in the bugs database at http://bugs.mysql.com/ are corrected or documented in the next MySQL release. If only minor code changes are needed to correct a problem, we may also post a patch that fixes the problem.
If you have found a sensitive security bug in MySQL, you can send email to security@mysql.com.
If you have a repeatable bug report, please report it to the bugs
database at http://bugs.mysql.com/. Note that even in this case
it's good to run the mysqlbug script first to find information
about your system. Any bug that we are able to repeat has a high chance
of being fixed in the next MySQL release.
To report other problems, you can use one of the MySQL mailing lists.
Remember that it is possible for us to respond to a message containing too much information, but not to one containing too little. People often omit facts because they think they know the cause of a problem and assume that some details don't matter. A good principle is this: If you are in doubt about stating something, state it. It is faster and less troublesome to write a couple more lines in your report than to wait longer for the answer if we must ask you to provide information that was missing from the initial report.
The most common errors made in bug reports are (a) not including the version number of the MySQL distribution used, and (b) not fully describing the platform on which the MySQL server is installed (including the platform type and version number). This is highly relevant information, and in 99 cases out of 100, the bug report is useless without it. Very often we get questions like, ``Why doesn't this work for me?'' Then we find that the feature requested wasn't implemented in that MySQL version, or that a bug described in a report has been fixed in newer MySQL versions. Sometimes the error is platform-dependent; in such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform.
If you compiled MySQL from source, remember also to provide information about your compiler, if it is related to the problem. Often people find bugs in compilers and think the problem is MySQL-related. Most compilers are under development all the time and become better version by version. To determine whether your problem depends on your compiler, we need to know what compiler you use. Note that every compiling problem should be regarded as a bug and reported accordingly.
It is most helpful when a good description of the problem is included in the bug report. That is, give a good example of everything you did that led to the problem and describe, in exact detail, the problem itself. The best reports are those that include a full example showing how to reproduce the bug or problem. See section E.1.6 Making a Test Case If You Experience Table Corruption.
If a program produces an error message, it is very important to include the message in your report. If we try to search for something from the archives using programs, it is better that the error message reported exactly matches the one that the program produces. (Even the lettercase should be observed.) You should never try to reproduce from memory what the error message was; instead, copy and paste the entire message into your report.
If you have a problem with Connector/ODBC (MyODBC), please try to generate a trace file and send it with your report. See section 23.1.1.9 How to Report MyODBC Problems or Bugs.
Please remember that many of the people who read your report
do so using an 80-column display. When generating reports or examples
using the mysql command-line tool, you should therefore use
the --vertical option (or the \G statement terminator)
for output that would exceed the available width for such a display
(for example, with the EXPLAIN SELECT statement; see the
example later in this section).
Please include the following information in your report:
mysqladmin version. The mysqladmin
program can be found in the `bin' directory under your MySQL
installation directory.
uname -a.
mysqld died, you should also report the query that crashed
mysqld. You can usually find this out by running mysqld with
query logging enabled, and then looking in the log after mysqld crashes
See section E.1.5 Using Log Files to Find Cause of Errors in mysqld.
mysqldump --no-data db_name tbl_name. This is very easy
to do and is a powerful way to get information about any table in a database.
The information helps us create a situation matching the one you have experienced.
SELECT statements, you
should always include the output of EXPLAIN SELECT ..., and at
least the number of rows that the SELECT statement produces. You
should also include the output from SHOW CREATE TABLE tbl_name
for each involved table. The more information you give about your
situation, the more likely it is that someone can help you.
The following is an example of a very good bug report. It should be posted
with the mysqlbug script. The example uses the mysql
command-line tool. Note the use of the \G statement terminator for
statements whose output width would otherwise exceed that of an 80-column
display device.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
including the time taken to run the query>
mysql> SHOW STATUS;
<output from SHOW STATUS>
mysqld, try to provide an
input script that reproduces the anomaly. This script should include any
necessary source files. The more closely the script can reproduce your
situation, the better. If you can make a reproducible test case, you should
post it on http://bugs.mysql.com/ for high-priority treatment.
If you can't provide a script, you should at least include the output
from mysqladmin variables extended-status processlist in your mail to
provide some information on how your system is performing.
mysqldump and create a `README' file
that describes your problem.
Create a compressed archive of your files using
tar and gzip or zip, and use FTP to transfer the
archive to ftp://ftp.mysql.com/pub/mysql/upload/. Then enter
the problem into our bugs database at http://bugs.mysql.com/.
mysqld
server as well as the options that you use to run any MySQL client programs.
The options to programs such as mysqld and mysql, and to the
configure script, are often keys to answers and are very relevant.
It is never a bad idea to include them. If you use any modules, such
as Perl or PHP, please include the version numbers of those as well.
mysqlaccess, the output of mysqladmin reload, and all
the error messages you get when trying to connect. When you test your
privileges, you should first run mysqlaccess. After this, execute
mysqladmin reload version and try to connect with the program that
gives you trouble. mysqlaccess can be found in the `bin'
directory under your MySQL installation directory.
parse error, please check your syntax closely. If
you can't find something wrong with it, it's extremely likely that your
current version of MySQL Server doesn't support the syntax you are
using. If you are using the current version and the manual at
http://dev.mysql.com/doc/ doesn't cover the
syntax you are using, MySQL Server doesn't support your query. In this
case, your only options are to implement the syntax yourself or email
licensing@mysql.com and ask for an offer to implement it.
If the manual covers the syntax you are using, but you have an older version
of MySQL Server, you should check the MySQL change history to see
when the syntax was implemented. In this case, you have the option of
upgrading to a newer version of MySQL Server. See section D MySQL Change History.
CHECK TABLE and REPAIR TABLE
or with myisamchk.
See section 5 Database Administration.
If you are running Windows, please verify that lower_case_table_names
is 1 or 2 with SHOW VARIABLES LIKE 'lower_case_table_names'.
mysqld should never crash a table if nothing killed it in the
middle of an update. If you can find the cause of mysqld dying,
it's much easier for us to provide you with a fix for the problem.
See section A.1 How to Determine What Is Causing a Problem.
If you are a support customer, please cross-post the bug report to mysql-support@mysql.com for higher-priority treatment, as well as to the appropriate mailing list to see whether someone else has experienced (and perhaps solved) the problem.
For information on reporting bugs in MyODBC, see section 23.1.1.9 How to Report MyODBC Problems or Bugs.
For solutions to some common problems, see section A Problems and Common Errors.
When answers are sent to you individually and not to the mailing list, it is considered good etiquette to summarize the answers and send the summary to the mailing list so that others may have the benefit of responses you received that helped you solve your problem.
If you consider your answer to have broad interest, you may want to post it to the mailing list instead of replying directly to the individual who asked. Try to make your answer general enough that people other than the original poster may benefit from it. When you post to the list, please make sure that your answer is not a duplication of a previous answer.
Try to summarize the essential part of the question in your reply; don't feel obliged to quote the entire original message.
Please don't post mail messages from your browser with HTML mode turned on. Many users don't read mail with a browser.
In addition to the various MySQL mailing lists, you can find experienced
community people on IRC (Internet Relay Chat).
These are the best networks/channels currently known to us:
#mysql
Primarily MySQL questions, but other database and general SQL questions are welcome.
Questions about PHP, Perl or C in combination with MySQL are also common.
If you are looking for IRC client software to connect to an IRC network,
take a look at X-Chat (http://www.xchat.org/).
X-Chat (GPL licensed) is available for Unix as well as for Windows platforms
(a free Windows build of X-Chat is available at http://www.silverex.org/download/).
The latest community support resource are the forums at http://forums.mysql.com.
There are a variety of forums available, grouped in the following general categories:
This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server has many extensions to the SQL standard, and here you can find out what they are and how to use them. You can also find information about functionality missing from MySQL Server, and how to work around some differences.
The SQL standard has been evolving since 1986 and several versions exist. In this manual, ``SQL-92'' refers to the standard released in 1992, ``SQL:1999'' refers to the standard released in 1999, and ``SQL:2003'' refers to the current version of the standard. We use the phrase ``the SQL standard'' to mean the current version of the SQL Standard at any time.
Our goal is to not restrict MySQL Server usability for any usage without a very good reason for doing so. Even if we don't have the resources to perform development for every possible use, we are always willing to help and offer suggestions to people who are trying to use MySQL Server in new territories.
One of our main goals with the product is to continue to work toward
compliance with the SQL standard, but without sacrificing speed or reliability.
We are not afraid to add extensions to SQL or support for non-SQL
features if this greatly increases the usability of MySQL Server for a large
segment of our user base.
The HANDLER interface in MySQL Server 4.0 is an example of this
strategy. See section 13.1.3 HANDLER Syntax.
We continue to support transactional and non-transactional databases to satisfy both mission-critical 24/7 usage and heavy Web or logging usage.
MySQL Server was originally designed to work with medium size databases (10-100 million rows, or about 100MB per table) on small computer systems. Today MySQL Server handles terabyte-size databases, but the code can also be compiled in a reduced version suitable for hand-held and embedded devices. The compact design of the MySQL server makes development in both directions possible without any conflicts in the source tree.
Currently, we are not targeting realtime support, although MySQL replication capabilities offer significant functionality.
Database cluster support exists through third-party clustering solutions as well as the integration of our acquired NDB Cluster technology, available from version 4.1.2. See section 16 MySQL Cluster.
We are also looking at providing XML support in the database server.
We are aiming toward supporting the full ANSI/ISO SQL standard, but without making concessions to speed and quality of the code.
ODBC levels 0-3.51.
The MySQL server can operate in different SQL modes, and can apply these modes differentially for different clients. This allows an application to tailor server operation to its own requirements.
Modes define what SQL syntax MySQL should support and what kind of validation checks it should perform on the data. This makes it easier to use MySQL in a lot of different environments and to use MySQL together with other database servers.
You can set the default SQL mode by starting mysqld with the
--sql-mode="modes" option. Beginning with MySQL 4.1, you can also
change the mode after startup time by setting the sql_mode variable
with a SET [SESSION|GLOBAL] sql_mode='modes' statement.
For more information on setting the server mode, see section 5.2.2 The Server SQL Mode.
You can tell mysqld to use the ANSI mode with the --ansi
startup option. See section 5.2.1 mysqld Command-Line Options.
Running the server in ANSI mode is the same as starting it with these options
(specify the --sql_mode value on a single line):
--transaction-isolation=SERIALIZABLE --sql-mode=REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES, IGNORE_SPACE
In MySQL 4.1, you can achieve the same effect with these two statements
(specify the sql_mode value on a single line):
SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE; SET GLOBAL sql_mode = 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES, IGNORE_SPACE';
See section 1.5.2 Selecting SQL Modes.
In MySQL 4.1.1, the sql_mode options shown can be also be set with
this statement:
SET GLOBAL sql_mode='ansi';
In this case, the value of the sql_mode variable is set to all
options that are relevant for ANSI mode. You can check the result like this:
mysql> SET GLOBAL sql_mode='ansi';
mysql> SELECT @@global.sql_mode;
-> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,
IGNORE_SPACE,ANSI';
MySQL Server includes some extensions that you probably won't find in
other SQL databases. Be warned that if you use them, your code won't be
portable to other SQL servers. In some cases, you can write code that
includes MySQL extensions, but is still portable, by using comments
of the form /*! ... */. In this case, MySQL Server parses and
execute the code within the comment as it would any other MySQL
statement, but other SQL servers will ignore the extensions. For example:
SELECT /*! STRAIGHT_JOIN */ col_name FROM table1,table2 WHERE ...
If you add a version number after the `!' character, the syntax within the comment is executed only if the MySQL version is equal to or newer than the specified version number:
CREATE /*!32302 TEMPORARY */ TABLE t (a INT);
This means that if you have Version 3.23.02 or newer, MySQL
Server uses the TEMPORARY keyword.
The following descriptions list MySQL extensions, organized by category.
MyISAM or ISAM storage engines.
For example, to rename a MyISAM table, rename the `.MYD',
`.MYI', and `.frm' files to which the table corresponds.
User space.
MySQL Server doesn't support tablespaces such as used in statements like this:
CREATE TABLE ralph.my_table...IN my_tablespace.
ANALYZE TABLE, CHECK TABLE, OPTIMIZE TABLE, and
REPAIR TABLE statements.
CREATE DATABASE and DROP DATABASE statements.
See section 13.2.4 CREATE DATABASE Syntax.
DO statement.
EXPLAIN SELECT to get a description of how tables are joined.
FLUSH and RESET statements.
SET statement. See section 13.5.3 SET Syntax.
SHOW statement.
See section 13.5.4 SHOW Syntax.
LOAD DATA INFILE. In many cases, this syntax is compatible with
Oracle's LOAD DATA INFILE. See section 13.1.5 LOAD DATA INFILE Syntax.
RENAME TABLE. See section 13.2.12 RENAME TABLE Syntax.
REPLACE instead of DELETE + INSERT.
See section 13.1.6 REPLACE Syntax.
CHANGE col_name, DROP col_name, or DROP
INDEX, IGNORE or RENAME in an ALTER TABLE
statement.
Use of multiple ADD, ALTER, DROP, or CHANGE
clauses in an ALTER TABLE statement.
See section 13.2.2 ALTER TABLE Syntax.
INDEX or KEY in a CREATE TABLE
statement. See section 13.2.6 CREATE TABLE Syntax.
TEMPORARY or IF NOT EXISTS with CREATE TABLE.
IF EXISTS with DROP TABLE.
DROP TABLE statement.
ORDER BY and LIMIT clauses of the UPDATE and
DELETE statements.
INSERT INTO ... SET col_name = ... syntax.
DELAYED clause of the INSERT and REPLACE
statements.
LOW_PRIORITY clause of the INSERT, REPLACE,
DELETE, and UPDATE statements.
INTO OUTFILE and STRAIGHT_JOIN in a SELECT
statement. See section 13.1.7 SELECT Syntax.
SQL_SMALL_RESULT option in a SELECT statement.
GROUP BY part.
This gives better performance for some very specific, but quite normal
queries.
See section 12.9 Functions and Modifiers for Use with GROUP BY Clauses.
ASC and DESC with GROUP BY.
:= assignment
operator:
mysql> SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg
-> FROM test_table;
mysql> SELECT @t1:=(@t2:=1)+@t3:=4,@t1,@t2,@t3;
MEDIUMINT, SET, ENUM, and the
different BLOB and TEXT types.
AUTO_INCREMENT, BINARY, NULL,
UNSIGNED, and ZEROFILL.
|| and && operators to mean
logical OR and AND, as in the C programming language. In MySQL Server,
|| and OR are synonyms, as are && and AND.
Because of this nice syntax, MySQL Server doesn't support
the standard SQL || operator for string concatenation; use
CONCAT() instead. Because CONCAT() takes any number
of arguments, it's easy to convert use of the || operator to
MySQL Server.
COUNT(DISTINCT list) where list has more than one element.
BINARY attribute or use the BINARY cast, which causes
comparisons to be done using the underlying character code values rather
then a lexical ordering.
% operator is a synonym for MOD(). That is,
N % M is equivalent to MOD(N,M). % is supported
for C programmers and for compatibility with PostgreSQL.
=, <>, <= ,<, >=,>,
<<, >>, <=>, AND, OR, or LIKE
operators may be used in column comparisons to the left of the
FROM in SELECT statements. For example:
mysql> SELECT col1=1 AND col2=2 FROM tbl_name;
LAST_INSERT_ID() function that returns the most recent
AUTO_INCREMENT value.
See section 12.8.3 Information Functions.
LIKE is allowed on numeric columns.
REGEXP and NOT REGEXP extended regular expression
operators.
CONCAT() or CHAR() with one argument or more than two
arguments. (In MySQL Server, these functions can take any number of
arguments.)
BIT_COUNT(), CASE, ELT(),
FROM_DAYS(), FORMAT(), IF(), PASSWORD(),
ENCRYPT(), MD5(), ENCODE(), DECODE(),
PERIOD_ADD(), PERIOD_DIFF(), TO_DAYS(), and
WEEKDAY() functions.
TRIM() to trim substrings. Standard SQL supports removal
of single characters only.
GROUP BY functions STD(), BIT_OR(),
BIT_AND(), BIT_XOR(), and GROUP_CONCAT().
See section 12.9 Functions and Modifiers for Use with GROUP BY Clauses.
For a prioritized list indicating when new extensions are added to MySQL Server, you should consult the online MySQL TODO list at http://dev.mysql.com/doc/mysql/en/TODO.html. That is the latest version of the TODO list in this manual. See section C MySQL and the Future (the TODO).
We try to make MySQL Server follow the ANSI SQL standard and the ODBC SQL standard, but MySQL Server performs operations differently in some cases:
VARCHAR columns, trailing spaces are removed when the value is
stored. (Fixed in MySQL 5.0.3). See section 1.5.7 Known Errors and Design Deficiencies in MySQL.
CHAR columns are silently converted to VARCHAR
columns when you define a table or alter its structure. (Fixed in MySQL 5.0.3).
See section 13.2.6.1 Silent Column Specification Changes.
REVOKE statement to revoke
privileges for a table. See section 13.5.1.3 GRANT and REVOKE Syntax.
CAST() function does not support cast to REAL or
BIGINT. See section 12.7 Cast Functions and Operators.
HAVING clause in a SELECT
statement be able to refer to columns in the GROUP BY clause. This
cannot be done before MySQL 5.0.2.
MySQL 4.1 supports subqueries and derived tables.
A ``subquery'' is a SELECT statement nested within another statement.
A ``derived table'' (an unnamed view) is a subquery in the FROM clause
of another statement.
See section 13.1.8 Subquery Syntax.
For MySQL versions older than 4.1, most subqueries can be rewritten using joins or other methods. See section 13.1.8.11 Rewriting Subqueries as Joins for Earlier MySQL Versions for examples that show how to do this.
SELECT INTO TABLE
MySQL Server doesn't support the Sybase SQL extension:
SELECT ... INTO TABLE .... Instead, MySQL Server supports the
standard SQL syntax INSERT INTO ... SELECT ..., which is basically
the same thing. See section 13.1.4.1 INSERT ... SELECT Syntax.
INSERT INTO tbl_temp2 (fld_id)
SELECT tbl_temp1.fld_order_id
FROM tbl_temp1 WHERE tbl_temp1.fld_order_id > 100;
Alternatively, you can use SELECT INTO OUTFILE ... or
CREATE TABLE ... SELECT.
From version 5.0, MySQL supports SELECT ... INTO with user
variables. The same syntax may also be used inside stored procedures using
cursors and local variables.
See section 19.2.9.3 SELECT ... INTO Statement.
MySQL Server (version 3.23-max and all versions 4.0 and above) supports
transactions with the InnoDB and BDB
transactional storage engines.
InnoDB provides full ACID compliance.
See section 14 MySQL Storage Engines and Table Types.
The other non-transactional storage engines in MySQL Server (such as
MyISAM) follow a different paradigm for data integrity called
``atomic operations.'' In transactional terms, MyISAM
tables effectively always operate in AUTOCOMMIT=1 mode.
Atomic operations often offer comparable integrity with higher performance.
With MySQL Server supporting both paradigms, you can decide whether your applications are best served by the speed of atomic operations or the use of transactional features. This choice can be made on a per-table basis.
As noted, the trade-off for transactional versus non-transactional table
types lies mostly in performance. Transactional tables have significantly
higher memory and diskspace requirements, and more CPU overhead.
On the other hand, transactional table types such as InnoDB also
offer many significant features. MySQL Server's modular design allows the
concurrent use of different storage engines to suit different
requirements and deliver optimum performance in all situations.
But how do you use the features of MySQL Server to maintain rigorous
integrity even with the non-transactional MyISAM tables, and how
do these features compare with the transactional table types?
ROLLBACK rather than
COMMIT in critical situations, transactions are more
convenient. Transactions also ensure that unfinished updates or
corrupting activities are not committed to the database; the server is
given the opportunity to do an automatic rollback and your database is
saved.
If you use non-transactional tables,
MySQL Server in almost all cases allows you to resolve potential problems
by including simple checks before updates and by running simple scripts
that check the databases for inconsistencies and automatically repair
or warn if such an inconsistency occurs. Note that just by using the
MySQL log or even adding one extra log, you can normally fix tables
perfectly with no data integrity loss.
LOCK TABLES or atomic updates, ensuring
that there are no automatic aborts from the server, which is
a common problem with transactional database systems.
The transactional paradigm has its benefits and its drawbacks. Many users and application developers depend on the ease with which they can code around problems where an abort appears to be, or is necessary. However, even if you are new to the atomic operations paradigm, or more familiar with transactions, do consider the speed benefit that non-transactional tables can offer on the order of three to five times the speed of the fastest and most optimally tuned transactional tables.
In situations where integrity is of highest importance, MySQL Server offers
transaction-level reliability and integrity even for non-transactional tables.
If you lock tables with LOCK TABLES, all updates stall
until integrity checks are made. If you obtain a READ LOCAL lock
(as opposed to a write lock) for a table that allows concurrent inserts at the
end of the table, reads are allowed, as are inserts by other clients.
The newly inserted records are not be seen by the
client that has the read lock until it releases the lock.
With INSERT DELAYED, you can queue inserts into a local
queue, until the locks are released, without having the client wait
for the insert to complete. See section 13.1.4.2 INSERT DELAYED Syntax.
``Atomic,'' in the sense that we mean it, is nothing magical. It only means that you can be sure that while each specific update is running, no other user can interfere with it, and there can never be an automatic rollback (which can happen with transactional tables if you are not very careful). MySQL Server also guarantees that there are no dirty reads.
Following are some techniques for working with non-transactional tables:
LOCK TABLES, and you don't need cursors to update
records on the fly.
ROLLBACK, you can use the following strategy:
LOCK TABLES to lock all the tables you want to access.
UNLOCK TABLES to release your locks.
WHERE clause in the UPDATE statement. If the record wasn't
updated, we give the client a message: ``Some of the data you have changed
has been changed by another user.'' Then we show the old row versus the new
row in a window so that the user can decide which version of the customer
record to use.
This gives us something that is similar to column locking but is actually
even better because we only update some of the columns, using values that
are relative to their current values. This means that typical UPDATE
statements look something like these:
UPDATE tablename SET pay_back=pay_back+125;
UPDATE customer
SET
customer_date='current_date',
address='new address',
phone='new phone',
money_owed_to_us=money_owed_to_us-125
WHERE
customer_id=id AND address='old address' AND phone='old phone';
This is very efficient and works even if another client
has changed the values in the pay_back or money_owed_to_us
columns.
LOCK TABLES and/or ROLLBACK
for the purpose of managing unique identifiers. This can be handled much
more efficiently without locking or rolling back by using an
AUTO_INCREMENT column and either the
LAST_INSERT_ID() SQL function or the mysql_insert_id() C API function.
See section 12.8.3 Information Functions.
See section 22.2.3.33 mysql_insert_id().
You can generally code around the need for row-level locking. Some situations
really do need it, and InnoDB tables support row-level locking. With
MyISAM tables, you can use a flag column in the table and do something
like the following:
UPDATE tbl_name SET row_flag=1 WHERE id=ID;MySQL returns
1 for the number of affected rows if the row was
found and row_flag wasn't 1 in the original row.
You can think of it as though MySQL Server changed the preceding query to:
UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1;
Stored procedures are implemented in MySQL version 5.0. See section 19 Stored Procedures and Functions.
Triggers are currently being implemented, with basic functionality in MySQL 5.0, with further development planned for MySQL 5.1.
In MySQL Server 3.23.44 and up, the InnoDB storage engine supports
checking of foreign key constraints, including CASCADE, ON
DELETE, and ON UPDATE. See section 15.7.4 FOREIGN KEY Constraints.
For storage engines other than InnoDB, MySQL Server parses the
FOREIGN KEY syntax in CREATE TABLE statements, but does not
use or store it. In the future, the implementation will be
extended to store this information in the table specification file so that it
may be retrieved by mysqldump and ODBC. At a later stage,
foreign key constraints will be implemented for MyISAM tables as well.
Foreign key enforcement offers several benefits to database developers:
Do keep in mind that these benefits come at the cost of additional overhead for the database server to perform the necessary checks. Additional checking by the server affects performance, which for some applications may be sufficiently undesirable as to be avoided if possible. (Some major commercial applications have coded the foreign-key logic at the application level for this reason.)
MySQL gives database developers the choice of which approach to use. If you
don't need foreign keys and want to avoid the overhead associated with
enforcing referential integrity, you can choose another table type instead,
such as MyISAM. (For example, the MyISAM storage engine offers
very fast performance for applications that perform only INSERT and
SELECT operations, because the inserts can be performed concurrently
with retrievals. See section 7.3.2 Table Locking Issues.)
If you choose not to take advantage of referential integrity checks, keep the following considerations in mind:
ON DELETE is the only referential integrity capability an
application needs, note that as of MySQL Server 4.0, you can use
multiple-table DELETE statements to delete rows from many
tables with a single statement. See section 13.1.1 DELETE Syntax.
ON DELETE is to add
the appropriate DELETE statement to your application when you
delete records from a table that has a foreign key. In practice, this is often
as quick as using foreign keys, and is more portable.
Be aware that the use of foreign keys can in some instances lead to problems:
FOREIGN KEY Constraints.
As of MySQL 4.1.1,
mysqldump generates dump files that take advantage of this
capability automatically when reloaded.)
Note that foreign keys in SQL are used to check and enforce referential
integrity, not to join tables. If you want to get results from multiple
tables from a SELECT statement, you do this by performing a join
between them:
SELECT * FROM t1, t2 WHERE t1.id = t2.id;
See section 13.1.7.1 JOIN Syntax. See section 3.6.6 Using Foreign Keys.
The FOREIGN KEY syntax without ON DELETE ... is often used
by ODBC applications to produce automatic WHERE clauses.
Views (including updatable views) are implemented in the 5.0 version
of MySQL Server. Views are available in binary releases from 5.0.1
and up.
See section 13.2.7 CREATE VIEW Syntax.
Views are useful for allowing users to access a set of relations (tables) as if it were a single table, and limiting their access to just that. Views can also be used to restrict access to rows (a subset of a particular table). For access control to columns, you can also use the sophisticated privilege system in MySQL Server. See section 5.5 The MySQL Access Privilege System.
In designing an implementation of views, our ambitious goal, as much as is possible within the confines of SQL, has been full compliance with ``Codd's Rule #6'' for relational database systems: ``All views that are theoretically updatable, should in practice also be updatable.''
Some other SQL databases use `--' to start comments.
MySQL Server uses `#' as the start comment character. You can also use
the C comment style /* this is a comment */ with MySQL Server.
See section 9.5 Comment Syntax.
MySQL Server 3.23.3 and above support the `--' comment style,
provided the comment is followed by a space (or by a control character such
as a newline). The requirement for a space is to prevent problems with
automatically generated SQL queries that have used something like the following code, where we automatically insert the value of the payment for
!payment!:
UPDATE account SET credit=credit-!payment!
Think about what happens if the value of payment is a negative value
such as -1:
UPDATE account SET credit=credit--1
credit--1 is a legal expression in SQL, but if -- is interpreted
as the start of a comment, part of the expression is discarded. The result is a
statement that has a completely different meaning than intended:
UPDATE account SET credit=credit
The statement produces no change in value at all! This illustrates that allowing comments to start with `--' can have serious consequences.
Using our implementation of this method of commenting in MySQL Server
3.23.3 and up, credit--1 is actually safe.
Another safe feature is that the mysql command-line client
removes all lines that start with `--'.
The following information is relevant only if you are running a MySQL version earlier than 3.23.3:
If you have an SQL program in a text file that contains `--'
comments, you should use the replace utility as follows to convert the
comments to use `#' characters:
shell> replace " --" " #" < text-file-with-funny-comments.sql \
| mysql db_name
instead of the usual:
shell> mysql db_name < text-file-with-funny-comments.sql
You can also edit the command file ``in place'' to change the `--' comments to `#' comments:
shell> replace " --" " #" -- text-file-with-funny-comments.sql
Change them back with this command:
shell> replace " #" " --" -- text-file-with-funny-comments.sql
MySQL allows you to work both with transactional tables that allow rollback and with non-transactional tables that do not. Because of this, constraint handling is a bit different in MySQL than in other databases. We must handle the case when you have inserted or updated a lot of rows in a non-transactional table for which changes cannot be rolled back when an error occurs.
The basic philosophy is that MySQL Server tries to produce an error for anything that it can detect while parsing a statement to be executed, and tries to recover from any errors that occur while executing the statement. We do this in most cases, but not yet for all. See section C.3 New Features Planned for the Near Future.
The options MySQL has when an error occurs are to stop the statement in the middle or to recover as well as possible from the problem and continue. By default, the server follows the latter course. This means, for example, that the server may coerce illegal values to the closest legal values.
Beginning with MySQL 5.0.2, several SQL mode options are available to provide greater control over how accepting to be of bad data values and whether to continue executing a statement or abort it when errors occur. Using these options, you can configure MySQL Server to act in a more traditional fashion that is like other DBMSs that reject improper input. The SQL mode can be set at runtime, which enables individual clients to select the behavior most appropriate for their requirements. See section 5.2.2 The Server SQL Mode.
The following sections describe what happens for the different types of constraints.
PRIMARY KEY and UNIQUE Index Constraints
Normally, an error occurs when you try to INSERT or UPDATE
a row that causes a primary key, unique key, or foreign key violation.
If you are using a transactional storage engine such as InnoDB, MySQL
automatically rolls back the statement. If you are using a non-transactional
storage engine, MySQL stops processing the statement at the row for which
the error occurred and leaves any remaining rows unprocessed.
If you wish to ignore such key violations, MySQL supports an IGNORE
keyword for INSERT and UPDATE. In this case, MySQL ignores
any key violations and continues processing with the next row.
See section 13.1.4 INSERT Syntax.
See section 13.1.10 UPDATE Syntax.
You can get information about the number of rows actually inserted or
updated with the mysql_info() C API function.
See section 22.2.3.31 mysql_info().
In MySQL 4.1 and up, you also can use the SHOW WARNINGS statement.
See section 13.5.4.20 SHOW WARNINGS Syntax.
For the moment, only InnoDB tables support foreign keys.
See section 15.7.4 FOREIGN KEY Constraints.
Foreign key support in MyISAM tables is scheduled for implementation
in MySQL 5.1.
Before MySQL 5.0.2, MySQL is forgiving of illegal or improper data values and coerces them to legal values for data entry. In MySQL 5.0.2 and up, that remains the default behavior, but you can select more traditional treatment of bad values such that the server rejects them and aborts the statement in which they occur. This section describes the default (forgiving) behavior of MySQL, as well as the newer strict SQL mode and how it differs.
The following holds true when you are not using strict mode.
If you insert an ``incorrect'' value into a column, such as a NULL
into a NOT NULL column or a too-large numeric value into a
numeric column, MySQL sets the column to the ``best possible value''
instead of producing an error:
NULL into a column that doesn't take NULL
values, MySQL Server stores 0 or '' (the empty string) instead.
DATE and
DATETIME columns (such as '2000-02-31' or '2000-02-00').
The idea is that it's not the job of the SQL server to validate dates. If
MySQL can store a date value and retrieve exactly the same value, MySQL
stores it as given. If the date is totally wrong (outside the server's
ability to store it), the special date value '0000-00-00' is stored
in the column instead.
INSERT statement specifies no value for a column, MySQL inserts
its default value if the column definition includes an explicit DEFAULT
clause. If the definition has no such DEFAULT clause, MySQL inserts
the implicit default value for the column data type. In general,
this is the empty string for string columns, 0 for numeric columns,
and '0000-00-00' for date columns. Implicit default values are
discussed in section 13.2.6 CREATE TABLE Syntax.
The reason for the preceding rules is that we can't check these conditions until the statement has begun executing. We can't just roll back if we encounter a problem after updating a few rows, because the storage engine may not support rollback. The option of terminating the statement is not that good; in this case, the update would be ``half done,'' which is probably the worst possible scenario. In this case, it's better to ``do the best you can'' and then continue as if nothing happened.
In MySQL 5.0.2 and up, you can select stricter treatment of input values by
using the STRICT_TRANS_TABLES or STRICT_ALL_TABLES SQL modes.
See section 5.2.2 The Server SQL Mode.
STRICT_TRANS_TABLES works like this: For transactional storage
engines, bad data values occurring anywhere in the statement causes
the to abort and roll back. For non-transactional storage engines,
the statement aborts if the error occurs in the first row to be inserted
or updated. (In this case, the statement can be regarded to leave the
table unchanged, just as for a transactional table.) Errors in rows
after the first do not abort the statement. Instead, bad data values
are adjusted and result in warnings rather than errors. In other words,
with STRICT_TRANS_TABLES, a wrong value causes MySQL to roll back,
if it can, all updates done so far.
For stricter checking, enable STRICT_ALL_TABLES. This is the same as
STRICT_TRANS_TABLES except that for non-transactional storage engines,
errors abort the statement even for bad data in rows following the first row.
This means that if an error occurs partway through a multiple-row insert or
update for a non-transactional table, a partial update results. Earlier rows
are inserted or updated, but those from the point of the error on are not.
To avoid this for non-transactional tables, either use single-row statements
or else use STRICT_TRANS_TABLES if conversion warnings rather than
errors are acceptable. To avoid problems in the first place, do not use
MySQL to check column content. It is safest (and often faster) to let the
application ensure that it passes only legal values to the database.
With either of the strict mode options, you can cause errors to be treated
as warnings by using INSERT IGNORE or UPDATE IGNORE.
ENUM and SET Constraints
ENUM and SET columns provide an efficient way to define columns
that can contain only a given set of values. However, before MySQL 5.0.2,
ENUM and SET are not real constraints. This is for the same
reasons that NOT NULL is not honored.
See section 1.5.6.2 Constraints on Invalid Data.
ENUM columns always have a default value. If you don't specify
a default value, then it is NULL for columns that can have
NULL, otherwise the first enumeration value is used as the default
value.
If you insert an incorrect value into an ENUM column or if you
force a value into an ENUM column with IGNORE, it is set
to the reserved enumeration value of 0, which is displayed as an
empty string in string context. See section 11.4.4 The ENUM Type.
If you insert an incorrect value into a SET column, the incorrect value
is ignored. For example, if the column can contain the values
'a', 'b', and 'c', an attempt to assign 'a,x,b,y'
results in a value of 'a,b'.
See section 11.4.5 The SET Type.
As of MySQL 5.0.2, you can configure the server to use strict SQL mode.
See section 5.2.2 The Server SQL Mode.
When strict mode is not enabled, values entered into ENUM and SET
columns are handled as just described for MySQL 4.x. However, if strict
mode is enabled, the definition of a ENUM or SET column does
act as a constraint on values entered into the column. An error occurs
for values that do not satisfy these conditions:
ENUM value must be one of those listed in the column definition, or
the internal numeric equivalent thereof. The value cannot be the error value
(that is, 0 or the empty string).
For a column defined as ENUM('a','b','c'), values such as '',
'd', and 'ax' are illegal and are rejected.
SET value must be the empty string or a value consisting of one or
more of the values listed in the column definition separated by commas.
For a column defined as SET('a','b','c'), values such as
'd', and 'a,b,c,d' are illegal and are rejected.
Errors for invalid values can be suppressed in strict mode if you use
INSERT IGNORE or UPDATE IGNORE. In this case, a warning is
generated rather than an error. For ENUM, the value is inserted as the
error member (0). For SET, the value is inserted as given except
that any invalid substrings are deleted. For example, 'a,x,b,y'
results in a value of 'a,b', as described earlier.
The following known errors or bugs are not fixed in MySQL 3.23 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as ``not fatal'' or ``bearable.''
LOCK TABLE to lock
multiple tables and then in the same connection use DROP TABLE to
drop one of them while another thread is trying to lock it. (To break the
deadlock, you can use KILL to terminate any of the threads involved.)
This issue is resolved as of MySQL 4.0.12.
SELECT MAX(key_column) FROM t1,t2,t3... where one of the tables are
empty doesn't return NULL but instead returns the maximum value for the
column. This issue is resolved as of MySQL 4.0.11.
DELETE FROM heap_table without a WHERE clause doesn't work on
a locked HEAP table.
The following known errors or bugs are not fixed in MySQL 4.0 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as ``not fatal'' or ``bearable.''
HAVING you can get a crash or wrong result if you use an alias to
a RAND() function. This is fixed in 4.1.10 but will not be fixed
in 4.0 because the fix 'may' cause side effects for some applications.
UNION, the first SELECT determines the type,
max_length, and NULL properties for the resulting
columns. This issue is resolved as of MySQL 4.1.1; the property values are
based on the rows from all UNION parts.
DELETE with many tables, you can't refer to tables to be
deleted through an alias. This is fixed as of MySQL 4.1.
UNION ALL and UNION DISTINCT in the same query.
If you use ALL for one UNION, it is used for all
of them. This is fixed as of MySQL 4.1.2. The rules for mixed UNION
types are given in section 13.1.7.2 UNION Syntax.
FLUSH TABLES WITH READ LOCK does not block CREATE TABLE, which
may cause a problem with the binary log position when
doing a full backup of tables and the binary log.
mysqldump --single-transaction --master-data behaved like
mysqldump --master-data, so the dump was a blocking one. This is fixed
starting from MySQL 4.1.8.
RPAD() function (or any function adding spaces to the
right) in a query that had to be resolved by using a temporary table, all
resulting strings had rightmost spaces removed (i.e. RPAD() did not
work).
The following known errors or bugs are not fixed in MySQL 4.1 because fixing them would involve changing a lot of code that could introduce other even worse bugs. The bugs are also classified as ``not fatal'' or ``bearable.''
VARCHAR and VARBINARY did not remember end space.
(Fixed in 5.0.3).
The following problems are known and fixing them is a high priority:
NULL value to a subquery using ALL/ANY/SOME
and the subquery returns an empty result, the comparison might evaluate
to the non-standard result of NULL rather than to TRUE or
FALSE. This will be fixed in MySQL 5.1.
IN is not as good as for =.
lower_case_table_names=2 (which enables
MySQL to remember the used case for databases and table names) MySQL
does not remember the used case for database
names for the function DATABASE() or in various logs (on case-insensitive systems).
FOREIGN KEY constraint doesn't work in replication because
the constraint may have another name on the slave.
REPLACE (and LOAD DATA with the REPLACE option) does not
trigger ON DELETE CASCADE.
DISTINCT with ORDER BY doesn't work inside GROUP_CONCAT()
if you don't use all and only those columns that are in the
DISTINCT list.
DROP TABLE command before the table is
used in the transaction itself. We plan to fix this by
having the DROP TABLE wait until the table is not used in any
transaction.
FLUSH TABLES WITH READ LOCK does not block COMMIT if the server
is running without binary logging, which may cause a problem (of consistency
between tables) when doing a full backup.
ANALYZE TABLE on a BDB table may in some cases make the table
unusable until you restart mysqld. If this happens, look for
errors of the following form in the MySQL error file:
001207 22:07:56 bdb: log_flush: LSN past current end-of-log
ALTER TABLE on a BDB table on which you are
running multiple-statement transactions until all those transactions complete.
(The transaction might be ignored.)
ANALYZE TABLE, OPTIMIZE TABLE, and REPAIR TABLE may
cause problems on tables for which you are using INSERT DELAYED.
LOCK TABLE ... and FLUSH TABLES ... doesn't
guarantee that there isn't a half-finished transaction in progress on the
table.
BDB tables are a bit slow to open. If you have many BDB tables
in a database, it takes a long time to use the mysql client on
the database if you are not using the -A option or if you are using
rehash. This is especially notable when you have a large table cache.
CREATE ... SELECT or
INSERT ... SELECT statements that
insert zero or NULL values into an AUTO_INCREMENT column.
DELETE if you are
deleting rows from a table that has foreign keys with ON DELETE
CASCADE properties.
REPLACE ... SELECT,
INSERT IGNORE ... SELECT if you have
duplicate key values in the inserted data.
ORDER BY
clause guaranteeing a deterministic order.
For example, for INSERT ... SELECT with no ORDER
BY, the SELECT may return rows in a different order
(which results in a row having different ranks, hence getting a
different number in the AUTO_INCREMENT column),
depending on the choices made by the optimizers on the master and
slave. A query is optimized differently on the master and slave only if:
OPTIMIZE TABLE was run on the master tables and not on
the slave tables. (To fix this, OPTIMIZE TABLE, ANALYZE TABLE,
and REPAIR TABLE are written to the binary log as of MySQL 4.1.1).
InnoDB on the master,
but MyISAM on the slave if the slave has less available disk
space.)
key_buffer_size, and so on) are different on
the master and slave.
mysqlbinlog|mysql.
The easiest way to avoid this problem in all cases is to add an
ORDER BY clause to
such non-deterministic queries to ensure that the rows are always
stored or modified in the same order.
In future MySQL versions, we will automatically add an ORDER BY
clause when needed.
The following problems are known and will be fixed in due time:
--log-bin=old_host_name-bin if you change your hostname to something
else. Another option is to just rename the old files to reflect your
hostname change (and if these are binary logs, you also need to edit the
binary log index file and fix the binlog names there). See section 5.2.1 mysqld Command-Line Options.
mysqlbinlog does not delete temporary files left after a
LOAD DATA INFILE command. See section 8.5 The mysqlbinlog Binary Log Utility.
RENAME doesn't work with TEMPORARY tables or tables used in a
MERGE table.
CHAR(255)) in table names, column names, or enumerations.
This is scheduled to be fixed in version 5.1 when we have new table
definition format files.
SET CHARACTER SET, you can't use translated
characters in database, table, and column names.
ESCAPE in LIKE
... ESCAPE.
DECIMAL column in which the same number is stored in
different formats (for example, +01.00, 1.00, 01.00),
GROUP BY may regard each value as a different value.
BLOB and TEXTvalues can't ``reliably'' be used in GROUP
BY or ORDER BY or DISTINCT. Only the first
max_sort_length bytes are used when comparing BLOB values in
these cases. The default value of max_sort_length value is 1024. It
can be changed at server startup time. As of MySQL 4.0.3, it can also be
changed at runtime. For older versions, a workaround for most cases is to
use a substring. For example:
SELECT DISTINCT LEFT(blob_col,2048) FROM tbl_name;
BIGINT or DOUBLE (both are
normally 64 bits long). Which precision you get depends on the function.
The general rule is that bit functions are done with BIGINT
precision, IF and ELT() with BIGINT or DOUBLE
precision, and the rest with DOUBLE precision. You should try to
avoid using unsigned long long values if they resolve to be bigger than
63 bits (9223372036854775807) for anything other than bit fields.
MySQL Server 4.0 has better BIGINT handling than 3.23.
ENUM and SET columns in one table.
MIN(), MAX(), and other aggregate functions, MySQL
currently compares ENUM and SET columns by their string
value rather than by the string's relative position in the set.
mysqld_safe redirects all messages from mysqld to the
mysqld log. One problem with this is that if you execute
mysqladmin refresh to close and reopen the log,
stdout and stderr are still redirected to the old log.
If you use --log extensively, you should edit mysqld_safe to
log to `host_name.err' instead of `host_name.log' so that you can
easily reclaim the space for the old log by deleting the old one and
executing mysqladmin refresh.
UPDATE statement, columns are updated from left to right. If
you refer to an updated column, you get the updated value instead of the
original value. For example, the following statement increments KEY
by 2, not 1:
mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1;
mysql> SELECT * FROM temp_table, temp_table AS t2; ERROR 1137: Can't reopen table: 'temp_table'
DISTINCT differently when you are using
``hidden'' columns in a join than when you are not. In a join, hidden
columns are counted as part of the result (even if they are not shown),
whereas in normal queries, hidden columns don't participate in the
DISTINCT comparison. We will probably change this in the future to
never compare the hidden columns when executing DISTINCT.
An example of this is:
SELECT DISTINCT mp3id FROM band_downloads
WHERE userid = 9 ORDER BY id DESC;
and
SELECT DISTINCT band_downloads.mp3id
FROM band_downloads,band_mp3
WHERE band_downloads.userid = 9
AND band_mp3.id = band_downloads.mp3id
ORDER BY band_downloads.id DESC;
In the second case, you might in MySQL Server 3.23.x get two identical rows in
the result set (because the values in the hidden id column may differ).
Note that this happens only for queries where you don't have the
ORDER BY columns in the result.
PROCEDURE on a query that returns an empty set,
in some cases the PROCEDURE does not transform the columns.
MERGE doesn't check whether the underlying
tables are of compatible types.
ALTER TABLE first to add a UNIQUE index to a
table used in a MERGE table and then to
add a normal index on the MERGE table, the key order is
different for the tables if there was an old key that was not unique in the
table. This is because ALTER TABLE puts UNIQUE indexes before
normal indexes to be able to detect duplicate keys as early as possible.
The following are known bugs in earlier versions of MySQL:
LOCK TABLE with WRITE.
FLUSH TABLES.
UPDATE that updated a key with
a WHERE on the same key may have failed because the key was used to
search for records and the same row may have been found multiple times:
UPDATE tbl_name SET KEY=KEY+1 WHERE KEY > 100;A workaround is to use:
UPDATE tbl_name SET KEY=KEY+1 WHERE KEY+0 > 100;This works because MySQL Server does not use an index on expressions in the
WHERE clause.
For information about platform-specific bugs, see the installation and porting instructions in section 2.12 Operating System-Specific Notes and section E Porting to Other Systems.
This chapter describes how to obtain and install MySQL:
GnuPG.
Before installing MySQL, you should do the following:
This section contains the information necessary to carry out these steps. After doing so, you can use the instructions in later sections of the chapter to install the distribution that you choose.
This section lists the operating systems on which you can expect to be able to run MySQL.
We use GNU Autoconf, so it is possible to port MySQL to all modern systems that have a C++ compiler and a working implementation of POSIX threads. (Thread support is needed for the server. To compile only the client code, the only requirement is a C++ compiler.) We use and develop the software ourselves primarily on Linux (SuSE and Red Hat), FreeBSD, and Sun Solaris (Versions 8 and 9).
MySQL has been reported to compile successfully on the following combinations of operating system and thread package. Note that for many operating systems, native thread support works only in the latest versions.
glibc 2.0.7+ for various
CPU architectures. See section 2.12.1 Linux Notes.
Not all platforms are equally well-suited for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the following factors:
pthread_mutex_lock() is too anxious to yield CPU time, this hurts
MySQL tremendously. If this issue is not taken care of, adding extra CPUs
actually makes MySQL slower.
Based on the preceding criteria, the best platforms for running
MySQL at this point are x86 with SuSE Linux using a 2.4 kernel, and
ReiserFS (or any similar Linux distribution) and SPARC with Solaris
(2.7-9). FreeBSD comes third, but we really hope it joins the top
club once the thread library is improved. We also hope that at some
point we is able to include into the top category all other platforms
on which MySQL currently compiles and runs okay, but not quite with the
same level of stability and performance. This requires some
effort on our part in cooperation with the developers of the operating system
and library components that MySQL depends on. If you are interested in
improving one of those components, are in a position to influence its
development, and need more detailed instructions on what MySQL
needs to run better, send an email message to the MySQL internals
mailing list.
See section 1.4.1.1 The MySQL Mailing Lists.
Please note that the purpose of the preceding comparison is not to say that one operating system is better or worse than another in general. We are talking only about choosing an OS for the specific purpose of running MySQL. With this in mind, the result of this comparison would be different if we considered more factors. In some cases, the reason one OS is better than the other could simply be that we have been able to put more effort into testing and optimizing for a particular platform. We are just stating our observations to help you decide which platform to use for running MySQL.
When preparing to install MySQL, you should decide which version to use. MySQL development occurs in several release series, and you can pick the one that best fits your needs. After deciding which version to install, you can choose a distribution format. Releases are available in binary or source format.
The first decision to make is whether you want to use a production (stable) release or a development release. In the MySQL development process, multiple release series co-exist, each at a different stage of maturity:
We don't believe in a complete freeze, as this also leaves out bugfixes and things that ``must be done.'' ``Somewhat frozen'' means that we may add small things that ``almost surely do not affect anything that's currently working.'' Naturally, relevant bugfixes from an earlier series propagate to later series.
Normally, if you are beginning to use MySQL for the first time or trying to port it to some system for which there is no binary distribution, we recommend going with the production release series. Currently this is MySQL 4.1. All MySQL releases, even those from development series, are checked with the MySQL benchmarks and an extensive test suite before being issued.
If you are running an old system and want to upgrade, but don't want to take the chance of having a non-seamless upgrade, you should upgrade to the latest version in the same release series you are using (where only the last part of the version number is newer than yours). We have tried to fix only fatal bugs and make small, relatively safe changes to that version.
If you want to use new features not present in the production release series, you can use a version from a development series. Note that development releases are not as stable as production releases.
If you want to use the very latest sources containing all current patches and bugfixes, you can use one of our BitKeeper repositories. These are not ``releases'' as such, but are available as previews of the code on which future releases are based.
The MySQL naming scheme uses release names that consist of three
numbers and a suffix; for example, mysql-4.1.2-alpha.
The numbers within the release name are interpreted like this:
4) is the major version and also describes the
file format. All Version 4 releases have the same file format.
1) is the release level.
Taken together, the major version and release level constitute the release
series number.
2) is the version number within the
release series. This is incremented for each new release. Usually you
want the latest version for the series you have chosen.
For each minor update, the last number in the version string is incremented. When there are major new features or minor incompatibilities with previous versions, the second number in the version string is incremented. When the file format changes, the first number is increased.
Release names also include a suffix to indicates the stability level of the release. Releases within a series progress through a set of suffixes to indicate how the stability level improves. The possible suffixes are:
alpha indicates that the release contains some large section of
new code that hasn't been 100% tested. Known bugs (usually there are none)
should be documented in the News section. See section D MySQL Change History. There are also new
commands and extensions in most alpha releases. Active development that
may involve major code changes can occur in an alpha release, but everything
is tested before issuing a release. For this reason, there should be
no known bugs in any MySQL release.
beta means that we are feature complete and that all new code has
been tested. No major new features that could cause corruption in old code
are added. There should be no known critical bugs. A version changes from
alpha to beta when there haven't been any reported fatal bugs within an
alpha version for at least a month and we have no plans to add any features
that could make any old command unreliable.
All API's, extern visible structures and columns for SQL commands will not
change during future beta, gamma or production releases.
gamma is a beta that has been around a while and seems to work fine.
Only minor fixes are added. This is what many other companies call a release.
MySQL uses a naming scheme that is slightly different from most other products. In general, it's relatively safe to use any version that has been out for a couple of weeks without being replaced with a new version within the release series.
All releases of MySQL are run through our standard tests and benchmarks to ensure that they are relatively safe to use. Because the standard tests are extended over time to check for all previously found bugs, the test suite keeps getting better.
All releases have been tested at least with:
crash-me test
Another test is that we use the newest MySQL version in our internal production environment, on at least one machine. We have more than 100GB of data to work with.
After choosing which version of MySQL to install, you should decide
whether to use a binary distribution or a source distribution. In
most cases, you should probably use a binary distribution, if one
exists for your platform. Binary distributions are available in native format
for many platforms, such as RPM files for Linux or DMG package installers for
Mac OS X. Distributions also are available as Zip archives or compressed
tar files.
Reasons to choose a binary distribution include the following:
-max suffix and is configured with the same options as
mysqld-max. See section 5.1.2 The mysqld-max Extended MySQL Server.
If you want to use the MySQL-Max RPM, you must first
install the standard MySQL-server RPM.
Under some circumstances, you may be better off installing MySQL from a source distribution:
mysqld with some extra features that are not
included in the standard binary distributions. Here is a list of the most
common extra options that you may want to use:
--with-innodb (default for MySQL 4.0 and up)
--with-berkeley-db (not available on all platforms)
--with-raid
--with-libwrap
--with-named-z-libs (this is done for some of the binaries)
--with-debug[=full]
mysqld without some features that are
included in the standard binary distributions. For example,
distributions normally are compiled with support for all character
sets. If you want a smaller MySQL server, you can recompile it with support
for only the character sets you need.
pgcc) or want to use compiler
options that are better optimized for your processor. Binary distributions
are compiled with options that should work on a variety of processors from
the same processor family.
MySQL is evolving quite rapidly here at MySQL AB and we want to share new developments with other MySQL users. We try to make a release when we have very useful features that others seem to have a need for.
We also try to help out users who request features that are easy to implement. We take note of what our licensed users want to have, and we especially take note of what our support customers want and try to help them out.
No one has to download a new release. The News section tells you if the new release has something you really want. See section D MySQL Change History.
We use the following policy when updating MySQL:
We put a lot of time and effort into making our releases bug-free. To our knowledge, we have not knowingly released a single MySQL version with any known ``fatal'' repeatable bugs. (A ``fatal'' bug is something that crashes MySQL under normal usage, produces incorrect answers for normal queries, or has a security problem.)
We have documented all open problems, bugs, and issues that are dependent on design decisions. See section 1.5.7 Known Errors and Design Deficiencies in MySQL.
Our aim is to fix everything that is fixable without risk of making a stable MySQL version less stable. In certain cases, this means we can fix an issue in the development versions, but not in the stable (production) version. Naturally, we document such issues so that users are aware of them.
Here is a description of how our build process works:
mysql and announce mailing
lists.
See section 1.4.1.1 The MySQL Mailing Lists.
The announcement message contains a list
of all changes to the release and any known problems with the release.
The Known Problems section in the release notes has been needed
for only a handful of releases.
'a' release for that
platform. Thanks to our large user base, problems are found quickly.
glibc library on one of our build
machines that took us a long time to track down.
As a service of MySQL AB, we provide a set of binary distributions of MySQL that are compiled on systems at our site or on systems where supporters of MySQL kindly have given us access to their machines.
In addition to the binaries provided in platform-specific package formats,
we offer binary distributions for a number of platforms in the form of
compressed tar files (.tar.gz files).
See section 2.2 Standard MySQL Installation Using a Binary Distribution.
For Windows distributions, see section 2.3 Installing MySQL on Windows.
These distributions are generated using the script
Build-tools/Do-compile, which compiles the source code and creates
the binary tar.gz archive using
scripts/make_binary_distribution.
These binaries are configured and built with the following compilers and
options. This information can also be obtained by looking at the variables
COMP_ENV_INFO and CONFIGURE_LINE inside the script
bin/mysqlbug of every binary tar file distribution.
The following binaries are built on MySQL AB development systems:
gcc 2.95.3:
CFLAGS="-O2 -mcpu=pentiumpro" CXX=gcc CXXFLAGS="-O2 -mcpu=pentiumpro -felide-constructors" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --disable-shared --with-client-ldflags=-all-static --with-mysqld-ldflags=-all-static
icc (Intel C++ Compiler 8.0):
CC=icc CXX=icc CFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict" CXXFLAGS="-O3 -unroll2 -ip -mp -no-gcc -restrict" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --disable-shared --with-client-ldflags=-all-static --with-mysqld-ldflags=-all-static --with-embedded-server --with-innodb
ecc (Intel C++ Itanium Compiler 7.0):
CC=ecc CFLAGS="-O2 -tpp2 -ip -nolib_inline" CXX=ecc CXXFLAGS="-O2 -tpp2 -ip -nolib_inline" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile
ecc (Intel C++ Itanium Compiler 7.0):
CC=ecc CFLAGS=-tpp1 CXX=ecc CXXFLAGS=-tpp1 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile
ccc (Compaq C V6.2-505 / Compaq C++ V6.3-006):
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx CXXFLAGS="-fast -arch generic -noexceptions -nortti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared --disable-shared
gcc 2.95.4:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-embedded-server --with-innodb
gcc 2.95.3:
CFLAGS="-O2" CXX=gcc CXXFLAGS="-O2 -felide-constructors" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-client-ldflags=-all-static --with-mysqld-ldflags=-all-static
gcc 3.2.1:
CXX=gcc ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
gcc 3.2.3:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-innodb
gcc 3.2:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-z-libs=no --with-named-curses-libs=-lcurses --disable-shared
gcc 3.2:
CC=gcc CFLAGS="-O3 -m64 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -m64 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --with-named-curses-libs=-lcurses --disable-shared
gcc 2.95.3:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-curses-libs=-lcurses --disable-shared
cc-5.0 (Sun Forte 5.0):
CC=cc-5.0 CXX=CC ASFLAGS="-xarch=v9" CFLAGS="-Xa -xstrconst -mt -D_FORTEC_ -xarch=v9" CXXFLAGS="-noex -mt -D_FORTEC_ -xarch=v9" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-z-libs=no --enable-thread-safe-client --disable-shared
gcc 3.2.3:
CFLAGS="-O2 -mcpu=powerpc -Wa,-many " CXX=gcc CXXFLAGS="-O2 -mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --disable-shared
xlC_r (IBM Visual Age C/C++ 6.0):
CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192" CXX=xlC_r CXXFLAGS ="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --disable-shared --with-innodb
gcc 3.3:
CFLAGS="-O2 -mcpu=powerpc -Wa,-many" CXX=gcc CXXFLAGS="-O2 -mcpu=powerpc -Wa,-many -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --disable-shared
xlC_r (IBM Visual Age C/C++ 6.0):
CC=xlc_r CFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192" CXX=xlC_r CXXFLAGS="-ma -O2 -qstrict -qoptimize=2 -qmaxmem=8192" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --disable-shared --with-embedded-server --with-innodb
gcc 3.1:
CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc CXXFLAGS="-DHPUX -I/opt/dce /include -felide-constructors -fno-exceptions -fno-rtti -O3 -fPIC" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-pthread --with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC --disable-shared
aCC (HP ANSI C++ B3910B A.03.50):
CC=cc CXX=aCC CFLAGS=+DAportable CXXFLAGS=+DAportable ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-embedded-server --with-innodb
aCC (HP ANSI C++ B3910B A.03.33):
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
aCC (HP ANSI C++ B3910B A.03.33):
CC=cc CXX=aCC CFLAGS="+DAportable" CXXFLAGS="+DAportable" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-innodb
aCC (HP aC++/ANSI C B3910B A.05.50):
CC=cc CXX=aCC CFLAGS="+DD64 +DSitanium2" CXXFLAGS="+DD64 +DSitanium2" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-embedded-server --with-innodb
gcc 3.1:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
gcc 2.95.4:
CFLAGS=-DHAVE_BROKEN_REALPATH ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-z-libs=not-used --disable-shared
gcc 2.95.4:
CFLAGS="-DHAVE_BROKEN_REALPATH -D__USE_UNIX98 -D_REENTRANT -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads" CXXFLAGS="-DHAVE_BROKEN_REALPATH -D__USE_UNIX98 -D_REENTRANT -D_THREAD_SAFE -I/usr/local/include/pthread/linuxthreads" ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --enable-thread-safe-client --enable-local-infile --enable-assembler --with-named-thread-libs="-DHAVE_GLIBC2_STYLE_GETHOSTBYNAME_R -D_THREAD_SAFE -I /usr/local/include/pthread/linuxthreads -L/usr/local/lib -llthread -llgcc_r" --disable-shared --with-embedded-server --with-innodb
gcc 2.95.3qnx-nto 20010315:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
The following binaries are built on third-party systems kindly provided to MySQL AB by other users. These are provided only as a courtesy; MySQL AB does not have full control over these systems, so we can provide only limited support for the binaries built on them.
gcc 2.95.3:
CFLAGS="-O3 -mpentium" LDFLAGS=-static CXX=gcc CXXFLAGS="-O3 -mpentium -felide-constructors" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --enable-thread-safe-client --disable-shared
CC 3.2:
CC=cc CFLAGS="-O" CXX=CC ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-z-libs=no --enable-thread-safe-client --disable-shared
cc/cxx (Compaq C V6.3-029i / DIGITAL C++ V6.1-027):
CC="cc -pthread" CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed -speculate all" CXX="cxx -pthread" CXXFLAGS="-O4 -ansi_alias -fast -inline speed -speculate all -noexceptions -nortti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --with-named-thread-libs="-lpthread -lmach -lexc -lc" --disable-shared --with-mysqld-ldflags=-all-static
gcc 3.0.1:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
gcc 3.2.1:
CFLAGS=-DHAVE_BROKEN_REALPATH ./configure --prefix=/usr/local/mysql --localstatedir=/usr/local/mysql/data --libexecdir=/usr/local/mysql/bin --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared --with-innodb
The following compile options have been used for binary packages that MySQL AB provided in the past. These binaries no longer are being updated, but the compile options are listed here for reference purposes.
egcs 1.1.2:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --enable-assembler --disable-shared
gcc 2.95.2:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --enable-assembler --with-mysqld-ldflags=-all-static --disable-shared --with-extra-charsets=complex
gcc 2.7.2.1:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors" ./configure --prefix=/usr/local/mysql --disable-shared --with-extra-charsets=complex --enable-assembler
egcs 1.0.3a or 2.90.27 or
gcc 2.95.2 and newer:
CC=gcc CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" ./configure --prefix=/usr/local/mysql --with-low-memory --with-extra-charsets=complex --enable-assembler
gcc 2.8.1:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-low-memory --with-extra-charsets=complex
gcc 2.7.2.1:
CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
gcc 2.7.2:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
gcc 2.7.2.2:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
Anyone who has more optimal options for any of the preceding configurations
listed can always mail them to the MySQL internals mailing list.
See section 1.4.1.1 The MySQL Mailing Lists.
RPM distributions prior to MySQL 3.22 are user-contributed. Beginning with MySQL 3.22, RPM distributions are generated by MySQL AB.
If you want to compile a debug version of MySQL, you should add
--with-debug or --with-debug=full to the preceding
configure commands and remove any -fomit-frame-pointer options.
Check the MySQL downloads page (http://dev.mysql.com/downloads/) for information about the current version and for downloading instructions. For a complete up-to-date list of MySQL download mirror sites, see http://dev.mysql.com/downloads/mirrors.html. There you can also find information about becoming a MySQL mirror site and how to report a bad or out-of-date mirror.
Our main mirror is located at http://mirrors.sunsite.dk/mysql/.
GnuPGAfter you have downloaded the MySQL package that suits your needs and before you attempt to install it, you should make sure that it is intact and has not been tampered with. MySQL AB offers three means of integrity checking:
GnuPG, the GNU Privacy Guard
The following sections describe how to use these methods.
If you notice that the MD5 checksum or GPG signatures do not match, first try to download the respective package one more time, perhaps from another mirror site. If you repeatedly cannot successfully verify the integrity of the package, please notify us about such incidents, including the full package name and the download site you have been using, at webmaster@mysql.com or build@mysql.com. Do not report downloading problems using the bug-reporting system.
After you have downloaded a MySQL package, you should make sure that its MD5
checksum matches the one provided on the MySQL download pages. Each package
has an individual checksum that you can verify with the following command,
where package_name is the name of the package you downloaded:
shell> md5sum package_name
Example:
shell> md5sum mysql-standard-4.0.17-pc-linux-i686.tar.gz 60f5fe969d61c8f82e4f7f62657e1f06 mysql-standard-4.0.17-pc-linux-i686.tar.gz
You should verify that the resulting checksum (the string of hexadecimal digits) matches the one displayed on the download page immediately below the respective package.
Note: Make sure to verify the checksum of the archive file
(e.g. the .zip or .tar.gz file) and not of the files that are
contained inside of the archive!
Note that not all operating systems support the md5sum command. On
some, it is simply called md5 and others do not ship it at all. On
Linux, it is part of the GNU Text Utilities package, which is
available for a wide range of platforms. You can download the source code
from http://www.gnu.org/software/textutils/ as well. If you have
OpenSSL installed, you can also use the command openssl md5
package_name instead. A DOS/Windows implementation of the md5
command line utility is available from http://www.fourmilab.ch/md5/.
A graphical MD5 checking tool is winMd5Sum, which can be obtained
from http://winmd5sum.solidblue.biz/.
GnuPGAnother method of verifying the integrity and authenticity of a package is to use cryptographic signatures. This is more reliable than using MD5 checksums, but requires more work.
Beginning with MySQL 4.0.10 (February 2003), MySQL AB started signing
downloadable packages with GnuPG (GNU Privacy Guard).
GnuPG is an Open Source alternative to the very well-known
Pretty Good Privacy (PGP) by Phil Zimmermann.
See http://www.gnupg.org/ for more information about GnuPG
and how to obtain and install it on your system. Most Linux distributions
ship with GnuPG installed by default. For more information
about OpenPGP, see http://www.openpgp.org/.
To verify the signature for a specific package, you first need to obtain a
copy of MySQL AB's public GPG build key. You can download the key from
http://www.keyserver.net/. The key that you want to obtain is named
build@mysql.com. Alternatively, you can cut and paste the key
directly from the following text:
Key ID:
pub 1024D/5072E1F5 2003-02-03
MySQL Package signing key (www.mysql.com) <build@mysql.com>
Fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5
Public Key (ASCII-armored):
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org
mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q7TXlTUUwgUGFj
a2FnZSBzaWduaW5nIGtleSAod3d3Lm15c3FsLmNvbSkgPGJ1aWxkQG15c3FsLmNv
bT6IXQQTEQIAHQUCPj6jDAUJCWYBgAULBwoDBAMVAwIDFgIBAheAAAoJEIxxjTtQ
cuH1cY4AnilUwTXn8MatQOiG0a/bPxrvK/gCAJ4oinSNZRYTnblChwFaazt7PF3q
zIhMBBMRAgAMBQI+PqPRBYMJZgC7AAoJEElQ4SqycpHyJOEAn1mxHijft00bKXvu
cSo/pECUmppiAJ41M9MRVj5VcdH/KN/KjRtW6tHFPYhMBBMRAgAMBQI+QoIDBYMJ
YiKJAAoJELb1zU3GuiQ/lpEAoIhpp6BozKI8p6eaabzF5MlJH58pAKCu/ROofK8J
Eg2aLos+5zEYrB/LsrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWsEN/l
xaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLmRDRi
Rjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hkAWzE
7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkbf4fm
Le11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHbuE5p
/1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+Lwqq
a8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1ZaSaf
anFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGoTbOW
I39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev42Lmu
QT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkKHt92
6s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUOetdZ
Whe70YGNPw1yjWJT1IhMBBgRAgAMBQI+PqMdBQkJZgGAAAoJEIxxjTtQcuH17p4A
n3r1QpVC9yhnW2cSAjq+kr72GX0eAJ4295kl6NxYEuFApmr1+0uUq/SlsQ==
=YJkx
-----END PGP PUBLIC KEY BLOCK-----
You can import the build key into your personal public GPG keyring by using
gpg --import. For example, if you save the key in a file named
`mysql_pubkey.asc', the import command looks like this:
shell> gpg --import mysql_pubkey.asc
See the GPG documentation for more information on how to work with public keys.
After you have downloaded and imported the public build key, download your desired MySQL package and the corresponding signature, which also is available from the download page. The signature file has the same name as the distribution file with an `.asc' extension. For example:
| Distribution file | mysql-standard-4.0.17-pc-linux-i686.tar.gz
|
| Signature file | mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
|
Make sure that both files are stored in the same directory and then run the following command to verify the signature for the distribution file:
shell> gpg --verify package_name.asc
Example:
shell> gpg --verify mysql-standard-4.0.17-pc-linux-i686.tar.gz.asc
gpg: Warning: using insecure memory!
gpg: Signature made Mon 03 Feb 2003 08:50:39 PM MET
using DSA key ID 5072E1F5
gpg: Good signature from
"MySQL Package signing key (www.mysql.com) <build@mysql.com>"
The Good signature message indicates that everything is all right.
You can ignore the insecure memory warning.
RPMFor RPM packages, there is no separate signature. RPM packages have a built-in GPG signature and MD5 checksum. You can verify a package by running the following command:
shell> rpm --checksig package_name.rpm
Example:
shell> rpm --checksig MySQL-server-4.0.10-0.i386.rpm MySQL-server-4.0.10-0.i386.rpm: md5 gpg OK
Note: If you are using RPM 4.1 and it complains about (GPG)
NOT OK (MISSING KEYS: GPG#5072e1f5), even though you have imported the
MySQL public build key into your own GPG keyring, you need to import the
key into the RPM keyring first. RPM 4.1 no longer uses your personal GPG
keyring (or GPG itself). Rather, it maintains its own keyring because it is
a system-wide application and a user's GPG public keyring is a user-specific
file. To import the MySQL public key into the RPM keyring, first obtain the
key as described in the previous section. Then use rpm --import
to import the key. For example, if you have the public key stored in a file
named `mysql_pubkey.asc', import it using this command:
shell> rpm --import mysql_pubkey.asc
If you need to obtain the MySQL public key, see section 2.1.4.2 Signature Checking Using GnuPG.
This section describes the default layout of the directories created by installing binary or source distributions provided by MySQL AB. If you install a distribution provided by another vendor, some other layout might be used.
On Windows, the default installation directory is `C:\mysql'. With MySQL version 4.1.5 and higher, this has changed to `C:\Program Files\MySQL\MySQL Server 4.1', where 4.1 is the major version of the installation. The folder has the following subdirectories:
| Directory | Contents of Directory |
| `bin' | Client programs and the mysqld server
|
| `data' | Log files, databases |
| `Docs' | Documentation |
| `examples' | Example programs and scripts |
| `include' | Include (header) files |
| `lib' | Libraries |
| `scripts' | Utility scripts |
| `share' | Error message files |
Installations created from Linux RPM distributions result in files under the following system directories:
| Directory | Contents of Directory |
| `/usr/bin' | Client programs and scripts |
| `/usr/sbin' | The mysqld server
|
| `/var/lib/mysql' | Log files, databases |
| `/usr/share/doc/packages' | Documentation |
| `/usr/include/mysql' | Include (header) files |
| `/usr/lib/mysql' | Libraries |
| `/usr/share/mysql' | Error message and character set files |
| `/usr/share/sql-bench' | Benchmarks |
On Unix, a tar file
binary distribution is installed by unpacking it at the installation
location you choose (typically `/usr/local/mysql') and creates the
following directories in that location:
| Directory | Contents of Directory |
| `bin' | Client programs and the mysqld server
|
| `data' | Log files, databases |
| `docs' | Documentation, ChangeLog |
| `include' | Include (header) files |
| `lib' | Libraries |
| `scripts' | mysql_install_db
|
| `share/mysql' | Error message files |
| `sql-bench' | Benchmarks |
A source distribution is installed after you configure and compile it. By default, the installation step installs files under `/usr/local', in the following subdirectories:
| Directory | Contents of Directory |
| `bin' | Client programs and scripts |
| `include/mysql' | Include (header) files |
| `info' | Documentation in Info format |
| `lib/mysql' | Libraries |
| `libexec' | The mysqld server
|
| `share/mysql' | Error message files |
| `sql-bench' | Benchmarks and crash-me test
|
| `var' | Databases and log files |
Within an installation directory, the layout of a source installation differs from that of a binary installation in the following ways:
mysqld server is installed in the `libexec'
directory rather than in the `bin' directory.
mysql_install_db is installed in the `bin' directory
rather than in the `scripts' directory.
You can create your own binary installation from a compiled source distribution by executing the `scripts/make_binary_distribution' script from the top directory of the source distribution.
The next several sections cover the installation of MySQL on platforms where we offer packages using the native packaging format of the respective platform. (This is also known as performing a ``binary install.'') However, binary distributions of MySQL are available for many other platforms as well. See section 2.7 Installing MySQL on Other Unix-Like Systems for generic installation instructions for these packages that apply to all platforms.
See section 2.1 General Installation Issues for more information on what other binary distributions are available and how to obtain them.
A native Windows version of MySQL has been available from MySQL AB since version 3.21 and represents a sizable percentage of the daily downloads of MySQL. This section describes the process for installing MySQL on Windows.
With the release of MySQL 4.1.5, MySQL AB has introduced a new installer for the Windows version of MySQL, combined with a new GUI Configuration Wizard. This combination automatically installs MySQL, creates an option file, starts the server, and secures the default user accounts.
If you have installed a version of MySQL prior to version 4.1.5, you must perform the following steps:
This process also must be followed with newer MySQL installations where the installation package does not include an installer.
MySQL for Windows is available in two distribution formats:
Generally speaking, you should use the binary distribution. It's simpler, and you need no additional tools to get MySQL up and running.
This section describes how to install MySQL on Windows using a binary distribution. To install using a source distribution, see section 2.8.6 Installing MySQL from Source on Windows.
To run MySQL on Windows, you need the following:
You may also have the following optional requirements:
MAX_ROWS and
AVG_ROW_LENGTH when you create tables.
See section 13.2.6 CREATE TABLE Syntax.
Starting with MySQL version 4.1.5, there are three install packages to choose from when installing MySQL on Windows. The Packages are as follows:
The Essentials package is recommended for most users.
Your choice of install package affects the installation process you must follow. If you choose to install either the Essentials or Complete install packages, see section 2.3.3 Installing MySQL with the Automated Installer. If you choose to install MySQL from the Noinstall archive, see section 2.3.6 Installing MySQL from a noinstall Zip Archive.
Starting with MySQL 4.1.5, users can use the new MySQL Installation Wizard and MySQL Configuration Wizard to install MySQL on Windows. The MySQL Installation Wizard and MySQL Configuration Wizard are designed to install and configure MySQL in such a way that new users can immediately get started using MySQL.
The MySQL Installation Wizard and MySQL Configuration Wizard are available in the Essentials and Complete install packages, and are recommended for most standard MySQL installations. Exceptions include users who need to install multiple instances of MySQL on a single server and advanced users who want complete control of server configuration.
If you are installing a version of MySQL prior to MySQL 4.1.5, please follow the instructions for installing MySQL from the Noinstall installation package. See section 2.3.6 Installing MySQL from a noinstall Zip Archive.
MySQL Installation Wizard is a new installer for the MySQL server that uses the latest installer technologies for Microsoft Windows. The MySQL Installation Wizard, in combination with the MySQL Configuration Wizard, allows a user to install and configure a MySQL server that is ready for use immediately after installation.
The MySQL Installation Wizard is the standard installer for all MySQL server distributions, version 4.1.5 and higher. Users of previous versions of MySQL need to manually shut down and remove their existing MySQL installations before installing MySQL with the MySQL Installation Wizard. See section 2.3.4.7 Upgrading MySQL for more information on upgrading from a previous version.
Microsoft has included an improved version of their Microsoft Windows Installer (MSI) in the recent versions of Windows. Using the MSI has become the de-facto standard for application installations on Windows 2000, Windows XP, and Windows Server 2003. The MySQL Installation Wizard makes use of this technology to provide a smoother and more flexible installation progress.
The Microsoft Windows Installer Engine was updated with the release of Windows XP; those using a previous version of Windows can reference this Microsoft Knowledge Base article for information on upgrading to the latest version of the Windows Installer Engine.
Further, Microsoft has introduced the WiX (Windows Installer XML) tool set recently. It is the first highly acknowledged Open Source project from Microsoft. We switched to WiX because it is an Open Source project and it allows us to handle the complete Windows installation process in a flexible way with scripts.
Improving the MySQL Installation Wizard depends on the support and feedback of users like you. If you find that the MySQL Installation Wizard is lacking some feature important to you, or if you discover a bug, please use our MySQL Bug System to request features or report problems.
The MySQL server install packages can be downloaded from http://dev.mysql.com/downloads/. If the package you download is contained within a Zip archive, you need to extract the archive first.
The process for starting the wizard depends on the contents of the
install package you download. If there is a
setup.exe file present, double-click it to start
the install process. If there is a .msi file
present, double-click it to start the install process.
There are up three installation types available:
Typical, Complete, and
Custom.
The Typical installation type installs the MySQL
server, the mysql command-line client, and the
command-line utilities. The command-line clients and utilities
include mysqldump, myisamchk,
and several other tools to help you manage the MySQL server.
The Complete installation type installs all
components included in the installation package. The full
installation package includes components such as the embedded server
library, the benchmark suite, support scripts, and documentation.
The Custom installation type gives you complete
control over which packages you wish to install and the installation
path that is used. See
section 2.3.4.4 The Custom Install Dialog
for more information on performing a custom install.
If you choose the Typical or
Complete installation types and click the
Next button, you advance to the confirmation
screen to confirm your choices and begin the installation. If you
choose the Custom installation type and click the
Next button, you advance to the custom install
dialog, described in
section 2.3.4.4 The Custom Install Dialog
If you wish to change the installation path or the specific
components that are installed by the MySQL Installation Wizard, you should
choose the Custom installation type.
All available components are listed in a tree view on the left side
of the custom install dialog. Components that are not installed
have a red X icon, components that are
installed have a gray icon. To change whether a component is
installed, click on the component's icon and choose an new option
from the drop-down list that appears.
You can change the default installation path by clicking the Change... button to the right of the displayed installation path.
After choosing your install components and installation path, click the Next button to advance to the confirmation dialog.
Once you choose an installation type and optionally choose your installation components, you advance to the confirmation dialog. Your installation type and installation path are displayed for you to review.
To install MySQL if you are satisfied with your settings, click the Install button. To change your settings, click the Back button. To exit the MySQL Installation Wizard without installing MySQL, click the Cancel button.
After installation is complete, you are given the option of registering with the MySQL web site. Registration gives you access to post in the MySQL forums at forums.mysql.com, along with the ability to report bugs at bugs.mysql.com and to subscribe to the newsletter. The final screen of the installer provides a summary of the installation and gives you the option to launch the MySQL Configuration Wizard, which you can use to create a configuration file, install the MySQL service, and configure security.
Once you click the Install button, the MySQL Installation Wizard begins the installation process and makes certain changes to your system which are described in the sections that follow.
Changes to the Registry
The MySQL Installation Wizard creates one Windows registry key in a typical
install situation, located in
HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB.
The MySQL Installation Wizard creates a key named after the major version of
the server that is being installed, such as MySQL Server
4.1. It contains two string values,
Location and Version. The
Location string contains the path to the
installation directory. In a default installation it contains
C:\Program Files\MySQL\MySQL Server 4.1\. The
Version string contains the release number. For
example, for an installation of MySQL Server 4.1.5 the key contains
a value of 4.1.5.
These registry keys are used to help external tools identify the
installed location of the MySQL server, preventing a complete scan
of the hard-disk to determine the installation path of the MySQL
server. The registry keys are not required to run the server and
when using the noinstall Zip archive the registry
keys are not created.
Changes to the Start Menu
The MySQL Installation Wizard creates a new entry in the Windows Start menu under a common MySQL menu heading named after the major version of MySQL that you have installed. For example, if you install MySQL 4.1, the MySQL Installation Wizard creates a MySQL Server 4.1 section in the start menu.
The following entries are created within the new Start menu section:
MySQL Command Line Client: This is a shortcut to
the mysql command-line client and is configured
to connect as the root user. The shortcut prompts for a root user
password when connecting.
MySQL Server Instance Config Wizard: This is a
shortcut to the MySQL Configuration Wizard. Use this shortcut to configure a
newly installed server, or to re-configure an existing server.
MySQL Documentation: This is a link to the MySQL
server documentation that is stored locally in the MySQL server
installation directory. This option is not available when the MySQL
server is installed from the essential
installation package.
Changes to the File System
The MySQL Installation Wizard by default installs the MySQL server to
C:\Program Files\MySQL\MySQL
Server 4.1, where
Program Files is the default location for
applications in your system, and 4.1 is
the major version of your MySQL server. This is the new recommended
location for the MySQL server, replacing the previous default
location of `c:\mysql'.
By default, all MySQL applications are stored in a common directory
at C:\Program
Files\MySQL, where Program
Files is the default location for applications in your
Windows installation. A typical MySQL installation on a developer
machine may look like this:
C:\Program Files\MySQL\MySQL Server 4.1 C:\Program Files\MySQL\MySQL Server 5.0 C:\Program Files\MySQL\MySQL Administrator 1.0 C:\Program Files\MySQL\MySQL Query Browser 1.0
This approach makes it easier to manage and maintain all MySQL applications installed on a particular system.
From MySQL version 4.1.5, the new MySQL Installation Wizard can perform server upgrades automatically using the upgrade capabilities of MSI. That means you do not need to remove a previous installation manually before installing a new release. The installer automatically shuts down and removes the previous MySQL service before installing the new version.
Automatic upgrades are only available when upgrading between installations that have the same major and minor version numbers. For example, you can upgrade automatically from MySQL 4.1.5 to MySQL 4.1.6, but not from MySQL 4.1 to MySQL 5.0.
If you are upgrading MySQL version 4.1.4 or earlier to version 4.1.5 or later, you must first manually shut down and remove the older installation before upgrading. Be sure to back up your databases before performing such an upgrade, so that you can restore the databases after the upgrade is completed. It is always recommended that you back up your data before performing any upgrades.
See section 2.3.15 Upgrading MySQL on Windows.
The MySQL Configuration Wizard helps automate the process of configuring your server under Windows. The MySQL Configuration Wizard creates a custom `my.ini' file by asking you a series of questions and then applying your responses to a template to generate a `my.ini' file that is tuned to your installation.
The MySQL Configuration Wizard is included with the MySQL server starting with MySQL version 4.1.5, but is designed to work with MySQL servers versions 4.1 and higher. The MySQL Configuration Wizard is currently available for Windows users only.
MySQL Configuration Wizard is to a large extent the result of feedback MySQL AB has received from many users over a period of several years. However, if you find it's lacking some feature important to you, or if you discover a bug, please use our MySQL Bug System to request features or report problems.
The MySQL Configuration Wizard is typically launched from the MySQL Installation Wizard,
as the MySQL Installation Wizard exits. You can also launch the
MySQL Configuration Wizard by clicking the MySQL Server Instance Config
Wizard entry in the MySQL section of the
Start menu.
In addition, you can navigate to the bin directory
of your MySQL installation and launch the
`MySQLInstanceConfig.exe' file directly.
If the MySQL Configuration Wizard detects an existing `my.ini' file, you have the option of either re-configuring your existing server, or removing the server instance by deleting the `my.ini' file and stopping and removing the MySQL service.
To reconfigure an existing server, choose the Re-configure
Instance option and click the Next
button. Your existing `my.ini' file is
renamed to my
timestamp.ini.bak, where
timestamp is the date and time the
existing `my.ini' file was created. To remove the
existing server instance, choose the Remove
Instance option and click the Next
button.
If you choose the Remove Instance option, you
advance to a confirmation window. Click the
Execute button and the MySQL Configuration Wizard
stops and removes the MySQL service and deletes the
`my.ini' file. The server installation and its
data folder are not removed.
If you choose the Re-configure Instance option,
you advance to the Configuration Type dialog where
you can choose the type of installation you wish to configure.
When you start the MySQL Configuration Wizard for a new MySQL installation, or
choose the Re-configure Instance option for an
existing installation, you advance to the Configuration
Type dialog.
There are two configuration types available: Detailed
Configuration and Standard
Configuration. The Standard
Configuration option is intended for new users who want to
get started with MySQL quickly without having to make a lot of
decisions in regards to server configuration. The Detailed
Configuration option is intended for advanced users who
want more fine-grained control of server configuration.
If you are new to MySQL and need a server configured as a
single-user developer machine the Standard
Configuration should suit your needs. Choosing the
Standard Configuration option causes the
MySQL Configuration Wizard to automatically set all configuration options with
the exception of the Service Options and
Security Options.
The Standard Configuration sets options that may
be incompatible with systems where there are existing MySQL
installations. If you have an existing MySQL installation on your
system in addition to the installation you wish to configure, the
Detailed Configuration option is recommended.
To complete the Standard Configuration, please refer to the sections
on Service Options and Security Options, located at
section 2.3.5.11 The Service Options Dialog and section 2.3.5.12 The Security Options Dialog
respectively.
There are three different server types available to choose from, and the server type you choose affects the decisions the MySQL Configuration Wizard makes with regards to memory, disk, and processor usage.
Developer Machine: Choose this option for a
typical desktop workstation where MySQL is intended only for
personal use. It is assumed that many other desktop applications
are running. The MySQL server is configured to use minimal
system resources.
Server Machine: Choose this option for a server
machine where the MySQL server is running alongside other
server applications such as FTP, email, and web servers. The MySQL
server is configured to use a medium portion of the system
resources.
Dedicated MySQL Server Machine: Choose this
option for a server machine that is intended to run only the MySQL
server. It is assumed that no other applications are running.
The MySQL server is configured to use all available system
resources.
The Database Usage dialog allows you to indicate
the table handlers you expect to use when creating MySQL tables. The
option you choose determines whether the InnoDB table handler is
available and what percentage of the server resources are available
to InnoDB.
Multifunctional Database: This option enables
both the InnoDB and MyISAM table handlers and divides resources
evenly between the two. This option is recommended for users that
use both table handlers on a regular basis.
Transactional Database Only: This option enables
both the InnoDB and MyISAM table handlers but dedicates most server
resources toward the InnoDB table handler. This option is
recommended for users that use InnoDB almost exclusively and
make only minimal use of MyISAM.
Non-Transactional Database Only: This option
disables the InnoDB table handler completely and dedicates all
server resources to the MyISAM table handler. This option is
recommended for users who do not use InnoDB.
Some users may want to locate the InnoDB tablespace files in a different location than the MySQL server data directory. Placing the tablespace files in a separate location can be desirable if your system has a higher capacity or higher performance storage device available, such as a RAID storage system.
To change the default location for the InnoDB tablespace files, choose a new drive from the drop-down list of drive letters and choose a new path from the drop-down list of paths. To create a custom path, click the ... button.
If you are modifying the configuration of an existing server, you must click the Modify button before you change the path. In this situation you have to manually move the existing tablespace files to the new location before starting the server.
It is important to set a limit to the number of concurrent
connections to the MySQL server that can be established to prevent
the server from running out of resources. The Concurrent
Connections dialog allows you to choose the expected usage
of your server, and sets the limit for concurrent connections
accordingly. It is also possible to manually set the concurrent
connection limit.
Decision Support (DSS)/OLAP: Choose this option
if your server does not require a large number of concurrent
connections. The maximum number of connections is set at 100,
with an average of 20 concurrent connections assumed.
Online Transaction Processing (OLTP): Choose this
option if your server requires a large number of concurrent
connections. The maximum number of connections is set at 500.
Manual Setting: Choose this option to manually
set the maximum number of concurrent connections to the server.
Choose the number of concurrent connections from the drop-down box
provided, or type the maximum number of connections into the
drop-down box if the number you desire is not listed.
Use the Networking Options dialog to enable or
disable TCP/IP networking and to configure the port number that is
used to connect to the MySQL server.
TCP/IP networking is enabled by default. To disable TCP/IP
networking, uncheck the box next to the Enable TCP/IP
Networking option.
Port 3306 is used by default. To change the port used to access MySQL, choose a new port number from the drop-down box or type a new port number directly into the drop-down box. If the port number you choose is in use you are prompted to confirm your choice of port number.
The MySQL server supports multiple character sets and it is possible
to set a default server character set that is applied to all
tables, columns, and databases unless overridden. Use the
Character Set dialog to change the default
character set of the MySQL server.
Standard Character Set: Choose this option if you
want to use Latin1 as the default server
character set. Latin1 is used for English and
many Western European languages.
Best Support For Multilingualism: Choose this
option if you want to use UTF8 as the default
server character set. UTF8 can store characters
from many different languages in a single character set.
Manual Selected Default Character Set /
Collation: Choose this option if you want to pick the
server's default character set manually. Choose the desired
character set from the provided drop-down list.
On Windows NT based platforms, the MySQL server can be installed as a service. When installed as a service, the MySQL server can be started automatically during system startup, and even restarted automatically by Windows in the event of a service failure.
The MySQL Configuration Wizard installs the MySQL server as a service by
default, using the service name MySQL. If you do
not wish to install the service, un-check the box next to the
Install As Windows Service option. You can changed
the service name by picking a new service name from the drop-down box
provided or by typing a new service name into the drop-down box.
To install the MySQL server as a service but not have it started
automatically at startup, un-check the box next to the
Launch the MySQL Server automatically option.
It is strongly recommended that you set a root password for your
MySQL server, and the MySQL Configuration Wizard requires you set a root
password by default. If you do not wish to set a root password,
un-check the box next to the Modify Security
Settings option.
To set the root password, type the desired password into both the
New root password and Confirm
boxes. If you are re-configuring an existing server, you also
need to enter the existing root password into the Current
root password box.
To prevent root logins from across the network, check the box next to
the Root may only connect from localhost option.
This increases the security of your root account.
To create an anonymous user account, check the box next to the
Create An Anonymous Account option. Creating an
anonymous account can decrease server security and cause login and
permission difficulties and is not recommended.
The final dialog in the MySQL Configuration Wizard is the Confirmation
Dialog. To start the configuration process, click the
Execute button. To return to a previous
dialog, click the Back button. To exit the
MySQL Configuration Wizard without configuring the server, click the
Cancel button.
After you click the Execute button, the MySQL Configuration Wizard performs a series of tasks with progress displayed onscreen as the tasks are performed.
The MySQL Configuration Wizard firsts determines various configuration file options based on your choices using a template prepared by MySQL AB developers and engineers. This template is named `my-template.ini' and is located in your server installation directory.
The MySQL Configuration Wizard then writes these options to a
`my.ini' file. The final location of the
`my.ini' file is displayed next to the
Write configuration file task.
If you chose to create a service for the MySQL server the MySQL Configuration Wizard creates ans starts the service. If you are re-configuring an existing service, the MySQL Configuration Wizard restarts the service to apply your configuration changes.
If you chose to set a root password, the MySQL Configuration Wizard connects
to the server, sets your new root password and applies any other
security settings you may have selected.
After the MySQL Configuration Wizard has completed its tasks, a summary is shown. Click the Finish button to exit the MySQL Configuration Wizard.
In MySQL installations prior to version 4.1.5 it was customary to name the server configuration file `my.cnf' or `my.ini' and locate the file either at `c:\my.cnf' or `c:\Windows\my.ini'.
The new MySQL Configuration Wizard places the `my.ini' file in the installation directory of the MySQL server. This helps associate configuration files with particular server instances.
To ensure that the MySQL server knows where to look for the
`my.ini' file, an argument similar to this is
passed to the MySQL server as part of the service installation:
--defaults-file="C:\Program Files\MySQL\MySQL
Server 4.1\my.ini", where
C:\Program Files\MySQL\MySQL Server 4.1 is
replaced with the installation path to the MySQL Server.
The --defaults-file instructs the MySQL server to
read the specified file for configuration options.
To modify the `my.ini' file, open it with a text editor and make any necessary changes. You can also modify the server configuration with the MySQL Administrator utility.
MySQL clients and utilities such as the mysql
command-line client and mysqldump are not able to locate
the `my.ini' file located in the server
installation directory. To configure the client and utility
applications, create a new `my.ini' file in the
`c:\Windows' directory.
Users who are installing from the Noinstall package, or who are installing a version of MySQL prior to 4.1.5 can use the instructions in this section to manually install MySQL. If you are installing a version prior to 4.1.5 with an install package that includes a Setup program, substitute running the Setup program for extracting the archive.
The process for installing MySQL from a Zip archive is as follows:
This process is described in the sections that follow.
To install MySQL manually, do the following:
If you need to specify startup options when you run the server, you can indicate them on the command line or place them in an option file. For options that are used every time the server starts, you may find it most convenient to use an option file to specify your MySQL configuration. This is particularly true under the following circumstances:
InnoDB
transactional tables in MySQL 3.23, you must manually add some extra lines
to the option file, as described in section 15.4 InnoDB Configuration. (As of MySQL 4.0, InnoDB creates its
data files and log files in the data directory by default. This means you
need not configure InnoDB explicitly. You may still do so if you
wish, and an option file is useful in this case, too.)
When the MySQL server starts on Windows, it looks for options in
two files: the `my.ini' file in the Windows directory, and
the `C:\my.cnf' file. The Windows directory typically is
named something like `C:\WINDOWS' or `C:\WinNT'. You
can determine its exact location from the value of the WINDIR
environment variable using the following command:
C:\> echo %WINDIR%
MySQL looks for options first in the `my.ini' file, then in
the `my.cnf' file. However, to avoid confusion, it's best if
you use only one file. If your PC uses a boot loader where the
C: drive isn't the boot drive, your only option is to use
the `my.ini' file. Whichever option file you use, it must be a plain
text file.
You can also make use of the example option files included with your MySQL distribution. Look in your install directory for files such as my-small.cnf, my-medium.cnf, my-large.cnf, etc., which you can rename and copy to the appropriate location for use as a base configuration file.
An option file can be created and modified with any text editor,
such as the Notepad program. For example, if MySQL is
installed at `E:\mysql' and the data directory is located at
`E:\mydata\data', you can create the option file and set up
a [mysqld] section to specify values for the basedir
and datadir parameters:
[mysqld] # set basedir to your installation path basedir=E:/mysql # set datadir to the location of your data directory datadir=E:/mydata/data
Note that Windows pathnames are specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them:
[mysqld] # set basedir to your installation path basedir=E:\\mysql # set datadir to the location of your data directory datadir=E:\\mydata\\data
On Windows, the MySQL installer places the data directory directly under the directory where you install MySQL. If you would like to use a data directory in a different location, you should copy the entire contents of the `data' directory to the new location. For example, by default, the installer places MySQL in `C:\mysql' and the data directory in `C:\mysql\data'. If you want to use a data directory of `E:\mydata', you must do two things:
--datadir option to specify the new data directory location
each time you start the server.
Starting with MySQL 3.23.38, the Windows distribution includes both the normal and the MySQL-Max server binaries.
Up through the early releases of MySQL 4.1, the servers included in Windows distributions are named like this:
| Binary | Description |
mysqld | Compiled with full debugging and automatic memory allocation checking, and InnoDB and BDB tables.
|
mysqld-opt | Optimized binary. From version 4.0 on, InnoDB is enabled. Before 4.0, this server includes no transactional table support.
|
mysqld-nt | Optimized binary for Windows NT, 2000, and XP with support for named pipes. |
mysqld-max | Optimized binary with support for InnoDB and BDB tables.
|
mysqld-max-nt | Like mysqld-max, but compiled with support for named pipes.
|
We have found that the server with the most generic name
(mysqld) is the one that many users are likely to choose
by default. However, that is also the server that results in the
highest memory and CPU use due to the inclusion of full debugging
support. The server named mysqld-opt is a better general-use
server choice to make instead if you don't need debugging support
and don't want the maximal feature set offered by the -max
servers or named pipe support offered by the -nt servers.
To make it less likely that the debugging server would be chosen
inadvertently, some name changes were made from MySQL 4.1.2 to
4.1.4: mysqld has been renamed to mysqld-debug
and mysqld-opt has been renamed to mysqld.
Thus, the server that includes debugging support indicates that in
its name, and the server named mysqld is an efficient
default choice. The other servers still have their same names. The
resulting servers are named like this:
| Binary | Description |
mysqld-debug | Compiled with full debugging and automatic memory allocation checking, and InnoDB and BDB tables.
|
mysqld | Optimized binary with InnoDB support.
|
mysqld-nt | Optimized binary for Windows NT, 2000, and XP with support for named pipes. |
mysqld-max | Optimized binary with support for InnoDB and BDB tables.
|
mysqld-max-nt | Like mysqld-max, but compiled with support for named pipes.
|
The name changes were not both instituted at the same time. If you
have MySQL 4.1.2 or 4.1.3, it might be that you have a server named
mysqld-debug but not one named mysqld. In this
case, you should have a server mysqld-opt, which you
should choose as your default server unless you need maximal features,
named pipes, or debugging support.
All of the preceding binaries are optimized for modern Intel processors, but should work on any Intel i386-class or higher processor.
As of MySQL 4.0, all Windows servers have support for symbolic linking of database directories. Before MySQL 4.0, only the debugging and Max server versions include this feature.
MySQL supports TCP/IP on all Windows platforms. The mysqld-nt
and mysql-max-nt servers support named pipes on Windows NT, 2000, XP, and 2003.
However, the default is to use TCP/IP regardless of the platform.
(Named pipes are slower than TCP/IP in many Windows configurations.)
Named pipe use is subject to these conditions:
--enable-named-pipe option.
It is necessary to use this option explicitly because some users have
experienced problems shutting down the MySQL server when named pipes
were used.
mysqld-nt or
mysqld-max-nt servers, and only if the server is run on a version
of Windows that supports named pipes (NT, 2000, XP, 2003).
Note:
Most of the examples in reference manual use mysqld as the
server name. If you choose to use a different server, such as
mysqld-nt, make the appropriate substitutions in the commands that
are shown in the examples.
On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. (This allows any machine on your network to connect to your MySQL server.) Because of this, you must make sure that TCP/IP support is installed on your machine before starting MySQL. You can find TCP/IP on your Windows CD-ROM.
Note that if you are using an old Windows 95 release (for example, OSR2), it's likely that you have an old Winsock package; MySQL requires Winsock 2! You can get the newest Winsock from http://www.microsoft.com/. Windows 98 has the new Winsock 2 library, so it is unnecessary to update the library.
On NT-based systems such as Windows NT, 2000, XP, or 2003, clients have two options. They can use TCP/IP, or they can use a named pipe if the server supports named pipe connections. To get MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3 (or newer).
In MySQL versions 4.1 and higher, Windows servers also support shared-memory
connections if started with the --shared-memory option. Clients can
connect through shared memory by using the --protocol=memory option.
For information about which server binary to run, see section 2.3.9 Selecting a MySQL Server type.
This section gives a general overview of starting the MySQL server. The following sections provide more specific information for starting the MySQL server from the command line or as a Windows service.
The examples in these sections assume that MySQL is installed under the default location of `C:\mysql'. Adjust the pathnames shown in the examples if you have MySQL installed in a different location.
Testing is best done from a command prompt in a console window (a ``DOS window''). This way you can have the server display status messages in the window where they are easy to see. If something is wrong with your configuration, these messages make it easier for you to identify and fix any problems.
To start the server, enter this command:
C:\> C:\mysql\bin\mysqld --console
For servers that include InnoDB support,
you should see the following messages as the server starts:
InnoDB: The first specified datafile c:\ibdata\ibdata1 did not exist: InnoDB: a new database to be created! InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200 InnoDB: Database physically writes the file full: wait... InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280 InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280 InnoDB: Doublewrite buffer not found: creating new InnoDB: Doublewrite buffer created InnoDB: creating foreign key constraint system tables InnoDB: foreign key constraint system tables created 011024 10:58:25 InnoDB: Started
When the server finishes its startup sequence, you should see something like this, which indicates that the server is ready to service client connections:
mysqld: ready for connections Version: '4.0.14-log' socket: '' port: 3306
The server continues to write to the console any further diagnostic output it produces. You can open a new console window in which to run client programs.
If you omit the --console option, the server writes diagnostic output
to the error log in the data directory (`C:\mysql\data' by default).
The error log is the file with the `.err' extension.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
The MySQL server can be started manually from the command line. This can be done on any version of Windows.
To start the mysqld server from the command line, you should
start a console window (a ``DOS window'') and enter this command:
C:\> C:\Program Files\MySQL\MySQL Server 4.1\bin\mysqld
The path used in the preceding example may vary depending on the install location of MySQL on your system.
On non-NT versions of Windows, this starts mysqld in the
background. That is, after the server starts, you should see another
command prompt. If you start the server this way on Windows NT, 2000, XP, or 2003,
the server runs in the foreground and no command prompt appears
until the server exits. Because of this, you should open another console
window to run client programs while the server is running.
You can stop the MySQL server by executing this command:
C:\> C:\Program Files\MySQL\MySQL Server 4.1\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to
connect to the server and tell it to shut down. The command connects as the
MySQL root user, which is the default administrative account in the
MySQL grant system. Note that users in the MySQL grant system are wholly
independent from any login users under Windows.
If mysqld doesn't start, check the error log to see whether the
server wrote any messages there to indicate the cause of the problem.
The error log is located in the `C:\mysql\data' directory. It is
the file with a suffix of `.err'. You can also try to start the
server as mysqld --console; in this case, you may get some useful
information on the screen that may help solve the problem.
The last option is to start mysqld with --standalone
--debug. In this case, mysqld writes a log file
`C:\mysqld.trace' that should contain the reason why mysqld
doesn't start. See section E.1.2 Creating Trace Files.
Use mysqld --verbose --help to display all the options that
mysqld understands. (Prior to MySQL 4.1, omit the
--verbose option.)
On the NT family (Windows NT, 2000, XP, 2003), the recommended way to
run MySQL is to install it as a Windows service. With the MySQL server
installed as a service, Windows starts and stops it server automatically
when Windows starts and stops. A MySQL server installed as a service can
also be controlled from the command line using NET commands,
or with the graphical Services utility.
The Services utility (the Windows Service Control Manager) can
be found in the Windows Control Panel (under Administrative
Tools on Windows 2000, XP, and Server 2003). It is advisable to close the
Services utility while performing server installation or removal
operations from this command line. This prevents some odd errors.
Before installing MySQL as a Windows service, you should first stop the current server if it is running by using the following command:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility mysqladmin to
connect to the server and tell it to shut down. The command connects as the
MySQL root user, which is the default administrative account in the
MySQL grant system. Note that users in the MySQL grant system are wholly
independent from any login users under Windows.
Install the server as a service using this command:
C:\> mysqld --install
If you have problems installing mysqld as a
service using just the server name, try installing it using its full pathname.
For example:
C:\> C:\mysql\bin\mysqld --install
The service-installation command does not start the server. Instructions for that are given later in this section.
Before MySQL 4.0.2, no command-line arguments can be given following the
--install option. MySQL 4.0.2 and up offers limited support for
additional arguments:
--install
option. The default service name is MySQL.
--defaults-file=file_name
to specify the name of an option file from which the server should read
options when it starts.
It is possible to use a single option other than --defaults-file, but
this is discouraged. --defaults-file is more flexible because it
enables you to specify multiple startup options for the server by placing
them in the named option file. Also, in MySQL 5.0, use of an option
different from --defaults-file is not supported until 5.0.3.
--local-service option
following the service name. This causes the server to run using the
LocalService Windows account that has limited system privileges.
This account is available only for Windows XP or newer. If both
--defaults-file and --local-service are given following the
service name, they can be in any order.
For a MySQL server that is installed as a Windows service, the following rules determine the service name and option files that the server uses:
MySQL) following the --install option,
the server uses the a service name of MySQL and reads options from
the [mysqld] group in the standard option files.
MySQL following the --install option, the server uses that
service name. It reads options from the group that has the same name as the
service, and reads options from the standard option files.
As of MySQL 4.0.17, the server also reads options from the [mysqld]
group from the standard option files. This allows you to use the
[mysqld] group for options that should be used by all MySQL services,
and an option group with the same name as a service for use by the server
installed with that service name.
--defaults-file
option after the service name, the server reads options only from the
[mysqld] group of the named file and ignores the standard option
files.
As a more complex example, consider the following command:
C:\> C:\mysql\bin\mysqld --install MySQL --defaults-file=C:\my-opts.cnf
Here, the default service name (MySQL) is given after the
--install option. If no --defaults-file option had been given,
this command would have the effect of causing the server to read the
[mysqld] group from the standard option files. However, because the
--defaults-file option is present, the server reads options from the
[mysqld] option group, but only from the named file.
You can also specify options as ``Start parameters'' in the
Windows Services utility before you start the MySQL service.
Note: Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its pathname or the service name contains spaces. For this reason, with older versions, avoid installing MySQL in a directory such as `C:\Program Files' or using a service name containing spaces.
Once a MySQL server has been installed as a service, Windows starts
the service automatically whenever Windows starts. The service also
can be started immediately from the Services utility, or by
using the command NET START MySQL. The NET command
is not case sensitive.
When run as a service, mysqld has no access to a console window,
so no messages can be seen there. If mysqld doesn't start, check
the error log to see whether the server wrote any messages there to indicate
the cause of the problem. The error log is located in the MySQL data
directory (for example, `C:\mysql\data'). It is the file with a suffix
of `.err'.
When a MySQL server has been installed as a service, and the service is
running, Windows stops the service automatically when Windows shuts down.
The server also can be stopped manually by using the Services
utility, the command NET STOP MySQL, or the command
mysqladmin shutdown.
From MySQL 3.23.44 on, you have the choice of installing the
server as a Manual service if you don't wish the service to
be started automatically during the boot process. To do this, use
the --install-manual option rather than the --install
option:
C:\> C:\mysql\bin\mysqld --install-manual
To remove a server that is installed as a service, first stop it if it is
running. Then use the --remove option to remove it:
C:\> C:\mysql\bin\mysqld --remove
For MySQL versions older than 3.23.49, one problem with automatic
MySQL service shutdown is that Windows waited only for a few
seconds for the shutdown to complete, then killed the database
server process if the time limit was exceeded. This had the potential
to cause problems. (For example, the InnoDB storage engine
would have to perform crash recovery at the next startup.) Starting from
MySQL 3.23.49, Windows waits longer for the MySQL server
shutdown to complete. If you notice this still is not enough for
your installation, it is safest not to run the MySQL server as a
service. Instead, start it from the command-line prompt, and stop
it with mysqladmin shutdown.
This change to tell Windows to wait longer when stopping the MySQL server
works for Windows 2000 and XP. It does not work for Windows NT, where Windows
waits only 20 seconds for a service to shut down, and after that kills the
service process. You can increase this default by opening the Registry
Editor `\winnt\system32\regedt32.exe' and editing the value of
WaitToKillServiceTimeout at
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
in the Registry tree. Specify the new larger value in milliseconds.
For example, the value 120000 tells Windows NT to wait up to 120 seconds.
If mysqld is not running as a service, you can start it
from the command line. For instructions, see section 2.3.11 Starting MySQL from the Windows Command Line.
Please see section 2.3.14 Troubleshooting a MySQL Installation Under Windows if you encounter difficulties during installation.
You can test whether the MySQL server is working by executing any of the following commands:
C:\> C:\mysql\bin\mysqlshow C:\> C:\mysql\bin\mysqlshow -u root mysql C:\> C:\mysql\bin\mysqladmin version status proc C:\> C:\mysql\bin\mysql test
If mysqld is slow to respond to TCP/IP connections from client
programs on Windows 9x/Me, there is probably a problem with your DNS. In
this case, start mysqld with the --skip-name-resolve option
and use only localhost and IP numbers in the Host column of
the MySQL grant tables.
You can force a MySQL client to use a named pipe connection rather than
TCP/IP by specifying the --pipe option or by specifying .
(period) as the host name. Use the --socket option to specify the
name of the pipe. As of MySQL 4.1, you can use the
--protocol=PIPE option instead.
There are two versions of the MySQL command-line tool on Windows:
| Binary | Description |
mysql | Compiled on native Windows, offering limited text editing capabilities. |
mysqlc | Compiled with the Cygnus GNU compiler and
libraries, which offers readline editing. mysqlc was
intended for use primarily with Windows 9x/Me. It does not support the
updated authentication protocol used beginning with MySQL 4.1, and is
not supported in MySQL 4.1 and above. Beginning with MySQL 4.1.8, it is
no longer included in MySQL Windows distributions.
|
To use mysqlc, you must have a copy of the `cygwinb19.dll'
library installed somewhere that mysqlc can find it. If your
distribution does not have the cygwinb19.dll library in the
`bin' directory under the base directory of your MySQL installation,
look for it in the lib directory and copy it to your Windows system
directory (`\Windows\system' or a similar place).
When installing and running MySQL for the first time, you may encounter certain errors that prevent the MySQL server from starting. The purpose of this section is to help you diagnose and correct some of these errors.
Your first resource when troubleshooting server issues is the error log. The MySQL server uses the error log to record information relevant to the error that is preventing the server from starting. The error log is located in the data directory specified in your `my.ini' file. The default data directory location is `C:\mysql\data'. See section 5.9.1 The Error Log.
Another source of information regarding possible errors is the console
messages displayed when the MySQL service is starting. Use the NET
START mysql command from the command line after installing mysqld as
a service to see any error messages regarding the starting of the MySQL
server as a service.
See section 2.3.12 Starting MySQL as a Windows Service.
The following are examples of some of the more common error messages you may encounter when installing MySQL and starting the server for the first time:
System error 1067 has occurred. Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't exist
These messages occur when the MySQL server cannot find the mysql
privileges database or other critical files. This error is often encountered
when the MySQL base or data directories are installed in different
locations than the default locations (`C:\mysql' and
`C:\mysql\data', respectively).
If you have installed MySQL to a directory other than `C:\mysql' you
need to ensure that the MySQL server is aware of this through the use of a
configuration (my.ini) file. The my.ini file needs to be
located in your Windows directory, typically located at `C:\WinNT' or
`C:\WINDOWS'. You can determine its exact location from the value of
the WINDIR environment variable by issuing the following command from
the command prompt:
C:\> echo %WINDIR%
An option file can be created and modified with any text editor,
such as the Notepad program. For example, if MySQL is installed at
`E:\mysql' and the data directory is located at `D:\MySQLdata',
you can create the option file and set up a [mysqld] section to specify
values for the basedir and datadir parameters:
[mysqld] # set basedir to your installation path basedir=E:/mysql # set datadir to the location of your data directory datadir=D:/MySQLdata
Note that Windows pathnames are specified in option files using forward slashes rather than backslashes. If you do use backslashes, you must double them:
[mysqld] # set basedir to your installation path basedir=C:\\Program Files\\mysql # set datadir to the location of your data directory datadir=D:\\MySQLdata
See section 2.3.8 Creating an Option File.
Error: Cannot create Windows service for MySql. Error: 0
This error is encountered when you re-install or upgrade MySQL without first stopping and removing the existing MySQL service and install MySQL using the MySQL Configuration Wizard. This happens because when the Configuration Wizard tries to install the service it finds an existing service with the same name.
One solution to this problem is to choose a service name other than mysql when
using the configuration wizard. This will allow the new service to be installed correctly,
but leaves the outdated service in place. While this is harmless it is best to remove old
services that are no longer in use.
To permanently remove the old mysql service, execute the following command as a user with administrative privileges, on the command-line:
C:\>sc delete mysql [SC] DeleteService SUCCESS
This section lists some of the steps you should take when upgrading MySQL on Windows.
C:\> NET STOP MySQLIf you are not running the MySQL server as a service, use the following command to stop the server:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
WinMySQLAdmin program if it is running.
C:\> C:\mysql\bin\mysqld --removeIf you do not remove the existing service, the MySQL Installation Wizard may fail to properly install the new MySQL service.
C:\mysql4. Overwriting the existing installation is recommended.
NET START MySQL if you run MySQL
as a service, or invoke mysqld directly otherwise.
MySQL for Windows has proven itself to be very stable. The Windows version of MySQL has the same features as the corresponding Unix version, with the following exceptions:
mysqld for an extended time on Windows 95 if your server handles
many connections! Other versions of Windows don't suffer from this bug.
pread() and pwrite() calls to be
able to mix INSERT and SELECT. Currently we use mutexes
to emulate pread()/pwrite(). We will, in the long run,
replace the file level interface with a virtual interface so that we can
use the readfile()/writefile() interface on NT, 2000, and XP to
get more speed.
The current implementation limits the number of open files MySQL can use to
2,048 (1,024 before MySQL 4.0.19), which means that you cannot
run as many concurrent threads on NT, 2000, XP, and 2003 as on Unix.
mysqladmin kill does not work on a sleeping connection.
mysqladmin shutdown can't abort as long as there are sleeping
connections.
ALTER TABLE
ALTER TABLE statement, the table is locked
from being used by other threads. This has to do with the fact that on Windows,
you can't delete a file that is in use by another thread. In the future,
we may find some way to work around this problem.
DROP TABLE
DROP TABLE on a table that is in use by a MERGE table does
not work on Windows because the MERGE handler does the table mapping
hidden from the upper layer of MySQL. Because Windows doesn't allow you
to drop files that are open, you first must flush all MERGE
tables (with FLUSH TABLES) or drop the MERGE table before
dropping the table. We will fix this at the same time we introduce
views.
DATA DIRECTORY and INDEX DIRECTORY
DATA DIRECTORY and INDEX DIRECTORY options for
CREATE TABLE are ignored on Windows, because Windows doesn't support
symbolic links. These options also are ignored on systems that have a
non-functional realpath() call.
DROP DATABASE
mysqladmin shutdown.
LOAD
DATA INFILE or SELECT ... INTO OUTFILE,
use Unix-style filenames with `/' characters:
mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;Alternatively, you must double the `\' character:
mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;
^Z / CHAR(24), Windows thinks it
has encountered end-of-file and aborts the program.
This is mainly a problem when you try to apply a binary log as follows:
C:\> mysqlbinlog binary-log-name | mysql --user=rootIf you have a problem applying the log and suspect that it is because of a
^Z / CHAR(24) character, you can use the following workaround:
C:\> mysqlbinlog binary-log-file --result-file=/tmp/bin.sql C:\> mysql --user=root --execute "source /tmp/bin.sql"The latter command also can be used to reliably read in any SQL file that may contain binary data.
Access denied for user error
Access denied
for user 'some-user'@'unknown' to database 'mysql', this means
that MySQL cannot resolve your hostname properly.
To fix this, you should create a file named `\windows\hosts' containing
the following information:
127.0.0.1 localhost
Here are some open issues for anyone who might want to help us improve MySQL on Windows:
MYSQL.DLL server. This should include everything in
a standard MySQL server, except thread creation. This makes
MySQL much easier to use in applications that don't need a true
client/server and don't need to access the server from other hosts.
mysqld from the Task Manager
in Windows 95. For the moment, you must use mysqladmin shutdown.
readline to Windows for use in the mysql command-line tool.
mysql,
mysqlshow, mysqladmin, and mysqldump) would be nice.
mysqladmin kill on Windows.
The recommended way to install MySQL on Linux is by using the RPM
packages. The MySQL RPMs are currently built on a SuSE Linux 7.3
system, but should work on most versions of Linux that support rpm
and use glibc.
To obtain RPM packages, see section 2.1.3 How to Get MySQL.
Note: RPM distributions of MySQL often are provided by other vendors. Be aware that they may differ in features and capabilities from those built by MySQL AB, and that the instructions in this manual do not necessarily apply to installing them. The vendor's instructions should be consulted instead.
If you have problems with an RPM file (for example, if you receive the error
``Sorry, the host 'xxxx' could not be looked up''), see
section 2.12.1.2 Linux Binary Distribution Notes.
In most cases, you only need to install the MySQL-server and
MySQL-client packages to get a functional MySQL installation. The
other packages are not required for a standard installation.
If you want to run a MySQL-Max server that has additional capabilities,
you should also install the MySQL-Max RPM. However, you should do so only
after installing the MySQL-server RPM.
See section 5.1.2 The mysqld-max Extended MySQL Server.
If you get a dependency failure when trying to install the MySQL 4.0
packages (for example, ``error: removing these packages would break dependencies:
libmysqlclient.so.10 is needed by ...''), you should also install
the package MySQL-shared-compat, which includes both the
shared libraries for backward compatibility (libmysqlclient.so.12
for MySQL 4.0 and libmysqlclient.so.10 for MySQL 3.23).
Many Linux distributions still ship with MySQL 3.23 and they usually link
applications dynamically to save disk space. If these shared libraries are
in a separate package (for example, MySQL-shared), it is
sufficient to simply leave this package installed and just upgrade
the MySQL server and client packages (which are statically linked
and do not depend on the shared libraries). For distributions that
include the shared libraries in the same package as the MySQL server
(for example, Red Hat Linux), you could either install our 3.23
MySQL-shared RPM, or use the MySQL-shared-compat package instead.
The following RPM packages are available:
MySQL-server-VERSION.i386.rpm
The MySQL server. You need this unless you only want to
connect to a MySQL server running on another machine. Note:
Server RPM files were called MySQL-VERSION.i386.rpm before
MySQL 4.0.10. That is, they did not have -server in the name.
MySQL-Max-VERSION.i386.rpm
The MySQL-Max server. This server has additional capabilities that the
one provided in the MySQL-server RPM does not. You must install the
MySQL-server RPM first, because the MySQL-Max RPM depends on it.
MySQL-client-VERSION.i386.rpm
The standard MySQL client programs. You probably always want to
install this package.
MySQL-bench-VERSION.i386.rpm
Tests and benchmarks. Requires Perl and the DBD::mysql module.
MySQL-devel-VERSION.i386.rpm
The libraries and include files that are needed if you want to compile other
MySQL clients, such as the Perl modules.
MySQL-shared-VERSION.i386.rpm
This package contains the shared libraries (libmysqlclient.so*)
that certain languages and applications need to dynamically load and
use MySQL.
MySQL-shared-compat-VERSION.i386.rpm
This package includes the shared libraries for both MySQL 3.23 and
MySQL 4.0. Install this package instead of MySQL-shared if you
have applications installed that are dynamically linked against MySQL
3.23 but you want to upgrade to MySQL 4.0 without breaking the library
dependencies. This package has been available since MySQL 4.0.13.
MySQL-embedded-VERSION.i386.rpm
The embedded MySQL server library (from MySQL 4.0).
MySQL-VERSION.src.rpm
This contains the source code for all of the previous packages. It can also
be used to rebuild the RPMs on other architectures (for example, Alpha or SPARC).
To see all files in an RPM package (for example, a MySQL-server
RPM), run:
shell> rpm -qpl MySQL-server-VERSION.i386.rpm
To perform a standard minimal installation, run:
shell> rpm -i MySQL-server-VERSION.i386.rpm shell> rpm -i MySQL-client-VERSION.i386.rpm
To install just the client package, run:
shell> rpm -i MySQL-client-VERSION.i386.rpm
RPM provides a feature to verify the integrity and authenticity of packages
before installing them. If you would like to learn more about this feature,
see section 2.1.4 Verifying Package Integrity Using MD5 Checksums or GnuPG.
The server RPM places data under the `/var/lib/mysql' directory. The
RPM also creates a login account for a user named mysql (if one does not
exist) to use for running the MySQL server, and
creates the appropriate entries in `/etc/init.d/' to start the
server automatically at boot time. (This means that if you have performed a
previous installation and have made changes to its startup script, you may
want to make a copy of the script so that you don't lose it when you install a
newer RPM.) See section 2.9.2.2 Starting and Stopping MySQL Automatically for more information on how MySQL can be
started automatically on system startup.
If you want to install the MySQL RPM on older Linux distributions that do not support initialization scripts in `/etc/init.d' (directly or via a symlink), you should create a symbolic link that points to the location where your initialization scripts actually are installed. For example, if that location is `/etc/rc.d/init.d', use these commands before installing the RPM to create `/etc/init.d' as a symbolic link that points there:
shell> cd /etc shell> ln -s rc.d/init.d .
However, all current major Linux distributions should support the new directory layout that uses `/etc/init.d', because it is required for LSB (Linux Standard Base) compliance.
If the RPM files that you install include MySQL-server, the
mysqld server should be up and running after installation.
You should be able to start using MySQL.
If something goes wrong, you can find more information in the binary installation section. See section 2.7 Installing MySQL on Other Unix-Like Systems.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2.x (``Jaguar'') and up using a Mac OS X binary package in PKG format instead of the binary tarball distribution. Please note that older versions of Mac OS X (for example, 10.1.x) are not supported by this package.
The package is located inside a disk image (.dmg) file that you
first need to mount by double-clicking its icon in the Finder. It should
then mount the image and display its contents.
To obtain MySQL, see section 2.1.3 How to Get MySQL.
Note: Before proceeding with the installation, be sure to
shut down all running MySQL server instances by either
using the MySQL Manager Application (on Mac OS X Server) or via
mysqladmin shutdown on the command line.
To actually install the MySQL PKG file, double-click on the package icon. This launches the Mac OS X Package Installer, which guides you through the installation of MySQL.
Due to a bug in the Mac OS X package installer, you may see this error message in the destination disk selection dialog:
You cannot install this software on this disk. (null)
If this error occurs, simply click the Go Back button once to return
to the previous screen. Then click Continue to advance to the
destination disk selection again, and you should be able to choose the
destination disk correctly. We have reported this bug to Apple and it is
investigating this problem.
The Mac OS X PKG of MySQL installs itself into
`/usr/local/mysql-VERSION' and also installs a symbolic link,
`/usr/local/mysql', pointing to the new location. If a directory named
`/usr/local/mysql' exists, it is renamed to
`/usr/local/mysql.bak' first. Additionally, the installer creates the
grant tables in the mysql database by executing mysql_install_db
after the installation.
The installation layout is similar to that of a tar file binary
distribution; all MySQL binaries are located in the directory
`/usr/local/mysql/bin'. The MySQL socket file is created as
`/tmp/mysql.sock' by default.
See section 2.1.5 Installation Layouts.
MySQL installation requires a Mac OS X user account named mysql. A
user account with this name should exist by default on Mac OS X 10.2 and up.
If you are running Mac OS X Server, you have a version of MySQL installed. The versions of MySQL that ship with Mac OS X Server versions are shown in the following table:
| Mac OS X Server Version | MySQL Version |
| 10.2-10.2.2 | 3.23.51 |
| 10.2.3-10.2.6 | 3.23.53 |
| 10.3 | 4.0.14 |
| 10.3.2 | 4.0.16 |
This manual section covers the installation of the official MySQL Mac OS X PKG only. Make sure to read Apple's help information about installing MySQL: Run the ``Help View'' application, select ``Mac OS X Server'' help, do a search for ``MySQL,'' and read the item entitled ``Installing MySQL.''
For pre-installed versions of MySQL on Mac OS X Server, note especially that
you should start mysqld with safe_mysqld instead of
mysqld_safe if MySQL is older than version 4.0.
If you previously used Marc Liyanage's MySQL packages for Mac OS X from http://www.entropy.ch, you can simply follow the update instructions for packages using the binary installation layout as given on his pages.
If you are upgrading from Marc's 3.23.xx versions or from the Mac OS X Server version of MySQL to the official MySQL PKG, you also need to convert the existing MySQL privilege tables to the current format, because some new security privileges have been added. See section 2.10.7 Upgrading the Grant Tables.
If you would like to automatically start up MySQL during system startup, you
also need to install the MySQL Startup Item. Starting with MySQL 4.0.15, it
is part of the Mac OS X installation disk images as a separate installation
package. Simply double-click the MySQLStartupItem.pkg icon and follow
the instructions to install it.
Note that the Startup Item need be installed only once! There is no need to install it each time you upgrade the MySQL package later.
The Startup Item is installed into
`/Library/StartupItems/MySQLCOM'. (Before MySQL 4.1.2, the location
was `/Library/StartupItems/MySQL', but that collided with the MySQL
Startup Item installed by Mac OS X Server.) Startup Item installation
adds a variable MYSQLCOM=-YES- to the system configuration file
`/etc/hostconfig'. If you would like to disable the automatic startup
of MySQL, simply change this variable to MYSQLCOM=-NO-.
On Mac OS X Server, the default MySQL installation uses the variable
MYSQL in the `/etc/hostconfig' file. The MySQL AB Startup Item
installer disables this variable by setting it to MYSQL=-NO-. This
avoids boot time conflicts with the MYSQLCOM variable used by the
MySQL AB Startup Item. However, it does not shut down a running
MySQL server. You should do that yourself.
After the installation, you can start up MySQL by running the following commands in a terminal window. You must have administrator privileges to perform this task.
If you have installed the Startup Item:
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start (Enter your password, if necessary) (Press Control-D or enter "exit" to exit the shell)
For versions of MySQL older than 4.1.3, substitute
/Library/StartupItems/MySQLCOM/MySQLCOM with
/Library/StartupItems/MySQL/MySQL above.
If you don't use the Startup Item, enter the following command sequence:
shell> cd /usr/local/mysql shell> sudo ./bin/mysqld_safe (Enter your password, if necessary) (Press Control-Z) shell> bg (Press Control-D or enter "exit" to exit the shell)
You should be able to connect to the MySQL server, for example, by running `/usr/local/mysql/bin/mysql'.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
You might want to add aliases to your shell's resource file to make it easier
to access commonly used programs such as mysql and mysqladmin
from the command line. The syntax for tcsh is:
alias mysql /usr/local/mysql/bin/mysql alias mysqladmin /usr/local/mysql/bin/mysqladmin
For bash, use:
alias mysql=/usr/local/mysql/bin/mysql alias mysqladmin=/usr/local/mysql/bin/mysqladmin
Even better,
add /usr/local/mysql/bin to
your PATH environment variable. For example, add the following
line to your `$HOME/.tcshrc' file if your shell is tcsh:
setenv PATH ${PATH}:/usr/local/mysql/bin
If no `.tcshrc' file exists in your home directory, create it with a text editor.
If you are upgrading an existing installation, please note that installing a new MySQL PKG does not remove the directory of an older installation. Unfortunately, the Mac OS X Installer does not yet offer the functionality required to properly upgrade previously installed packages.
To use your existing databases with the new installation, you'll need to copy the contents of the old data directory to the new data directory. Make sure that neither the old server nor the new one is running when you do this. After you have copied over the MySQL database files from the previous installation and have successfully started the new server, you should consider removing the old installation files to save disk space. Additionally, you should also remove older versions of the Package Receipt directories located in `/Library/Receipts/mysql-VERSION.pkg'.
Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers should be pleased to note that NetWare 6.5 ships with bundled MySQL binaries, complete with an automatic commercial use license for all servers running that version of NetWare.
MySQL for NetWare is compiled using a combination of Metrowerks
CodeWarrior for NetWare and special cross-compilation versions of the
GNU autotools.
The latest binary packages for NetWare can be obtained at http://dev.mysql.com/downloads/. See section 2.1.3 How to Get MySQL.
In order to host MySQL, the NetWare server must meet these requirements:
To install MySQL for NetWare, use the following procedure:
SERVER: mysqladmin -u root shutdown
SERVER: SEARCH ADD SYS:MYSQL\BIN
mysql_install_db at the server console.
mysqld_safe at the server console.
autoexec.ncf. For example, if your MySQL installation is in
`SYS:MYSQL' and you want MySQL to start automatically, you could
add these lines:
#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFEIf you are running MySQL on NetWare 6.0, we strongly suggest that you use the
--skip-external-locking option on the command line:
#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --skip-external-lockingIt is also necessary to use
CHECK TABLE and REPAIR
TABLE instead of myisamchk, because myisamchk makes use
of external locking. External locking is known to have problems on
NetWare 6.0; the problem has been eliminated in NetWare 6.5.
mysqld_safe on NetWare provides a screen presence. When you unload
(shut down) the mysqld_safe NLM, the screen does not by default go
away. Instead, it prompts for user input:
*<NLM has terminated; Press any key to close the screen>*If you want NetWare to close the screen automatically instead, use the
--autoclose option to mysqld_safe. For example:
#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --autoclose
The behavior of mysqld_safe on NetWare is described further in
section 5.1.3 The mysqld_safe Server Startup Script.
If there was an existing installation of MySQL on the server, be sure
to check for existing MySQL startup commands in autoexec.ncf,
and edit or delete them as necessary.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
This section covers the installation of MySQL binary distributions that are
provided for various platforms in the form of compressed tar files
(files with a .tar.gz extension). See section 2.1.2.5 MySQL Binaries Compiled by MySQL AB for a
detailed list.
To obtain MySQL, see section 2.1.3 How to Get MySQL.
MySQL tar file binary distributions have names of the form
`mysql-VERSION-OS.tar.gz', where VERSION is a number (for
example, 4.0.17), and OS indicates the type of operating
system for which the distribution is intended (for example,
pc-linux-i686).
In addition to these generic packages, we also offer binaries in platform-specific package formats for selected platforms. See section 2.2 Standard MySQL Installation Using a Binary Distribution for more information on how to install these.
You need the following tools to install a MySQL tar file binary
distribution:
gunzip to uncompress the distribution.
tar to unpack the distribution. GNU tar is known
to work. Some operating systems come with a pre-installed version of
tar that is known to have problems. For example, Mac OS X tar
and Sun tar are known to have problems with long filenames. On Mac
OS X, you can use the pre-installed gnutar program. On other systems
with a deficient tar, you should install GNU tar first.
If you run into problems, please always use mysqlbug when
posting questions to a MySQL mailing list. Even if the problem
isn't a bug, mysqlbug gathers system information that helps others
solve your problem. By not using mysqlbug, you lessen the likelihood
of getting a solution to your problem. You can find mysqlbug in the
`bin' directory after you unpack the distribution. See section 1.4.1.3 How to Report Bugs or Problems.
The basic commands you must execute to install and use a MySQL binary distribution are:
shell> groupadd mysql shell> useradd -g mysql mysql shell> cd /usr/local shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysql shell> cd mysql shell> scripts/mysql_install_db --user=mysql shell> chown -R root . shell> chown -R mysql data shell> chgrp -R mysql . shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld
for bin/mysqld_safe in the final command.
Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to section 2.9 Post-Installation Setup and Testing.
A more detailed version of the preceding description for installing a binary distribution follows:
mysqld to run as:
shell> groupadd mysql shell> useradd -g mysql mysqlThese commands add the
mysql group and the mysql user. The
syntax for useradd and groupadd may differ slightly on different
versions of Unix. They may also be called adduser and addgroup.
You might want to call the user and group something else instead
of mysql. If so, substitute the appropriate name in the
following steps.
root.)
shell> cd /usr/local
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysqlThe
tar command creates a directory named
`mysql-VERSION-OS'. The
ln command makes a symbolic link to that directory. This lets you refer
more easily to the installation directory as `/usr/local/mysql'.
With GNU tar, no separate invocation of gunzip is necessary.
You can replace the first line with the following
alternative command to uncompress and extract the distribution:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
shell> cd mysqlYou can find several files and subdirectories in the
mysql directory.
The most important for installation purposes are the `bin' and
`scripts' subdirectories.
PATH environment variable so that your shell finds the MySQL
programs properly. See section F Environment Variables.
mysql_install_db script used to initialize
the mysql database containing the grant tables that store the server
access permissions.
shell> scripts/mysql_install_db --user=mysqlIf you run the command as
root, you should use the --user
option as shown. The value of the option should be the name of the login
account that you created in the first step to use for running the server.
If you run the command while logged in as that user, you can omit the
--user option.
Note that for MySQL versions older than 3.22.10,
mysql_install_db left the server running after creating the grant
tables. This is no longer true; you need to restart the server after
performing the remaining steps in this procedure.
root and ownership of the
data directory to the user that you run mysqld as. Assuming
that you are located in the installation directory
(`/usr/local/mysql'), the commands look like this:
shell> chown -R root . shell> chown -R mysql data shell> chgrp -R mysql .The first command changes the owner attribute of the files to the
root user. The second changes the owner attribute of the
data directory to the mysql user. The third changes the
group attribute to the mysql group.
support-files/mysql.server to the location where
your system has its startup files. More information can be found in the
support-files/mysql.server script itself and in
section 2.9.2.2 Starting and Stopping MySQL Automatically.
bin/mysql_setpermission script if
you install the DBI and DBD::mysql Perl modules.
For instructions, see section 2.13 Perl Installation Notes.
mysqlaccess and have the MySQL
distribution in some non-standard place, you must change the location where
mysqlaccess expects to find the mysql client. Edit the
`bin/mysqlaccess' script at approximately line 18. Search for a line
that looks like this:
$MYSQL = '/usr/local/bin/mysql'; # path to mysql executableChange the path to reflect the location where
mysql actually is
stored on your system. If you do not do this, you get a Broken
pipe error when you run mysqlaccess.
After everything has been unpacked and installed, you should test your distribution.
You can start the MySQL server with the following command:
shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld
for bin/mysqld_safe in the command.
More information about mysqld_safe is given in
section 5.1.3 The mysqld_safe Server Startup Script.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
Before you proceed with the source installation, check first to see whether our binary is available for your platform and whether it works for you. We put a lot of effort into making sure that our binaries are built with the best possible options.
To obtain a source distribution for MySQL, section 2.1.3 How to Get MySQL.
MySQL source distributions are provided as compressed tar
archives and have names of the form `mysql-VERSION.tar.gz', where
VERSION is a number like 4.1.11.
You need the following tools to build and install MySQL from source:
gunzip to uncompress the distribution.
tar to unpack the distribution. GNU tar is known
to work. Some operating systems come with a pre-installed version of
tar that is known to have problems. For example, Mac OS X tar
and Sun tar are known to have problems with long filenames. On Mac
OS X, you can use the pre-installed gnutar program. On other systems
with a deficient tar, you should install GNU tar first.
gcc 2.95.2 or later, egcs 1.0.2
or later or egcs 2.91.66, SGI C++, and SunPro C++ are some of the
compilers that are known to work. libg++ is not needed when
using gcc. gcc 2.7.x has a bug that makes it impossible
to compile some perfectly legal C++ files, such as
`sql/sql_base.cc'. If you have only gcc 2.7.x, you must
upgrade your gcc to be able to compile MySQL. gcc
2.8.1 is also known to have problems on some platforms, so it should be
avoided if a new compiler exists for the platform.
gcc 2.95.2 or later is recommended when compiling MySQL
3.23.x.
make program. GNU make is always recommended and is
sometimes required. If you have problems, we recommend trying GNU
make 3.75 or newer.
If you are using a version of gcc recent enough to understand the
-fno-exceptions option, it is very important that you use
this option. Otherwise, you may compile a binary that crashes randomly. We also
recommend that you use -felide-constructors and -fno-rtti along
with -fno-exceptions. When in doubt, do the following:
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
-fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static
On most systems, this gives you a fast and stable binary.
If you run into problems, please always use mysqlbug when
posting questions to a MySQL mailing list. Even if the problem
isn't a bug, mysqlbug gathers system information that helps others
solve your problem. By not using mysqlbug, you lessen the likelihood
of getting a solution to your problem. You can find mysqlbug in the
`scripts' directory after you unpack the distribution.
See section 1.4.1.3 How to Report Bugs or Problems.
The basic commands you must execute to install a MySQL source distribution are:
shell> groupadd mysql shell> useradd -g mysql mysql shell> gunzip < mysql-VERSION.tar.gz | tar -xvf - shell> cd mysql-VERSION shell> ./configure --prefix=/usr/local/mysql shell> make shell> make install shell> cp support-files/my-medium.cnf /etc/my.cnf shell> cd /usr/local/mysql shell> bin/mysql_install_db --user=mysql shell> chown -R root . shell> chown -R mysql var shell> chgrp -R mysql . shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute bin/safe_mysqld
for bin/mysqld_safe in the final command.
If you start from a source RPM, do the following:
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm
This makes a binary RPM that you can install. For older versions of RPM,
you may have to replace the command rpmbuild with rpm instead.
Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to section 2.9 Post-Installation Setup and Testing, for post-installation setup and testing.
A more detailed version of the preceding description for installing MySQL from a source distribution follows:
mysqld to run as:
shell> groupadd mysql shell> useradd -g mysql mysqlThese commands add the
mysql group and the mysql user. The
syntax for useradd and groupadd may differ slightly on different
versions of Unix. They may also be called adduser and addgroup.
You might want to call the user and group something else instead
of mysql. If so, substitute the appropriate name in the
following steps.
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -This command creates a directory named `mysql-VERSION'. With GNU
tar, no separate invocation of gunzip is necessary.
You can use the following alternative command to uncompress and extract
the distribution:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
shell> cd mysql-VERSIONNote that currently you must configure and build MySQL from this top-level directory. You cannot build it in a different directory.
shell> ./configure --prefix=/usr/local/mysql shell> makeWhen you run
configure, you might want to specify some options.
Run ./configure --help for a list of options.
section 2.8.2 Typical configure Options, discusses some of the
more useful options.
If configure fails and you are going to send mail to a MySQL mailing
list to ask for assistance, please include any
lines from `config.log' that you think can help solve the problem. Also
include the last couple of lines of output from configure.
Post the bug report using the mysqlbug
script. See section 1.4.1.3 How to Report Bugs or Problems.
If the compile fails, see section 2.8.4 Dealing with Problems Compiling MySQL for help.
shell> make installIf you want to set up an option file, use one of those present in the `support-files' directory as a template. For example:
shell> cp support-files/my-medium.cnf /etc/my.cnfYou might need to run these commands as
root.
If you want to configure support for InnoDB tables, you should edit the
/etc/my.cnf file, remove the # character before the
option lines that start with innodb_..., and modify the option values
to be what you want.
See section 4.3.2 Using Option Files
and section 15.4 InnoDB Configuration.
shell> cd /usr/local/mysql
shell> bin/mysql_install_db --user=mysqlIf you run the command as
root, you should use the --user
option as shown. The value of the option should be the name of the login
account that you created in the first step to use for running the server.
If you run the command while logged in as that user, you can omit the
--user option.
Note that for MySQL versions older than 3.22.10,
mysql_install_db left the server running after creating the grant
tables. This is no longer true; you need to restart the server after
performing the remaining steps in this procedure.
root and ownership of the
data directory to the user that you run mysqld as. Assuming
that you are located in the installation directory
(`/usr/local/mysql'), the commands look like this:
shell> chown -R root . shell> chown -R mysql var shell> chgrp -R mysql .The first command changes the owner attribute of the files to the
root user. The second changes the owner attribute of the
data directory to the mysql user. The third changes the
group attribute to the mysql group.
support-files/mysql.server to the location where
your system has its startup files. More information can be found in the
support-files/mysql.server script itself and in
section 2.9.2.2 Starting and Stopping MySQL Automatically.
bin/mysql_setpermission script if
you install the DBI and DBD::mysql Perl modules.
For instructions, see section 2.13 Perl Installation Notes.
After everything has been installed, you should initialize and test your distribution using this command:
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute safe_mysqld
for mysqld_safe in the command.
If that command fails immediately and prints mysqld ended, you can
find some information in the `host_name.err' file in the data directory.
More information about mysqld_safe is given in
section 5.1.3 The mysqld_safe Server Startup Script.
Note: The accounts that are listed in the MySQL grant tables initially have no passwords. After starting the server, you should set up passwords for them using the instructions in section 2.9 Post-Installation Setup and Testing.
configure Options
The configure script gives you a great deal of control over how
you configure a MySQL source distribution. Typically you do this
using options on the configure command line. You can also affect
configure using certain environment variables. See section F Environment Variables. For a list of options supported by configure, run
this command:
shell> ./configure --help
Some of the more commonly used configure options are described here:
--without-server option:
shell> ./configure --without-serverIf you don't have a C++ compiler,
mysql cannot be compiled (it is the
one client program that requires C++). In this case,
you can remove the code in configure that tests for the C++ compiler
and then run ./configure with the --without-server option. The
compile step should still try to build mysql, but you can ignore any
warnings about `mysql.cc'. (If make stops, try make -k
to tell it to continue with the rest of the build even if errors occur.)
libmysqld.a) you should
use the --with-embedded-server option.
configure command something like one
of these:
shell> ./configure --prefix=/usr/local/mysql
shell> ./configure --prefix=/usr/local \
--localstatedir=/usr/local/mysql/data
The first command changes the installation prefix so that everything is
installed under `/usr/local/mysql' rather than the default of
`/usr/local'. The second command preserves the default installation
prefix, but overrides the default location for database directories
(normally `/usr/local/var') and changes it to
/usr/local/mysql/data. After you have compiled MySQL, you can
change these options with option files. See section 4.3.2 Using Option Files.
configure command like this:
shell> ./configure \
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock
The socket filename must be an absolute pathname.
You can also change the location of `mysql.sock' later by using a MySQL
option file. See section A.4.5 How to Protect or Change the MySQL Socket File `/tmp/mysql.sock'.
configure like this:
shell> ./configure --with-client-ldflags=-all-static \
--with-mysqld-ldflags=-all-static
gcc and don't have libg++ or libstdc++
installed, you can tell configure to use gcc as your C++
compiler:
shell> CC=gcc CXX=gcc ./configureWhen you use
gcc as your C++ compiler, it does not attempt to link in
libg++ or libstdc++. This may be a good idea to do even if you
have these libraries installed, because some versions of them have
caused strange problems for MySQL users in the past.
The following list indicates some compilers and environment variable settings
that are commonly used with each one.
gcc 2.7.2:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
egcs 1.0.3a:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors \ -fno-exceptions -fno-rtti"
gcc 2.95.2:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \ -felide-constructors -fno-exceptions -fno-rtti"
pgcc 2.90.29 or newer:
CFLAGS="-O3 -mpentiumpro -mstack-align-double" CXX=gcc \ CXXFLAGS="-O3 -mpentiumpro -mstack-align-double \ -felide-constructors -fno-exceptions -fno-rtti"
configure line:
--prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-staticThe full
configure line would, in other words, be something like the
following for all recent gcc versions:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \ -felide-constructors -fno-exceptions -fno-rtti" ./configure \ --prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-staticThe binaries we provide on the MySQL Web site at http://www.mysql.com/ are all compiled with full optimization and should be perfect for most users. See section 2.1.2.5 MySQL Binaries Compiled by MySQL AB. There are some configuration settings you can tweak to make an even faster binary, but these are only for advanced users. See section 7.5.4 How Compiling and Linking Affects the Speed of MySQL. If the build fails and produces errors about your compiler or linker not being able to create the shared library `libmysqlclient.so.#' (where `#' is a version number), you can work around this problem by giving the
--disable-shared option to configure. In this case,
configure does not build a shared `libmysqlclient.so.#' library.
latin1 (ISO-8859-1) character set. To
change the default set, use the --with-charset option:
shell> ./configure --with-charset=CHARSETCHARSET may be one of
big5, cp1251, cp1257,
czech, danish, dec8, dos, euc_kr,
gb2312, gbk, german1, hebrew, hp8,
hungarian, koi8_ru, koi8_ukr, latin1,
latin2, sjis, swe7, tis620, ujis,
usa7, or win1251ukr.
See section 5.8.1 The Character Set Used for Data and Sorting.
As of MySQL 4.1.1, the default collation may also be specified. MySQL uses
the latin1_swedish_ci collation. To change this, use the
--with-collation option:
shell> ./configure --with-collation=COLLATIONTo change both the character set and the collation, use both the
--with-charset and --with-collation options.
The collation must be a legal collation for the character set.
(Use the SHOW COLLATION statement to determine which collations are
available for each character set.)
If you want to convert characters between the server and the client,
you should take a look at the SET CHARACTER SET statement.
See section 13.5.3 SET Syntax.
Warning: If you change character sets after having created any
tables, you have to run myisamchk -r -q --set-character-set=charset
on every table. Your
indexes may be sorted incorrectly otherwise. (This can happen if you
install MySQL, create some tables, then reconfigure
MySQL to use a different character set and reinstall it.)
With the configure option --with-extra-charsets=LIST, you can
define which additional character sets should be compiled into the server.
LIST is either a list of character set names separated by spaces,
complex to include all character sets that can't be dynamically loaded,
or all to include all character sets into the binaries.
--with-debug
option:
shell> ./configure --with-debugThis causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. See section E.1 Debugging a MySQL Server.
--enable-thread-safe-client configure option. This creates a
libmysqlclient_r library with which you should link your threaded
applications. See section 22.2.15 How to Make a Threaded Client.
--with-big-tables option, beginning with the following MySQL versions:
unsigned long long rather than unsigned long. What this does
is to allow tables to hold up to approximately 1.844E+19 ((2^32)^2) rows rather
than 4G rows. Previously it was necessary to pass -DBIG_TABLES to the
compiler manually in order to enable this feature.
Caution: You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL up and running on your system, you should use a standard release distribution (either a binary or source distribution).
To obtain our most recent development source tree, use these instructions:
shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23To clone the 4.0 stable (production) branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0To clone the 4.1 stable (production) branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1To clone the 5.0 development branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0In the preceding examples, the source tree is set up in the `mysql-3.23/', `mysql-4.0/', `mysql-4.1/', or `mysql-5.0/' subdirectory of your current directory. If you are behind a firewall and can only initiate HTTP connections, you can also use BitKeeper via HTTP. If you are required to use a proxy server, set the environment variable
http_proxy to point to your proxy:
shell> export http_proxy="http://your.proxy.server:8080/"Replace the
bk:// with http:// when doing
a clone. Example:
shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1The initial download of the source tree may take a while, depending on the speed of your connection. Please be patient.
make, autoconf 2.58 (or newer),
automake 1.8, libtool 1.5, and m4 to run the next
set of commands. Even though many operating systems come with their
own implementation of make, chances are high that the compilation
fails with strange error messages. Therefore, it is highly recommended
that you use GNU make (sometimes named gmake) instead.
Fortunately, a large number of operating systems ship with the GNU
toolchain preinstalled or supply installable packages of these. In any case,
they can also be downloaded from the following locations:
bison 1.75 or later. Older versions of bison may report this
error:
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceededNote: The maximum table size is not actually exceeded; the error is caused by bugs in older versions of
bison.
Versions of MySQL before version 4.1 may also compile with other
yacc implementations (for example, BSD yacc 91.7.30). For later
versions, GNU bison is required.
The following example shows the typical commands required to configure a
source tree. The first cd command changes location into the top-level
directory of the tree; replace `mysql-4.0' with the appropriate directory
name.
shell> cd mysql-4.0 shell> bk -r edit shell> aclocal; autoheader; autoconf; automake shell> (cd innobase; aclocal; autoheader; autoconf; automake) shell> (cd bdb/dist; sh s_all) shell> ./configure # Add your favorite options here makeThe command lines that change directory into the `innobase' and `bdb/dist' directories are used to configure the
InnoDB and
Berkeley DB (BDB) storage engines. You can omit these command lines if
you to not require InnoDB or BDB support.
If you get some strange errors during this stage, verify that you really
have libtool installed.
A collection of our standard configuration scripts is located in the
`BUILD/' subdirectory. You may find it more convenient to use the
`BUILD/compile-pentium-debug' script than the preceding set of
shell commands. To compile on a different architecture,
modify the script by removing flags that are Pentium-specific.
make install. Be careful with this
on a production machine; the command may overwrite your live release
installation. If you have another installation of MySQL, we
recommend that you run ./configure with different values for the
--prefix, --with-tcp-port, and --unix-socket-path options
than those used for your production server.
make test. See section 25.1.2 MySQL Test Suite.
make stage and the distribution does
not compile, please report it in our bugs database at
http://bugs.mysql.com/. If you
have installed the latest versions of the required GNU tools, and they
crash trying to process our configuration files, please report that also.
However, if you execute aclocal and get a command not found
error or a similar problem, do not report it. Instead, make sure that all
the necessary tools are installed and that your PATH variable is
set correctly so that your shell can find them.
bk clone operation to obtain the source tree, you
should run bk pull periodically to get updates.
bk revtool. If you see some funny diffs or code that you have a
question about, do not hesitate to send email to the MySQL internals
mailing list.
See section 1.4.1.1 The MySQL Mailing Lists.
Also, if you think you have a better idea
on how to do something, send an email message to the same address with a patch.
bk diffs produces a patch for you after you have made changes
to the source. If you do not have the time to code your idea, just send
a description.
bk helptool.
bk ci or bk citool)
triggers the posting of a message with the changeset to our internals
mailing list, as well as the usual openlogging.org submission with
just the changeset comments.
Generally, you wouldn't need to use commit (since the public tree does
not allow bk push), but rather use the bk diffs method
described previously.
You can also browse changesets, comments, and source code online. For example, to browse this information for MySQL 4.1, go to http://mysql.bkbits.net:8080/mysql-4.1.
The manual is in a separate tree that can be cloned with:
shell> bk clone bk://mysql.bkbits.net/mysqldoc mysqldoc
There are also public BitKeeper trees for MySQL Control Center and MyODBC. They can be cloned respectively as follows.
To clone MySQL Control center, use this command:
shell> bk clone http://mysql.bkbits.net/mysqlcc mysqlcc
To clone MyODBC, use this command:
shell> bk clone http://mysql.bkbits.net/myodbc3 myodbc3
To clone Connector/NET, use this command:
shell> bk clone http://mysql.bkbits.net/connector-net connector-net
All MySQL programs compile cleanly for us with no warnings on
Solaris or Linux using gcc. On other systems, warnings may occur due to
differences in system include files. See section 2.8.5 MIT-pthreads Notes for warnings
that may occur when using MIT-pthreads. For other problems, check
the following list.
The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of the following:
configure is run after it has previously been run, it may use
information that was gathered during its previous invocation. This
information is stored in `config.cache'. When configure starts
up, it looks for that file and reads its contents if it exists, on the
assumption that the information is still correct. That assumption is invalid
when you reconfigure.
configure, you must run make again
to recompile. However, you may want to remove old object files from previous
builds first because they were compiled using different configuration options.
To prevent old configuration information or object files from being used,
run these commands before re-running configure:
shell> rm config.cache shell> make clean
Alternatively, you can run make distclean.
The following list describes some of the problems when compiling MySQL that have been found to occur most often:
Internal compiler error: program cc1plus got fatal signal 11 Out of virtual memory Virtual memory exhaustedThe problem is that
gcc requires a huge amount of memory to compile
`sql_yacc.cc' with inline functions. Try running configure with
the --with-low-memory option:
shell> ./configure --with-low-memoryThis option causes
-fno-inline to be added to the compile line if you
are using gcc and -O0 if you are using something else. You
should try the --with-low-memory option even if you have so much
memory and swap space that you think you can't possibly have run out. This
problem has been observed to occur even on systems with generous hardware
configurations and the --with-low-memory option usually fixes it.
configure picks c++ as the compiler name and
GNU c++ links with -lg++. If you are using gcc,
that behavior can cause problems during configuration such as this:
configure: error: installation or configuration problem: C++ compiler cannot create executables.You might also observe problems during compilation related to
g++, libg++, or libstdc++.
One cause of these problems is that you may not have g++, or you may
have g++ but not libg++, or libstdc++. Take a look at
the `config.log' file. It should contain the exact reason why your C++
compiler didn't work. To work around these problems, you can use gcc
as your C++ compiler. Try setting the environment variable CXX to
"gcc -O3". For example:
shell> CXX="gcc -O3" ./configureThis works because
gcc compiles C++ sources as well as g++
does, but does not link in libg++ or libstdc++ by default.
Another way to fix these problems is to install g++,
libg++, and libstdc++. We would, however, like to recommend
that you not use libg++ or libstdc++ with MySQL because this
only increases the binary size of mysqld without giving you any benefits.
Some versions of these libraries have also caused strange problems for
MySQL users in the past.
Using gcc as the C++ compiler is also required if you want to
compile MySQL with RAID functionality (see section 13.2.6 CREATE TABLE Syntax for more info
on RAID table type) and you are using GNU gcc version 3 and above. If
you get errors like those following during the linking stage when you
configure MySQL to compile with the option --with-raid, try to use
gcc as your C++ compiler by defining the CXX environment
variable:
gcc -O3 -DDBUG_OFF -rdynamic -o isamchk isamchk.o sort.o libnisam.a ../mysys/libmysys.a ../dbug/libdbug.a ../strings/libmystrings.a -lpthread -lz -lcrypt -lnsl -lm -lpthread ../mysys/libmysys.a(raid.o)(.text+0x79): In function `my_raid_create':: undefined reference to `operator new(unsigned)' ../mysys/libmysys.a(raid.o)(.text+0xdd): In function `my_raid_create':: undefined reference to `operator delete(void*)' ../mysys/libmysys.a(raid.o)(.text+0x129): In function `my_raid_open':: undefined reference to `operator new(unsigned)' ../mysys/libmysys.a(raid.o)(.text+0x189): In function `my_raid_open':: undefined reference to `operator delete(void*)' ../mysys/libmysys.a(raid.o)(.text+0x64b): In function `my_raid_close':: undefined reference to `operator delete(void*)' collect2: ld returned 1 exit status
make to GNU make:
making all in mit-pthreads make: Fatal error in reader: Makefile, line 18: Badly formed macro assignmentOr:
make: file `Makefile' line 18: Must be a separator (:Or:
pthread.h: No such file or directorySolaris and FreeBSD are known to have troublesome
make programs.
GNU make Version 3.75 is known to work.
CFLAGS and CXXFLAGS environment
variables. You can also specify the compiler names this way using CC
and CXX. For example:
shell> CC=gcc shell> CFLAGS=-O3 shell> CXX=gcc shell> CXXFLAGS=-O3 shell> export CC CFLAGS CXX CXXFLAGSSee section 2.1.2.5 MySQL Binaries Compiled by MySQL AB, for a list of flag definitions that have been found to be useful on various systems.
gcc compiler:
client/libmysql.c:273: parse error before `__attribute__'
gcc 2.8.1 is known to work, but we recommend using gcc 2.95.2 or
egcs 1.0.3a instead.
mysqld,
configure didn't correctly detect the type of the last argument to
accept(), getsockname(), or getpeername():
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
type of the pointer value ''length'' is ''unsigned long'',
which is not compatible with ''int''.
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);
To fix this, edit the `config.h' file (which is generated by
configure). Look for these lines:
/* Define as the base type of the last arg to accept */ #define SOCKET_SIZE_TYPE XXXChange
XXX to size_t or int, depending on your
operating system. (Note that you have to do this each time you run
configure because configure regenerates `config.h'.)
"sql_yacc.yy", line xxx fatal: default action causes potential...This is a sign that your version of
yacc is deficient.
You probably need to install bison (the GNU version of yacc)
and use that instead.
gawk instead of the default
mawk if you want to compile MySQL 4.1 or higher with Berkeley DB
support.
mysqld or a MySQL client, run
configure with the --with-debug option, then recompile and
link your clients with the new client library. See section E.2 Debugging a MySQL Client.
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from incompatible pointer type libmysql.c:1329: too few arguments to function `gethostbyname_r' libmysql.c:1329: warning: assignment makes pointer from integer without a cast make[2]: *** [libmysql.lo] Error 1By default, the
configure script attempts to determine the correct
number of arguments by using g++ the GNU C++ compiler. This test
yields wrong results if g++ is not installed. There are two ways
to work around this problem:
g++ is installed. On some Linux
distributions, the required package is called gpp; on others, it
is named gcc-c++.
gcc as your C++ compiler by setting the CXX environment
variable to gcc:
export CXX="gcc"
configure again afterward.
This section describes some of the issues involved in using MIT-pthreads.
On Linux, you should not use MIT-pthreads. Use the installed LinuxThreads implementation instead. See section 2.12.1 Linux Notes.
If your system does not provide native thread support, you need to build MySQL using the MIT-pthreads package. This includes older FreeBSD systems, SunOS 4.x, Solaris 2.4 and earlier, and some others. See section 2.1.1 Operating Systems Supported by MySQL.
Beginning with MySQL 4.0.2, MIT-pthreads is no longer part of the source distribution. If you require this package, you need to download it separately from http://www.mysql.com/Downloads/Contrib/pthreads-1_60_beta6-mysql.tar.gz
After downloading, extract this source archive into the top level of the
MySQL source directory. It creates a new subdirectory named
mit-pthreads.
configure with the --with-mit-threads option:
shell> ./configure --with-mit-threadsBuilding in a non-source directory is not supported when using MIT-pthreads because we want to minimize our changes to this code.
--without-server
to build only the client code, clients do not know whether
MIT-pthreads is being used and use Unix socket connections by default.
Because Unix socket files do not work under MIT-pthreads on some platforms, this
means you need to use -h or --host when you run client
programs.
--external-locking option. This is needed
only if you want to be able to run two MySQL servers against the same data
files, which is not recommended.
bind() command fails to bind to a socket without
any error message (at least on Solaris). The result is that all connections
to the server fail. For example:
shell> mysqladmin version mysqladmin: connect to server at '' failed; error: 'Can't connect to mysql server on localhost (146)'The solution to this is to kill the
mysqld server and restart it.
This has only happened to us when we have forced down the server and done
a restart immediately.
sleep() system call isn't interruptible with
SIGINT (break). This is only noticeable when you run
mysqladmin --sleep. You must wait for the sleep() call to
terminate before the interrupt is served and the process stops.
ld: warning: symbol `_iob' has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
ld: warning: symbol `__iob' has differing sizes:
(file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4;
file /usr/lib/libc.so value=0x140);
/my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
implicit declaration of function `int strtoll(...)' implicit declaration of function `int strtoul(...)'
readline to work with MIT-pthreads. (This isn't
needed, but may be interesting for someone.)
These instructions describe how to build MySQL binaries from source for versions 4.1 and above on Windows. Instructions are provided for building binaries from a standard source distribution or from the BitKeeper tree that contains the latest development source.
Note: The instructions in this document are strictly for users who want to test MySQL on Windows from the latest source distribution or from the BitKeeper tree. For production use, MySQL AB does not advise using a MySQL server built by yourself from source. Normally, it is best to use precompiled binary distributions of MySQL that are built specifically for optimal performance on Windows by MySQL AB. Instructions for installing a binary distributions are available at section 2.3 Installing MySQL on Windows.
To build MySQL on Windows from source, you need the following compiler and resources available on your Windows system:
You'll also need a MySQL source distribution for Windows. There are two ways you can get a source distribution for MySQL version 4.1 and above:
If you are using a Windows source distribution, you can go directly to section 2.8.6.1 Building MySQL Using VC++. To build from the BitKeeper tree, proceed to section 2.8.6.2 Creating a Windows Source Package from the Latest Development Source.
If you find something not working as expected, or you have
suggestions about ways to improve the current build process
on Windows, please send a message to the win32 mailing list.
See section 1.4.1.1 The MySQL Mailing Lists.
Note: VC++ workspace files for MySQL 4.1 and above are compatible with Microsoft Visual Studio 6.0 and above (7.0/.NET) editions and tested by MySQL AB staff before each release.
Follow this procedure to build MySQL:
WinZip or other Windows tool that can read `.zip' files.
File menu, select Open Workspace.
Build menu,
select the Set Active Configuration menu.
mysqld - Win32 Debug
and click OK.
F7 to begin the build of the debug server, libraries, and
some client applications.
Build All option from the Build menu.
--basedir and --datadir
options, or place appropriate options in an option file (the `my.ini'
file in your Windows directory or `C:\my.cnf'). If you have
an existing data directory elsewhere that you want to use, you can
specify its pathname instead.
mysql
interactive command-line utility that exists in your `client_release'
or `client_debug' directory.
When you are satisfied that the programs you have built are working correctly, stop the server. Then install MySQL as follows:
C:\> mkdir C:\mysql C:\> mkdir C:\mysql\bin C:\> mkdir C:\mysql\data C:\> mkdir C:\mysql\share C:\> mkdir C:\mysql\scriptsIf you want to compile other clients and link them to MySQL, you should also create several additional directories:
C:\> mkdir C:\mysql\include C:\> mkdir C:\mysql\lib C:\> mkdir C:\mysql\lib\debug C:\> mkdir C:\mysql\lib\optIf you want to benchmark MySQL, create this directory:
C:\> mkdir C:\mysql\sql-benchBenchmarking requires Perl support.
C:\mysql directory the
following directories:
C:\> cd \workdir C:\workdir> copy client_release\*.exe C:\mysql\bin C:\workdir> copy client_debug\mysqld.exe C:\mysql\bin\mysqld-debug.exe C:\workdir> xcopy scripts\*.* C:\mysql\scripts /E C:\workdir> xcopy share\*.* C:\mysql\share /EIf you want to compile other clients and link them to MySQL, you should also copy several libraries and header files:
C:\workdir> copy lib_debug\mysqlclient.lib C:\mysql\lib\debug C:\workdir> copy lib_debug\libmysql.* C:\mysql\lib\debug C:\workdir> copy lib_debug\zlib.* C:\mysql\lib\debug C:\workdir> copy lib_release\mysqlclient.lib C:\mysql\lib\opt C:\workdir> copy lib_release\libmysql.* C:\mysql\lib\opt C:\workdir> copy lib_release\zlib.* C:\mysql\lib\opt C:\workdir> copy include\*.h C:\mysql\include C:\workdir> copy libmysql\libmysql.def C:\mysql\includeIf you want to benchmark MySQL, you should also do this:
C:\workdir> xcopy sql-bench\*.* C:\mysql\bench /E
Set up and start the server in the same way as for the binary Windows distribution. See section 2.3 Installing MySQL on Windows.
To create a Windows source package from the current BitKeeper source tree, use the following instructions. Please note that this procedure must be performed on a system running a Unix or Unix-like operating system. For example, the procedure is known to work well on Linux.
shell> ./BUILD/compile-pentium-max
shell> ./scripts/make_win_src_distributionThis script creates a Windows source package to be used on your Windows system. You can supply different options to the script based on your needs. It accepts the following options:
--help
--debug
--tmp
--suffix
--dirname
--silent
--tar
make_win_src_distribution creates a Zip-format
archive with the name `mysql-VERSION-win-src.zip', where
VERSION represents the version of your MySQL source tree.
In your source files, you should include `my_global.h' before `mysql.h':
#include <my_global.h> #include <mysql.h>
`my_global.h' includes any other files needed for Windows compatibility (such as `windows.h') if you compile your program on Windows.
You can either link your code with the dynamic `libmysql.lib' library, which is just a wrapper to load in `libmysql.dll' on demand, or link with the static `mysqlclient.lib' library.
The MySQL client libraries are compiled as threaded libraries, so you should also compile your code to be multi-threaded.
After installing MySQL, there are some issues you should address. For example, on Unix, you should initialize the data directory and create the MySQL grant tables. On all platforms, an important security concern is that the initial accounts in the grant tables have no passwords. You should assign passwords to prevent unauthorized access to the MySQL server. For MySQL 4.1.3 and up, you can create time zone tables to enable recognition of named time zones. (Currently, these tables can be populated only on Unix. This problem will be addressed soon for Windows.)
The following sections include post-installation procedures that are specific to Windows systems and to Unix systems. Another section, section 2.9.2.3 Starting and Troubleshooting the MySQL Server, applies to all platforms; it describes what to do if you have trouble getting the server to start. section 2.9.3 Securing the Initial MySQL Accounts also applies to all platforms. You should follow its instructions to make sure that you have properly protected your MySQL accounts by assigning passwords to them.
When you are ready to create additional user accounts, you can find information on the MySQL access control system and account management in section 5.5 The MySQL Access Privilege System and section 5.6 MySQL User Account Management.
On Windows, the data directory and the grant tables do not have to be
created. MySQL Windows distributions include the grant tables with a set of
preinitialized accounts in the mysql database under the
data directory. You do not run the mysql_install_db script that
is used on Unix. However, if you did not install MySQL using the Windows Installation Wizard,
you should assign passwords to the accounts. See section 2.3.4.1 Introduction.
The procedure for this is given in section 2.9.3 Securing the Initial MySQL Accounts.
Before setting up passwords, you might want to try running some client programs to make sure that you can connect to the server and that it is operating properly. Make sure the server is running (see section 2.3.10 Starting the Server for the First Time), then issue the following commands to verify that you can retrieve information from the server. The output should be similar to what is shown here:
C:\> C:\mysql\bin\mysqlshow +-----------+ | Databases | +-----------+ | mysql | | test | +-----------+ C:\> C:\mysql\bin\mysqlshow mysql Database: mysql +--------------+ | Tables | +--------------+ | columns_priv | | db | | func | | host | | tables_priv | | user | +--------------+ C:\> C:\mysql\bin\mysql -e "SELECT Host,Db,User FROM db" mysql +------+-------+------+ | host | db | user | +------+-------+------+ | % | test% | | +------+-------+------+
If you are running a version of Windows that supports services and you want the MySQL server to run automatically when Windows starts, see section 2.3.12 Starting MySQL as a Windows Service.
After installing MySQL on Unix, you need to initialize the grant tables, start the server, and make sure that the server works okay. You may also wish to arrange for the server to be started and stopped automatically when your system starts and stops. You should also assign passwords to the accounts in the grant tables.
On Unix, the grant tables are set up by the mysql_install_db program.
For some installation methods, this program is run for you automatically:
mysql_install_db.
mysql_install_db.
Otherwise, you'll need to run mysql_install_db yourself.
The following procedure describes how to initialize the grant tables (if that has not previously been done) and then start the server. It also suggests some commands that you can use to test whether the server is accessible and working properly. For information about starting and stopping the server automatically, see section 2.9.2.2 Starting and Stopping MySQL Automatically.
After you complete the procedure and have the server running, you should
assign passwords to the accounts created by mysql_install_db.
Instructions for doing so are given in section 2.9.3 Securing the Initial MySQL Accounts.
In the examples shown here, the server runs under the user ID of the
mysql login account. This assumes that such an account exists.
Either create the account if it does not exist, or substitute the name of a
different existing login account that you plan to use for running the
server.
shell> cd BASEDIRBASEDIR is likely to be something like `/usr/local/mysql' or `/usr/local'. The following steps assume that you are located in this directory.
mysql_install_db program to set up the initial
MySQL grant tables containing the privileges that determine how users are
allowed to connect to the server. You'll need to do this if you used a
distribution type that doesn't run the program for you.
Typically, mysql_install_db needs to be run only the first time you
install MySQL, so you can skip this step if you are upgrading an existing
installation, However, mysql_install_db does not overwrite any
existing privilege tables, so it should be safe to run in any circumstances.
To initialize the grant tables, use one of the following commands,
depending on whether mysql_install_db is located in the bin
or scripts directory:
shell> bin/mysql_install_db --user=mysql shell> scripts/mysql_install_db --user=mysqlThe
mysql_install_db script creates the data directory, the
mysql database that holds all database privileges, and the test
database that you can use to test MySQL. The script also creates privilege
table entries for root accounts and anonymous-user accounts.
The accounts have no passwords initially. A description of their initial
privileges is given in section 2.9.3 Securing the Initial MySQL Accounts. Briefly, these privileges
allow the MySQL root user to do anything, and allow anybody to create
or use databases with a name of test or starting with test_.
It is important to make sure that the database directories and files are
owned by the mysql login account so that the server has read and
write access to them when you run it later. To ensure this, the --user
option should be used as shown if you run mysql_install_db as
root. Otherwise, you should execute the script while logged in as
mysql, in which case you can omit the --user option from the
command.
mysql_install_db creates several tables in the mysql database:
user, db, host, tables_priv,
columns_priv, func, and possibly others depending on your
version of MySQL.
If you don't want to have the test database, you can remove it with
mysqladmin -u root drop test after starting the server.
If you have problems with mysql_install_db, see
section 2.9.2.1 Problems Running mysql_install_db.
There are some alternatives to running the mysql_install_db
script as it is provided in the MySQL distribution:
mysql_install_db before you run it.
However, a preferable technique is to use GRANT and REVOKE to
change the privileges after the grant tables have been set up. In other
words, you can run mysql_install_db, and then use mysql -u root
mysql to connect to the server as the MySQL root user so that you
can issue the GRANT and REVOKE statements.
If you want to install MySQL on a lot of machines with the
same privileges, you can put the GRANT and REVOKE statements in
a file and execute the file as a script using mysql after running
mysql_install_db. For example:
shell> bin/mysql_install_db --user=mysql shell> bin/mysql -u root < your_script_fileBy doing this, you can avoid having to issue the statements manually on each machine.
GRANT and REVOKE and have made so many modifications
after running mysql_install_db that you want to wipe out the tables
and start over.
To re-create the grant tables, remove all the `.frm', `.MYI', and
`.MYD' files in the directory containing the mysql database.
(This is the directory named `mysql' under the data directory, which is
listed as the datadir value when you run mysqld --help.) Then
run the mysql_install_db script again.
Note: For MySQL versions older than 3.22.10, you should not
delete the `.frm' files. If you accidentally do this, you should copy
them back into the `mysql' directory from your MySQL distribution
before running mysql_install_db.
mysqld manually using the --skip-grant-tables
option and add the privilege information yourself using mysql:
shell> bin/mysqld_safe --user=mysql --skip-grant-tables & shell> bin/mysql mysqlFrom
mysql, manually execute the SQL commands contained in
mysql_install_db. Make sure that you run mysqladmin
flush-privileges or mysqladmin reload afterward to tell the server to
reload the grant tables.
Note that by not using mysql_install_db, you not only have to
populate the grant tables manually, you also have to create them first.
shell> bin/mysqld_safe --user=mysql &For versions of MySQL older than 4.0, substitute
bin/safe_mysqld
for bin/mysqld_safe in this command.
It is important that the MySQL server be run using an unprivileged
(non-root) login account. To ensure this, the --user
option should be used as shown if you run mysql_safe as
root. Otherwise, you should execute the script while logged in as
mysql, in which case you can omit the --user option from the
command.
Further instructions for running MySQL as an unprivileged user are given in
section A.3.2 How to Run MySQL as a Normal User.
If you neglected to create the grant tables before proceeding to this step,
the following message appears in the error log file when you start the
server:
mysqld: Can't find file: 'host.frm'If you have other problems starting the server, see section 2.9.2.3 Starting and Troubleshooting the MySQL Server.
mysqladmin to verify that the server is running. The following
commands provide simple tests to check whether the server is up and responding
to connections:
shell> bin/mysqladmin version shell> bin/mysqladmin variablesThe output from
mysqladmin version varies slightly depending on your
platform and version of MySQL, but should be similar to that shown here:
shell> bin/mysqladmin version mysqladmin Ver 8.40 Distrib 4.0.18, for linux on i586 Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB This software comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to modify and redistribute it under the GPL license Server version 4.0.18-log Protocol version 10 Connection Localhost via Unix socket TCP port 3306 UNIX socket /tmp/mysql.sock Uptime: 16 sec Threads: 1 Questions: 9 Slow queries: 0 Opens: 7 Flush tables: 2 Open tables: 0 Queries per second avg: 0.000 Memory in use: 132K Max memory used: 16773KTo see what else you can do with
mysqladmin,
invoke it with the --help option.
shell> bin/mysqladmin -u root shutdown
mysqld_safe or
by invoking mysqld directly. For example:
shell> bin/mysqld_safe --user=mysql --log &If
mysqld_safe fails, see section 2.9.2.3 Starting and Troubleshooting the MySQL Server.
shell> bin/mysqlshow +-----------+ | Databases | +-----------+ | mysql | | test | +-----------+ shell> bin/mysqlshow mysql Database: mysql +--------------+ | Tables | +--------------+ | columns_priv | | db | | func | | host | | tables_priv | | user | +--------------+ shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql +------+--------+------+ | host | db | user | +------+--------+------+ | % | test | | | % | test_% | | +------+--------+------+
DBI DBD::mysql Data::Dumper Data::ShowTableThese modules can be obtained from CPAN (http://www.cpan.org/). See section 2.13.1 Installing Perl on Unix. The `sql-bench/Results' directory contains the results from many runs against different databases and platforms. To run all tests, execute these commands:
shell> cd sql-bench shell> perl run-all-testsIf you don't have the `sql-bench' directory, you probably installed MySQL using RPM files other than the source RPM. (The source RPM includes the `sql-bench' benchmark directory.) In this case, you must first install the benchmark suite before you can use it. Beginning with MySQL 3.22, there are separate benchmark RPM files named `mysql-bench-VERSION-i386.rpm' that contain benchmark code and data. If you have a source distribution, there are also tests in its `tests' subdirectory that you can run. For example, to run `auto_increment.tst', execute this command from the top-level directory of your source distribution:
shell> mysql -vvf test < ./tests/auto_increment.tstThe expected result of the test can be found in the `./tests/auto_increment.res' file.
As of MySQL 4.1.3, the installation procedure creates time zone tables
in the mysql database. However, you must populate the tables manually.
Instructions to do this are given in section 5.8.8 MySQL Server Time Zone Support.
mysql_install_db
The purpose of the mysql_install_db script is to generate new MySQL
privilege tables. It does not overwrite existing MySQL privilege tables,
and it does not affect any other data.
If you want to re-create your privilege tables, first stop
the mysqld server if it's running. Then rename the `mysql'
directory under the data directory to save it, and then run
mysql_install_db. For example:
shell> mv mysql-data-directory/mysql mysql-data-directory/mysql-old shell> mysql_install_db --user=mysql
This section lists problems you might encounter when you run
mysql_install_db:
mysql_install_db doesn't install the grant tables
mysql_install_db fails to install the grant
tables and terminates after displaying the following messages:
Starting mysqld daemon with databases from XXXXXX mysqld endedIn this case, you should examine the error log file very carefully. The log should be located in the directory `XXXXXX' named by the error message, and should indicate why
mysqld didn't start. If you don't understand
what happened, include the log when you post a bug report.
See section 1.4.1.3 How to Report Bugs or Problems.
mysqld process running
mysql_install_db at all because it need be run only once (when you
install MySQL the first time).
mysqld server doesn't work when one server is running
Can't start server: Bind on TCP/IP port: Address already in use Can't start server: Bind on unix socket...For instructions on setting up multiple servers, see section 5.10 Running Multiple MySQL Servers on the Same Machine.
mysql_install_db or the mysqld server.
You can specify different temporary directory and Unix socket file locations
by executing these commands prior to starting mysql_install_db or
mysqld:
shell> TMPDIR=/some_tmp_dir/ shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysql.sock shell> export TMPDIR MYSQL_UNIX_PORT`some_tmp_dir' should be the full pathname to some directory for which you have write permission. After this, you should be able to run
mysql_install_db and start
the server with these commands:
shell> bin/mysql_install_db --user=mysql shell> bin/mysqld_safe --user=mysql &If
mysql_install_db is located in the `scripts' directory,
modify the first command to use scripts/mysql_install_db.
See section A.4.5 How to Protect or Change the MySQL Socket File `/tmp/mysql.sock'.
See section F Environment Variables.
Generally, you start the mysqld server in one of these ways:
mysqld directly. This works on any platform.
mysqld_safe, which tries to determine the proper options
for mysqld and then runs it with those options. This script is
used on systems based on BSD Unix.
See section 5.1.3 The mysqld_safe Server Startup Script.
mysql.server. This script is used primarily at
system startup and shutdown on systems that use System V-style run
directories, where it usually is installed under the name mysql.
The mysql.server script starts the server by invoking mysqld_safe.
See section 5.1.4 The mysql.server Server Startup Script.
mysql.server.
See section 2.5 Installing MySQL on Mac OS X for details.
The mysql.server and mysqld_safe scripts and the Mac OS X
Startup Item can be used to start the server manually, or automatically at
system startup time. mysql.server and the Startup Item also can be
used to stop the server.
To start or stop the server manually using the mysql.server script,
invoke it with start or stop arguments:
shell> mysql.server start shell> mysql.server stop
Before mysql.server starts the server, it changes location to the
MySQL installation directory, and then invokes mysqld_safe. If you
want the server to run as some specific user, add an appropriate user
option to the [mysqld] group of the `/etc/my.cnf' option file,
as shown later in this section.
(It is possible that you'll need to edit mysql.server
if you've installed a binary distribution of MySQL in a non-standard
location. Modify it to cd into the proper directory before it runs
mysqld_safe. If you do this, your modified version of
mysql.server may be overwritten if you upgrade MySQL in the future,
so you should make a copy of your edited version that you can reinstall.)
mysql.server stop brings down the server by sending a signal to it.
You can also stop the server manually by executing mysqladmin
shutdown.
To start and stop MySQL automatically on your server, you need to add start and stop commands to the appropriate places in your `/etc/rc*' files.
If you use the Linux server RPM package (MySQL-server-VERSION.rpm),
the mysql.server script is installed in the
`/etc/init.d' directory with the name `mysql'. You need not
install it manually. See section 2.4 Installing MySQL on Linux for more information on the Linux
RPM packages.
Some vendors provide RPM packages that install a startup script under a
different name such as mysqld.
If you install MySQL from a source distribution or using a binary
distribution format that does not install mysql.server automatically,
you can install it manually. The script can be found in the
`support-files' directory under the MySQL installation directory or in
a MySQL source tree.
To install mysql.server manually, copy it to the `/etc/init.d'
directory with the name mysql, and then make it executable. Do this
by changing location into the appropriate directory where
mysql.server is located and executing these commands:
shell> cp mysql.server /etc/init.d/mysql shell> chmod +x /etc/init.d/mysql
Older Red Hat systems use the `/etc/rc.d/init.d' directory rather than `/etc/init.d'. Adjust the preceding commands accordingly. Alternatively, first create `/etc/init.d' as a symbolic link that points to `/etc/rc.d/init.d':
shell> cd /etc shell> ln -s rc.d/init.d .
After installing the script, the commands needed to activate it to run
at system startup depend on your operating system. On Linux, you can use
chkconfig:
shell> chkconfig --add mysql
On some Linux systems, the following command also seems to be necessary to
fully enable the mysql script:
shell> chkconfig --level 345 mysql on
On FreeBSD, startup scripts generally should go in
`/usr/local/etc/rc.d/'. The rc(8) manual page states that
scripts in this directory are executed only if their basename matches the
*.sh shell filename pattern. Any other files or directories present
within the directory are silently ignored. In other words, on FreeBSD, you
should install the `mysql.server' script as
`/usr/local/etc/rc.d/mysql.server.sh' to enable automatic startup.
As an alternative to the preceding setup, some operating systems also use `/etc/rc.local' or `/etc/init.d/boot.local' to start additional services on startup. To start up MySQL using this method, you could append a command like the one following to the appropriate startup file:
/bin/sh -c 'cd /usr/local/mysql; ./bin/mysqld_safe --user=mysql &'
For other systems, consult your operating system documentation to see how to install startup scripts.
You can add options for mysql.server in a global
`/etc/my.cnf' file. A typical `/etc/my.cnf' file might look like
this:
[mysqld] datadir=/usr/local/mysql/var socket=/var/tmp/mysql.sock port=3306 user=mysql [mysql.server] basedir=/usr/local/mysql
The mysql.server script understands the following options:
basedir, datadir, and pid-file. If specified, they
must be placed in an option file, not on the command line.
mysql.server understands only start and stop as
command-line arguments.
The following table shows which option groups the server and each startup script read from option files:
| Script | Option Groups |
mysqld | [mysqld], [server], [mysqld-major-version]
|
mysql.server | [mysqld], [mysql.server]
|
mysqld_safe | [mysqld], [server], [mysqld_safe]
|
[mysqld-major-version] means that groups with names like
[mysqld-4.0], [mysqld-4.1], and [mysqld-5.0] are
read by servers having versions 4.0.x, 4.1.x, 5.0.x, and so forth. This
feature was added in MySQL 4.0.14. It can be used to specify options that can
be read only by servers within a given release series.
For backward compatibility, mysql.server also reads the
[mysql_server] group and mysqld_safe also reads the
[safe_mysqld] group. However, you should update your option
files to use the [mysql.server] and [mysqld_safe] groups instead
when you begin using MySQL 4.0 or later.
See section 4.3.2 Using Option Files.
If you have problems starting the server, here are some things you can try:
Some storage engines have options that control their behavior.
You can create a `my.cnf' file and set startup options
for the engines you plan to use.
If you are going to use storage engines that support transactional tables
(InnoDB, BDB), be sure that you have them configured the
way you want before starting the server:
InnoDB tables, refer to the InnoDB-specific
startup options. In MySQL 3.23, you must configure InnoDB explicitly
or the server fails to start. From MySQL 4.0 on, InnoDB uses default
values for its configuration options if you specify none.
See section 15.4 InnoDB Configuration.
BDB (Berkeley DB) tables, you should familiarize
yourself with the different BDB-specific startup options.
See section 14.4.3 BDB Startup Options.
When the mysqld server starts, it changes location to the data
directory. This is where it expects to find databases and where it expects
to write log files. On Unix, the server also writes the pid (process ID)
file in the data directory.
The data directory location is hardwired in when the server is compiled.
This is where the server looks for the data directory by default. If
the data directory is located somewhere else on your system, the server does
not work properly. You can find out what the default path settings are by
invoking mysqld with the --verbose and --help options.
(Prior to MySQL 4.1, omit the --verbose option.)
If the defaults don't match the MySQL installation layout on your system,
you can override them by specifying options on the command line to
mysqld or mysqld_safe. You can also list the options in an
option file.
To specify the location of the data directory explicitly, use the
--datadir option. However, normally you can tell mysqld the
location of the base directory under which MySQL is installed and it looks
for the data directory there. You can do this with the --basedir
option.
To check the effect of specifying path options, invoke mysqld with
those options followed by the --verbose and --help options.
For example, if you change location into the directory where mysqld is
installed, and then run the following command, it
shows the effect of starting the server with a base
directory of `/usr/local':
shell> ./mysqld --basedir=/usr/local --verbose --help
You can specify other options such as --datadir as well, but note
that --verbose and --help must be the last options. (Prior to
MySQL 4.1, omit the --verbose option.)
Once you determine the path settings you want, start the server without
--verbose and --help.
If mysqld is currently running, you can find out what path settings
it is using by executing this command:
shell> mysqladmin variables
Or:
shell> mysqladmin -h host_name variables
host_name is the name of the MySQL server host.
If you get Errcode 13 (which means Permission denied) when
starting mysqld, this means that the access privileges of the data
directory or its contents do not allow the server access. In this case, you
change the permissions for the involved files and directories so that the
server has the right to use them. You can also start the server as
root, but this can raise security issues and should be avoided.
On Unix, change location into the data directory and check the ownership of the data directory and its contents to make sure the server has access. For example, if the data directory is `/usr/local/mysql/var', use this command:
shell> ls -la /usr/local/mysql/var
If the data directory or its files or subdirectories are not owned by the account that you use for running the server, change their ownership to that account:
shell> chown -R mysql /usr/local/mysql/var shell> chgrp -R mysql /usr/local/mysql/var
If the server fails to start up correctly, check the error log file to
see if you can find out why. Log files are located in the data directory
(typically `C:\mysql\data' on Windows, `/usr/local/mysql/data'
for a Unix binary distribution, and `/usr/local/var' for a Unix source
distribution). Look in the data directory for files with names of the form
`host_name.err' and `host_name.log', where host_name is the
name of your server host. (Older servers on Windows use `mysql.err'
as the error log name.) Then check the last few lines of these files.
On Unix, you can use tail to display the last few lines:
shell> tail host_name.err shell> tail host_name.log
The error log contains information that indicates why the server couldn't start. For example, you might see something like this in the log:
000729 14:50:10 bdb: Recovery function for LSN 1 27595 failed 000729 14:50:10 bdb: warning: ./test/t1.db: No such file or directory 000729 14:50:10 Can't init databases
This means that you didn't start mysqld with the
--bdb-no-recover option and Berkeley DB found something wrong with
its own log files when it tried to recover your databases. To be able to
continue, you should move away the old Berkeley DB log files from the
database directory to some other place, where you can later examine them.
The BDB log files are named in sequence beginning with
`log.0000000001', where the number increases over time.
If you are running mysqld with BDB table support and
mysqld dumps core at startup, this could be due to problems with the
BDB recovery log. In this case, you can try starting mysqld
with --bdb-no-recover. If that helps, then you should remove
all BDB log files from the data directory and try starting mysqld
again without the --bdb-no-recover option.
If either of the following errors occur, it means that some other program
(perhaps another mysqld server) is using the TCP/IP port or
Unix socket file that mysqld is trying to use:
Can't start server: Bind on TCP/IP port: Address already in use Can't start server: Bind on unix socket...
Use ps to determine whether you have another mysqld server
running. If so, shut down the server before starting mysqld again.
(If another server is running, and you really want to run multiple servers,
you can find information about how to do so in section 5.10 Running Multiple MySQL Servers on the Same Machine.)
If no other server is running, try to execute the command telnet
your-host-name tcp-ip-port-number. (The default MySQL port number is
3306.) Then press Enter a couple of times. If you don't get an error
message like telnet: Unable to connect to remote host: Connection
refused, some other program is using the TCP/IP port that mysqld is
trying to use. You'll need to track down what program this is and disable
it, or else tell mysqld to listen to a different port with the
--port option. In this case, you'll also need to specify the port
number for client programs when connecting to the server via TCP/IP.
Another reason the port might be inaccessible is that you have a firewall running that blocks connections to it. If so, modify the firewall settings to allow access to the port.
If the server starts but you can't connect to it, you should make sure that you have an entry in `/etc/hosts' that looks like this:
127.0.0.1 localhost
This problem occurs only on systems that don't have a working thread library and for which MySQL must be configured to use MIT-pthreads.
If you can't get mysqld to start, you can try to make a trace file
to find the problem by using the --debug option.
See section E.1.2 Creating Trace Files.
See section 2.3.14 Troubleshooting a MySQL Installation Under Windows, for more information on troubleshooting Windows installations.
Part of the MySQL installation process is to set up the mysql database
containing the grant tables:
mysql_install_db
program. Some installation methods run this program for you. Others require
that you execute it manually. For details, see section 2.9.2 Unix Post-Installation Procedures.
The grant tables define the initial MySQL user accounts and their access privileges. These accounts are set up as follows:
root. These are
superuser accounts that can do anything. The initial root account
passwords are empty, so anyone can connect to the MySQL server as root
without a password and be granted all privileges.
root account is for connecting from the local host
and the other allows connections from any host.
root accounts are for connections from the local host.
Connections must be made from the local host by specifying a hostname of
localhost for one account, or the actual hostname or IP number for
the other.
root accounts.
The other is for connections from any host and has all privileges for the
test database or other databases with names that start with test.
localhost for one account, or the actual hostname or IP number for
the other. These accounts have all privileges for the test database
or other databases with names that start with test_.
As noted, none of the initial accounts have passwords. This means that your MySQL installation is unprotected until you do something about it:
root accounts.
The following instructions describe how to set up passwords for the
initial MySQL accounts, first for the anonymous accounts and then for the
root accounts. Replace ``newpwd'' in the examples with the
actual password that you want to use. The instructions also cover how
to remove the anonymous accounts, should you prefer not to allow anonymous
access at all.
You might want to defer setting the passwords until later, so that you don't need to specify them while you perform additional setup or testing. However, be sure to set them before using your installation for any real production work.
To assign passwords to the anonymous accounts, you can use either
SET PASSWORD or UPDATE. In both cases, be sure to encrypt the
password using the PASSWORD() function.
To use SET PASSWORD on Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'%' = PASSWORD('newpwd');
To use SET PASSWORD on Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace host_name
with the name of the server host. This is the name that is specified in
the Host column of the non-localhost record for root
in the user table. If you don't know what hostname this is, issue
the following statement before using SET PASSWORD:
mysql> SELECT Host, User FROM mysql.user;
Look for the record that has root in the User column and
something other than localhost in the Host column. Then use that
Host value in the second SET PASSWORD statement.
The other way to assign passwords to the anonymous accounts is by using
UPDATE to modify the user table directly. Connect to the
server as root and issue an UPDATE statement that assigns a
value to the Password column of the appropriate user table
records. The procedure is the same for Windows and Unix. The following
UPDATE statement assigns a password to both anonymous accounts at
once:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
-> WHERE User = '';
mysql> FLUSH PRIVILEGES;
After you update the passwords in the user table directly using
UPDATE, you must tell the server to re-read the grant tables with
FLUSH PRIVILEGES. Otherwise, the change goes unnoticed until you
restart the server.
If you prefer to remove the anonymous accounts instead, do so as follows:
shell> mysql -u root mysql> DELETE FROM mysql.user WHERE User = ''; mysql> FLUSH PRIVILEGES;
The DELETE statement applies both to Windows and to Unix.
On Windows, if you want to remove only the anonymous account that has the same
privileges as root, do this instead:
shell> mysql -u root mysql> DELETE FROM mysql.user WHERE Host='localhost' AND User=''; mysql> FLUSH PRIVILEGES;
This account allows anonymous access but has full privileges, so removing it improves security.
You can assign passwords to the root accounts in several ways. The
following discussion demonstrates three methods:
SET PASSWORD statement
mysqladmin command-line client program
UPDATE statement
To assign passwords using SET PASSWORD, connect to the server as
root and issue two SET PASSWORD statements.
Be sure to encrypt the password using the PASSWORD() function.
For Windows, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
For Unix, do this:
shell> mysql -u root
mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd');
mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD statement, replace host_name with
the name of the server host. This is the same hostname that you used when
you assigned the anonymous account passwords.
To assign passwords to the root accounts using mysqladmin,
execute the following commands:
shell> mysqladmin -u root password "newpwd" shell> mysqladmin -u root -h host_name password "newpwd"
These commands apply both to Windows and to Unix. In the second command, replace host_name with the name of the server host. The double quotes around the password are not always necessary, but you should use them if the password contains spaces or other characters that are special to your command interpreter.
If you are using a server from a very old version of MySQL, the
mysqladmin commands to set the password fail with the message
parse error near 'SET password'. The solution to this problem is
to upgrade the server to a newer version of MySQL.
You can also use UPDATE to modify the user table directly.
The following UPDATE statement assigns a password to both root
accounts at once:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('newpwd')
-> WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
The UPDATE statement applies both to Windows and to Unix.
After the passwords have been set, you must supply the appropriate
password whenever you connect to the server.
For example, if you want to use mysqladmin to shut
down the server, you can do so using this command:
shell> mysqladmin -u root -p shutdown Enter password: (enter root password here)
Note: If you forget your root password after setting it up,
the procedure for resetting it is covered in section A.4.1 How to Reset the Root Password.
To set up new accounts, you can use the GRANT statement. For
instructions, see section 5.6.2 Adding New User Accounts to MySQL.
As a general rule, we recommend that when upgrading from one release series to another, you should go to the next series rather than skipping a series. For example, if you currently are running MySQL 3.23 and wish to upgrade to a newer series, upgrade to MySQL 4.0 rather than to 4.1 or 5.0.
The following items form a checklist of things you should do whenever you perform an upgrade:
mysql database. Occasionally new columns or tables are added to
support new features. To take advantage of these features, be sure that
your grant tables are up to date. The upgrade procedure is described in
section 2.10.7 Upgrading the Grant Tables.
mysqld-max, then upgrade later to a non-Max version of MySQL,
mysqld_safe still attempts to run the old mysqld-max
server. If you perform such an upgrade, you should manually remove the old
mysqld-max server to ensure that mysqld_safe runs the new
mysqld server.
You can always move the MySQL format files and data files between different
versions on the same architecture as long as you stay within versions for
the same release series of MySQL. The current production release series is
4.1. If you change the character set when running MySQL, you must run
myisamchk -r -q --set-character-set=charset on all MyISAM tables.
Otherwise, your indexes may not be ordered correctly, because changing the
character set may also change the sort order.
Normally you can upgrade MySQL to a newer MySQL version without having
to do any changes to your tables. Please confirm if the upgrade notes
to the particular version you are upgrading to tells you anything about
this. If there would be any incompatibilities you can use
mysqldump to dump your tables before upgrading. After
upgrading, reload the dump file using mysql or mysqlimport
to re-create your tables.
If you are cautious about using new versions, you can always rename your old
mysqld before installing a newer one. For example, if you are using
MySQL 4.0.18 and want to upgrade to 4.1.1, rename your current server from
mysqld to mysqld-4.0.18. If your new mysqld then does
something unexpected, you can simply shut it down and restart with your old
mysqld.
If, after an upgrade, you experience problems with recompiled client programs,
such as Commands out of sync or unexpected core dumps, you probably have
used old header or library files when compiling your programs. In this
case, you should check the date for your `mysql.h' file and
`libmysqlclient.a' library to verify that they are from the new
MySQL distribution. If not, recompile your programs with the new
headers and libraries.
If problems occur, such as that the new mysqld server doesn't want to
start or that you can't connect without a password, verify that you don't
have some old `my.cnf' file from your previous installation. You can
check this with the --print-defaults option (for example,
mysqld --print-defaults). If this displays
anything other than the program name, you have an active `my.cnf'
file that affects server or client operation.
It is a good idea to rebuild and reinstall the Perl DBD::mysql
module whenever you install a new release of MySQL. The same applies to other
MySQL interfaces as well, such as the PHP mysql extension and the
Python MySQLdb module.
Note: Currently, MySQL 5.0 is at Beta status and, as for any other pre-production release, should not be installed on ``production'' level systems or systems with critical data. It is good practice to back up your data before installing any new version of software. Although MySQL has done its best to ensure a high level of quality, protect your data by making a backup as you would for any software beta release.
In general, you should do the following when upgrading to MySQL 5.0 from 4.1:
proc table in the mysql database.
To create this file, you should run the mysql_fix_privilege_tables
script as described in section 2.10.7 Upgrading the Grant Tables.
user and db tables in the mysql database.
To create these columns, you should run the mysql_fix_privilege_tables
script as described in section 2.10.7 Upgrading the Grant Tables.
Several visible behaviors have changed between MySQL 4.1 and mySQL 5.0 to make MySQL more compatible with standard SQL. These changes may affect your applications.
The following list describes changes that may affect applications and that you should watch out for when upgrading to version 5.0.
Server Changes:
TEXT columns for InnoDB and MyISAM tables
has changed. Starting from 5.0.3, TEXT indexes are compared as space-padded
at the end (just like the way MySQL sorts CHAR, VARCHAR and
TEXT fields. If you have a index on a TEXT column, you
should run CHECK TABLE on it, and run OPTIMIZE TABLE or
REPAIR TABLE if the check reports errors.
xxx_init or xxx_deinit symbol) defined in addition
to the main function symbol. This behavior can be overridden with the
--allow-suspicious-udfs option.
See section 25.2.3.6 User-defined Function Security Precautions.
ISAM storage engine has been removed. If you have
ISAM tables, you should convert them before upgrading. For example,
to convert an ISAM table to use the MyISAM storage engine,
use this statement:
ALTER TABLE tbl_name ENGINE = MyISAM;Use a similar statement for each
ISAM table.
RAID options in MyISAM tables has been removed.
If you have tables that use these options, you should convert them before
upgrading. One way to do this is to dump them with mysqldump,
edit the dump file to remove the RAID options in the CREATE
TABLE statements, and reload the dump file. Another way to convert a table
is to use ALTER TABLE to convert it to use a different storage
engine. The use ALTER TABLE to convert it back if you want to
continue to use the table as a MyISAM table. This approach requires
some care, however. It cannot be used if the table contains
MyISAM-only features such as FULLTEXT indexes or columns with
spatial data types.
The `.MYD' files for RAID tables in a given database are stored
under the database directory in subdirectories that have names consisting of
two hex digits in the range from 00 to ff. After converting
all tables that use RAID options, these RAID-related
subdirectories still will exist but can be removed. Verify that they are
empty, and then remove them manually. (If they are not empty, there is some
RAID table that has not been converted.)
SQL Changes:
VARCHAR and VARBINARY columns. The maximum length for
VARCHAR or VARBINARY now is 65,535 characters or bytes,
respectively.
BIT is a separate data type, not a synonym for
TINYINT(1).
See section 11.1.1 Overview of Numeric Types.
'2004-02-31', you should start
the server with --sql_mode=TRADITIONAL,ALLOW_INVALID_DATES.
SCHEMA and SCHEMAS keywords are
accepted as synonyms for DATABASE and DATABASES.
SET @x = 0; SET @X = 1; SELECT @x; creates two variables and
returns 0. In MySQL 5.0, it creates one variable and returns
1.
C API Changes:
reconnect flag in the MYSQL structure is set
to 0 by mysql_real_connect(). Only those client programs which didn't
explicitly set this flag to 0 or 1 after mysql_real_connect()
experience a change. Having automatic reconnection enabled by default was
considered too dangerous (after reconnection, table locks, temporary tables,
user and session variables are lost).
In general, you should do the following when upgrading to MySQL 4.1 from 4.0:
Password column that is needed for more secure handling of passwords.
The procedure uses mysql_fix_privilege_tables and is described
in section 2.10.7 Upgrading the Grant Tables. If you don't do this, MySQL does not
use the new more secure protocol to authenticate. Implications of the
password-handling change for applications are given later in this section.
mysqldump to dump your BDB tables in text format and delete
all log.XXXXXXXXXX files before you start MySQL 4.0 and reload
the data.
mysql database.
For instructions, see section 2.9 Post-Installation Setup and Testing.
DBD-mysql module
(Msql-MySQL-modules) you have to upgrade to use the newer
DBD-mysql module. Anything above DBD-mysql 2.xx should be fine.
If you don't upgrade, some methods (such as DBI->do()) do not
notice error conditions correctly.
--defaults-file=option-file-name option gives an error if
the option file doesn't exist.
Several visible behaviors have changed between MySQL 4.0 and MySQL 4.1 to fix some critical bugs and make MySQL more compatible with standard SQL. These changes may affect your applications.
Some of the 4.1 behaviors can be tested in 4.0 before performing
a full upgrade to 4.1. We have added to later MySQL 4.0 releases
(from 4.0.12 on) a --new startup option for mysqld.
See section 5.2.1 mysqld Command-Line Options.
This option gives you the 4.1 behavior for the most critical changes.
You can also enable these behaviors for a given client connection with
the SET @@new=1 command, or turn them off if they are on with
SET @@new=0.
If you believe that some of the 4.1 changes affect you,
we recommend that before upgrading to 4.1, you download
the latest MySQL 4.0 version and run it with the --new option by
adding the following to your config file:
[mysqld-4.0] new
That way you can test the new behaviors in 4.0 to make sure that your
applications work with them. This helps you have a smooth, painless
transition when you perform a full upgrade to 4.1 later. Putting the
--new option in the [mysqld-4.0] option group ensures
that you don't accidentally later run the 4.1
version with the --new option.
The following lists describe changes that may affect applications and that you should watch out for when upgrading to version 4.1.
Server Changes:
The most notable change is that character set support has been improved. The server supports multiple character sets, and all tables and string columns have a character set. See section 10 Character Set Support. However, this change results in the potential for table damage if you do not upgrade properly, so consider carefully the incompatibilities noted here.
mysqldump
and reload the dump file. Some items in the following list indicate
alternatives means for rebuilding.
InnoDB tables with TIMESTAMP
columns in MySQL versions 4.1.0 to 4.1.3, you have to rebuild those tables
when you upgrade to MySQL 4.1.4 or later. The storage format in those
MySQL versions for a TIMESTAMP column was incorrect. If you upgrade
from MySQL 4.0 to 4.1.4 or later, then no rebuild of tables with
TIMESTAMP columns is needed.
InnoDB uses the same character set
comparison functions as MySQL for non-latin1_swedish_ci character
strings that are not BINARY. This changes the sorting order of
space and characters with a code < ASCII(32) in those character sets.
For latin1_swedish_ci character strings and BINARY strings,
InnoDB uses its own pad-spaces-at-end comparison method, which
stays unchanged. If you have an InnoDB table created with MySQL
4.1.2 or earlier, with an index on a non-latin1 character set
(in the case of 4.1.0 and 4.1.1, with any character set) and the table
contains any CHAR or VARCHAR columns that are
not BINARY but may contain characters with a code < ASCII(32),
then you should do ALTER TABLE or OPTIMIZE TABLE on it to
regenerate the index, after upgrading to MySQL 4.1.3 or later.
MyISAM tables also have to be rebuilt or repaired in these cases.
You can use mysqldump to dump them in 4.0 and then reload them
in 4.1. An alternative is to use OPTIMIZE TABLE after upgrading,
but this must be done before any updates are made in 4.1.
RENAME
TABLE to overcome this if the accent character is in the table name or
the database name, or rebuild the table.
'a' > 'a\t',
which it wasn't before. If you have any tables where you
have an indexed CHAR, VARCHAR or TEXT column in which
the last character in the index may be less than ASCII(32), you should
use REPAIR TABLE or mysqlcheck to ensure that the table is
correct.
CHAR(N) means N characters, not N
bytes.
For single-byte character sets, this change makes no difference. However,
if you upgrade to MySQL 4.1 and configure the server to use a multi-byte
character set, the apparent length of character columns changes. Suppose
that a 4.0 table contains a CHAR(8) column used to store ujis
characters. Eight bytes can store from two to four ujis characters.
If you upgrade to 4.1 and configure the server to use ujis as its
default character set, the server interprets character column lengths
based on the maximum size of a ujis character, which is three
bytes. The number of three-byte characters that fit in eight bytes is
two. Consequently, if you use SHOW CREATE TABLE to view the table
definition, MySQL displays CHAR(2). You can retrieve existing
data from the table, but you can only store new values containing
up to two characters. To correct this issue, use ALTER TABLE
to change the column definition. For example:
ALTER TABLE tbl_name MODIFY col_name CHAR(8);
UTF8. If you have
table names or column names that use characters outside of the standard 7-bit
US-ASCII range, you may have to do a mysqldump of your tables
in MySQL 4.0 and restore them after upgrading to MySQL 4.1. The symptom for
this problem is that you get a table not found error when trying to
access your tables. In this case, you should be able to downgrade back to
MySQL 4.0 and access your data.
InnoDB is not aware of multiple tablespaces.
timezone system variable was renamed to system_time_zone.
SHOW CREATE TABLE and mysqldump.
(MySQL versions 4.0.6 and above can read the new dump files; older
versions cannot.)
This change should not affect applications that use only one character set.
mysqldump.
See section 8.8 The mysqldump Database Backup Program.
--shared-memory option. If you are running
multiple servers this way on the same Windows machine, you should use a
different --shared-memory-base-name option for each server.
xxx_clear() function for each aggregate
function XXX(). xxx_clear() is used instead of
xxx_reset().
See section 25.2.3.2 UDF Calling Sequences for aggregate functions.
--allow-suspicious-udfs option.
See section 25.2.3.6 User-defined Function Security Precautions.
Client Changes:
mysqldump has the --opt and --quote-names options
enabled by default. You can turn them off with --skip-opt and
--skip-quote-names.
SQL Changes:
'a' > 'a\t',
which it wasn't before. If you have any tables where you
have an indexed CHAR, VARCHAR or TEXT column in which
the last character in the index may be less than ASCII(32), you should
use REPAIR TABLE or mysqlcheck to ensure that the table is
correct.
TIMESTAMP is returned as a string in 'YYYY-MM-DD HH:MM:SS'
format (from 4.0.12 the --new option can be used to make a
4.0 server behave as 4.1 in this respect).
See section 11.3.1.2 TIMESTAMP Properties as of MySQL 4.1.
If you want to have the value returned as a number (as MySQL 4.0 does) you
should add +0 to TIMESTAMP columns when you retrieve them:
mysql> SELECT ts_col + 0 FROM tbl_name;Display widths for
TIMESTAMP columns are no longer supported.
For example, if you declare a column as TIMESTAMP(10), the (10)
is ignored.
These changes were necessary for SQL standards compliance. In a future
version, a further change will be made (backward compatible with this
change), allowing the timestamp length to indicate the desired number of
digits for fractions of a second.
0xFFDF are assumed to be strings instead of
numbers. This fixes some problems with character sets where it's
convenient to input a string as a binary value. With this change,
you should use CAST() if you want to compare binary values
numerically as integers:
mysql> SELECT CAST(0xFEFF AS UNSIGNED INTEGER)
-> < CAST(0xFF AS UNSIGNED INTEGER);
-> 0
If you don't use CAST(), a lexical string comparison is done:
mysql> SELECT 0xFEFF < 0xFF;
-> 1
Using binary items in a numeric context or comparing them using the
= operator should work as before. (The --new option can
be used from 4.0.13 on to make a 4.0 server behave as 4.1 in this respect.)
INSERT INTO t (datetime_col) VALUES ('stuff 2005-02-11 10:17:01');
As of MySQL 4.1.1, the parser is more strict and treats the string as an
invalid date, so the preceding statement results in a warning.
Type column in the output from SHOW TABLE
STATUS was renamed to Engine. This affects applications that identify
output columns by name rather than by position.
DELETE statements, you should use the
alias of the tables from which you want to delete, not the actual table name.
For example, instead of doing this:
DELETE test FROM test AS t1, test2 WHERE ...Do this:
DELETE t1 FROM test AS t1, test2 WHERE ...This corrects a problem that was present in MySQL 4.0.
DATE, DATETIME, or TIME
value, the result returned to the client is fixed up to have a temporal
type. For example, in MySQL 4.1, you get this result:
mysql> SELECT CAST('2001-1-1' AS DATETIME);
-> '2001-01-01 00:00:00'
In MySQL 4.0, the result is different:
mysql> SELECT CAST('2001-1-1' AS DATETIME);
-> '2001-01-01'
DEFAULT values no longer can be specified for AUTO_INCREMENT
columns. (In 4.0, a DEFAULT value is silently ignored; in 4.1,
an error occurs.)
LIMIT no longer accepts negative arguments.
Use some large number (maximum 18446744073709551615) instead of -1.
SERIALIZE is no longer a valid mode value for the sql_mode
variable. You should use SET TRANSACTION ISOLATION LEVEL SERIALIZABLE
instead. SERIALIZE is no longer valid for the --sql-mode option
for mysqld, either. Use --transaction-isolation=SERIALIZABLE
instead.
C API Changes:
mysql_shutdown() C API function has an extra parameter
as of MySQL 4.1.3: SHUTDOWN-level. You should convert any
mysql_shutdown(X) call you have in your application to
mysql_shutdown(X,SHUTDOWN_DEFAULT). Any third-party API that
links against the C API library must be modified to account for this change
or it will not compile.
mysql_real_query() return 1 on error,
not -1. You may have to change some old applications if they use
constructs like this:
if (mysql_real_query(mysql_object, query, query_length) == -1)
{
printf("Got error");
}
Change the call to test for a non-zero value instead:
if (mysql_real_query(mysql_object, query, query_length) != 0)
{
printf("Got error");
}
Password-Handling Changes:
The password hashing mechanism has changed in 4.1 to provide better security, but this may cause compatibility problems if you still have clients that use the client library from 4.0 or earlier. (It is very likely that you have 4.0 clients in situations where clients connect from remote hosts that have not yet upgraded to 4.1.) The following list indicates some possible upgrade strategies. They represent various tradeoffs between the goal of compatibility with old clients and the goal of security.
mysql_fix_privilege_tables script to
widen the Password column in the user table so that it can
hold long password hashes. But run the server with the
--old-passwords option to provide backward compatibility that allows
pre-4.1 clients to continue to connect to their short-hash accounts.
Eventually, when all your clients are upgraded to 4.1, you can stop using
the --old-passwords server option. You can also change the passwords
for your MySQL accounts to use the new more secure format. A pure-4.1
installation is the most secure.
Further background on password hashing with respect to client authentication
and password-changing operations may be found in section 5.5.9 Password Hashing in MySQL 4.1 and
section A.2.3 Client does not support authentication protocol.
In general, you should do the following when upgrading to MySQL 4.0 from 3.23:
mysql_fix_privilege_tables script and is described
in section 2.10.7 Upgrading the Grant Tables.
ISAM files to MyISAM files. One way to do this
is with the
mysql_convert_table_format script. (This is a Perl script;
it requires that DBI be installed.) To convert the tables in a given database,
use this command:
shell> mysql_convert_table_format database db_nameNote that this should be used only if all tables in the given database are
ISAM or MyISAM tables. To avoid converting tables
of other types to MyISAM, you can explicitly list the names
of your ISAM tables after the database name on the command
line.
Individual tables can be changed to MyISAM by using the following
ALTER TABLE statement for each table to be converted:
mysql> ALTER TABLE tbl_name TYPE=MyISAM;If you are not sure of the table type for a given table, use this statement:
mysql> SHOW TABLE STATUS LIKE 'tbl_name';
DBD::mysql module). If you do, you should recompile
them, because the data structures used in `libmysqlclient.so' have changed.
The same applies to other MySQL interfaces as well, such as the Python
MySQLdb module.
MySQL 4.0 works even if you don't perform the preceding actions, but you
cannot use the new security privileges in MySQL 4.0 and you
may run into problems when upgrading later to MySQL 4.1 or newer. The
ISAM file format still works in MySQL 4.0, but is deprecated and
is not compiled in by default as of MySQL 4.1. MyISAM tables should
be used instead.
Old clients should work with a MySQL 4.0 server without any problems.
Even if you perform the preceding actions, you can still downgrade to MySQL
3.23.52 or newer if you run into problems with the MySQL 4.0 series. In
this case, you must use mysqldump to dump any tables that use
full-text indexes and reload the dump file into the 3.23 server. This is
necessary because 4.0 uses a new format for full-text indexing.
The following lists describe changes that may affect applications and that you should watch out for when upgrading to version 4.0.
Server Changes:
--allow-suspicious-udfs option.
See section 25.2.3.6 User-defined Function Security Precautions.
mysql.user table.
See section 5.5.3 Privileges Provided by MySQL.
To get these new privileges to work, you must update the grant tables.
The procedure is described in section 2.10.7 Upgrading the Grant Tables.
Until you do this, all
accounts have the SHOW DATABASES, CREATE TEMPORARY TABLES,
and LOCK TABLES privileges. SUPER and EXECUTE
privileges take their value from PROCESS.
REPLICATION SLAVE and REPLICATION CLIENT take their
values from FILE.
If you have any scripts that create new MySQL user accounts, you may want to change
them to use the new privileges. If you are not using GRANT
commands in the scripts, this is a good time to change your scripts to use
GRANT instead of modifying the grant tables directly.
From version 4.0.2 on, the option --safe-show-database is deprecated
(and no longer does anything). See section 5.4.3 Startup Options for mysqld Concerning Security.
If you get Access denied errors for new users in version 4.0.2 and up, you
should check whether you need some of the new grants that you didn't need
before. In particular, you need REPLICATION SLAVE
(instead of FILE) for new slave servers.
safe_mysqld has been renamed to mysqld_safe. For backward
compatibility, binary distributions will for some time include
safe_mysqld as a symlink to mysqld_safe.
InnoDB support is included by default in binary distributions.
If you build MySQL from source, InnoDB is configured in by default.
If you do not use InnoDB and want to save memory when running a
server that has InnoDB support enabled, use the --skip-innodb
server startup option. To compile MySQL without InnoDB support, run
configure with the --without-innodb option.
myisam_max_extra_sort_file_size and
myisam_max_extra_sort_file_size are given in bytes
(they were given in megabytes before 4.0.3).
mysqld has the option --temp-pool enabled by default
because this gives better performance with some operating systems (most
notably Linux).
mysqld startup options --skip-locking and
--enable-locking were renamed to --skip-external-locking
and --external-locking.
MyISAM/ISAM files is
turned off by default. You can turn this on with
--external-locking. (However, this is never needed for most users.)
| Old Name | New Name |
myisam_bulk_insert_tree_size | bulk_insert_buffer_size
|
query_cache_startup_type | query_cache_type
|
record_buffer | read_buffer_size
|
record_rnd_buffer | read_rnd_buffer_size
|
sort_buffer | sort_buffer_size
|
warnings | log-warnings
|
--err-log | --log-error (for mysqld_safe)
|
record_buffer, sort_buffer, and
warnings still work in MySQL 4.0 but are deprecated.
SQL Changes:
| Old Name | New Name |
SQL_BIG_TABLES | BIG_TABLES
|
SQL_LOW_PRIORITY_UPDATES | LOW_PRIORITY_UPDATES
|
SQL_MAX_JOIN_SIZE | MAX_JOIN_SIZE
|
SQL_QUERY_CACHE_TYPE | QUERY_CACHE_TYPE
|
SET GLOBAL SQL_SLAVE_SKIP_COUNTER=skip_count instead of
SET SQL_SLAVE_SKIP_COUNTER=skip_count.
SHOW MASTER STATUS returns an empty set if binary logging is not
enabled.
SHOW SLAVE STATUS returns an empty set if the slave is not
initialized.
SHOW INDEX has two more columns than it had in 3.23 (Null and
Index_type).
SHOW OPEN TABLES has changed.
ORDER BY col_name DESC sorts NULL values last, as of
MySQL 4.0.11. In 3.23 and in earlier 4.0 versions, this was not
always consistent.
CHECK, LOCALTIME, and LOCALTIMESTAMP
are reserved words.
DOUBLE and FLOAT columns honor the
UNSIGNED flag on storage (before, UNSIGNED was ignored for
these columns).
|, &, <<,
>>, and ~) is unsigned. This may cause problems if you
are using them in a context where you want a signed result.
See section 12.7 Cast Functions and Operators.
Note: When you use subtraction between integer values where
one is of type UNSIGNED, the result is unsigned. In other
words, before upgrading to MySQL 4.0, you should check your application
for cases in which you are subtracting a value from an unsigned entity and
want a negative answer or subtracting an unsigned value from an
integer column. You can disable this behavior by using the
--sql-mode=NO_UNSIGNED_SUBTRACTION option when starting
mysqld. See section 5.2.2 The Server SQL Mode.
BIGINT columns (instead
of using strings, as you did in MySQL 3.23). Using strings still
works, but using integers is more efficient.
INSERT INTO ... SELECT always had IGNORE enabled.
As of 4.0.1, MySQL stops (and possibly rolls back) by default in case of
an error unless you specify IGNORE.
TRUNCATE TABLE when you want to delete all rows
from a table and you don't need to obtain a count of the number of rows
that were deleted. (DELETE FROM tbl_name returns a row count in
4.0 and doesn't reset the AUTO_INCREMENT counter, and
TRUNCATE TABLE is faster.)
LOCK TABLES
statement when trying to execute TRUNCATE TABLE or DROP
DATABASE.
MATCH ... AGAINST (... IN BOOLEAN MODE) full-text searches
with your tables, you must rebuild their indexes with REPAIR TABLE
tbl_name USE_FRM. If you attempt a boolean full-text search without
rebuilding the indexes this way, the search returns incorrect results.
See section 12.6.4 Fine-Tuning MySQL Full-Text Search.
LOCATE() and INSTR() are case sensitive if one of the
arguments is a binary string. Otherwise they are case insensitive.
STRCMP() uses the current character set when performing comparisons.
This makes the default comparison behavior not case sensitive unless
one or both of the operands are binary strings.
HEX(str) returns the characters in str converted to
hexadecimal. If you want to convert a number to hexadecimal, you should
ensure that you call HEX() with a numeric argument.
RAND(seed) returns a different random number series in 4.0 than in
3.23; this was done to further differentiate RAND(seed) and
RAND(seed+1).
IFNULL(A,B) is set to be the
more ``general'' of the types of A and B. (The general-to-specific
order is string, REAL, INTEGER).
C API Changes:
mysql_drop_db(), mysql_create_db(), and
mysql_connect() are no longer supported unless you compile
MySQL with CFLAGS=-DUSE_OLD_FUNCTIONS. However, it is preferable
to change client programs to use the new 4.0 API instead.
MYSQL_FIELD structure, length and max_length have
changed from unsigned int to unsigned long. This should not
cause any problems, except that they may generate warning messages when
used as arguments in the printf() class of functions.
mysql_thread_init() and
mysql_thread_end(). See section 22.2.15 How to Make a Threaded Client.
Other Changes:
DBD::mysql module, use a recent
version. Version 2.9003 is recommended. Versions older than 1.2218 should
not be used because they use the deprecated mysql_drop_db() call.
MySQL 3.22 and 3.21 clients work without any problems with a MySQL 3.23 server.
When upgrading to MySQL 3.23 from an earlier version, note the following changes:
Table Changes:
MyISAM type and the old
ISAM type. By default, all new tables are created with type
MyISAM unless you start mysqld with the
--default-table-type=isam option. You don't have to convert your old
ISAM tables to use them with MySQL 3.23. You can convert an
ISAM table to MyISAM format with ALTER TABLE tbl_name
TYPE=MyISAM or the Perl script mysql_convert_table_format.
tis620 character set must be fixed
with myisamchk -r or REPAIR TABLE.
german character sort order for ISAM
tables, you must repair them with isamchk -r, because we have made
some changes in the sort order.
Client Program Changes:
mysql is by default started with the
--no-named-commands (-g) option. This option can be disabled with
--enable-named-commands (-G). This may cause incompatibility problems in
some cases--for example, in SQL scripts that use named commands without a
semicolon. Long format commands still work from the first line.
mysqldump files to be compatible between
MySQL 3.22 and 3.23, you should not use the
--opt or --all option to mysqldump.
SQL Changes:
DROP DATABASE on a symbolically linked database, both the
link and the original database are deleted. This didn't happen in MySQL 3.22
because configure didn't detect the availability of the
readlink() system call.
OPTIMIZE TABLE works only for MyISAM tables.
For other table types, you can use ALTER TABLE to optimize the table.
During OPTIMIZE TABLE, the table is locked to prevent it from being
used by other threads.
MONTH())
return 0 for 0000-00-00 dates. In MySQL 3.22, these functions returned
NULL.
IF() depends on both arguments,
not just the first one.
AUTO_INCREMENT columns should not be used to store negative
numbers. The reason for this is that negative numbers caused problems
when wrapping from -1 to 0. You should not store 0 in AUTO_INCREMENT
columns, either; CHECK TABLE complains about 0 values because
they may change if you dump and restore the table. AUTO_INCREMENT
for MyISAM tables is handled at a lower level and is much
faster than before. In addition, for MyISAM tables, old numbers
are not reused, even if you delete rows from the table.
CASE, DELAYED, ELSE, END, FULLTEXT,
INNER, RIGHT, THEN, and WHEN are reserved words.
FLOAT(p) is a true floating-point type and not a value with a
fixed number of decimals.
DECIMAL(length,dec) type, the
length argument no longer includes a place for the sign or the
decimal point.
TIME string must be of one of the following formats:
[[[DAYS] [H]H:]MM:]SS[.fraction] or
[[[[[H]H]H]H]MM]SS[.fraction].
LIKE compares strings using the same character comparison rules
as for the = operator. If you require the old behavior, you can
compile MySQL with the CXXFLAGS=-DLIKE_CMP_TOUPPER flag.
REGEXP is case insensitive if neither of the strings is a binary
string.
MyISAM (`.MYI') tables, you should use
the CHECK TABLE statement or the myisamchk command. For
ISAM (`.ISM') tables, use the isamchk command.
DATE_FORMAT() to make sure that there is a
`%' before each format character.
SELECT DISTINCT ... was
almost always sorted. In MySQL 3.23, you must use GROUP BY or
ORDER BY to obtain sorted output.
SUM() returns NULL instead of 0 if
there are no matching rows. This is required by standard SQL.
AND or OR with NULL values returns
NULL instead of 0. This mostly affects queries that use NOT
on an AND/OR expression as NOT NULL = NULL.
LPAD() and RPAD() shorten the result string if it's longer
than the length argument.
C API Changes:
mysql_fetch_fields_direct() is a function instead of a macro.
It returns a pointer to a MYSQL_FIELD instead of a
MYSQL_FIELD.
mysql_num_fields() cannot be used on a MYSQL* object (it's
a function that takes a MYSQL_RES* value as an argument). With a
MYSQL* object, you should use mysql_field_count() instead.
Nothing that affects compatibility has changed between versions 3.21 and 3.22.
The only pitfall is that new tables that are created with DATE type
columns use the new way to store the date. You can't access these new
columns from an old version of mysqld.
When upgrading to MySQL 3.23 from an earlier version, note the following changes:
mysql_fix_privilege_tables script. This adds the
new privileges that you need to use the GRANT command. If you forget
this, you get Access denied when you try to use ALTER
TABLE, CREATE INDEX, or DROP INDEX. The procedure for updating
the grant tables is described in section 2.10.7 Upgrading the Grant Tables.
mysql_real_connect() has changed. If you have
an old client program that calls this function, you must pass a 0 for
the new db argument (or recode the client to send the db
element for faster connections). You must also call mysql_init()
before calling mysql_real_connect(). This change was done to allow
the new mysql_options() function to save options in the MYSQL
handler structure.
mysqld variable key_buffer has been renamed to
key_buffer_size, but you can still use the old name in your
startup files.
If you are running a version older than Version 3.20.28 and want to switch to Version 3.21, you need to do the following:
You can start the mysqld Version 3.21 server with the
--old-protocol option to use it with clients from a Version 3.20
distribution. In this case, the server uses the old pre-3.21
password() checking rather than the new method. Also, the new client
function mysql_errno() does not return any server error, only
CR_UNKNOWN_ERROR. The function does work for client errors.
If you are not using the --old-protocol option to
mysqld, you need to make the following changes:
scripts/add_long_password script must be run to convert the
Password field in the mysql.user table to CHAR(16).
mysql.user table to get 62-bit
rather than 31-bit passwords.
MySQL 3.20.28 and above can handle the new user table
format without affecting clients. If you have a MySQL version earlier
than 3.20.28, passwords no longer work with it if you convert the
user table. So to be safe, you should first upgrade to at least Version
3.20.28 and then upgrade to Version 3.21.
The new client code works with a 3.20.x mysqld server, so
if you experience problems with 3.21.x, you can use the old 3.20.x server
without having to recompile the clients again.
If you are not using the --old-protocol option to mysqld,
old clients are unable to connect and should issue the following error
message:
ERROR: Protocol mismatch. Server Version = 10 Client Version = 9
The Perl DBI interface also supports the old
mysqlperl interface. The only change you have to make if you use
mysqlperl is to change the arguments to the connect() function.
The new arguments are: host, database, user,
and password (note that the user and password arguments
have changed places).
The following changes may affect queries in old applications:
HAVING must be specified before any ORDER BY clause.
LOCATE() have been swapped.
DATE,
TIME, and TIMESTAMP.
Some releases introduce changes to the structure of the grant tables
(the tables in the mysql database)
to add new privileges or features. To make sure that your grant tables
are current when you update to a new version of MySQL, you should update
your grant tables as well.
On Unix or Unix-like systems, update the grant tables by running the
mysql_fix_privilege_tables script:
shell> mysql_fix_privilege_tables
You must run this script while the server is running. It attempts to
connect to the server running on the local host as root.
If your root account requires a password, indicate the password
on the command line. For MySQL 4.1 and up, specify the password like this:
shell> mysql_fix_privilege_tables --password=root_password
Prior to MySQL 4.1, specify the password like this:
shell> mysql_fix_privilege_tables root_password
The mysql_fix_privilege_tables script performs any actions
necessary to convert your grant tables to the current format. You
might see some Duplicate column name warnings as it runs; you can
ignore them.
After running the script, stop the server and restart it.
On Windows systems, there isn't an easy way to update the grant tables
until MySQL 4.0.15. From version 4.0.15 on, MySQL distributions include a
`mysql_fix_privilege_tables.sql' SQL script that you can run using
the mysql client. If your MySQL installation is located at
`C:\mysql', the commands look like this:
C:\> C:\mysql\bin\mysql -u root -p mysql mysql> SOURCE C:\mysql\scripts\mysql_fix_privilege_tables.sql
If your installation is located in some other directory, adjust the pathnames appropriately.
The mysql command will prompt you for the root password; enter it
when prompted.
As with the Unix procedure, you might see some Duplicate column name
warnings as mysql processes the statements in the
`mysql_fix_privilege_tables.sql' script; you can ignore them.
After running the script, stop the server and restart it.
If you are upgrading to MySQL 5.0.1 or later, the grant table upgrade
procedure just described adds view-related columns for the
CREATE VIEW and SHOW VIEW privileges. These privileges
exist at the global and database levels. Their initial values are assigned
as follows:
mysql_fix_privilege_tables
copies the Create_priv value in the user table to the
Create_view_priv and Show_view_priv columns.
GRANT to give them to accounts
that should have them. To deal with this, first connect to the server as
root and issue the following statements to give the privileges to
the root accounts manually with UPDATE:
mysql> UPDATE mysql.user SET Show_view_priv = 'Y', Create_view_priv = 'Y'
-> WHERE User = 'root';
mysql> FLUSH PRIVILEGES;
After this, root can use GRANT to give the view privileges
to other accounts. Note: You should issue the statements just shown,
GRANT ALL does not work at the global and database levels, because
GRANT ALL requires that you actually possess all privileges.
If you are using MySQL 3.23 or later, you can copy the `.frm',
`.MYI', and `.MYD' files for MyISAM tables between different
architectures that support the same floating-point format. (MySQL takes care
of any byte-swapping issues.)
See section 14.1 The MyISAM Storage Engine.
The MySQL ISAM data and index files (`.ISD' and `*.ISM',
respectively) are architecture dependent and in some cases operating
system dependent. If you want to move your applications to another
machine that has a different architecture or operating system than your
current machine, you should not try to move a database by simply copying
the files to the other machine. Use mysqldump instead.
By default, mysqldump creates a file containing SQL statements.
You can then transfer the file to the other machine and feed it as input
to the mysql client.
Try mysqldump --help to see what options are available.
If you are moving the data to a newer version of MySQL, you should use
mysqldump --opt to take advantage of any optimizations that result
in a dump file that is smaller and can be processed faster.
The easiest (although not the fastest) way to move a database between two machines is to run the following commands on the machine on which the database is located:
shell> mysqladmin -h 'other_hostname' create db_name shell> mysqldump --opt db_name | mysql -h 'other_hostname' db_name
If you want to copy a database from a remote machine over a slow network, you can use:
shell> mysqladmin create db_name shell> mysqldump -h 'other_hostname' --opt --compress db_name | mysql db_name
You can also store the result in a file, then transfer the file to the target machine and load the file into the database there. For example, you can dump a database to a file on the source machine like this:
shell> mysqldump --quick db_name | gzip > db_name.contents.gz
(The file created in this example is compressed.) Transfer the file containing the database contents to the target machine and run these commands there:
shell> mysqladmin create db_name shell> gunzip < db_name.contents.gz | mysql db_name
You can also use mysqldump and mysqlimport to transfer
the database.
For big tables, this is much faster than simply using mysqldump.
In the following commands, DUMPDIR represents the full pathname
of the directory you use to store the output from mysqldump.
First, create the directory for the output files and dump the database:
shell> mkdir DUMPDIR shell> mysqldump --tab=DUMPDIR db_name
Then transfer the files in the DUMPDIR directory to some corresponding
directory on the target machine and load the files into MySQL
there:
shell> mysqladmin create db_name # create database shell> cat DUMPDIR/*.sql | mysql db_name # create tables in database shell> mysqlimport db_name DUMPDIR/*.txt # load data into tables
Also, don't forget to copy the mysql database because that is
where the user, db, and host grant tables are stored.
You might have to run commands as the MySQL root user on the new
machine until you have the mysql database in place.
After you import the mysql database on the new machine, execute
mysqladmin flush-privileges so that the server reloads the grant table
information.
This section describes what you should do if you are downgrading to an older MySQL version in the unlikely case that the previous version worked better than the new one.
If you are downgrading within the same release series (for example, from 4.0.20 to 4.0.19) the general rule is that you just have to install the new binaries on top of the old ones. There is no need to do anything with the databases. As always, however, it's always a good idea to make a backup.
The following items form a checklist of things you should do whenever you perform an downgrade:
You can always move the MySQL format files and data files between different versions on the same architecture as long as you stay within versions for the same release series of MySQL. The current production release series is 4.1.
If you downgrade from one release series to another, there may be
incompatibilities in table storage formats. In this case, you can use
mysqldump to dump your tables before downgrading. After
downgrading, reload the dump file using mysql or mysqlimport
to re-create your tables. See section 2.10.8 Copying MySQL Databases to Another Machine for examples.
The normal symptom of a downward-incompatible table format change when you downgrade is that you can't open tables. In that case, use the following procedure:
mysqldump to create a dump file.
After downgrading from MySQL 5.0, you may see the following information in the `mysql.err' file:
Incorrect information in file: './mysql/user.frm'
In this case, you can do the following:
mysql_fix_privilege_tables, which will change the
mysql.user table to a format that both MySQL 4.1 and 5.0 can use.
If the preceding procedure fails, then you should be able to do the following instead:
mysqldump --opt --add-drop-table mysql > /tmp/mysql.dump.
--skip-grant option.
mysql mysql < /tmp/mysql.dump.
mysqladmin flush-privileges.
The table format in 4.1 changed to include more and new character set
information. Because of this, you must use mysqldump to dump any
tables you have created with the newer MySQL server. For example, if all
the tables in a particular database need to be dumped to be reverted back to
MySQL 4.0 format, use this command:
shell> mysqldump --create-options --compatible=mysql40 db_name > dump_file
Then stop the newer server, restart the older server, and read in the dump file:
shell> mysql db_name < dump_file
In the special case that you're downgrading MyISAM tables, no special
treatment is necessary if all columns in the tables contain only numeric
columns or string columns (CHAR, VARCHAR, TEXT, and so
forth) that contain only latin1 data. Your
4.1 tables should be directly usable with a 4.0 server.
If you used the mysql_fix_privilege_tables script to upgrade the
grant tables, you can either use the preceding method to convert them to back to
MySQL 4.0 or do the following in MySQL 4.1 (or above):
ALTER TABLE mysql.user CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci; ALTER TABLE mysql.db CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci; ALTER TABLE mysql.host CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci; ALTER TABLE mysql.tables_priv CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci; ALTER TABLE mysql.columns_priv CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci; ALTER TABLE mysql.func CONVERT TO CHARACTER SET latin1 COLLATE latin1_swedish_ci;
This section discusses issues that have been found to occur on Linux. The first few subsections describe general operating system-related issues, problems that can occur when using binary or source distributions, and post-installation issues. The remaining subsections discuss problems that occur with Linux on specific platforms.
Note that most of these problems occur on older versions of Linux. If you are running a recent version, you may see none of them.
MySQL needs at least Linux Version 2.0.
Warning: We have seen some strange problems with Linux 2.2.14 and MySQL on SMP systems. We also have reports from some MySQL users that they have encountered serious stability problems using MySQL with kernel 2.2.14. If you are using this kernel, you should upgrade to 2.2.19 (or newer) or to a 2.4 kernel. If you have a multiple-CPU box, then you should seriously consider using 2.4 because it gives you a significant speed boost. Your system should be more stable.
When using LinuxThreads, you should see a minimum of three mysqld processes
running. These are in fact threads. There is one thread for the
LinuxThreads manager, one thread to handle connections, and one thread
to handle alarms and signals.
The Linux-Intel binary and RPM releases of MySQL are configured for the highest possible speed. We are always trying to use the fastest stable compiler available.
The binary release is linked with -static, which means you do not
normally need to worry about which version of the system libraries you
have. You need not install LinuxThreads, either. A program linked with
-static is slightly larger than a dynamically linked program,
but also slightly faster (3-5%). However, one problem with a statically
linked program is that you can't use user-defined functions (UDFs).
If you are going to write or use UDFs (this is something for C or C++
programmers only), you must compile MySQL yourself using dynamic linking.
A known issue with binary distributions is that on older Linux
systems that use libc (such as Red Hat 4.x or Slackware), you get
some non-fatal problems with hostname resolution. If your system uses
libc rather than glibc2,
you probably will encounter some difficulties with hostname resolution and
getpwnam(). This happens because glibc
unfortunately depends on some external libraries to implement hostname
resolution and getpwent(), even when compiled with -static.
These problems manifest themselves in two ways:
mysql_install_db:
Sorry, the host 'xxxx' could not be looked upYou can deal with this by executing
mysql_install_db --force, which does not execute the
resolveip test in mysql_install_db. The downside is that
you can't use hostnames in the grant tables: Except for localhost,
you must use IP numbers instead. If you are using an old version of MySQL
that doesn't support --force, you must manually remove the
resolveip test in mysql_install using an editor.
mysqld with the --user
option:
getpwnam: No such file or directoryTo work around this, start
mysqld by using
the su command rather than by specifying the --user
option. This causes the system itself to change the user ID of the
mysqld process so that mysqld need not do so.
Another solution, which solves both problems, is to not use a binary
distribution. Get a MySQL source distribution (in RPM or tar.gz
format) and install that instead.
On some Linux 2.2 versions, you may get the error Resource
temporarily unavailable when clients make a lot of new connections to
a mysqld server over TCP/IP. The problem is that Linux has a
delay between the time that you close a TCP/IP socket and the time that
the system actually frees it. There is room for only a finite number
of TCP/IP slots, so you encounter the resource-unavailable error if
clients attempt too many new TCP/IP connections during a short time. For
example, you may see the error when you run the MySQL `test-connect'
benchmark over TCP/IP.
We have inquired about this problem a few times on different Linux mailing lists but have never been able to find a suitable resolution. The only known ``fix'' is for the clients to use persistent connections, or, if you are running the database server and clients on the same machine, to use Unix socket file connections rather than TCP/IP connections.
The following notes regarding glibc apply only to the situation
when you build MySQL
yourself. If you are running Linux on an x86 machine, in most cases it is
much better for you to just use our binary. We link our binaries against
the best patched version of glibc we can come up with and with the
best compiler options, in an attempt to make it suitable for a high-load
server. For a typical user, even for setups with a lot of concurrent
connections or tables exceeding the 2GB limit, our binary is
the best choice in most cases. After reading the following text, if you
are in doubt about what to do, try our binary first to see whether it meets
your needs. If you discover that it is not good enough, then
you may want to try your own build. In that case, we would appreciate
a note about it so that we can build a better binary next time.
MySQL uses LinuxThreads on Linux. If you are using an old
Linux version that doesn't have glibc2, you must install
LinuxThreads before trying to compile MySQL. You can get
LinuxThreads at http://dev.mysql.com/downloads/os-linux.html.
Note that glibc versions before and including Version 2.1.1 have
a fatal bug in pthread_mutex_timedwait() handling, which is used
when you issue INSERT DELAYED statements. We recommend that you not use
INSERT DELAYED before upgrading glibc.
Note that Linux kernel and the LinuxThread library can by default only have 1,024 threads. If you plan to have more than 1,000 concurrent connections, you need to make some changes to LinuxThreads:
PTHREAD_THREADS_MAX in
`sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decrease
STACK_SIZE in `linuxthreads/internals.h' to 256KB. The
paths are relative to the root of glibc. (Note that MySQL is not
stable with around 600-1000 connections if STACK_SIZE
is the default of 2MB.)
The page http://www.volano.com/linuxnotes.html contains additional information about circumventing thread limits in LinuxThreads.
There is another issue that greatly hurts MySQL performance, especially on
SMP systems. The mutex implementation in LinuxThreads in glibc
2.1 is very bad for programs with many threads that hold the mutex
only for a short time. This produces a paradoxical result: If you link
MySQL against an unmodified LinuxThreads, removing processors from an
SMP actually improves MySQL performance in many cases. We have made a
patch available for glibc 2.1.3 to correct this behavior
(http://www.mysql.com/Downloads/Linux/linuxthreads-2.1-patch).
With glibc 2.2.2,
MySQL 3.23.36 uses the adaptive mutex, which is much
better than even the patched one in glibc 2.1.3. Be warned, however,
that under some conditions, the current mutex code in glibc 2.2.2
overspins, which hurts MySQL performance. The likelihood that this condition
occurs can be reduced by renicing the mysqld process to the highest
priority. We have also been able to correct the overspin behavior with
a patch, available at
http://www.mysql.com/Downloads/Linux/linuxthreads-2.2.2.patch.
It combines the correction of overspin, maximum number of
threads, and stack spacing all in one. You need to apply it in the
linuxthreads directory with
patch -p0 </tmp/linuxthreads-2.2.2.patch.
We hope it is included in
some form in future releases of glibc 2.2. In any case, if
you link against glibc 2.2.2, you still need to correct
STACK_SIZE and PTHREAD_THREADS_MAX. We hope that the defaults
is corrected to some more acceptable values for high-load
MySQL setup in the future, so that the commands needed to produce
your own build can be reduced to ./configure; make; make install.
We recommend that you use these patches to build a special static
version of libpthread.a and use it only for statically linking
against MySQL. We know that the patches are safe for MySQL
and significantly improve its performance, but we cannot say anything
about other applications. If you link other applications that require
LinuxThreads against the
patched static version of the library, or build a patched shared version and
install it on your system, you do so at your own risk.
If you experience any strange problems during the installation of MySQL, or with some common utilities hanging, it is very likely that they are either library or compiler related. If this is the case, using our binary resolves them.
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory
This problem can be avoided by one of the following methods:
-Wl,r/full/path/to/libmysqlclient.so
flag rather than with -Lpath).
libmysqclient.so to `/usr/lib'.
LD_RUN_PATH environment variable before running your client.
If you are using the Fujitsu compiler (fcc/FCC), you may have
some problems compiling MySQL because the Linux header files are very
gcc oriented.
The following configure line should work with fcc/FCC:
CC=fcc CFLAGS="-O -K fast -K lib -K omitfp -Kpreex -D_GNU_SOURCE \
-DCONST=const -DNO_STRTOLL_PROTO" \
CXX=FCC CXXFLAGS="-O -K fast -K lib \
-K omitfp -K preex --no_exceptions --no_rtti -D_GNU_SOURCE \
-DCONST=const -Dalloca=__builtin_alloca -DNO_STRTOLL_PROTO \
'-D_EXTERN_INLINE=static __inline'" \
./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static --disable-shared \
--with-low-memory
mysql.server can be found in the `support-files' directory under
the MySQL installation directory or in a MySQL source tree. You can install
it as `/etc/init.d/mysql' for automatic MySQL startup and shutdown.
See section 2.9.2.2 Starting and Stopping MySQL Automatically.
If MySQL can't open enough files or connections, it may be that you haven't configured Linux to handle enough files.
In Linux 2.2 and onward, you can check the number of allocated file handles as follows:
shell> cat /proc/sys/fs/file-max shell> cat /proc/sys/fs/dquot-max shell> cat /proc/sys/fs/super-max
If you have more than 16MB of memory, you should add something like the following to your init scripts (for example, `/etc/init.d/boot.local' on SuSE Linux):
echo 65536 > /proc/sys/fs/file-max echo 8192 > /proc/sys/fs/dquot-max echo 1024 > /proc/sys/fs/super-max
You can also run the echo commands from the command line as root,
but these settings are lost the next time your computer restarts.
Alternatively, you can set these parameters on startup by using the
sysctl tool, which is used by many Linux distributions (SuSE has
added it as well, beginning with SuSE Linux 8.0). Just put the following
values into a file named `/etc/sysctl.conf':
# Increase some values for MySQL fs.file-max = 65536 fs.dquot-max = 8192 fs.super-max = 1024
You should also add the following to `/etc/my.cnf':
[mysqld_safe] open-files-limit=8192
This should allow the server a limit of 8,192 for the combined number of connections and open files.
The STACK_SIZE constant in LinuxThreads controls the spacing of thread
stacks in the address space. It needs to be large enough so that there is
plenty of room for each individual thread stack, but small enough
to keep the stack of some threads from running into the global mysqld
data. Unfortunately, as we have experimentally discovered, the Linux
implementation of mmap() successfully unmaps a mapped
region if you ask it to map out an address currently in use, zeroing out the data
on the entire page instead of returning an error. So, the safety of
mysqld or any other threaded application depends on ``gentlemanly''
behavior of the code that creates threads. The user must take measures to
make sure that the number of running threads at any time is sufficiently low for
thread stacks to stay away from the global heap. With mysqld, you
should enforce this behavior by setting a reasonable value for
the max_connections variable.
If you build MySQL yourself, you can patch LinuxThreads for better stack use.
See section 2.12.1.3 Linux Source Distribution Notes.
If you do not want to patch
LinuxThreads, you should set max_connections to a value no higher
than 500. It should be even less if you have a large key buffer, large
heap tables, or some other things that make mysqld allocate a lot
of memory, or if you are running a 2.2 kernel with a 2GB patch. If you are
using our binary or RPM version 3.23.25 or later, you can safely set
max_connections at 1500, assuming no large key buffer or heap tables
with lots of data. The more you reduce STACK_SIZE in LinuxThreads
the more threads you can safely create. We recommend values between
128KB and 256KB.
If you use a lot of concurrent connections, you may suffer from a ``feature'' in the 2.2 kernel that attempts to prevent fork bomb attacks by penalizing a process for forking or cloning a child. This causes MySQL not to scale well as you increase the number of concurrent clients. On single-CPU systems, we have seen this manifested as very slow thread creation: It may take a long time to connect to MySQL (as long as one minute), and it may take just as long to shut it down. On multiple-CPU systems, we have observed a gradual drop in query speed as the number of clients increases. In the process of trying to find a solution, we have received a kernel patch from one of our users who claimed it made a lot of difference for his site. The patch is available at http://www.mysql.com/Downloads/Patches/linux-fork.patch. We have done rather extensive testing of this patch on both development and production systems. It has significantly improved MySQL performance without causing any problems and we recommend it to our users who still run high-load servers on 2.2 kernels.
This issue has been fixed in the 2.4 kernel, so if you are not satisfied with the current performance of your system, rather than patching your 2.2 kernel, it might be easier to upgrade to 2.4. On SMP systems, upgrading also gives you a nice SMP boost in addition to fixing the fairness bug.
We have tested MySQL on the 2.4 kernel on a two-CPU machine and found MySQL scales much better. There was virtually no slowdown on query throughput all the way up to 1,000 clients, and the MySQL scaling factor (computed as the ratio of maximum throughput to the throughput for one client) was 180%. We have observed similar results on a four-CPU system: Virtually no slowdown as the number of clients was increased up to 1,000, and a 300% scaling factor. Based on these results, for a high-load SMP server using a 2.2 kernel, we definitely recommend upgrading to the 2.4 kernel at this point.
We have discovered that it is essential to run the mysqld process
with the highest possible priority on the 2.4 kernel to achieve maximum
performance. This can be done by adding a renice -20 $$ command
to mysqld_safe. In our testing on a four-CPU machine, increasing
the priority resulted in a 60% throughput increase with 400 clients.
We are currently also trying to collect more information on how well MySQL performs with a 2.4 kernel on four-way and eight-way systems. If you have access such a system and have done some benchmarks, please send an email message to benchmarks@mysql.com with the results. We will review them for inclusion in the manual.
If you see a dead mysqld server process with ps, this usually
means that you have found a bug in MySQL or you have a corrupted
table. See section A.4.2 What to Do If MySQL Keeps Crashing.
To get a core dump on Linux if mysqld dies with a SIGSEGV signal,
you can start mysqld with the --core-file option. Note
that you also probably need to raise the core file size by adding
ulimit -c 1000000 to mysqld_safe or starting
mysqld_safe with --core-file-size=1000000.
See section 5.1.3 The mysqld_safe Server Startup Script.
MySQL requires libc Version 5.4.12 or newer. It's known to
work with libc 5.4.46. glibc Version 2.0.6 and later should
also work. There have been some problems with the glibc RPMs from
Red Hat, so if you have problems, check whether there are any updates.
The glibc 2.0.7-19 and 2.0.7-29 RPMs are known to work.
If you are using Red Hat 8.0 or a new glibc 2.2.x library, you may see
mysqld die in gethostbyaddr(). This happens because the new
glibc library requires a stack size greater than 128KB for this call.
To fix the problem, start mysqld with the --thread-stack=192K
option. (Use -O thread_stack=192K before MySQL 4.)
This stack size is the default on MySQL 4.0.10 and above, so you should
not see the problem.
If you are using gcc 3.0 and above to compile MySQL, you must install
the libstdc++v3 library before compiling MySQL; if you don't do
this, you get an error about a missing __cxa_pure_virtual
symbol during linking.
On some older Linux distributions, configure may produce an error
like this:
Syntax error in sched.h. Change _P to __P in the /usr/include/sched.h file. See the Installation chapter in the Reference Manual.
Just do what the error message says. Add an extra underscore to the
_P macro name that has only one underscore, then try again.
You may get some warnings when compiling. Those shown here can be ignored:
mysqld.cc -o objs-thread/mysqld.o mysqld.cc: In function `void init_signals()': mysqld.cc:315: warning: assignment of negative value `-1' to `long unsigned int' mysqld.cc: In function `void * signal_hand(void *)': mysqld.cc:346: warning: assignment of negative value `-1' to `long unsigned int'
If mysqld always dumps core when it starts, the problem may be that
you have an old `/lib/libc.a'. Try renaming it, then remove
`sql/mysqld' and do a new make install and try again. This
problem has been reported on some Slackware installations.
If you get the following error when linking mysqld,
it means that your `libg++.a' is not installed correctly:
/usr/lib/libc.a(putc.o): In function `_IO_putc': putc.o(.text+0x0): multiple definition of `_IO_putc'
You can avoid using `libg++.a' by running configure like this:
shell> CXX=gcc ./configure
If mysqld crashes immediately and you are running Red Hat Version 5.0
with a version of glibc older than 2.0.7-5, you should make sure that
you have installed all glibc patches. There is a lot of information
about this in the MySQL mail archives, available online at
http://lists.mysql.com/.
In some implementations, readdir_r() is broken. The symptom is
that the SHOW DATABASES statement always returns an empty set.
This can be fixed by removing HAVE_READDIR_R from `config.h'
after configuring and before compiling.
MySQL 3.23.12 is the first MySQL version that is tested on Linux-Alpha. If you plan to use MySQL on Linux-Alpha, you should ensure that you have this version or newer.
We have tested MySQL on Alpha with our benchmarks and test suite, and it appears to work nicely.
We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP, kernel 2.4.4-SMP, Compaq C compiler (V6.2-505) and Compaq C++ compiler (V6.3-006) on a Compaq DS20 machine with an Alpha EV6 processor.
You can find the preceding compilers at
http://www.support.compaq.com/alpha-tools/. By using these compilers
rather than gcc, we get about 9-14% better MySQL performance.
Note that until MySQL version 3.23.52 and 4.0.2, we optimized the binary for
the current CPU only (by using the -fast compile option). This means
that for older versions, you can use our Alpha binaries only if you have an
Alpha EV6 processor.
For all following releases, we added the -arch generic flag
to our compile options, which makes sure that the binary runs on all Alpha
processors. We also compile statically to avoid library problems.
The configure command looks like this:
CC=ccc CFLAGS="-fast -arch generic" CXX=cxx \
CXXFLAGS="-fast -arch generic -noexceptions -nortti" \
./configure --prefix=/usr/local/mysql --disable-shared \
--with-extra-charsets=complex --enable-thread-safe-client \
--with-mysqld-ldflags=-non_shared --with-client-ldflags=-non_shared
If you want to use egcs, the following configure line worked
for us:
CFLAGS="-O3 -fomit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --disable-shared
Some known problems when running MySQL on Linux-Alpha:
gdb 4.18. You should use gdb 5.1 instead.
mysqld statically when using gcc, the
resulting image dumps core at startup time. In other words, do not
use --with-mysqld-ldflags=-all-static with gcc.
MySQL should work on MkLinux with the newest glibc package
(tested with glibc 2.0.7).
To get MySQL to work on Qube2 (Linux Mips), you need the
newest glibc libraries. glibc-2.0.7-29C2 is known to
work. You must also use the egcs C++ compiler
(egcs 1.0.2-9, gcc 2.95.2 or newer).
To get MySQL to compile on Linux IA-64, we use the following configure
command for building with gcc 2.96:
CC=gcc \
CFLAGS="-O3 -fno-omit-frame-pointer" \
CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql \
"--with-comment=Official MySQL binary" \
--with-extra-charsets=complex
On IA-64, the MySQL client binaries use shared libraries. This means
that if you install our binary distribution at a location other than
`/usr/local/mysql', you need to add the path of the directory
where you have `libmysqlclient.so' installed either to the
`/etc/ld.so.conf' file or to the value of your LD_LIBRARY_PATH
environment variable.
See section A.3.1 Problems Linking to the MySQL Client Library.
On Mac OS X, tar cannot handle long filenames. If you need to unpack a
`.tar.gz' distribution, use gnutar instead.
MySQL should work without any problems on Mac OS X 10.x (Darwin).
Our binary for Mac OS X is compiled on Darwin 6.3 with the following
configure line:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --disable-shared
See section 2.5 Installing MySQL on Mac OS X.
For current versions of Mac OS X Server, no operating system changes are necessary before compiling MySQL. Compiling for the Server platform is the same as for the client version of Mac OS X. (However, note that MySQL comes preinstalled on Mac OS X Server, so you need not build it yourself.)
For older versions (Mac OS X Server 1.2, a.k.a. Rhapsody), you must first install a pthread package before trying to configure MySQL.
See section 2.5 Installing MySQL on Mac OS X.
On Solaris, you may run into trouble even before you get the MySQL
distribution unpacked! Solaris tar can't handle long filenames, so
you may see an error like this when you unpack MySQL:
x mysql-3.22.12-beta/bench/Results/ATIS-mysql_odbc-NT_4.0-cmp-db2, informix,ms-sql,mysql,oracle,solid,sybase, 0 bytes, 0 tape blocks tar: directory checksum error
In this case, you must use GNU tar (gtar) to unpack the
distribution. You can find a precompiled copy for Solaris at
http://dev.mysql.com/downloads/os-solaris.html.
Sun native threads work only on Solaris 2.5 and higher. For Version 2.4 and earlier, MySQL automatically uses MIT-pthreads. See section 2.8.5 MIT-pthreads Notes.
If you get the following error from configure,
it means that you have something wrong with your compiler installation:
checking for restartable system calls... configure: error can not run test programs while cross compiling
In this case, you should upgrade your compiler to a newer version. You may also be able to solve this problem by inserting the following row into the `config.cache' file:
ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'}
If you are using Solaris on a SPARC, the recommended compiler is
gcc 2.95.2 or 3.2. You can find this at http://gcc.gnu.org/.
Note that egcs 1.1.1 and gcc 2.8.1 don't work reliably on
SPARC!
The recommended configure line when using gcc 2.95.2 is:
CC=gcc CFLAGS="-O3" \
CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory \
--enable-assembler
If you have an UltraSPARC system, you can get 4% better performance by adding
-mcpu=v8 -Wa,-xarch=v8plusa to the CFLAGS and CXXFLAGS
environment variables.
If you have Sun's Forte 5.0 (or newer) compiler, you can
run configure like this:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \ CXX=CC CXXFLAGS="-noex -mt" \ ./configure --prefix=/usr/local/mysql --enable-assembler
To create a 64-bit binary with Sun's Forte compiler, use the following configuration options:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \ CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \ ./configure --prefix=/usr/local/mysql --enable-assembler
To create a 64-bit Solaris binary using gcc, add -m64 to
CFLAGS and CXXFLAGS and remove --enable-assembler from
the configure line. This works only with MySQL
4.0 and up; MySQL 3.23 does not include the required modifications to
support this.
In the MySQL benchmarks, we got a 4% speedup on an UltraSPARC when using
Forte 5.0 in 32-bit mode compared to using gcc 3.2 with the -mcpu
flag.
If you create a 64-bit mysqld binary, it is 4% slower than the 32-bit
binary, but can handle more threads and memory.
If you get a problem with fdatasync or sched_yield,
you can fix this by adding LIBS=-lrt to the configure line
For compilers older than WorkShop 5.3, you might have to edit the
configure script. Change this line:
#if !defined(__STDC__) || __STDC__ != 1
To this:
#if !defined(__STDC__)
If you turn on __STDC__ with the -Xc option, the Sun compiler
can't compile with the Solaris `pthread.h' header file. This is a Sun
bug (broken compiler or broken include file).
If mysqld issues the following error message when you run it, you have
tried to compile MySQL with the Sun compiler without enabling the -mt
multi-thread option:
libc internal error: _rmutex_unlock: rmutex not held
Add -mt to CFLAGS and CXXFLAGS and recompile.
If you are using the SFW version of gcc (which comes with Solaris 8),
you must add `/opt/sfw/lib' to the environment variable
LD_LIBRARY_PATH before running configure.
If you are using the gcc available from sunfreeware.com, you may
have many problems. To avoid this, you should recompile gcc and GNU
binutils on the machine where you are running them.
If you get the following error when compiling MySQL with gcc,
it means that your gcc is not configured for your version of Solaris:
shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ... ./thr_alarm.c: In function `signal_hand': ./thr_alarm.c:556: too many arguments to function `sigwait'
The proper thing to do in this case is to get the newest version of
gcc and compile it with your current gcc compiler. At
least for Solaris 2.5, almost all binary versions of gcc have
old, unusable include files that break all programs that use
threads, and possibly other programs!
Solaris doesn't provide static versions of all system libraries
(libpthreads and libdl), so you can't compile MySQL
with --static. If you try to do so, you get one of the following
errors:
ld: fatal: library -ldl: not found undefined reference to `dlopen' cannot find -lrt
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory
This problem can be avoided by one of the following methods:
-Wl,r/full/path/to/libmysqlclient.so
flag rather than with -Lpath).
libmysqclient.so to `/usr/lib'.
LD_RUN_PATH environment variable before running your client.
If you have problems with configure trying to link with -lz when
you don't have zlib installed, you have two options:
zlib from ftp.gnu.org.
configure with the --with-named-z-libs=no option when
building MySQL.
If you are using gcc and have problems with loading user-defined
functions (UDFs) into MySQL, try adding -lgcc to the link line
for the UDF.
If you would like MySQL to start automatically, you can copy `support-files/mysql.server' to `/etc/init.d' and create a symbolic link to it named `/etc/rc3.d/S99mysql.server'.
If too many processes try to connect very rapidly to mysqld, you should
see this error in the MySQL log:
Error in accept: Protocol error
You might try starting the server with the --back_log=50
option as a workaround for this. (Use -O back_log=50 before MySQL 4.)
Solaris doesn't support core files for setuid() applications, so
you can't get a core file from mysqld if you are using the
--user option.
Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8.
MySQL 3.23.4 and above should be able to detect new versions of Solaris automatically and enable workarounds for the following problems.
Solaris 2.7 / 2.8 has some bugs in the include files. You may see the
following error when you use gcc:
/usr/include/widec.h:42: warning: `getwc' redefined /usr/include/wchar.h:326: warning: this is the location of the previous definition
If this occurs, you can fix the problem by copying
/usr/include/widec.h to
.../lib/gcc-lib/os/gcc-version/include and changing line 41 from this:
#if !defined(lint) && !defined(__lint)
To this:
#if !defined(lint) && !defined(__lint) && !defined(getwc)
Alternatively, you can edit `/usr/include/widec.h' directly. Either
way, after you make the fix, you should remove `config.cache' and run
configure again.
If you get the following errors when you run make, it's because
configure didn't detect the `curses.h' file (probably
because of the error in `/usr/include/widec.h'):
In file included from mysql.cc:50: /usr/include/term.h:1060: syntax error before `,' /usr/include/term.h:1081: syntax error before `;'
The solution to this problem is to do one of the following:
CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure.
configure.
#define HAVE_TERM line from the `config.h' file and
run make again.
If your linker can't find -lz when linking
client programs, the problem is probably that your `libz.so' file is
installed in `/usr/local/lib'. You can fix this problem by one of the
following methods:
LD_LIBRARY_PATH.
zlib from your
Solaris 8 CD distribution.
configure with the --with-named-z-libs=no option when
building MySQL.
On Solaris 8 on x86, mysqld dumps core if you remove the
debug symbols using strip.
If you are using gcc or egcs on Solaris x86 and you
experience problems with core dumps under load, you should use the
following configure command:
CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti -DHAVE_CURSES_H" \
./configure --prefix=/usr/local/mysql
This avoids problems with the libstdc++ library and with C++
exceptions.
If this doesn't help, you should compile a debug version and run
it with a trace file or under gdb.
See section E.1.3 Debugging mysqld under gdb.
This section provides information about using MySQL on variants of BSD Unix.
FreeBSD 4.x or newer is recommended for running MySQL, because the thread
package is much more integrated.
To get a secure and stable system, you should use only FreeBSD kernels
that are marked -RELEASE.
The easiest (and preferred) way to install MySQL is to use the
mysql-server and mysql-client ports available at
http://www.freebsd.org/.
Using these ports gives you the following benefits:
pkg_info -L to see which files are installed.
pkg_delete to remove MySQL if you no longer want it
on your machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x, and native threads on
Versions 3 and up. It is possible to run with native threads on some late
2.2.x versions, but you may encounter problems shutting down mysqld.
Unfortunately, certain function calls on FreeBSD are not yet fully thread-safe.
Most notably, this includes the gethostbyname() function, which is
used by MySQL to convert hostnames into IP addresses. Under certain
circumstances, the mysqld process suddenly causes 100%
CPU load and is unresponsive. If you encounter this problem, try to start
MySQL using the --skip-name-resolve option.
Alternatively, you can link MySQL on FreeBSD 4.x against the LinuxThreads library, which avoids a few of the problems that the native FreeBSD thread implementation has. For a very good comparison of LinuxThreads versus native threads, see Jeremy Zawodny's article FreeBSD or Linux for your MySQL Server? at http://jeremy.zawodny.com/blog/archives/000697.html.
A known problem when using LinuxThreads on FreeBSD is that the
wait_timeout value is not honored (probably a signal handling problem in
FreeBSD/LinuxThreads). This is supposed to be fixed in FreeBSD 5.0.
The symptom is that persistent connections can hang for a very long
time without getting closed down.
The MySQL build process requires GNU make (gmake) to work. If
GNU make is not available, you must install it first before compiling
MySQL.
The recommended way to compile and install MySQL on FreeBSD with
gcc (2.95.2 and up) is:
CC=gcc CFLAGS="-O2 -fno-strength-reduce" \
CXX=gcc CXXFLAGS="-O2 -fno-rtti -fno-exceptions \
-felide-constructors -fno-strength-reduce" \
./configure --prefix=/usr/local/mysql --enable-assembler
gmake
gmake install
cd /usr/local/mysql
bin/mysql_install_db --user=mysql
bin/mysqld_safe &
If you notice that configure uses MIT-pthreads, you should read
the MIT-pthreads notes. See section 2.8.5 MIT-pthreads Notes.
If you get an error from make install that it can't find
`/usr/include/pthreads', configure didn't detect that you need
MIT-pthreads. To fix this problem, remove `config.cache', then re-run
configure with the --with-mit-threads option.
Be sure that your name resolver setup is correct. Otherwise, you may
experience resolver delays or failures when connecting to mysqld.
Also make sure that the localhost entry in the `/etc/hosts' file is
correct. The file should start with a line similar to this:
127.0.0.1 localhost localhost.your.domain
FreeBSD is known to have a very low default file handle limit.
See section A.2.17 File Not Found. Start the server by using the
--open-files-limit option for mysqld_safe, or raise
the limits for the mysqld user in `/etc/login.conf' and
rebuild it with cap_mkdb /etc/login.conf. Also be sure that you set
the appropriate class for this user in the password file if you are not
using the default (use chpass mysqld-user-name).
See section 5.1.3 The mysqld_safe Server Startup Script.
If you have a lot of memory, you should consider rebuilding
the kernel to allow MySQL to use more than 512MB of RAM.
Take a look at option MAXDSIZ in the LINT config
file for more information.
If you get problems with the current date in MySQL, setting the
TZ variable should help. See section F Environment Variables.
To compile on NetBSD, you need GNU make. Otherwise, the build process
fails when make tries to run lint on C++ files.
On OpenBSD Version 2.5, you can compile MySQL with native threads with the following options:
CFLAGS=-pthread CXXFLAGS=-pthread ./configure --with-mit-threads=no
Our users have reported that OpenBSD 2.8 has a threading bug that causes problems with MySQL. The OpenBSD Developers have fixed the problem, but as of January 25, 2001, it's only available in the ``-current'' branch. The symptoms of this threading bug are slow response, high load, high CPU usage, and crashes.
If you get an error like Error in accept:: Bad file descriptor or
error 9 when trying to open tables or directories, the problem is probably
that you have not allocated enough file descriptors for MySQL.
In this case, try starting mysqld_safe as root with the following
options:
mysqld_safe --user=mysql --open-files-limit=2048 &
If you get the following error when compiling MySQL, your
ulimit value for virtual memory is too low:
item_func.h: In method `Item_func_ge::Item_func_ge(const Item_func_ge &)': item_func.h:28: virtual memory exhausted make[2]: *** [item_func.o] Error 1
Try using ulimit -v 80000 and run make again. If this
doesn't work and you are using bash, try switching to csh
or sh; some BSDI users have reported problems with bash
and ulimit.
If you are using gcc, you may also use have to use the
--with-low-memory flag for configure to be able to compile
`sql_yacc.cc'.
If you get problems with the current date in MySQL, setting the
TZ variable should help. See section F Environment Variables.
Upgrade to BSD/OS Version 3.1. If that is not possible, install BSDIpatch M300-038.
Use the following command when configuring MySQL:
env CXX=shlicc++ CC=shlicc2 \
./configure \
--prefix=/usr/local/mysql \
--localstatedir=/var/mysql \
--without-perl \
--with-unix-socket-path=/var/mysql/mysql.sock
The following is also known to work:
env CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure \
--prefix=/usr/local/mysql \
--with-unix-socket-path=/var/mysql/mysql.sock
You can change the directory locations if you wish, or just use the defaults by not specifying any locations.
If you have problems with performance under heavy load, try using the
--skip-thread-priority option to mysqld. This runs
all threads with the same priority. On BSDI Version 3.1, this gives better
performance, at least until BSDI fixes its thread scheduler.
If you get the error virtual memory exhausted while compiling,
you should try using ulimit -v 80000 and running make again.
If this doesn't work and you are using bash, try switching to
csh or sh; some BSDI users have reported problems with
bash and ulimit.
BSDI Version 4.x has some thread-related bugs. If you want to use MySQL on this, you should install all thread-related patches. At least M400-023 should be installed.
On some BSDI Version 4.x systems, you may get problems with shared libraries.
The symptom is that you can't execute any client programs, for example,
mysqladmin. In this case, you need to reconfigure not to use
shared libraries with the --disable-shared option to configure.
Some customers have had problems on BSDI 4.0.1 that the mysqld
binary after a while can't open tables. This is because some
library/system-related bug causes mysqld to change current
directory without having asked for that to happen.
The fix is to either upgrade MySQL to at least version 3.23.34 or, after
running configure, remove the line #define HAVE_REALPATH from
config.h before running make.
Note that this means that you can't symbolically link a database directories to another database directory or symbolic link a table to another database on BSDI. (Making a symbolic link to another disk is okay).
There are a couple of small problems when compiling MySQL on
HP-UX. We recommend that you use gcc instead of the HP-UX native
compiler, because gcc produces better code.
We recommend using gcc 2.95 on HP-UX. Don't use high optimization
flags (such as -O6) because they may not be safe on HP-UX.
The following configure line should work with gcc 2.95:
CFLAGS="-I/opt/dce/include -fpic" \
CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
-fno-rtti" \
CXX=gcc \
./configure --with-pthread \
--with-named-thread-libs='-ldce' \
--prefix=/usr/local/mysql --disable-shared
The following configure line should work with gcc 3.1:
CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \
-fno-exceptions -fno-rtti -O3 -fPIC" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --with-pthread \
--with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
--disable-shared
For HP-UX Version 11.x, we recommend MySQL 3.23.15 or later.
Because of some critical bugs in the standard HP-UX libraries, you should install the following patches before trying to run MySQL on HP-UX 11.0:
PHKL_22840 Streams cumulative PHNE_22397 ARPA cumulative
This solves the problem of getting EWOULDBLOCK from recv()
and EBADF from accept() in threaded applications.
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system,
you may get the following error:
In file included from /usr/include/unistd.h:11,
from ../include/global.h:125,
from mysql_priv.h:15,
from item.cc:19:
/usr/include/sys/unistd.h:184: declaration of C function ...
/usr/include/sys/pthread.h:440: previous declaration ...
In file included from item.h:306,
from mysql_priv.h:158,
from item.cc:19:
The problem is that HP-UX doesn't define pthreads_atfork() consistently.
It has conflicting prototypes in
`/usr/include/sys/unistd.h':184 and
`/usr/include/sys/pthread.h':440.
One solution is to copy `/usr/include/sys/unistd.h' into `mysql/include' and edit `unistd.h' and change it to match the definition in `pthread.h'. Look for this line:
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
void (*child)());
Change it to look like this:
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
void (*child)(void));
After making the change, the following configure line should work:
CFLAGS="-fomit-frame-pointer -O3 -fpic" CXX=gcc \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti -O3" \ ./configure --prefix=/usr/local/mysql --disable-shared
If you are using MySQL 4.0.5 with the HP-UX compiler, you can use the following
command (which has been tested with cc B.11.11.04):
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
--with-extra-character-set=complex
You can ignore any errors of the following type:
aCC: warning 901: unknown option: `-3': use +help for online documentation
If you get the following error from configure,
verify that you don't have the path to the K&R compiler before the path
to the HP-UX C and C++ compiler:
checking for cc option to accept ANSI C... no configure: error: MySQL requires an ANSI C compiler (and a C++ compiler). Try gcc. See the Installation chapter in the Reference Manual.
Another reason for not being able to compile is that you didn't define
the +DD64 flags as just described.
Another possibility for HP-UX 11 is to use MySQL binaries for HP-UX 10.20. We have received reports from some users that these binaries work fine on HP-UX 11.00. If you encounter problems, be sure to check your HP-UX patch level.
Automatic detection of xlC is missing from Autoconf, so a number of
variables need to be set before running configure. The following
example uses the IBM compiler:
export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
export CFLAGS="-I /usr/local/include"
export LDFLAGS="-L /usr/local/lib"
export CPPFLAGS=$CFLAGS
export CXXFLAGS=$CFLAGS
./configure --prefix=/usr/local \
--localstatedir=/var/mysql \
--sbindir='/usr/local/bin' \
--libexecdir='/usr/local/bin' \
--enable-thread-safe-client \
--enable-large-files
The preceding options are used to compile the MySQL distribution that can be found at http://www-frec.bull.com/.
If you change the -O3 to -O2 in the preceding configure
line, you must also remove the -qstrict option. This is a limitation in
the IBM C compiler.
If you are using gcc or egcs to compile MySQL, you
must use the -fno-exceptions flag, because the exception
handling in gcc/egcs is not thread-safe! (This is tested with
egcs 1.1.) There are also some known problems with IBM's assembler
that may cause it to generate bad code when used with gcc.
We recommend the following configure line with egcs and
gcc 2.95 on AIX:
CC="gcc -pipe -mcpu=power -Wa,-many" \ CXX="gcc -pipe -mcpu=power -Wa,-many" \ CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti" \ ./configure --prefix=/usr/local/mysql --with-low-memory
The -Wa,-many option is necessary for the compile to be successful.
IBM is aware of this problem but is in no hurry to fix it because of the
workaround that is available. We don't know if the -fno-exceptions
is required with gcc 2.95, but because MySQL doesn't use exceptions
and the option generates faster code, we recommend that you should always
use it with egcs / gcc.
If you get a problem with assembler code, try changing the -mcpu=xxx
option to match your CPU. Typically power2, power, or
powerpc may need to be used. Alternatively, you might need to use
604 or 604e. We are not positive but suspect that
power would likely be safe most of the time, even on
a power2 machine.
If you don't know what your CPU is, execute a uname -m command. It
produces a string that looks like 000514676700, with a format of
xxyyyyyymmss where xx and ss are always 00,
yyyyyy is a unique system ID and mm is the ID of the CPU Planar.
A chart of these values can be found at
http://www16.boulder.ibm.com/pseries/en_US/cmds/aixcmds5/uname.htm.
This gives you a machine type and a machine model you can use to
determine what type of CPU you have.
If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring as follows:
CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
-DDONT_USE_THR_ALARM" \
./configure --prefix=/usr/local/mysql --with-debug \
--with-low-memory
This doesn't affect the performance of MySQL, but has the side
effect that you can't kill clients that are ``sleeping'' on a connection with
mysqladmin kill or mysqladmin shutdown. Instead, the client
dies when it issues its next command.
On some versions of AIX, linking with libbind.a makes
getservbyname() dump core. This is an AIX bug and should be reported
to IBM.
For AIX 4.2.1 and gcc, you have to make the following changes.
After configuring, edit `config.h' and `include/my_config.h' and change the line that says this:
#define HAVE_SNPRINTF 1
to this:
#undef HAVE_SNPRINTF
And finally, in `mysqld.cc', you need to add a prototype for
initgroups().
#ifdef _AIX41 extern "C" int initgroups(const char *,int); #endif
If you need to allocate a lot of memory to the mysqld process, it's not
enough to just use ulimit -d unlimited. You may also have to modify
mysqld_safe to add a line something like this:
export LDR_CNTRL='MAXDATA=0x80000000'
You can find more information about using a lot of memory at http://publib16.boulder.ibm.com/pseries/en_US/aixprggd/genprogc/lrg_prg_support.htm.
On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn
means you need GNU make.
Some SunOS 4 systems have problems with dynamic libraries and libtool.
You can use the following configure line to avoid this problem:
./configure --disable-shared --with-mysqld-ldflags=-all-static
When compiling readline, you may get warnings about duplicate defines.
These can be ignored.
When compiling mysqld, there are some implicit declaration
of function warnings. These can be ignored.
If you are using egcs 1.1.2 on Digital Unix, you should upgrade to
gcc 2.95.2, because egcs on DEC has some serious bugs!
When compiling threaded programs under Digital Unix, the documentation
recommends using the -pthread option for cc and cxx and
the -lmach -lexc libraries (in addition to -lpthread). You
should run configure something like this:
CC="cc -pthread" CXX="cxx -pthread -O" \ ./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"
When compiling mysqld, you may see a couple of warnings like this:
mysqld.cc: In function void handle_connections()': mysqld.cc:626: passing long unsigned int *' as argument 3 of accept(int,sockadddr *, int *)'
You can safely ignore these warnings. They occur because configure
can detect only errors, not warnings.
If you start the server directly from the command line, you may have problems
with it dying when you log out. (When you log out, your outstanding processes
receive a SIGHUP signal.) If so, try starting the server like this:
nohup mysqld [options] &
nohup causes the command following it to ignore any SIGHUP
signal sent from the terminal. Alternatively, start the server by running
mysqld_safe, which invokes mysqld using nohup for you.
See section 5.1.3 The mysqld_safe Server Startup Script.
If you get a problem when compiling `mysys/get_opt.c', just remove the
#define _NO_PROTO line from the start of that file.
If you are using Compaq's CC compiler, the following configure line
should work:
CC="cc -pthread"
CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all -arch host"
CXX="cxx -pthread"
CXXFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed all \
-arch host -noexceptions -nortti"
export CC CFLAGS CXX CXXFLAGS
./configure \
--prefix=/usr/local/mysql \
--with-low-memory \
--enable-large-files \
--enable-shared=yes \
--with-named-thread-libs="-lpthread -lmach -lexc -lc"
gnumake
If you get a problem with libtool when compiling with shared libraries
as just shown, when linking mysql, you should be able to get around
this by issuing these commands:
cd mysql
/bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \
-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \
-o mysql mysql.o readline.o sql_string.o completion_hash.o \
../readline/libreadline.a -lcurses \
../libmysql/.libs/libmysqlclient.so -lm
cd ..
gnumake
gnumake install
scripts/mysql_install_db
If you have problems compiling and have DEC CC and gcc
installed, try running configure like this:
CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \ ./configure --prefix=/usr/local/mysql
If you get problems with the `c_asm.h' file, you can create and use a 'dummy' `c_asm.h' file with:
touch include/c_asm.h CC=gcc CFLAGS=-I./include \ CXX=gcc CXXFLAGS=-O3 \ ./configure --prefix=/usr/local/mysql
Note that the following problems with the ld program can be fixed
by downloading the latest DEC (Compaq) patch kit from:
http://ftp.support.compaq.com/public/unix/.
On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev. 878),"
the compiler had some strange behavior (undefined asm symbols).
/bin/ld also appears to be broken (problems with _exit
undefined errors occurring while linking mysqld). On this system, we
have managed to compile MySQL with the following configure
line, after replacing /bin/ld with the version from OSF 4.0C:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql
With the Digital compiler "C++ V6.1-029," the following should work:
CC=cc -pthread
CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host
CXX=cxx -pthread
CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host -noexceptions -nortti
export CC CFLAGS CXX CXXFLAGS
./configure --prefix=/usr/mysql/mysql \
--with-mysqld-ldflags=-all-static --disable-shared \
--with-named-thread-libs="-lmach -lexc -lc"
In some versions of OSF/1, the alloca() function is broken. Fix
this by removing the line in `config.h' that defines 'HAVE_ALLOCA'.
The alloca() function also may have an incorrect prototype in
/usr/include/alloca.h. This warning resulting from this can be ignored.
configure uses the following thread libraries automatically:
--with-named-thread-libs="-lpthread -lmach -lexc -lc".
When using gcc, you can also try running configure like this:
CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ...
If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring with:
CFLAGS=-DDONT_USE_THR_ALARM \ CXXFLAGS=-DDONT_USE_THR_ALARM \ ./configure ...
This doesn't affect the performance of MySQL, but has the side
effect that you can't kill clients that are ``sleeping'' on a connection with
mysqladmin kill or mysqladmin shutdown. Instead, the client
dies when it issues its next command.
With gcc 2.95.2, you may encounter the following compile error:
sql_acl.cc:1456: Internal compiler error in `scan_region', at except.c:2566 Please submit a full bug report.
To fix this, you should change to the sql directory and do a
cut-and-paste of the last gcc line, but change -O3 to
-O0 (or add -O0 immediately after gcc if you don't
have any -O option on your compile line). After this is done, you
can just change back to the top-level directory and run make
again.
If you are using Irix Version 6.5.3 or newer, mysqld is able to
create threads only if you run it as a user that has CAP_SCHED_MGT
privileges (such as root) or give the mysqld server this privilege
with the following shell command:
chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld
You may have to undefine some symbols in `config.h' after running
configure and before compiling.
In some Irix implementations, the alloca() function is broken. If the
mysqld server dies on some SELECT statements, remove the lines
from `config.h' that define HAVE_ALLOC and HAVE_ALLOCA_H.
If mysqladmin create doesn't work, remove the line from `config.h'
that defines HAVE_READDIR_R. You may have to remove the
HAVE_TERM_H line as well.
SGI recommends that you install all the patches on this page as a set: http://support.sgi.com/surfzone/patches/patchset/6.2_indigo.rps.html
At the very minimum, you should install the latest kernel rollup, the
latest rld rollup, and the latest libc rollup.
You definitely need all the POSIX patches on this page, for pthreads support:
http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html
If you get the something like the following error when compiling `mysql.cc':
"/usr/include/curses.h", line 82: error(1084): invalid combination of type
Type the following in the top-level directory of your MySQL source tree:
extra/replace bool curses_bool < /usr/include/curses.h > include/curses.h make
There have also been reports of scheduling problems. If only one thread is running, performance is slow. Avoid this by starting another client. This may lead to a two-to-tenfold increase in execution speed thereafter for the other thread. This is a poorly understood problem with Irix threads; you may have to improvise to find solutions until this can be fixed.
If you are compiling with gcc, you can use the following
configure command:
CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql --enable-thread-safe-client \
--with-named-thread-libs=-lpthread
On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the following is reported to work
CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \
-L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \
-I/usr/local/include -L/usr/local/lib' \
./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \
--with-libwrap=/usr/local \
--with-named-curses-libs=/usr/local/lib/libncurses.a
The current port is tested only on ``sco3.2v5.0.5,'' ``sco3.2v5.0.6,'' and ``sco3.2v5.0.7'' systems. There has also been a lot of progress on a port to ``sco 3.2v4.2.'' Open Server 5.0.8(Legend) has native threads and allows files greater than 2GB. The current maximum file size is 2GB.
We have been able to compile MySQL with the following configure
command on OpenServer with gcc 2.95.3.
CC=gcc CXX=gcc ./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-innodb \
--with-openssl --with-vio --with-extra-charsets=complex
gcc is available at
ftp://ftp.sco.com/pub/openserver5/opensrc/gnutools-5.0.7Kj.
This development system requires the OpenServer Execution Environment Supplement oss646B on OpenServer 5.0.6 and oss656B and The OpenSource libraries found in gwxlibs. All OpenSource tools are in the `opensrc' directory. They are available at ftp://ftp.sco.com/pub/openserver5/opensrc/.
We recommend using the latest production release of MySQL.
SCO provides operating system patches at ftp://ftp.sco.com/pub/openserver5 for OpenServer 5.0.[0-6] and ftp://ftp.sco.com/pub/openserverv5/507 for OpenServer 5.0.7.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenServer for OpenServer 5.0.x.
The maximum file size on an OpenSever 5.0.x system is 2GB.
The total memory which could be allocated for streams buffers, clists and lock records cannot exceed 60MB on OpenServer 5.0.x.
Streams buffers are allocated in units of 4096 byte pages, clists are 70 bytes each, and lock records are 64 bytes each, so:
(NSTRPAGES * 4096) + (NCLIST * 70) + (MAX_FLCKREC * 64) <= 62914560
Follow this procedure to configure the Database Services option. If you are unsure whether an application requires this, see the documentation provided with the application.
root.
N in the second field to a Y.
mkdev aio or the Hardware/Kernel Manager to enable support for
asynchronous I/O and relink the kernel. To allow users to lock down memory
for use with this type of I/O, update the aiomemlock(F) file. This file
should be updated to include the names of users that can use AIO and the
maximum amounts of memory they can lock down.
After you complete this process, reboot the system to create a new kernel incorporating these changes.
By default, the entries in `/etc/conf/cf.d/mtune' are set as follows:
Value Default Min Max ----- ------- -- --- NBUF 0 24 450000 NHBUF 0 32 524288 NMPBUF 0 12 512 MAX_INODE 0 100 64000 MAX_FILE 0 100 64000 CTBUFSIZE 128 0 256 MAX_PROC 0 50 16000 MAX_REGION 0 500 160000 NCLIST 170 120 16640 MAXUP 100 15 16000 NOFILES 110 60 11000 NHINODE 128 64 8192 NAUTOUP 10 0 60 NGROUPS 8 0 128 BDFLUSHR 30 1 300 MAX_FLCKREC 0 50 16000 PUTBUFSZ 8000 2000 20000 MAXSLICE 100 25 100 ULIMIT 4194303 2048 4194303 * Streams Parameters NSTREAM 64 1 32768 NSTRPUSH 9 9 9 NMUXLINK 192 1 4096 STRMSGSZ 16384 4096 524288 STRCTLSZ 1024 1024 1024 STRMAXBLK 524288 4096 524288 NSTRPAGES 500 0 8000 STRSPLITFRAC 80 50 100 NLOG 3 3 3 NUMSP 64 1 256 NUMTIM 16 1 8192 NUMTRW 16 1 8192 * Semaphore Parameters SEMMAP 10 10 8192 SEMMNI 10 10 8192 SEMMNS 60 60 8192 SEMMNU 30 10 8192 SEMMSL 25 25 150 SEMOPM 10 10 1024 SEMUME 10 10 25 SEMVMX 32767 32767 32767 SEMAEM 16384 16384 16384 * Shared Memory Parameters SHMMAX 524288 131072 2147483647 SHMMIN 1 1 1 SHMMNI 100 100 2000 FILE 0 100 64000 NMOUNT 0 4 256 NPROC 0 50 16000 NREGION 0 500 160000
We recommend setting these values as follows:
NOFILES should be 4096 or 2048.
MAXUP should be 2048.
To make changes to the kernel, cd to `/etc/conf/bin' and
use ./idtune name parameter to make the changes. For example,
to change SEMMS to 200, execute these commands as root:
# cd /etc/conf/bin # ./idtune SEMMNS 200
We recommend tuning the system, but the proper parameter values to use depend on the number of users accessing the application or database and size the of the database (that is, the used buffer pool). The following affects the kernel parameters defined in `/etc/conf/cf.d/stune':
SHMMAX (recommended setting: 128MB) and SHMSEG (recommended
setting: 15).
These parameters have influence on the MySQL database engine to create
user buffer pools.
NOFILES and MAXUP should be at to at least 2048.
MAXPROC should be set to at least 3000/4000 (depends on number of users)
or more.
Also is recommended to use following formula to count value for SEMMSL,
SEMMNS and SEMMNU:
SEMMSL = 13
The 13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system.
Set SEMMNS to the value of SEMMSL multiplied by the number of
db servers (maximum) that you are running on the system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the value of SEMMNS. You
could probably set this to 75% of SEMMNS, but this is a conservative
estimate.
You need to at least install the "SCO OpenServer Linker and Application
Development Libraries" or the OpenServer Development System to use gcc.
You cannot just use the GCC Dev system without installing one of these.
You should get the FSU Pthreads package and install it first. This can be found at http://moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz. You can also get a precompiled package from ftp://ftp.zenez.com/pub/zenez/prgms/FSU-threads-3.14.tar.gz.
FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip, or using OpenServer 3.0 or Open Desktop 3.0 (OS 3.0 ODT 3.0) with the SCO Development System installed using a good port of GCC 2.5.x. For ODT or OS 3.0, you need a good port of GCC 2.5.x. There are a lot of problems without a good port. The port for this product requires the SCO Unix Development system. Without it, you are missing the libraries and the linker that is needed. You also need `SCO-3.2v4.2-includes.tar.gz'. This file contains the changes to the SCO Development include files that are needed to get MySQL to build. You need to replace the existing system include files with these modified header files. They can be obtained from ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
To build FSU Pthreads on your system,
all you should need to do is run GNU make. The `Makefile' in
FSU-threads-3.14.tar.gz is set up to make FSU-threads.
You can run ./configure in the `threads/src' directory and
select the SCO OpenServer option. This command copies `Makefile.SCO5' to
`Makefile'. Then run make.
To install in the default `/usr/include' directory, log in as
root, then cd to the `thread/src' directory and run
make install.
Remember that you must use GNU make when making MySQL.
Note: If you don't start mysqld_safe as root, you
should get only the default 110 open files per process. mysqld
writes a note about this in the log file.
With SCO 3.2V4.2, you should use FSU Pthreads version 3.14 or newer.
The following configure command should work:
CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
./configure \
--prefix=/usr/local/mysql \
--with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
--with-named-curses-libs="-lcurses"
You may get some problems with some include files. In this case, you can find new SCO-specific include files at ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
You should unpack this file in the `include' directory of your MySQL source tree.
SCO development notes:
mysqld with
-lgthreads -lsocket -lgthreads.
malloc. If you encounter problems with memory usage,
make sure that `gmalloc.o' is included in `libgthreads.a' and
`libgthreads.so'.
read(), write(), getmsg(), connect(),
accept(), select(), and wait().
mysqld unstable. You have to remove this one if you want to run
mysqld on an OpenServer 5.0.6 machine.
libsocket.so.2 at
ftp://ftp.sco.com/pub/security/OpenServer and
ftp://ftp.sco.com/pub/security/sse for OpenServer 5.0.x.
telnetd fix at
ftp://stage.caldera.com/pub/security/openserver/ or
ftp://stage.caldera.com/pub/security/openserver/CSSA-2001-SCO.10/ as
both `libsocket.so.2' and `libresolv.so.1' with instructions for
installing on pre-OSR506 systems.
It's probably a good idea to install these
patches before trying to compile/use MySQL.
Beginning with Legend, OpenServer has native threads and no 2GB file size limit.
We recommend using the latest production release of MySQL. Currently this is MySQL 4.0.x. Should you choose to use an older release of MySQL on UnixWare 7.1.x, you must use a version of MySQL at least as recent as 3.22.13 to get fixes for some portability and OS problems.
We have been able to compile MySQL with the following configure
command on UnixWare Version 7.1.x:
CC="cc" CFLAGS="-I/usr/local/include" \
CXX="CC" CXXFLAGS="-I/usr/local/include" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-berkeley-db=./bdb \
--with-innodb --with-openssl --with-extra-charsets=complex
If you want to use gcc, you must use gcc 2.95.3 or newer.
CC=gcc CXX=g++ ./configure --prefix=/usr/local/mysql
SCO provides operating system patches at ftp://ftp.sco.com/pub/unixware7 for UnixWare 7.1.1, ftp://ftp.sco.com/pub/unixware7/713/ for UnixWare 7.1.3, ftp://ftp.sco.com/pub/unixware7/714/ for UnixWare 7.1.4, and ftp://ftp.sco.com/pub/openunix8 for OpenUNIX 8.0.0.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenUNIX for OpenUNIX and ftp://ftp.sco.com/pub/security/UnixWare for UnixWare.
By default, the maximum file size on a UnixWare 7 system is 1GB. Many OS utilities have a limitation of 2GB. The maximum possible file size on UnixWare 7 is 1TB with VXFS.
To enable large file support on UnixWare 7.1.x, run fsadm.
# fsadm -Fvxfs -o largefiles / # fsadm / * Note # ulimit unlimited # cd /etc/conf/bin # ./idtune SFSZLIM 0x7FFFFFFF ** Note # ./idtune HFSZLIM 0x7FFFFFFF ** Note # ./idbuild -B * This should report "largefiles". ** 0x7FFFFFFF represents infinity for these values.
Reboot the system using shutdown.
By default, the entries in `/etc/conf/cf.d/mtune' are set to:
Value Default Min Max ----- ------- -- --- SVMMLIM 0x9000000 0x1000000 0x7FFFFFFF HVMMLIM 0x9000000 0x1000000 0x7FFFFFFF SSTKLIM 0x1000000 0x2000 0x7FFFFFFF HSTKLIM 0x1000000 0x2000 0x7FFFFFFF
We recommend setting these values as follows:
SDATLIM 0x7FFFFFFF HDATLIM 0x7FFFFFFF SSTKLIM 0x7FFFFFFF HSTKLIM 0x7FFFFFFF SVMMLIM 0x7FFFFFFF HVMMLIM 0x7FFFFFFF SFNOLIM 2048 HFNOLIM 2048
We recommend tuning the system, but the proper parameter values to use depend on the number of users accessing the application or database and size the of the database (that is, the used buffer pool). The following affects the kernel parameters defined in `/etc/conf/cf.d/stune':
SHMMAX (recommended setting: 128MB) and SHMSEG (recommended
setting: 15).
These parameters have influence on the MySQL database engine to create
user buffer pools.
SFNOLIM and HFNOLIM should be at maximum 2048.
NPROC should be set to at least 3000/4000 (depends on number of users).
Also is recommended to use following formula to count value for SEMMSL,
SEMMNS, and SEMMNU:
SEMMSL = 13
13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system.
Set SEMMNS to the value of SEMMSL multiplied by the number
of db servers (maximum) that you are running on the system at one time.
SEMMNU = SEMMNS
Set the value of SEMMNU to equal the value of SEMMNS. You
could probably set this to 75% of SEMMNS, but this is a conservative estimate.
MySQL uses quite a few open files. Because of this, you should add something like the following to your `CONFIG.SYS' file:
SET EMXOPT=-c -n -h1024
If you don't do this, you may encounter the following error:
File 'xxxx' not found (Errcode: 24)
When using MySQL with OS/2 Warp 3, FixPack 29 or above is required. With OS/2 Warp 4, FixPack 4 or above is required. This is a requirement of the Pthreads library. MySQL must be installed on a partition with a type that supports long filenames, such as HPFS, FAT32, and so on.
The `INSTALL.CMD' script must be run from OS/2's own `CMD.EXE' and may not work with replacement shells such as `4OS2.EXE'.
The `scripts/mysql-install-db' script has been renamed. It is called `install.cmd' and is a REXX script, which sets up the default MySQL security settings and creates the WorkPlace Shell icons for MySQL.
Dynamic module support is compiled in but not fully tested. Dynamic modules should be compiled using the Pthreads runtime library.
gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
-o example udf_example.cc -L../lib -lmysqlclient udf_example.def
mv example.dll example.udf
Note: Due to limitations in OS/2, UDF module name stems must not
exceed eight characters. Modules are stored in the `/mysql2/udf'
directory; the safe-mysqld.cmd script puts this directory in
the BEGINLIBPATH environment variable. When using UDF modules,
specified extensions are ignored--it is assumed to be `.udf'.
For example, in Unix, the shared module might be named `example.so'
and you would load a function from it like this:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example.so';
In OS/2, the module would be named `example.udf', but you would not specify the module extension:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example';
We have in the past talked with some BeOS developers who have said that MySQL is 80% ported to BeOS, but we haven't heard from them in a while.
Perl support for MySQL is provided by means of the DBI/DBD
client interface. The interface requires Perl Version 5.6.0 or later.
It does not work if you have an older version of Perl.
If you want to use transactions with Perl DBI, you need to have
DBD::mysql version 1.2216 or newer. Version 2.9003 or newer
is recommended.
If you are using the MySQL 4.1 client library, you must use
DBD::mysql 2.9003 or newer.
As of MySQL 3.22.8, Perl support is no longer included with MySQL
distributions. You can obtain the necessary modules from
http://search.cpan.org for Unix, or by using the ActiveState
ppm program on Windows. The following sections describe how to do
this.
Perl support for MySQL must be installed if you want to run the MySQL benchmark scripts. See section 7.1.4 The MySQL Benchmark Suite.
MySQL Perl support requires that you've installed MySQL client programming support (libraries and header files). Most installation methods install the necessary files. However, if you installed MySQL from RPM files on Linux, be sure that you've installed the developer RPM. The client programs are in the client RPM, but client programming support is in the developer RPM.
If you want to install Perl support, the files you need can be obtained from the CPAN (Comprehensive Perl Archive Network) at http://search.cpan.org.
The easiest way to install Perl modules on Unix is to use the CPAN
module. For example:
shell> perl -MCPAN -e shell cpan> install DBI cpan> install DBD::mysql
The DBD::mysql installation runs a number of tests.
These tests require being able to connect to the local MySQL server
as the anonymous user with no password. If you have removed anonymous
accounts or assigned them passwords, the tests fail. You can use force
install DBD::mysql to ignore the failed tests.
DBI requires the Data::Dumper module. It may be
installed; if not, you should install it before installing DBI.
It is also possible to download the module distributions in the form of
compressed tar archives and build the modules manually. For example,
to unpack and build a DBI distribution, use a procedure such as this:
shell> gunzip < DBI-VERSION.tar.gz | tar xvf -This command creates a directory named `DBI-VERSION'.
shell> cd DBI-VERSION
shell> perl Makefile.PL shell> make shell> make test shell> make install
The make test command is important because it verifies that the
module is working. Note that when you run that command during the
DBD::mysql installation to exercise the interface code, the
MySQL server must be running or the test fails.
It is a good idea to rebuild and reinstall the DBD::mysql
distribution whenever you install a new release of MySQL,
particularly if you notice symptoms such as that all your DBI scripts
fail after you upgrade MySQL.
If you don't have access rights to install Perl modules in the system directory or if you want to install local Perl modules, the following reference may be useful: http://servers.digitaldaze.com/extensions/perl/modules.html#modules
Look under the heading ``Installing New Modules that Require Locally Installed Modules.''
On Windows, you should do the following to install the MySQL
DBD module with ActiveState Perl:
HTTP_proxy variable. For example, you might try:
set HTTP_proxy=my.proxy.com:3128
C:\> C:\perl\bin\ppm.pl
DBI:
ppm> install DBI
install \ ftp://ftp.de.uu.net/pub/CPAN/authors/id/JWIED/DBD-mysql-1.2212.x86.ppd
This procedure should work at least with ActiveState Perl Version 5.6.
If you can't get the procedure to work, you should instead install the MyODBC driver and connect to the MySQL server through ODBC:
use DBI;
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
die "Got error $DBI::errstr when connecting to $dsn\n";
DBI/DBD InterfaceIf Perl reports that it can't find the `../mysql/mysql.so' module, then the problem is probably that Perl can't locate the shared library `libmysqlclient.so'.
You should be able to fix this by one of the following methods:
DBD::mysql distribution with perl
Makefile.PL -static -config rather than perl Makefile.PL.
-L options used to compile DBD::mysql to reflect
the actual location of `libmysqlclient.so'.
LD_RUN_PATH environment variable. Some systems use
LD_LIBRARY_PATH instead.
Note that you may also need to modify the -L options if there are
other libraries that the linker fails to find. For example, if the linker
cannot find libc because it is in `/lib' and the link command
specifies -L/usr/lib, change the -L option to -L/lib
or add -L/lib to the existing link command.
If you get the following errors from DBD::mysql,
you are probably using gcc (or using an old binary compiled with
gcc):
/usr/bin/perl: can't resolve symbol '__moddi3' /usr/bin/perl: can't resolve symbol '__divdi3'
Add -L/usr/lib/gcc-lib/... -lgcc to the link command when the
`mysql.so' library gets built (check the output from make for
`mysql.so' when you compile the Perl client). The -L option
should specify the pathname of the directory where `libgcc.a' is located
on your system.
Another cause of this problem may be that Perl and MySQL aren't both
compiled with gcc. In this case, you can solve the mismatch by
compiling both with gcc.
You may see the following error from DBD::mysql
when you run the tests:
t/00base............install_driver(mysql) failed: Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql: ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
This means that you need to include the -lz compression library on the
link line. That can be done by changing the following line in the file
`lib/DBD/mysql/Install.pm':
$sysliblist .= " -lm";
Change that line to:
$sysliblist .= " -lm -lz";
After this, you must run make realclean and then
proceed with the installation from the beginning.
If you want to install DBI on SCO, you have to edit the
`Makefile' in DBI-xxx and each subdirectory.
Note that the following assumes gcc 2.95.2 or newer:
OLD: NEW: CC = cc CC = gcc CCCDLFLAGS = -KPIC -W1,-Bexport CCCDLFLAGS = -fpic CCDLFLAGS = -wl,-Bexport CCDLFLAGS = LD = ld LD = gcc -G -fpic LDDLFLAGS = -G -L/usr/local/lib LDDLFLAGS = -L/usr/local/lib LDFLAGS = -belf -L/usr/local/lib LDFLAGS = -L/usr/local/lib LD = ld LD = gcc -G -fpic OPTIMISE = -Od OPTIMISE = -O1 OLD: CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include NEW: CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include
These changes are necessary
because the Perl dynaloader does not load the DBI modules
if they were compiled with icc or cc.
If you want to use the Perl module on a system that doesn't support
dynamic linking (such as SCO), you can generate a static version of
Perl that includes DBI and DBD::mysql. The way this works
is that you generate a version of Perl with the DBI code linked
in and install it on top of your current Perl. Then you use that to
build a version of Perl that additionally has the DBD code linked
in, and install that.
On SCO, you must have the following environment variables set:
LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib:/usr/progressive/lib
Or:
LD_LIBRARY_PATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
LIBPATH=/usr/lib:/lib:/usr/local/lib:/usr/ccs/lib:\
/usr/progressive/lib:/usr/skunk/lib
MANPATH=scohelp:/usr/man:/usr/local1/man:/usr/local/man:\
/usr/skunk/man:
First, create a Perl that includes a statically linked DBI module by
running these commands in the directory where your DBI distribution is
located:
shell> perl Makefile.PL -static -config shell> make shell> make install shell> make perl
Then you must install the new Perl. The output of make perl
indicates the exact make command you need to execute to perform
the installation. On SCO, this is
make -f Makefile.aperl inst_perl MAP_TARGET=perl.
Next, use the just-created Perl to create another Perl that also includes a
statically linked DBD::mysql by running these commands in the
directory where your DBD::mysql distribution is located:
shell> perl Makefile.PL -static -config shell> make shell> make install shell> make perl
Finally, you should install this new Perl. Again, the output of make
perl indicates the command to use.
This chapter provides a tutorial introduction to MySQL by showing
how to use the mysql client program to create and use a simple
database. mysql (sometimes referred to as the ``terminal monitor'' or
just ``monitor'') is an interactive program that allows you to connect to a
MySQL server, run queries, and view the results. mysql may
also be used in batch mode: you place your queries in a file beforehand, then
tell mysql to execute the contents of the file. Both ways of using
mysql are covered here.
To see a list of options provided by mysql, invoke it with
the --help option:
shell> mysql --help
This chapter assumes that mysql is installed on your machine and that
a MySQL server is available to which you can connect. If this is
not true, contact your MySQL administrator. (If you are the
administrator, you need to consult other sections of this manual.)
This chapter describes the entire process of setting up and using a database. If you are interested only in accessing an existing database, you may want to skip over the sections that describe how to create the database and the tables it contains.
Because this chapter is tutorial in nature, many details are necessarily omitted. Consult the relevant sections of the manual for more information on the topics covered here.
To connect to the server, you'll usually need to provide a MySQL
username when you invoke mysql and, most likely, a password. If the
server runs on a machine other than the one where you log in, you'll also
need to specify a hostname. Contact your administrator to find out what
connection parameters you should use to connect (that is, what host, username,
and password to use). Once you know the proper parameters, you should be
able to connect like this:
shell> mysql -h host -u user -p Enter password: ********
host and user represent the hostname where your MySQL server is
running and the username of your MySQL account. Substitute appropriate values
for your setup.
The ******** represents your password; enter it when mysql
displays the Enter password: prompt.
If that works, you should see some introductory information followed by a
mysql> prompt:
shell> mysql -h host -u user -p Enter password: ******** Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 25338 to server version: 4.0.14-log Type 'help;' or '\h' for help. Type '\c' to clear the buffer. mysql>
The prompt tells you that mysql is ready for you to enter commands.
Some MySQL installations allow users to connect as the anonymous
(unnamed) user to the server running on the local host. If this is the case
on your machine, you should be able to connect to that server by invoking
mysql without any options:
shell> mysql
After you have connected successfully, you can disconnect any time by typing
QUIT (or \q) at the mysql> prompt:
mysql> QUIT Bye
On Unix, you can also disconnect by pressing Control-D.
Most examples in the following sections assume that you are connected to the
server. They indicate this by the mysql> prompt.
Make sure that you are connected to the server, as discussed in the previous
section. Doing so does not in itself select any database to work with, but
that's okay. At this point, it's more important to find out a little about
how to issue queries than to jump right in creating tables, loading data
into them, and retrieving data from them. This section describes the basic
principles of entering commands, using several queries you can try out to
familiarize yourself with how mysql works.
Here's a simple command that asks the server to tell you its version number
and the current date. Type it in as shown here following the mysql>
prompt and press Enter:
mysql> SELECT VERSION(), CURRENT_DATE; +--------------+--------------+ | VERSION() | CURRENT_DATE | +--------------+--------------+ | 3.22.20a-log | 1999-03-19 | +--------------+--------------+ 1 row in set (0.01 sec) mysql>
This query illustrates several things about mysql:
QUIT,
mentioned earlier, is one of them. We'll get to others later.)
mysql sends it to the server for execution
and displays the results, then prints another mysql> prompt to indicate
that it is ready for another command.
mysql displays query output in tabular form (rows and columns). The
first row contains labels for the columns. The rows following are the query
results. Normally, column labels are the names of the columns you fetch from
database tables. If you're retrieving the value of an expression rather than
a table column (as in the example just shown), mysql labels the column
using the expression itself.
mysql shows how many rows were returned and how long the query took
to execute, which gives you a rough idea of server performance. These values
are imprecise because they represent wall clock time (not CPU or machine
time), and because they are affected by factors such as server load and
network latency. (For brevity, the ``rows in set'' line is not shown in
the remaining examples in this chapter.)
Keywords may be entered in any lettercase. The following queries are equivalent:
mysql> SELECT VERSION(), CURRENT_DATE; mysql> select version(), current_date; mysql> SeLeCt vErSiOn(), current_DATE;
Here's another query. It demonstrates that you can use mysql as a
simple calculator:
mysql> SELECT SIN(PI()/4), (4+1)*5; +-------------+---------+ | SIN(PI()/4) | (4+1)*5 | +-------------+---------+ | 0.707107 | 25 | +-------------+---------+
The queries shown thus far have been relatively short, single-line statements. You can even enter multiple statements on a single line. Just end each one with a semicolon:
mysql> SELECT VERSION(); SELECT NOW(); +--------------+ | VERSION() | +--------------+ | 3.22.20a-log | +--------------+ +---------------------+ | NOW() | +---------------------+ | 1999-03-19 00:15:33 | +---------------------+
A command need not be given all on a single line, so lengthy commands that
require several lines are not a problem. mysql determines where your
statement ends by looking for the terminating semicolon, not by looking for
the end of the input line. (In other words, mysql
accepts free-format input: it collects input lines but does not execute them
until it sees the semicolon.)
Here's a simple multiple-line statement:
mysql> SELECT
-> USER()
-> ,
-> CURRENT_DATE;
+--------------------+--------------+
| USER() | CURRENT_DATE |
+--------------------+--------------+
| joesmith@localhost | 1999-03-18 |
+--------------------+--------------+
In this example, notice how the prompt changes from mysql> to
-> after you enter the first line of a multiple-line query. This is
how mysql indicates that it hasn't seen a complete statement and is
waiting for the rest. The prompt is your friend, because it provides
valuable feedback. If you use that feedback, you can always be aware of
what mysql is waiting for.
If you decide you don't want to execute a command that you are in the
process of entering, cancel it by typing \c:
mysql> SELECT
-> USER()
-> \c
mysql>
Here, too, notice the prompt. It switches back to mysql> after you
type \c, providing feedback to indicate that mysql is ready
for a new command.
The following table shows each of the prompts you may see and summarizes what
they mean about the state that mysql is in:
| Prompt | Meaning |
mysql> | Ready for new command. |
-> | Waiting for next line of multiple-line command. |
'> | Waiting for next line, collecting a string that begins with a single quote (`''). |
"> | Waiting for next line, collecting a string that begins with a double quote (`"'). |
`> | Waiting for next line, collecting an identifier that begins with a backtick (``'). |
Multiple-line statements commonly occur by accident when you intend to
issue a command on a single line, but forget the terminating semicolon. In
this case, mysql waits for more input:
mysql> SELECT USER()
->
If this happens to you (you think you've entered a statement but the only
response is a -> prompt), most likely mysql is waiting for the
semicolon. If you don't notice what the prompt is telling you, you might sit
there for a while before realizing what you need to do. Enter a semicolon to
complete the statement, and mysql executes it:
mysql> SELECT USER()
-> ;
+--------------------+
| USER() |
+--------------------+
| joesmith@localhost |
+--------------------+
The '> and "> prompts occur during string collection.
In MySQL, you can write strings surrounded by either `''
or `"' characters (for example, 'hello' or "goodbye"),
and mysql lets you enter strings that span multiple lines. When you
see a '> or "> prompt, it means that you've entered a line
containing a string that begins with a `'' or `"' quote character,
but have not yet entered the matching quote that terminates the string.
That's fine if you really are entering a multiple-line string, but how likely
is that? Not very. More often, the '> and "> prompts indicate
that you've inadvertently left out a quote character. For example:
mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
'>
If you enter this SELECT statement, then press Enter and wait for the
result, nothing happens. Instead of wondering why this
query takes so long, notice the clue provided by the '> prompt. It
tells you that mysql expects to see the rest of an unterminated
string. (Do you see the error in the statement? The string 'Smith is
missing the second quote.)
At this point, what do you do? The simplest thing is to cancel the command.
However, you cannot just type \c in this case, because mysql
interprets it as part of the string that it is collecting! Instead, enter
the closing quote character (so mysql knows you've finished the
string), then type \c:
mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
'> '\c
mysql>
The prompt changes back to mysql>, indicating that mysql
is ready for a new command.
The `> prompt is similar to the '> and "> prompts,
but indicates that you have begun but not completed a backtick-quoted
identifier.
It's important to know what the '>, ">, and `> prompts signify,
because if you mistakenly enter an unterminated string, any further lines you
type appear to be ignored by mysql---including a line
containing QUIT. This can be quite confusing, especially if you
don't know that you need to supply the terminating quote before you can
cancel the current command.
Once you know how to enter commands, it's time to access a database.
Suppose that you have several pets in your home (your menagerie) and you'd like to keep track of various types of information about them. You can do so by creating tables to hold your data and loading them with the desired information. Then you can answer different sorts of questions about your animals by retrieving data from the tables. This section shows you how to:
The menagerie database is simple (deliberately), but it is not difficult
to think of real-world situations in which a similar type of database might
be used. For example, a database like this could be used by a farmer to keep
track of livestock, or by a veterinarian to keep track of patient records.
A menagerie distribution containing some of the queries and sample data used
in the following sections can be obtained from the MySQL Web site.
It's available in either compressed tar format
(http://www.mysql.com/Downloads/Contrib/Examples/menagerie.tar.gz)
or Zip format
(http://www.mysql.com/Downloads/Contrib/Examples/menagerie.zip).
Use the SHOW statement to find out what databases currently exist
on the server:
mysql> SHOW DATABASES; +----------+ | Database | +----------+ | mysql | | test | | tmp | +----------+
The list of databases is probably different on your machine, but the
mysql and test databases are likely to be among them. The
mysql database is required because it describes user access
privileges. The test database is often provided as a workspace for
users to try things out.
Note that you may not see all databases if you don't have the
SHOW DATABASES privilege. See section 13.5.1.3 GRANT and REVOKE Syntax.
If the test database exists, try to access it:
mysql> USE test Database changed
Note that USE, like QUIT, does not require a semicolon. (You
can terminate such statements with a semicolon if you like; it does no harm.)
The USE statement is special in another way, too: it must be given on
a single line.
You can use the test database (if you have access to it) for the
examples that follow, but anything you create in that database can be
removed by anyone else with access to it. For this reason, you should
probably ask your MySQL administrator for permission to use a
database of your own. Suppose that you want to call yours menagerie. The
administrator needs to execute a command like this:
mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';
where your_mysql_name is the MySQL username assigned to
you and your_client_host is the host from which you connect to the
server.
If the administrator creates your database for you when setting up your permissions, you can begin using it. Otherwise, you need to create it yourself:
mysql> CREATE DATABASE menagerie;
Under Unix, database names are case sensitive (unlike SQL keywords), so you
must always refer to your database as menagerie, not as
Menagerie, MENAGERIE, or some other variant. This is also true
for table names. (Under Windows, this restriction does not apply, although
you must refer to databases and tables using the same lettercase throughout a
given query.)
Creating a database does not select it for use; you must do that explicitly.
To make menagerie the current database, use this command:
mysql> USE menagerie Database changed
Your database needs to be created only once, but you must select it for use
each time you begin a mysql session. You can do this by issuing a
USE statement as shown in the example. Alternatively, you can select the
database on the command line when you invoke mysql. Just specify its
name after any connection parameters that you might need to provide. For
example:
shell> mysql -h host -u user -p menagerie Enter password: ********
Note that menagerie is not your password on the command just shown.
If you want to supply your password on the command line after the -p
option, you must do so with no intervening space (for example, as
-pmypassword, not as -p mypassword). However, putting your
password on the command line is not recommended, because doing so exposes it
to snooping by other users logged in on your machine.
Creating the database is the easy part, but at this point it's empty, as
SHOW TABLES tells you:
mysql> SHOW TABLES; Empty set (0.00 sec)
The harder part is deciding what the structure of your database should be: what tables you need and what columns should be in each of them.
You'll want a table that contains a record for each of your pets. This can
be called the pet table, and it should contain, as a bare minimum,
each animal's name. Because the name by itself is not very interesting, the
table should contain other information. For example, if more than one person
in your family keeps pets, you might want to list each animal's owner. You
might also want to record some basic descriptive information such as species
and sex.
How about age? That might be of interest, but it's not a good thing to store in a database. Age changes as time passes, which means you'd have to update your records often. Instead, it's better to store a fixed value such as date of birth. Then, whenever you need age, you can calculate it as the difference between the current date and the birth date. MySQL provides functions for doing date arithmetic, so this is not difficult. Storing birth date rather than age has other advantages, too:
You can probably think of other types of information that would be useful in
the pet table, but the ones identified so far are sufficient:
name, owner, species, sex, birth, and death.
Use a CREATE TABLE statement to specify the layout of your table:
mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
-> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);
VARCHAR is a good choice for the name, owner, and
species columns because the column values vary in length. The
lengths of those columns need not all be the same, and need not be
20. You can pick any length from 1 to 255, whatever
seems most reasonable to you. (If you make a poor choice and it turns
out later that you need a longer field, MySQL provides an
ALTER TABLE statement.)
Several types of values can be chosen to represent sex in animal records,
such as 'm'
and 'f', or perhaps 'male' and 'female'. It's simplest
to use the single characters 'm' and 'f'.
The use of the DATE data type for the birth and death
columns is a fairly obvious choice.
Once you have created a table, SHOW TABLES should produce some
output:
mysql> SHOW TABLES; +---------------------+ | Tables in menagerie | +---------------------+ | pet | +---------------------+
To verify that your table was created the way you expected, use
a DESCRIBE statement:
mysql> DESCRIBE pet; +---------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+-------+ | name | varchar(20) | YES | | NULL | | | owner | varchar(20) | YES | | NULL | | | species | varchar(20) | YES | | NULL | | | sex | char(1) | YES | | NULL | | | birth | date | YES | | NULL | | | death | date | YES | | NULL | | +---------+-------------+------+-----+---------+-------+
You can use DESCRIBE any time, for example, if you forget the names of
the columns in your table or what types they have.
After creating your table, you need to populate it. The LOAD DATA and
INSERT statements are useful for this.
Suppose that your pet records can be described as shown here.
(Observe that MySQL expects dates in 'YYYY-MM-DD' format;
this may be different from what you are used to.)
| name | owner | species | sex | birth | death |
| Fluffy | Harold | cat | f | 1993-02-04 | |
| Claws | Gwen | cat | m | 1994-03-17 | |
| Buffy | Harold | dog | f | 1989-05-13 | |
| Fang | Benny | dog | m | 1990-08-27 | |
| Bowser | Diane | dog | m | 1979-08-31 | 1995-07-29 |
| Chirpy | Gwen | bird | f | 1998-09-11 | |
| Whistler | Gwen | bird | 1997-12-09 | ||
| Slim | Benny | snake | m | 1996-04-29 |
Because you are beginning with an empty table, an easy way to populate it is to create a text file containing a row for each of your animals, then load the contents of the file into the table with a single statement.
You could create a text file `pet.txt' containing one record per line,
with values separated by tabs, and given in the order in which the columns
were listed in the CREATE TABLE statement. For missing values (such
as unknown sexes or death dates for animals that are still living), you can
use NULL values. To represent these in your text file, use
\N (backslash, capital-N). For example, the record for Whistler the
bird would look like
this (where the whitespace between values is a single tab character):
| name | owner | species | sex | birth | death |
Whistler | Gwen | bird | \N | 1997-12-09 | \N
|
To load the text file `pet.txt' into the pet table, use this
command:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;
Note that if you created the file on Windows with an editor that uses
\r\n as a line terminator, you should use:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet
-> LINES TERMINATED BY '\r\n';
You can specify the column value separator and end of line marker explicitly
in the LOAD DATA statement if you wish, but the defaults are tab and
linefeed. These are sufficient for the statement to read the file
`pet.txt' properly.
If the statement fails, it is likely that your MySQL installation does not
have local file capability enabled by default. See
section 5.4.4 Security Issues with LOAD DATA LOCAL for information on how to
change this.
When you want to add new records one at a time, the INSERT statement
is useful. In its simplest form, you supply values for each column, in the
order in which the columns were listed in the CREATE TABLE statement.
Suppose that Diane gets a new hamster named Puffball. You could add a new record
using an INSERT statement like this:
mysql> INSERT INTO pet
-> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);
Note that string and date values are specified as quoted strings here. Also,
with INSERT, you can insert NULL directly to represent a
missing value. You do not use \N like you do with LOAD DATA.
From this example, you should be able to see that there would be a lot more
typing involved to load
your records initially using several INSERT statements rather
than a single LOAD DATA statement.
The SELECT statement is used to pull information from a table.
The general form of the statement is:
SELECT what_to_select FROM which_table WHERE conditions_to_satisfy;
what_to_select indicates what you want to see. This can be a list of
columns, or * to indicate ``all columns.'' which_table
indicates the table from which you want to retrieve data. The WHERE
clause is optional. If it's present, conditions_to_satisfy specifies
conditions that rows must satisfy to qualify for retrieval.
The simplest form of SELECT retrieves everything from a table:
mysql> SELECT * FROM pet; +----------+--------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +----------+--------+---------+------+------------+------------+ | Fluffy | Harold | cat | f | 1993-02-04 | NULL | | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | | Fang | Benny | dog | m | 1990-08-27 | NULL | | Bowser | Diane | dog | m | 1979-08-31 | 1995-07-29 | | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | | Slim | Benny | snake | m | 1996-04-29 | NULL | | Puffball | Diane | hamster | f | 1999-03-30 | NULL | +----------+--------+---------+------+------------+------------+
This form of SELECT is useful if you want to review your entire table,
for example, after you've just loaded it with your initial dataset. For
example, you may happen to think that the birth date for Bowser doesn't seem
quite right. Consulting your original pedigree
papers, you find that the correct birth year should be 1989, not 1979.
There are least a couple of ways to fix this:
DELETE and LOAD DATA:
mysql> DELETE FROM pet; mysql> LOAD DATA LOCAL INFILE 'pet.txt' INTO TABLE pet;However, if you do this, you must also re-enter the record for Puffball.
UPDATE statement:
mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';The
UPDATE changes only the record in question and does not require you
to reload the table.
As shown in the preceding section, it is easy to retrieve an entire table.
Just omit the WHERE clause from the SELECT statement.
But typically you don't want
to see the entire table, particularly when it becomes large. Instead,
you're usually more interested in answering a particular question, in which
case you specify some constraints on the information you want. Let's look at
some selection queries in terms of questions about your pets that they
answer.
You can select only particular rows from your table. For example, if you want to verify the change that you made to Bowser's birth date, select Bowser's record like this:
mysql> SELECT * FROM pet WHERE name = 'Bowser'; +--------+-------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +--------+-------+---------+------+------------+------------+ | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | +--------+-------+---------+------+------------+------------+
The output confirms that the year is correctly recorded as 1989, not 1979.
String comparisons normally are case-insensitive, so you can specify the
name as 'bowser', 'BOWSER', etc. The query result is
the same.
You can specify conditions on any column, not just name. For example,
if you want to know which animals were born after 1998, test the birth
column:
mysql> SELECT * FROM pet WHERE birth >= '1998-1-1'; +----------+-------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+-------+ | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Puffball | Diane | hamster | f | 1999-03-30 | NULL | +----------+-------+---------+------+------------+-------+
You can combine conditions, for example, to locate female dogs:
mysql> SELECT * FROM pet WHERE species = 'dog' AND sex = 'f'; +-------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +-------+--------+---------+------+------------+-------+ | Buffy | Harold | dog | f | 1989-05-13 | NULL | +-------+--------+---------+------+------------+-------+
The preceding query uses the AND logical operator. There is also an
OR operator:
mysql> SELECT * FROM pet WHERE species = 'snake' OR species = 'bird'; +----------+-------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+-------+ | Chirpy | Gwen | bird | f | 1998-09-11 | NULL | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | | Slim | Benny | snake | m | 1996-04-29 | NULL | +----------+-------+---------+------+------------+-------+
AND and OR may be intermixed, although AND has higher
precedence than OR. If you use both operators, it's a good idea
to use parentheses to indicate explicitly how conditions should be grouped:
mysql> SELECT * FROM pet WHERE (species = 'cat' AND sex = 'm')
-> OR (species = 'dog' AND sex = 'f');
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth | death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen | cat | m | 1994-03-17 | NULL |
| Buffy | Harold | dog | f | 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
If you don't want to see entire rows from your table, just name the columns
in which you're interested, separated by commas. For example, if you want to
know when your animals were born, select the name and birth
columns:
mysql> SELECT name, birth FROM pet; +----------+------------+ | name | birth | +----------+------------+ | Fluffy | 1993-02-04 | | Claws | 1994-03-17 | | Buffy | 1989-05-13 | | Fang | 1990-08-27 | | Bowser | 1989-08-31 | | Chirpy | 1998-09-11 | | Whistler | 1997-12-09 | | Slim | 1996-04-29 | | Puffball | 1999-03-30 | +----------+------------+
To find out who owns pets, use this query:
mysql> SELECT owner FROM pet; +--------+ | owner | +--------+ | Harold | | Gwen | | Harold | | Benny | | Diane | | Gwen | | Gwen | | Benny | | Diane | +--------+
However, notice that the query simply retrieves the owner field from
each record, and some of them appear more than once. To minimize the output,
retrieve each unique output record just once by adding the keyword
DISTINCT:
mysql> SELECT DISTINCT owner FROM pet; +--------+ | owner | +--------+ | Benny | | Diane | | Gwen | | Harold | +--------+
You can use a WHERE clause to combine row selection with column
selection. For example, to get birth dates for dogs and cats only,
use this query:
mysql> SELECT name, species, birth FROM pet
-> WHERE species = 'dog' OR species = 'cat';
+--------+---------+------------+
| name | species | birth |
+--------+---------+------------+
| Fluffy | cat | 1993-02-04 |
| Claws | cat | 1994-03-17 |
| Buffy | dog | 1989-05-13 |
| Fang | dog | 1990-08-27 |
| Bowser | dog | 1989-08-31 |
+--------+---------+------------+
You may have noticed in the preceding examples that the result rows are
displayed in no particular order. It's often easier to examine
query output when the rows are sorted in some meaningful way. To sort a
result, use an ORDER BY clause.
Here are animal birthdays, sorted by date:
mysql> SELECT name, birth FROM pet ORDER BY birth; +----------+------------+ | name | birth | +----------+------------+ | Buffy | 1989-05-13 | | Bowser | 1989-08-31 | | Fang | 1990-08-27 | | Fluffy | 1993-02-04 | | Claws | 1994-03-17 | | Slim | 1996-04-29 | | Whistler | 1997-12-09 | | Chirpy | 1998-09-11 | | Puffball | 1999-03-30 | +----------+------------+
On character type columns, sorting--like all other comparison
operations--is normally performed in a case-insensitive fashion.
This means that the order is undefined for columns that are identical
except for their case. You can force a case-sensitive sort for a column
by using the BINARY cast: ORDER BY BINARY col_name.
The default sort order is ascending, with smallest values first.
To sort in reverse (descending) order, add the DESC keyword to the
name of the column you are sorting by:
mysql> SELECT name, birth FROM pet ORDER BY birth DESC; +----------+------------+ | name | birth | +----------+------------+ | Puffball | 1999-03-30 | | Chirpy | 1998-09-11 | | Whistler | 1997-12-09 | | Slim | 1996-04-29 | | Claws | 1994-03-17 | | Fluffy | 1993-02-04 | | Fang | 1990-08-27 | | Bowser | 1989-08-31 | | Buffy | 1989-05-13 | +----------+------------+
You can sort on multiple columns, and you can sort columns in different directions. For example, to sort by type of animal in ascending order, then by birth date within animal type in descending order (youngest animals first), use the following query:
mysql> SELECT name, species, birth FROM pet
-> ORDER BY species, birth DESC;
+----------+---------+------------+
| name | species | birth |
+----------+---------+------------+
| Chirpy | bird | 1998-09-11 |
| Whistler | bird | 1997-12-09 |
| Claws | cat | 1994-03-17 |
| Fluffy | cat | 1993-02-04 |
| Fang | dog | 1990-08-27 |
| Bowser | dog | 1989-08-31 |
| Buffy | dog | 1989-05-13 |
| Puffball | hamster | 1999-03-30 |
| Slim | snake | 1996-04-29 |
+----------+---------+------------+
Note that the DESC keyword applies only to the column name immediately
preceding it (birth); it does not affect the species column sort
order.
MySQL provides several functions that you can use to perform calculations on dates, for example, to calculate ages or extract parts of dates.
To determine how many years old each of your pets is, compute the difference in the year part of the current date and the birth date, then subtract one if the current date occurs earlier in the calendar year than the birth date. The following query shows, for each pet, the birth date, the current date, and the age in years.
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet;
+----------+------------+------------+------+
| name | birth | CURDATE() | age |
+----------+------------+------------+------+
| Fluffy | 1993-02-04 | 2003-08-19 | 10 |
| Claws | 1994-03-17 | 2003-08-19 | 9 |
| Buffy | 1989-05-13 | 2003-08-19 | 14 |
| Fang | 1990-08-27 | 2003-08-19 | 12 |
| Bowser | 1989-08-31 | 2003-08-19 | 13 |
| Chirpy | 1998-09-11 | 2003-08-19 | 4 |
| Whistler | 1997-12-09 | 2003-08-19 | 5 |
| Slim | 1996-04-29 | 2003-08-19 | 7 |
| Puffball | 1999-03-30 | 2003-08-19 | 4 |
+----------+------------+------------+------+
Here, YEAR() pulls out the year part of a date and RIGHT()
pulls off the rightmost five characters that represent the MM-DD
(calendar year) part of the date. The part of the expression that
compares the MM-DD values evaluates to 1 or 0, which adjusts the
year difference down a year if CURDATE() occurs earlier in
the year than birth. The full expression is somewhat ungainly,
so an alias (age) is used to make the output column label more
meaningful.
The query works, but the result could be scanned more easily if the rows
were presented in some order. This can be done by adding an ORDER
BY name clause to sort the output by name:
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet ORDER BY name;
+----------+------------+------------+------+
| name | birth | CURDATE() | age |
+----------+------------+------------+------+
| Bowser | 1989-08-31 | 2003-08-19 | 13 |
| Buffy | 1989-05-13 | 2003-08-19 | 14 |
| Chirpy | 1998-09-11 | 2003-08-19 | 4 |
| Claws | 1994-03-17 | 2003-08-19 | 9 |
| Fang | 1990-08-27 | 2003-08-19 | 12 |
| Fluffy | 1993-02-04 | 2003-08-19 | 10 |
| Puffball | 1999-03-30 | 2003-08-19 | 4 |
| Slim | 1996-04-29 | 2003-08-19 | 7 |
| Whistler | 1997-12-09 | 2003-08-19 | 5 |
+----------+------------+------------+------+
To sort the output by age rather than name, just use a
different ORDER BY clause:
mysql> SELECT name, birth, CURDATE(),
-> (YEAR(CURDATE())-YEAR(birth))
-> - (RIGHT(CURDATE(),5)<RIGHT(birth,5))
-> AS age
-> FROM pet ORDER BY age;
+----------+------------+------------+------+
| name | birth | CURDATE() | age |
+----------+------------+------------+------+
| Chirpy | 1998-09-11 | 2003-08-19 | 4 |
| Puffball | 1999-03-30 | 2003-08-19 | 4 |
| Whistler | 1997-12-09 | 2003-08-19 | 5 |
| Slim | 1996-04-29 | 2003-08-19 | 7 |
| Claws | 1994-03-17 | 2003-08-19 | 9 |
| Fluffy | 1993-02-04 | 2003-08-19 | 10 |
| Fang | 1990-08-27 | 2003-08-19 | 12 |
| Bowser | 1989-08-31 | 2003-08-19 | 13 |
| Buffy | 1989-05-13 | 2003-08-19 | 14 |
+----------+------------+------------+------+
A similar query can be used to determine age at death for animals that have
died. You determine which animals these are by checking whether the
death value is NULL. Then, for those with non-NULL
values, compute the difference between the death and birth
values:
mysql> SELECT name, birth, death,
-> (YEAR(death)-YEAR(birth)) - (RIGHT(death,5)<RIGHT(birth,5))
-> AS age
-> FROM pet WHERE death IS NOT NULL ORDER BY age;
+--------+------------+------------+------+
| name | birth | death | age |
+--------+------------+------------+------+
| Bowser | 1989-08-31 | 1995-07-29 | 5 |
+--------+------------+------------+------+
The query uses death IS NOT NULL rather than death <> NULL
because NULL is a special value that cannot be compared using the usual
comparison operators. This is discussed later.
See section 3.3.4.6 Working with NULL Values.
What if you want to know which animals have birthdays next month? For this
type of calculation, year and day are irrelevant; you simply want to extract
the month part of the birth column. MySQL provides several
date-part extraction functions, such as YEAR(), MONTH(), and
DAYOFMONTH(). MONTH() is the appropriate function here. To
see how it works, run a simple query that displays the value of both
birth and MONTH(birth):
mysql> SELECT name, birth, MONTH(birth) FROM pet; +----------+------------+--------------+ | name | birth | MONTH(birth) | +----------+------------+--------------+ | Fluffy | 1993-02-04 | 2 | | Claws | 1994-03-17 | 3 | | Buffy | 1989-05-13 | 5 | | Fang | 1990-08-27 | 8 | | Bowser | 1989-08-31 | 8 | | Chirpy | 1998-09-11 | 9 | | Whistler | 1997-12-09 | 12 | | Slim | 1996-04-29 | 4 | | Puffball | 1999-03-30 | 3 | +----------+------------+--------------+
Finding animals with birthdays in the upcoming month is easy, too. Suppose
that the current month is April. Then the month value is 4 and you look
for animals born in May (month 5) like this:
mysql> SELECT name, birth FROM pet WHERE MONTH(birth) = 5; +-------+------------+ | name | birth | +-------+------------+ | Buffy | 1989-05-13 | +-------+------------+
There is a small complication if the current month is December.
You don't just add one to the month number (12) and look for animals
born in month 13, because there is no such month. Instead, you look for
animals born in January (month 1).
You can even write the query so that it works no matter what the current
month is. That way you don't have to use a particular month number
in the query. DATE_ADD() allows you to add a time interval to a
given date. If you add a month to the value of CURDATE(), then extract
the month part with MONTH(), the result produces the month in which to
look for birthdays:
mysql> SELECT name, birth FROM pet
-> WHERE MONTH(birth) = MONTH(DATE_ADD(CURDATE(),INTERVAL 1 MONTH));
A different way to accomplish the same task is to add 1 to get the
next month after the current one (after using the modulo function (MOD)
to wrap around the month value to 0 if it is currently
12):
mysql> SELECT name, birth FROM pet
-> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1;
Note that MONTH returns a number between 1 and 12. And
MOD(something,12) returns a number between 0 and 11. So the
addition has to be after the MOD(), otherwise we would go from
November (11) to January (1).
NULL Values
The NULL value can be surprising until you get used to it.
Conceptually, NULL means missing value or unknown value and it
is treated somewhat differently than other values. To test for NULL,
you cannot use the arithmetic comparison operators such as =, <,
or <>. To demonstrate this for yourself, try the following query:
mysql> SELECT 1 = NULL, 1 <> NULL, 1 < NULL, 1 > NULL; +----------+-----------+----------+----------+ | 1 = NULL | 1 <> NULL | 1 < NULL | 1 > NULL | +----------+-----------+----------+----------+ | NULL | NULL | NULL | NULL | +----------+-----------+----------+----------+
Clearly you get no meaningful results from these comparisons. Use
the IS NULL and IS NOT NULL operators instead:
mysql> SELECT 1 IS NULL, 1 IS NOT NULL; +-----------+---------------+ | 1 IS NULL | 1 IS NOT NULL | +-----------+---------------+ | 0 | 1 | +-----------+---------------+
Note that in MySQL, 0 or NULL means false and anything else means
true. The default truth value from a boolean operation is 1.
This special treatment of NULL is why, in the previous section, it
was necessary to determine which animals are no longer alive using
death IS NOT NULL instead of death <> NULL.
Two NULL values are regarded as equal in a GROUP BY.
When doing an ORDER BY, NULL values are presented first if you
do ORDER BY ... ASC and last if you do ORDER BY ... DESC.
Note that MySQL 4.0.2 to 4.0.10 incorrectly always sorts NULL values
first regardless of the sort direction.
MySQL provides standard SQL pattern matching as well as a form of
pattern matching based on extended regular expressions similar to those used
by Unix utilities such as vi, grep, and sed.
SQL pattern matching allows you to use `_' to match any single
character and `%' to match an arbitrary number of characters (including
zero characters). In MySQL, SQL patterns are case-insensitive by
default. Some examples are shown here. Note that you do not use =
or <> when you use SQL patterns; use the LIKE or NOT
LIKE comparison operators instead.
To find names beginning with `b':
mysql> SELECT * FROM pet WHERE name LIKE 'b%'; +--------+--------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +--------+--------+---------+------+------------+------------+ | Buffy | Harold | dog | f | 1989-05-13 | NULL | | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | +--------+--------+---------+------+------------+------------+
To find names ending with `fy':
mysql> SELECT * FROM pet WHERE name LIKE '%fy'; +--------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +--------+--------+---------+------+------------+-------+ | Fluffy | Harold | cat | f | 1993-02-04 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | +--------+--------+---------+------+------------+-------+
To find names containing a `w':
mysql> SELECT * FROM pet WHERE name LIKE '%w%'; +----------+-------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+------------+ | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | +----------+-------+---------+------+------------+------------+
To find names containing exactly five characters, use five instances of the `_' pattern character:
mysql> SELECT * FROM pet WHERE name LIKE '_____'; +-------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +-------+--------+---------+------+------------+-------+ | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | +-------+--------+---------+------+------------+-------+
The other type of pattern matching provided by MySQL uses extended
regular expressions. When you test for a match for this type of pattern, use
the REGEXP and NOT REGEXP operators (or RLIKE and
NOT RLIKE, which are synonyms).
Some characteristics of extended regular expressions are:
REGEXP pattern match succeed if
the pattern matches anywhere in the value being tested.
(This differs from a LIKE pattern match, which succeeds only if the
pattern matches the entire value.)
To demonstrate how extended regular expressions work, the LIKE queries
shown previously are rewritten here to use REGEXP.
To find names beginning with `b', use `^' to match the beginning of the name:
mysql> SELECT * FROM pet WHERE name REGEXP '^b'; +--------+--------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +--------+--------+---------+------+------------+------------+ | Buffy | Harold | dog | f | 1989-05-13 | NULL | | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | +--------+--------+---------+------+------------+------------+
Prior to MySQL Version 3.23.4, REGEXP is case sensitive,
and the previous query will return no rows. In this case, to match either
lowercase or uppercase `b', use this query instead:
mysql> SELECT * FROM pet WHERE name REGEXP '^[bB]';
From MySQL 3.23.4 on, if you really want to force a REGEXP comparison to
be case sensitive, use the BINARY keyword to make one of the
strings a binary string. This query matches only lowercase `b'
at the beginning of a name:
mysql> SELECT * FROM pet WHERE name REGEXP BINARY '^b';
To find names ending with `fy', use `$' to match the end of the name:
mysql> SELECT * FROM pet WHERE name REGEXP 'fy$'; +--------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +--------+--------+---------+------+------------+-------+ | Fluffy | Harold | cat | f | 1993-02-04 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | +--------+--------+---------+------+------------+-------+
To find names containing a `w', use this query:
mysql> SELECT * FROM pet WHERE name REGEXP 'w'; +----------+-------+---------+------+------------+------------+ | name | owner | species | sex | birth | death | +----------+-------+---------+------+------------+------------+ | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Bowser | Diane | dog | m | 1989-08-31 | 1995-07-29 | | Whistler | Gwen | bird | NULL | 1997-12-09 | NULL | +----------+-------+---------+------+------------+------------+
Because a regular expression pattern matches if it occurs anywhere in the value, it is not necessary in the previous query to put a wildcard on either side of the pattern to get it to match the entire value like it would be if you used an SQL pattern.
To find names containing exactly five characters, use `^' and `$' to match the beginning and end of the name, and five instances of `.' in between:
mysql> SELECT * FROM pet WHERE name REGEXP '^.....$'; +-------+--------+---------+------+------------+-------+ | name | owner | species | sex | birth | death | +-------+--------+---------+------+------------+-------+ | Claws | Gwen | cat | m | 1994-03-17 | NULL | | Buffy | Harold | dog | f | 1989-05-13 | NULL | +-------+--------+---------+------+------------+-------+
You could also write the previous query using the `{n}'
``repeat-n-times'' operator:
mysql> SELECT * FROM pet WHERE name REGEXP '^.{5}$';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth | death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen | cat | m | 1994-03-17 | NULL |
| Buffy | Harold | dog | f | 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
Databases are often used to answer the question, ``How often does a certain type of data occur in a table?'' For example, you might want to know how many pets you have, or how many pets each owner has, or you might want to perform various kinds of census operations on your animals.
Counting the total number of animals you have is the same question as ``How
many rows are in the pet table?'' because there is one record per pet.
COUNT(*) counts the number of rows, so
the query to count your animals looks like this:
mysql> SELECT COUNT(*) FROM pet; +----------+ | COUNT(*) | +----------+ | 9 | +----------+
Earlier, you retrieved the names of the people who owned pets. You can
use COUNT() if you want to find out how many pets each owner has:
mysql> SELECT owner, COUNT(*) FROM pet GROUP BY owner; +--------+----------+ | owner | COUNT(*) | +--------+----------+ | Benny | 2 | | Diane | 2 | | Gwen | 3 | | Harold | 2 | +--------+----------+
Note the use of GROUP BY to group together all records for each
owner. Without it, all you get is an error message:
mysql> SELECT owner, COUNT(*) FROM pet; ERROR 1140: Mixing of GROUP columns (MIN(),MAX(),COUNT()...) with no GROUP columns is illegal if there is no GROUP BY clause
COUNT() and GROUP BY are useful for characterizing your
data in various ways. The following examples show different ways to
perform animal census operations.
Number of animals per species:
mysql> SELECT species, COUNT(*) FROM pet GROUP BY species; +---------+----------+ | species | COUNT(*) | +---------+----------+ | bird | 2 | | cat | 2 | | dog | 3 | | hamster | 1 | | snake | 1 | +---------+----------+
Number of animals per sex:
mysql> SELECT sex, COUNT(*) FROM pet GROUP BY sex; +------+----------+ | sex | COUNT(*) | +------+----------+ | NULL | 1 | | f | 4 | | m | 4 | +------+----------+
(In this output, NULL indicates that the sex is unknown.)
Number of animals per combination of species and sex:
mysql> SELECT species, sex, COUNT(*) FROM pet GROUP BY species, sex; +---------+------+----------+ | species | sex | COUNT(*) | +---------+------+----------+ | bird | NULL | 1 | | bird | f | 1 | | cat | f | 1 | | cat | m | 1 | | dog | f | 1 | | dog | m | 2 | | hamster | f | 1 | | snake | m | 1 | +---------+------+----------+
You need not retrieve an entire table when you use COUNT(). For
example, the previous query, when performed just on dogs and cats, looks like
this:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE species = 'dog' OR species = 'cat'
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| cat | f | 1 |
| cat | m | 1 |
| dog | f | 1 |
| dog | m | 2 |
+---------+------+----------+
Or, if you wanted the number of animals per sex only for known-sex animals:
mysql> SELECT species, sex, COUNT(*) FROM pet
-> WHERE sex IS NOT NULL
-> GROUP BY species, sex;
+---------+------+----------+
| species | sex | COUNT(*) |
+---------+------+----------+
| bird | f | 1 |
| cat | f | 1 |
| cat | m | 1 |
| dog | f | 1 |
| dog | m | 2 |
| hamster | f | 1 |
| snake | m | 1 |
+---------+------+----------+
The pet table keeps track of which pets you have. If you want to
record other information about them, such as events in their lives like
visits to the vet or when litters are born, you need another table. What
should this table look like? It needs:
Given these considerations, the CREATE TABLE statement for the
event table might look like this:
mysql> CREATE TABLE event (name VARCHAR(20), date DATE,
-> type VARCHAR(15), remark VARCHAR(255));
As with the pet table, it's easiest to load the initial records
by creating a tab-delimited text file containing the information:
| name | date | type | remark |
| Fluffy | 1995-05-15 | litter | 4 kittens, 3 female, 1 male |
| Buffy | 1993-06-23 | litter | 5 puppies, 2 female, 3 male |
| Buffy | 1994-06-19 | litter | 3 puppies, 3 female |
| Chirpy | 1999-03-21 | vet | needed beak straightened |
| Slim | 1997-08-03 | vet | broken rib |
| Bowser | 1991-10-12 | kennel | |
| Fang | 1991-10-12 | kennel | |
| Fang | 1998-08-28 | birthday | Gave him a new chew toy |
| Claws | 1998-03-17 | birthday | Gave him a new flea collar |
| Whistler | 1998-12-09 | birthday | First birthday |
Load the records like this:
mysql> LOAD DATA LOCAL INFILE 'event.txt' INTO TABLE event;
Based on what you've learned from the queries you've run on the pet
table, you should be able to perform retrievals on the records in the
event table; the principles are the same. But when is the
event table by itself insufficient to answer questions you might ask?
Suppose that you want to find out the ages at which each pet had its
litters. We saw earlier how to calculate ages from two dates.
The litter date of the mother is in the
event table, but to calculate her age on that date you need her
birth date, which is stored in the pet table.
This means the query requires both tables:
mysql> SELECT pet.name,
-> (YEAR(date)-YEAR(birth)) - (RIGHT(date,5)<RIGHT(birth,5)) AS age,
-> remark
-> FROM pet, event
-> WHERE pet.name = event.name AND type = 'litter';
+--------+------+-----------------------------+
| name | age | remark |
+--------+------+-----------------------------+
| Fluffy | 2 | 4 kittens, 3 female, 1 male |
| Buffy | 4 | 5 puppies, 2 female, 3 male |
| Buffy | 5 | 3 puppies, 3 female |
+--------+------+-----------------------------+
There are several things to note about this query:
FROM clause lists two tables because the query needs to pull
information from both of them.
name column. The query uses
WHERE clause to match up records in the two tables based on the
name values.
name column occurs in both tables, you must be specific
about which table you mean when referring to the column. This is done
by prepending the table name to the column name.
You need not have two different tables to perform a join. Sometimes it is
useful to join a table to itself, if you want to compare records in a table
to other records in that same table. For example, to find breeding pairs
among your pets, you can join the pet table with itself to produce
candidate pairs of males and females of like species:
mysql> SELECT p1.name, p1.sex, p2.name, p2.sex, p1.species
-> FROM pet AS p1, pet AS p2
-> WHERE p1.species = p2.species AND p1.sex = 'f' AND p2.sex = 'm';
+--------+------+--------+------+---------+
| name | sex | name | sex | species |
+--------+------+--------+------+---------+
| Fluffy | f | Claws | m | cat |
| Buffy | f | Fang | m | dog |
| Buffy | f | Bowser | m | dog |
+--------+------+--------+------+---------+
In this query, we specify aliases for the table name in order to refer to the columns and keep straight which instance of the table each column reference is associated with.
What if you forget the name of a database or table, or what the structure of a given table is (for example, what its columns are called)? MySQL addresses this problem through several statements that provide information about the databases and tables it supports.
You have previously seen SHOW DATABASES, which lists the databases
managed by the server. To find out which database is currently selected,
use the DATABASE() function:
mysql> SELECT DATABASE(); +------------+ | DATABASE() | +------------+ | menagerie | +------------+
If you haven't selected any database yet, the result is NULL
(or the empty string before MySQL 4.1.1).
To find out what tables the current database contains (for example, when you're not sure about the name of a table), use this command:
mysql> SHOW TABLES; +---------------------+ | Tables in menagerie | +---------------------+ | event | | pet | +---------------------+
If you want to find out about the structure of a table, the DESCRIBE
command is useful; it displays information about each of a table's columns:
mysql> DESCRIBE pet; +---------+-------------+------+-----+---------+-------+ | Field | Type | Null | Key | Default | Extra | +---------+-------------+------+-----+---------+-------+ | name | varchar(20) | YES | | NULL | | | owner | varchar(20) | YES | | NULL | | | species | varchar(20) | YES | | NULL | | | sex | char(1) | YES | | NULL | | | birth | date | YES | | NULL | | | death | date | YES | | NULL | | +---------+-------------+------+-----+---------+-------+
Field indicates the column name, Type is the data type for
the column, NULL indicates whether the column can contain
NULL values, Key indicates whether the column is
indexed, and Default specifies the column's default value.
If you have indexes on a table,
SHOW INDEX FROM tbl_name produces information about them.
mysql in Batch Mode
In the previous sections, you used mysql interactively to enter
queries and view the results. You can also run mysql in batch
mode. To do this, put the commands you want to run in a file, then
tell mysql to read its input from the file:
shell> mysql < batch-file
If you are running mysql under Windows and have some special
characters in the file that cause problems, you can do this:
C:\> mysql -e "source batch-file"
If you need to specify connection parameters on the command line, the command might look like this:
shell> mysql -h host -u user -p < batch-file Enter password: ********
When you use mysql this way, you are creating a script file, then
executing the script.
If you want the script to continue even if some of the statements in it
produce errors, you should
use the --force command-line option.
Why use a script? Here are a few reasons:
mysql to execute it again.
shell> mysql < batch-file | more
shell> mysql < batch-file > mysql.out
cron job. In this case, you must use batch mode.
The default output format is different (more concise) when you run
mysql in batch mode than when you use it interactively. For
example, the output of SELECT DISTINCT species FROM pet looks like
this when mysql is run interactively:
+---------+ | species | +---------+ | bird | | cat | | dog | | hamster | | snake | +---------+
In batch mode, the output looks like this instead:
species bird cat dog hamster snake
If you want to get the interactive output format in batch mode, use
mysql -t. To echo to the output the commands that are executed, use
mysql -vvv.
You can also use scripts from the mysql prompt by
using the source or \. command:
mysql> source filename; mysql> \. filename
Here are examples of how to solve some common problems with MySQL.
Some of the examples use the table shop to hold the price of each
article (item number) for certain traders (dealers). Supposing that each
trader has a single fixed price per article, then (article,
dealer) is a primary key for the records.
Start the command-line tool mysql and select a database:
shell> mysql your-database-name
(In most MySQL installations, you can use the database name test).
You can create and populate the example table with these statements:
mysql> CREATE TABLE shop (
-> article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
-> dealer CHAR(20) DEFAULT '' NOT NULL,
-> price DOUBLE(16,2) DEFAULT '0.00' NOT NULL,
-> PRIMARY KEY(article, dealer));
mysql> INSERT INTO shop VALUES
-> (1,'A',3.45),(1,'B',3.99),(2,'A',10.99),(3,'B',1.45),
-> (3,'C',1.69),(3,'D',1.25),(4,'D',19.95);
After issuing the statements, the table should have the following contents:
mysql> SELECT * FROM shop; +---------+--------+-------+ | article | dealer | price | +---------+--------+-------+ | 0001 | A | 3.45 | | 0001 | B | 3.99 | | 0002 | A | 10.99 | | 0003 | B | 1.45 | | 0003 | C | 1.69 | | 0003 | D | 1.25 | | 0004 | D | 19.95 | +---------+--------+-------+
``What's the highest item number?''
SELECT MAX(article) AS article FROM shop; +---------+ | article | +---------+ | 4 | +---------+
``Find number, dealer, and price of the most expensive article.''
In standard SQL (and as of MySQL 4.1), this is easily done with a subquery:
SELECT article, dealer, price FROM shop WHERE price=(SELECT MAX(price) FROM shop);
In MySQL versions prior to 4.1, just do it in two steps:
SELECT statement.
mysql> SELECT MAX(price) FROM shop; +------------+ | MAX(price) | +------------+ | 19.95 | +------------+
mysql> SELECT article, dealer, price
-> FROM shop
-> WHERE price=19.95;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
| 0004 | D | 19.95 |
+---------+--------+-------+
Another solution is to sort all rows descending by price and only
get the first row using the MySQL-specific LIMIT clause:
SELECT article, dealer, price FROM shop ORDER BY price DESC LIMIT 1;
Note: If there were several most expensive articles, each with a
price of 19.95, the LIMIT solution would show only one of them!
``What's the highest price per article?''
SELECT article, MAX(price) AS price FROM shop GROUP BY article +---------+-------+ | article | price | +---------+-------+ | 0001 | 3.99 | | 0002 | 10.99 | | 0003 | 1.69 | | 0004 | 19.95 | +---------+-------+
``For each article, find the dealer or dealers with the most expensive price.''
In standard SQL (and as of MySQL 4.1), the problem can be solved with a subquery like this:
SELECT article, dealer, price
FROM shop s1
WHERE price=(SELECT MAX(s2.price)
FROM shop s2
WHERE s1.article = s2.article);
In MySQL versions prior to 4.1, it's best do it in several steps:
This can easily be done with a temporary table and a join:
CREATE TEMPORARY TABLE tmp (
article INT(4) UNSIGNED ZEROFILL DEFAULT '0000' NOT NULL,
price DOUBLE(16,2) DEFAULT '0.00' NOT NULL);
LOCK TABLES shop READ;
INSERT INTO tmp SELECT article, MAX(price) FROM shop GROUP BY article;
SELECT shop.article, dealer, shop.price FROM shop, tmp
WHERE shop.article=tmp.article AND shop.price=tmp.price;
UNLOCK TABLES;
DROP TABLE tmp;
If you don't use a TEMPORARY table, you must also lock the tmp
table.
``Can it be done with a single query?''
Yes, but only by using a quite inefficient trick called the ``MAX-CONCAT trick'':
SELECT article,
SUBSTRING( MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 7) AS dealer,
0.00+LEFT( MAX( CONCAT(LPAD(price,6,'0'),dealer) ), 6) AS price
FROM shop
GROUP BY article;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
| 0001 | B | 3.99 |
| 0002 | A | 10.99 |
| 0003 | C | 1.69 |
| 0004 | D | 19.95 |
+---------+--------+-------+
The last example can be made a bit more efficient by doing the splitting of the concatenated column in the client.
You can use MySQL user variables to remember results without having to store them in temporary variables in the client. See section 9.3 User Variables.
For example, to find the articles with the highest and lowest price you can do this:
mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop; mysql> SELECT * FROM shop WHERE price=@min_price OR price=@max_price; +---------+--------+-------+ | article | dealer | price | +---------+--------+-------+ | 0003 | D | 1.25 | | 0004 | D | 19.95 | +---------+--------+-------+
In MySQL 3.23.44 and up, InnoDB tables support checking of
foreign key constraints. See section 15 The InnoDB Storage Engine.
See also section 1.5.5.5 Foreign Keys.
You don't actually need foreign keys to join two tables.
For table types other than InnoDB,
the only things MySQL currently doesn't do are 1)
CHECK to make sure that the keys you use
really exist in the table or tables you're referencing and 2)
automatically delete rows from a table with a foreign key
definition. Using your keys to join tables works just fine:
CREATE TABLE person (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
name CHAR(60) NOT NULL,
PRIMARY KEY (id)
);
CREATE TABLE shirt (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
PRIMARY KEY (id)
);
INSERT INTO person VALUES (NULL, 'Antonio Paz');
SELECT @last := LAST_INSERT_ID();
INSERT INTO shirt VALUES
(NULL, 'polo', 'blue', @last),
(NULL, 'dress', 'white', @last),
(NULL, 't-shirt', 'blue', @last);
INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');
SELECT @last := LAST_INSERT_ID();
INSERT INTO shirt VALUES
(NULL, 'dress', 'orange', @last),
(NULL, 'polo', 'red', @last),
(NULL, 'dress', 'blue', @last),
(NULL, 't-shirt', 'white', @last);
SELECT * FROM person;
+----+---------------------+
| id | name |
+----+---------------------+
| 1 | Antonio Paz |
| 2 | Lilliana Angelovska |
+----+---------------------+
SELECT * FROM shirt;
+----+---------+--------+-------+
| id | style | color | owner |
+----+---------+--------+-------+
| 1 | polo | blue | 1 |
| 2 | dress | white | 1 |
| 3 | t-shirt | blue | 1 |
| 4 | dress | orange | 2 |
| 5 | polo | red | 2 |
| 6 | dress | blue | 2 |
| 7 | t-shirt | white | 2 |
+----+---------+--------+-------+
SELECT s.* FROM person p, shirt s
WHERE p.name LIKE 'Lilliana%'
AND s.owner = p.id
AND s.color <> 'white';
+----+-------+--------+-------+
| id | style | color | owner |
+----+-------+--------+-------+
| 4 | dress | orange | 2 |
| 5 | polo | red | 2 |
| 6 | dress | blue | 2 |
+----+-------+--------+-------+
An OR using a single key is well optimized, as is the handling
of AND.
The one tricky case is that of searching on two different keys
combined with OR:
SELECT field1_index, field2_index FROM test_table WHERE field1_index = '1' OR field2_index = '1'
This case is optimized from MySQL 5.0.0. See section 7.2.6 Index Merge Optimization.
In MySQL 4.0 and up, you can also solve the problem efficiently by
using a UNION that combines the output of two separate
SELECT statements.
See section 13.1.7.2 UNION Syntax.
Each SELECT searches only one key and can be optimized:
SELECT field1_index, field2_index
FROM test_table WHERE field1_index = '1'
UNION
SELECT field1_index, field2_index
FROM test_table WHERE field2_index = '1';
Prior to MySQL 4.0, you can achieve the same effect by using a
TEMPORARY table and separate SELECT statements.
This type of optimization is also very good if
you are using very complicated queries where the SQL server does the
optimizations in the wrong order.
CREATE TEMPORARY TABLE tmp
SELECT field1_index, field2_index
FROM test_table WHERE field1_index = '1';
INSERT INTO tmp
SELECT field1_index, field2_index
FROM test_table WHERE field2_index = '1';
SELECT * from tmp;
DROP TABLE tmp;
This method of solving the problem is in effect a UNION of two queries.
The following example shows how you can use the bit group functions to calculate the number of days per month a user has visited a Web page.
CREATE TABLE t1 (year YEAR(4), month INT(2) UNSIGNED ZEROFILL,
day INT(2) UNSIGNED ZEROFILL);
INSERT INTO t1 VALUES(2000,1,1),(2000,1,20),(2000,1,30),(2000,2,2),
(2000,2,23),(2000,2,23);
The example table contains year-month-day values representing visits by users to the page. To determine how many different days in each month these visits occur, use this query:
SELECT year,month,BIT_COUNT(BIT_OR(1<<day)) AS days FROM t1
GROUP BY year,month;
Which returns:
+------+-------+------+ | year | month | days | +------+-------+------+ | 2000 | 01 | 3 | | 2000 | 02 | 2 | +------+-------+------+
The query calculates how many different days appear in the table for each year/month combination, with automatic removal of duplicate entries.
AUTO_INCREMENT
The AUTO_INCREMENT attribute can be used to generate a unique
identity for new rows:
CREATE TABLE animals (
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (id)
);
INSERT INTO animals (name) VALUES ('dog'),('cat'),('penguin'),
('lax'),('whale'),('ostrich');
SELECT * FROM animals;
Which returns:
+----+---------+ | id | name | +----+---------+ | 1 | dog | | 2 | cat | | 3 | penguin | | 4 | lax | | 5 | whale | | 6 | ostrich | +----+---------+
You can retrieve the most recent AUTO_INCREMENT value with the
LAST_INSERT_ID() SQL function or the mysql_insert_id() C API
function. These functions are connection-specific, so their return value
is not affected by another connection also doing inserts.
Note: For a multiple-row insert,
LAST_INSERT_ID()/mysql_insert_id() actually returns the
AUTO_INCREMENT key from the first of the inserted rows.
This allows multiple-row inserts to be reproduced correctly on other servers
in a replication setup.
For MyISAM and BDB tables you can specify AUTO_INCREMENT
on a secondary column in a multiple-column index. In this case, the generated
value for the AUTO_INCREMENT column is calculated as
MAX(auto_increment_column)+1 WHERE prefix=given-prefix. This is
useful when you want to put data into ordered groups.
CREATE TABLE animals (
grp ENUM('fish','mammal','bird') NOT NULL,
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (grp,id)
);
INSERT INTO animals (grp,name) VALUES('mammal','dog'),('mammal','cat'),
('bird','penguin'),('fish','lax'),('mammal','whale'),
('bird','ostrich');
SELECT * FROM animals ORDER BY grp,id;
Which returns:
+--------+----+---------+ | grp | id | name | +--------+----+---------+ | fish | 1 | lax | | mammal | 1 | dog | | mammal | 2 | cat | | mammal | 3 | whale | | bird | 1 | penguin | | bird | 2 | ostrich | +--------+----+---------+
Note that in this case (when the AUTO_INCREMENT column is part of a
multiple-column index), AUTO_INCREMENT values are reused if you
delete the row with the biggest AUTO_INCREMENT value in any group.
This happens even for MyISAM tables, for which AUTO_INCREMENT
values normally are not reused.)
If the AUTO_INCREMENT column is part of multiple indexes, MySQL will
generate sequence values using the index that begins with the
AUTO_INCREMENT column, if there is one. For example, if the
animals table contained indexes PRIMARY KEY (grp, id) and
INDEX (id), MySQL would ignore the PRIMARY KEY for generating
sequence values. As a result, the table would contain a single sequence, not
a sequence per grp value.
At Analytikerna and Lentus, we have been doing the systems and field work for a big research project. This project is a collaboration between the Institute of Environmental Medicine at Karolinska Institutet Stockholm and the Section on Clinical Research in Aging and Psychology at the University of Southern California.
The project involves a screening part where all twins in Sweden older than 65 years are interviewed by telephone. Twins who meet certain criteria are passed on to the next stage. In this latter stage, twins who want to participate are visited by a doctor/nurse team. Some of the examinations include physical and neuropsychological examination, laboratory testing, neuroimaging, psychological status assessment, and family history collection. In addition, data are collected on medical and environmental risk factors.
More information about Twin studies can be found at: http://www.mep.ki.se/twinreg/index_en.html
The latter part of the project is administered with a Web interface written using Perl and MySQL.
Each night all data from the interviews is moved into a MySQL database.
The following query is used to determine who goes into the second part of the project:
SELECT
CONCAT(p1.id, p1.tvab) + 0 AS tvid,
CONCAT(p1.christian_name, ' ', p1.surname) AS Name,
p1.postal_code AS Code,
p1.city AS City,
pg.abrev AS Area,
IF(td.participation = 'Aborted', 'A', ' ') AS A,
p1.dead AS dead1,
l.event AS event1,
td.suspect AS tsuspect1,
id.suspect AS isuspect1,
td.severe AS tsevere1,
id.severe AS isevere1,
p2.dead AS dead2,
l2.event AS event2,
h2.nurse AS nurse2,
h2.doctor AS doctor2,
td2.suspect AS tsuspect2,
id2.suspect AS isuspect2,
td2.severe AS tsevere2,
id2.severe AS isevere2,
l.finish_date
FROM
twin_project AS tp
/* For Twin 1 */
LEFT JOIN twin_data AS td ON tp.id = td.id
AND tp.tvab = td.tvab
LEFT JOIN informant_data AS id ON tp.id = id.id
AND tp.tvab = id.tvab
LEFT JOIN harmony AS h ON tp.id = h.id
AND tp.tvab = h.tvab
LEFT JOIN lentus AS l ON tp.id = l.id
AND tp.tvab = l.tvab
/* For Twin 2 */
LEFT JOIN twin_data AS td2 ON p2.id = td2.id
AND p2.tvab = td2.tvab
LEFT JOIN informant_data AS id2 ON p2.id = id2.id
AND p2.tvab = id2.tvab
LEFT JOIN harmony AS h2 ON p2.id = h2.id
AND p2.tvab = h2.tvab
LEFT JOIN lentus AS l2 ON p2.id = l2.id
AND p2.tvab = l2.tvab,
person_data AS p1,
person_data AS p2,
postal_groups AS pg
WHERE
/* p1 gets main twin and p2 gets his/her twin. */
/* ptvab is a field inverted from tvab */
p1.id = tp.id AND p1.tvab = tp.tvab AND
p2.id = p1.id AND p2.ptvab = p1.tvab AND
/* Just the screening survey */
tp.survey_no = 5 AND
/* Skip if partner died before 65 but allow emigration (dead=9) */
(p2.dead = 0 OR p2.dead = 9 OR
(p2.dead = 1 AND
(p2.death_date = 0 OR
(((TO_DAYS(p2.death_date) - TO_DAYS(p2.birthday)) / 365)
>= 65))))
AND
(
/* Twin is suspect */
(td.future_contact = 'Yes' AND td.suspect = 2) OR
/* Twin is suspect - Informant is Blessed */
(td.future_contact = 'Yes' AND td.suspect = 1
AND id.suspect = 1) OR
/* No twin - Informant is Blessed */
(ISNULL(td.suspect) AND id.suspect = 1
AND id.future_contact = 'Yes') OR
/* Twin broken off - Informant is Blessed */
(td.participation = 'Aborted'
AND id.suspect = 1 AND id.future_contact = 'Yes') OR
/* Twin broken off - No inform - Have partner */
(td.participation = 'Aborted' AND ISNULL(id.suspect)
AND p2.dead = 0))
AND
l.event = 'Finished'
/* Get at area code */
AND SUBSTRING(p1.postal_code, 1, 2) = pg.code
/* Not already distributed */
AND (h.nurse IS NULL OR h.nurse=00 OR h.doctor=00)
/* Has not refused or been aborted */
AND NOT (h.status = 'Refused' OR h.status = 'Aborted'
OR h.status = 'Died' OR h.status = 'Other')
ORDER BY
tvid;
Some explanations:
CONCAT(p1.id, p1.tvab) + 0 AS tvid
id and tvab in
numerical order. Adding 0 to the result causes MySQL to
treat the result as a number.
id
tvab
1 or 2.
ptvab
tvab. When tvab is 1 this is
2, and vice versa. It exists to save typing and to make it easier for
MySQL to optimize the query.
This query demonstrates, among other things, how to do lookups on a table
from the same table with a join (p1 and p2). In the example,
this is used to check whether a twin's partner died before the age of 65. If
so, the row is not returned.
All of the above exist in all tables with twin-related information. We
have a key on both id,tvab (all tables), and id,ptvab
(person_data) to make queries faster.
On our production machine (A 200MHz UltraSPARC), this query returns about 150-200 rows and takes less than one second.
The current number of records in the tables used in the query:
| Table | Rows |
person_data | 71074 |
lentus | 5291 |
twin_project | 5286 |
twin_data | 2012 |
informant_data | 663 |
harmony | 381 |
postal_groups | 100 |
Each interview ends with a status code called event. The query
shown here is used to display a table over all twin pairs combined by
event. This indicates in how many pairs both twins are finished, in how many
pairs one twin is finished and the other refused, and so on.
SELECT
t1.event,
t2.event,
COUNT(*)
FROM
lentus AS t1,
lentus AS t2,
twin_project AS tp
WHERE
/* We are looking at one pair at a time */
t1.id = tp.id
AND t1.tvab=tp.tvab
AND t1.id = t2.id
/* Just the screening survey */
AND tp.survey_no = 5
/* This makes each pair only appear once */
AND t1.tvab='1' AND t2.tvab='2'
GROUP BY
t1.event, t2.event;
There are programs that let you authenticate your users from a MySQL database and also let you write your log files into a MySQL table.
You can change the Apache logging format to be easily readable by MySQL by putting the following into the Apache configuration file:
LogFormat \
"\"%h\",%{%Y%m%d%H%M%S}t,%>s,\"%b\",\"%{Content-Type}o\", \
\"%U\",\"%{Referer}i\",\"%{User-Agent}i\""
To load a log file in that format into MySQL, you can use a statement something like this:
LOAD DATA INFILE '/local/access_log' INTO TABLE tbl_name FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"' ESCAPED BY '\\'
The named table should be created to have columns that correspond to those
that the LogFormat line writes to the log file.
This chapter provides a brief overview of the programs provided by MySQL AB and discusses how to specify options when you run these programs. Most programs have options that are specific to their own operation, but the syntax for specifying options is similar for all of them. Later chapters provide more detailed descriptions of individual programs, including which options they recognize.
MySQL AB provides several types of programs:
mysqld is the MySQL server
mysqld_safe, mysql.server, and mysqld_multi are server
startup scripts
mysql_install_db initializes the data directory and the initial
databases
mysql is a command-line client for executing SQL statements interactively
or in batch mode
mysqlcc (MySQL Control Center) is an interactive graphical tool for
executing SQL statements and administration
mysqladmin is an administrative client
mysqlcheck performs table maintenance operations
mysqldump and mysqlhotcopy make database backups
mysqlimport imports data files
mysqlshow displays information about databases and tables
myisamchk performs table maintenance operations
myisampack produces compressed, read-only tables
mysqlbinlog is a tool for processing binary log files
perror displays error code meanings
myisamchk is discussed further in section 5 Database Administration.
The other programs are further in section 8 MySQL Client and Utility Programs.
Most MySQL distributions include all of these programs, except for those programs that are platform-specific. (For example, the server startup scripts are not used on Windows.) The exception is that RPM distributions are more specialized. There is one RPM for the server, another for the client programs, and so forth. If you appear to be missing one or more programs, see section 2 Installing MySQL for information on types of distributions and what they contain. It may be that you need to install something else.
To invoke a MySQL program at the command line (that is, from your shell or
command prompt), enter the program name followed by any options or other
arguments needed to instruct the program what you want it to do. The following
commands show some sample program invocations. ``shell>'' represents
the prompt for your command interpreter; it is not part of what you type.
The particular prompt you see depends on your command interpreter.
Typical prompts are $ for sh or bash, % for
csh or tcsh, and C:\> for Windows
command.com or cmd.exe.
shell> mysql test shell> mysqladmin extended-status variables shell> mysqlshow --help shell> mysqldump --user=root personnel
Arguments that begin with a dash are option arguments. They typically specify the type of connection a program should make to the server or affect its operational mode. Options have a syntax that is described in section 4.3 Specifying Program Options.
Non-option arguments (arguments with no leading dash) provide additional
information to the program. For example, the mysql program interprets
the first non-option argument as a database name, so the command
mysql test indicates that you want to use the test database.
Later sections that describe individual programs indicate which options a program understands and describe the meaning of any additional non-option arguments.
Some options are common to a number of programs. The most common of these are
the --host, --user, and --password options that specify
connection parameters. They indicate the host where the MySQL server is
running, and the username and password of your MySQL account. All MySQL client
programs understand these options; they allow you to specify which server to
connect to and the account to use on that server.
You may find it necessary to invoke MySQL programs using the
pathname to the `bin' directory in which they are installed. This is
likely to be the case if you get a ``program not found'' error whenever
you attempt to run a MySQL program from any directory other than the
`bin' directory. To make it more convenient to use MySQL, you
can add the pathname of the `bin' directory to your PATH
environment variable setting. Then to run a program you need only type
its name, not its entire pathname.
Consult the documentation for your command interpreter for instructions on
setting your PATH. The syntax for setting environment variables is
interpreter-specific.
You can provide options for MySQL programs in several ways:
MySQL programs determine which options are given first by examining environment variables, then option files, and then the command line. If an option is specified multiple times, the last occurrence takes precedence. This means that environment variables have the lowest precedence and command-line options the highest.
You can take advantage of the way that MySQL programs process options by specifying the default values for a program's options in an option file. Then you need not type them each time you run the program, but can override the defaults if necessary by using command-line options.
Program options specified on the command line follow these rules:
-? and --help are the short and long forms
of the option that instructs a MySQL program to display a help message.
-v and -V are both legal and
have different meanings. (They are the corresponding short forms of the
--verbose and --version options.)
-h localhost or --host=localhost indicate
the MySQL server host to a client program. The option value
tells the program the name of the host where the MySQL server is running.
-hlocalhost and -h localhost are equivalent.)
An exception to this rule is the option for specifying your MySQL password.
This option can be given in long form as --password=pass_val or as
--password. In the latter case (with no password value given), the
program prompts you for the password.
The password option also may be given in short form as -ppass_val or as
-p. However, for the short form, if the password value is given, it
must follow the option letter with no intervening space. The reason for
this is that if a space follows the option letter, the program has no way to
tell whether a following argument is supposed to be the password value or some
other kind of argument. Consequently, the following two commands have two
completely different meanings:
shell> mysql -ptest shell> mysql -p testThe first command instructs
mysql to use a password value of
test, but specifies no default database.
The second instructs mysql to prompt for the password value
and to use test as the default database.
MySQL 4.0 introduced some additional flexibility in the way you specify options. These changes were made in MySQL 4.0.2. Some of them relate to the way you specify options that have ``enabled'' and ``disabled'' states, and to the use of options that might be present in one version of MySQL but not another. Those capabilities are discussed in this section. Another change pertains to the way you use options to set program variables. section 4.3.4 Using Options to Set Program Variables discusses that topic further.
Some options control behavior that can be turned on or off. For example,
the mysql client supports a --column-names option that
determines whether or not to display a row of column names at the beginning
of query results. By default, this option is enabled. However, you may
want to disable it in some instances, such as when sending the output
of mysql into another program that expects to see only data and
not an initial header line.
To disable column names, you can specify the option using any of these forms:
--disable-column-names --skip-column-names --column-names=0
The --disable and --skip prefixes and the =0 suffix
all have the same effect: They turn the option off.
The ``enabled'' form of the option may be specified in any of these ways:
--column-names --enable-column-names --column-names=1
Another change to option processing introduced in MySQL 4.0 is that you
can use the --loose prefix for command-line options. If an option
is prefixed by --loose, the program does not exit with
an error if it does not recognize the option, but instead issues
only a warning:
shell> mysql --loose-no-such-option mysql: WARNING: unknown option '--no-such-option'
The --loose prefix can be useful when you run programs from
multiple installations of MySQL on the same machine, at least if all the
versions are as recent as 4.0.2. This prefix is particularly useful when you
list options in an option file. An option that may not be recognized by all
versions of a program can be given using the --loose
prefix (or loose in an option file). Versions of the program that do
not recognize the option issue a warning and ignore it. This
strategy requires that versions involved be 4.0.2 or later, because
earlier versions know nothing of the --loose convention.
MySQL programs can read startup options from option files (also sometimes called configuration files). Option files provide a convenient way to specify commonly used options so that they need not be entered on the command line each time you run a program. Option file capability is available from MySQL 3.22 on.
The following programs support option files:
myisamchk,
myisampack,
mysql,
mysql.server,
mysqladmin,
mysqlbinlog,
mysqlcc,
mysqlcheck,
mysqld_safe,
mysqldump,
mysqld,
mysqlhotcopy,
mysqlimport, and
mysqlshow.
On Windows, MySQL programs read startup options from the following files:
| Filename | Purpose |
WINDIR\my.ini | Global options |
C:\my.cnf | Global options |
INSTALLDIR\my.ini | Global Options |
WINDIR represents the location of your Windows directory. This is
commonly `C:\Windows' or `C:\WinNT'. You can determine its
exact location from the value of the WINDIR environment variable
using the following command:
C:\> echo %WINDIR%
INSTALLDIR represents the installation directory of MySQL. This is typically the case with MySQL 4.1.5 and higher, when installed using the installation and configuration wizards. See section 2.3.5.14 The Location of the my.ini File.
On Unix, MySQL programs read startup options from the following files:
| Filename | Purpose |
/etc/my.cnf | Global options |
$MYSQL_HOME/my.cnf | Server-specific options |
defaults-extra-file | The file specified with --defaults-extra-file=path, if any
|
~/.my.cnf | User-specific options |
MYSQL_HOME is an environment variable containing the path to the directory
in which the server-specific my.cnf file resides. This used to be DATADIR
prior to MySQL version 5.0.3.
If MYSQL_HOME is not set and there is a my.cnf file in DATADIR and
there is no my.cnf file in BASEDIR, mysqld_safe sets MYSQL_HOME to DATADIR.
Otherwise, if MYSQL_HOME is not set and there is no my.cnf in DATADIR, then
mysqld_safe sets MYSQL_HOME to BASEDIR.
Typically this is `/usr/local/mysql/data' for a binary installation or
`/usr/local/var' for a source installation. Note that this is the data
directory location that was specified at configuration time, not the
one specified with --datadir when mysqld starts.
Use of --datadir at runtime has no effect on where the server
looks for option files, because it looks for them before processing any
command-line arguments.
MySQL looks for option files in the order just described and reads any that exist. If an option file that you want to use does not exist, create it with a plain text editor. If multiple option files exist, an option specified in a file read later takes precedence over the same option specified in a file read earlier.
Any long option that may be given on the command line when running a
MySQL program can be given in an option file as well. To get the list
of available options for a program, run it with the --help option.
The syntax for
specifying options in an option file is similar to command-line syntax, except
that you omit the leading two dashes. For example, --quick or
--host=localhost on the command line should be specified as
quick or host=localhost in an option file.
To specify an option of the form --loose-opt_name
in an option file, write it as loose-opt_name.
Empty lines in option files are ignored. Non-empty lines can take any of the following forms:
#comment
;comment
[group]
set-variable lines
apply to the named group until the end of the option file or another group
line is given.
opt_name
--opt_name on the command line.
opt_name=value
--opt_name=value on the command line.
In an option file, you can have spaces around the `=' character,
something that is not true on the command line.
As of
MySQL 4.0.16, you can quote the value with double quotes or single quotes.
This is useful if the value contains a `#' comment character or whitespace.
set-variable = var_name=value
--set-variable=var_name=value on the
command line.
Spaces are allowed around the first `=' character but not around
the second.
This syntax is deprecated as of MySQL 4.0.
See section 4.3.4 Using Options to Set Program Variables for more information on setting program variables.
Leading and trailing blanks are automatically deleted from option names and values. You may use the escape sequences `\b', `\t', `\n', `\r', `\\', and `\s' in option values to represent the backspace, tab, newline, carriage return, and space characters.
On Windows, if an option value represents a pathname, you should specify the value using `/' rather than `\' as the pathname separator. If you use `\', you must double it as `\\', because `\' is the escape character in MySQL.
If an option group name is the same as a program name, options in the group apply specifically to that program.
The [client] option group is read by all client programs (but not
by mysqld). This allows you to specify options that apply to every
client. For example, [client] is the perfect group to use to specify
the password that you use to connect to the server. (But make sure that
the option file is readable and writable only by yourself, so that other
people cannot find out your password.) Be sure not to put an option in the
[client] group unless it is recognized by all client programs
that you use. Programs that do not understand the option quit after
displaying an error message if you try to run them.
As of MySQL 4.0.14, if you want to create option groups that should be
read only by one specific mysqld server release series, you can do this by
using groups with names of [mysqld-4.0], [mysqld-4.1], and so
forth. The following group indicates that the --new option should be
used only by MySQL servers with 4.0.x version numbers:
[mysqld-4.0] new
Here is a typical global option file:
[client] port=3306 socket=/tmp/mysql.sock [mysqld] port=3306 socket=/tmp/mysql.sock key_buffer_size=16M max_allowed_packet=8M [mysqldump] quick
The preceding option file uses var_name=value syntax for the
lines that set the key_buffer_size and max_allowed_packet
variables. Prior to MySQL 4.0.2, you would need to use set-variable
syntax instead (described earlier in this section).
Here is a typical user option file:
[client] # The following password will be sent to all standard MySQL clients password="my_password" [mysql] no-auto-rehash set-variable = connect_timeout=2 [mysqlhotcopy] interactive-timeout
This option file uses set-variable syntax to set the
connect_timeout variable. For MySQL 4.0.2 and up, you can also set
the variable using just connect_timeout=2.
If you have a source distribution, you can find sample option files named `my-xxxx.cnf' in the `support-files' directory. If you have a binary distribution, look in the `support-files' directory under your MySQL installation directory (typically `C:\mysql' on Windows or `/usr/local/mysql' on Unix). On Windows the sample option files may also be located in the MySQL installation directory. Currently there are sample option files for small, medium, large, and very large systems. To experiment with one of these files, copy it to `C:\my.cnf' on Windows or to `.my.cnf' in your home directory on Unix.
Note: On Windows, the `.cnf' option file extension might not be displayed.
All MySQL programs that support option files handle the following command-line options:
--no-defaults
--print-defaults
--defaults-file=path_name
--defaults-extra-file=path_name
To work properly, each of these options must immediately
follow the command name on the command line, with the exception
that --print-defaults may be used immediately after
--defaults-file or --defaults-extra-file.
In shell scripts, you can use the my_print_defaults program to parse
option files. The following example shows the output that
my_print_defaults might produce when asked to show the options found in
the [client] and [mysql] groups:
shell> my_print_defaults client mysql --port=3306 --socket=/tmp/mysql.sock --no-auto-rehash
Note for developers: Option file handling is implemented in the C client library simply by processing all matching options (that is, options in the appropriate group) before any command-line arguments. This works nicely for programs that use the last instance of an option that is specified multiple times. If you have a C or C++ program that handles multiply specified options this way but doesn't read option files, you need add only two lines to give it that capability. Check the source code of any of the standard MySQL clients to see how to do this.
Several other language interfaces to MySQL are based on the C client library, and some of them provide a way to access option file contents. These include Perl and Python. See the documentation for your preferred interface for details.
To specify an option using an environment variable, set the variable using the
syntax appropriate for your comment processor. For example, on Windows or
NetWare,
you can set the USER variable to specify your MySQL account name.
To do so, use this syntax:
SET USER=your_name
The syntax on Unix depends on your shell. Suppose that you want to specify the
TCP/IP port number using the MYSQL_TCP_PORT variable. Typical syntax
(such as for sh, bash, zsh, etc.) is as follows:
MYSQL_TCP_PORT=3306 export MYSQL_TCP_PORT
The first command sets the variable, and the export command exports
the variable to the shell environment so that its value becomes accessible
to MySQL and other processes.
For csh and tcsh there are similar issues. When running
these shells, use setenv to make the shell variable available
to the environment:
setenv MYSQL_TCP_PORT 3306
The commands to set environment variables can be executed at your command
prompt to take effect immediately. These settings persist until you log out.
To have the settings take effect each time you log in,
place the appropriate command or commands in a startup file that your
command interpreter reads each time it starts. Typical startup files are
`AUTOEXEC.BAT' for Windows, `.bash_profile' for bash, or
`.tcshrc' for tcsh. Consult the documentation for your command
interpreter for specific details.
section F Environment Variables lists all environment variables that affect MySQL program operation.
Many MySQL programs have internal variables that can be set at runtime.
As of MySQL 4.0.2, program
variables are set the same way as any other long option that takes a value.
For example, mysql has a max_allowed_packet variable that
controls the maximum size of its communication buffer.
To set the max_allowed_packet variable for mysql to a value of
16MB, use either of the following commands:
shell> mysql --max_allowed_packet=16777216 shell> mysql --max_allowed_packet=16M
The first command specifies the value in bytes. The second specifies the value
in megabytes. Variable values can have a suffix of K, M, or
G (either uppercase or lowercase) to indicate units of kilobytes,
megabytes, or gigabytes.
In an option file, the variable setting is given without the leading dashes:
[mysql] max_allowed_packet=16777216
Or:
[mysql] max_allowed_packet=16M
If you like, underscores in a variable name can be specified as dashes.
Prior to MySQL 4.0.2, program variable names are not recognized as option
names.
Instead, use the --set-variable option to assign a value to a variable:
shell> mysql --set-variable=max_allowed_packet=16777216 shell> mysql --set-variable=max_allowed_packet=16M
In an option file, omit the leading dashes:
[mysql] set-variable = max_allowed_packet=16777216
Or:
[mysql] set-variable = max_allowed_packet=16M
With --set-variable, underscores in variable names cannot be given as
dashes for versions of MySQL older than 4.0.2.
The --set-variable option is still recognized in MySQL 4.0.2 and up,
but is deprecated.
Some server variables can be set at runtime. For details, see section 5.2.3.1 Dynamic System Variables.
This chapter covers topics that deal with administering a MySQL installation, such as configuring the server, managing user accounts, and performing backups.
The MySQL server, mysqld, is the main program that does most of the
work in a MySQL installation. The server is accompanied by several related
scripts that perform setup operations when you install MySQL or that are
helper programs to assist you in starting and stopping the server.
This section provides an overview of the server and related programs, and information about server startup scripts. Information about configuring the server itself is given in section 5.2 Configuring the MySQL Server.
All MySQL programs take many different options. However, every
MySQL program provides a --help option that you can use
to get a description of the program's options. For example, try
mysqld --help.
You can override default options for all standard programs by specifying options on the command line or in an option file. section 4.3 Specifying Program Options.
The following list briefly describes the MySQL server and server-related programs:
mysqld
mysqld-max
mysqld-max Extended MySQL Server.
mysqld_safe
mysqld_safe attempts to start mysqld-max if it exists, and
mysqld otherwise.
See section 5.1.3 The mysqld_safe Server Startup Script.
mysql.server
mysqld_safe to start the MySQL server.
See section 5.1.4 The mysql.server Server Startup Script.
mysqld_multi
mysqld_multi Program for Managing Multiple MySQL Servers.
mysql_install_db
mysql_fix_privilege_tables
There are several other programs that also are run on the server host:
myisamchk
MyISAM tables.
myisamchk is described in
section 5.7.3 Table Maintenance and Crash Recovery.
make_binary_distribution
ftp.mysql.com for the
convenience of other MySQL users.
mysqlbug
mysqld-max Extended MySQL Server
A MySQL-Max server is a version of the mysqld MySQL server that
has been built to include additional features.
The distribution to use depends on your platform:
mysqld.exe) and the MySQL-Max server (mysqld-max.exe), so you
need not get a special distribution. Just use a regular Windows
distribution, available at
http://dev.mysql.com/downloads/.
See section 2.3 Installing MySQL on Windows.
MySQL-server RPM first to install a standard server named
mysqld. Then use the MySQL-Max RPM to install a server named
mysqld-max. The MySQL-Max RPM presupposes that you have
installed the regular server RPM. See section 2.4 Installing MySQL on Linux for more
information on the Linux RPM packages.
mysqld but that has the additional features included.
You can find the MySQL-Max binaries on the MySQL AB Web site at http://dev.mysql.com/downloads/mysql-4.0.html.
MySQL AB builds the MySQL-Max servers by using the following
configure options:
--with-server-suffix=-max
-max suffix to the mysqld version string.
--with-innodb
--with-bdb
USE_SYMDIR
--with-ndb-cluster
MySQL-Max binary distributions are a convenience for those who wish to install precompiled programs. If you build MySQL using a source distribution, you can build your own Max-like server by enabling the same features at configuration time that the MySQL-Max binary distributions are built with.
MySQL-Max servers include the BerkeleyDB (BDB) storage engine whenever possible, but not all platforms support BDB.
MySQL-Max servers for Solaris, Mac OS X, and Linux (on most platforms) include
support for the NDB Cluster storage engine. Note that the server must be started
with the ndbcluster option in order to run the server as part of a MySQL
Cluster. (For details, see section 16.4 MySQL Cluster Configuration.)
The following table shows on which platforms allow MySQL-Max binaries include support for BDB and/or NDB Cluster:
| System | BDB Support | NDB Support |
| AIX 4.3 | N | N |
| HP-UX 11.0 | N | N |
| Linux-Alpha | N | Y |
| Linux-IA-64 | N | N |
| Linux-Intel | Y | Y |
| Mac OS X | N | N |
| NetWare | N | N |
| SCO OSR5 | Y | N |
| Solaris-SPARC | Y | Y |
| Solaris-Intel | N | Y |
| UnixWare | Y | N |
| Windows NT/2000/XP | Y | N |
To find out which storage engines your server supports, issue the following statement:
mysql> SHOW ENGINES; +------------+---------+------------------------------------------------------------+ | Engine | Support | Comment | +------------+---------+------------------------------------------------------------+ | MyISAM | DEFAULT | Default engine as of MySQL 3.23 with great performance | | HEAP | YES | Alias for MEMORY | | MEMORY | YES | Hash based, stored in memory, useful for temporary tables | | MERGE | YES | Collection of identical MyISAM tables | | MRG_MYISAM | YES | Alias for MERGE | | ISAM | NO | Obsolete storage engine, now replaced by MyISAM | | MRG_ISAM | NO | Obsolete storage engine, now replaced by MERGE | | InnoDB | YES | Supports transactions, row-level locking, and foreign keys | | INNOBASE | YES | Alias for INNODB | | BDB | YES | Supports transactions and page-level locking | | BERKELEYDB | YES | Alias for BDB | | NDBCLUSTER | NO | Clustered, fault-tolerant, memory-based tables | | NDB | NO | Alias for NDBCLUSTER | | EXAMPLE | NO | Example storage engine | | ARCHIVE | NO | Archive storage engine | | CSV | NO | CSV storage engine | +------------+---------+------------------------------------------------------------+ 16 rows in set (0.02 sec)
(See also section 13.5.4.8 SHOW ENGINES Syntax.)
Before MySQL 4.1.2, SHOW ENGINES is unavailable. Use the following
statement instead and check the value of the variable for the storage engine
in which you are interested:
mysql> SHOW VARIABLES LIKE 'have_%'; +---------------------+-------+ | Variable_name | Value | +---------------------+-------+ | have_archive | NO | | have_bdb | YES | | have_compress | YES | | have_crypt | NO | | have_csv | NO | | have_example_engine | NO | | have_geometry | YES | | have_innodb | YES | | have_isam | NO | | have_ndbcluster | NO | | have_openssl | NO | | have_query_cache | YES | | have_raid | NO | | have_rtree_keys | YES | | have_symlink | YES | +---------------------+-------+ 15 rows in set (0.15 sec)
The precise output from these SHOW commands will vary according to the
MySQL version used (and the features which are enabled). The values in the
second column indicate the server's level of support for each feature, as shown
here:
| Value | Meaning |
YES | The feature is supported and is active. |
NO | The feature is not supported. |
DISABLED | The feature is supported but has been disabled. |
A value of NO means that the server was compiled without support
for the feature, so it cannot be activated at runtime.
A value of DISABLED occurs either because the server was
started with an option that disables the feature, or because not
all options required to enable it were given. In the latter case, the
host_name.err error log file should contain a reason indicating why
the option is disabled.
One situation in which you might see DISABLED occurs with MySQL 3.23
when the InnoDB storage engine is compiled in. In MySQL 3.23, you
must supply at least the innodb_data_file_path option at runtime to
set up the InnoDB tablespace. Without this option, InnoDB
disables itself.
See section 15.3 InnoDB in MySQL 3.23.
You can specify configuration options for the BDB storage engine, too,
but BDB does not disable itself if you do not provide them.
See section 14.4.3 BDB Startup Options.
You might also see DISABLED for the InnoDB, BDB, or
ISAM storage engines if the server was compiled to support them, but
was started with the --skip-innodb, --skip-bdb, or
--skip-isam options at runtime.
As of Version 3.23, all MySQL servers support MyISAM tables, because
MyISAM is the default storage engine.
mysqld_safe Server Startup Script
mysqld_safe is the recommended way to start a mysqld
server on Unix and NetWare. mysqld_safe adds some safety features
such as restarting the server when an error occurs and logging runtime
information to an error log file. NetWare-specific behaviors are listed
later in this section.
Note:
Before MySQL 4.0, mysqld_safe is named safe_mysqld.
To preserve backward compatibility, MySQL binary distributions for
some time will include safe_mysqld as a symbolic link to
mysqld_safe.
By default, mysqld_safe tries to start an executable named
mysqld-max if it exists, or mysqld otherwise.
Be aware of the implications of this behavior:
MySQL-Max RPM relies on this mysqld_safe
behavior. The RPM installs an executable named mysqld-max, which
causes mysqld_safe to automatically use that executable from that
point on.
mysqld-max, then upgrade later to a non-Max version of MySQL,
mysqld_safe still attempts to run the old mysqld-max
server. If you perform such an upgrade, you should manually remove the old
mysqld-max server to ensure that mysqld_safe runs the new
mysqld server.
To override the default behavior and specify explicitly which server you
want to run, specify a --mysqld or --mysqld-version option to
mysqld_safe.
Many of the options to mysqld_safe are the same as the options to
mysqld. See section 5.2.1 mysqld Command-Line Options.
All options specified to mysqld_safe on the command line are
passed to mysqld. If you want to use any options that are specific
to mysqld_safe and that mysqld doesn't support, do not specify
them on the command line. Instead, list them in the [mysqld_safe] group
of an option file.
See section 4.3.2 Using Option Files.
mysqld_safe reads all options from the [mysqld],
[server], and [mysqld_safe] sections in option files.
For backward compatibility, it also reads [safe_mysqld]
sections, although you should rename such sections to [mysqld_safe]
when you begin using MySQL 4.0 or later.
mysqld_safe supports the following options:
--help
--basedir=path
--core-file-size=size
mysqld should be able to create. The option
value is passed to ulimit -c.
--datadir=path
--defaults-extra-file=path
--defaults-file=path
--err-log=path
--log-error option, to be used before MySQL 4.0.
--ledir=path
mysqld program.
Use this option to explicitly indicate the location of the server.
--log-error=path
--mysqld=prog_name
ledir directory) that you
want to start. This option is needed if you use the MySQL binary distribution
but have the data directory outside of the binary distribution.
--mysqld-version=suffix
--mysqld option, but you specify only
the suffix for the server program name. The basename is assumed to be
mysqld. For example, if you use --mysqld-version=max,
mysqld_safe starts the mysqld-max program in the
ledir directory. If the argument to --mysqld-version is
empty, mysqld_safe uses mysqld in the ledir directory.
--nice=priority
nice program to set the server's scheduling priority to the
given value. This option was added in MySQL 4.0.14.
--no-defaults
--open-files-limit=count
mysqld should be able to open. The option value
is passed to ulimit -n. Note that you need to start
mysqld_safe as root for this to work properly!
--pid-file=path
--port=port_num
--socket=path
--timezone=zone
TZ time zone environment variable to the given option value.
Consult your operating system documentation for legal time zone
specification formats.
--user={user_name | user_id}
mysqld server as the user having the name user_name or
the numeric user ID user_id.
(``User'' in this context refers to a system login account, not a MySQL user
listed in the grant tables.)
The mysqld_safe script is written so that it normally can start a
server that was installed from either a source or a binary distribution of
MySQL, even though these types of distributions typically install the server
in slightly different locations.
(See section 2.1.5 Installation Layouts.)
mysqld_safe expects one of the following conditions to be true:
mysqld_safe is invoked. For binary distributions, mysqld_safe
looks under its working directory for `bin' and `data'
directories. For source distributions, it looks for `libexec' and
`var' directories. This condition should be met if you execute
mysqld_safe from your MySQL installation directory (for example,
`/usr/local/mysql' for a binary distribution).
mysqld_safe attempts to locate them by absolute pathnames.
Typical locations are `/usr/local/libexec' and `/usr/local/var'.
The actual locations are determined from the values configured into the
distribution at the time it was built. They should be correct if MySQL
is installed in the location specified at configuration time.
Because mysqld_safe tries to find the server and databases relative
to its own working directory, you can install a binary distribution of
MySQL anywhere, as long as you run mysqld_safe from the
MySQL installation directory:
shell> cd mysql_installation_directory shell> bin/mysqld_safe &
If mysqld_safe fails, even when invoked from the MySQL
installation directory, you can specify the --ledir and
--datadir options to indicate the directories in which the server and
databases are located on your system.
Normally, you should not edit the mysqld_safe script. Instead,
configure mysqld_safe by using command-line options or options in the
[mysqld_safe] section of a `my.cnf' option file. In rare cases,
it might be necessary to edit mysqld_safe to get it to start the server
properly. However, if you do this, your modified version of
mysqld_safe might be overwritten if you upgrade MySQL in the future, so
you should make a copy of your edited version that you can reinstall.
On NetWare, mysqld_safe is a NetWare Loadable Module (NLM) that is
ported from the original Unix shell script. It does the following:
MyISAM and ISAM tables.
mysqld, monitors it, and restarts it if it terminates in error.
mysqld to the `host_name.err' file in the
data directory.
mysqld_safe screen output to the `host_name.safe' file in the
data directory.
mysql.server Server Startup Script
MySQL distributions on Unix include a script named mysql.server.
It can be used on systems such as Linux and Solaris that use System V-style
run directories to start and stop system services. It is also used by the Mac
OS X Startup Item for MySQL.
mysql.server can be found in the `support-files' directory under
your MySQL installation directory or in a MySQL source tree.
If you use the Linux server RPM package (MySQL-server-VERSION.rpm),
the mysql.server script will be installed in the
`/etc/init.d' directory with the name `mysql'. You need not
install it manually. See section 2.4 Installing MySQL on Linux for more information on the Linux
RPM packages.
Some vendors provide RPM packages that install a startup script under a
different name such as mysqld.
If you install MySQL from a source distribution or using a binary distribution
format that does not install mysql.server automatically, you can
install it manually. Instructions are provided in section 2.9.2.2 Starting and Stopping MySQL Automatically.
mysql.server reads options from the [mysql.server] and
[mysqld] sections of option files. (For backward compatibility,
it also reads [mysql_server] sections, although you should rename such
sections to [mysql.server] when you begin using MySQL 4.0 or later.)
mysqld_multi Program for Managing Multiple MySQL Servers
mysqld_multi is meant for managing several mysqld
processes that listen for connections on different Unix socket files and
TCP/IP ports. It can start or stop servers, or report their current status.
The program searches for groups named [mysqld#] in `my.cnf' (or
in the file named by the --config-file option). # can be any
positive integer. This number is referred to in the following discussion as
the option group number, or GNR. Group numbers distinguish option groups
from one another and are used as arguments to mysqld_multi to specify
which servers you want to start, stop, or obtain a status report for.
Options listed in these groups are the same that you would use in the
[mysqld] group used for starting mysqld. (See, for example,
section 2.9.2.2 Starting and Stopping MySQL Automatically.) However, when using multiple servers it is necessary
that each one use its own value for options such as the Unix socket file and
TCP/IP port number. For more information on which options must be unique per
server in a multiple-server environment, see section 5.10 Running Multiple MySQL Servers on the Same Machine.
To invoke mysqld_multi, use the following syntax:
shell> mysqld_multi [options] {start|stop|report} [GNR[,GNR]...]
start, stop, and report indicate which operation you
want to perform. You can perform the designated operation on a single server
or multiple servers, depending on the GNR list that follows the option name.
If there is no list, mysqld_multi performs the operation for all
servers in the option file.
Each GNR value represents an option group number or range of group numbers.
The value should be the number at the end of the group name in the
option file. For example, the GNR for a group named [mysqld17]
is 17. To specify a range of numbers, separate the first and last
numbers by a dash. The GNR value 10-13 represents groups
[mysqld10] through [mysqld13]. Multiple groups or group
ranges can be specified on the command line, separated by commas. There
must be no whitespace characters (spaces or tabs) in the GNR list; anything
after a whitespace character is ignored.
This command starts a single server using option group [mysqld17]:
shell> mysqld_multi start 17
This command stops several servers, using option groups [mysql8]
and [mysqld10] through [mysqld13]:
shell> mysqld_multi stop 8,10-13
For an example of how you might set up an option file, use this command:
shell> mysqld_multi --example
mysqld_multi supports the following options:
--config-file=name
mysqld_multi looks for [mysqld#] option groups. Without this
option, all options are read from the usual `my.cnf' file. The option
does not affect where mysqld_multi reads its own options, which are
always taken from the [mysqld_multi] group in the usual `my.cnf'
file.
--example
--help
--log=name
--mysqladmin=prog_name
mysqladmin binary to be used to stop servers.
--mysqld=prog_name
mysqld binary to be used. Note that you can specify
mysqld_safe as the value for this option also. The options are passed
to mysqld. Just make sure that you have the directory where mysqld is
located in your PATH
environment variable setting or fix mysqld_safe.
--no-log
--password=password
mysqladmin.
Note that the password value is not optional for this option, unlike for other
MySQL programs.
--silent
--tcp-ip
stop and
report operations.
--user=user_name
mysqladmin.
--verbose
--version
Some notes about mysqld_multi:
mysqld servers
(with the mysqladmin program) has the same username and password for
each server. Also, make sure that the account has the SHUTDOWN
privilege. If the servers that you want to manage have many different
usernames or passwords for the administrative accounts, you might want to
create an account on each server that has the same username and password.
For example, you might set up a common multi_admin account by
executing the following commands for each server:
shell> mysql -u root -S /tmp/mysql.sock -proot_password
mysql> GRANT SHUTDOWN ON *.*
-> TO 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
See section 5.5.2 How the Privilege System Works.
You have to do this for each mysqld server. Change the
connection parameters appropriately when connecting to each one. Note that
the host part of the account name must allow you to connect as
multi_admin from the host where you want to run mysqld_multi.
--pid-file option is very important if you are using mysqld_safe
to start mysqld (for example, --mysqld=mysqld_safe) Every
mysqld should have its own process ID file. The advantage of
using mysqld_safe instead of mysqld is
that mysqld_safe ``guards'' its mysqld process and
restarts it if the process terminates due to a signal
sent using kill -9 or for other reasons, such as a segmentation
fault. Please note that the
mysqld_safe script might require that you start it from a certain
place. This means that you might have to change location to a certain directory
before running mysqld_multi. If you have problems starting,
please see the mysqld_safe script. Check especially the lines:
---------------------------------------------------------------- MY_PWD=`pwd` # Check if we are starting this relative (for the binary release) if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \ -x ./bin/mysqld ----------------------------------------------------------------See section 5.1.3 The
mysqld_safe Server Startup Script.
The test performed by these lines should be successful, or you might encounter
problems.
mysqld.
--user option for mysqld, but in order
to do this you need to run the mysqld_multi script as the Unix
root user. Having the option in the option file doesn't matter; you
just get a warning if you are not the superuser and the mysqld
processes are started under your own Unix account.
mysqld process is started as. Do not use the
Unix root account for this, unless you know what you are doing.
mysqld_multi be sure that you
understand the meanings of the options that are passed to the mysqld
servers and why you would want to have separate mysqld
processes. Beware of the dangers of using multiple mysqld servers
with the same data directory. Use separate data directories, unless you
know what you are doing. Starting multiple servers with the same
data directory does not give you extra performance in a threaded
system.
See section 5.10 Running Multiple MySQL Servers on the Same Machine.
The following example shows how you might set up an option file for use with
mysqld_multi. The first and fifth [mysqld#] group were
intentionally left out from the example to illustrate that you can have
``gaps'' in the option file. This gives you more flexibility. The order in
which the mysqld programs are started or stopped depends on the order
in which they appear in the option file.
# This file should probably be in your home dir (~/.my.cnf) # or /etc/my.cnf # Version 2.1 by Jani Tolonen [mysqld_multi] mysqld = /usr/local/bin/mysqld_safe mysqladmin = /usr/local/bin/mysqladmin user = multi_admin password = multipass [mysqld2] socket = /tmp/mysql.sock2 port = 3307 pid-file = /usr/local/mysql/var2/hostname.pid2 datadir = /usr/local/mysql/var2 language = /usr/local/share/mysql/english user = john [mysqld3] socket = /tmp/mysql.sock3 port = 3308 pid-file = /usr/local/mysql/var3/hostname.pid3 datadir = /usr/local/mysql/var3 language = /usr/local/share/mysql/swedish user = monty [mysqld4] socket = /tmp/mysql.sock4 port = 3309 pid-file = /usr/local/mysql/var4/hostname.pid4 datadir = /usr/local/mysql/var4 language = /usr/local/share/mysql/estonia user = tonu [mysqld6] socket = /tmp/mysql.sock6 port = 3311 pid-file = /usr/local/mysql/var6/hostname.pid6 datadir = /usr/local/mysql/var6 language = /usr/local/share/mysql/japanese user = jani
See section 4.3.2 Using Option Files.
This section discusses MySQL server configuration topics:
mysqld Command-Line Options
When you start the mysqld server, you can specify program options
using any of the methods described in section 4.3 Specifying Program Options. The most
common methods are to provide options in an option file or on the command
line. However, in most cases it is desirable to make sure that the server uses
the same options each time it runs. The best way to ensure this is to
list them in an option file.
See section 4.3.2 Using Option Files.
mysqld reads options from the [mysqld] and [server]
groups. mysqld_safe reads options from the [mysqld],
[server], [mysqld_safe], and [safe_mysqld]
groups. mysql.server reads options from the [mysqld]
and [mysql.server] groups. An embedded MySQL server usually reads
options from the [server], [embedded], and [xxxxx_SERVER]
groups, where xxxxx is the name of the application into which the
server is embedded.
mysqld accepts many command-line options.
For a list, execute mysqld --help. Before MySQL 4.1.1, --help
prints the full help message. As of 4.1.1, it prints a brief message; to see
the full list, use mysqld --verbose --help.
The following list shows some of the most common server options. Additional options are described elsewhere:
mysqld Concerning Security.
MyISAM Startup Options,
section 14.4.3 BDB Startup Options,
section 15.5 InnoDB Startup Options.
You can also set the value of a server system variable by using the variable name as an option, as described later in this section.
--help, -?
--help displays the full help message.
As of 4.1.1, it displays an abbreviated message only. Use both the
--verbose and --help options to see the full message.
--allow-suspicious-udfs
xxx symbol for the main function can be loaded. By default, the
option is off and only UDFs that have at least one auxiliary symbol can be
loaded. This prevents attempts at loading functions from shared object files
other than those containing legitimate UDFs. This option was added in MySQL
4.0.24, 4.1.10a, and 5.0.3.
See section 25.2.3.6 User-defined Function Security Precautions.
--ansi
--sql-mode
option instead.
--basedir=path, -b path
--big-tables
--bind-address=IP
--console
--log-error
is specified. On Windows, mysqld does not close the console screen if
this option is used.
--character-sets-dir=path
--chroot=path
mysqld server in a closed environment during startup by using the
chroot() system call. This is a recommended security measure as of
MySQL 4.0. (MySQL 3.23 is not able to provide a chroot() jail that is
100% closed.) Note that use of this option somewhat limits LOAD
DATA INFILE and SELECT ... INTO OUTFILE.
--character-set-server=charset
--core-file
mysqld dies. For some systems, you must also
specify the --core-file-size option to mysqld_safe.
See section 5.1.3 The mysqld_safe Server Startup Script.
Note that on some systems, such as Solaris, you do
not get a core file if you are also using the --user option.
--collation-server=collation
--datadir=path, -h path
--debug[=debug_options], -# [debug_options]
--with-debug, you can use this
option to get a trace file of what mysqld is doing.
The debug_options string often is 'd:t:o,file_name'.
See section E.1.2 Creating Trace Files.
--default-character-set=charset
--character-set-server as of MySQL 4.1.3.
See section 5.8.1 The Character Set Used for Data and Sorting.
--default-collation=collation
--collation-server as of MySQL 4.1.3.
See section 5.8.1 The Character Set Used for Data and Sorting.
--default-storage-engine=type
--default-table-type.
It is available as of MySQL 4.1.2.
--default-table-type=type
--default-time-zone=type
time_zone system variable. If this option is not given, the default
time zone is the same as the system time zone (given by the value of
the system_time_zone system variable.
This option is available as of MySQL 4.1.3.
--delay-key-write[= OFF | ON | ALL]
DELAYED KEYS option should be used.
Delayed key writing causes key buffers not to be flushed between writes for
MyISAM tables.
OFF disables delayed key writes.
ON enables delayed key writes for those tables that were created with
the DELAYED KEYS option.
ALL delays key writes for all MyISAM tables.
Available as of MySQL 4.0.3.
See section 7.5.2 Tuning Server Parameters. See section 14.1.1 MyISAM Startup Options.
Note: If you set this variable to ALL, you should not use
MyISAM tables from within another program (such as from another MySQL server or
with myisamchk) when the table is in use. Doing so leads to index
corruption.
--delay-key-write-for-all-tables
--delay-key-write=ALL for use prior to MySQL 4.0.3.
As of 4.0.3, use --delay-key-write instead.
--des-key-file=file_name
DES_ENCRYPT() and DES_DECRYPT()
from this file.
--enable-named-pipe
mysqld-nt and mysqld-max-nt servers that support
named pipe connections.
--exit-info[=flags], -T [flags]
mysqld server. Do not use this option unless you know
exactly what it does!
--external-locking
lockd does not fully work (as on Linux), it is easy for
mysqld to deadlock.
This option previously was named --enable-locking.
Note: If you use this option to enable updates to MyISAM
tables from many MySQL processes, you have to ensure that these conditions are
satisfied:
--delay-key-write=ALL or DELAY_KEY_WRITE=1
on any shared tables.
--external-locking
together with --delay-key-write=OFF --query-cache-size=0.
(This is not done by default because in many setups it's useful to have a
mixture of the above options.)
--flush
--init-file=file
--innodb-safe-binlog
InnoDB tables and
the binary log.
See section 5.9.4 The Binary Log.
--language=lang_name, -L lang_name
--large-pages
--log[=file], -l [file]
host_name.log as the filename.
--log-bin=[file]
host_name-bin as the log file basename.
--log-bin-index[=file]
--log-bin, MySQL uses host_name-bin.index as the
filename.
--log-error[=file]
host_name.err as the filename.
--log-isam[=file]
ISAM/MyISAM changes to this file (used only when
debugging ISAM/MyISAM).
--log-long-format
--log-slow-queries and --log-long-format,
queries that are not using indexes also are logged to the slow query log.
--log-long-format is deprecated as of MySQL version 4.1, when
--log-short-format was introduced. (Long log format is the
default setting since version 4.1.) Also note that starting with MySQL
4.1, the --log-queries-not-using-indexes option is available for
the purpose of logging queries that do not use indexes to the slow query log.
--log-queries-not-using-indexes
--log-slow-queries, then
queries that are not using indexes also are logged to the slow query log. This
option is available as of MySQL 4.1. See section 5.9.5 The Slow Query Log.
--log-short-format
--log-slow-queries[=file]
long_query_time seconds
to execute to this file.
See section 5.9.5 The Slow Query Log.
Note that the default for the amount of information
logged has changed in MySQL 4.1. See the --log-long-format and
--log-short-format options for details.
--log-update[=file]
--log-bin). See section 5.9.4 The Binary Log. Starting from version 5.0.0,
using --log-update turns on the binary log instead
(see section D.1.5 Changes in release 5.0.0 (22 Dec 2003: Alpha)).
--log-warnings, -W
Aborted connection... to the error log.
Enabling this option is recommended, for example, if you
use replication (you get more information about what is happening,
such as messages about network failures and reconnections).
This option is enabled by default as of MySQL 4.0.19 and 4.1.2; to disable it,
use --skip-log-warnings.
As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error
log unless the value is greater than 1.
See section A.2.10 Communication Errors and Aborted Connections.
This option was named --warnings before MySQL 4.0.
--low-priority-updates
INSERT, REPLACE, DELETE, UPDATE)
have lower priority than selects. This can also be done via
{INSERT | REPLACE | DELETE | UPDATE} LOW_PRIORITY ... to lower
the priority of only one query, or by
SET LOW_PRIORITY_UPDATES=1 to change the priority in one
thread. See section 7.3.2 Table Locking Issues.
--memlock
mysqld process in memory. This works on systems such as
Solaris that support the mlockall() system call. This
might help if you have a problem where the operating system is causing
mysqld to swap on disk.
Note that use of this option requires that you run the server as root,
which is normally not a good idea for security reasons.
--myisam-recover [=option[,option...]]]
MyISAM storage engine recovery mode.
The option value is any combination of the values
of DEFAULT, BACKUP, FORCE, or QUICK.
If you specify multiple values, separate them by commas.
You can also use a value of "" to disable this
option. If this option is used, mysqld, when it opens a
MyISAM table, checks whether the
table is marked as crashed or wasn't closed properly.
(The last option works only if you are running with
--skip-external-locking.) If this is the case, mysqld runs
a check on the table. If the table was corrupted, mysqld
attempts to repair it.
The following options affect how the repair works:
| Option | Description |
DEFAULT | The same as not giving any option to
--myisam-recover.
|
BACKUP | If the data file was changed during recovery, save a backup of the `tbl_name.MYD' file as `tbl_name-datetime.BAK'. |
FORCE | Run recovery even if we would lose more than one row from the `.MYD' file. |
QUICK | Don't check the rows in the table if there aren't any delete blocks. |
BACKUP,FORCE. This forces a repair of a table even if some rows
would be deleted, but it keeps the old data file as a backup so that
you can later examine what happened.
This option is available as of MySQL 3.23.25.
--ndb-connectstring=connect_string
NDB storage engine, it is possible to point out the
management server that distributes the cluster configuration by setting the
connect string option. See section 16.4.4.2 The MySQL Cluster connectstring for syntax.
--ndbcluster
NDB Cluster storage engine
(from version 4.1.3, the MySQL-Max binaries are built with NDB Cluster enabled)
the default disabling of support for the NDB Cluster storage engine can be
overruled by using this option. Using the NDB Cluster storage engine is
necessary for using MySQL Cluster.
See section 16 MySQL Cluster.
--new
--new option can be used to make the server
behave as 4.1 in certain respects, easing a 4.0 to 4.1 upgrade:
0xFF are treated as strings by
default rather than as numbers. (Works in 4.0.12 and up.)
TIMESTAMP is returned as a string with the format
'YYYY-MM-DD HH:MM:SS'. (Works in 4.0.13 and up.)
See section 11 Column Types.
--old-passwords
--old-protocol, -o
--one-thread
--open-files-limit=count
mysqld.
If this is not set or set to 0, then mysqld uses this value
to reserve file descriptors to use with setrlimit(). If this
value is 0 then mysqld reserves max_connections*5 or
max_connections + table_cache*2 (whichever is larger) number of
files. You should try increasing this if mysqld gives you the
error "Too many open files."
--pid-file=path
mysqld_safe.
--port=port_num, -P port_num
--safe-mode
--safe-show-database
SHOW DATABASES statement displays only the names
of those databases for which the user has some kind of privilege.
As of MySQL 4.0.2, this option is deprecated and doesn't do anything
(it is enabled by default), because there is a SHOW DATABASES
privilege that can be used to control access to database
names on a per-account basis.
See section 5.5.3 Privileges Provided by MySQL.
--safe-user-create
GRANT
statement, if the user doesn't have the INSERT privilege for the
mysql.user table or any column in the table.
--secure-auth
--shared-memory
--shared-memory-base-name=name
--skip-bdb
BDB storage engine. This saves memory and might speed
up some operations.
Do not use this option if you require BDB tables.
--skip-concurrent-insert
MyISAM
tables. (This is to be used only if you think you have found a bug in this
feature.)
--skip-delay-key-write
DELAY_KEY_WRITE option for all tables.
As of MySQL 4.0.3, you should use --delay-key-write=OFF instead.
See section 7.5.2 Tuning Server Parameters.
--skip-external-locking
isamchk or myisamchk,
you must shut down the server. See section 1.2.3 MySQL Stability. In MySQL 3.23, you
can use CHECK TABLE and REPAIR TABLE to check and repair
MyISAM tables.
This option previously was named --skip-locking.
--skip-grant-tables
mysqladmin
flush-privileges or mysqladmin reload command, or by issuing a
FLUSH PRIVILEGES statement.)
--skip-host-cache
--skip-innodb
InnoDB storage engine. This saves memory and disk
space and might speed up some operations.
Do not use this option if you require InnoDB tables.
--skip-isam
ISAM storage engine. As of MySQL 4.1, ISAM is
disabled by default, so this option applies only if the server was configured
with support for ISAM.
This option was added in MySQL 4.1.1.
--skip-name-resolve
Host column values in the
grant tables must be IP numbers or localhost. See section 7.5.6 How MySQL Uses DNS.
--skip-ndbcluster
NDB Cluster storage engine. This is the default for binaries
that were built with NDB Cluster storage engine support, this means that
the system only allocates memory and other resources for this storage engine
if it is explicitly enabled.
--skip-networking
mysqld must be made via named pipes or shared memory (on Windows) or Unix socket files
(on Unix). This option is highly recommended for systems where only local
clients are allowed. See section 7.5.6 How MySQL Uses DNS.
--skip-new
--skip-symlink
--skip-symbolic-links, for use before MySQL
4.0.13.
--symbolic-links, --skip-symbolic-links
directory.sym file that contains the path to the real directory.
See section 7.6.1.3 Using Symbolic Links for Databases on Windows.
MyISAM index file or data file to another directory with
the INDEX DIRECTORY or DATA DIRECTORY options of the
CREATE TABLE statement. If you delete or rename the table,
the files that its symbolic links point to also are deleted or
renamed. See section 13.2.6 CREATE TABLE Syntax.
--skip-safemalloc
--with-debug=full, all MySQL programs
check for memory overruns during each memory allocation and memory
freeing operation. This checking is very slow, so for the server you
can avoid it when you don't need it by using the --skip-safemalloc
option.
--skip-show-database
SHOW DATABASES statement is allowed only to
users who have the SHOW DATABASES privilege, and the statement
displays all database names. Without this option, SHOW DATABASES is
allowed to all users, but displays each database name only if the user has
the SHOW DATABASES privilege or some privilege for the database.
--skip-stack-trace
mysqld under a debugger. On some systems, you also must use
this option to get a core file. See section E.1 Debugging a MySQL Server.
--skip-thread-priority
--socket=path
MySQL.
--sql-mode=value[,value[,value...]]
--temp-pool
--transaction-isolation=level
READ-UNCOMMITTED,
READ-COMMITTED,
REPEATABLE-READ, or
SERIALIZABLE.
See section 13.4.6 SET TRANSACTION Syntax.
--tmpdir=path, -t path
/tmp directory resides on a partition that
is too small to hold temporary tables. Starting from MySQL 4.1, this
option accepts several paths that are used in round-robin fashion. Paths
should be separated by colon characters (`:') on Unix and semicolon
characters (`;') on Windows, NetWare, and OS/2.
If the MySQL server is acting as a replication slave, you should not set
--tmpdir to point to a directory on a memory-based filesystem or to a
directory that is cleared when the server host restarts. A replication
slave needs some of its temporary files to survive a machine restart so that
it can replicate temporary tables or LOAD DATA INFILE operations. If
files in the temporary file directory are lost when the server restarts,
replication fails.
--user={user_name | user_id}, -u {user_name | user_id}
mysqld server as the user having the name user_name or
the numeric user ID user_id.
(``User'' in this context refers to a system login account, not a MySQL user
listed in the grant tables.)
This option is mandatory when starting mysqld as root.
The server changes its user ID during its startup sequence, causing it
to run as that particular user rather than as root.
See section 5.4.1 General Security Guidelines.
Starting from MySQL 3.23.56 and 4.0.12:
To avoid a possible security hole where a user adds a --user=root
option to some `my.cnf' file (thus causing the server to run as
root), mysqld uses only the first
--user option specified and produces a warning if there are multiple
--user options. Options in `/etc/my.cnf' and
`$MYSQL_HOME/my.cnf' are processed before
command-line options, so it is recommended that you
put a --user option in `/etc/my.cnf' and specify a value other than
root. The option in `/etc/my.cnf' is found before any other
--user options, which ensures that the server runs as a user other
than root, and that a warning results if any other --user option
is found.
--version, -V
As of MySQL 4.0,
you can assign a value to a server system variable by using an option of
the form --var_name=value. For example, --key_buffer_size=32M
sets the key_buffer_size variable to a value of 32MB.
Note that when setting a variable to a value, MySQL might automatically correct it to stay within a given range, or adjust the value to the closest allowable value if only certain values are allowed.
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
You can find a full description for all variables in section 5.2.3 Server System Variables. The section on tuning server parameters includes information on how to optimize them. See section 7.5.2 Tuning Server Parameters.
You can change the values of most system variables for a running server with the
SET statement. See section 13.5.3 SET Syntax.
If you want to restrict the maximum value that a startup option can be set to
with SET, you can define this by using the
--maximum-var_name command-line option.
The MySQL server can operate in different SQL modes, and (as of MySQL 4.1) can apply these modes differentially for different clients. This allows an application to tailor server operation to its own requirements.
Modes define what SQL syntax MySQL should support and what kind of data validation checks it should perform. This makes it easier to use MySQL in different environments and to use MySQL together with other database servers.
You can set the default SQL mode by starting mysqld with the
--sql-mode="modes" option. The value also can be empty
(--sql-mode="") if you want to reset it.
Beginning with MySQL 4.1, you can also change the SQL mode after startup time
by setting the sql_mode variable with a SET [SESSION|GLOBAL]
sql_mode='modes' statement. Setting the GLOBAL variable
requires the SUPER privilege and affects the operation of all clients
that connect from that time on. Setting the SESSION variable affects
only the current client. Any client can change its session sql_mode
value.
modes is a list of different modes separated
by comma (`,') characters. You can retrieve the current mode by
issuing a SELECT @@sql_mode statement. The default value is empty
(no modes set).
The most important sql_mode values are probably these:
ANSI
STRICT_TRANS_TABLES
TRADITIONAL
INSERT/UPDATE aborts as soon as the error is noticed.
This may not be what you want if you are using a non-transactional storage
engine, because data changes made prior to the error are not be rolled
back, resulting in a ``partially done'' update. (New in MySQL 5.0.2)
When this manual refers to ``strict mode,'' it means a mode where at least
one of STRICT_TRANS_TABLES or STRICT_ALL_TABLES is enabled.
The following list describes all the supported modes:
ALLOW_INVALID_DATES
DATE
and DATETIME columns. It does not apply TIMESTAMP columns,
which always require a valid date.
This mode is new in MySQL 5.0.2. Before 5.0.2, this was the default MySQL
date-handling mode. As of 5.0.2, enabling strict mode causes the server to
require that month and day values be legal, not just in the range from 1
to 12 and 1 to 31. For example, '2004-04-31' is legal with strict
mode disabled, but illegal with strict mode enabled. To allow such dates
in strict mode, enable ALLOW_INVALID_DATES as well.
ANSI_QUOTES
ANSI_QUOTES
enabled, you cannot use double quotes to quote a literal string, because it
is interpreted as an identifier.
(New in MySQL 4.0.0)
ERROR_FOR_DIVISION_BY_ZERO
MOD(X,0)) during an INSERT or
UPDATE, or in any expression (for example, in a select list or
WHERE clause) that involves table data and a division by zero. If
this mode is not given, MySQL instead returns NULL for divisions by
zero. If used in INSERT IGNORE or UPDATE IGNORE, MySQL
generates a warning for divisions by zero, but the result of the operation
is NULL.
(New in MySQL 5.0.2)
HIGH_NOT_PRECEDENCE
NOT operator precedence is handled
so that expressions such as
NOT a BETWEEN b AND c are parsed as
NOT (a BETWEEN b AND c).
Before MySQL 5.0.2, the expression is parsed as
(NOT a) BETWEEN b AND c.
The old higher-precedence behavior can be obtained by enabling the
HIGH_NOT_PRECEDENCE SQL mode.
(New in MySQL 5.0.2)
mysql> SET sql_mode = '';
mysql> SELECT NOT 1 BETWEEN -5 AND 5;
-> 0
mysql> SET sql_mode = 'broken_not';
mysql> SELECT NOT 1 BETWEEN -5 AND 5;
-> 1
IGNORE_SPACE
USER() function, the
name of the user table in the mysql database and the User
column in that table become reserved, so you must quote them:
SELECT "User" FROM mysql."user";(New in MySQL 4.0.0)
NO_AUTO_CREATE_USER
GRANT from automatically creating new users if it would
otherwise do so, unless a password also is specified.
(New in MySQL 5.0.2)
NO_AUTO_VALUE_ON_ZERO
NO_AUTO_VALUE_ON_ZERO affects handling of AUTO_INCREMENT
columns. Normally, you generate the next sequence number for the column by
inserting either NULL or 0 into it.
NO_AUTO_VALUE_ON_ZERO suppresses this behavior for 0 so that
only NULL generates the next sequence number.
(New in MySQL 4.1.1)
This mode can be useful if 0 has been stored in a table's
AUTO_INCREMENT column. (This is not a recommended practice, by
the way.) For example, if you dump the table with mysqldump
and then reload it, MySQL normally generates new sequence numbers when
it encounters the 0 values, resulting in a table with different
contents than the one that was dumped. Enabling NO_AUTO_VALUE_ON_ZERO
before reloading the dump file solves this problem. As of MySQL 4.1.1,
mysqldump automatically includes a statement in the dump output
to enable NO_AUTO_VALUE_ON_ZERO.
NO_BACKSLASH_ESCAPES
NO_DIR_IN_CREATE
INDEX DIRECTORY and DATA
DIRECTORY directives. This option is useful on slave replication servers.
(New in MySQL 4.0.15)
NO_FIELD_OPTIONS
SHOW CREATE
TABLE. This mode is used by mysqldump in portability mode.
(New in MySQL 4.1.1)
NO_KEY_OPTIONS
SHOW CREATE
TABLE. This mode is used by mysqldump in portability mode.
(New in MySQL 4.1.1)
NO_TABLE_OPTIONS
ENGINE) in the
output of SHOW CREATE TABLE. This mode is used by mysqldump in
portability mode.
(New in MySQL 4.1.1)
NO_UNSIGNED_SUBTRACTION
UNSIGNED if one
of the operands is unsigned. Note that this makes UNSIGNED BIGINT not
100% usable in all contexts. See section 12.7 Cast Functions and Operators.
(New in MySQL 4.0.2)
NO_ZERO_DATE
'0000-00-00' as a valid date. You can still insert zero
dates with the IGNORE option.
(New in MySQL 5.0.2)
NO_ZERO_IN_DATE
IGNORE option, we insert a '0000-00-00' date for any such date.
(New in MySQL 5.0.2)
ONLY_FULL_GROUP_BY
GROUP BY part refer to a not
selected column.
(New in MySQL 4.0.0)
PIPES_AS_CONCAT
|| as a string concatenation operator (same as CONCAT())
rather than as a synonym for OR.
(New in MySQL 4.0.0)
REAL_AS_FLOAT
REAL as a synonym for FLOAT rather than as a synonym for
DOUBLE.
(New in MySQL 4.0.0)
STRICT_ALL_TABLES
STRICT_TRANS_TABLES
Strict mode controls how MySQL handles values that are invalid or missing. A
value can be invalid for several reasons. For example, it might have
the wrong data type for the column, or it might be out of range. A value
is missing when a new row to be inserted does not contain a value for a
column that has no explicit DEFAULT clause in its definition.
For transactional tables, an error occurs for invalid or missing
values in a statement when either of the STRICT_ALL_TABLES or
STRICT_TRANS_TABLES modes are enabled. The statement is aborted
and rolled back.
For non-transactional tables, the behavior is the same for either mode, if the bad value occurs in the first row to be inserted or updated. The statement is aborted and the table remains unchanged. If the statement inserts or modifies multiple rows and the bad value occurs in the second or later row, the result depends on which strict option is enabled:
STRICT_ALL_TABLES, MySQL returns an error and ignores the
rest of the rows. However, in this case, the earlier rows still
have been inserted or updated. This means that you might get a partial
update, which might not be what you want. To avoid this, it's best to
use single-row statements because these can be aborted without changing the
table.
STRICT_TRANS_TABLES, MySQL converts an invalid value to the
closest valid value for the column and insert the adjusted value. If a
value is missing, MySQL inserts the implicit default value for the column
data type. In either case, MySQL generates a warning rather than an error
and continues processing the statement. Implicit defaults are described in
section 13.2.6 CREATE TABLE Syntax.
Strict mode disallows invalid date values such as '2004-04-31'.
It does not disallow dates with zero parts such as 2004-04-00' or
``zero'' dates. To disallow these as well, enable the NO_ZERO_IN_DATE
and NO_ZERO_DATE SQL modes in addition to strict mode.
If you are not using strict mode (that is, neither STRICT_TRANS_TABLES
nor STRICT_ALL_TABLES is enabled), MySQL inserts adjusted values
for invalid or missing values and produces warnings. In strict mode, you can
produce this behavior by using INSERT IGNORE or UPDATE IGNORE.
See section 13.5.4.20 SHOW WARNINGS Syntax.
The following special modes are provided as shorthand for combinations of
mode values from the preceding list. All are available as of MySQL 4.1.1,
except TRADITIONAL (5.0.2).
The descriptions include all mode values that are available in the most recent version of MySQL. For older versions, a combination mode does not include individual mode values that are not available except in newer versions.
ANSI
REAL_AS_FLOAT, PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE. Before MySQL 4.1.11 and 5.0.3, ANSI also includes
ONLY_FULL_GROUP_BY.
See section 1.5.3 Running MySQL in ANSI Mode.
DB2
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
MAXDB
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_AUTO_CREATE_USER.
MSSQL
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
MYSQL323
NO_FIELD_OPTIONS, HIGH_NOT_PRECEDENCE.
MYSQL40
NO_FIELD_OPTIONS, HIGH_NOT_PRECEDENCE.
ORACLE
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_AUTO_CREATE_USER.
POSTGRESQL
PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS, NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.
TRADITIONAL
STRICT_TRANS_TABLES, STRICT_ALL_TABLES, NO_ZERO_IN_DATE, NO_ZERO_DATE, ERROR_FOR_DIVISION_BY_ZERO, NO_AUTO_CREATE_USER.
The server maintains many system variables that indicate how it is configured.
All of them have default values. They can be set at server startup
using options on the command line or in option
files. Most of them can be set at runtime using the
SET statement.
Beginning with MySQL 4.0.3,
the mysqld server maintains two kinds of variables.
Global variables affect the overall operation of the server.
Session variables affect its operation for individual client connections.
When the server starts, it initializes all global variables to their default
values. These defaults can be changed by options specified in option files
or on the command line. After the server starts, those global variables
that are dynamic can be changed by connecting to the server and issuing
a SET GLOBAL var_name statement. To change a global variable,
you must have the SUPER privilege.
The server also maintains a set of session variables for each client
that connects. The client's session variables are initialized at connect
time using the current values of the corresponding global variables. For
those session variables that are dynamic, the client can change them
by issuing a SET SESSION var_name statement. Setting a session
variable requires no special privilege, but a client can change only its
own session variables, not those of any other client.
A change to a global variable is visible to any client that accesses that
global variable. However, it affects the corresponding session variable
that is initialized from the global variable only for clients that connect
after the change. It does not affect the session variable for any client
that is currently connected (not even that of the client that issues the
SET GLOBAL statement).
When setting a variable using a startup option, variable values can be given
with a suffix of K, M, or G to indicate kilobytes,
megabytes, or gigabytes, respectively. For example, the following command
starts the server with a key buffer size of 16 megabytes:
mysqld --key_buffer_size=16M
Before MySQL 4.0, use this syntax instead:
mysqld --set-variable=key_buffer_size=16M
The lettercase of suffix letters does not matter; 16M and 16m are
equivalent.
At runtime, use the SET statement to set system variables. In this
context, suffix letters cannot be used, but the value can take the form of an
expression:
mysql> SET sort_buffer_size = 10 * 1024 * 1024;
To specify explicitly whether to set the global or session variable, use the
GLOBAL or SESSION options:
mysql> SET GLOBAL sort_buffer_size = 10 * 1024 * 1024; mysql> SET SESSION sort_buffer_size = 10 * 1024 * 1024;
Without either option, the statement sets the session variable.
The variables that can be set at runtime are listed in section 5.2.3.1 Dynamic System Variables.
If you want to restrict the maximum value to which a system variable can
be set with the SET statement, you can specify this maximum
by using an option of the form --maximum-var_name at server
startup. For example, to prevent the value of query_cache_size
from being increased to more than 32MB at runtime, use the option
--maximum-query_cache_size=32M. This feature is available as of MySQL
4.0.2.
You can view system variables and their values by using the
SHOW VARIABLES statement.
See section 9.4 System Variables for more information.
mysql> SHOW VARIABLES; mysql> SHOW VARIABLES; +---------------------------------+-------------------------------------------------------------+ | Variable_name | Value | +---------------------------------+-------------------------------------------------------------+ | auto_increment_increment | 1 | | auto_increment_offset | 1 | | back_log | 50 | | basedir | /usr/local/mysql | | bdb_cache_size | 8388600 | | bdb_home | /usr/local/mysql | | bdb_log_buffer_size | 131072 | | bdb_logdir | | | bdb_max_lock | 10000 | | bdb_shared_data | OFF | | bdb_tmpdir | /tmp/ | | binlog_cache_size | 32768 | | bulk_insert_buffer_size | 8388608 | | character_set_client | latin1 | | character_set_connection | latin1 | | character_set_database | latin1 | | character_set_results | latin1 | | character_set_server | latin1 | | character_set_system | utf8 | | character_sets_dir | /usr/local/mysql/share/charsets/ | | collation_connection | latin1_swedish_ci | | collation_database | latin1_swedish_ci | | collation_server | latin1_swedish_ci | | concurrent_insert | ON | | connect_timeout | 5 | | datadir | /usr/local/mysql/data/ | | date_format | %Y-%m-%d | | datetime_format | %Y-%m-%d %H:%i:%s | | default_week_format | 0 | | delay_key_write | ON | | delayed_insert_limit | 100 | | delayed_insert_timeout | 300 | | delayed_queue_size | 1000 | | expire_logs_days | 0 | | flush | OFF | | flush_time | 1800 | | ft_boolean_syntax | + -><()~*:""&| | | ft_max_word_len | 84 | | ft_min_word_len | 4 | | ft_query_expansion_limit | 20 | | ft_stopword_file | (built-in) | | group_concat_max_len | 1024 | | have_archive | NO | | have_bdb | YES | | have_compress | YES | | have_crypt | NO | | have_csv | NO | | have_example_engine | NO | | have_geometry | YES | | have_innodb | YES | | have_isam | NO | | have_ndbcluster | NO | | have_openssl | YES | | have_query_cache | YES | | have_raid | NO | | have_rtree_keys | YES | | have_symlink | YES | | init_connect | | | init_file | | | init_slave | | | innodb_additional_mem_pool_size | 2097152 | | innodb_autoextend_increment | 8 | | innodb_buffer_pool_awe_mem_mb | 0 | | innodb_buffer_pool_size | 8388608 | | innodb_data_file_path | ibdata1:10M:autoextend | | innodb_data_home_dir | | | innodb_fast_shutdown | ON | | innodb_file_io_threads | 4 | | innodb_file_per_table | OFF | | innodb_locks_unsafe_for_binlog | OFF | | innodb_flush_log_at_trx_commit | 1 | | innodb_flush_method | | | innodb_force_recovery | 0 | | innodb_lock_wait_timeout | 50 | | innodb_log_arch_dir | | | innodb_log_archive | OFF | | innodb_log_buffer_size | 1048576 | | innodb_log_file_size | 10485760 | | innodb_log_files_in_group | 2 | | innodb_log_group_home_dir | ./ | | innodb_max_dirty_pages_pct | 90 | | innodb_max_purge_lag | 0 | | innodb_table_locks | ON | | innodb_max_purge_lag | 0 | | innodb_mirrored_log_groups | 1 | | innodb_open_files | 300 | | innodb_thread_concurrency | 8 | | interactive_timeout | 28800 | | join_buffer_size | 131072 | | key_buffer_size | 4194304 | | key_cache_age_threshold | 300 | | key_cache_block_size | 1024 | | key_cache_division_limit | 100 | | language | /usr/local/mysql/share/english/ | | large_files_support | ON | | license | GPL | | local_infile | ON | | log | OFF | | log_bin | OFF | | log_error | ./gigan.err | | log_slave_updates | OFF | | log_slow_queries | OFF | | log_update | OFF | | log_warnings | 1 | | long_query_time | 10 | | low_priority_updates | OFF | | lower_case_file_system | OFF | | lower_case_table_names | 1 | | max_allowed_packet | 1048576 | | max_binlog_cache_size | 4294967295 | | max_binlog_size | 1073741824 | | max_connect_errors | 10 | | max_connections | 100 | | max_delayed_threads | 20 | | max_error_count | 64 | | max_heap_table_size | 16777216 | | max_insert_delayed_threads | 20 | | max_join_size | 4294967295 | | max_length_for_sort_data | 1024 | | max_relay_log_size | 0 | | max_seeks_for_key | 4294967295 | | max_sort_length | 1024 | | max_tmp_tables | 32 | | max_user_connections | 0 | | max_write_lock_count | 4294967295 | | myisam_data_pointer_size | 4 | | myisam_max_extra_sort_file_size | 107374182400 | | myisam_max_sort_file_size | 107374182400 | | myisam_recover_options | OFF | | myisam_repair_threads | 1 | | myisam_sort_buffer_size | 8388608 | | named_pipe | OFF | | net_buffer_length | 16384 | | net_read_timeout | 30 | | net_retry_count | 10 | | net_write_timeout | 60 | | new | OFF | | old_passwords | OFF | | open_files_limit | 622 | | optimizer_prune_level | 1 | | optimizer_search_depth | 62 | | pid_file | /usr/local/mysql/gigan.pid | | port | 3306 | | preload_buffer_size | 32768 | | protocol_version | 10 | | query_alloc_block_size | 8192 | | query_cache_limit | 1048576 | | query_cache_min_res_unit | 4096 | | query_cache_size | 0 | | query_cache_type | ON | | query_cache_wlock_invalidate | OFF | | query_prealloc_size | 8192 | | range_alloc_block_size | 2048 | | read_buffer_size | 61440 | | read_only | OFF | | read_rnd_buffer_size | 258048 | | relay_log_purge | ON | | rpl_recovery_rank | 0 | | secure_auth | OFF | | shared_memory | OFF | | shared_memory_base_name | MYSQL | | server_id | 0 | | skip_external_locking | ON | | skip_networking | OFF | | skip_show_database | OFF | | slave_net_timeout | 3600 | | slow_launch_time | 2 | | socket | /tmp/mysql.sock | | sort_buffer_size | 217080 | | sql_mode | | | storage_engine | MyISAM | | sync_binlog | 0 | | sync_frm | ON | | system_time_zone | E. Australia Standard Time | | table_cache | 256 | | table_type | MyISAM | | thread_cache_size | 0 | | thread_stack | 196608 | | time_format | %H:%i:%s | | time_zone | SYSTEM | | tmp_table_size | 5242880 | | tmpdir | /tmp/ | | transaction_alloc_block_size | 8192 | | transaction_prealloc_size | 4096 | | tx_isolation | REPEATABLE-READ | | updatable_views_with_limit | YES | | version | 5.0.2-alpha-max | | version_bdb | Sleepycat Software: Berkeley DB 4.1.24: (December 1, 2004) | | version_comment | Source distribution | | wait_timeout | 28800 | +---------------------------------+-------------------------------------------------------------+
Most system variables are described here. Variables with no version
indicated have been present since at least MySQL 3.22. InnoDB system
variables are listed at
section 15.5 InnoDB Startup Options.
Values for buffer sizes, lengths, and stack sizes are given in bytes unless otherwise specified.
Information on tuning these variables can be found in section 7.5.2 Tuning Server Parameters.
ansi_mode
ON if mysqld was started with --ansi.
See section 1.5.3 Running MySQL in ANSI Mode.
This variable was added in MySQL 3.23.6 and removed in 3.23.41.
See the description for sql_mode.
back_log
back_log value indicates how many requests can be
stacked during this short time before MySQL momentarily stops
answering new requests. You need to increase this only if you expect a large
number of connections in a short period of time.
In other words, this value is the size of the listen queue for incoming
TCP/IP connections. Your operating system has its own limit on the size
of this queue. The manual page for the Unix listen() system
call should have more details. Check your OS documentation for the
maximum value for this variable. Attempting to set back_log
higher than your operating system limit is ineffective.
basedir
--basedir option.
bdb_cache_size
BDB tables. If you don't use BDB tables, you should start
mysqld with --skip-bdb to not waste memory for this cache.
This variable was added in MySQL 3.23.14.
bdb_home
BDB tables. This should be assigned the same
value as the datadir variable.
This variable was added in MySQL 3.23.14.
bdb_log_buffer_size
BDB tables. If you don't use BDB tables, you should set this
to 0 or start mysqld with --skip-bdb to not waste memory for
this cache.
This variable was added in MySQL 3.23.31.
bdb_logdir
BDB storage engine writes its log files.
This variable can be set with the --bdb-logdir option.
This variable was added in MySQL 3.23.14.
bdb_max_lock
BDB table
(10,000 by default). You should increase this if errors such as the
following occur when you perform long transactions or when mysqld has
to examine many rows to calculate a query:
bdb: Lock table is out of available locks Got error 12 from ...This variable was added in MySQL 3.23.29.
bdb_shared_data
ON if you are using --bdb-shared-data.
This variable was added in MySQL 3.23.29.
bdb_tmpdir
--bdb-tmpdir option.
This variable was added in MySQL 3.23.14.
bdb_version
version_bdb.
binlog_cache_size
--log-bin option). If you
often use big, multiple-statement transactions, you can increase this to get
more performance.
The Binlog_cache_use and Binlog_cache_disk_use status variables
can be useful for tuning the size of this variable.
This variable was added in MySQL 3.23.29.
See section 5.9.4 The Binary Log.
bulk_insert_buffer_size
MyISAM uses a special tree-like cache to make bulk inserts faster for
INSERT ... SELECT, INSERT ... VALUES (...), (...), ..., and
LOAD DATA INFILE. This variable limits
the size of the cache tree in bytes per thread. Setting it to 0
disables this optimization.
Note: This cache is used only when adding data to a non-empty table.
The default value is 8MB.
This variable was added in MySQL 4.0.3.
This variable previously was named myisam_bulk_insert_tree_size.
character_set
character_set_xxx variables.
character_set_client
character_set_connection
character_set_database
character_set_server.
This variable was added in MySQL 4.1.1.
character_set_results
character_set_server
character_set_system
utf8.
This variable was added in MySQL 4.1.1.
character_sets
SHOW CHARACTER SET for a list of character sets.)
character_sets_dir
collation_connection
collation_database
collation_server.
This variable was added in MySQL 4.1.1.
collation_server
concurrent_insert
ON (the default), MySQL allows INSERT and SELECT
statements to run concurrently for MyISAM tables that have no free
blocks in the middle. You can turn this option off by starting
mysqld with --safe or --skip-new.
This variable was added in MySQL 3.23.7.
connect_timeout
mysqld server waits for a connect
packet before responding with Bad handshake.
convert_character_set
SET CHARACTER SET.
This variable was removed in MySQL 4.1.
datadir
--datadir option.
default_week_format
WEEK() function.
This variable is available as of MySQL 4.0.14.
delay_key_write
MyISAM tables. It can have one of the
following values to affect handling of the DELAY_KEY_WRITE table
option that can be used in CREATE TABLE statements.
| Option | Description |
OFF | DELAY_KEY_WRITE is ignored.
|
ON | MySQL honors the DELAY_KEY_WRITE option
for CREATE TABLE. This is the default value.
|
ALL | All new opened tables are treated as if they were
created with the DELAY_KEY_WRITE option enabled.
|
DELAY_KEY_WRITE is enabled, this means that the key buffer for
tables with this option are not flushed on every index update, but
only when a table is closed. This speeds up writes on keys a lot,
but if you use this feature, you should add automatic checking of all
MyISAM tables by starting the server with the --myisam-recover
option (for example, --myisam-recover=BACKUP,FORCE).
See section 5.2.1 mysqld Command-Line Options and section 14.1.1 MyISAM Startup Options.
Note that --external-locking doesn't offer any protection against
index corruption for tables that use delayed key writes.
This variable was added in MySQL 3.23.8.
delayed_insert_limit
delayed_insert_limit delayed rows, the INSERT
DELAYED handler thread checks whether there are any SELECT
statements pending. If so, it allows them to execute before continuing to
insert delayed rows.
delayed_insert_timeout
INSERT DELAYED handler thread should wait for
INSERT statements before terminating.
delayed_queue_size
INSERT DELAYED
statements. If the queue becomes full, any client that issues an
INSERT DELAYED statement waits until there is room in the queue
again.
expire_logs_days
flush
ON if you have started mysqld with the --flush
option.
This variable was added in MySQL 3.22.9.
flush_time
flush_time seconds to free up resources and sync unflushed data to
disk. We recommend this option only on Windows 9x or Me, or on systems
with minimal resources available.
This variable was added in MySQL 3.22.18.
ft_boolean_syntax
IN BOOLEAN MODE.
This variable was added in MySQL 4.0.1.
See section 12.6.1 Boolean Full-Text Searches.
The default variable value is '+ -><()~*:""&|'. The rules for
changing the value are as follows:
ft_max_word_len
FULLTEXT index.
This variable was added in MySQL 4.0.0.
Note: FULLTEXT indexes must be rebuilt after changing
this variable.
Use REPAIR TABLE tbl_name QUICK.
ft_min_word_len
FULLTEXT index.
This variable was added in MySQL 4.0.0.
Note: FULLTEXT indexes must be rebuilt after changing
this variable.
Use REPAIR TABLE tbl_name QUICK.
ft_query_expansion_limit
WITH QUERY EXPANSION.
This variable was added in MySQL 4.1.1.
ft_stopword_file
'') disables stopword filtering. This variable was added in
MySQL 4.0.10.
Note: FULLTEXT indexes must be rebuilt after changing
this variable.
Use REPAIR TABLE tbl_name QUICK.
group_concat_max_len
GROUP_CONCAT() function.
This variable was added in MySQL 4.1.0.
have_archive
YES if mysqld supports ARCHIVE tables, NO
if not. This variable was added in MySQL 4.1.3.
have_bdb
YES if mysqld supports BDB tables. DISABLED
if --skip-bdb is used.
This variable was added in MySQL 3.23.30.
have_compress
zlib compression library is available to the server.
If not, the COMPRESS() and UNCOMPRESS() functions cannot be
used.
This variable was added in MySQL 4.1.1.
have_crypt
crypt() system call is available to the server.
If not, the CRYPT() function cannot be used.
This variable was added in MySQL 4.0.10.
have_csv
YES if mysqld supports ARCHIVE tables, NO
if not. This variable was added in MySQL 4.1.4.
have_example_engine
YES if mysqld supports EXAMPLE tables, NO
if not. This variable was added in MySQL 4.1.4.
have_geometry
have_innodb
YES if mysqld supports InnoDB tables. DISABLED
if --skip-innodb is used.
This variable was added in MySQL 3.23.37.
have_isam
YES if mysqld supports ISAM tables. DISABLED
if --skip-isam is used.
This variable was added in MySQL 3.23.30.
have_ndbcluster
YES if mysqld supports NDB Cluster tables.
DISABLED if --skip-ndbcluster is used.
This variable was added in MySQL 4.1.2.
have_openssl
YES if mysqld supports SSL (encryption) of the client/server
protocol.
This variable was added in MySQL 3.23.43.
have_query_cache
YES if mysqld supports the query cache.
This variable was added in MySQL 4.0.2.
have_raid
YES if mysqld supports the RAID option.
This variable was added in MySQL 3.23.30.
have_rtree_keys
RTREE indexes are available. (These are used for spatial
indexed in MyISAM tables.)
This variable was added in MySQL 4.1.3.
have_symlink
DATA DIRECTORY and INDEX DIRECTORY table options.
This variable was added in MySQL 4.0.0.
init_connect
init_connect can be used to achieve the
same effect:
SET GLOBAL init_connect='SET AUTOCOMMIT=0';This variable can also be set on the command line or in an option file. To set the variable as just shown using an option file, include these lines:
[mysqld] init_connect='SET AUTOCOMMIT=0'Note that the content of
init_connect is not executed for users having
the SUPER privilege; this is in case that content has been wrongly set
(contains a wrong query, for example with a syntax error),
thus making all connections fail. Not executing it for SUPER users
enables those to open a connection and fix init_connect.
This variable was added in MySQL 4.1.2.
init_file
--init-file option when you
start the server. This is a file containing SQL statements that you want
the server to execute when it starts.
Each statement must be on a single line and should not include comments.
This variable was added in MySQL 3.23.2.
init_slave
init_connect, but is a string to be
executed by a slave server each time the SQL thread starts. The format of
the string is the same as for the init_connect variable.
This variable was added in MySQL 4.1.2.
innodb_xxx
InnoDB system variables are listed at
section 15.5 InnoDB Startup Options.
interactive_timeout
CLIENT_INTERACTIVE option to
mysql_real_connect(). See also wait_timeout.
join_buffer_size
join_buffer_size to get a faster full join when
adding indexes is not possible. One join buffer is allocated for each full
join between two tables. For a complex join between several tables for which
indexes are not used, multiple join buffers might be necessary.
key_buffer_size
MyISAM and ISAM tables are buffered and are
shared by all threads. key_buffer_size is the size of the buffer
used for index blocks. The key buffer is also known as the key cache.
The maximum allowable setting for key_buffer_size is 4GB. The
effective maximum size might be less, depending on your available
physical RAM and per-process RAM limits imposed by your operating
system or hardware platform.
Increase the value to get better index handling (for all reads and multiple
writes) to as much as you can afford. Using a value that is 25% of total
memory on a machine that mainly runs MySQL is quite common. However, if you
make the value too large (for example, more than 50% of your total memory)
your system might start to page and become extremely slow. MySQL relies on
the operating system to perform filesystem caching for data reads, so you
must leave some room for the filesystem cache.
For even more speed when writing many rows at the same time, use
LOCK TABLES. See section 13.4.5 LOCK TABLES and UNLOCK TABLES Syntax.
You can check the performance of the key buffer by issuing a SHOW
STATUS statement and examining the Key_read_requests,
Key_reads, Key_write_requests, and Key_writes status
variables.
See section 13.5.4 SHOW Syntax.
The Key_reads/Key_read_requests ratio should normally be
less than 0.01. The Key_writes/Key_write_requests ratio is usually
near 1 if you are using mostly updates and deletes, but might be much
smaller if you tend to do updates that affect many rows at the same time or
if you are using the DELAY_KEY_WRITE table option.
The fraction of the key buffer in use can be determined using
key_buffer_size in conjunction with the Key_blocks_unused status
variable and the buffer block size. From MySQL 4.1.1 on, the buffer block
size is available from the key_cache_block_size server variable. The
fraction of the buffer in use is:
1 - ((Key_blocks_unused * key_cache_block_size) / key_buffer_size)This value is an approximation because some space in the key buffer may be allocated internally for administrative structures. Before MySQL 4.1.1, key cache blocks are 1024 bytes, and before MySQL 4.1.2,
Key_blocks_unused is unavailable. The Key_blocks_used variable
can be used as follows to determine the fraction of the key buffer in use:
(Key_blocks_used * 1024) / key_buffer_sizeHowever,
Key_blocks_used indicates the maximum number of blocks that
have ever been in use at once, so this formula does not necessary represent
the current fraction of the buffer that is in use.
As of MySQL 4.1, it is possible to create multiple MyISAM key caches. The
size limit of 4GB applies to each cache individually, not as a group.
See section 7.4.6 The MyISAM Key Cache.
key_cache_age_threshold
MyISAM Key Cache.
key_cache_block_size
MyISAM Key Cache.
key_cache_division_limit
MyISAM Key Cache.
language
large_file_support
mysqld was compiled with options for large file support.
This variable was added in MySQL 3.23.28.
large_pages
license
local_infile
LOCAL is supported for LOAD DATA INFILE statements.
This variable was added in MySQL 4.0.3.
locked_in_memory
mysqld was locked in memory with --memlock.
This variable was added in MySQL 3.23.25.
log
log_bin
log_error
log_slave_updates
log_slow_queries
long_query_time variable.
This variable was added in MySQL 4.0.2.
See section 5.9.5 The Slow Query Log.
log_update
log_warnings
long_query_time
Slow_queries
status variable is incremented. If you are using the
--log-slow-queries option, the query is logged to the slow query log
file. This value is measured in real time, not CPU time, so a query that is
under the threshold on a lightly loaded system might be above the threshold
on a heavily loaded one.
See section 5.9.5 The Slow Query Log.
low_priority_updates
1, all INSERT, UPDATE, DELETE, and
LOCK TABLE WRITE statements wait until there is no pending
SELECT or LOCK TABLE READ on the affected table.
This variable previously was named sql_low_priority_updates.
It was added in MySQL 3.22.5.
lower_case_file_system
ON means filenames are case
insensitive, OFF means they are case sensitive. This variable was
added in MySQL 4.0.19.
lower_case_table_names
lower_case_table_names to 2.
max_allowed_packet
net_buffer_length
bytes, but can grow up to max_allowed_packet bytes when needed.
This value by default is small, to catch big (possibly wrong) packets.
You must increase this value if you are using big BLOB columns or
long strings. It should be as big as the biggest BLOB you want to
use. The protocol limit for max_allowed_packet is 16MB before
MySQL 4.0 and 1GB thereafter.
max_binlog_cache_size
Multi-statement transaction required more than
'max_binlog_cache_size' bytes of storage.
This variable was added in MySQL 3.23.29.
max_binlog_size
max_binlog_size.
If max_relay_log_size is 0, the value of max_binlog_size
applies to relay logs as well. max_relay_log_size was added in
MySQL 4.0.14.
max_connect_errors
FLUSH HOSTS statement.
max_connections
mysqld requires. See
section 7.4.8 How MySQL Opens and Closes Tables for comments on file descriptor limits.
Also see section A.2.6 Too many connections.
max_delayed_threads
INSERT DELAYED
statements. If you try to insert data into a new table after all INSERT
DELAYED threads are in use, the row is inserted as if the
DELAYED attribute wasn't specified. If you set this to 0, MySQL
never creates a thread to handle DELAYED rows; in effect, this
disables DELAYED entirely.
This variable was added in MySQL 3.23.0.
max_error_count
SHOW ERRORS or SHOW WARNINGS.
This variable was added in MySQL 4.1.0.
max_heap_table_size
MEMORY (HEAP)
tables are allowed to grow. The value of the variable is used to calculate
MEMORY table MAX_ROWS values. Setting this variable has no
effect on any existing MEMORY table, unless the table is re-created
with a statement such as CREATE TABLE or TRUNCATE TABLE, or
altered with ALTER TABLE.
This variable was added in MySQL 3.23.0.
max_insert_delayed_threads
max_delayed_threads.
It was added in MySQL 4.0.19.
max_join_size
SELECT statements that probably need to examine
more than max_join_size rows (for single-table statements) or row
combinations (for multiple-table statements) or that are likely to do more
than max_join_size disk seeks. By setting this value, you can catch
SELECT statements where keys are not used properly and that would
probably take a long time. Set it if your users tend to perform joins
that lack a WHERE clause, that take a long time, or that return
millions of rows.
Setting this variable to a value other than DEFAULT resets
the SQL_BIG_SELECTS value to 0. If you set the
SQL_BIG_SELECTS value again, the max_join_size variable
is ignored.
If a query result is in the query cache, no result size check is performed,
because the result has previously been computed and it does not burden
the server to send it to the client.
This variable previously was named sql_max_join_size.
max_length_for_sort_data
filesort
algorithm to use.
See section 7.2.10 How MySQL Optimizes ORDER BY.
This variable was added in MySQL 4.1.1
max_relay_log_size
max_binlog_size for both binary logs and relay
logs. You must set max_relay_log_size to between 4096 bytes and 1GB
(inclusive), or to 0. The default value is 0. This variable was added in
MySQL 4.0.14.
See section 6.3 Replication Implementation Details.
max_seeks_for_key
SHOW INDEX Syntax). By setting this to a low value (100?), you can force
MySQL to prefer keys instead of table scans.
This variable was added in MySQL 4.0.14.
max_sort_length
BLOB or TEXT
values. Only the first max_sort_length bytes of each value
are used; the rest are ignored.
max_tmp_tables
max_user_connections
MAX_USER_CONNECTIONS resource limit. In that case, the
session value reflects the account limit.
max_write_lock_count
multi_read_range
NDBCLUSTER. This engine needs to send
the range requests to all nodes, and sending many of those requests at once
reduces the communication costs significantly. This variable was added in
MySQL 5.0.3.
myisam_data_pointer_size
CREATE TABLE for
MyISAM tables when no MAX_ROWS option is specified. This
variable cannot be less than 2 or larger than 8. The default value is 4.
This variable was added in MySQL 4.1.2.
See section A.2.11 The table is full.
myisam_max_extra_sort_file_size
MyISAM index creation would be
larger than using the key cache by the amount specified here, prefer the key
cache method. This is mainly used to force long character keys in large
tables to use the slower key cache method to create the index.
This variable was added in MySQL 3.23.37.
Note: The value is given in megabytes before 4.0.3 and
in bytes thereafter.
myisam_max_sort_file_size
MyISAM index (during REPAIR TABLE, ALTER
TABLE, or LOAD DATA INFILE). If the file size would be bigger than
this value, the index is created using the key cache instead, which is
slower.
This variable was added in MySQL 3.23.37.
Note: The value is given in megabytes before 4.0.3 and
in bytes thereafter.
myisam_recover_options
--myisam-recover option.
This variable was added in MySQL 3.23.36.
myisam_repair_threads
MyISAM table indexes are created in
parallel (each index in its own thread) during the Repair by sorting
process. The default value is 1. Note: Multi-threaded repair is
still alpha quality code.
This variable was added in MySQL 4.0.13.
myisam_sort_buffer_size
MyISAM indexes during a
REPAIR TABLE or when creating indexes with CREATE INDEX or
ALTER TABLE.
This variable was added in MySQL 3.23.16.
named_pipe
net_buffer_length
max_allowed_packet bytes.
net_read_timeout
net_read_timeout is the
timeout value controlling when to abort.
When the server is writing to the client, net_write_timeout is the
timeout value controlling when to abort.
See also slave_net_timeout.
This variable was added in MySQL 3.23.20.
net_retry_count
net_write_timeout
net_read_timeout.
This variable was added in MySQL 3.23.20.
new
old_passwords
open_files_limit
mysqld to open.
This is the real value allowed by the system and might be different from the
value you gave mysqld as a startup option. The value is 0 on systems
where MySQL can't change the number of open files. This variable was added
in MySQL 3.23.20.
optimizer_prune_level
optimizer_search_depth
pid_file
--pid-file option.
This variable was added in MySQL 3.23.23.
port
--port option.
preload_buffer_size
protocol_version
query_alloc_block_size
query_cache_limit
query_cache_min_res_unit
query_cache_size
query_cache_type is set to 0.
This variable was added in MySQL 4.0.1.
query_cache_type
GLOBAL value sets the type for all
clients that connect thereafter. Individual clients can set the
SESSION value to affect their own use of the query cache.
| Option | Description |
0 or OFF | Don't cache or retrieve results.
Note that this does not deallocate the query cache buffer. To
do that, you should set query_cache_size to 0.
|
1 or ON | Cache all query results except for those that
begin with SELECT SQL_NO_CACHE.
|
2 or DEMAND | Cache results only for queries that
begin with SELECT SQL_CACHE.
|
query_cache_wlock_invalidate
WRITE lock on a MyISAM
table, other clients are not blocked from issuing queries for the table if
the query results are present in the query cache. Setting this variable to
1 causes acquisition of a WRITE lock for a table to invalidate
any queries in the query cache that refer to the table. This forces other
clients that attempt to access the table to wait while the lock is in effect.
This variable was added in MySQL 4.0.19.
query_prealloc_size
query_prealloc_size value
might be helpful in improving performance, because it can reduce the need for
the server to perform memory allocation during query execution operations.
This variable was added in MySQL 4.0.16.
range_alloc_block_size
read_buffer_size
record_buffer.
read_only
ON for a replication slave server, it
causes the slave to allow no updates except from slave threads or from users
with the SUPER privilege. This can be useful to ensure that a slave
server accepts no updates from clients.
This variable was added in MySQL 4.0.14.
relay_log_purge
read_rnd_buffer_size
ORDER BY performance by a lot. However, this is a buffer
allocated for each client, so you should not set the global variable to a
large value. Instead, change the session variable only from within those
clients that need to run large queries.
This variable was added in MySQL 4.0.3.
Previously, it was named record_rnd_buffer.
safe_show_database
skip_show_database.
This variable was removed in MySQL 4.0.5. Instead, use the SHOW
DATABASES privilege to control access by MySQL accounts to database names.
secure_auth
--secure-auth option,
it blocks connections from all accounts that have passwords stored in the old
(pre-4.1) format. In that case, the value of this variable is ON,
otherwise it is OFF.
You should enable this option if you want to prevent all usage of passwords
in old format (and hence insecure communication over the network).
This variable was added in MySQL 4.1.1.
Server startup fails with an error if this option is enabled
and the privilege tables are in pre-4.1 format.
When used as a client-side option, the client refuses to connect to a server
if the server requires a password in old format for the client account.
server_id
--server-id option. It is used for master and slave
replication servers.
This variable was added in MySQL 3.23.26.
shared_memory
shared_memory_base_name
skip_external_locking
OFF if mysqld uses external locking.
This variable was added in MySQL 4.0.3.
Previously, it was named skip_locking.
skip_networking
ON if the server allows only local (non-TCP/IP) connections.
On Unix, local connections use a Unix socket file. On Windows, local
connections use a named pipe or shared memory. On NetWare, only TCP/IP connections are
supported, so do not set this variable to ON.
This variable was added in MySQL 3.22.23.
skip_show_database
SHOW DATABASES statement if they
don't have the SHOW DATABASES privilege. This can improve security if
you're concerned about people being able to see what databases other users
have. See also safe_show_database.
This variable was added in MySQL 3.23.4. As of MySQL 4.0.2, its effect also
depends on the SHOW DATABASES privilege: If the variable value is
ON, the SHOW DATABASES statement is allowed only to users who
have the SHOW DATABASES privilege, and the statement displays all
database names. If the value is OFF, SHOW DATABASES is
allowed to all users, but displays each database name only if the user has
the SHOW DATABASES privilege or some privilege for the database.
slave_compressed_protocol
slave_net_timeout
slow_launch_time
Slow_launch_threads status variable.
This variable was added in MySQL 3.23.15.
socket
sort_buffer_size
ORDER BY or GROUP BY
operations.
See section A.4.4 Where MySQL Stores Temporary Files.
sql_mode
sql_slave_skip_counter
storage_engine
table_type.
It was added in MySQL 4.1.2.
sync_binlog
fdatasync()) after every sync_binlog'th write to this binary
log. Note that there is one write to the binary log per statement if in
autocommit mode, and otherwise one write per transaction. The default value is
0 which does no sync'ing to disk. A value of 1 is the safest choice, because in
case of crash you lose at most one statement/transaction from the binary
log; but it is also the slowest choice (unless the disk has a battery-backed
cache, which makes sync'ing very fast). This variable was added in MySQL 4.1.3.
sync_frm
fdatasync());
this is slower but safer in case of crash. Default is 1.
system_time_zone
system_time_zone. Typically the time zone
is specified by the TZ environment variable. It also can be specified
using the --timezone option of the mysqld_safe script.
This variable was added in MySQL 4.1.3.
table_cache
mysqld requires.
You can check whether you need to increase the table cache by checking the
Opened_tables status variable.
See section 5.2.4 Server Status Variables.
If the value of Opened_tables is large and you don't do FLUSH
TABLES a lot (which just forces all tables to be closed and reopened),
then you should increase the value of the table_cache variable.
For more information about the table cache, see section 7.4.8 How MySQL Opens and Closes Tables.
table_type
--default-table-type
option.
This variable was added in MySQL 3.23.0.
See section 5.2.1 mysqld Command-Line Options.
thread_cache_size
thread_cache_size threads there. Requests for threads are
satisfied by reusing threads taken from the cache if possible, and only when
the cache is empty is a new thread created. This variable can be increased
to improve performance if you have a lot of new connections. (Normally this
doesn't give a notable performance improvement if you have a good thread
implementation.) By examining the difference between the Connections
and Threads_created status variables (see section 5.2.4 Server Status Variables
for details) you can see how efficient the thread cache is.
This variable was added in MySQL 3.23.16.
thread_concurrency
mysqld calls thr_setconcurrency() with this value.
This function allows applications to give the threads system a hint about
the desired number of threads that should be run at the same time.
This variable was added in MySQL 3.23.7.
thread_stack
crash-me test are dependent on this value. The default is
large enough for normal operation. See section 7.1.4 The MySQL Benchmark Suite.
time_zone
'SYSTEM'
(use the value of system_time_zone), but can be specified
explicitly at server startup time with the --default-time-zone
option.
This variable was added in MySQL 4.1.3.
timezone
TZ environment
variable when mysqld is started. The time zone also can be set by
giving a --timezone argument to mysqld_safe.
This variable was added in MySQL 3.23.15. As of MySQL 4.1.3, it is obsolete
and has been replaced by the system_time_zone variable.
See section A.4.6 Time Zone Problems.
tmp_table_size
MyISAM table.
Increase the value of tmp_table_size if you do many advanced
GROUP BY queries and you have lots of memory.
tmpdir
tmpdir to point to a directory on a memory-based filesystem or to a
directory that is cleared when the server host restarts. A replication
slave needs some of its temporary files to survive a machine restart so that
it can replicate temporary tables or LOAD DATA INFILE operations. If
files in the temporary file directory are lost when the server restarts,
replication fails.
This variable was added in MySQL 3.22.4.
transaction_alloc_block_size
transaction_prealloc_size
transaction_alloc_blocks that
is not freed between queries. By making this big enough to fit all queries
in a common transaction, you can avoid a lot of malloc() calls. This
variable was added in MySQL 4.0.16.
tx_isolation
updatable_views_with_limit
LIMIT clause. (Such updates often are generated by GUI tools.)
An update is an UPDATE or DELETE statement. Primary key
here means a PRIMARY KEY, or a UNIQUE index in which no column
can contain NULL.
The variable can have two values:
1 or YES: Issue a warning only (not an error message).
This is the default value.
0 or NO: Prohibit the update.
version
version_bdb
BDB storage engine version.
This variable was added in MySQL 3.23.31 with the name bdb_version
and renamed to version_bdb in MySQL 4.1.1.
version_comment
configure script has a --with-comment option that
allows a comment to be specified when building MySQL.
This variable contains the value of that comment.
This variable was added in MySQL 4.0.17.
version_compile_machine
version_compile_os
wait_timeout
wait_timeout value is initialized from
the global wait_timeout value or from the global
interactive_timeout value, depending on the type of client (as
defined by the CLIENT_INTERACTIVE connect option to
mysql_real_connect()). See also interactive_timeout.
Beginning with MySQL 4.0.3, many server system variables are dynamic and can
be set at runtime using SET GLOBAL or SET SESSION. You can also
select their values using SELECT.
See section 9.4 System Variables.
The following table shows the full list of all dynamic system variables.
The last column indicates for each variable whether GLOBAL or
SESSION (or both) apply.
| Variable Name | Value Type | Type |
autocommit | boolean | SESSION
|
big_tables | boolean | SESSION
|
binlog_cache_size | numeric | GLOBAL
|
bulk_insert_buffer_size | numeric | GLOBAL | SESSION
|
character_set_client | string | GLOBAL | SESSION
|
character_set_connection | string | GLOBAL | SESSION
|
character_set_results | string | GLOBAL | SESSION
|
character_set_server | string | GLOBAL | SESSION
|
collation_connection | string | GLOBAL | SESSION
|
collation_server | string | GLOBAL | SESSION
|
concurrent_insert | boolean | GLOBAL
|
connect_timeout | numeric | GLOBAL
|
convert_character_set | string | GLOBAL | SESSION
|
default_week_format | numeric | GLOBAL | SESSION
|
delay_key_write | OFF | ON | ALL | GLOBAL
|
delayed_insert_limit | numeric | GLOBAL
|
delayed_insert_timeout | numeric | GLOBAL
|
delayed_queue_size | numeric | GLOBAL
|
error_count | numeric | SESSION
|
expire_logs_days | numeric | GLOBAL
|
flush | boolean | GLOBAL
|
flush_time | numeric | GLOBAL
|
foreign_key_checks | boolean | SESSION
|
ft_boolean_syntax | numeric | GLOBAL
|
group_concat_max_len | numeric | GLOBAL | SESSION
|
identity | numeric | SESSION
|
innodb_autoextend_increment | numeric | GLOBAL
|
innodb_concurrency_tickets | numeric | GLOBAL
|
innodb_max_dirty_pages_pct | numeric | GLOBAL
|
innodb_max_purge_lag | numeric | GLOBAL
|
innodb_sync_spin_loops | numeric | GLOBAL
|
innodb_table_locks | boolean | GLOBAL | SESSION
|
innodb_thread_concurrency | numeric GLOBAL
| |
innodb_thread_sleep_delay | numeric GLOBAL
| |
insert_id | boolean | SESSION
|
interactive_timeout | numeric | GLOBAL | SESSION
|
join_buffer_size | numeric | GLOBAL | SESSION
|
key_buffer_size | numeric | GLOBAL
|
last_insert_id | numeric | SESSION
|
local_infile | boolean | GLOBAL
|
log_warnings | numeric | GLOBAL
|
long_query_time | numeric | GLOBAL | SESSION
|
low_priority_updates | boolean | GLOBAL | SESSION
|
max_allowed_packet | numeric | GLOBAL | SESSION
|
max_binlog_cache_size | numeric | GLOBAL
|
max_binlog_size | numeric | GLOBAL
|
max_connect_errors | numeric | GLOBAL
|
max_connections | numeric | GLOBAL
|
max_delayed_threads | numeric | GLOBAL
|
max_error_count | numeric | GLOBAL | SESSION
|
max_heap_table_size | numeric | GLOBAL | SESSION
|
max_insert_delayed_threads | numeric | GLOBAL
|
max_join_size | numeric | GLOBAL | SESSION
|
max_relay_log_size | numeric | GLOBAL
|
max_seeks_for_key | numeric | GLOBAL | SESSION
|
max_sort_length | numeric | GLOBAL | SESSION
|
max_tmp_tables | numeric | GLOBAL | SESSION
|
max_user_connections | numeric | GLOBAL
|
max_write_lock_count | numeric | GLOBAL
|
multi_read_range | numeric | GLOBAL | SESSION
|
myisam_data_pointer_size | numeric | GLOBAL
|
myisam_max_extra_sort_file_size | numeric | GLOBAL | SESSION
|
myisam_max_sort_file_size | numeric | GLOBAL | SESSION
|
myisam_repair_threads | numeric | GLOBAL | SESSION
|
myisam_sort_buffer_size | numeric | GLOBAL | SESSION
|
net_buffer_length | numeric | GLOBAL | SESSION
|
net_read_timeout | numeric | GLOBAL | SESSION
|
net_retry_count | numeric | GLOBAL | SESSION
|
net_write_timeout | numeric | GLOBAL | SESSION
|
old_passwords | numeric | GLOBAL | SESSION
|
optimizer_prune_level | numeric | GLOBAL | SESSION
|
optimizer_search_depth | numeric | GLOBAL | SESSION
|
preload_buffer_size | numeric | GLOBAL | SESSION
|
query_alloc_block_size | numeric | GLOBAL | SESSION
|
query_cache_limit | numeric | GLOBAL
|
query_cache_size | numeric | GLOBAL
|
query_cache_type | enumeration | GLOBAL | SESSION
|
query_cache_wlock_invalidate | boolean | GLOBAL | SESSION
|
query_prealloc_size | numeric | GLOBAL | SESSION
|
range_alloc_block_size | numeric | GLOBAL | SESSION
|
read_buffer_size | numeric | GLOBAL | SESSION
|
read_only | numeric | GLOBAL
|
read_rnd_buffer_size | numeric | GLOBAL | SESSION
|
rpl_recovery_rank | numeric | GLOBAL
|
safe_show_database | boolean | GLOBAL
|
secure_auth | boolean | GLOBAL
|
server_id | numeric | GLOBAL
|
slave_compressed_protocol | boolean | GLOBAL
|
slave_net_timeout | numeric | GLOBAL
|
slave_transaction_retries | numeric | GLOBAL
|
slow_launch_time | numeric | GLOBAL
|
sort_buffer_size | numeric | GLOBAL | SESSION
|
sql_auto_is_null | boolean | SESSION
|
sql_big_selects | boolean | SESSION
|
sql_big_tables | boolean | SESSION
|
sql_buffer_result | boolean | SESSION
|
sql_log_bin | boolean | SESSION
|
sql_log_off | boolean | SESSION
|
sql_log_update | boolean | SESSION
|
sql_low_priority_updates | boolean | GLOBAL | SESSION
|
sql_max_join_size | numeric | GLOBAL | SESSION
|
sql_mode | enumeration | GLOBAL | SESSION
|
sql_notes | boolean | SESSION
|
sql_quote_show_create | boolean | SESSION
|
sql_safe_updates | boolean | SESSION
|
sql_select_limit | numeric | SESSION
|
sql_slave_skip_counter | numeric | GLOBAL
|
updatable_views_with_limit | enumeration | GLOBAL | SESSION
|
sql_warnings | boolean | SESSION
|
sync_binlog | numeric | GLOBAL
|
sync_frm | boolean | GLOBAL
|
storage_engine | enumeration | GLOBAL | SESSION
|
table_cache | numeric | GLOBAL
|
table_type | enumeration | GLOBAL | SESSION
|
thread_cache_size | numeric | GLOBAL
|
time_zone | string | GLOBAL | SESSION
|
timestamp | boolean | SESSION
|
tmp_table_size | enumeration | GLOBAL | SESSION
|
transaction_alloc_block_size | numeric | GLOBAL | SESSION
|
transaction_prealloc_size | numeric | GLOBAL | SESSION
|
tx_isolation | enumeration | GLOBAL | SESSION
|
unique_checks | boolean | SESSION
|
wait_timeout | numeric | GLOBAL | SESSION
|
warning_count | numeric | SESSION
|
Variables that are marked as ``string'' take a string value. Variables that
are marked as ``numeric'' take a numeric value. Variables that are
marked as ``boolean'' can be set to 0, 1, ON or OFF. Variables
that are marked as ``enumeration'' normally should be set to one of the
available values for the variable, but can also be set to the number that
corresponds to the desired enumeration value. For enumeration-valued system
variables, the first enumeration value corresponds to 0. This differs
from ENUM columns, for which the first enumeration value corresponds
to 1.
The server maintains many status variables that provide information about its
operations. You can view these variables and their values by using the
SHOW STATUS statement:
mysql> SHOW STATUS; +--------------------------+------------+ | Variable_name | Value | +--------------------------+------------+ | Aborted_clients | 0 | | Aborted_connects | 0 | | Bytes_received | 155372598 | | Bytes_sent | 1176560426 | | Connections | 30023 | | Created_tmp_disk_tables | 0 | | Created_tmp_files | 60 | | Created_tmp_tables | 8340 | | Delayed_errors | 0 | | Delayed_insert_threads | 0 | | Delayed_writes | 0 | | Flush_commands | 1 | | Handler_delete | 462604 | | Handler_read_first | 105881 | | Handler_read_key | 27820558 | | Handler_read_next | 390681754 | | Handler_read_prev | 6022500 | | Handler_read_rnd | 30546748 | | Handler_read_rnd_next | 246216530 | | Handler_update | 16945404 | | Handler_write | 60356676 | | Key_blocks_used | 14955 | | Key_read_requests | 96854827 | | Key_reads | 162040 | | Key_write_requests | 7589728 | | Key_writes | 3813196 | | Max_used_connections | 0 | | Not_flushed_delayed_rows | 0 | | Not_flushed_key_blocks | 0 | | Open_files | 2 | | Open_streams | 0 | | Open_tables | 1 | | Opened_tables | 44600 | | Qcache_free_blocks | 36 | | Qcache_free_memory | 138488 | | Qcache_hits | 79570 | | Qcache_inserts | 27087 | | Qcache_lowmem_prunes | 3114 | | Qcache_not_cached | 22989 | | Qcache_queries_in_cache | 415 | | Qcache_total_blocks | 912 | | Questions | 2026873 | | Select_full_join | 0 | | Select_full_range_join | 0 | | Select_range | 99646 | | Select_range_check | 0 | | Select_scan | 30802 | | Slave_open_temp_tables | 0 | | Slave_running | OFF | | Slow_launch_threads | 0 | | Slow_queries | 0 | | Sort_merge_passes | 30 | | Sort_range | 500 | | Sort_rows | 30296250 | | Sort_scan | 4650 | | Table_locks_immediate | 1920382 | | Table_locks_waited | 0 | | Threads_cached | 0 | | Threads_connected | 1 | | Threads_created | 30022 | | Threads_running | 1 | | Uptime | 80380 | +--------------------------+------------+
Many status variables are reset to 0 by the FLUSH STATUS statement.
The status variables have the following meanings. The Com_xxx
statement counter variables were added beginning with MySQL 3.23.47. The
Qcache_xxx query cache variables were added beginning with MySQL
4.0.1. Otherwise, variables with no version indicated have been present since
at least MySQL 3.22.
Aborted_clients
Aborted_connects
Binlog_cache_disk_use
binlog_cache_size and used a temporary file to
store statements from the transaction.
This variable was added in MySQL 4.1.2.
Binlog_cache_use
Bytes_received
Bytes_sent
Com_xxx
Com_delete and Com_insert count DELETE and INSERT
statements.
Connections
Created_tmp_disk_tables
Created_tmp_files
mysqld has created.
This variable was added in MySQL 3.23.28.
Created_tmp_tables
Created_tmp_disk_tables is big, you may want to increase the
tmp_table_size value to cause temporary tables to be memory-based
instead of disk-based.
Delayed_errors
INSERT DELAYED for which some error
occurred (probably duplicate key).
Delayed_insert_threads
INSERT DELAYED handler threads in use.
Delayed_writes
INSERT DELAYED rows written.
Flush_commands
FLUSH statements.
Handler_commit
COMMIT statements.
This variable was added in MySQL 4.0.2.
Handler_discover
NDB Cluster storage engine if it knows about
a table with a given name. This is called discovery. Handler_discover
indicates the number of time tables have been discovered.
This variable was added in MySQL 4.1.2.
Handler_delete
Handler_read_first
SELECT col1 FROM foo, assuming that col1 is indexed.
Handler_read_key
Handler_read_next
Handler_read_prev
ORDER BY ... DESC.
This variable was added in MySQL 3.23.6.
Handler_read_rnd
Handler_read_rnd_next
Handler_rollback
ROLLBACK statements.
This variable was added in MySQL 4.0.2.
Handler_update
Handler_write
Innodb_buffer_pool_pages_data
Innodb_buffer_pool_pages_dirty
Innodb_buffer_pool_pages_flushed
Innodb_buffer_pool_pages_free
Innodb_buffer_pool_pages_latched
InnoDB buffer pool. These are pages
currently being read or written or that can't be flushed or removed
for some other reason.
Added in MySQL 5.0.2.
Innodb_buffer_pool_pages_misc
Innodb_buffer_pool_pages_total
- Innodb_buffer_pool_pages_free
- Innodb_buffer_pool_pages_data.
Added in MySQL 5.0.2.
Innodb_buffer_pool_pages_total
Innodb_buffer_pool_read_ahead_rnd
InnoDB initiated. This happens
when a query is to scan a large portion of a table but in random order.
Added in MySQL 5.0.2.
Innodb_buffer_pool_read_ahead_seq
InnoDB initiated. This happens when
InnoDB does a sequential full table scan.
Added in MySQL 5.0.2.
Innodb_buffer_pool_read_requests
InnoDB has done.
Added in MySQL 5.0.2.
Innodb_buffer_pool_reads
InnoDB could not satisfy from
buffer pool and had to do a single-page read.
Added in MySQL 5.0.2.
Innodb_buffer_pool_wait_free
InnoDB buffer pool happen in the background.
However, if it's necessary to read or create a page and no clean pages are
available, it's necessary to wait for pages to be flushed first.
This counter counts instances of these waits.
If the buffer pool size was set properly, this value should be small.
Added in MySQL 5.0.2.
Innodb_buffer_pool_write_requests
InnoDB buffer pool.
Added in MySQL 5.0.2.
Innodb_data_fsyncs
fsync() operations so far.
Added in MySQL 5.0.2.
Innodb_data_pending_fsyncs
fsync() operations.
Added in MySQL 5.0.2.
Innodb_data_pending_reads
Innodb_data_pending_writes
Innodb_data_read
Innodb_data_reads
Innodb_data_writes
Innodb_data_written
Innodb_dblwr_writes
Innodb_dblwr_pages_written
Innodb_log_waits
Innodb_log_write_requests
Innodb_log_writes
Innodb_os_log_fsyncs
Innodb_os_log_pending_fsyncs
Innodb_os_log_pending_writes
Innodb_os_log_written
Innodb_page_size
InnoDB page size (default 16KB). Many values are
counted in pages; the page size allows them to be easily converted to bytes.
Added in MySQL 5.0.2.
Innodb_pages_created
Innodb_pages_read
Innodb_pages_written
Innodb_row_lock_current_waits
Innodb_row_lock_time
Innodb_row_lock_time_avg
Innodb_row_lock_time_max
Innodb_row_lock_waits
Innodb_rows_deleted
InnoDB tables.
Added in MySQL 5.0.2.
Innodb_rows_inserted
InnoDB tables.
Added in MySQL 5.0.2.
Innodb_rows_read
InnoDB tables.
Added in MySQL 5.0.2.
Innodb_rows_updated
InnoDB tables.
Added in MySQL 5.0.2.
Key_blocks_not_flushed
Not_flushed_key_blocks.
Key_blocks_unused
key_buffer_size in
section 5.2.3 Server System Variables.
This variable was added in MySQL 4.1.2.
section 5.2.3 Server System Variables.
Key_blocks_used
Key_read_requests
Key_reads
Key_reads is big, then your key_buffer_size value is
probably too small. The cache miss rate can be calculated as
Key_reads/Key_read_requests.
Key_write_requests
Key_writes
Last_query_cost
Max_used_connections
Not_flushed_delayed_rows
INSERT DELAY queues.
Not_flushed_key_blocks
Key_blocks_not_flushed before MySQL 4.1.1.
Open_files
Open_streams
Open_tables
Opened_tables
Opened_tables is big, your table_cache
value is probably too small.
Qcache_free_blocks
Qcache_free_memory
Qcache_hits
Qcache_inserts
Qcache_lowmem_prunes
Qcache_not_cached
query_cache_type).
Qcache_queries_in_cache
Qcache_total_blocks
Questions
Rpl_status
Select_full_join
Select_full_range_join
Select_range
Select_range_check
Select_scan
Slave_open_temp_tables
Slave_running
ON if this server is a slave that is connected to a master.
This variable was added in MySQL 3.23.16.
Slave_retried_transactions
Slow_launch_threads
slow_launch_time
seconds to create.
This variable was added in MySQL 3.23.15.
Slow_queries
long_query_time seconds. See section 5.9.5 The Slow Query Log.
Sort_merge_passes
sort_buffer_size
system variable.
This variable was added in MySQL 3.23.28.
Sort_range
Sort_rows
Sort_scan
Ssl_xxx
Table_locks_immediate
Table_locks_waited
Threads_cached
Threads_connected
Threads_created
Threads_created is big, you may want to increase the
thread_cache_size value. The cache hit rate can be calculated
as Threads_created/Connections.
This variable was added in MySQL 3.23.31.
Threads_running
Uptime
The server shutdown process can be summarized like this:
A more detailed description of the process follows:
SHUTDOWN privilege can execute a mysqladmin shutdown
command. mysqladmin can be used on any platform supported by
MySQL. Other operating system-specific shutdown initiation methods are possible
as well: The server shuts down on Unix when it receives a SIGTERM
signal. A server running as a service on Windows shuts down when the services
manager tells it to.
SIGTERM signal, the signal thread might handle shutdown itself, or it
might create a separate thread to do so. If the server tries to create a
shutdown thread and cannot (for example, if memory is exhausted), it issues a
diagnostic message that appears in the error log:
Error: Can't create thread to kill server
KILL Syntax, in particular for the
instructions about killed REPAIR TABLE or OPTIMIZE TABLE
operations on MyISAM tables.
For threads that have an open transaction, the transaction is rolled back.
Note that if a thread is updating a non-transactional table, an operation
such as a multiple-row UPDATE or INSERT may leave the table
partially updated, because the operation can terminate before completion.
If the server is a master replication server, threads associated with
currently connected slaves are treated like other client threads. That
is, each one is marked as killed and exits when it next checks its state.
If the server is a slave replication server, the I/O and SQL threads, if
active, are stopped before client threads are marked as killed. The SQL
thread is allowed to finish its current statement (to avoid causing
replication problems) then stops. If the SQL thread was in the middle
of a transaction at this point, the transaction is rolled back.
This section describes some general security issues to be aware of and what you can do to make your MySQL installation more secure against attack or misuse. For information specifically about the access control system that MySQL uses for setting up user accounts and checking database access, see section 5.5 The MySQL Access Privilege System.
Anyone using MySQL on a computer connected to the Internet should read this section to avoid the most common security mistakes.
In discussing security, we emphasize the necessity of fully protecting the entire server host (not just the MySQL server) against all types of applicable attacks: eavesdropping, altering, playback, and denial of service. We do not cover all aspects of availability and fault tolerance here.
MySQL uses security based on Access Control Lists (ACLs) for all connections, queries, and other operations that users can attempt to perform. There is also some support for SSL-encrypted connections between MySQL clients and servers. Many of the concepts discussed here are not specific to MySQL at all; the same general ideas apply to almost all applications.
When running MySQL, follow these guidelines whenever possible:
root accounts) access
to the user table in the mysql database! This is critical.
The encrypted password is the real password in MySQL. Anyone who
knows the password that is listed in the user table and has access
to the host listed for the account can easily log in as that user.
GRANT and
REVOKE statements are used for controlling access to MySQL. Do
not grant any more privileges than necessary. Never grant privileges to all
hosts.
Checklist:
mysql -u root. If you are able to connect successfully to the
server without being asked for a password, you have problems. Anyone
can connect to your MySQL server as the MySQL
root user with full privileges!
Review the MySQL installation instructions, paying particular
attention to the information about setting a root password.
See section 2.9.3 Securing the Initial MySQL Accounts.
SHOW GRANTS statement and check to see who has access to
what. Then use the REVOKE statement to remove those privileges that
are not necessary.
MD5(), SHA1(), or
some other one-way hashing function.
nmap. MySQL uses port 3306 by default. This port should
not be accessible from untrusted hosts. Another simple way to check whether
or not your MySQL port is open is to try the following command
from some remote machine, where server_host is the host on which
your MySQL server runs:
shell> telnet server_host 3306If you get a connection and some garbage characters, the port is open, and should be closed on your firewall or router, unless you really have a good reason to keep it open. If
telnet just hangs or the
connection is refused, everything is OK; the port is blocked.
; DROP
DATABASE mysql;''. This is an extreme example, but large security leaks
and data loss might occur as a result of hackers using similar techniques,
if you do not prepare for them.
A common mistake is to protect only string data values. Remember to check
numeric data as well. If an application generates a query such as
SELECT * FROM table WHERE ID=234 when a user enters the value
234, the user can enter the value 234 OR 1=1 to cause the
application to generate the query SELECT * FROM table WHERE ID=234 OR
1=1. As a result, the server retrieves every record in the table. This
exposes every record and causes excessive server load. The simplest way to
protect from this type of attack is to use apostrophes around the numeric
constants: SELECT * FROM table WHERE ID='234'. If the user enters
extra information, it all becomes part of the string. In numeric context,
MySQL automatically converts this string to a number and strips any trailing
non-numeric characters from it.
Sometimes people think that if a database contains only publicly available
data, it need not be protected. This is incorrect. Even if it is allowable
to display any record in the database, you should still protect against
denial of service attacks (for example, those that are based on the
technique in the preceding paragraph that causes the server to waste
resources). Otherwise, your server becomes unresponsive to legitimate users.
Checklist:
%22 (`"'), %23
(`#'), and %27 (`'') in the URL.
mysql_real_escape_string() API call.
escape and quote modifiers for query streams.
mysql_escape_string() function, which
is based on the function of the same name in the MySQL C API.
Prior to PHP 4.0.3, use addslashes() instead.
quote() method or use placeholders.
PreparedStatement object and placeholders.
tcpdump and strings utilities. For most cases,
you can check whether MySQL data streams are unencrypted
by issuing a command like the following:
shell> tcpdump -l -i eth0 -w - src or dst port 3306 | strings(This works under Linux and should work with small modifications under other systems.) Warning: If you do not see plaintext data, this doesn't always mean that the information actually is encrypted. If you need high security, you should consult with a security expert.
When you connect to a MySQL server, you should use a password. The password is not transmitted in clear text over the connection. Password handling during the client connection sequence was upgraded in MySQL 4.1.1 to be very secure. If you are using an older version of MySQL, or are still using pre-4.1.1-style passwords, the encryption algorithm is less strong and with some effort a clever attacker who can sniff the traffic between the client and the server can crack the password. (See section 5.5.9 Password Hashing in MySQL 4.1 for a discussion of the different password handling methods.) If the connection between the client and the server goes through an untrusted network, you should use an SSH tunnel to encrypt the communication.
All other information is transferred as text that can be read by anyone who is able to watch the connection. If you are concerned about this, you can use the compressed protocol (in MySQL 3.22 and above) to make traffic much more difficult to decipher. To make the connection even more secure, you should use SSH to get an encrypted TCP/IP connection between a MySQL server and a MySQL client. You can find an Open Source SSH client at http://www.openssh.org/, and a commercial SSH client at http://www.ssh.com/.
If you are using MySQL 4.0 or newer, you can also use internal OpenSSL support. See section 5.6.7 Using Secure Connections.
To make a MySQL system secure, you should strongly consider the following suggestions:
mysql program to connect as any other
person simply by invoking it as mysql -u other_user db_name if
other_user has no password. If all users have a password,
connecting using another user's account becomes much more difficult.
To change the password for a user, use the SET PASSWORD statement.
It is also possible to update the user table in the mysql
database directly. For example, to change the password of all MySQL accounts
that have a username of root, do this:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password=PASSWORD('newpwd')
-> WHERE User='root';
mysql> FLUSH PRIVILEGES;
root user. This is
very dangerous, because any user with the FILE privilege is able
to create files as root (for example, ~root/.bashrc). To
prevent this, mysqld refuses to run as root unless that
is specified explicitly using a --user=root option.
mysqld can be run as an ordinary unprivileged user instead.
You can also create a separate Unix account named mysql to make
everything even more secure. Use the account only for administering MySQL.
To start mysqld as another Unix user, add a user
option that specifies the username to the [mysqld] group of the
`/etc/my.cnf' option file or the `my.cnf' option file in the
server's data directory. For example:
[mysqld] user=mysqlThis causes the server to start as the designated user whether you start it manually or by using
mysqld_safe or mysql.server.
For more details, see section A.3.2 How to Run MySQL as a Normal User.
Running mysqld as a Unix user other than root does not
mean that you need to change the root username in the user
table. Usernames for MySQL accounts have nothing to do with usernames for Unix
accounts.
--skip-symbolic-links option.) This is especially important if you run
mysqld as root, because anyone that has write access to the
server's data directory then could delete any file in the system!
See section 7.6.1.2 Using Symbolic Links for Tables on Unix.
mysqld runs as.
PROCESS or SUPER privilege to non-administrative users.
The output of mysqladmin processlist shows the text of the currently
executing queries, so any user who is allowed to execute that command
might be able to see if another user issues an UPDATE user SET
password=PASSWORD('not_secure') query.
mysqld reserves an extra connection for users who have the
SUPER privilege (PROCESS before MySQL 4.0.2), so that a MySQL
root user can log in and check server activity even if all normal
connections are in use.
The SUPER privilege
can be used to terminate client connections, change server operation by
changing the value of system variables, and control replication servers.
FILE privilege to non-administrative users.
Any user that has this privilege can write a file anywhere in the
filesystem with the privileges of the mysqld daemon! To make
this a bit safer, files generated with SELECT ... INTO OUTFILE
do not overwrite existing files and are writable by everyone.
The FILE privilege may also be used to read any file that is
world-readable or accessible to the Unix user that the server runs as.
With this privilege, you can read any file into a database table.
This could be abused, for example, by using LOAD DATA to load
`/etc/passwd' into a table, which then can be displayed with
SELECT.
max_user_connections variable in
mysqld.
The GRANT statement also supports resource control options for limiting
the extent of server use allowed to an account.
mysqld Concerning Security
The following mysqld options affect security:
--allow-suspicious-udfs
xxx symbol for the main function can be loaded. By default, the
option is off and only UDFs that have at least one auxiliary symbol can be
loaded. This prevents attempts at loading functions from shared object files
other than those containing legitimate UDFs. This option was added in MySQL
4.0.24, 4.1.10a, and 5.0.3.
See section 25.2.3.6 User-defined Function Security Precautions.
--local-infile[={0|1}]
--local-infile=0, clients cannot use
LOCAL in LOAD DATA statements.
See section 5.4.4 Security Issues with LOAD DATA LOCAL.
--old-passwords
--safe-show-database
SHOW DATABASES statement displays the names
of only those databases for which the user has some kind of privilege.
As of MySQL 4.0.2, this option is deprecated and doesn't do anything
(it is enabled by default), because there is a SHOW DATABASES
privilege that can be used to control access to database
names on a per-account basis. See section 13.5.1.3 GRANT and REVOKE Syntax.
--safe-user-create
GRANT
statement unless the user has the INSERT privilege for the
mysql.user table. If you want a user to have the ability to create
new users with those privileges that the user has right to grant, you should
grant the user the following privilege:
mysql> GRANT INSERT(user) ON mysql.user TO 'user_name'@'host_name';This ensures that the user can't change any privilege columns directly, but has to use the
GRANT statement to give privileges to other users.
--secure-auth
--skip-grant-tables
mysqladmin
flush-privileges or mysqladmin reload command, or by issuing a
FLUSH PRIVILEGES statement.)
--skip-name-resolve
Host column values in the grant
tables must be IP numbers or localhost.
--skip-networking
mysqld must be made via Unix socket files.
This option is unsuitable when using a MySQL version prior to 3.23.27 with
the MIT-pthreads package, because Unix socket files were not supported by
MIT-pthreads at that time.
--skip-show-database
SHOW DATABASES statement is allowed only to
users who have the SHOW DATABASES privilege, and the statement
displays all database names. Without this option, SHOW DATABASES is
allowed to all users, but displays each database name only if the user has
the SHOW DATABASES privilege or some privilege for the database.
LOAD DATA LOCAL
The LOAD DATA statement can load a file that is located on the
server host, or it can load a file that is located on the client host when
the LOCAL keyword is specified.
There are two potential security issues with supporting the LOCAL
version of LOAD DATA statements:
LOAD DATA statement. Such a
server could access any file on the client host to which the client user has
read access.
LOAD DATA LOCAL to read any files
that the Web server process has read access to (assuming that a user could
run any command against the SQL server). In this environment, the client with
respect to the MySQL server actually is the Web server, not the program being
run by the user connecting to the Web server.
To deal with these problems, we changed how LOAD DATA
LOCAL is handled as of MySQL 3.23.49 and MySQL 4.0.2 (4.0.13 on Windows):
--enable-local-infile option, to be compatible
with MySQL 3.23.48 and before.
--enable-local-infile
option to configure, LOAD DATA LOCAL cannot be used
by any client unless it is written explicitly to invoke
mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0).
See section 22.2.3.43 mysql_options().
LOAD DATA LOCAL commands from the server side
by starting mysqld with the --local-infile=0 option.
mysql command-line client, LOAD DATA LOCAL can be
enabled by specifying the --local-infile[=1] option, or disabled with
the --local-infile=0 option. Similarly, for mysqlimport,
the --local or -L option enables local data file loading. In
any case, successful use of a local loading operation requires that the
server is enabled to allow it.
LOAD DATA LOCAL in Perl scripts or other programs that
read the [client] group from option files, you can add the
local-infile=1 option to that group. However, to keep this from
causing problems for programs that do not understand local-infile,
specify it using the loose- prefix:
[client] loose-local-infile=1The
loose- prefix can be used as of MySQL 4.0.2.
LOAD DATA LOCAL INFILE is disabled, either in the server or
the client, a client that attempts to issue such a statement receives the
following error message:
ERROR 1148: The used command is not allowed with this MySQL version
MySQL has an advanced but non-standard security and privilege system. This section describes how it works.
The primary function of the MySQL privilege system is to
authenticate a user connecting from a given host, and to associate that user
with privileges on a database such as
SELECT, INSERT, UPDATE, and DELETE.
Additional functionality includes the ability to have anonymous users and
to grant privileges for MySQL-specific functions such as LOAD
DATA INFILE and administrative operations.
The MySQL privilege system ensures that all users may perform only the operations allowed to them. As a user, when you connect to a MySQL server, your identity is determined by the host from which you connect and the username you specify. When you issue requests after connecting, the system grants privileges according to your identity and what you want to do.
MySQL considers both your hostname and username in identifying you
because there is little reason to assume that a given username belongs to
the same person everywhere on the Internet. For example, the user
joe who connects from office.com need not be the same
person as the user joe who connects from elsewhere.com.
MySQL handles this by allowing you to distinguish users on different
hosts that happen to have the same name: You can grant one set of
privileges for connections by joe from office.com, and a
different set of privileges for connections by joe from
elsewhere.com.
MySQL access control involves two stages:
SELECT
privilege for the table or the DROP privilege for the database.
If your privileges are changed (either by yourself or someone else) while you are connected, those changes do not necessarily take effect immediately for the next statement you issue. See section 5.5.7 When Privilege Changes Take Effect for details.
The server stores privilege information in the grant tables of the
mysql database (that is, in the database named mysql).
The MySQL server reads the contents of these tables into memory when it
starts and re-reads them under the circumstances indicated in section 5.5.7 When Privilege Changes Take Effect. Access-control decisions are based on the in-memory copies of the
grant tables.
Normally, you manipulate the contents of the grant tables indirectly by using
the GRANT and REVOKE statements to set up accounts and control
the privileges available to each one.
See section 13.5.1.3 GRANT and REVOKE Syntax.
The discussion here describes the underlying structure of the grant tables and
how the server uses their contents when interacting with clients.
The server uses the user, db, and host tables in the
mysql database at both stages of access control. The columns in these
grant tables are shown here:
| Table Name | user | db | host |
| Scope columns | Host | Host | Host
|
User | Db | Db
| |
Password | User | ||
| Privilege columns | Select_priv | Select_priv | Select_priv
|
Insert_priv | Insert_priv | Insert_priv
| |
Update_priv | Update_priv | Update_priv
| |
Delete_priv | Delete_priv | Delete_priv
| |
Index_priv | Index_priv | Index_priv
| |
Alter_priv | Alter_priv | Alter_priv
| |
Create_priv | Create_priv | Create_priv
| |
Drop_priv | Drop_priv | Drop_priv
| |
Grant_priv | Grant_priv | Grant_priv
| |
Create_view_priv | Create_view_priv | Create_view_priv
| |
Show_view_priv | Show_view_priv | Show_view_priv
| |
Create_routine_priv | Create_routine_priv | ||
Alter_routine_priv | Alter_routine_priv | ||
References_priv | References_priv | References_priv
| |
Reload_priv | |||
Shutdown_priv | |||
Process_priv | |||
File_priv | |||
Show_db_priv | |||
Super_priv | |||
Create_tmp_table_priv | Create_tmp_table_priv | Create_tmp_table_priv
| |
Lock_tables_priv | Lock_tables_priv | Lock_tables_priv
| |
Execute_priv | |||
Repl_slave_priv | |||
Repl_client_priv | |||
| Security columns | ssl_type | @tab | |
ssl_cipher | |||
x509_issuer | |||
x509_subject | |||
| Resource control columns | max_questions | @tab | |
max_updates | |||
max_connections | |||
max_user_connections |
The
ssl_type,
ssl_cipher,
x509_issuer, and
x509_subject
columns were added in MySQL 4.0.0.
The
Create_tmp_table_priv,
Execute_priv,
Lock_tables_priv,
Repl_client_priv,
Repl_slave_priv,
Show_db_priv,
Super_priv,
max_questions,
max_updates, and
max_connections
columns were added in MySQL 4.0.2.
Execute_priv is not operational until MySQL 5.0.3, however.
The Create_view_priv and Show_view_priv columns were added in
MySQL 5.0.1.
The Create_routine_priv, Alter_routine_priv, and
max_user_connections columns were added in MySQL 5.0.3.
During the second stage of access control, the server performs request
verification to make sure that each client has sufficient privileges for
each request that it issues. In addition to the user, db, and
host grant tables, the server may also consult the tables_priv
and columns_priv tables for requests that involve tables. The
tables_priv and columns_priv tables provide finer privilege
control at the table and column levels. They have the following columns:
| Table Name | tables_priv | columns_priv |
| Scope columns | Host | Host
|
Db | Db
| |
User | User
| |
Table_name | Table_name
| |
Column_name
| ||
| Privilege columns | Table_priv | Column_priv
|
Column_priv | ||
| Other columns | Timestamp | Timestamp
|
Grantor |
The Timestamp and Grantor columns currently are unused and are
discussed no further here.
For verification of requests that involve stored routines, the server may
consult the procs_priv table. This table exists as of MySQL 5.0.3 and
has the following columns:
| Table Name | procs_priv |
| Scope columns | Host
|
Db
| |
User
| |
Routine_name
| |
| Privilege columns | Proc_priv
|
| Other columns | Timestamp
|
Grantor
|
The Timestamp and Grantor columns currently are unused and are
discussed no further here.
Each grant table contains scope columns and privilege columns:
user table row
with Host and User values of 'thomas.loc.gov' and
'bob' would be used for authenticating connections made to the server
from the host thomas.loc.gov by a client that specifies a username of
bob. Similarly, a db
table row with Host, User, and Db column values of
'thomas.loc.gov', 'bob' and 'reports' would be used when
bob connects from the host thomas.loc.gov to access the
reports database. The tables_priv and columns_priv
tables contain scope columns indicating tables or table/column combinations
to which each row applies. The procs_priv scope columns indicate the
store routine to which each row applies.
Scope columns contain strings. They are declared as shown here; the default value for each is the empty string:
| Column Name | Type |
Host | CHAR(60)
|
User | CHAR(16)
|
Password | CHAR(16)
|
Db | CHAR(64)
|
Table_name | CHAR(64)
|
Column_name | CHAR(64)
|
Routine_name | CHAR(64)
|
Before MySQL 3.23, the Db column is CHAR(32) in some tables
and CHAR(60) in others.
For access-checking purposes, comparisons of Host values are
case-insensitive. User, Password, Db, and
Table_name values are case sensitive. Column_name values are
case insensitive in MySQL 3.22.12 or later.
In the user, db, and host tables, each privilege
is listed in a separate column that is declared as
ENUM('N','Y') DEFAULT 'N'. In other words, each privilege can be disabled
or enabled, with the default being disabled.
In the tables_priv, columns_priv, and procs_priv
tables, the privilege columns are declared as SET columns. Values in
these columns can contain any combination of the privileges controlled by
the table:
| Table Name | Column Name | Possible Set Elements |
tables_priv
| Table_priv
| 'Select', 'Insert', 'Update', 'Delete', 'Create', 'Drop', 'Grant', 'References', 'Index', 'Alter'
|
tables_priv
| Column_priv
| 'Select', 'Insert', 'Update', 'References'
|
columns_priv
| Column_priv
| 'Select', 'Insert', 'Update', 'References'
|
procs_priv
| Proc_priv
| 'Execute', 'Alter Routine', 'Grant'
|
Briefly, the server uses the grant tables as follows:
user table scope columns determine whether to reject or allow
incoming connections. For allowed connections, any privileges granted in
the user table indicate the user's global (superuser) privileges.
These privileges apply to all databases on the server.
db table scope columns determine which users can access which
databases from which hosts. The privilege columns determine which operations
are allowed. A privilege granted at the database level applies to the database
and to all its tables.
host table is used in conjunction with the db table when you
want a given db table row to apply to several hosts. For example,
if you want a user to be able to use a database from several hosts in
your network, leave the Host value empty in the user's db table
row, then populate the host table with a row for each of those
hosts. This mechanism is described more detail in section 5.5.6 Access Control, Stage 2: Request Verification.
Note: The host table is not affected by the GRANT and
REVOKE statements. Most MySQL installations need not use this table at
all.
tables_priv and columns_priv tables are similar to
the db table, but are more fine-grained: They apply at the
table and column levels rather than at the database level.
A privilege granted at the table level applies to the table and to all its
columns.
A privilege granted at the column level applies only to a specific column.
procs_priv table applies to stored routines. A privilege granted at
the routine level applies only to a single routine.
Administrative privileges (such as RELOAD or SHUTDOWN)
are specified only in the user table. This is because
administrative operations are operations on the server itself and are not
database-specific, so there is no reason to list these privileges in the
other grant tables. In fact, to determine whether you can perform an
administrative operation, the server need consult only the user table.
The FILE privilege also is specified only in the user table.
It is not an administrative privilege as such, but your ability to read or
write files on the server host is independent of the database you are
accessing.
The mysqld server reads the contents of the grant tables into memory
when it starts. You can tell it to re-read the tables by issuing a FLUSH
PRIVILEGES statement or executing a mysqladmin flush-privileges or
mysqladmin reload command.
Changes to the grant tables take effect as indicated in
section 5.5.7 When Privilege Changes Take Effect.
When you modify the contents of the grant tables, it is a good idea to make
sure that your changes set up privileges the way you want. To check
the privileges for a given account, use the SHOW GRANTS statement.
For example, to determine the privileges that are granted to an account with
Host and User values of pc84.example.com and bob,
issue this statement:
mysql> SHOW GRANTS FOR 'bob'@'pc84.example.com';
A useful diagnostic tool is the mysqlaccess script, which Yves
Carlier has provided for the MySQL distribution. Invoke
mysqlaccess with the --help option to find out how it
works. Note that mysqlaccess checks access using only the
user, db, and host tables. It does not check table,
column, or routine privileges specified in the tables_priv,
columns_priv, or procs_priv tables.
For additional help in diagnosing privilege-related problems, see
section 5.5.8 Causes of Access denied Errors. For general advice on security issues, see
section 5.4 General Security Issues.
Information about account privileges is stored in the user,
db, host, tables_priv, columns_priv, and
procs_priv tables in the mysql database. The MySQL server
reads the contents of these tables into memory when it starts and re-reads
them under the circumstances indicated in section 5.5.7 When Privilege Changes Take Effect.
Access-control decisions are based on the in-memory copies of the grant
tables.
The names used in the GRANT and REVOKE statements to refer to
privileges are shown in the following table, along with the column name
associated with each privilege in the grant tables and the context in
which the privilege applies. Further information about the meaning of
each privilege may be found at section 13.5.1.3 GRANT and REVOKE Syntax.
| Privilege | Column | Context |
CREATE | Create_priv | databases, tables, or indexes |
DROP | Drop_priv | databases or tables |
GRANT | Grant_priv | databases, tables, or stored routines |
REFERENCES | References_priv | databases or tables |
ALTER | Alter_priv | tables |
DELETE | Delete_priv | tables |
INDEX | Index_priv | tables |
INSERT | Insert_priv | tables |
SELECT | Select_priv | tables |
UPDATE | Update_priv | tables |
CREATE VIEW | Create_view_priv | views |
SHOW VIEW | Show_view_priv | views |
ALTER ROUTINE | Alter_routine_priv | stored routines |
CREATE ROUTINE | Create_routine_priv | stored routines |
EXECUTE | Execute_priv | stored routines |
FILE | File_priv | file access on server host |
CREATE TEMPORARY TABLES | Create_tmp_table_priv | server administration |
LOCK TABLES | Lock_tables_priv | server administration |
CREATE USER | Create_user_priv | server administration |
PROCESS | Process_priv | server administration |
RELOAD | Reload_priv | server administration |
REPLICATION CLIENT | Repl_client_priv | server administration |
REPLICATION SLAVE | Repl_slave_priv | server administration |
SHOW DATABASES | Show_db_priv | server administration |
SHUTDOWN | Shutdown_priv | server administration |
SUPER | Super_priv | server administration |
The CREATE TEMPORARY TABLES, EXECUTE, LOCK TABLES,
REPLICATION CLIENT, REPLICATION SLAVE, SHOW DATABASES,
and SUPER privileges were added in MySQL 4.0.2. (EXECUTE is
not operational until MySQL 5.0.3.) CREATE VIEW and SHOW VIEW
were added in MySQL 5.0.1. CREATE USER, CREATE ROUTINE and
ALTER ROUTINE were added in MySQL 5.0.3. To use these privileges when
upgrading from an earlier version of MySQL that does not have them, you must
upgrade your grant tables. See section 2.10.7 Upgrading the Grant Tables.
The CREATE and DROP privileges allow you to create new
databases and tables, or to drop (remove) existing databases and tables.
If you grant the DROP privilege for the mysql
database to a user, that user can drop the database in which the
MySQL access privileges are stored!
The SELECT, INSERT, UPDATE, and DELETE
privileges allow you to perform operations on rows in existing tables in
a database.
SELECT statements require the SELECT privilege only if they
actually retrieve rows from a table. Some SELECT statements do not
access tables and can be executed without permission for any database.
For example, you can use the mysql client as a simple calculator
to evaluate expressions that make no reference to tables:
mysql> SELECT 1+1; mysql> SELECT PI()*2;
The INDEX privilege allows you to create or drop (remove) indexes.
INDEX applies to existing tables.
If you have the CREATE privilege for a table, you can include index
definitions in the CREATE TABLE statement.
The ALTER privilege allows you to use ALTER TABLE to change the
structure of or rename tables.
The CREATE ROUTINE privilege is needed for creating stored routines
(functions and procedures). ALTER ROUTINE privilege is needed for
altering or dropping stored routines, and EXECUTE is needed for
executing stored routines.
The GRANT privilege allows you to give to other users those
privileges that you yourself possess. It can be used for databases, tables, and
stored routines.
The FILE privilege gives you permission to read and write files on
the server host using the LOAD DATA INFILE and SELECT ... INTO
OUTFILE statements. A user who has the FILE privilege can read any
file on the server host that is either world-readable or readable by the MySQL
server. (This implies the user can read any file in any database
directory, because the server can access any of those files.)
The FILE privilege also allows the user to create new files in any
directory where the MySQL server has write access. Existing files cannot be
overwritten.
The remaining privileges are used for administrative operations. Many of
them can be performed by using the mysqladmin program or by
issuing SQL statements. The following table shows which mysqladmin
commands each administrative privilege allows you to execute:
| Privilege | Commands Permitted to Privilege Holders |
RELOAD | flush-hosts, flush-logs, flush-privileges, flush-status, flush-tables, flush-threads, refresh, reload
|
SHUTDOWN | shutdown
|
PROCESS | processlist
|
SUPER | kill
|
The reload command tells the server to re-read the grant tables
into memory. flush-privileges is a synonym for reload.
The refresh command closes and reopens the log files and flushes
all tables. The other flush-xxx commands perform functions similar to
refresh, but are more specific and may be preferable in some instances.
For example, if you want to flush just the log files, flush-logs
is a better choice than refresh.
The shutdown command shuts down the server. This command can be issued
only from mysqladmin. There is no corresponding SQL statement.
The processlist command displays information about the threads
executing within the server (that is, about the statements being executed by
clients associated with other accounts).
The kill command terminates server threads.
You can always display or kill your own threads, but you need the
PROCESS privilege to display threads initiated by other users and
the SUPER privilege to kill them.
See section 13.5.5.3 KILL Syntax. Prior to MySQL 4.0.2 when SUPER was
introduced, the PROCESS privilege controls the ability to both see and
terminate threads for other clients.
The CREATE TEMPORARY TABLES privilege allows the use of the keyword
TEMPORARY in CREATE TABLE statements.
The LOCK TABLES privilege allows the use of explicit LOCK TABLES
statements to lock tables for which you have the SELECT privilege.
This includes the use of write locks, which prevents anyone else from reading
the locked table.
The REPLICATION CLIENT privilege allows the use of SHOW MASTER
STATUS and SHOW SLAVE STATUS.
The REPLICATION SLAVE privilege should be granted to accounts that are
used by slave servers to connect to the current server as their master.
Without this privilege, the slave cannot request updates that have been made
to databases on the master server.
The SHOW DATABASES privilege allows the account to see database names
by issuing the SHOW DATABASE statement. Accounts that do not have this
privilege see only databases for which they have some privileges, and cannot
use the statement at all if the server was started with the
--skip-show-database option.
It is a good idea in general to grant to an account only those privileges
that it needs. You should exercise particular caution in granting the
FILE and administrative privileges:
FILE privilege can be abused to read into a database table any
files that the MySQL server can read on the server host. This includes all
world-readable files and files in the server's data directory. The table
can then be accessed using SELECT to transfer its contents to the
client host.
GRANT privilege allows users to give their privileges to
other users. Two users with different privileges and with the GRANT
privilege are able to combine privileges.
ALTER privilege may be used to subvert the privilege system
by renaming tables.
SHUTDOWN privilege can be abused to deny service to other
users entirely by terminating the server.
PROCESS privilege can be used to view the plain text of
currently executing queries, including queries that set or change passwords.
SUPER privilege can be used to terminate other clients or change
how the server operates.
mysql database itself can be used to
change passwords and other access privilege information. Passwords are
stored encrypted, so a malicious user cannot simply read them to know the
plain text password. However, a user with write access to the user
table Password column can change an account's password, and then
connect to the MySQL server using that account.
There are some things that you cannot do with the MySQL privilege system:
MySQL client programs generally expect you to specify connection parameters when you want to access a MySQL server:
For example, the
mysql client can be started as follows from a command-line prompt
(indicated here by shell>):
shell> mysql -h host_name -u user_name -pyour_pass
Alternate forms of the -h, -u, and -p options are
--host=host_name, --user=user_name, and
--password=your_pass. Note that there is no space between
-p or --password= and the password following it.
If you use a -p or --password option but do not specify the
password value, the client program prompts you to enter the password.
The password is not displayed as you enter it.
This is more secure than giving the password on the command line.
Any user on your system may be able to see a password specified on the command
line by executing a command such as ps auxww.
See section 5.6.6 Keeping Your Password Secure.
MySQL client programs use default values for any connection parameter option that you do not specify:
localhost.
ODBC on Windows and your Unix login name
on Unix.
-p is missing.
Thus, for a Unix user with a login name of joe, all of the following
commands are equivalent:
shell> mysql -h localhost -u joe shell> mysql -h localhost shell> mysql -u joe shell> mysql
Other MySQL clients behave similarly.
You can specify different default values to be used when you make a connection so that you need not enter them on the command line each time you invoke a client program. This can be done in a couple of ways:
[client] section of an
option file. The relevant section of the file might look like this:
[client] host=host_name user=user_name password=your_passOption files are discussed further in section 4.3.2 Using Option Files.
mysql using MYSQL_HOST. The
MySQL username can be specified using USER (this is for
Windows and NetWare only). The password can be specified using
MYSQL_PWD,
although this is insecure; see section 5.6.6 Keeping Your Password Secure.
For a list of variables, see section F Environment Variables.
When you attempt to connect to a MySQL server, the server accepts or rejects the connection based on your identity and whether you can verify your identity by supplying the correct password. If not, the server denies access to you completely. Otherwise, the server accepts the connection, then enters Stage 2 and waits for requests.
Your identity is based on two pieces of information:
Identity checking is performed using the three user table scope columns
(Host, User, and Password). The server accepts the
connection only if the Host and User columns in some
user table record match the client hostname and username,
and the client supplies the password specified in that record.
Host values in the user table may be specified as follows:
Host value may be a hostname or an IP number, or 'localhost'
to indicate the local host.
Host
column values.
These have the same meaning as for pattern-matching operations
performed with the LIKE operator.
For example, a Host value of '%' matches any hostname, whereas a
value of '%.mysql.com' matches any host in the mysql.com domain.
Host values specified as
IP numbers, you can specify a netmask indicating how many address bits to
use for the network number. For example:
mysql> GRANT ALL PRIVILEGES ON db.*
-> TO david@'192.58.197.0/255.255.255.0';
This allows david to connect from any client host having an IP number
client_ip for which the following condition is true:
client_ip & netmask = host_ipThat is, for the
GRANT statement just shown:
client_ip & 255.255.255.0 = 192.58.197.0IP numbers that satisfy this condition and can connect to the MySQL server are those that lie in the range from
192.58.197.0 to
192.58.197.255.
Host value in a db table record means that its
privileges should be combined with those in the row in the host
table that matches the client hostname. The privileges are combined
using an AND (intersection) operation, not OR (union). You can find more
information about the host table in section 5.5.6 Access Control, Stage 2: Request Verification.
A blank Host value in the other grant tables is the same as '%'.
Because you can use IP wildcard values in the Host column
(for example, '144.155.166.%' to match every host on a
subnet), someone could try to exploit this capability by naming a host
144.155.166.somewhere.com. To foil such attempts, MySQL disallows
matching on hostnames that start with digits and a dot. Thus, if you have
a host named something like 1.2.foo.com, its name never matches
the Host column of the grant tables. An IP wildcard value can
match only IP numbers, not hostnames.
In the User column, wildcard characters are not allowed, but you can
specify a blank value, which matches any name. If the user table
row that matches an incoming connection has a blank username, the user is
considered to be an anonymous user with no name, not a user with the
name that the client actually specified. This means that a blank username
is used for all further access checking for the duration of the connection
(that is, during Stage 2).
The Password column can be blank. This is not a wildcard and does
not mean that any password matches. It means that the user must connect
without specifying a password.
Non-blank Password values in the user table represent
encrypted passwords. MySQL does not store passwords in plaintext form for
anyone to see. Rather, the password supplied by a user who is attempting to
connect is encrypted (using the PASSWORD() function). The encrypted
password then is used during the connection process when checking whether
the password is correct. (This is done without the encrypted password ever
traveling over the connection.) From MySQL's point of view, the
encrypted password is the REAL password, so you should not give anyone
access to it! In particular, don't give non-administrative users read
access to the tables in the mysql database!
From version 4.1 on, MySQL employs a stronger authentication method that has
better password protection during the connection process than in earlier
versions. It is secure even if TCP/IP packets are sniffed or the
mysql database is captured. Password encryption is discussed further
in section 5.5.9 Password Hashing in MySQL 4.1.
The following examples show how various combinations of Host and
User values in the user table apply to incoming
connections:
Host Value | User Value | Connections Matched by Entry |
'thomas.loc.gov' | 'fred' | fred, connecting from thomas.loc.gov
|
'thomas.loc.gov' | '' | Any user, connecting from thomas.loc.gov
|
'%' | 'fred' | fred, connecting from any host
|
'%' | '' | Any user, connecting from any host |
'%.loc.gov' | 'fred' | fred, connecting from any host in the loc.gov domain
|
'x.y.%' | 'fred' | fred, connecting from x.y.net, x.y.com, x.y.edu, and so on. (this is probably not useful)
|
'144.155.166.177' | 'fred' | fred, connecting from the host with IP address 144.155.166.177
|
'144.155.166.%' | 'fred' | fred, connecting from any host in the 144.155.166 class C subnet
|
'144.155.166.0/255.255.255.0' | 'fred' | Same as previous example |
It is possible for the client hostname and username of
an incoming connection to match more than one row in the
user table. The preceding set of examples demonstrates this:
Several of the entries shown match a connection from thomas.loc.gov by
fred.
When multiple matches are possible, the server must determine which of them to use. It resolves this issue as follows:
user table into memory, it sorts the
entries.
To see how this works, suppose that the user table looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | % | root | ... | % | jeffrey | ... | localhost | root | ... | localhost | | ... +-----------+----------+-
When the server reads in the table, it orders the entries with the
most-specific Host values first. Literal hostnames and IP numbers
are the most specific. The pattern '%' means ``any host'' and is
least specific. Entries with the same Host value are ordered with
the most-specific User values first (a blank User value means
``any user'' and is least specific). For the user table just shown,
the result after sorting looks like this:
+-----------+----------+- | Host | User | ... +-----------+----------+- | localhost | root | ... | localhost | | ... | % | jeffrey | ... | % | root | ... +-----------+----------+-
When a client attempts to connect, the server looks through the sorted entries
and uses the first match found. For a connection from localhost by
jeffrey, two of the entries in the table match:
the one with Host and User values of 'localhost' and
'', and the one with values of '%' and 'jeffrey'.
The 'localhost' row appears first in sorted order, so that is the one
the server uses.
Here is another example. Suppose that the user table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | % | jeffrey | ... | thomas.loc.gov | | ... +----------------+----------+-
The sorted table looks like this:
+----------------+----------+- | Host | User | ... +----------------+----------+- | thomas.loc.gov | | ... | % | jeffrey | ... +----------------+----------+-
A connection by jeffrey from thomas.loc.gov is matched by the
first row, whereas a connection by jeffrey from whitehouse.gov
is matched by the second.
It is a common misconception to think that, for a given username, all entries
that explicitly name that user are used first when the server attempts to
find a match for the connection. This is simply not true. The previous
example illustrates this, where a connection from thomas.loc.gov by
jeffrey is first matched not by the row containing 'jeffrey'
as the User column value, but by the row with no username.
As a result, jeffrey is authenticated as an anonymous user, even
though he specified a username when connecting.
If you are able to connect to the server, but your privileges are not
what you expect, you probably are being authenticated as some other
account. To find out what account the server used to authenticate
you, use the CURRENT_USER() function. It returns a value in
user_name@host_name format that indicates the User
and Host values from the matching user table record.
Suppose that jeffrey connects and issues the following query:
mysql> SELECT CURRENT_USER(); +----------------+ | CURRENT_USER() | +----------------+ | @localhost | +----------------+
The result shown here indicates that the matching user table row
had a blank User column value. In other words, the server is
treating jeffrey as an anonymous user.
The CURRENT_USER() function is available as of MySQL 4.0.6.
See section 12.8.3 Information Functions.
Another thing you can do to diagnose authentication problems is to print
out the user table and sort it by hand to see where the first
match is being made.
Once you establish a connection, the server enters Stage 2 of access
control. For each request that comes in on the connection, the server
determines what operation you want to perform, then checks whether you have
sufficient privileges to do so. This is where the privilege columns in the
grant tables come into play. These privileges can come from any of the
user, db, host, tables_priv, or
columns_priv tables. (You may find it helpful to refer to
section 5.5.2 How the Privilege System Works, which lists the columns present in each of the grant
tables.)
The user table grants privileges that are assigned to you on a global
basis and that apply no matter what the current database is. For example, if
the user table grants you the DELETE privilege, you can
delete rows from any table in any database on the server host! In other words,
user table privileges are superuser privileges. It is wise to grant
privileges in the user table only to superusers such as
database administrators. For other users, you should leave the privileges
in the user table set to 'N' and grant privileges at more
specific levels only. You can grant privileges for particular databases,
tables, or columns.
The db and host tables grant database-specific privileges.
Values in the scope columns of these tables can take the following forms:
Host
and Db columns of either table. These have the same meaning as for
pattern-matching operations performed with the LIKE operator. If you
want to use either character literally when granting privileges, you must
escape it with a backslash. For example, to include `_' character
as part of a database name, specify it as `\_' in the GRANT
statement.
'%' Host value in the db table means ``any host.'' A
blank Host value in the db table means ``consult the
host table for further information'' (a process that is described later
in this section).
'%' or blank Host value in the host table means ``any
host.''
'%' or blank Db value in either table means ``any database.''
User value in either table matches the anonymous user.
The server reads in and sorts the db and host tables at the
same time that it reads the user table. The server sorts the db
table based on the Host, Db, and User scope columns,
and sorts the host table based on the Host and Db
scope columns. As with the user table, sorting puts the
most-specific values first and least-specific values last, and when the
server looks for matching entries, it uses the first match that it finds.
The tables_priv and columns_priv tables grant table-specific and
column-specific privileges. Values in the scope columns of these tables can
take the following form:
Host
column of either table. These have the same meaning as for pattern-matching
operations performed with the LIKE operator.
'%' or blank Host value in either table means ``any host.''
Db, Table_name, and Column_name columns cannot contain
wildcards or be blank in either table.
The server sorts the tables_priv and columns_priv tables based
on the Host, Db, and User columns. This is similar to
db table sorting, but simpler because only the Host column can
contain wildcards.
The request verification process is described here. (If you are familiar with the access-checking source code, you may notice that the description here differs slightly from the algorithm used in the code. The description is equivalent to what the code actually does; it differs only to make the explanation simpler.)
For requests that require administrative privileges such as SHUTDOWN or
RELOAD, the
server checks only the user table row because that is the only table
that specifies administrative privileges. Access is granted if the row
allows the requested operation and denied otherwise. For example, if you
want to execute mysqladmin shutdown but your user table row
doesn't grant the SHUTDOWN privilege to you, the server denies access
without even checking the db or host tables. (They
contain no Shutdown_priv column, so there is no need to do so.)
For database-related requests (INSERT, UPDATE, and so on), the
server first checks the user's global (superuser) privileges by looking in
the user table row. If the row allows the requested operation,
access is granted. If the global privileges in the user table are
insufficient, the server determines the user's database-specific privileges
by checking the db and host tables:
db table for a match on the Host,
Db, and User columns. The Host and User columns are
matched to the connecting user's hostname and MySQL username. The
Db column is matched to the database that the user wants to access. If
there is no row for the Host and User, access is denied.
db table row and its Host column is
not blank, that row defines the user's database-specific privileges.
db table row's Host column is blank, it
signifies that the host table enumerates which hosts should be allowed
access to the database. In this case, a further lookup is done in the
host table to find a match on the Host and Db columns.
If no host table row matches, access is denied. If there is a
match, the user's database-specific privileges are computed as the
intersection (not the union!) of the privileges in the db and
host table entries; that is, the privileges that are 'Y' in both
entries. (This way you can grant general privileges in the db table
row and then selectively restrict them on a host-by-host basis using the
host table entries.)
After determining the database-specific privileges granted by the db
and host table entries, the server adds them to the global privileges
granted by the user table. If the result allows the requested
operation, access is granted. Otherwise, the server successively
checks the user's table and column privileges in the tables_priv
and columns_priv tables, adds those to the user's privileges,
and allows or denies access based on the result.
Expressed in boolean terms, the preceding description of how a user's privileges are calculated may be summarized like this:
global privileges OR (database privileges AND host privileges) OR table privileges OR column privileges
It may not be apparent why, if the global user row privileges are
initially found to be insufficient for the requested operation, the server
adds those privileges to the database, table, and column privileges
later. The reason is that a request might require more than one type of
privilege. For example, if you execute an INSERT INTO ... SELECT
statement, you need both the INSERT and the SELECT privileges.
Your privileges might be such that the user table row grants one
privilege and the db table row grants the other. In this case, you
have the necessary privileges to perform the request, but the server cannot
tell that from either table by itself; the privileges granted by the entries
in both tables must be combined.
The host table is not affected by the GRANT or REVOKE
statements, so it is unused in most MySQL installations. If you modify
it directly, you can use it for some specialized purposes, such as to
maintain a list of secure servers. For example, at TcX, the host
table contains a list of all machines on the local network. These are
granted all privileges.
You can also use the host table to indicate hosts that are not
secure. Suppose that you have a machine public.your.domain that is located
in a public area that you do not consider secure. You can allow access to
all hosts on your network except that machine by using host table
entries
like this:
+--------------------+----+- | Host | Db | ... +--------------------+----+- | public.your.domain | % | ... (all privileges set to 'N') | %.your.domain | % | ... (all privileges set to 'Y') +--------------------+----+-
Naturally, you should always test your entries in the grant tables (for
example, by using SHOW GRANTS or
mysqlaccess) to make sure that your access privileges are
actually set up the way you think they are.
When mysqld starts, all grant table contents are read into memory and
become effective for access control at that point.
When the server reloads the grant tables, privileges for existing client connections are affected as follows:
USE db_name
statement.
If you modify the grant tables using GRANT, REVOKE, or
SET PASSWORD, the server notices these changes and reloads the
grant tables into memory again immediately.
If you modify the grant tables directly using statements such as
INSERT, UPDATE, or DELETE, your changes have
no effect on privilege checking until you either restart the server
or tell it to reload the tables. To reload the grant tables manually,
issue a FLUSH PRIVILEGES statement or execute a mysqladmin
flush-privileges or mysqladmin reload command.
If you change the grant tables directly but forget to reload them, your changes have no effect until you restart the server. This may leave you wondering why your changes don't seem to make any difference!
Access denied ErrorsIf you encounter problems when you try to connect to the MySQL server, the following items describe some courses of action you can take to correct the problem.
shell> mysql ERROR 2003: Can't connect to MySQL server on 'host_name' (111) shell> mysql ERROR 2002: Can't connect to local MySQL server through socket '/tmp/mysql.sock' (111)It might also be that the server is running, but you are trying to connect using a TCP/IP port, named pipe, or Unix socket file different from those on which the server is listening. To correct this when you invoke a client program, specify a
--port option to indicate the proper port, or a
--socket option to indicate the proper named pipe or Unix socket
file.
To find out where the socket file is, you can do:
shell> netstat -ln | grep mysql
mysql database containing the grant tables. For
distributions that do not do this, you should initialize the grant tables
manually by running the mysql_install_db script. For details, see
section 2.9.2 Unix Post-Installation Procedures.
One way to determine whether you need to initialize the grant tables is to
look for a `mysql' directory under the data directory. (The data
directory normally is named `data' or `var' and is located under
your MySQL installation directory.) Make sure that you have a file named
`user.MYD' in the `mysql' database directory. If you do not,
execute the mysql_install_db script. After running this script and
starting the server, test the initial privileges by executing this command:
shell> mysql -u root testThe server should let you connect without error.
shell> mysql -u root mysqlThe server should let you connect because the MySQL
root user
has no password initially. That is also a security risk, so setting the
password for the
root accounts is something you should do while you're setting up
your other MySQL users.
For instructions on setting the initial passwords, see section 2.9.3 Securing the Initial MySQL Accounts.
mysql_fix_privilege_tables script? If not, do so. The
structure of the grant tables changes occasionally when new capabilities are
added, so after an upgrade you should always make sure that your tables have
the current structure. For instructions, see section 2.10.7 Upgrading the Grant Tables.
shell> mysql Client does not support authentication protocol requested by server; consider upgrading MySQL clientFor information on how to deal with this, see section 5.5.9 Password Hashing in MySQL 4.1 and section A.2.3
Client does not support authentication protocol.
root and get the following error,
it means that you don't have an row in the user table with a
User column value of 'root' and that mysqld cannot
resolve the hostname for your client:
Access denied for user ''@'unknown' to database mysqlIn this case, you must restart the server with the
--skip-grant-tables
option and edit your `/etc/hosts' or `\windows\hosts' file to
add an entry for your host.
Access denied when you run a client
without any options, make sure that you haven't specified an old password in
any of your option files!
You can suppress the use of option files by a client program by invoking it
with the --no-defaults option. For example:
shell> mysqladmin --no-defaults -u root versionThe option files that clients use are listed in section 4.3.2 Using Option Files. Environment variables are listed in section F Environment Variables.
root password:
shell> mysqladmin -u root -pxxxx ver Access denied for user 'root'@'localhost' (using password: YES)If the preceding error occurs even when you haven't specified a password, it means that you have an incorrect password listed in some option file. Try the
--no-defaults option as described in the previous item.
For information on changing passwords, see section 5.6.5 Assigning Account Passwords.
If you have lost or forgotten the root password, you can restart
mysqld with --skip-grant-tables to change the password.
See section A.4.1 How to Reset the Root Password.
SET PASSWORD, INSERT, or
UPDATE, you must encrypt the password using the PASSWORD()
function. If you do not use PASSWORD() for these statements,
the password does not work. For example, the following statement sets a
password, but fails to encrypt it, so the user is not able to connect
afterward:
mysql> SET PASSWORD FOR 'abe'@'host_name' = 'eagle';Instead, set the password like this:
mysql> SET PASSWORD FOR 'abe'@'host_name' = PASSWORD('eagle');
The PASSWORD() function is unnecessary when you specify a password
using the GRANT statement or the mysqladmin password command,
both of which automatically use PASSWORD() to encrypt the password.
See section 5.6.5 Assigning Account Passwords.
localhost is a synonym for your local hostname, and is also the
default host to which clients try to connect if you specify no host
explicitly. However, connections to localhost on Unix systems
do not work if you are using a MySQL version older than 3.23.27 that uses
MIT-pthreads: localhost connections are made using Unix socket files,
which were not supported by MIT-pthreads at that time.
To avoid this problem on such systems, you can use a --host=127.0.0.1
option to name the server host explicitly. This will make a TCP/IP
connection to the local mysqld server. You can also use TCP/IP by
specifying a --host option that uses the actual hostname of the
local host. In this case, the hostname must be specified in a user
table row on the server host, even though you are running the client
program on the same host as the server.
Access denied error when trying to connect to the
database with mysql -u user_name, you may have a problem
with the user table. Check this by executing mysql -u root
mysql and issuing this SQL statement:
mysql> SELECT * FROM user;The result should include an row with the
Host and User
columns matching your computer's hostname and your MySQL username.
Access denied error message tells you who you are trying
to log in as, the client host from which you are trying to connect, and whether
or not you were using a password. Normally, you should have one row in
the user table that exactly matches the hostname and username
that were given in the error message. For example, if you get an error
message that contains using password: NO, it means that you
tried to log in without an password.
user table with a Host value that matches the client
host:
Host ... is not allowed to connect to this MySQL serverYou can fix this by setting up an account for the combination of client hostname and username that you are using when trying to connect. If you don't know the IP number or hostname of the machine from which you are connecting, you should put an row with
'%' as the Host column value in the user
table and restart mysqld with the --log option on the server
machine. After trying to connect from the client machine, the information
in the MySQL log indicates how you really did connect. (Then change
the '%' in the user table row to the actual hostname
that shows up in the log. Otherwise, you'll have a system that is insecure
because it allows connections from any host for the given username.)
On Linux, another reason that this error might occur is that you are using
a binary MySQL version that is compiled with a different version of the
glibc library than the one you are using. In this case, you should
either upgrade your operating system or glibc, or download a source
distribution of MySQL version and compile it yourself. A source RPM is
normally trivial to compile and install, so this isn't a big problem.
shell> mysqladmin -u root -pxxxx -h some-hostname ver Access denied for user 'root'@'' (using password: YES)This indicates a DNS problem. To fix it, execute
mysqladmin
flush-hosts to reset the internal DNS hostname cache. See section 7.5.6 How MySQL Uses DNS.
Some permanent solutions are:
/etc/hosts.
mysqld with the --skip-name-resolve option.
mysqld with the --skip-host-cache option.
localhost. Unix connections to localhost use a Unix
socket file rather than TCP/IP.
. (period). Connections to . use a named pipe rather than
TCP/IP.
mysql -u root test works but mysql -h your_hostname -u root
test results in Access denied (where your_hostname is the
actual hostname of the local host), you may not have the correct name
for your host in the user table. A common problem here is that the
Host value in the user table row specifies an unqualified hostname,
but your system's name resolution routines return a fully qualified domain
name (or vice versa). For example, if you have an entry with host
'tcx' in the user table, but your DNS tells MySQL that
your hostname is 'tcx.subnet.se', the entry does not work. Try adding
an entry to the user table that contains the IP number of your host as
the Host column value. (Alternatively, you could add an entry to the
user table with a Host value that contains a wildcard; for
example, 'tcx.%'. However, use of hostnames ending with `%' is
insecure and is not recommended!)
mysql -u user_name test works but mysql -u user_name
other_db_name does not, you have not granted database access for
other_db_name to the given user.
mysql -u user_name works when executed on the server host, but
mysql -h host_name -u user_name doesn't work when executed on a
remote client host, you have not enabled access to the server for the given
username from the remote host.
Access denied, remove from the
user table all entries that have Host values containing
wildcards (entries that contain `%' or `_'). A very common error
is to insert a new entry with Host='%' and
User='some_user', thinking that this allows you to specify
localhost to connect from the same machine. The reason that this
doesn't work is that the default privileges include an entry with
Host='localhost' and User=''. Because that entry
has a Host value 'localhost' that is more specific than
'%', it is used in preference to the new entry when connecting from
localhost! The correct procedure is to insert a second entry with
Host='localhost' and User='some_user', or to
delete the entry with Host='localhost' and
User=''.
After deleting the entry, remember to issue a FLUSH PRIVILEGES
statement to reload the grant tables.
db or
host table:
Access to database deniedIf the entry selected from the
db table has an empty value in the
Host column, make sure that there are one or more corresponding entries in
the host table specifying which hosts the db table entry
applies to.
Access
denied message whenever you issue a SELECT ... INTO OUTFILE or
LOAD DATA INFILE statement, your entry in the user table
doesn't have the FILE privilege enabled.
INSERT,
UPDATE, or DELETE statements) and your changes seem to be
ignored, remember that you must execute a FLUSH PRIVILEGES statement
or a mysqladmin flush-privileges command to cause the server
to re-read the privilege tables. Otherwise, your changes have no effect
until the next time the server is restarted. Remember that after you change
the root password with an UPDATE command, you won't need
to specify the new password until after you flush the privileges, because
the server won't know you've changed the password yet!
mysql -u user_name db_name or mysql
-u user_name -pyour_pass db_name. If you are able to connect using the
mysql client, the problem lies with your program, not with the
access privileges. (There is no space between -p and the
password; you can also use the --password=your_pass syntax to specify
the password. If you use the -p option alone, MySQL
prompts you for the password.)
mysqld server with the
--skip-grant-tables option. Then you can change the MySQL
grant tables and use the mysqlaccess script to check whether
your modifications have the desired effect. When you are satisfied with your
changes, execute mysqladmin flush-privileges to tell the mysqld
server to start using the new grant tables. (Reloading the
grant tables overrides the --skip-grant-tables option. This allows
you to tell the server to begin using the grant tables again without stopping
and restarting it.)
mysqld server with a debugging
option (for example, --debug=d,general,query). This prints host and
user information about attempted connections, as well as information about
each command issued. See section E.1.2 Creating Trace Files.
mysqldump mysql command. As always, post your problem using
the mysqlbug script. See section 1.4.1.3 How to Report Bugs or Problems. In some cases, you may need
to restart mysqld with --skip-grant-tables to run
mysqldump.
MySQL user accounts are listed in the user table of the mysql
database. Each MySQL account is assigned a password, although
what is stored in the Password column of the user table is not the
plaintext version of the password, but a hash value computed from
it. Password hash values are computed by the PASSWORD() function.
MySQL uses passwords in two phases of client/server communication:
user table for
the account that the client wants to use.
user table.
The client can do this by using the PASSWORD() function to generate a
password hash, or by using the GRANT or SET PASSWORD
statements.
In other words, the server uses hash values during authentication when
a client first attempts to connect. The server generates hash values
if a connected client invokes the PASSWORD() function or uses a
GRANT
or SET PASSWORD statement to set or change a password.
The password hashing mechanism was updated in MySQL 4.1 to provide
better security and to reduce the risk of passwords being intercepted.
However, this new mechanism is understood only by the 4.1 server and
4.1 clients, which can result in some compatibility problems.
A 4.1 client can connect to a pre-4.1 server, because the client
understands both the old and new password hashing mechanisms. However,
a pre-4.1 client that attempts to connect to a 4.1 server may run into
difficulties. For example, a 4.0 mysql client that attempts to connect
to a 4.1 server may fail with the following error message:
shell> mysql -h localhost -u root Client does not support authentication protocol requested by server; consider upgrading MySQL client
The following discussion describes the differences between the old and
new password mechanisms, and what you should do if you upgrade your
server to 4.1 but need to maintain backward compatibility with pre-4.1
clients. Additional information can be found in section A.2.3 Client does not support authentication protocol.
Note: This discussion contrasts 4.1 behavior with pre-4.1 behavior, but the 4.1 behavior described here actually begins with 4.1.1. MySQL 4.1.0 is an ``odd'' release because it has a slightly different mechanism than that implemented in 4.1.1 and up. Differences between 4.1.0 and more recent versions are described further in section 5.5.9.2 Password Hashing in MySQL 4.1.0.
Prior to MySQL 4.1, password hashes computed by the PASSWORD() function
are 16 bytes long. Such hashes look like this:
mysql> SELECT PASSWORD('mypass');
+--------------------+
| PASSWORD('mypass') |
+--------------------+
| 6f8c114b58f2ce9e |
+--------------------+
The Password column of the user table (in which these hashes are stored)
also is 16 bytes long before MySQL 4.1.
As of MySQL 4.1, the PASSWORD() function has been modified to produce
a longer 41-byte hash value:
mysql> SELECT PASSWORD('mypass');
+-----------------------------------------------+
| PASSWORD('mypass') |
+-----------------------------------------------+
| *43c8aa34cdc98eddd3de1fe9a9c2c2a9f92bb2098d75 |
+-----------------------------------------------+
Accordingly, the Password column in the user table also must be 41
bytes long to store these values:
Password column
is made 41 bytes long automatically.
mysql_fix_privilege_tables script to increase the length of the
Password
column from 16 to 41 bytes. (The script does not change existing
password values, which remain 16 bytes long.)
A widened Password column can store password hashes in both the old and
new formats. The format of any given password hash value can be
determined two ways:
The longer password hash format has better cryptographic properties, and client authentication based on long hashes is more secure than that based on the older short hashes.
The differences between short and long password hashes are relevant both for how the server uses passwords during authentication and for how it generates password hashes for connected clients that perform password-changing operations.
The way in which the server uses password hashes during authentication
is affected by the width of the Password column:
For short-hash accounts, the authentication process is actually a bit more secure for 4.1 clients than for older clients. In terms of security, the gradient from least to most secure is:
The way in which the server generates password hashes for connected
clients is affected by the width of the Password column and by the
--old-passwords option. A 4.1 server generates long hashes only if certain
conditions are met:
The Password column must be wide enough to hold long
values and the --old-passwords option must not be given.
These conditions apply as follows:
Password column must be wide enough to hold long hashes (41 bytes).
If the column has not been updated and still has the pre-4.1 width of
16 bytes, the server notices that long hashes cannot fit into it and
generates only short hashes when a client performs password-changing
operations using PASSWORD(), GRANT, or SET PASSWORD.
This is the behavior that
occurs if you have upgraded to 4.1 but have not yet run the
mysql_fix_privilege_tables script to widen the Password column.
Password column is wide, it can store either short or long
password hashes. In this case, PASSWORD(), GRANT, and SET PASSWORD
generate long hashes unless the server was started with the
--old-passwords option. That option forces the server to generate
short password hashes instead.
The purpose of the --old-passwords option is to allow you to maintain
backward compatibility with pre-4.1 clients under circumstances where
the server would otherwise generate long password hashes. The option doesn't
affect authentication (4.1 clients can still use accounts that have
long password hashes), but it does prevent creation of a long
password hash in the user table as the result of a password-changing
operation. Were that to occur, the account no longer could be used
by pre-4.1 clients. Without the --old-passwords option, the following
undesirable scenario is possible:
--old-passwords,
this results in the account having a long password hash.
This scenario illustrates that, if you must support older pre-4.1 clients,
it is dangerous to run a 4.1 server without using the --old-passwords
option. By running the server with --old-passwords, password-changing
operations do not generate long password hashes and thus do not cause
accounts to become inaccessible to older clients. (Those clients cannot
inadvertently lock themselves out by changing their password and ending
up with a long password hash.)
The downside of the --old-passwords option is that any passwords you
create or change use short hashes, even for 4.1 clients. Thus, you
lose the additional security provided by long password hashes. If you want
to create an account that has a long hash (for example, for use by 4.1
clients), you must do so while running the server without
--old-passwords.
The following scenarios are possible for running a 4.1 server:
Scenario 1: Short Password column in user table:
Password column.
PASSWORD(), GRANT, or SET PASSWORD use short hashes
exclusively. Any change to an account's password results in
that account having a short password hash.
--old-passwords option can be used but is superfluous because
with a short Password column, the server generates only short
password hashes anyway.
Scenario 2: Long Password column; server not started with
--old-passwords option:
Password column.
PASSWORD(), GRANT, or SET PASSWORD use long hashes
exclusively. A change to an account's password results in that account
having a long password hash.
As indicated earlier, a danger in this scenario is that it is possible for
accounts that have a short password hash to become inaccessible to pre-4.1
clients. A change to such an account's password made via GRANT,
PASSWORD(), or SET PASSWORD results in the account being
given a long password hash. From that point on, no pre-4.1 client can
authenticate to that account until the client upgrades to 4.1.
To deal with this problem, you can change a password in a special way.
For example, normally you use SET PASSWORD as follows to change
an account password:
mysql> SET PASSWORD FOR 'some_user'@'some_host' = PASSWORD('mypass');
To change the password but create a short hash, use the
OLD_PASSWORD() function instead:
mysql> SET PASSWORD FOR 'some_user'@'some_host' = OLD_PASSWORD('mypass');
OLD_PASSWORD() is useful for situations in which you explicitly want
to generate a short hash.
Scenario 3: Long Password column; server started with
--old-passwords option:
Password column.
--old-passwords).
PASSWORD(), GRANT, or SET PASSWORD use short hashes
exclusively. Any change to an account's password results in that
account having a short password hash.
In this scenario, you cannot create accounts that have long password
hashes, because the --old-passwords option prevents generation of long hashes. Also,
if you create an account with a long hash before using the
--old-passwords
option, changing the account's password while --old-passwords is in
effect results in the account being given a short password, causing it
to lose the security benefits of a longer hash.
The disadvantages for these scenarios may be summarized as follows:
In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication.
In scenario 2, accounts with short hashes become inaccessible to pre-4.1
clients if you change their passwords without explicitly using
OLD_PASSWORD().
In scenario 3, --old-passwords prevents accounts with short hashes from
becoming inaccessible, but password-changing operations cause accounts
with long hashes to revert to short hashes, and you cannot change them
back to long hashes while --old-passwords is in effect.
An upgrade to MySQL 4.1 can cause a compatibility issue for
applications that use PASSWORD() to generate passwords for their own
purposes. Applications really should not do this, because PASSWORD()
should be used only to manage passwords for MySQL accounts. But some
applications use PASSWORD() for their own purposes anyway.
If you upgrade to 4.1 and run the server under conditions where it
generates long password hashes, an application that uses PASSWORD()
for its own passwords breaks. The recommended course of action is
to modify the application to use another function, such as SHA1()
or MD5(), to produce hashed values. If that is not possible, you
can use the OLD_PASSWORD() function, which is provided to generate
short hashes in the old format. But note that OLD_PASSWORD() may
one day no longer be supported.
If the server is running under circumstances where it generates short hashes,
OLD_PASSWORD() is available but is equivalent to PASSWORD().
Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up. The 4.1.0 differences are:
PASSWORD() function is non-repeatable. That is, with a given
argument X, successive calls to PASSWORD(X) generate different
results.
These differences make authentication in 4.1.0 incompatible with that of
releases that follow it. If you have upgraded to MySQL 4.1.0, it is
recommended that you upgrade to a newer version as soon as possible. After
you do, reassign any long passwords in the user table so that they are
compatible with the 41-byte format.
This section describes how to set up accounts for clients of your MySQL server. It discusses the following topics:
A MySQL account is defined in terms of a username and the client host or hosts from which the user can connect to the server. The account also has a password. There are several distinctions between the way usernames and passwords are used by MySQL and the way they are used by your operating system:
-u or --user option. Because this means
that anyone can attempt to connect to the server using any username, you
can't make a database secure in any way unless all MySQL accounts have
passwords. Anyone who specifies a username for an account that
has no password is able to connect successfully to the server.
PASSWORD() SQL
function. Unix password encryption is the same as that implemented by the
ENCRYPT() SQL function. See the descriptions of the
PASSWORD() and ENCRYPT() functions in section 12.8.2 Encryption Functions. From version 4.1 on, MySQL employs a stronger authentication
method that has better password protection during the connection process
than in earlier versions. It is secure even if TCP/IP packets are sniffed or
the mysql database is captured. (In earlier versions, even though
passwords are stored in encrypted form in the user table, knowledge
of the encrypted password value could be used to connect to the MySQL
server.)
When you install MySQL, the grant tables are populated with an initial set of
accounts. These accounts have names and access privileges that are described
in section 2.9.3 Securing the Initial MySQL Accounts, which also discusses how to assign passwords
to them. Thereafter, you normally set up, modify, and remove MySQL accounts
using the GRANT and REVOKE statements.
See section 13.5.1.3 GRANT and REVOKE Syntax.
When you connect to a MySQL server with a command-line client, you should specify the username and password for the account that you want to use:
shell> mysql --user=monty --password=guess db_name
If you prefer short options, the command looks like this:
shell> mysql -u monty -pguess db_name
There must be no space between the -p option and the
following password value.
See section 5.5.4 Connecting to the MySQL Server.
The preceding commands include the password value on the command line, which
can be a security risk.
See section 5.6.6 Keeping Your Password Secure.
To avoid this, specify the --password or -p option without any
following password value:
shell> mysql --user=monty --password db_name shell> mysql -u monty -p db_name
Then the client program prints a prompt and waits for you to enter the password. (In these examples, db_name is not interpreted as a password, because it is separated from the preceding password option by a space.)
On some systems, the library call that MySQL uses to prompt for a password automatically limits the password to eight characters. That is a problem with the system library, not with MySQL. Internally, MySQL doesn't have any limit for the length of the password. To work around the problem, change your MySQL password to a value that is eight or fewer characters long, or put your password in an option file.
You can create MySQL accounts in two ways:
GRANT statements
The preferred method is to use GRANT statements, because they are
more concise and less error-prone. GRANT is available as of MySQL
3.22.11; its syntax is described in
section 13.5.1.3 GRANT and REVOKE Syntax.
Another option for creating accounts is to use one of several available
third-party programs that offer capabilities for MySQL account
administration. phpMyAdmin is one such program.
The following examples show how to use the mysql client program to
set up new users. These examples assume that privileges are set up
according to the defaults described in section 2.9.3 Securing the Initial MySQL Accounts. This means
that to make changes, you must connect to the MySQL server as the MySQL
root user, and the root account must have the INSERT
privilege for the mysql database and the RELOAD administrative
privilege.
First, use the mysql program to connect to the server as the
MySQL root user:
shell> mysql --user=root mysql
If you have assigned a password to the root account, you'll also
need to supply a --password or -p option for this mysql
command and also for those later in this section.
After connecting to the server as root, you can add new accounts. The following
statements use GRANT to set up four new accounts:
mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
-> IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
-> IDENTIFIED BY 'some_pass' WITH GRANT OPTION;
mysql> GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
mysql> GRANT USAGE ON *.* TO 'dummy'@'localhost';
The accounts created by these GRANT statements have the
following properties:
monty and a password of
some_pass. Both accounts are superuser accounts with full privileges
to do anything. One account ('monty'@'localhost') can be used only
when connecting from the local host. The other ('monty'@'%') can be
used to connect from any other host. Note that it is necessary to have both
accounts for monty to be able to connect from anywhere as
monty. Without the localhost account, the anonymous-user
account for localhost that is created by mysql_install_db
would take precedence when monty connects from the local host. As a
result, monty would be treated as an anonymous user. The reason for
this is that the anonymous-user account has a more specific Host
column value than the 'monty'@'%' account and thus comes earlier in
the user table sort order. (user table sorting is discussed
in section 5.5.5 Access Control, Stage 1: Connection Verification.)
admin and no password. This account
can be used only by connecting from the local host. It is granted the
RELOAD and PROCESS administrative privileges. These
privileges allow the admin user to execute the mysqladmin
reload, mysqladmin refresh, and mysqladmin flush-xxx commands,
as well as mysqladmin processlist . No privileges are granted for
accessing any databases. You could add such privileges later by issuing
additional GRANT statements.
dummy and no password. This account
can be used only by connecting from the local host. No privileges are
granted. The USAGE privilege in the GRANT statement allows you
to create an account without giving it any privileges. It has the effect of
setting all the global privileges to 'N'. It is assumed that you
will grant specific privileges to the account later.
As an alternative to GRANT, you can create the same accounts
directly by issuing INSERT statements and then telling
the server to reload the grant tables:
shell> mysql --user=root mysql
mysql> INSERT INTO user
-> VALUES('localhost','monty',PASSWORD('some_pass'),
-> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
mysql> INSERT INTO user
-> VALUES('%','monty',PASSWORD('some_pass'),
-> 'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
mysql> INSERT INTO user SET Host='localhost',User='admin',
-> Reload_priv='Y', Process_priv='Y';
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('localhost','dummy','');
mysql> FLUSH PRIVILEGES;
The reason for using FLUSH PRIVILEGES when you create accounts with
INSERT is to tell the server to re-read the grant tables.
Otherwise, the changes go unnoticed until you restart the server. With
GRANT, FLUSH PRIVILEGES is unnecessary.
The reason for using the PASSWORD() function with INSERT is to
encrypt the password. The GRANT statement encrypts the password for
you, so PASSWORD() is unnecessary.
The 'Y' values enable privileges for the accounts. Depending on your
MySQL version, you may have to use a different number of 'Y' values
in the first two INSERT statements. (Versions prior to 3.22.11 have
fewer privilege columns, and versions from 4.0.2 on have more.) For the
admin account, the more readable extended INSERT syntax using
SET that is available starting with MySQL 3.22.11 is used.
In the INSERT statement for the dummy account, only the
Host, User, and Password columns in the user
table record are assigned values. None of the privilege columns are set
explicitly, so MySQL assigns them all the default value of 'N'.
This is equivalent to what GRANT USAGE does.
Note that to set up a superuser account, it is necessary only to create a
user table entry with the privilege columns set to 'Y'.
user table privileges are global, so no entries in any of the other
grant tables are needed.
The next examples create three accounts and give them access to specific
databases. Each of them has a username of custom and password of
obscure.
To create the accounts with GRANT, use the following statements:
shell> mysql --user=root mysql
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
-> ON bankaccount.*
-> TO 'custom'@'localhost'
-> IDENTIFIED BY 'obscure';
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
-> ON expenses.*
-> TO 'custom'@'whitehouse.gov'
-> IDENTIFIED BY 'obscure';
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
-> ON customer.*
-> TO 'custom'@'server.domain'
-> IDENTIFIED BY 'obscure';
The three accounts can be used as follows:
bankaccount database, but only from the local host.
expenses database, but only from the host whitehouse.gov.
customer database, but only from the host server.domain.
To set up the custom accounts without GRANT, use INSERT
statements as follows to modify the grant tables directly:
shell> mysql --user=root mysql
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('localhost','custom',PASSWORD('obscure'));
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('whitehouse.gov','custom',PASSWORD('obscure'));
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('server.domain','custom',PASSWORD('obscure'));
mysql> INSERT INTO db
-> (Host,Db,User,Select_priv,Insert_priv,
-> Update_priv,Delete_priv,Create_priv,Drop_priv)
-> VALUES('localhost','bankaccount','custom',
-> 'Y','Y','Y','Y','Y','Y');
mysql> INSERT INTO db
-> (Host,Db,User,Select_priv,Insert_priv,
-> Update_priv,Delete_priv,Create_priv,Drop_priv)
-> VALUES('whitehouse.gov','expenses','custom',
-> 'Y','Y','Y','Y','Y','Y');
mysql> INSERT INTO db
-> (Host,Db,User,Select_priv,Insert_priv,
-> Update_priv,Delete_priv,Create_priv,Drop_priv)
-> VALUES('server.domain','customer','custom',
-> 'Y','Y','Y','Y','Y','Y');
mysql> FLUSH PRIVILEGES;
The first three INSERT statements add user table entries that
allow the user custom to connect from the various hosts with the given
password, but grant no global privileges (all privileges are set to the
default value of 'N'). The next three INSERT statements add
db table entries that grant privileges to custom for the
bankaccount, expenses, and customer databases, but only
when accessed from the proper hosts. As usual when you modify the grant
tables directly, you tell the server to reload them with
FLUSH PRIVILEGES so that the privilege changes take effect.
If you want to give a specific user access from all machines in a given
domain (for example, mydomain.com), you can issue a GRANT
statement that uses the `%' wildcard character in the host part of the
account name:
mysql> GRANT ...
-> ON *.*
-> TO 'myname'@'%.mydomain.com'
-> IDENTIFIED BY 'mypass';
To do the same thing by modifying the grant tables directly, do this:
mysql> INSERT INTO user (Host,User,Password,...)
-> VALUES('%.mydomain.com','myname',PASSWORD('mypass'),...);
mysql> FLUSH PRIVILEGES;
To remove an account, use the DROP USER statement, which was added in
MySQL 4.1.1. For older versions of MySQL, use DELETE instead.
The account removal procedure is described in section 13.5.1.2 DROP USER Syntax.
Before MySQL 4.0.2, the only available method for limiting use of MySQL
server resources is to set the max_user_connections system
variable to a non-zero value. But that method is strictly global. It does
not allow for management of individual accounts. Also, it limits only the
number of simultaneous connections made using a single account, not
what a client can do once connected. Both types of control are
interest to many MySQL administrators, particularly those for Internet
Service Providers.
Starting from MySQL 4.0.2, you can limit the following server resources for individual accounts:
Any statement that a client can issue counts against the query limit. Only statements that modify databases or tables count against the update limit.
From MySQL 5.0.3 on, it is also possible to limit the number of simultaneous connection to the server on a per-account basis.
An account in this context is a single record in the user table. Each
account is uniquely identified by its User and Host column
values.
As a prerequisite for using this feature, the user table in the
mysql database must contain the resource-related columns. Resource
limits are stored in the max_questions, max_updates,
max_connections, and max_user_connections columns. If your
user table doesn't have these columns, it must be upgraded; see
section 2.10.7 Upgrading the Grant Tables.
To set resource limits with a GRANT statement, use a WITH
clause that names each resource to be limited and a per-hour count
indicating the limit value. For example, to create a new account that can
access the customer database, but only in a limited fashion, issue
this statement:
mysql> GRANT ALL ON customer.* TO 'francis'@'localhost'
-> IDENTIFIED BY 'frank'
-> WITH MAX_QUERIES_PER_HOUR 20
-> MAX_UPDATES_PER_HOUR 10
-> MAX_CONNECTIONS_PER_HOUR 5
-> MAX_USER_CONNECTIONS 2;
The limit types need not all be named in the WITH clause, but those
named can be present in any order. The value for each per-hour limit should
be an integer representing a count per hour. If the GRANT statement
has no WITH clause, the limits are each set to the default value of
zero (that is, no limit). For MAX_USER_CONNECTIONS, the limit is an
integer indicating the maximum number of simultaneous connections the
account can make at any one time. If the limit is set to the default value
of zero, the max_user_connections system variable determines the number
of simultaneous connections for the account.
To set or change limits for an existing account, use a GRANT USAGE
statement at the global level (ON *.*). The following statement
changes the query limit for francis to 100:
mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
-> WITH MAX_QUERIES_PER_HOUR 100;
This statement leaves the account's existing privileges unchanged and modifies only the limit values specified.
To remove an existing limit, set its value to zero. For example, to remove the
limit on how many times per hour francis can connect, use this
statement:
mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
-> WITH MAX_CONNECTIONS_PER_HOUR 0;
Resource-use counting takes place when any account has a non-zero limit placed on its use of any of the resources.
As the server runs, it counts the number of times each account uses resources. If an account reaches its limit on number of connections within the last hour, further connections for the account are rejected until that hour is up. Similarly, if the account reaches its limit on the number of queries or updates, further queries or updates are rejected until the hour is up. In all such cases, an appropriate error message is issued.
Resource counting is done per account, not per client. For example, if your account has a query limit of 50, you cannot increase your limit to 100 by making two simultaneous client connections to the server. Queries issued on both connections are counted together.
The current per-hour resource-use counts can be reset globally for all accounts, or individually for a given account:
FLUSH
USER_RESOURCES statement. The counts also can be reset by reloading the
grant tables (for example, with a FLUSH PRIVILEGES statement or a
mysqladmin reload command).
GRANT USAGE as described earlier
and specify a limit value equal to the value that the account currently has.
Counter resets do not affect the MAX_USER_CONNECTIONS limit.
All counts begin at zero when the server starts; counts are not carried over through a restart.
Passwords may be assigned from the command line by using the mysqladmin
command:
shell> mysqladmin -u user_name -h host_name password "newpwd"
The account for which this command resets the password is the one with a
user table record that matches user_name in the User
column and the client host from which you connect in the
Host column.
Another way to assign a password to an account is to issue a SET
PASSWORD statement:
mysql> SET PASSWORD FOR 'jeffrey'@'%' = PASSWORD('biscuit');
Only users such as root with update access to the mysql
database can change the password for other users. If you are not connected
as an anonymous user, you can change your own password by omitting the
FOR clause:
mysql> SET PASSWORD = PASSWORD('biscuit');
You can also use a GRANT USAGE statement at the global level
(ON *.*) to assign a password to an account without affecting the
account's current privileges:
mysql> GRANT USAGE ON *.* TO 'jeffrey'@'%' IDENTIFIED BY 'biscuit';
Although it is generally preferable to assign passwords using one of the
preceding methods, you can also do so by modifying the user table
directly:
Password column:
shell> mysql -u root mysql
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('%','jeffrey',PASSWORD('biscuit'));
mysql> FLUSH PRIVILEGES;
UPDATE to set the
Password column value:
shell> mysql -u root mysql
mysql> UPDATE user SET Password = PASSWORD('bagel')
-> WHERE Host = '%' AND User = 'francis';
mysql> FLUSH PRIVILEGES;
When you assign an account a password using SET PASSWORD,
INSERT, or UPDATE, you must use the PASSWORD() function
to encrypt it. (The only exception is that you need not use
PASSWORD() if the password is empty.) PASSWORD() is
necessary because the user table stores passwords in encrypted form,
not as plaintext. If you forget that fact, you are likely to set passwords
like this:
shell> mysql -u root mysql
mysql> INSERT INTO user (Host,User,Password)
-> VALUES('%','jeffrey','biscuit');
mysql> FLUSH PRIVILEGES;
The result is that the literal value 'biscuit' is stored as the
password in the user table, not the encrypted value. When
jeffrey attempts to connect to the server using this password, the
value is encrypted and compared to the value stored in the user
table. However, the stored value is the literal string 'biscuit', so
the comparison fails and the server rejects the connection:
shell> mysql -u jeffrey -pbiscuit test Access denied
If you set passwords using the GRANT ... IDENTIFIED BY statement or
the mysqladmin password command, they both take care of encrypting
the password for you. The PASSWORD() function is unnecessary.
Note: PASSWORD() encryption is different from Unix password
encryption.
See section 5.6.1 MySQL Usernames and Passwords.
On an administrative level, you should never grant access to the
mysql.user table to any non-administrative accounts. Passwords in the
user table are stored in encrypted form, but in versions of MySQL
earlier than 4.1, knowing the encrypted password for an account makes it
possible to connect to the server using that account.
When you run a client program to connect to the MySQL server, it is inadvisable to specify your password in a way that exposes it to discovery by other users. The methods you can use to specify your password when you run client programs are listed here, along with an assessment of the risks of each method:
-pyour_pass or --password=your_pass option on the command
line. For example:
shell> mysql -u francis -pfrank db_nameThis is convenient but insecure, because your password becomes visible to system status programs such as
ps that may be invoked by other users
to display command lines. MySQL clients typically overwrite the
command-line password argument with zeros during their initialization
sequence, but there is still a brief interval during which the value is
visible.
-p or --password option with no password value
specified. In this case, the client program solicits the password from
the terminal:
shell> mysql -u francis -p db_name Enter password: ********The `*' characters indicate where you enter your password. The password is not displayed as you enter it. It is more secure to enter your password this way than to specify it on the command line because it is not visible to other users. However, this method of entering a password is suitable only for programs that you run interactively. If you want to invoke a client from a script that runs non-interactively, there is no opportunity to enter the password from the terminal. On some systems, you may even find that the first line of your script is read and interpreted (incorrectly) as your password!
[client] section of the `.my.cnf' file in your
home directory:
[client] password=your_passIf you store your password in `.my.cnf', the file should not be accessible to anyone but yourself. To ensure this, set the file access mode to
400 or 600. For example:
shell> chmod 600 .my.cnfsection 4.3.2 Using Option Files discusses option files in more detail.
MYSQL_PWD environment variable.
This method of specifying your MySQL password must be considered
extremely insecure and should not be used. Some versions of ps
include an option to display the environment of running processes. If you
set MYSQL_PWD, your password is exposed to any other user who
runs ps. Even on systems without such a version of ps, it is
unwise to assume that there are no other methods by which users can examine
process environments.
See section F Environment Variables.
All in all, the safest methods are to have the client program prompt for the password or to specify the password in a properly protected option file.
Beginning with version 4.0.0, MySQL has support for secure (encrypted) connections between MySQL clients and the server using the Secure Sockets Layer (SSL) protocol. This section discusses how to use SSL connections. It also describes a way to set up SSH on Windows.
The standard configuration of MySQL is intended to be as fast as possible, so encrypted connections are not used by default. Doing so would make the client/server protocol much slower. Encrypting data is a CPU-intensive operation that requires the computer to do additional work and can delay other MySQL tasks. For applications that require the security provided by encrypted connections, the extra computation is warranted.
MySQL allows encryption to be enabled on a per-connection basis. You can choose a normal unencrypted connection or a secure encrypted SSL connection according the requirements of individual applications.
To understand how MySQL uses SSL, it's necessary to explain some basic SSL and X509 concepts. People who are familiar with them can skip this part.
By default, MySQL uses unencrypted connections between the client and the
server. This means that someone with access to the network could watch all
your traffic and look at the data being sent or received. They could even
change the data while it is in transit between client and server. To improve
security a little, you can compress client/server traffic by using the
--compress option when invoking client programs. However, this does
not foil a determined attacker.
When you need to move information over a network in a secure fashion, an unencrypted connection is unacceptable. Encryption is the way to make any kind of data unreadable. In fact, today's practice requires many additional security elements from encryption algorithms. They should resist many kind of known attacks such as changing the order of encrypted messages or replaying data twice.
SSL is a protocol that uses different encryption algorithms to ensure that data received over a public network can be trusted. It has mechanisms to detect any data change, loss, or replay. SSL also incorporates algorithms that provide identity verification using the X509 standard.
X509 makes it possible to identify someone on the Internet. It is most commonly used in e-commerce applications. In basic terms, there should be some company called a ``Certificate Authority'' (or CA) that assigns electronic certificates to anyone who needs them. Certificates rely on asymmetric encryption algorithms that have two encryption keys (a public key and a secret key). A certificate owner can show the certificate to another party as proof of identity. A certificate consists of its owner's public key. Any data encrypted with this public key can be decrypted only using the corresponding secret key, which is held by the owner of the certificate.
If you need more information about SSL, X509, or encryption, use your favorite Internet search engine to search for keywords in which you are interested.
To use SSL connections between the MySQL server and client programs, your system must be able to support OpenSSL and your version of MySQL must be 4.0.0 or newer.
To get secure connections to work with MySQL, you must do the following:
configure script with the
--with-vio and --with-openssl options.
mysql.user table.
This is necessary if your grant tables date from a version prior to MySQL
4.0.0. The upgrade procedure is described in section 2.10.7 Upgrading the Grant Tables.
mysqld server supports OpenSSL,
examine the value of the have_openssl system variable:
mysql> SHOW VARIABLES LIKE 'have_openssl'; +---------------+-------+ | Variable_name | Value | +---------------+-------+ | have_openssl | YES | +---------------+-------+If the value is
YES, the server supports OpenSSL connections.
Here is an example for setting up SSL certificates for MySQL:
DIR=`pwd`/openssl
PRIV=$DIR/private
mkdir $DIR $PRIV $DIR/newcerts
cp /usr/share/ssl/openssl.cnf $DIR
replace ./demoCA $DIR -- $DIR/openssl.cnf
# Create necessary files: $database, $serial and $new_certs_dir
# directory (optional)
touch $DIR/index.txt
echo "01" > $DIR/serial
#
# Generation of Certificate Authority(CA)
#
openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/cacert.pem \
-config $DIR/openssl.cnf
# Sample output:
# Using configuration from /home/monty/openssl/openssl.cnf
# Generating a 1024 bit RSA private key
# ................++++++
# .........++++++
# writing new private key to '/home/monty/openssl/private/cakey.pem'
# Enter PEM pass phrase:
# Verifying password - Enter PEM pass phrase:
# -----
# You are about to be asked to enter information that will be
# incorporated into your certificate request.
# What you are about to enter is what is called a Distinguished Name
# or a DN.
# There are quite a few fields but you can leave some blank
# For some fields there will be a default value,
# If you enter '.', the field will be left blank.
# -----
# Country Name (2 letter code) [AU]:FI
# State or Province Name (full name) [Some-State]:.
# Locality Name (eg, city) []:
# Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
# Organizational Unit Name (eg, section) []:
# Common Name (eg, YOUR name) []:MySQL admin
# Email Address []:
#
# Create server request and key
#
openssl req -new -keyout $DIR/server-key.pem -out \
$DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf
# Sample output:
# Using configuration from /home/monty/openssl/openssl.cnf
# Generating a 1024 bit RSA private key
# ..++++++
# ..........++++++
# writing new private key to '/home/monty/openssl/server-key.pem'
# Enter PEM pass phrase:
# Verifying password - Enter PEM pass phrase:
# -----
# You are about to be asked to enter information that will be
# incorporated into your certificate request.
# What you are about to enter is what is called a Distinguished Name
# or a DN.
# There are quite a few fields but you can leave some blank
# For some fields there will be a default value,
# If you enter '.', the field will be left blank.
# -----
# Country Name (2 letter code) [AU]:FI
# State or Province Name (full name) [Some-State]:.
# Locality Name (eg, city) []:
# Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
# Organizational Unit Name (eg, section) []:
# Common Name (eg, YOUR name) []:MySQL server
# Email Address []:
#
# Please enter the following 'extra' attributes
# to be sent with your certificate request
# A challenge password []:
# An optional company name []:
#
# Remove the passphrase from the key (optional)
#
openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem
#
# Sign server cert
#
openssl ca -policy policy_anything -out $DIR/server-cert.pem \
-config $DIR/openssl.cnf -infiles $DIR/server-req.pem
# Sample output:
# Using configuration from /home/monty/openssl/openssl.cnf
# Enter PEM pass phrase:
# Check that the request matches the signature
# Signature ok
# The Subjects Distinguished Name is as follows
# countryName :PRINTABLE:'FI'
# organizationName :PRINTABLE:'MySQL AB'
# commonName :PRINTABLE:'MySQL admin'
# Certificate is to be certified until Sep 13 14:22:46 2003 GMT
# (365 days)
# Sign the certificate? [y/n]:y
#
#
# 1 out of 1 certificate requests certified, commit? [y/n]y
# Write out database with 1 new entries
# Data Base Updated
#
# Create client request and key
#
openssl req -new -keyout $DIR/client-key.pem -out \
$DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf
# Sample output:
# Using configuration from /home/monty/openssl/openssl.cnf
# Generating a 1024 bit RSA private key
# .....................................++++++
# .............................................++++++
# writing new private key to '/home/monty/openssl/client-key.pem'
# Enter PEM pass phrase:
# Verifying password - Enter PEM pass phrase:
# -----
# You are about to be asked to enter information that will be
# incorporated into your certificate request.
# What you are about to enter is what is called a Distinguished Name
# or a DN.
# There are quite a few fields but you can leave some blank
# For some fields there will be a default value,
# If you enter '.', the field will be left blank.
# -----
# Country Name (2 letter code) [AU]:FI
# State or Province Name (full name) [Some-State]:.
# Locality Name (eg, city) []:
# Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
# Organizational Unit Name (eg, section) []:
# Common Name (eg, YOUR name) []:MySQL user
# Email Address []:
#
# Please enter the following 'extra' attributes
# to be sent with your certificate request
# A challenge password []:
# An optional company name []:
#
# Remove a passphrase from the key (optional)
#
openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem
#
# Sign client cert
#
openssl ca -policy policy_anything -out $DIR/client-cert.pem \
-config $DIR/openssl.cnf -infiles $DIR/client-req.pem
# Sample output:
# Using configuration from /home/monty/openssl/openssl.cnf
# Enter PEM pass phrase:
# Check that the request matches the signature
# Signature ok
# The Subjects Distinguished Name is as follows
# countryName :PRINTABLE:'FI'
# organizationName :PRINTABLE:'MySQL AB'
# commonName :PRINTABLE:'MySQL user'
# Certificate is to be certified until Sep 13 16:45:17 2003 GMT
# (365 days)
# Sign the certificate? [y/n]:y
#
#
# 1 out of 1 certificate requests certified, commit? [y/n]y
# Write out database with 1 new entries
# Data Base Updated
#
# Create a my.cnf file that you can use to test the certificates
#
cnf=""
cnf="$cnf [client]"
cnf="$cnf ssl-ca=$DIR/cacert.pem"
cnf="$cnf ssl-cert=$DIR/client-cert.pem"
cnf="$cnf ssl-key=$DIR/client-key.pem"
cnf="$cnf [mysqld]"
cnf="$cnf ssl-ca=$DIR/cacert.pem"
cnf="$cnf ssl-cert=$DIR/server-cert.pem"
cnf="$cnf ssl-key=$DIR/server-key.pem"
echo $cnf | replace " " '
' > $DIR/my.cnf
To test SSL connections, start the server as follows, where $DIR is the
pathname to the directory where the sample `my.cnf' option file is
located:
shell> mysqld --defaults-file=$DIR/my.cnf &
Then invoke a client program using the same option file:
shell> mysql --defaults-file=$DIR/my.cnf
If you have a MySQL source distribution, you can also test your setup by modifying the preceding `my.cnf' file to refer to the demonstration certificate and key files in the `SSL' directory of the distribution.
GRANT Options
MySQL can check X509 certificate attributes in addition to the usual
authentication that is based on the username and password. To specify
SSL-related options for a MySQL account, use the REQUIRE clause of
the GRANT statement.
See section 13.5.1.3 GRANT and REVOKE Syntax.
There are different possibilities for limiting connection types for an account:
REQUIRE SSL option limits the server to allow only SSL
encrypted connections for the account. Note that this option can be omitted
if there are any ACL records that allow non-SSL connections.
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret' REQUIRE SSL;
REQUIRE X509 means that the client must have a valid certificate
but that the exact certificate, issuer, and subject do not matter.
The only requirement is that it should be possible to verify its
signature with one of the CA certificates.
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret' REQUIRE X509;
REQUIRE ISSUER 'issuer' places the restriction on connection attempts
that the client must present a valid X509 certificate issued by CA
'issuer'. If the client presents a certificate that is valid but has
a different issuer, the server rejects the connection. Use of X509
certificates always implies encryption, so the SSL option is
unnecessary.
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret'
-> REQUIRE ISSUER '/C=FI/ST=Some-State/L=Helsinki/
O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@example.com';
Note that the ISSUER value should be entered as a single string.
REQUIRE SUBJECT 'subject' places the restriction on connection
attempts that the client must present a valid X509 certificate with subject
'subject' on it. If the client presents a certificate that is valid
but has a different subject, the server rejects the connection.
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret'
-> REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
O=MySQL demo client certificate/
CN=Tonu Samuel/Email=tonu@example.com';
Note that the SUBJECT value should be entered as a single string.
REQUIRE CIPHER 'cipher' is needed to ensure that strong enough ciphers
and key lengths are used. SSL itself can be weak if old algorithms
with short encryption keys are used. Using this option, we can ask for
some exact cipher method to allow a connection.
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret'
-> REQUIRE CIPHER 'EDH-RSA-DES-CBC3-SHA';
The SUBJECT, ISSUER, and CIPHER options can be
combined in the REQUIRE clause like this:
mysql> GRANT ALL PRIVILEGES ON test.* TO 'root'@'localhost'
-> IDENTIFIED BY 'goodsecret'
-> REQUIRE SUBJECT '/C=EE/ST=Some-State/L=Tallinn/
O=MySQL demo client certificate/
CN=Tonu Samuel/Email=tonu@example.com'
-> AND ISSUER '/C=FI/ST=Some-State/L=Helsinki/
O=MySQL Finland AB/CN=Tonu Samuel/Email=tonu@example.com'
-> AND CIPHER 'EDH-RSA-DES-CBC3-SHA';
Note that the SUBJECT and ISSUER values each should be entered
as a single string.
Starting from MySQL 4.0.4, the AND keyword is optional between
REQUIRE options.
The order of the options does not matter, but no option can be specified twice.
The following list describes options that are used for specifying the use of SSL, certificate files, and key files. These options are available beginning with MySQL 4.0. They may be given on the command line or in an option file.
--ssl
--ssl-ca, --ssl-cert, and --ssl-key options.
This option is more often used in its opposite form to indicate that SSL
should not be used. To do this, specify the option as
--skip-ssl or --ssl=0.
Note that use of --ssl doesn't require an SSL connection.
For example, if the server or client is compiled without SSL support,
a normal unencrypted connection is used.
The secure way to ensure that an SSL connection is used is
to create an account on the server that includes a
REQUIRE SSL clause in the GRANT statement.
Then use this account to connect to the server, with both a server and client
that have SSL support enabled.
--ssl-ca=file_name
--ssl-capath=directory_name
--ssl-cert=file_name
--ssl-cipher=cipher_list
openssl ciphers
command.
Example: --ssl-cipher=ALL:-AES:-EXP
--ssl-key=file_name
Here is a note about how to connect to get a secure connection to remote MySQL server with SSH (by David Carlson dcarlson@mplcomm.com):
SecureCRT from http://www.vandyke.com/.
Another option is f-secure from http://www.f-secure.com/. You
can also find some free ones on Google at
http://directory.google.com/Top/Computers/Security/Products_and_Tools/Cryptography/SSH/Clients/Windows/.
Host_Name = yourmysqlserver_URL_or_IP.
Set userid=your_userid to log in to your server. This userid
value may not be the same as the username of your MySQL account.
local_port: 3306, remote_host: yourmysqlservername_or_ip, remote_port: 3306 )
or a local forward (Set port: 3306, host: localhost, remote port: 3306).
localhost
for the MySQL host server, not yourmysqlservername.
You should have an ODBC connection to MySQL, encrypted using SSH.
This section discusses how to make database backups (full and incremental)
and how to perform
table maintenance. The syntax of the SQL statements described here is
given in section 13.5 Database Administration Statements.
Much of the information here pertains primarily to MyISAM tables.
InnoDB backup procedures are given in section 15.9 Backing Up and Recovering an InnoDB Database.
Because MySQL tables are stored as files, it is easy to do a
backup. To get a consistent backup, do a LOCK TABLES on the
relevant tables, followed by FLUSH TABLES for the tables.
See section 13.4.5 LOCK TABLES and UNLOCK TABLES Syntax and
section 13.5.5.2 FLUSH Syntax.
You need only a read lock; this allows other clients to continue to
query the tables while you are making a copy of the files in the
database directory. The FLUSH TABLES statement is needed to ensure that
the all active index pages are written to disk before you start the backup.
If you want to make an SQL-level backup of a table, you can use
SELECT INTO ... OUTFILE or BACKUP TABLE.
For SELECT INTO ... OUTFILE, the output file cannot previously exist.
For BACKUP TABLE, the same is true as of
MySQL 3.23.56 and 4.0.12, because this would be a security risk.
See section 13.1.7 SELECT Syntax and
section 13.5.2.2 BACKUP TABLE Syntax.
Another way to back up a database is to use the mysqldump program or
the mysqlhotcopy script.
See section 8.8 The mysqldump Database Backup Program and
section 8.9 The mysqlhotcopy Database Backup Program.
shell> mysqldump --tab=/path/to/some/dir --opt db_nameOr:
shell> mysqlhotcopy db_name /path/to/some/dirYou can also simply copy all table files (`*.frm', `*.MYD', and `*.MYI' files) as long as the server isn't updating anything. The
mysqlhotcopy script uses this method. (But note that these
methods
do not work if your database contains InnoDB tables. InnoDB
does not store table contents in database directories, and mysqlhotcopy
works only for MyISAM and ISAM tables.)
mysqld if it's running, then start it with the
--log-bin[=file_name] option. See section 5.9.4 The Binary Log. The binary
log files provide you with the information you need to replicate
changes to the database that are made subsequent to the point at which
you executed mysqldump.
For InnoDB tables, it's possible to perform an online backup that
takes no locks on tables; see section 8.8 The mysqldump Database Backup Program
MySQL supports incremental backups: You need to start the server with the
--log-bin option to enable binary logging; see section 5.9.4 The Binary Log.
At the moment you want to make an incremental backup (containing all
changes that happened since the last full or incremental backup), you should
rotate the binary log by using FLUSH LOGS. This done, you need to
copy to the backup location all binary logs which range from the one of the
moment of the last full or incremental backup to the last but one. These
binary logs are the incremental backup; at restore time, you apply them
as explained further below. The next time you do a full backup, you should
also rotate the binary log using FLUSH LOGS, mysqldump
--flush-logs, or mysqlhotcopy --flushlogs. See section 8.8 The mysqldump Database Backup Program and section 8.9 The mysqlhotcopy Database Backup Program.
If your MySQL server is a slave replication server, then regardless of the
backup method you choose, you should also back up the
`master.info' and `relay-log.info' files
when you back up your slave's data. These files
are always needed to resume replication after you restore
the slave's data. If your slave is subject to replicating LOAD
DATA INFILE commands, you should also back up any `SQL_LOAD-*' files
that may exist in the directory specified by the --slave-load-tmpdir
option. (This location defaults to the value of the tmpdir variable
if not specified.) The slave needs these files to resume
replication of any interrupted LOAD DATA INFILE operations.
If you have to restore MyISAM tables, try to recover them using
REPAIR TABLE or myisamchk -r first. That should work in
99.9% of all cases. If myisamchk fails, try the following procedure.
Note that it works only if you have enabled binary logging by starting
MySQL with the --log-bin option; see section 5.9.4 The Binary Log.
mysqldump backup, or binary backup.
shell> mysqlbinlog hostname-bin.[0-9]* | mysqlIn your case, you may want to re-run only certain binary logs, from certain positions (usually you want to re-run all binary logs from the date of the restored backup, excepting possibly some incorrect queries). See section 8.5 The
mysqlbinlog Binary Log Utility for more information on
the mysqlbinlog utility and how to use it.
If you are using the update logs instead (which is a deprecated feature removed
in MySQL 5.0), you can process their contents like this:
shell> ls -1 -t -r hostname.[0-9]* | xargs cat | mysql
ls is used to sort the update log filenames into the right order.
You can also do selective backups of individual files:
SELECT * INTO OUTFILE 'file_name' FROM tbl_name.
LOAD DATA INFILE 'file_name' REPLACE ...
To avoid duplicate records, the table must have a PRIMARY KEY or a
UNIQUE index. The REPLACE keyword causes old records
to be replaced with new ones when a new record duplicates an old record on
a unique key value.
If you have performance problems with your server while making backups, one strategy that can help is to set up replication and perform backups on the slave rather than on the master. See section 6.1 Introduction to Replication.
If you are using a Veritas filesystem, you can make a backup like this:
FLUSH TABLES WITH READ LOCK.
mount vxfs snapshot.
UNLOCK TABLES.
This section discusses a procedure for performing backups that allows you to recover data after several types of crashes:
The following instructions assume a minimum version of MySQL 4.1.8,
because some mysqldump options used here are not available in
earlier versions.
The example commands do not include options such as --user and
--password for the mysqldump and mysql programs.
You should include such options as necessary so that the MySQL server allows
you to connect to it.
We'll consider data is stored into the InnoDB storage engine of
MySQL, which has support for transactions and automatic crash recovery.
We'll always assume the MySQL server is under load at the time of crash. If
it were not, no recovery would ever be needed.
For the cases of operating system crashes or power failures, we can assume
the MySQL disk data is available after a restart. The InnoDB data
files do not contain consistent data due to the crash, but InnoDB
reads its logs and finds in them the list of pending committed and
non-committed transactions that have not been flushed to the data files. It
automatically rolls back those that were not committed, and flushes to the
data files those that were committed. Information about this recovery
process is conveyed to the user through the MySQL error log. The following
is an example log excerpt:
InnoDB: Database was not shut down normally. InnoDB: Starting recovery from log files... InnoDB: Starting log scan based on checkpoint at InnoDB: log sequence number 0 13674004 InnoDB: Doing recovery: scanned up to log sequence number 0 13739520 InnoDB: Doing recovery: scanned up to log sequence number 0 13805056 InnoDB: Doing recovery: scanned up to log sequence number 0 13870592 InnoDB: Doing recovery: scanned up to log sequence number 0 13936128 ... InnoDB: Doing recovery: scanned up to log sequence number 0 20555264 InnoDB: Doing recovery: scanned up to log sequence number 0 20620800 InnoDB: Doing recovery: scanned up to log sequence number 0 20664692 InnoDB: 1 uncommitted transaction(s) which must be rolled back InnoDB: Starting rollback of uncommitted transactions InnoDB: Rolling back trx no 16745 InnoDB: Rolling back of trx no 16745 completed InnoDB: Rollback of uncommitted transactions completed InnoDB: Starting an apply batch of log records to the database... InnoDB: Apply batch completed InnoDB: Started mysqld: ready for connections
For the cases of filesystem crashes or hardware problems, we can assume the MySQL disk data is not available after a restart. This means that MySQL fails to start successfully because some blocks of disk data are no longer readable. In this case, it's necessary to reformat the disk, install a new one, or otherwise correct the underlying problem. Then it's necessary to recover our MySQL data from backups--which means that we must already have made backups. To make sure that is the case, let's step back in time and design a backup policy.
We all know that backups must be scheduled periodically. Full backups (a
snapshot of the data at a point in time) can be done in MySQL with several
tools. For example, InnoDB Hot Backup provides online non-blocking
physical backup of the InnoDB data file, and mysqldump provides
online logical backup. This discussion uses mysqldump.
Assume that we make a backup on Sunday at 1 PM, when load is low. The
following command makes a full backup of all our
InnoDB tables in all databases:
shell> mysqldump --single-transaction --all-databases > backup_sunday_1_PM.sql
This is an online, non-blocking backup that does not disturb the reads
and writes on the tables. We assumed earlier that our tables are InnoDB
tables, so --single-transaction uses a consistent read and guarantees
that data seen by mysqldump does not change. (Changes made by other
clients to InnoDB tables are not seen by the mysqldump
process.) If we do also have other types of tables, we must assume that they
are not changed during the backup. For example, for the MyISAM tables
in the mysql database, we must assume that no administrative changes are
being made to MySQL accounts during the backup.
The resulting `.sql' file produced by the mysqldump command
contains SQL INSERT statements that can be used to reload the dumped
tables later.
Full backups are necessary, but they are not always convenient. They produce large backup files and take time to generate. They are not optimal in the sense that each successive full backup includes all data, even that part that didn't change since the previous full backup. After we have made the initial full backup, it is more optimal to make incremental backups. They are smaller and take less time to produce. (The tradeoff is that at recovery time, you do not restore your data just by reloading the full backup. You must also process the incremental backups to recover the incremental changes.)
To make incremental backups, we need to save the incremental changes. The
MySQL server should always be started with the --log-bin option so
that it stores these changes in a file while it updates data. This option
enables binary logging, so that the server writes each SQL statement that
updates data into a file called a MySQL binary log. Let's look at the data
directory of a MySQL server that was started with the --log-bin
option and that has been running for some days. We find these MySQL binary
log files:
-rw-rw---- 1 guilhem guilhem 1277324 Nov 10 23:59 gbichot2-bin.000001 -rw-rw---- 1 guilhem guilhem 4 Nov 10 23:59 gbichot2-bin.000002 -rw-rw---- 1 guilhem guilhem 79 Nov 11 11:06 gbichot2-bin.000003 -rw-rw---- 1 guilhem guilhem 508 Nov 11 11:08 gbichot2-bin.000004 -rw-rw---- 1 guilhem guilhem 220047446 Nov 12 16:47 gbichot2-bin.000005 -rw-rw---- 1 guilhem guilhem 998412 Nov 14 10:08 gbichot2-bin.000006 -rw-rw---- 1 guilhem guilhem 361 Nov 14 10:07 gbichot2-bin.index
Each time it restarts, the MySQL server creates a new binary log file using
the next number in the sequence. While the server is running, you can also
tell it to close the current binary log file and begin a new one manually by
issuing a FLUSH LOGS SQL statement or with a mysqladmin
flush-logs command. mysqldump also has an option to flush the
logs. The .index file contains the list of all MySQL binary logs in
the directory. This file is used for replication.
The MySQL binary logs are important for recovery, because they are
incremental backups. If you make sure to flush the logs when you make your
full backup, then any binary log files created afterward contain all the
data changes made since the backup. Let's modify the previous
mysqldump command a bit so that it flushes the MySQL binary logs
at the moment of the full backup, and so that the dump file contains
the name of the new current binary log:
shell> mysqldump --single-transaction --flush-logs --master-data=2
--all-databases > backup_sunday_1_PM.sql
After executing this command, the the data directory contains a new binary log file, `gbichot2-bin.000007'. The resulting `.sql' file contains these lines:
-- Position to start replication or point-in-time recovery from -- CHANGE MASTER TO MASTER_LOG_FILE='gbichot2-bin.000007',MASTER_LOG_POS=4;
Because the mysqldump command made a full backup, these lines mean
two things:
On Monday at 1 PM, we can create an incremental backup by flushing the logs
to begin a new binary log file. For example, executing a mysqladmin
flush-logs command creates `gbichot2-bin.000008'. All changes
between the Sunday 1 PM full backup and Monday 1 PM are the file
`gbichot2-bin.000007'. This incremental backup is important, so it's a
good idea to copy it to a safe place. (For example, back it up on tape or
DVD, or copy it to another machine.) On Tuesday 1 PM, execute another
mysqladmin flush-logs command. All changes between Monday 1 PM and
Tuesday 1 PM are the file `gbichot2-bin.000008' (which also should be
copied somewhere safe).
The MySQL binary logs take up disk space. To free up space, purge them from time to time. One way to do this is by deleting the binary logs that are no longer needed, such as when we make a full backup:
shell> mysqldump --single-transaction --flush-logs --master-data=2
--all-databases --delete-master-logs > backup_sunday_1_PM.sql
Note: Deleting the MySQL binary logs with mysqldump
--delete-master-logs can be dangerous if your server is a replication
master server, because slave servers might not yet fully have processed
the contents of the binary log.
The description for the PURGE MASTER LOGS statement explains what
should be verified before deleting the MySQL binary logs.
See section 13.6.1.1 PURGE MASTER LOGS Syntax.
Now suppose that we have a catastrophic crash on Wednesday at 8 AM that requires recovery from backups. To recover, first we restore the last full backup we have (the one from Sunday 1 PM). The full backup file is just a set of SQL statements, so restoring it is very easy:
shell> mysql < backup_sunday_1_PM.sql
At this point, the data is restored to its state as of Sunday 1 PM. To restore the changes made since then, we must use the incremental backups, that is, the `gbichot2-bin.000007' and `gbichot2-bin.000008' binary log files. Fetch them if necessary from where they were backed up, and then process their contents like this:
shell> mysqlbinlog gbichot2-bin.000007 gbichot2-bin.000008 | mysql
We now have recovered the data to its state as of Tuesday 1 PM, but still
are missing the changes from that date to the date of the crash. To not
miss them, we would have needed to have the MySQL server store its MySQL
binary logs into a safe location (RAID disks, SAN, ...) different from the
place where it stores its data files, so that these logs were not in the
destroyed disk. (That is, we can start the server with a --log-bin
option that specifies a location on a different physical device than the
one on which the data directory resides. That way, the logs are not lost
even if the device containing the directory is.) If we had done this,
we would have the `gbichot2-bin.000009' at hand, and we could apply
it to restore the most recent data changes with no loss how it was at the
moment of the crash.
In case of an operating system crash or power failure, InnoDB
itself does all the job of recovering data. But to make sure that you can
sleep well, observe the following guidelines:
--log-bin option, or even
--log-bin=log_name, where the log file name is located on
some safe media different from the drive on which the data directory is
located. If you have such safe media, this can also be good for disk load
balancing (which results in a performance improvement).
mysqldump command given
earlier that makes an online, non-blocking backup.
FLUSH LOGS
or mysqladmin flush-logs.
The following text discusses how to use myisamchk to check or repair
MyISAM tables (tables with `.MYI' and `.MYD' files).
The same concepts apply to using isamchk to check or repair
ISAM tables (tables with `.ISM' and `.ISD' files).
See section 14 MySQL Storage Engines and Table Types.
You can use the myisamchk utility to get information about your
database tables or to check, repair, or optimize them. The following
sections describe how to invoke myisamchk (including a
description of its options), how to set up a table maintenance schedule,
and how to use myisamchk to perform its various functions.
Even though table repair with myisamchk is quite secure, it's
always a good idea to make a backup before doing a repair (or any
maintenance operation that could make a lot of changes to a table)
myisamchk operations that affect indexes can cause
FULLTEXT indexes to be rebuilt with full-text parameters that
are incompatible with the values used by the MySQL server. To avoid this,
read the instructions in
section 5.7.3.2 General Options for myisamchk.
In many cases, you may find it simpler to do MyISAM table maintenance
using the SQL statements that perform operations that myisamchk can
do:
MyISAM tables, use CHECK TABLE or
REPAIR TABLE.
MyISAM tables, use OPTIMIZE TABLE.
MyISAM tables, use ANALYZE TABLE.
These statements were introduced in different versions, but all are available
from MySQL 3.23.14 on.
See
section 13.5.2.1 ANALYZE TABLE Syntax,
section 13.5.2.3 CHECK TABLE Syntax,
section 13.5.2.5 OPTIMIZE TABLE Syntax,
and section 13.5.2.6 REPAIR TABLE Syntax.
The statements can be used directly, or by means of the mysqlcheck
client program, which provides a command-line interface to them.
One advantage of these statements over myisamchk is that the server
does all the work. With myisamchk, you must make sure that the server
does not use the tables at the same time. Otherwise, there can be unwanted
interaction between myisamchk and the server.
myisamchk Invocation Syntax
Invoke myisamchk like this:
shell> myisamchk [options] tbl_name
The options specify what you want myisamchk to do. They are
described in the following sections. You can also get a list of options by
invoking myisamchk --help.
With no options, myisamchk simply checks your table as the default
operation. To get more information or to tell myisamchk to take
corrective action, specify options as described in the following discussion.
tbl_name is the database table you want to check or repair. If you run
myisamchk somewhere other than in the database directory, you must
specify the path to the database directory, because myisamchk has no
idea where the
database is located. In fact, myisamchk doesn't actually care whether
the files you are working on are located in a database directory. You can
copy the files that correspond to a database table into some other location and
perform recovery operations on them there.
You can name several tables on the myisamchk command line if you
wish. You can also specify a table by naming its index file (the file with
the `.MYI' suffix). This allows you to specify all tables in a
directory by using the pattern `*.MYI'. For example, if you are in a
database directory, you can check all the MyISAM tables in that
directory like this:
shell> myisamchk *.MYI
If you are not in the database directory, you can check all the tables there by specifying the path to the directory:
shell> myisamchk /path/to/database_dir/*.MYI
You can even check all tables in all databases by specifying a wildcard with the path to the MySQL data directory:
shell> myisamchk /path/to/datadir/*/*.MYI
The recommended way to quickly check all MyISAM and ISAM
tables is:
shell> myisamchk --silent --fast /path/to/datadir/*/*.MYI shell> isamchk --silent /path/to/datadir/*/*.ISM
If you want to check all MyISAM and ISAM tables and repair any
that are corrupted, you can use the following commands:
shell> myisamchk --silent --force --fast --update-state \
-O key_buffer=64M -O sort_buffer=64M \
-O read_buffer=1M -O write_buffer=1M \
/path/to/datadir/*/*.MYI
shell> isamchk --silent --force -O key_buffer=64M \
-O sort_buffer=64M -O read_buffer=1M -O write_buffer=1M \
/path/to/datadir/*/*.ISM
These commands assume that you have more than 64MB free.
For more information about memory allocation with myisamchk, see
section 5.7.3.6 myisamchk Memory Usage.
You must ensure that no other program is using the tables while you are
running myisamchk. Otherwise, when you run myisamchk, it may
display the following error message:
warning: clients are using or haven't closed the table properly
This means that you are trying to check a table that has been updated by
another program (such as the mysqld server) that hasn't yet closed
the file or that has died without closing the file properly.
If mysqld is running, you must force it to flush any table
modifications that are still buffered in memory by using FLUSH
TABLES. You should then ensure that no one is using the tables while you
are running myisamchk. The easiest way to
avoid this problem is to use CHECK TABLE instead of myisamchk
to check tables.
myisamchk
The options described in this section can be used for any
type of table maintenance operation performed by myisamchk.
The sections following this one describe options that pertain only to specific
operations, such as table checking or repairing.
--help, -?
--debug=debug_options, -# debug_options
'd:t:o,file_name'.
--silent, -s
-s
twice (-ss) to make myisamchk very silent.
--verbose, -v
-d and
-e. Use -v multiple times (-vv, -vvv) for even
more output.
--version, -V
--wait, -w
mysqld with the --skip-external-locking option, the table can
be locked only by another myisamchk command.
You can also set the following variables by using --var_name=value
options:
| Variable | Default Value |
decode_bits | 9 |
ft_max_word_len | version-dependent |
ft_min_word_len | 4 |
ft_stopword_file | built-in list |
key_buffer_size | 523264 |
myisam_block_size | 1024 |
read_buffer_size | 262136 |
sort_buffer_size | 2097144 |
sort_key_blocks | 16 |
write_buffer_size | 262136 |
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
The possible myisamchk variables and their default values
can be examined with myisamchk --help:
sort_buffer_size is used when the keys are repaired by sorting
keys, which is the normal case when you use --recover.
key_buffer_size is used when you are checking the table with
--extend-check or when the keys are repaired by inserting keys
row by row into the table (like when doing normal inserts). Repairing
through the key buffer is used in the following cases:
--safe-recover.
CHAR, VARCHAR, or TEXT
columns, because the sort operation needs to store the complete key values
as it proceeds. If you have lots of temporary space and you can force
myisamchk to repair by sorting, you can use the --sort-recover
option.
Repairing through the key buffer takes much less disk space than using sorting, but is also much slower.
If you want a faster repair, set the key_buffer_size and
sort_buffer_size variables to about 25% of your available memory.
You can set both variables to large values, because only one of them is used
at a time.
myisam_block_size is the size used for index blocks. It is available
as of MySQL 4.0.0.
The ft_min_word_len and ft_max_word_len variables are
available as of MySQL 4.0.0. ft_stopword_file is available as of
MySQL 4.0.19.
ft_min_word_len and ft_max_word_len indicate the minimum and
maximum word length for FULLTEXT indexes. ft_stopword_file
names the stopword file. These need to be set under the following
circumstances.
If you use myisamchk to perform an operation that modifies
table indexes (such as repair or analyze), the FULLTEXT indexes
are rebuilt using the default full-text parameter values for minimum and
maximum word length and the stopword file unless you specify otherwise.
This can result in queries failing.
The problem occurs because these parameters are known only by the server.
They are not stored in MyISAM index files. To avoid the problem if
you have modified the minimum or maximum word length or the stopword file in
the server, specify the same ft_min_word_len, ft_max_word_len,
and ft_stopword_file values to myisamchk that you use for
mysqld. For example, if you have set the minimum word length to 3,
you can repair a table with myisamchk like this:
shell> myisamchk --recover --ft_min_word_len=3 tbl_name.MYI
To ensure that myisamchk and the server use the same values for
full-text parameters, you can place each one in both the [mysqld]
and [myisamchk] sections of an option file:
[mysqld] ft_min_word_len=3 [myisamchk] ft_min_word_len=3
An alternative to using myisamchk is to use the REPAIR TABLE,
ANALYZE TABLE, OPTIMIZE TABLE, or ALTER TABLE.
These statements are performed by the server, which knows the proper
full-text parameter values to use.
myisamchk
myisamchk supports the following options for table checking operations:
--check, -c
--check-only-changed, -C
--extend-check, -e
myisamchk or myisamchk --medium-check should
be able to determine whether there are any errors in the table.
If you are using --extend-check and have plenty of memory, setting
the key_buffer_size variable to a large value helps the repair
operation run faster.
--fast, -F
--force, -f
myisamchk finds any errors in the table.
The repair type is the same as that specified with the --repair or
-r option.
--information, -i
--medium-check, -m
--extend-check operation.
This finds only 99.99% of all errors, which should be good enough in most cases.
--read-only, -T
myisamchk
to check a table that is in use by some other application that doesn't
use locking, such as mysqld when run with the
--skip-external-locking option.
--update-state, -U
--check-only-changed option, but you shouldn't use this
option if the mysqld server is using the table and you are
running it with the --skip-external-locking option.
myisamchk
myisamchk supports the following options for table repair operations:
--backup, -B
--character-sets-dir=path
--correct-checksum
--data-file-length=#, -D #
--extend-check, -e
--force, -f
--keys-used=#, -k #
myisamchk, the option value indicates which indexes to update.
Each binary bit of the option value corresponds to a table index, where the
first index is bit 0.
For isamchk, the option value indicates that only the first # of
the table indexes should be updated.
In either case, an option value of 0 disables updates to all indexes, which
can be used to get faster inserts.
Deactivated indexes can be reactivated by using myisamchk -r
or (isamchk -r).
--no-symlinks, -l
myisamchk repairs the
table that a symlink points to. This option doesn't exist as of MySQL 4.0,
because versions from 4.0 on do not remove symlinks during repair operations.
--parallel-recover, -p
-r and -n, but creates
all the keys in parallel, using different threads.
This option was added in MySQL 4.0.2.
This is alpha code. Use at your own risk!
--quick, -q
myisamchk to modify the original data file in
case of duplicate keys.
--recover, -r
ISAM/MyISAM
tables). If you want to recover a table, this is the option to try
first. You should try -o only if myisamchk reports that the
table can't be recovered by -r. (In the unlikely case
that -r fails, the data file is still intact.)
If you have lots of memory, you should increase the value of
sort_buffer_size.
--safe-recover, -o
-r, but can handle a couple of very unlikely cases that
-r cannot. This recovery method also uses much less disk
space than -r. Normally, you should repair first with
-r, and then with -o only if -r fails.
If you have lots of memory, you should increase the value of
key_buffer_size.
--set-character-set=name
--set-collation in MySQL 4.1.1/5.0.3.
--set-collation=name
--sort-recover, -n
myisamchk to use sorting to resolve the keys even if the
temporary files should be very big.
--tmpdir=path, -t path
myisamchk uses the value of the TMPDIR environment variable.
Starting from MySQL 4.1, tmpdir can be set to a list of directory paths
that are used successively in round-robin fashion for creating
temporary files. The separator character between directory names should be
colon (`:') on Unix and semicolon (`;') on Windows, NetWare, and
OS/2.
--unpack, -u
myisampack.
myisamchk
myisamchk supports the following options for actions other than
table checks and repairs:
--analyze, -a
myisamchk --description --verbose tbl_name command or the
SHOW KEYS FROM tbl_name statement.
--description, -d
--set-auto-increment[=value], -A[value]
AUTO_INCREMENT numbering for new records to start at the given
value (or higher, if there are existing records with AUTO_INCREMENT
values this large). If value is not specified, AUTO_INCREMENT
number for new records begins with the largest value currently in the table,
plus one.
--sort-index, -S
--sort-records=#, -R #
SELECT and ORDER
BY operations that use this index. (The first time you use this option to
sort a table, it may be very slow.) To determine a table's index numbers,
use SHOW KEYS, which displays a table's indexes in the same order
that myisamchk sees them. Indexes are numbered beginning with 1.
myisamchk Memory Usage
Memory allocation is important when you run myisamchk.
myisamchk uses no more memory than you specify with the -O
options. If you are going to use myisamchk on very large tables,
you should first decide how much memory you want it to use. The default
is to use only about 3MB to perform repairs. By using larger values, you can
get myisamchk to operate faster. For example, if you have more
than 32MB RAM, you could use options such as these (in addition to any
other options you might specify):
shell> myisamchk -O sort=16M -O key=16M -O read=1M -O write=1M ...
Using -O sort=16M should probably be enough for most cases.
Be aware that myisamchk uses temporary files in TMPDIR. If
TMPDIR points to a memory filesystem, you may easily get out of
memory errors. If this happens, set TMPDIR to point at some directory
located on a filesystem
with more space and run myisamchk again.
When repairing, myisamchk also needs a lot of disk space:
--quick; in this
case, only the index file is re-created. This space is needed on the same
filesystem as the original data file! (The copy is created in the
same directory as the original.)
--recover or --sort-recover
(but not when using --safe-recover), you need space for a
sort buffer. The amount of space required is:
(largest_key + row_pointer_length) * number_of_rows * 2You can check the length of the keys and the
row_pointer_length
with myisamchk -dv tbl_name. This space is allocated in the temporary
directory (specified by TMPDIR or --tmpdir=path).
If you have a problem with disk space during repair, you can try to use
--safe-recover instead of --recover.
myisamchk for Crash Recovery
If you run mysqld with --skip-external-locking (which is the
default on some systems, such as Linux), you can't reliably use myisamchk
to check a table when mysqld is using the same table. If you
can be sure that no one is accessing the tables through mysqld
while you run myisamchk, you only have to do mysqladmin
flush-tables before you start checking the tables. If you can't
guarantee this, then you must stop mysqld while you
check the tables. If you run myisamchk while mysqld is updating
the tables, you may get a warning that a table is corrupt even when it
isn't.
If you are not using --skip-external-locking, you can use
myisamchk to check tables at any time. While you do this, all clients
that try to update the table wait until myisamchk is ready before
continuing.
If you use myisamchk to repair or optimize tables, you
must always ensure that the mysqld server is not using
the table (this also applies if you are using --skip-external-locking).
If you don't take down mysqld, you should at least do a
mysqladmin flush-tables before you run myisamchk.
Your tables may become corrupted if the server and myisamchk
access the tables simultaneously.
This section describes how to check for and deal with data corruption in MySQL databases. If your tables get corrupted frequently you should try to find the reason why. See section A.4.2 What to Do If MySQL Keeps Crashing.
The MyISAM table section contains reason for why a table could be
corrupted. See section 14.1.4 MyISAM Table Problems.
When performing crash recovery, it is important to understand that each
MyISAM table tbl_name in a database corresponds to three files
in the database directory:
| File | Purpose |
| `tbl_name.frm' | Definition (format) file |
| `tbl_name.MYD' | Data file |
| `tbl_name.MYI' | Index file |
Each of these three file types is subject to corruption in various ways, but problems occur most often in data files and index files.
myisamchk works by creating a copy of the `.MYD' data file
row by row. It ends the repair stage by removing the old `.MYD'
file and renaming the new file to the original file name. If you use
--quick, myisamchk does not create a temporary `.MYD'
file, but instead assumes that the `.MYD' file is correct and only
generates a new index file without touching the `.MYD' file. This is
safe, because myisamchk automatically detects whether the `.MYD'
file is corrupt and aborts the repair if it is. You can also specify
the --quick option twice to myisamchk. In this case,
myisamchk does not abort on some errors (such as duplicate-key
errors) but instead tries to resolve them by modifying the `.MYD'
file. Normally the use of two --quick options is useful only if you
have too little free disk space to perform a normal repair. In this case,
you should at least make a backup before running myisamchk.
MyISAM Tables for Errors
To check a MyISAM table, use the following commands:
myisamchk tbl_name
myisamchk without options or
with either the -s or --silent option.
myisamchk -m tbl_name
myisamchk -e tbl_name
-e means
``extended check''). It does a check-read of every key for each row to verify
that they indeed point to the correct row. This may take a long time for a
large table that has many indexes. Normally, myisamchk stops after
the first error it finds. If you want to obtain more information, you can
add the --verbose (-v) option. This causes myisamchk
to keep going, up through a maximum of 20 errors.
myisamchk -e -i tbl_name
-i option tells myisamchk to
print some informational statistics, too.
In most cases, a simple myisamchk with no arguments other than the
table name is sufficient to check a table.
The discussion in this section describes how to use myisamchk on
MyISAM tables (extensions `.MYI' and `.MYD'). If you
are using ISAM tables (extensions `.ISM' and `.ISD'),
you should use isamchk instead; the concepts are similar.
If you are using MySQL 3.23.16 and above, you can (and
should) use the CHECK TABLE and REPAIR TABLE statements to
check and repair MyISAM tables.
See section 13.5.2.3 CHECK TABLE Syntax
and section 13.5.2.6 REPAIR TABLE Syntax.
The symptoms of a corrupted table include queries that abort unexpectedly and observable errors such as these:
To get more information about the error you can run perror ###,
where ### is the error number. The following example shows how to use
perror to find the meanings for the most common error numbers that
indicate a problem with a table:
shell> perror 126 127 132 134 135 136 141 144 145 126 = Index file is crashed / Wrong file format 127 = Record-file is crashed 132 = Old database file 134 = Record was already deleted (or record file crashed) 135 = No more room in record file 136 = No more room in index file 141 = Duplicate unique key or constraint on write or update 144 = Table is crashed and last repair failed 145 = Table was marked as crashed and should be repaired
Note that error 135 (no more room in record file) and error 136 (no more
room in index file) are not errors that can be fixed by a simple repair. In
this case, you have to use ALTER TABLE to increase the
MAX_ROWS and AVG_ROW_LENGTH table option values:
ALTER TABLE tbl_name MAX_ROWS=xxx AVG_ROW_LENGTH=yyy;
If you don't know the current table option values, use SHOW CREATE TABLE
tbl_name.
For the other errors, you must repair your tables. myisamchk can
usually detect and fix most problems that occur.
The repair process involves up to four stages, described here. Before you
begin, you should change location to the database directory and check the
permissions of the table files. On Unix, make sure that they are readable by
the user that mysqld runs as (and to you, because you need to access
the files you are checking). If it turns out you need to modify files, they
must also be writable by you.
The options that you can use for table maintenance with myisamchk
and isamchk are described in several of the earlier subsections of
section 5.7.3 Table Maintenance and Crash Recovery.
The following section is for the cases where the above command fails or
if you want to use the extended features that myisamchk and
isamchk provide.
If you are going to repair a table from the command line, you must first
stop the mysqld server. Note that when you do
mysqladmin shutdown on a remote server, the mysqld server
is still alive for a while after mysqladmin returns, until
all queries are stopped and all keys have been flushed to disk.
Stage 1: Checking your tables
Run myisamchk *.MYI or myisamchk -e *.MYI if you have
more time. Use the -s (silent) option to suppress unnecessary
information.
If the mysqld server is down, you should use the --update-state
option to tell myisamchk to mark the table as 'checked'.
You have to repair only those tables for which myisamchk announces an
error. For such tables, proceed to Stage 2.
If you get weird errors when checking (such as out of
memory errors), or if myisamchk crashes, go to Stage 3.
Stage 2: Easy safe repair
Note: If you want a repair operation to go much faster, you should set the
values of the sort_buffer_size and key_buffer_size variables
each to about 25% of your available memory when running myisamchk
or isamchk.
First, try myisamchk -r -q tbl_name (-r -q means ``quick
recovery mode''). This attempts to repair the index file without
touching the data file. If the data file contains everything that it
should and the delete links point at the correct locations within the
data file, this should work, and the table is fixed. Start repairing the
next table. Otherwise, use the following procedure:
myisamchk -r tbl_name (-r means ``recovery mode''). This
removes incorrect records and deleted records from the data file and
reconstructs the index file.
myisamchk --safe-recover tbl_name.
Safe recovery mode uses an old recovery method that handles a few cases that
regular recovery mode doesn't (but is slower).
If you get weird errors when repairing (such as out of
memory errors), or if myisamchk crashes, go to Stage 3.
Stage 3: Difficult repair
You should reach this stage only if the first 16KB block in the index file is destroyed or contains incorrect information, or if the index file is missing. In this case, it's necessary to create a new index file. Do so as follows:
shell> mysql db_name mysql> SET AUTOCOMMIT=1; mysql> TRUNCATE TABLE tbl_name; mysql> quitIf your version of MySQL doesn't have
TRUNCATE TABLE, use
DELETE FROM tbl_name instead.
Go back to Stage 2. myisamchk -r -q should work. (This shouldn't
be an endless loop.)
As of MySQL 4.0.2, you can also use REPAIR TABLE tbl_name USE_FRM,
which performs the whole procedure automatically.
Stage 4: Very difficult repair
You should reach this stage only if the `.frm' description file has also crashed. That should never happen, because the description file isn't changed after the table is created:
myisamchk -r.
To coalesce fragmented records and eliminate wasted space resulting from
deleting or updating records, run myisamchk in recovery mode:
shell> myisamchk -r tbl_name
You can optimize a table in the same way by using the SQL OPTIMIZE TABLE
statement. OPTIMIZE TABLE does a repair of the table and a key
analysis, and also sorts the index tree to give faster key lookups.
There is also no possibility of unwanted interaction between a utility
and the server, because the server does all the work when you use
OPTIMIZE TABLE. See section 13.5.2.5 OPTIMIZE TABLE Syntax.
myisamchk also has a number of other options you can use to improve
the performance of a table:
-S, --sort-index
-R index_num, --sort-records=index_num
-a, --analyze
For a full description of the options, see section 5.7.3.1 myisamchk Invocation Syntax.
It is a good idea to perform table checks on a regular basis rather than
waiting for problems to occur.
One way to check and repair MyISAM tables is
with the CHECK TABLE and REPAIR TABLE statements.
These are available starting with MySQL 3.23.16.
See section 13.5.2.3 CHECK TABLE Syntax and
section 13.5.2.6 REPAIR TABLE Syntax.
Another way to check tables is to use myisamchk. For maintenance
purposes, you can use myisamchk -s. The -s option (short for
--silent) causes myisamchk to run in silent mode, printing
messages only when errors occur.
It's also a good idea to check tables when the server starts.
For example, whenever the machine has done a restart in the middle of an
update, you usually need to check all the tables that could have been
affected. (These are ``expected crashed tables.'')
To check MyISAM tables automatically, start the server with the --myisam-recover option, available as of MySQL 3.23.25.
If your server is too old to support this option, you could
add a test to
mysqld_safe that runs myisamchk to check all tables that have
been modified during the last 24 hours if there is an old `.pid'
(process ID) file left after a restart. (The `.pid' file is created by
mysqld when it starts and removed when it terminates normally. The
presence of a `.pid' file at system startup time indicates that
mysqld terminated abnormally.)
An even better test would be to check any table whose last-modified time is more recent than that of the `.pid' file.
You should also check your tables regularly during normal system
operation. At MySQL AB, we run a cron job to check all
our important tables once a week, using a line like this in a `crontab'
file:
35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI
This prints out information about crashed tables so that we can examine and repair them when needed.
Because we haven't had any unexpectedly crashed tables (tables that become corrupted for reasons other than hardware trouble) for a couple of years (this is really true), once a week is more than enough for us.
We recommend that to start with, you execute myisamchk -s each
night on all tables that have been updated during the last 24 hours,
until you come to trust MySQL as much as we do.
Normally, MySQL tables need little maintenance. If you are changing
MyISAM tables with dynamic-sized rows (tables with VARCHAR,
BLOB, or TEXT columns) or have tables with many deleted rows
you may want to defragment/reclaim space from the tables
from time to time (once a month?).
You can do this by using OPTIMIZE TABLE on the tables in question.
Or, if you can stop the mysqld server for a while, change location
into the data directory and use this command while the server is stopped:
shell> myisamchk -r -s --sort-index -O sort_buffer_size=16M */*.MYI
For ISAM tables, the command is similar:
shell> isamchk -r -s --sort-index -O sort_buffer_size=16M */*.ISM
To obtain a description of a table or statistics about it, use the commands shown here. We explain some of the information in more detail later:
myisamchk -d tbl_name
Runs myisamchk in ``describe mode'' to produce a description of
your table. If you start the MySQL server using the
--skip-external-locking option, myisamchk may report an error
for a table that is updated while it runs. However, because myisamchk
doesn't change the table in describe mode, there is no risk of
destroying data.
myisamchk -d -v tbl_name
Adding -v runs myisamchk in verbose mode so that it produces
more information about what it is doing.
myisamchk -eis tbl_name
Shows only the most important information from a table. This operation is slow
because it must read the entire table.
myisamchk -eiv tbl_name
This is like -eis, but tells you what is being done.
Sample output for some of these commands follows. They are based on a table with these data and index file sizes:
-rw-rw-r-- 1 monty tcx 317235748 Jan 12 17:30 company.MYD -rw-rw-r-- 1 davida tcx 96482304 Jan 12 18:35 company.MYM
Example of myisamchk -d output:
MyISAM file: company.MYI
Record format: Fixed length
Data records: 1403698 Deleted blocks: 0
Recordlength: 226
table description:
Key Start Len Index Type
1 2 8 unique double
2 15 10 multip. text packed stripped
3 219 8 multip. double
4 63 10 multip. text packed stripped
5 167 2 multip. unsigned short
6 177 4 multip. unsigned long
7 155 4 multip. text
8 138 4 multip. unsigned long
9 177 4 multip. unsigned long
193 1 text
Example of myisamchk -d -v output:
MyISAM file: company
Record format: Fixed length
File-version: 1
Creation time: 1999-10-30 12:12:51
Recover time: 1999-10-31 19:13:01
Status: checked
Data records: 1403698 Deleted blocks: 0
Datafile parts: 1403698 Deleted data: 0
Datafile pointer (bytes): 3 Keyfile pointer (bytes): 3
Max datafile length: 3791650815 Max keyfile length: 4294967294
Recordlength: 226
table description:
Key Start Len Index Type Rec/key Root Blocksize
1 2 8 unique double 1 15845376 1024
2 15 10 multip. text packed stripped 2 25062400 1024
3 219 8 multip. double 73 40907776 1024
4 63 10 multip. text packed stripped 5 48097280 1024
5 167 2 multip. unsigned short 4840 55200768 1024
6 177 4 multip. unsigned long 1346 65145856 1024
7 155 4 multip. text 4995 75090944 1024
8 138 4 multip. unsigned long 87 85036032 1024
9 177 4 multip. unsigned long 178 96481280 1024
193 1 text
Example of myisamchk -eis output:
Checking MyISAM file: company Key: 1: Keyblocks used: 97% Packed: 0% Max levels: 4 Key: 2: Keyblocks used: 98% Packed: 50% Max levels: 4 Key: 3: Keyblocks used: 97% Packed: 0% Max levels: 4 Key: 4: Keyblocks used: 99% Packed: 60% Max levels: 3 Key: 5: Keyblocks used: 99% Packed: 0% Max levels: 3 Key: 6: Keyblocks used: 99% Packed: 0% Max levels: 3 Key: 7: Keyblocks used: 99% Packed: 0% Max levels: 3 Key: 8: Keyblocks used: 99% Packed: 0% Max levels: 3 Key: 9: Keyblocks used: 98% Packed: 0% Max levels: 4 Total: Keyblocks used: 98% Packed: 17% Records: 1403698 M.recordlength: 226 Packed: 0% Recordspace used: 100% Empty space: 0% Blocks/Record: 1.00 Record blocks: 1403698 Delete blocks: 0 Recorddata: 317235748 Deleted data: 0 Lost space: 0 Linkdata: 0 User time 1626.51, System time 232.36 Maximum resident set size 0, Integral resident set size 0 Non physical pagefaults 0, Physical pagefaults 627, Swaps 0 Blocks in 0 out 0, Messages in 0 out 0, Signals 0 Voluntary context switches 639, Involuntary context switches 28966
Example of myisamchk -eiv output:
Checking MyISAM file: company Data records: 1403698 Deleted blocks: 0 - check file-size - check delete-chain block_size 1024: index 1: index 2: index 3: index 4: index 5: index 6: index 7: index 8: index 9: No recordlinks - check index reference - check data record references index: 1 Key: 1: Keyblocks used: 97% Packed: 0% Max levels: 4 - check data record references index: 2 Key: 2: Keyblocks used: 98% Packed: 50% Max levels: 4 - check data record references index: 3 Key: 3: Keyblocks used: 97% Packed: 0% Max levels: 4 - check data record references index: 4 Key: 4: Keyblocks used: 99% Packed: 60% Max levels: 3 - check data record references index: 5 Key: 5: Keyblocks used: 99% Packed: 0% Max levels: 3 - check data record references index: 6 Key: 6: Keyblocks used: 99% Packed: 0% Max levels: 3 - check data record references index: 7 Key: 7: Keyblocks used: 99% Packed: 0% Max levels: 3 - check data record references index: 8 Key: 8: Keyblocks used: 99% Packed: 0% Max levels: 3 - check data record references index: 9 Key: 9: Keyblocks used: 98% Packed: 0% Max levels: 4 Total: Keyblocks used: 9% Packed: 17% - check records and index references [LOTS OF ROW NUMBERS DELETED] Records: 1403698 M.recordlength: 226 Packed: 0% Recordspace used: 100% Empty space: 0% Blocks/Record: 1.00 Record blocks: 1403698 Delete blocks: 0 Recorddata: 317235748 Deleted data: 0 Lost space: 0 Linkdata: 0 User time 1639.63, System time 251.61 Maximum resident set size 0, Integral resident set size 0 Non physical pagefaults 0, Physical pagefaults 10580, Swaps 0 Blocks in 4 out 0, Messages in 0 out 0, Signals 0 Voluntary context switches 10604, Involuntary context switches 122798
Explanations for the types of information myisamchk produces are
given here. ``Keyfile'' refers to the index file. ``Record'' and ``row''
are synonymous.
MyISAM file
Name of the MyISAM (index) file.
File-version
Version of MyISAM format. Currently always 2.
Creation time
When the data file was created.
Recover time
When the index/data file was last reconstructed.
Data records
How many records are in the table.
Deleted blocks
How many deleted blocks still have reserved space.
You can optimize your table to minimize this space.
See section 5.7.3.10 Table Optimization.
Datafile parts
For dynamic record format, this indicates how many data blocks there are. For
an optimized table without fragmented records, this is the same as Data
records.
Deleted data
How many bytes of unreclaimed deleted data there are.
You can optimize your table to minimize this space.
See section 5.7.3.10 Table Optimization.
Datafile pointer
The size of the data file pointer, in bytes. It is usually 2, 3, 4, or 5
bytes. Most tables manage with 2 bytes, but this cannot be controlled
from MySQL yet. For fixed tables, this is a record address. For
dynamic tables, this is a byte address.
Keyfile pointer
The size of the index file pointer, in bytes. It is usually 1, 2, or 3
bytes. Most tables manage with 2 bytes, but this is calculated
automatically by MySQL. It is always a block address.
Max datafile length
How long the table data file can become, in bytes.
Max keyfile length
How long the table index file can become, in bytes.
Recordlength
How much space each record takes, in bytes.
Record format
The format used to store table rows.
The preceding examples use Fixed length.
Other possible values are Compressed and Packed.
table description
A list of all keys in the table. For each key, myisamchk displays
some low-level information:
Key
This key's number.
Start
Where in the record this index part starts.
Len
How long this index part is. For packed numbers, this should always be
the full length of the column. For strings, it may be shorter than the full
length of the indexed column, because you can index a prefix of a string
column.
Index
Whether a key value can exist multiple times in the index. Values are
unique or multip. (multiple).
Type
What data type this index part has. This is a MyISAM data type
with the options packed, stripped, or empty.
Root
Address of the root index block.
Blocksize
The size of each index block. By default this is 1024, but the value may be
changed at compile time when MySQL is built from source.
Rec/key
This is a statistical value used by the optimizer. It tells how many
records there are per value for this key. A unique key always has a
value of 1. This may be updated after a table is loaded (or greatly
changed) with myisamchk -a. If this is not updated at all, a default
value of 30 is given.
table description
lines for the ninth index. This indicates that it is a multiple-part index
with two parts.
Keyblocks used
What percentage of the keyblocks are used. When a table has just been
reorganized with myisamchk, as for the table in the examples, the
values are very high (very near the theoretical maximum).
Packed
MySQL tries to pack keys with a common suffix. This can only be used
for indexes on CHAR, VARCHAR columns. For
long indexed strings that have similar leftmost parts,
this can significantly reduce the space used. In the third example
above, the fourth key is 10 characters long and a 60% reduction in space is
achieved.
Max levels
How deep the B-tree for this key is. Large tables with long key values get high
values.
Records
How many rows are in the table.
M.recordlength
The average record length. This is the exact record length for tables
with fixed-length records, because all records have the same length.
Packed
MySQL strips spaces from the end of strings. The Packed
value indicates the percentage of savings achieved by doing this.
Recordspace used
What percentage of the data file is used.
Empty space
What percentage of the data file is unused.
Blocks/Record
Average number of blocks per record (that is, how many links a fragmented
record is composed of). This is always 1.0 for fixed-format tables. This
value should stay as close to 1.0 as possible. If it gets too big, you can
reorganize the table.
See section 5.7.3.10 Table Optimization.
Recordblocks
How many blocks (links) are used. For fixed format, this is the same as the number
of records.
Deleteblocks
How many blocks (links) are deleted.
Recorddata
How many bytes in the data file are used.
Deleted data
How many bytes in the data file are deleted (unused).
Lost space
If a record is updated to a shorter length, some space is lost. This is
the sum of all such losses, in bytes.
Linkdata
When the dynamic table format is used, record fragments are linked with
pointers (4 to 7 bytes each). Linkdata is the sum of the amount of
storage used by all such pointers.
If a table has been compressed with myisampack, myisamchk
-d prints additional information about each table column. See
section 8.2 myisampack, the MySQL Compressed Read-only Table Generator, for an example of this
information and a description of what it means.
This section describes how to configure the server to use different character sets. It also discusses how to set the server's time zone and enable per-connection time zone support.
By default, MySQL uses the ISO-8859-1 (Latin1) character set with sorting according to Swedish/Finnish rules. These defaults are suitable for the United States and most of western Europe.
All MySQL binary distributions are compiled with
--with-extra-charsets=complex. This adds code to all
standard programs that enables them to handle latin1 and all multi-byte
character sets within the binary. Other character sets are
loaded from a character-set definition file when needed.
The character set determines what characters are allowed in names. It also
determines how strings are sorted by the ORDER BY and GROUP
BY clauses of the SELECT statement.
You can change the character set with the --default-character-set
option when you start the server. The character sets available depend
on the --with-charset=charset and --with-extra-charsets=
list-of-charsets | complex | all | none options to configure, and the
character set configuration files listed in
`SHAREDIR/charsets/Index'.
See section 2.8.2 Typical configure Options.
As of MySQL 4.1.1, you can also change the character set collation with the
--default-collation option when you start the server. The collation
must be a legal collation for the default character set. (Use the
SHOW COLLATION statement to determine which collations are available
for each character set.)
See section 2.8.2 Typical configure Options.
If you change the character set when running MySQL, that may also
change the sort order. Consequently, you must run myisamchk -r -q
--set-character-set=charset on all tables, or your indexes may not be
ordered correctly.
When a client connects to a MySQL server, the server indicates to the client what the server's default character set is. The client switches to use this character set for this connection.
You should use mysql_real_escape_string() when escaping strings
for an SQL query. mysql_real_escape_string() is identical to the
old mysql_escape_string() function, except that it takes the MYSQL
connection handle as the first parameter so that the appropriate character set
can be taken into account when escaping characters.
If the client is compiled with different paths than where the server is installed and the user who configured MySQL didn't include all character sets in the MySQL binary, you must tell the client where it can find the additional character sets it needs if the server runs with a different character set than the client.
You can do this by specifying a --character-sets-dir option to
indicate the path to the directory in which the dynamic MySQL character
sets are stored. For example, you can put the following in an option file:
[client] character-sets-dir=/usr/local/mysql/share/mysql/charsets
You can force the client to use specific character set as follows:
[client] default-character-set=charset
This is normally unnecessary, however.
In MySQL 4.0, to get German sorting order, you should start mysqld
with a --default-character-set=latin1_de option. This affects server
behavior in several ways:
ä -> ae ö -> oe ü -> ue ß -> ss
LIKE, the one-character to two-character mapping
is not done. All letters are converted to uppercase. Accents are removed
from all letters except Ü, ü, Ö, ö,
Ä, and ä.
In MySQL 4.1 and up, character set and collation are specified separately.
You should select the latin1 character set and either the
latin1_german1_ci or latin1_german2_ci collation. For
example, to start the server with the latin1_german1_ci collation,
use the --character-set-server=latin1 and
--collation-server=latin1_german1_ci options.
For information on the differences between these two collations, see section 10.11.2 West European Character Sets.
By default, mysqld produces error messages in English, but they can
also be displayed in any of these other languages:
Czech, Danish, Dutch, Estonian, French, German, Greek,
Hungarian, Italian, Japanese, Korean, Norwegian, Norwegian-ny, Polish,
Portuguese, Romanian, Russian, Slovak, Spanish, or Swedish.
To start mysqld with a particular language for error messages, use the
--language or -L option. The option value can be a language name
or the full path to the error message file.
For example:
shell> mysqld --language=swedish
Or:
shell> mysqld --language=/usr/local/share/swedish
The language name should be specified in lowercase.
The language files are located (by default) in the `share/LANGUAGE' directory under the MySQL base directory.
To change the error message file, you should edit the `errmsg.txt' file, and then execute the following command to generate the `errmsg.sys' file:
shell> comp_err errmsg.txt errmsg.sys
If you upgrade to a newer version of MySQL, remember to repeat your changes with the new `errmsg.txt' file.
This section discusses the procedure for adding add another character set to MySQL. You must have a MySQL source distribution to use these instructions.
To choose the proper procedure, decide whether the character set is simple or complex:
For example, latin1 and danish are simple character sets,
whereas big5 and czech are complex character sets.
In the following procedures, the name of your character set is represented by MYSET.
For a simple character set, do the following:
ctype array takes up the first 257 words. The
to_lower[], to_upper[] and sort_order[] arrays take up
256 words each after that.
CHARSETS_AVAILABLE and
COMPILED_CHARSETS lists in configure.in.
For a complex character set, do the following:
ctype_MYSET,
to_lower_MYSET, and so on. These correspond to the arrays
for a simple character set. See section 5.8.4 The Character Definition Arrays.
/* * This comment is parsed by configure to create ctype.c, * so don't change it unless you know what you are doing. * * .configure. number_MYSET=MYNUMBER * .configure. strxfrm_multiply_MYSET=N * .configure. mbmaxlen_MYSET=N */The
configure program uses this comment to include
the character set into the MySQL library automatically.
The strxfrm_multiply and mbmaxlen lines are explained in
the following sections. You need include them only if you need the string
collating functions or the multi-byte character set functions,
respectively.
my_strncoll_MYSET()
my_strcoll_MYSET()
my_strxfrm_MYSET()
my_like_range_MYSET()
CHARSETS_AVAILABLE and
COMPILED_CHARSETS lists in configure.in.
The `sql/share/charsets/README' file includes additional instructions.
If you want to have the character set included in the MySQL
distribution, mail a patch to the MySQL internals mailing list.
See section 1.4.1.1 The MySQL Mailing Lists.
to_lower[] and to_upper[] are simple arrays that hold the
lowercase and uppercase characters corresponding to each member of the
character set. For example:
to_lower['A'] should contain 'a' to_upper['a'] should contain 'A'
sort_order[] is a map indicating how characters should be ordered for
comparison and sorting purposes. Quite often (but not for all character sets)
this is the same as to_upper[], which means that sorting is
case-insensitive. MySQL sorts characters based on the values of
sort_order[] elements. For more complicated sorting rules, see
the discussion of string collating in section 5.8.5 String Collating Support.
ctype[] is an array of bit values, with one element for one character.
(Note that to_lower[], to_upper[], and sort_order[]
are indexed by character value, but ctype[] is indexed by character
value + 1. This is an old legacy convention to be able to handle EOF.)
You can find the following bitmask definitions in `m_ctype.h':
#define _U 01 /* Uppercase */ #define _L 02 /* Lowercase */ #define _N 04 /* Numeral (digit) */ #define _S 010 /* Spacing character */ #define _P 020 /* Punctuation */ #define _C 040 /* Control character */ #define _B 0100 /* Blank */ #define _X 0200 /* heXadecimal digit */
The ctype[] entry for each character should be the union of the
applicable bitmask values that describe the character. For example,
'A' is an uppercase character (_U) as well as a
hexadecimal digit (_X), so ctype['A'+1] should contain the
value:
_U + _X = 01 + 0200 = 0201
If the sorting rules for your language are too complex to be handled
with the simple sort_order[] table, you need to use the string
collating functions.
The best documentation for this is the existing character sets.
Look at the big5, czech, gbk,
sjis, and tis160 character sets for examples.
You must specify the strxfrm_multiply_MYSET=N value in the
special comment at the top of the file. N should be set to
the maximum ratio the strings may grow during my_strxfrm_MYSET (it
must be a positive integer).
If you want to add support for a new character set that includes multi-byte characters, you need to use the multi-byte character functions.
The best documentation for this is the existing character sets.
Look at the euc_kr, gb2312,
gbk, sjis, and ujis character sets for
examples. These are implemented in the `ctype-charset.c' files
in the `strings' directory.
You must specify the mbmaxlen_MYSET=N value in the special
comment at the top of the source file. N should be set to the
size in bytes of the largest character in the set.
If you try to use a character set that is not compiled into your binary, you might run into the following problems:
--character-sets-dir
option when you run the program in question.
ERROR 1105: File '/usr/local/share/mysql/charsets/?.conf' not found (Errcode: 2)In this case, you should either get a new
Index file or manually add
the name of any missing character sets to the current file.
For MyISAM tables, you can check the character set name and number for a
table with myisamchk -dvv tbl_name.
Before MySQL 4.1.3, you can set the time zone for the server with the
--timezone=timezone_name option to mysqld_safe. You can
also set it by setting the TZ environment variable before you
start mysqld.
The allowable values for --timezone or TZ are
system-dependent. Consult your operating system documentation to see
what values are acceptable.
Beginning with MySQL 4.1.3, the server maintains several time zone settings:
system_time_zone
system variable.
time_zone system variable
indicates the time zone the server currently is operating in. The initial
value is 'SYSTEM', which indicates that the server time zone is the
same as the system time zone. The initial value can be specified explicitly
with the --default-time-zone=timezone option. If you have the
SUPER privilege, you can set the global value at runtime with this
statement:
mysql> SET GLOBAL time_zone = timezone;
time_zone variable. Initially
this is the same as the global time_zone variable, but can be
reset with this statement:
mysql> SET time_zone = timezone;
The current values of the global and per-connection time zones can be retrieved like this:
mysql> SELECT @@global.time_zone, @@session.time_zone;
timezone values can be given as strings indicating an offset
from UTC, such as '+10:00' or '-6:00'. If the time zone-related
tables in the mysql database have been created and populated, you
can also used named time zones, such as 'Europe/Helsinki',
'US/Eastern', or 'MET'. The value 'SYSTEM' indicates
that the time zone should be the same as the system time zone. Time zone
names are not case sensitive.
The MySQL installation procedure creates the time zone tables in the
mysql database, but does not load them. You must do so manually.
(If you are upgrading to MySQL 4.1.3 or later from an earlier version, you
should create the tables by upgrading your mysql database. Use the
instructions in section 2.10.7 Upgrading the Grant Tables.)
If your system has its own zoneinfo database (the set of files describing
time zones), you should use the mysql_tzinfo_to_sql program for
filling the time zone tables. Examples of such systems are Linux, FreeBSD,
Sun Solaris, and Mac OS X. One likely location for these files is the
`/usr/share/zoneinfo' directory. If your system does not have a
zoneinfo database, you can use the downloadable package described later in
this section.
The mysql_tzinfo_to_sql program is used to load the time zone
tables. On the command line, pass the zoneinfo directory pathname to
mysql_tzinfo_to_sql and send the output into the mysql
program. For example:
shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
mysql_tzinfo_to_sql reads your system's time zone files and
generates SQL statements from them. mysql processes those
statements to load the time zone tables.
mysql_tzinfo_to_sql also can be used to load a single time zone
file, and to generate leap second information.
To load a single time zone file tz_file that corresponds to a
time zone name tz_name, invoke mysql_tzinfo_to_sql like this:
shell> mysql_tzinfo_to_sql tz_file tz_name | mysql -u root mysql
If your time zone needs to account for leap seconds, initialize the leap second information like this, where tz_file is the name of your time zone file:
shell> mysql_tzinfo_to_sql --leap tz_file | mysql -u root mysql
If your system doesn't have a zoneinfo database (for example, Windows or
HP-UX), you can use the package of pre-built time zone tables that is
available for download at
http://dev.mysql.com/downloads/timezones.html. This package contains
`.frm', `.MYD', and `.MYI' files for the MyISAM time
zone tables. These tables should belong to the mysql database, so
you should place the files in the `mysql' subdirectory of your MySQL
server's data directory. The server should be shut down while you do this.
Warning! Please don't use the downloadable package if your system
has a zoneinfo database. Use the mysql_tzinfo_to_sql utility
instead! Otherwise, you may cause a difference in datetime handling between
MySQL and other applications on your system.
For information about time zone settings in replication setup please look into section 6.7 Replication Features and Known Problems.
MySQL has several different log files that can help you find
out what's going on inside mysqld:
| Log File | Types of Information Logged to File |
| The error log | Logs problems encountered starting, running, or
stopping mysqld.
|
| The isam log | Logs all changes to the ISAM tables. Used only for debugging the isam code.
|
| The query log | Logs established client connections and executed statements. |
| The update log | Logs statements that change data. This log is deprecated. |
| The binary log | Logs all statements that change data. Also used for replication. |
| The slow log | Logs all queries that took more than long_query_time seconds to execute or didn't use indexes.
|
By default, all logs are created in the mysqld data directory. You can
force mysqld to close and reopen the log files (or in some cases
switch to a new log) by flushing the logs. Log flushing occurs when you
issue a FLUSH LOGS statement or execute mysqladmin flush-logs or
mysqladmin refresh.
See section 13.5.5.2 FLUSH Syntax.
If you are using MySQL replication capabilities, slave replication servers maintain additional log files called relay logs. These are discussed in section 6 Replication in MySQL.
The error log file contains information indicating when mysqld
was started and stopped and also any critical errors that occur while the
server is running.
If mysqld dies unexpectedly and mysqld_safe needs to
restart it, mysqld_safe writes a restarted
mysqld message to the error log. If
mysqld notices a table that needs to be automatically checked or
repaired, it writes a message to the error log.
On some operating systems, the error log contains a stack trace if
mysqld dies. The trace can be used to determine where
mysqld died. See section E.1.4 Using a Stack Trace.
Beginning with MySQL 4.0.10, you can specify where mysqld stores the
error log file with the --log-error[=file_name] option. If no
file_name value is given, mysqld uses the name
`host_name.err' and writes the file in the data directory.
(Prior to MySQL 4.0.10, the Windows error log name is `mysql.err'.)
If you execute FLUSH LOGS, the error log is renamed with a suffix
of -old and mysqld creates a new empty log file.
In older MySQL versions on Unix, error log handling was done by
mysqld_safe which redirected the error file to
host_name.err. You could change this filename by specifying a
--err-log=file_name option to mysqld_safe.
If you don't specify --log-error, or (on Windows) if you use the
--console option, errors are written to stderr, the standard error
output. Usually this is your terminal.
On Windows, error output is always written to the .err file if
--console is not given.
If you want to know what happens within mysqld, you should start
it with the --log[=file_name] or -l [file_name] option.
If no file_name value is given, the default name is
`host_name.log'
This logs all connections and statements to the log file.
This log can be very useful when you suspect an error in a client and want
to know exactly what the client sent to mysqld.
Older versions of the mysql.server script (from MySQL 3.23.4 to 3.23.8)
pass a --log option to safe_mysqld to enable the general query log.
If you need better performance when you start using MySQL in a production
environment, you can remove the --log option from mysql.server
or change it to --log-bin. See section 5.9.4 The Binary Log.
mysqld writes statements to the query log in the order that it
receives them. This may be different from the order in which they are
executed. This is in contrast to the update log and the binary log, which
are written after the query is executed, but before any locks are released.
(The query log also contains all statements, whereas the update and binary
logs do not contain statements that only select data.)
Server restarts and log flushing do not cause a new general query log file to be generated (although flushing closes and reopens it). On Unix, you can rename the file and create a new one by using the following commands:
shell> mv hostname.log hostname-old.log shell> mysqladmin flush-logs shell> cp hostname-old.log to-backup-directory shell> rm hostname-old.log
On Windows, you cannot rename the log file while the server has it open. You must stop the server and rename the log. Then restart the server to create a new log.
Note: The update log has been deprecated and replaced by the binary log. See section 5.9.4 The Binary Log. The binary log can do anything the old update log could do, and more. The update log is unavailable as of MySQL 5.0.0.
When started with the --log-update[=file_name] option,
mysqld writes a log file containing all SQL statements that update
data. If no file_name value is given, the default name is name of the host
machine. If a filename is given, but it doesn't contain a leading path, the file
is written in the data directory. If `file_name' doesn't have an
extension, mysqld creates log files with names of the form
file_name.###, where ### is a number that is incremented each
time you start the server or flush the logs.
Note: For this naming scheme to work, you must not create your own files with the same names as those that might be used for the log file sequence.
Update logging is smart because it logs only statements that really update
data. So, an UPDATE or a DELETE with a WHERE that finds no
rows is not written to the log. It even skips UPDATE statements that
set a column to its existing value.
The update logging is done immediately after a query completes but before any locks are released or any commit is done. This ensures that statements are logged in execution order.
If you want to update a database from update log files, you could do the following (assuming that your update logs have names of the form `file_name.###'):
shell> ls -1 -t -r file_name.[0-9]* | xargs cat | mysql
ls is used to sort the update log filenames into the right order.
This can be useful if you have to revert to backup files after a crash and you want to redo the updates that occurred between the time of the backup and the crash.
The binary log has replaced the old update log, which is unavailable starting from MySQL 5.0. The binary log contains all information that is available in the update log in a more efficient format and in a manner that is transactionally safe.
The binary log contains all statements which updated data or (starting from
MySQL 4.1.3) could potentially have updated it (for example, a DELETE
which matched no rows).
The binary log also contains information about how long each statement took that updated the database. It doesn't contain statements that don't modify any data. If you want to log all statements (for example, to identify a problem query) you should use the general query log. See section 5.9.2 The General Query Log.
The primary purpose of the binary log is to be able to update the database during a restore operation as fully as possible, because the binary log contains all updates done after a backup was made.
The binary log is also used on master replication servers as a record of the statements to be sent to slave servers. See section 6 Replication in MySQL.
Running the server with the binary log enabled makes performance about 1% slower. However, the benefits of the binary log for restore operations and in allowing you to set up replication generally outweigh this minor performance decrement.
When started with the --log-bin[=file_name] option, mysqld
writes a log file containing all SQL commands that update data. If no
file_name value is given, the default name is the name of the host machine followed
by -bin. If file name is given, but it doesn't contain a path, the
file is written in the data directory.
It is recommended to specify a filename, see section 1.5.7.4 Open Bugs and Design Deficiencies in MySQL for the reason.
If you supply an extension in the log name (for example,
--log-bin=file_name.extension), the
extension is silently removed and ignored.
mysqld appends a numeric extension to the binary log name. The number
is incremented each time you start the server or flush the logs.
A new binary log also is created
automatically when the current log's size reaches
max_binlog_size. A binary log may become larger than
max_binlog_size if you are using large transactions: A transaction is
written to the binary log in one piece, never split between binary logs.
To be able to know which different binary log files have been used,
mysqld also creates a binary log index file that
contains the name of all used binary log files. By default this has the
same name as the binary log file, with the extension '.index'.
You can change the name of the binary log index file with the
--log-bin-index[=file_name] option.
You should not manually edit this file while mysqld is running;
doing so would confuse mysqld.
You can delete all binary log files with the RESET MASTER statement,
or only some of them with PURGE MASTER LOGS.
See section 13.5.5.5 RESET Syntax and section 13.6.1 SQL Statements for Controlling Master Servers.
The binary log format has some known limitations which can affect recovery from
backups, especially in old versions. These caveats which also affect
replication are listed at section 6.7 Replication Features and Known Problems. One caveat which does not
affect replication but only recovery with mysqlbinlog: before MySQL 4.1,
mysqlbinlog could not prepare output suitable for mysql if
the binary log contained interlaced statements originating from different
clients that used temporary tables of the same name. This is fixed in MySQL
4.1. However, the problem still existed for LOAD DATA INFILE statements
until it was fixed in MySQL 4.1.8.
You can use the following options to mysqld to affect what is logged
to the binary log. See also the discussion that follows this option list.
--binlog-do-db=db_name
USE) is db_name. All
other databases that are not explicitly mentioned are ignored. If you use
this, you should ensure that you only do updates in the current database.
Observe that there is an exception to the CREATE/ALTER/DROP
DATABASE statements, which use the database manipulated to decide if
it should log the statement rather than the current database.
An example of what does not work as you might expect: If the server is
started with binlog-do-db=sales, and you do
USE prices; UPDATE sales.january SET amount=amount+1000;,
this statement does not get written into the binary log.
--binlog-ignore-db=db_name
USE) is
db_name should not be stored in the binary log. If
you use this, you should ensure that you only do updates in the current
database.
An example of what does not work as you might expect: If the server is
started with binlog-ignore-db=sales, and you do
USE prices; UPDATE sales.january SET amount=amount+1000;,
this statement is not written into the binary log.
Similar to the case for --binlog-do-db, there is an exception
to the CREATE/ALTER/DROP DATABASE statements, which use the
database manipulated to decide if it should log the statement rather
than the current database.
To log or ignore multiple databases, specify the appropriate option multiple times, once for each database.
The rules for logging or ignoring updates to the binary log are
evaluated according to the following rules. Observe that there is an
exception for CREATE/ALTER/DROP DATABASE statements. In those
cases, the database being created/altered/dropped replace the
current database in the rules below.
binlog-do-db or binlog-ignore-db rules?
binlog-do-db or
binlog-ignore-db or both). Is there a current database (has any
database been selected by USE?)?
binlog-do-db rules?
binlog-do-db
rules?
binlog-ignore-db rules.
Does the current database match any of the binlog-ignore-db
rules?
For example, a slave running with only binlog-do-db=sales
does not write to the binary log any statement whose current database is
different from sales (in other words, binlog-do-db can
sometimes mean ``ignore other databases'').
If you are using replication, you should not delete old binary log
files until you are sure that no slave still needs to use them.
One way to do this is to do mysqladmin flush-logs once a day and then
remove any logs that are more than three days old. You can remove them
manually, or preferably using PURGE MASTER LOGS
(see section 13.6.1 SQL Statements for Controlling Master Servers), which also safely updates the binary
log index file for you (and which can take a date argument since
MySQL 4.1)
A client with the SUPER privilege can disable binary
logging of its own statements by using a SET
SQL_LOG_BIN=0 statement. See section 13.5.3 SET Syntax.
You can examine the binary log file with the mysqlbinlog utility.
This can be useful when you want to reprocess statements in the log.
For example, you can update a MySQL server from the binary log
as follows:
shell> mysqlbinlog log-file | mysql -h server_name
See section 8.5 The mysqlbinlog Binary Log Utility for more information on the
mysqlbinlog utility and how to use it.
If you are using transactions, you must use the MySQL binary log for backups instead of the old update log.
The binary logging is done immediately after a query completes but before any locks are released or any commit is done. This ensures that the log is logged in the execution order.
Updates to non-transactional tables are stored in the binary log
immediately after execution. For transactional tables such as BDB
or InnoDB tables, all updates (UPDATE, DELETE,
or INSERT) that change tables are cached until a COMMIT
statement is received by the server. At that point, mysqld writes the
whole transaction to the binary log before the COMMIT is executed.
When the thread that handles the transaction starts, it allocates a buffer
of binlog_cache_size to buffer queries. If a statement is bigger
than this, the thread opens a temporary file to store the transaction. The
temporary file is deleted when the thread ends.
The Binlog_cache_use status variable shows the number of transactions
that used this buffer (and possibly a temporary file) for storing statements.
The Binlog_cache_disk_use status variable shows how many of those
transactions actually did have to use a temporary file. These two variables
can be used for tuning binlog_cache_size to a large enough value that
avoids the use of temporary files.
The max_binlog_cache_size (default 4GB) can be used to restrict the
total size used to cache a multiple-statement transaction. If a transaction
is larger than this, it fails and rolls back.
If you are using the update log or binary log, concurrent inserts are
converted to normal inserts when using CREATE ... SELECT or
INSERT ... SELECT.
This is to ensure that you can re-create an exact copy of your tables by
applying the log on a backup.
The binary log format is different in versions 3.23, 4.0, and 5.0.0. Those format changes were required to implement enhancements to replication. MySQL 4.1 has the same binary log format as 4.0. See section 6.5 Replication Compatibility Between MySQL Versions.
By default, the binary log is not synchronized to disk at each write. So
if the operating system or machine (not only the MySQL server) crashes
there is a chance that the last statements of the binary log are lost. To
prevent this, you can make the binary log be synchronized to disk after
every Nth binary log write, with the sync_binlog global variable
(1 being the safest value, but also the slowest). See section 5.2.3 Server System Variables. Even with this set to 1, there is still the chance of an
inconsistency between the tables content and the binary log content in
case of crash. For example, if using InnoDB tables, and the MySQL
server processes a COMMIT statement, it writes the whole transaction
to the binary log and then commits this transaction into InnoDB. If
it crashes between those two operations, at restart the transaction is
rolled back by InnoDB but still exist in the binary log. This problem can be
solved with the --innodb-safe-binlog option (available starting from
MySQL 4.1.3), which adds consistency between the content of InnoDB
tables and the binary log. For this option to really bring safety to you,
the MySQL server should also be configured to synchronize to disk, at every
transaction, the binary log (sync_binlog=1) and (which is true by
default) the InnoDB logs. The effect of this option is that at restart
after a crash,
after doing a rollback of transactions, the MySQL server cuts rolled
back InnoDB transactions from the binary log. This ensures that the
binary log reflects the exact data of InnoDB tables, and so, that
the slave remains in sync with the master (not receiving a statement which
has been rolled back). Note that --innodb-safe-binlog can be used
even if the MySQL server updates other storage engines than InnoDB. Only
statements/transactions affecting InnoDB tables are subject to
being removed from the binary log at InnoDB's crash recovery. If at
crash recovery the MySQL server discovers that the binary log is shorter
than it should have been (that is, it lacks at least one successfully committed
InnoDB transaction), which should not happen if sync_binlog=1
and the disk/filesystem do an actual sync when they are requested to (some
don't), it prints an error message ("The binary log <name> is shorter
than its expected size"). In this case, this binary log is not correct,
replication should be restarted from a fresh master's data snapshot.
Before MySQL 4.1.9, a write to a binary log file or binary log index file
that failed due to a full disk or an exceeded quota resulted in corruption
of the file. Starting from MySQL 4.1.9, writes to the binary log file and
binary log index file are handled the same way as writes to MyISAM
tables.
See section A.4.3 How MySQL Handles a Full Disk.
When started with the --log-slow-queries[=file_name] option,
mysqld writes a log file containing all SQL statements that took
more than long_query_time seconds to execute. The time to acquire
the initial table locks are not counted as execution time.
If no file_name value is given, the default is the name of the
host machine with a suffix of -slow.log. If a filename is given,
but doesn't contain a path, the file is written in the data directory.
A statement is logged to the slow query log after it has been executed and after all locks have been released. Log order may be different from execution order.
The slow query log can be used to find queries that take a long time to
execute and are therefore candidates for optimization. However, examining a long
slow query log can become a difficult task. To make this easier, you
can pipe the slow query log through the mysqldumpslow command to
get a summary of the queries that appear in the log.
Before MySQL 4.1, if you also use --log-long-format when logging
slow queries, then queries that are not using indexes are logged as well.
queries that are not using indexes also are logged to the slow query log.
--log-long-format is deprecated as of MySQL version 4.1, when
--log-short-format was introduced. (Long log format is the default
setting since version 4.1.) Also note that starting with MySQL 4.1,
the --log-queries-not-using-indexes option is available for the
purpose of logging queries that do not use indexes to the slow query log.
See section 5.2.1 mysqld Command-Line Options.
Queries handled by the query cache are not added to the slow query log, nor are queries that would not benefit from the presence of an index because the table has zero rows or one row.
The MySQL Server can create a number of different log files that make it easy to see what is going on. See section 5.9 The MySQL Log Files. However, you must clean up these files regularly to ensure that the logs don't take up too much disk space.
When using MySQL with logging enabled, you may want to back up and remove old log files from time to time and tell MySQL to start logging to new files. See section 5.7.1 Database Backups.
On a Linux (Red Hat) installation, you can use the
mysql-log-rotate script for this. If you installed MySQL
from an RPM distribution, the script should have been installed
automatically. You should be careful with this script if you are
using the binary log for replication! (You should not remove binary logs until
you are certain that their contents have been processed by all slaves.)
On other systems, you must install a short script yourself that you
start from cron to handle log files.
You can force MySQL to start using new log files by using
mysqladmin flush-logs or by using the SQL statement FLUSH LOGS.
If you are using MySQL 3.21, you must use mysqladmin refresh.
A log flushing operation does the following:
--log) or slow query logging
(--log-slow-queries) is used, closes and reopens the log file
(`mysql.log' and ``hostname`-slow.log' as default).
--log-update) or binary logging (--log-bin)
is used, closes the log and opens a new log file with a higher sequence number.
If you are using only an update log, you only have to rename the log file and then flush the logs before making a backup. For example, you can do something like this:
shell> cd mysql-data-directory shell> mv mysql.log mysql.old shell> mysqladmin flush-logs
Then make a backup and remove `mysql.old'.
In some cases, you might want to run multiple mysqld servers
on the same machine. You might want to test a new
MySQL release while leaving your existing production setup undisturbed.
Or you may want to give different users access to different mysqld
servers that they manage themselves. (For example, you might be an
Internet Service Provider that wants to provide independent MySQL
installations for different customers.)
To run multiple servers on a single machine, each server must have unique values for several operating parameters. These can be set on the command line or in option files. See section 4.3 Specifying Program Options.
At least the following options must be different for each server:
--port=port_num
--port controls the port number for TCP/IP connections.
--socket=path
--socket controls the Unix socket file path on Unix and the name of the
named pipe on Windows. On Windows, it's necessary to specify distinct pipe names
only for those servers that support named pipe connections.
--shared-memory-base-name=name
--pid-file=path
If you use the following log file options, they must be different for each server:
--log=path
--log-bin=path
--log-update=path
--log-error=path
--log-isam=path
--bdb-logdir=path
Log file options are described in section 5.9.6 Log File Maintenance.
If you want more performance, you can also specify the following options differently for each server, to spread the load between several physical disks:
--tmpdir=path
--bdb-tmpdir=path
Having different temporary directories is also recommended, to make it easier to determine which MySQL server created any given temporary file.
Generally, each server should also use a different data directory, which is
specified using the --datadir=path option.
Warning: Normally you should never have two servers that
update data in the same databases! This may lead to unpleasant
surprises if your operating system doesn't support fault-free system
locking!
If (despite this warning) you run multiple servers using
the same data directory and they have logging enabled, you must
use the appropriate options to specify log filenames that are
unique to each server. Otherwise, the servers try to log to
the same files.
Please note that this kind of setup only works with ISAM,
MyISAM and MERGE tables, and not with any of the other
storage engines.
The warning against sharing a data directory among servers also applies in an NFS environment. Allowing multiple MySQL servers to access a common data directory over NFS is a bad idea!
lockd
daemon, but at the moment there is no platform that performs
locking 100% reliably in every situation.
Make it easy for yourself: Forget about sharing a data directory among servers over NFS. A better solution is to have one computer that contains several CPUs and use an operating system that handles threads efficiently.
If you have multiple MySQL installations in different locations, normally
you can specify the base installation directory for each server with the
--basedir=path option to cause each server to use a different data
directory, log files, and PID file. (The defaults for all these values are
determined relative to the base directory). In that case, the only other
options you need to specify are the --socket and --port
options. For example, suppose that you install different versions of MySQL using
`tar' file binary distributions. These install in different
locations, so you can start the server for each installation using the
command bin/mysqld_safe under its corresponding base directory.
mysqld_safe determines the proper
--basedir option to pass to mysqld, and you need specify
only the --socket and --port options to mysqld_safe.
(For versions of MySQL older than 4.0, use safe_mysqld
rather than mysqld_safe.)
As discussed in the following sections, it is possible to start additional servers by setting environment variables or by specifying appropriate command-line options. However, if you need to run multiple servers on a more permanent basis, it is more convenient to use option files to specify for each server those option values that must be unique to it.
You can run multiple servers on Windows by starting them manually from the command line, each with appropriate operating parameters. On Windows NT-based systems, you also have the option of installing several servers as Windows services and running them that way. General instructions for running MySQL servers from the command line or as services are given in section 2.3 Installing MySQL on Windows. This section describes how to make sure that you start each server with different values for those startup options that must be unique per server, such as the data directory. These options are described in section 5.10 Running Multiple MySQL Servers on the Same Machine.
To start multiple servers manually from the command line, you can specify the appropriate options on
the command line or in an option file. It's more convenient to place the
options in an option file, but it's necessary to make sure that each server
gets its own set of options. To do this, create an option file for each
server and tell the server the filename with a --defaults-file option
when you run it.
Suppose that you want to run mysqld on port 3307 with a
data directory of `C:\mydata1', and mysqld-max on port 3308 with a
data directory of `C:\mydata2'. (To do this, make sure that before you
start the servers, each data directory exists and has its own copy of the
mysql database that contains the grant tables.)
Then create two option files. For example, create one file named `C:\my-opts1.cnf' that looks like this:
[mysqld] datadir = C:/mydata1 port = 3307
Create a second file named `C:\my-opts2.cnf' that looks like this:
[mysqld] datadir = C:/mydata2 port = 3308
Then start each server with its own option file:
C:\> C:\mysql\bin\mysqld --defaults-file=C:\my-opts1.cnf C:\> C:\mysql\bin\mysqld-max --defaults-file=C:\my-opts2.cnf
On NT, each server starts in the foreground (no new prompt appears until the server exits later); you'll need to issue those two commands in separate console windows.
To shut down the servers, you must connect to the appropriate port number:
C:\> C:\mysql\bin\mysqladmin --port=3307 shutdown C:\> C:\mysql\bin\mysqladmin --port=3308 shutdown
Servers configured as just described allow clients to connect over
TCP/IP. If your version of Windows supports named pipes and you also want
to allow named pipe connections, use the mysqld-nt or
mysqld-max-nt servers and specify options that enable the named pipe
and specify its name. Each server that supports named pipe connections must
use a unique pipe name. For example, the `C:\my-opts1.cnf' file might
be written like this:
[mysqld] datadir = C:/mydata1 port = 3307 enable-named-pipe socket = mypipe1
Then start the server this way:
C:\> C:\mysql\bin\mysqld-nt --defaults-file=C:\my-opts1.cnf
Modify `C:\my-opts2.cnf' similarly for use by the second server.
On NT-based systems, a MySQL server can be run as a Windows service. The procedures for installing, controlling, and removing a single MySQL service are described in section 2.3.12 Starting MySQL as a Windows Service.
As of MySQL 4.0.2, you can install multiple servers as services. In this case, you must make sure that each server uses a different service name in addition to all the other parameters that must be unique per server.
For the following instructions, assume that you want to run the mysqld-nt
server from two different versions of MySQL that are installed at
`C:\mysql-4.0.8' and `C:\mysql-4.0.17', respectively. (This might be
the case if you're running 4.0.8 as your production server, but want to test
4.0.17 before upgrading to it.)
The following principles apply when installing a MySQL service with the
--install or --install-manual option:
MySQL and the server reads options from the [mysqld] group in
the standard option files.
--install option, the server ignores the [mysqld] option
group and instead reads options from the group that has the same name as the
service. The server reads options from the standard option files.
--defaults-file option after the service name,
the server ignores the standard option files and reads options only from the
[mysqld] group of the named file.
Note: Before MySQL 4.0.17, only a server installed using the default service
name (MySQL) or one installed explicitly with a service name of
mysqld read the [mysqld] group in the standard option
files. As of 4.0.17, all servers read the [mysqld] group if they read
the standard option files, even if they are installed using another service
name. This allows you to use the [mysqld] group for options that should
be used by all MySQL services, and an option group named after each service
for use by the server installed with that service name.
Based on the preceding information, you have several ways to set up multiple services. The following instructions describe some examples. Before trying any of them, be sure that you shut down and remove any existing MySQL services first.
mysqld-nt using the service
name of mysqld1 and the 4.0.17 mysqld-nt using the service name mysqld2.
In this case, you can use the [mysqld1] group for 4.0.8 and the
[mysqld2] group for 4.0.17.
For example, you can set up `C:\my.cnf' like this:
# options for mysqld1 service [mysqld1] basedir = C:/mysql-4.0.8 port = 3307 enable-named-pipe socket = mypipe1 # options for mysqld2 service [mysqld2] basedir = C:/mysql-4.0.17 port = 3308 enable-named-pipe socket = mypipe2Install the services as follows, using the full server pathnames to ensure that Windows registers the correct executable program for each service:
C:\> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1 C:\> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2To start the services, use the services manager, or use
NET START
with the appropriate service names:
C:\> NET START mysqld1 C:\> NET START mysqld2To stop the services, use the services manager, or use
NET STOP
with the appropriate service names:
C:\> NET STOP mysqld1 C:\> NET STOP mysqld2
--defaults-file when you install the services to tell each server
what file to use. In this case, each file should list options using a
[mysqld] group.
With this approach, to specify options for the 4.0.8 mysqld-nt,
create a file `C:\my-opts1.cnf' that looks like this:
[mysqld] basedir = C:/mysql-4.0.8 port = 3307 enable-named-pipe socket = mypipe1For the 4.0.17
mysqld-nt, create a file
`C:\my-opts2.cnf' that looks like this:
[mysqld] basedir = C:/mysql-4.0.17 port = 3308 enable-named-pipe socket = mypipe2Install the services as follows (enter each command on a single line):
C:\> C:\mysql-4.0.8\bin\mysqld-nt --install mysqld1
--defaults-file=C:\my-opts1.cnf
C:\> C:\mysql-4.0.17\bin\mysqld-nt --install mysqld2
--defaults-file=C:\my-opts2.cnf
To use a --defaults-file option when you install a MySQL server as a
service, you must precede the option with the service name.
After installing the services, start and stop them the same way as in the
preceding example.
To remove multiple services, use mysqld --remove for each one,
specifying a service name following the --remove option. If the
service name is the default (MySQL), you can omit it.
The easiest way is to run multiple servers on Unix is to compile them with different TCP/IP ports and Unix socket files so that each one is listening on different network interfaces. Also, by compiling in different base directories for each installation, that automatically results in different compiled-in data directory, log file, and PID file locations for each of your servers.
Assume that an existing server is configured for the default TCP/IP port
number (3306) and Unix socket file (`/tmp/mysql.sock'). To configure a
new server to have different operating parameters, use a configure
command something like this:
shell> ./configure --with-tcp-port=port_number \
--with-unix-socket-path=file_name \
--prefix=/usr/local/mysql-4.0.17
Here, port_number and file_name must be different from the
default TCP/IP port number and Unix socket file pathname, and the
--prefix value should specify an installation directory different
than the one under which the existing MySQL installation is located.
If you have a MySQL server listening on a given port number, you can use the following command to find out what operating parameters it is using for several important configurable variables, including the base directory and Unix socket filename:
shell> mysqladmin --host=host_name --port=port_number variables
With the information displayed by that command, you can tell what option values not to use when configuring an additional server.
Note that if you specify localhost as a hostname, mysqladmin
defaults to using a Unix socket file connection rather than TCP/IP.
In MySQL 4.1, you can explicitly specify the connection protocol to use by
using the --protocol={TCP | SOCKET | PIPE | MEMORY} option.
You don't have to compile a new MySQL server just to start with a different Unix socket file and TCP/IP port number. It is also possible to specify those values at runtime. One way to do so is by using command-line options:
shell> mysqld_safe --socket=file_name --port=port_number
To start a second server, provide different --socket and
--port option values, and pass a --datadir=path option to
mysqld_safe so that the server uses a different data directory.
Another way to achieve a similar effect is to use environment variables to set the Unix socket filename and TCP/IP port number:
shell> MYSQL_UNIX_PORT=/tmp/mysqld-new.sock shell> MYSQL_TCP_PORT=3307 shell> export MYSQL_UNIX_PORT MYSQL_TCP_PORT shell> mysql_install_db --user=mysql shell> mysqld_safe --datadir=/path/to/datadir &
This is a quick way of starting a second server to use for testing. The nice thing about this method is that the environment variable settings apply to any client programs that you invoke from the same shell. Thus, connections for those clients are automatically directed to the second server!
section F Environment Variables includes a list of other environment
variables you can use to affect mysqld.
For automatic server execution, your startup script that is executed at boot time should execute the following command once for each server with an appropriate option file path for each command:
mysqld_safe --defaults-file=path
Each option file should contain option values specific to a given server.
On Unix,
the mysqld_multi script is another way to start multiple servers.
See section 5.1.5 The mysqld_multi Program for Managing Multiple MySQL Servers.
When you want to connect with a client program to a MySQL server that is listening to different network interfaces than those compiled into your client, you can use one of the following methods:
--host=host_name --port=port_number to connect
via TCP/IP to a remote server, with --host=127.0.0.1
--port=port_number to connect via TCP/IP to a local server, or with
--host=localhost --socket=file_name to connect to a local server via
a Unix socket file or a Windows named pipe.
--protocol=tcp to connect
via TCP/IP, --protocol=socket to connect via a Unix socket file,
--protocol=pipe to connect via a named pipe, or
--protocol=memory to connect via shared memory. For TCP/IP
connections, you may also need to specify --host and --port
options. For the other types of connections, you may need to specify
a --socket option to specify a Unix socket file or named pipe name, or a
--shared-memory-base-name option to specify the shared memory name.
Shared memory connections are supported only on Windows.
MYSQL_UNIX_PORT and MYSQL_TCP_PORT
environment variables to point to the Unix socket file and TCP/IP port
number before you start your clients. If you normally use a specific socket
file or port number, you can place commands to set these environment
variables in your `.login' file so that they apply each time you log
in.
See section F Environment Variables.
[client] group of an option file. For example, you can use
`C:\my.cnf' on Windows, or the `.my.cnf' file in your home
directory on Unix.
See section 4.3.2 Using Option Files.
mysql_real_connect() call. You can also have the program read
option files by calling mysql_options().
See section 22.2.3 C API Function Descriptions.
DBD::mysql module, you can read options
from MySQL option files. For example:
$dsn = "DBI:mysql:test;mysql_read_default_group=client;"
. "mysql_read_default_file=/usr/local/mysql/data/my.cnf";
$dbh = DBI->connect($dsn, $user, $password);
See section 22.4 MySQL Perl API.
Other programming interfaces may provide similar capabilities for reading
option files.
From version 4.0.1 on, MySQL Server features a query cache.
When in use, the query cache stores the text of a SELECT query
together with the corresponding result that was sent to the client.
If the identical query is received later, the server retrieves
the results from the query cache rather than parsing and executing the
query again.
The query cache is extremely useful in an environment where (some) tables don't change very often and you have a lot of identical queries. This is a typical situation for many Web servers that generate a lot of dynamic pages based on database content.
Note: The query cache does not return stale data. When tables are modified, any relevant entries in the query cache are flushed.
Note: The query cache does not work in an environment where you
have many mysqld servers updating the same MyISAM tables.
Some performance data for the query cache follow. These results were generated by running the MySQL benchmark suite on a Linux Alpha 2 x 500MHz system with 2GB RAM and a 64MB query cache.
To disable the query cache at server startup, set the
query_cache_size system variable to 0. By disabling the query cache
code, there is no noticeable overhead. Query cache capabilities can be
excluded from the server entirely by using the --without-query-cache
option to configure when compiling MySQL.
This section describes how the query cache works when it is operational. section 5.11.3 Query Cache Configuration describes how to control whether or not it is operational.
Queries are compared before parsing, so the following two queries are regarded as different by the query cache:
SELECT * FROM tbl_name Select * from tbl_name
Queries must be exactly the same (byte for byte) to be seen as identical. In addition, query strings that are identical may be treated as different for other reasons. Queries that use different databases, different protocol versions, or different default character sets are considered different queries and are cached separately.
If a query result is returned from query cache, the server increments the
Qcache_hits status variable, not Com_select.
See section 5.11.4 Query Cache Status and Maintenance.
If a table changes, then all cached queries that use the table become
invalid and are removed from the cache. This includes queries that use
MERGE tables that map to the changed table. A table can be changed
by many types of statements, such as INSERT, UPDATE,
DELETE, TRUNCATE, ALTER TABLE, DROP TABLE, or
DROP DATABASE.
Transactional InnoDB tables that have been changed are invalidated
when a COMMIT is performed.
In MySQL 4.0, the query cache is disabled within transactions (it does
not return results). Beginning with MySQL 4.1.1, the query cache also
works within transactions when using InnoDB tables (it uses the
table version number to detect whether or not its contents are still current).
Before MySQL 5.0, a query that begins with a leading comment might be cached, but could not be fetched from the cache. This problem is fixed in MySQL 5.0.
The query cache works for SELECT SQL_CALC_FOUND_ROWS ... and
SELECT FOUND_ROWS() type queries. FOUND_ROWS() returns
the correct value even if the preceding query was fetched from the cache
because the number of found rows is also stored in the cache.
A query cannot be cached if it contains any of the following functions:
BENCHMARK()
| CONNECTION_ID()
| CURDATE()
|
CURRENT_DATE()
| CURRENT_TIME()
| CURRENT_TIMESTAMP()
|
CURTIME()
| DATABASE()
| ENCRYPT() with one parameter
|
FOUND_ROWS()
| GET_LOCK()
| LAST_INSERT_ID()
|
LOAD_FILE()
| MASTER_POS_WAIT()
| NOW()
|
RAND()
| RELEASE_LOCK()
| SYSDATE()
|
UNIX_TIMESTAMP() with no parameters
| USER()
|
A query also is not cached under these conditions:
mysql system database.
SELECT ... IN SHARE MODE SELECT ... INTO OUTFILE ... SELECT ... INTO DUMPFILE ... SELECT * FROM ... WHERE autoincrement_col IS NULLThe last form is not cached because it is used as the ODBC workaround for obtaining the last insert ID value. See section 23.1.14.1 How to Get the Value of an
AUTO_INCREMENT Column in ODBC.
TEMPORARY tables.
SELECT privilege for all the involved databases and
tables. If this is not the case, the cached result is not used.
SELECT Options
There are two query cache-related options that may be
specified in a SELECT statement:
SQL_CACHE
query_cache_type
system variable is ON or DEMAND.
SQL_NO_CACHE
Examples:
SELECT SQL_CACHE id, name FROM customer; SELECT SQL_NO_CACHE id, name FROM customer;
The have_query_cache server system variable indicates whether the query
cache is available:
mysql> SHOW VARIABLES LIKE 'have_query_cache'; +------------------+-------+ | Variable_name | Value | +------------------+-------+ | have_query_cache | YES | +------------------+-------+
Several other system variables control query cache operation.
These can be set in an option file or on the command line
when starting mysqld.
The query cache-related system variables all have names that begin with
query_cache_. They are described briefly in section 5.2.3 Server System Variables, with additional configuration information given here.
To set the size of the query cache, set the query_cache_size system
variable. Setting it to 0 disables the query cache. The default cache size
is 0; that is, the query cache is disabled.
If the query cache is enabled, the query_cache_type variable
influences how it works. This variable can be set to the following values:
0 or OFF prevents caching or retrieval of cached
results.
1 or ON allows caching except of those statements
that begin with SELECT SQL_NO_CACHE.
2 or DEMAND causes caching of only those statements
that begin with SELECT SQL_CACHE.
Setting the GLOBAL value of query_cache_type determines query
cache behavior for all clients that connect after the change is made.
Individual clients can control cache behavior for their own connection by
setting the SESSION value of query_cache_type. For example, a
client can disable use of the query cache for its own queries like this:
mysql> SET SESSION query_cache_type = OFF;
To control the maximum size of individual query results that can be cached,
set the query_cache_limit variable. The default value is 1MB.
The result of a query (the data sent to the client) is stored in the query
cache during result retrieval. Therefore the data usually is not handled in
one big chunk. The query cache allocates blocks for storing this data on
demand, so when one block is filled, a new block is allocated. Because
memory allocation operation is costly (timewise), the query cache allocates
blocks with a minimum size given by the query_cache_min_res_unit
system variable. When a query is executed, the last result block is trimmed
to the actual data size so that unused memory is freed.
Depending on the types of queries your server executes, you might find it
helpful to tune the value of query_cache_min_res_unit:
query_cache_min_res_unit is 4KB. This should
be adequate for most cases.
query_cache_min_res_unit. The number of free blocks and queries
removed due to pruning are given by the values of the
Qcache_free_blocks and Qcache_lowmem_prunes status variables.
Qcache_total_blocks and Qcache_queries_in_cache status
variables), you can increase performance by increasing
query_cache_min_res_unit. However, be careful to not make it too
large (see the previous item).
query_cache_min_res_unit is present from MySQL 4.1.
You can check whether the query cache is present in your MySQL server using the following statement:
mysql> SHOW VARIABLES LIKE 'have_query_cache'; +------------------+-------+ | Variable_name | Value | +------------------+-------+ | have_query_cache | YES | +------------------+-------+
You can defragment the query cache to better utilize its memory
with the FLUSH QUERY CACHE statement.
The statement does not remove any queries from the cache.
The RESET QUERY CACHE statement removes all query results from the
query cache. The FLUSH TABLES statement also does this.
To monitor query cache performance, use SHOW STATUS to view
the cache status variables:
mysql> SHOW STATUS LIKE 'Qcache%'; +-------------------------+--------+ | Variable_name | Value | +-------------------------+--------+ | Qcache_free_blocks | 36 | | Qcache_free_memory | 138488 | | Qcache_hits | 79570 | | Qcache_inserts | 27087 | | Qcache_lowmem_prunes | 3114 | | Qcache_not_cached | 22989 | | Qcache_queries_in_cache | 415 | | Qcache_total_blocks | 912 | +-------------------------+--------+
Descriptions of each of these variables are given in section 5.2.4 Server Status Variables. Some uses for them are described here.
The total number of SELECT queries is equal to:
Com_select + Qcache_hits + queries with errors found by parser
The Com_select value is equal to:
Qcache_inserts + Qcache_not_cached + queries with errors found during columns/rights check
The query cache uses variable-length blocks, so Qcache_total_blocks
and Qcache_free_blocks may indicate query cache memory fragmentation.
After FLUSH QUERY CACHE, only a single free block remains.
Every cached query requires a minimum of two blocks (one for the query text and one or more for the query results). Also, every table that is used by a query requires one block. However, if two or more queries use the same table, only one block needs to be allocated.
The information provided by the Qcache_lowmem_prunes status variable
can help you tune the query cache size. It counts the number of queries that
have been removed from the cache to free up memory for caching new queries.
The query cache uses a least recently used (LRU) strategy to decide which
queries to remove from the cache. Tuning information is given in section 5.11.3 Query Cache Configuration.
Replication capabilities allowing the databases on one MySQL server to be duplicated on another were introduced in MySQL 3.23.15. This chapter describes the various replication features provided by MySQL. It introduces replication concepts, shows how to set up replication servers, and serves as a reference to the available replication options. It also provides a list of frequently asked questions (with answers), and troubleshooting advice for solving problems.
For a description of the syntax of replication-related SQL statements, see section 13.6 Replication Statements.
We suggest that you visit our Web site at http://www.mysql.com often and read updates to this chapter. Replication is constantly being improved, and we update the manual frequently with the most current information.
MySQL 3.23.15 and up features support for one-way replication. One server acts as the master, while one or more other servers act as slaves. The master server writes updates to its binary log files, and maintains an index of the files to keep track of log rotation. These logs serve as a record of updates to be sent to slave servers. When a slave server connects to the master server, it informs the master of its last position within the logs since the last successfully propagated update. The slave catches up any updates that have occurred since then, and then blocks and waits for the master to notify it of new updates.
A slave server can also serve as a master if you want to set up chained replication servers.
Note that when you are using replication, all updates to the tables that are replicated should be performed on the master server. Otherwise, you must always be careful to avoid conflicts between updates that users make to tables on the master and updates that they make to tables on the slave.
One-way replication has benefits for robustness, speed, and system administration:
SELECT queries may be sent to the slave to reduce the query
processing load of the master. Statements that modify data should still
be sent to the master so that the master and slave do not get out of sync.
This load-balancing strategy is effective if non-updating queries dominate,
but that is the normal case.
MySQL replication is based on the master server keeping track of all changes to your databases (updates, deletes, and so on) in the binary logs. Therefore, to use replication, you must enable binary logging on the master server. See section 5.9.4 The Binary Log.
Each slave server receives from the master the saved updates that the master has recorded in its binary log, so that the slave can execute the same updates on its copy of the data.
It is very important to realize that the binary log is simply a record starting from the fixed point in time at which you enable binary logging. Any slaves that you set up need copies of the databases on your master as they existed at the moment you enabled binary logging on the master. If you start your slaves with databases that are not the same as what was on the master when the binary log was started, your slaves may fail.
One way to copy the master's data to the slave is to use the LOAD
DATA FROM MASTER statement. Be aware that LOAD DATA FROM MASTER
is available only as of MySQL 4.0.0 and currently works only if all the
tables on the master are MyISAM type. Also, this statement acquires a
global read lock, so no updates on the master are possible while the tables
are being transferred to the slave. When we implement lock-free hot table
backup (in MySQL 5.0), this global read lock will no longer be necessary.
Due to these limitations, we recommend that at this point you use
LOAD DATA FROM MASTER only if the dataset on the master is relatively
small, or if a prolonged read lock on the master is acceptable. While the
actual speed of LOAD DATA FROM MASTER may vary from system to system,
a good rule of thumb for how long it takes is 1 second per 1MB of data.
That is only a rough estimate, but you should get close to it if both
master and slave are equivalent to 700MHz Pentium performance and are
connected through a 100MBit/s network.
After the slave has been set up with a copy of the master's data, it
connects to the master and waits for updates to process. If
the master goes away or the slave loses connectivity with your master,
it keeps trying to connect periodically until it is able to reconnect
and resume listening for updates. The retry interval is controlled by the
--master-connect-retry option. The default is 60 seconds.
Each slave keeps track of where it left off. The master server has no knowledge of how many slaves there are or which ones are up to date at any given time.
MySQL replication capabilities are implemented using three threads (one
on the master server and two on the slave). When START SLAVE is
issued, the slave creates an I/O thread. The I/O thread connects to the
master and asks it to send the statements recorded in its binary logs. The
master creates a thread to send the binary log contents to the slave.
This thread can be identified as the Binlog Dump thread in the
output of SHOW PROCESSLIST on the master. The slave I/O thread
reads what the master Binlog Dump thread sends and simply copies
it to some local files in the slave's data directory called relay logs.
The third thread is the SQL thread, which the slave creates to read the
relay logs and execute the updates they contain.
In the preceding description, there are three threads per slave. For a master that has multiple slaves, it creates one thread for each currently connected slave, and each slave has its own I/O and SQL threads.
For versions of MySQL before 4.0.2, replication involves only two threads (one on the master and one on the slave). The slave I/O and SQL threads are combined as a single thread, and no relay log files are used.
The advantage of using two slave threads is that statement reading and execution are separated into two independent tasks. The task of reading statements is not slowed down if statement execution is slow. For example, if the slave server has not been running for a while, its I/O thread can quickly fetch all the binary log contents from the master when the slave starts, even if the SQL thread lags far behind and may take hours to catch up. If the slave stops before the SQL thread has executed all the fetched statements, the I/O thread has at least fetched everything so that a safe copy of the statements is locally stored in the slave's relay logs for execution when next the slave starts. This allows the binary logs to be purged on the master, because it no longer need wait for the slave to fetch their contents.
The SHOW PROCESSLIST statement provides information that tells you
what is happening on the master and on the slave regarding replication.
The following example illustrates how the three threads show up in
SHOW PROCESSLIST. The output format is that used by SHOW
PROCESSLIST as of MySQL version 4.0.15, when the content of the
State column was changed to be more meaningful compared to
earlier versions.
On the master server, the output from SHOW PROCESSLIST looks like this:
mysql> SHOW PROCESSLIST\G
*************************** 1. row ***************************
Id: 2
User: root
Host: localhost:32931
db: NULL
Command: Binlog Dump
Time: 94
State: Has sent all binlog to slave; waiting for binlog to
be updated
Info: NULL
Here, thread 2 is a replication thread for a connected slave. The information indicates that all outstanding updates have been sent to the slave and that the master is waiting for more updates to occur.
On the slave server, the output from SHOW PROCESSLIST looks like this:
mysql> SHOW PROCESSLIST\G
*************************** 1. row ***************************
Id: 10
User: system user
Host:
db: NULL
Command: Connect
Time: 11
State: Waiting for master to send event
Info: NULL
*************************** 2. row ***************************
Id: 11
User: system user
Host:
db: NULL
Command: Connect
Time: 11
State: Has read all relay log; waiting for the slave I/O
thread to update it
Info: NULL
This information indicates that thread 10 is the I/O thread that is communicating with the master server, and thread 11 is the SQL thread that is processing the updates stored in the relay logs. Currently, both threads are idle, waiting for further updates.
Note that the value in the Time column can tell how late the slave
is compared to the master.
See section 6.9 Replication FAQ.
The following list shows the most common states you see in the
State column for the master's Binlog Dump thread. If you
don't see any Binlog Dump threads on a master server, replication
is not running. That is, no slaves currently are connected.
Sending binlog event to slave
Finished reading one binlog; switching to next binlog
Has sent all binlog to slave; waiting for binlog to be updated
Waiting to finalize termination
The following list shows the most common states you see in the
State column for a slave server I/O thread. Beginning with MySQL
4.1.1, this state also appears in the Slave_IO_State column displayed
by the SHOW SLAVE STATUS statement. This means that you can get a
good view of what is happening by using only SHOW SLAVE STATUS.
Connecting to master
Checking master version
Registering slave on master
Requesting binlog dump
Waiting to reconnect after a failed binlog dump request
--master-connect-retry option.
Reconnecting after a failed binlog dump request
Waiting for master to send event
slave_read_timeout seconds, a timeout occurs.
At that point, the thread considers the connection to be broken and
make an attempt to reconnect.
Queueing master event to the relay log
Waiting to reconnect after a failed master event read
master-connect-retry seconds before attempting to reconnect.
Reconnecting after a failed master event read
Waiting for master to send event.
Waiting for the slave SQL thread to free enough relay log space
relay_log_space_limit value, and the relay
logs have grown so much that their combined size exceeds this value.
The I/O thread is waiting until the SQL
thread frees enough space by processing relay log contents so that it can
delete some relay log files.
Waiting for slave mutex on exit
The following list shows the most common states you see in the
State column for a slave server SQL thread:
Reading event from the relay log
Has read all relay log; waiting for the slave I/O thread to update it
Waiting for slave mutex on exit
The State column for the I/O thread may also show the text of
a statement. This indicates that the thread has read an event from the
relay log, extracted the statement from it, and is executing it.
By default, relay logs are named using filenames of the form
`host_name-relay-bin.nnnnnn', where host_name is the name of the
slave server host and nnnnnn is a sequence number.
Successive relay log files are created using successive sequence numbers,
beginning with 000001 (001 in MySQL 4.0 or older).
The slave keeps track of relay logs currently in use in an index file.
The default relay log index filename is
`host_name-relay-bin.index'.
By default, these files are created in the slave's data directory.
The default filenames may be overridden with the --relay-log and
--relay-log-index server options.
See section 6.8 Replication Startup Options.
Relay logs have the same format as binary logs, so you can use
mysqlbinlog to read them. A relay log is automatically deleted by
the SQL thread as soon as it has executed all its events and no longer needs
it). There is no explicit mechanism for deleting relay logs, because the SQL
thread takes care of doing so. However, from MySQL 4.0.14, FLUSH LOGS
rotates relay logs, which influences when the SQL thread deletes them.
A new relay log is created under the following conditions:
FLUSH LOGS or
mysqladmin flush-logs. (This creates a new relay log only as of MySQL
4.0.14.)
max_relay_log_size, if max_relay_log_size > 0
max_binlog_size, if max_relay_log_size = 0
or MySQL is older than 4.0.14
A slave replication server creates two additional small files in the
data directory. These are status files and are named `master.info'
and `relay-log.info' by default. They contain information like
that shown in the output of the SHOW SLAVE STATUS statement
(see section 13.6.2 SQL Statements for Controlling Slave Servers for a description of this statement).
As disk files, they survive a slave server's shutdown. The next time the
slave starts up, it reads these files to determine how far it has proceeded
in reading binary logs from the master and in processing its own relay logs.
The `master.info' file is updated by the I/O thread.
Before MySQL 4.1,
the correspondence between the lines in the file and the
columns displayed by SHOW SLAVE STATUS is as follows:
| Line | Description |
| 1 | Master_Log_File
|
| 2 | Read_Master_Log_Pos
|
| 3 | Master_Host
|
| 4 | Master_User
|
| 5 | Password (not shown by SHOW SLAVE STATUS)
|
| 6 | Master_Port
|
| 7 | Connect_Retry
|
As of MySQL 4.1, the file includes a line count and information about SSL options:
| Line | Description |
| 1 | Number of lines in the file |
| 2 | Master_Log_File
|
| 3 | Read_Master_Log_Pos
|
| 4 | Master_Host
|
| 5 | Master_User
|
| 6 | Password (not shown by SHOW SLAVE STATUS)
|
| 7 | Master_Port
|
| 8 | Connect_Retry
|
| 9 | Master_SSL_Allowed
|
| 10 | Master_SSL_CA_File
|
| 11 | Master_SSL_CA_Path
|
| 12 | Master_SSL_Cert
|
| 13 | Master_SSL_Cipher
|
| 14 | Master_SSL_Key
|
The `relay-log.info' file is updated by the SQL thread.
The correspondence between the lines in the file and the
columns displayed by SHOW SLAVE STATUS is as follows:
| Line | Description |
| 1 | Relay_Log_File
|
| 2 | Relay_Log_Pos
|
| 3 | Relay_Master_Log_File
|
| 4 | Exec_Master_Log_Pos
|
When you back up your slave's data, you should back up these two small files
as well, along with the relay log files. They are needed to resume
replication after you restore the slave's data. If you lose the relay logs
but still have the `relay-log.info' file, you can check it to determine
how far the SQL thread has executed in the master binary logs. Then you
can use CHANGE MASTER TO with the MASTER_LOG_FILE and
MASTER_LOG_POS options to tell the slave to re-read the binary
logs from that point. This requires that the binary logs still exist on
the master server.
If your slave is subject to replicating LOAD DATA INFILE statements,
you should also back up any `SQL_LOAD-*' files that exist in the
directory that the slave uses for this purpose. The slave needs these files
to resume replication of any interrupted LOAD DATA INFILE operations.
The directory location is specified using the --slave-load-tmpdir
option. Its default value, if not specified, is the value of the tmpdir
variable.
Here is a quick description of how to set up complete replication of your current MySQL server. It assumes that you want to replicate all your databases and have not configured replication before. You need to shut down your master server briefly to complete the steps outlined here.
The procedure is written in terms of setting up a single slave, but you can use it to set up multiple slaves.
While this method is the most straightforward way to set up a slave, it is not the only one. For example, if you have a snapshot of the master's data, and the master has its server ID set and binary logging enabled, you can set up a slave without shutting down the master or even blocking updates to it. For more details, please see section 6.9 Replication FAQ.
If you want to administer a MySQL replication setup, we suggest that you read this entire chapter through and try all statements mentioned in section 13.6.1 SQL Statements for Controlling Master Servers and section 13.6.2 SQL Statements for Controlling Slave Servers. You should also familiarize yourself with replication startup options described in section 6.8 Replication Startup Options.
Note that this procedure and some of the replication SQL statements
in later sections refer to the SUPER privilege. Prior to MySQL
4.0.2, use the PROCESS privilege instead.
REPLICATION SLAVE privilege.
If the account is used only for replication
(which is recommended), you don't need to grant any additional privileges.
Suppose that your domain is mydomain.com and you want to create an
account with a username of repl such that slave servers can use the
account to access the master server from any host in your domain using a
password of slavepass.
To create the account, this use GRANT statement:
mysql> GRANT REPLICATION SLAVE ON *.*
-> TO 'repl'@'%.mydomain.com' IDENTIFIED BY 'slavepass';
For MySQL versions older than 4.0.2, the REPLICATION SLAVE privilege
does not exist. Grant the FILE privilege instead:
mysql> GRANT FILE ON *.*
-> TO 'repl'@'%.mydomain.com' IDENTIFIED BY 'slavepass';
If you plan to use the LOAD TABLE FROM MASTER or LOAD DATA
FROM MASTER statements from the slave host, you need to grant this
account additional privileges:
SUPER and RELOAD global privileges.
SELECT privilege for all tables that
you want to load. Any master tables from which the account cannot
SELECT are ignored by LOAD DATA FROM MASTER.
MyISAM tables, flush all the tables and block
write statements by executing a FLUSH TABLES WITH READ LOCK statement.
mysql> FLUSH TABLES WITH READ LOCK;Leave the client running from which you issue the
FLUSH TABLES
statement so that the read lock remains in effect. (If you exit the client,
the lock is released.) Then take a snapshot of the data on your master server.
The easiest way to create a snapshot is to use an archiving program to make a
binary backup of the databases in your master's data directory.
For example, use tar on Unix, or PowerArchiver, WinRAR,
WinZip, or any similar software on Windows.
To use tar to create an archive that includes all
databases, change location into the master server's data directory, then
execute this command:
shell> tar -cvf /tmp/mysql-snapshot.tar .If you want the archive to include only a database called
this_db, use
this command instead:
shell> tar -cvf /tmp/mysql-snapshot.tar ./this_dbThen copy the archive file to the `/tmp' directory on the slave server host. On that machine, change location into the slave's data directory, and unpack the archive file using this command:
shell> tar -xvf /tmp/mysql-snapshot.tarYou may not want to replicate the
mysql database if the slave
server has a different set of user accounts from those that exist on the
master. In this case, you should exclude it from the archive. You also
need not include any log files in the archive, or the `master.info'
or `relay-log.info' files.
While the read lock placed by FLUSH TABLES WITH READ LOCK is in effect,
read the value of the current binary log name and offset on the master:
mysql > SHOW MASTER STATUS; +---------------+----------+--------------+------------------+ | File | Position | Binlog_Do_DB | Binlog_Ignore_DB | +---------------+----------+--------------+------------------+ | mysql-bin.003 | 73 | test | manual,mysql | +---------------+----------+--------------+------------------+The
File column shows the name of the log, while Position shows
the offset. In this example, the binary log value is
mysql-bin.003 and the offset is 73. Record the values. You need
to use them later when you are setting up the slave. They represent the
replication coordinates at which the slave should begin processing new updates
from the master.
After you have taken the snapshot and recorded the log name and offset,
you can re-enable write activity on the master:
mysql> UNLOCK TABLES;If you are using
InnoDB tables, ideally you should use the InnoDB Hot
Backup tool. It takes a consistent snapshot without acquiring any locks on
the master server, and records the log name and offset corresponding to the
snapshot to be later used on the slave. InnoDB Hot Backup is a non-free
(commercial) additional tool that is not included in the standard MySQL distribution.
See the InnoDB Hot Backup home page at http://www.innodb.com/manual.php
for detailed information and screenshots.
Without the Hot Backup tool, the quickest way to take a binary snapshot
of InnoDB tables is to shut down the master server and copy the
InnoDB data files, log files, and table definition files (`.frm'
files). To record the current log file name and offset, you should issue
the following statements before you shut down the server:
mysql> FLUSH TABLES WITH READ LOCK; mysql> SHOW MASTER STATUS;Then record the log name and the offset from the output of
SHOW MASTER
STATUS as was shown earlier. After recording the log name and the offset,
shut down the server without unlocking the tables to make sure that the
server goes down with the snapshot corresponding to the current log file
and offset:
shell> mysqladmin -u root shutdownAn alternative that works for both
MyISAM and InnoDB
tables is to take an SQL dump of the master instead of a binary copy as
described in the preceding discussion. For this, you can use mysqldump
--master-data on your master and later load the SQL dump file into your
slave. However, this is slower than doing a binary copy.
If the master has been previously running without --log-bin enabled,
the log name and position values displayed by SHOW MASTER STATUS
or mysqldump --master-data are empty. In that case, the values
that you need to use later when specifying the slave's log file and
position are the empty string ('') and 4.
[mysqld] section of the `my.cnf' file on
the master host includes a log-bin option. The section should also
have a server-id=master_id option, where master_id must be
a positive integer value from 1 to 2^32 - 1. For example:
[mysqld] log-bin=mysql-bin server-id=1If those options are not present, add them and restart the server.
[mysqld] server-id=slave_idThe
slave_id value, like the master_id value, must
be a positive integer value from 1 to 2^32 - 1. In addition, it is very
important that the ID of the slave be different from the ID of the
master. For example:
[mysqld] server-id=2If you are setting up multiple slaves, each one must have a unique
server-id value that differs from that of the master and from each
of the other slaves. Think of server-id values as something similar
to IP addresses: These IDs uniquely identify each server instance in the
community of replication partners.
If you don't specify a server-id value, it is set to 1 if
you have not defined master-host, otherwise it is set to 2. Note
that in the case of server-id omission, a master refuses
connections from all slaves, and a slave refuses to connect to a
master. Thus, omitting server-id is good only for backup with a
binary log.
mysqldump, start the slave first (see next
step).
--skip-slave-start option so that it
doesn't immediately try to connect to its master.
You also may want to start the slave server with the
--log-warnings option (enabled by default as of MySQL 4.0.19 and 4.1.2),
to get more messages in the error log about
problems (for example, network or connection problems).
As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error
log unless the value is greater than 1.
mysqldump, load
the dump file into the slave server:
shell> mysql -u root -p < dump_file.sql
mysql> CHANGE MASTER TO
-> MASTER_HOST='master_host_name',
-> MASTER_USER='replication_user_name',
-> MASTER_PASSWORD='replication_password',
-> MASTER_LOG_FILE='recorded_log_file_name',
-> MASTER_LOG_POS=recorded_log_position;
The following table shows the maximum length for the string options:
MASTER_HOST | 60 |
MASTER_USER | 16 |
MASTER_PASSWORD | 32 |
MASTER_LOG_FILE | 255 |
mysql> START SLAVE;
After you have performed this procedure, the slave should connect to the master and catch up on any updates that have occurred since the snapshot was taken.
If you have forgotten to set the server-id value for the master, slaves are
not able to connect to it.
If you have forgotten to set the server-id value for the slave, you get
the following error in its error log:
Warning: You should set server-id to a non-0 value if master_host is set; we will force server id to 2, but this MySQL server will not act as a slave.
You also find error messages in the slave's error log if it is not able to replicate for any other reason.
Once a slave is replicating, you can find in its data directory one
file named
`master.info' and another named `relay-log.info'.
The slave uses these two files to keep track of how much
of the master's binary log it has processed. Do not remove or
edit these files, unless you really know what you are doing and understand
the implications. Even in that case,
it is preferred that you use the CHANGE MASTER TO statement.
Note: The content of `master.info' overrides some options specified on the command line or in `my.cnf'. See section 6.8 Replication Startup Options for more details.
Once you have a snapshot, you can use it to set up other slaves by following the slave portion of the procedure just described. You do not need to take another snapshot of the master; you can use the same one for each slave.
The original binary log format was developed in MySQL 3.23. It changed in
MySQL 4.0, and again in MySQL 5.0.0 (massively), 5.0.3 (for improvements to
character set aware replication and LOAD DATA INFILE), 5.0.4 (for
improvements to time zone aware replication). This has consequences when you
upgrade servers in a replication setup, as described in section 6.6 Upgrading a Replication Setup.
As far as replication is concerned, any MySQL 4.1.x version and any 4.0.x version are identical, because they all use the same binary log format. Thus, any servers from these versions are compatible, and replication between them should work seamlessly. The exceptions to this compatibility is that versions from MySQL 4.0.0 to 4.0.2 were very early development versions that should not be used anymore. (These were the alpha versions in the 4.0 release series. Compatibility for them is still documented in the manual included with their distributions.)
The following table indicates master/slave replication compatibility between different versions of MySQL.
| Master | Master | Master | ||
| 3.23.33 and up | 4.0.3 and up or any 4.1.x | 5.0.3 | ||
| Slave | 3.23.33 and up | yes | no | no |
| Slave | 4.0.3 and up | yes | yes | no |
| Slave | 5.0.3 | yes | yes | yes |
As a general rule, we recommended using recent MySQL versions, because replication capabilities are continually being improved. We also recommend using the same version for both the master and the slave. We recommend upgrading master and slave running alpha or beta versions to new versions. Replication from a 5.0.3 master to a 5.0.2 slave will fail; from a 5.0.4 master to a 5.0.3 slave will also fail.
The preceding information pertains the replication compatibility at the protocol level. There can also be SQL-level compatibility constraints, as discussed in section 6.7 Replication Features and Known Problems.
When you upgrade servers that participate in a replication setup, the procedure for upgrading depends on the current server versions and the version to which you are upgrading.
This section applies to upgrading replication from MySQL 3.23 to 4.0 or 4.1. A 4.0 server should be 4.0.3 or newer, as mentioned in section 6.5 Replication Compatibility Between MySQL Versions.
When you upgrade a master from MySQL 3.23 to MySQL 4.0 or 4.1, you should first ensure that all the slaves of this master are at 4.0 or 4.1. If that is not the case, you should first upgrade your slaves: Shut down each one, upgrade it, restart it, and restart replication.
The upgrade can safely be done using the following procedure, assuming that you have a 3.23 master to upgrade and the slaves are 4.0 or 4.1. Note that after the master has been upgraded, you should not restart replication using any old 3.23 binary logs, because this unfortunately confuses the 4.0 or 4.1 slaves.
FLUSH TABLES WITH READ LOCK
statement.
SHOW MASTER STATUS on the master to obtain its current binary log
file and position. Then, for each slave, use those values with a SELECT
MASTER_POS_WAIT() statement. The statement blocks on the slave and returns
when the slave has caught up. Then run STOP SLAVE on the slave.
SHOW MASTER STATUS statement on the master. Then issue these
statements on each slave:
mysql> CHANGE MASTER TO MASTER_LOG_FILE='binary_log_name',
-> MASTER_LOG_POS=4;
mysql> START SLAVE;
This section applies to upgrading replication from MySQL 3.23, 4.0, or 4.1 to 5.0.0. A 4.0 server should be 4.0.3 or newer, as mentioned in section 6.5 Replication Compatibility Between MySQL Versions.
First, note that MySQL 5.0.0 is an alpha release. It is intended to work
better than older versions (easier upgrade, replication of some important
session variables such as sql_mode; see section D.1.5 Changes in release 5.0.0 (22 Dec 2003: Alpha)). However
it has not yet been extensively tested. As with any alpha release, we
recommend that you not use it in critical production environments yet.
When you upgrade a master from MySQL 3.23, 4.0, or 4.1 to 5.0.0, you should first ensure that all the slaves of this master are 5.0.0. If that's not the case, you should first upgrade your slaves. To upgrade each slave, just shut it down, upgrade it to 5.0.0, restart it, and restart replication. The 5.0.0 slave is able to read its old relay logs that were written before the upgrade and execute the statements they contain. Relay logs created by the slave after the upgrade are in 5.0.0 format.
After the slaves have been upgraded, shut down your master, upgrade it to 5.0.0, and restart it. The 5.0.0 master is able to read its old binary logs that were written before the upgrade and send them to the 5.0.0 slaves. The slaves recognize the old format and handle it properly. Binary logs created by master after the upgrade are in 5.0.0 format. These too are recognized by the 5.0.0 slaves.
In other words, there are no measures to take when upgrading to 5.0.0, except that slaves must be 5.0.0 before you can upgrade the master to 5.0.0. Note that downgrading from 5.0.0 to older versions does not work so automatically: You must ensure that any 5.0.0 binary logs or relay logs have been fully processed, so that you can remove them before proceeding with the downgrade.
In general, replication compatibility at the SQL level requires that any
features used be supported by both the master and the slave servers. For
example, the GROUP_CONCAT() function is available in MySQL 4.1 and
up. If you use this function on the master server, you cannot replicate to
a slave server that is older than MySQL 4.1.
The following list provides details about
what is supported and what is not.
Additional InnoDB-specific information about replication is given in
section 15.7.5 InnoDB and MySQL Replication.
AUTO_INCREMENT,
LAST_INSERT_ID(), and TIMESTAMP values.
USER(), UUID(), and LOAD_FILE() functions
are replicated without changes and thus do not work reliably on the
slave. This is also true for CONNECTION_ID() in slave versions
older than 4.1.1.
The new PASSWORD() function in MySQL 4.1 is well
replicated in masters from 4.1.1 and up; your slaves also must be 4.1.1 or above
to replicate it. If you have older slaves and need to replicate
PASSWORD() from your 4.1.x master, you must start your master
with the --old-password option, so that it uses the old implementation
of PASSWORD(). (Note that the PASSWORD() implementation in
MySQL 4.1.0 differs from every other version of MySQL. It is best to avoid
4.1.0 in a replication situation.)
GET_LOCK(),
RELEASE_LOCK(), IS_FREE_LOCK(), IS_USED_LOCK() are
replicated without the slave knowing the concurrency context on master; so
these functions should not be used to insert into a master's table as the
content on slave would differ (i.e. do not do
INSERT INTO mytable VALUES(GET_LOCK(...))).
FOREIGN_KEY_CHECKS variable is replicated as of MySQL 4.0.14.
The SQL_MODE, UNIQUE_CHECKS, and SQL_AUTO_IS_NULL
variables are replicated as of 5.0.0. The TABLE_TYPE, also known as
STORAGE_ENGINE variable is not yet replicated, which is a good thing for
replication between different storage engines.
--default-character-set, --default-collation) on the
master and the slave. Otherwise, you may get duplicate-key errors on
the slave, because a key that is regarded as unique in the master's character
set may not be unique in the slave's character set.
Second, if the master is strictly older than MySQL 4.1.3, the character set of
the session should never be made different from its global value (in other words, don't
use SET NAMES, SET CHARACTER SET etc) because this character set
change is not known to the slave. If the master is 4.1.3 or newer, and the
slave too, the session can freely set its local value of character set
variables (NAMES, CHARACTER SET, COLLATION_CLIENT,
COLLATION_SERVER etc) as these settings are written to the binary
log and then known to the slave. The session however is prevented from
changing the global value of these; as said previously the master and
slave must always have identical global character set values. There also is one
last limitation: if on the master you have databases with different character
sets from the global collation_server value, you should design your
CREATE TABLE statements so that they don't implicitly rely on the
default database's character set, because there currently is a bug (Bug #2326);
a good workaround is to explicitly state the character set and collation in a
clause of the CREATE TABLE.
NOW() or FROM_UNIXTIME()
functions, won't be replicated properly). One could set time zone in which
MySQL server runs by using --timezone=timezone_name option of
mysqld_safe script or by setting TZ environment variable.
Also starting from version 4.1.3 both master and slave should have same
default connection time zone set, i.e. --default-time-zone parameter
should have the same value for both master and slave.
CONVERT_TZ(...,...,@global.time_zone) is not properly
replicated. CONVERT_TZ(...,...,@session.time_zone) is properly
replicated only if master and slave are 5.0.4 or newer.
SET MAX_JOIN_SIZE=1000; INSERT INTO mytable VALUES(@MAX_JOIN_SIZE);
will not insert the same data on master and on slave.
This does not applie to the common
SET TIME_ZONE=...; INSERT INTO mytable
VALUES(CONVERT_TZ(...,...,@time_zone)), which is fixed in MySQL 5.0.4.
InnoDB master table as a MyISAM slave table. However, if you do
this, there are problems if
the slave is stopped in the middle of a BEGIN/COMMIT block, because
the slave restarts at the beginning of the BEGIN block.
This issue is on our TODO and will be fixed in the near future.
@var_name) are badly replicated in 3.23 and 4.0. This is fixed
in 4.1. Note that user variable names are case insensitive starting from
MySQL 5.0. You should take this into account when setting up replication
between 5.0 and an older version.
slave_transaction_retries: If the replication slave SQL thread
fails to execute a transaction because of an InnoDB deadlock
or exceeded InnoDB's innodb_lock_wait_timeout or NDBCluster's
TransactionDeadlockDetectionTimeout or
TransactionInactiveTimeout, it automatically retries
slave_transaction_retries times before stopping with an error. The
default value is 0 in MySQL 4.1 and 10 in MySQL 5.0. Starting from MySQL 4.1.11
and 5.0.4, the total count of retries can be seen in SHOW STATUS, see
section 5.2.4 Server Status Variables.
DATA DIRECTORY or INDEX DIRECTORY clause is used in a
CREATE TABLE statement on the master server, the clause is also used
on the slave. This can cause problems if no corresponding directory exists
in the slave host filesystem or exists but is not accessible to the slave
server. Starting from MySQL 4.0.15, there is a sql_mode option
called NO_DIR_IN_CREATE. If the slave server is run with its SQL mode
set to include this option, it ignores the clauses before
replicating the CREATE TABLE statement. The result is that the
MyISAM data and index files are created in the table's database
directory.
LOAD DATA INFILE is interrupted in the middle (integrity
constraint violation, killed connection...), the slave skips this
LOAD DATA INFILE entirely. It means that if this command permanently
inserted/updated some table records before being interrupted, these
modifications won't be replicated to the slave.
FLUSH, ANALYZE TABLE, OPTIMIZE
TABLE, and REPAIR TABLE statements are not written to the binary
log and thus are not replicated to the slaves. This is not normally
a problem because these statements do not modify table data. However,
it can cause difficulties under certain circumstances. If you replicate
the privilege tables in the mysql database and update those tables
directly without using the GRANT statement, you
must issue a FLUSH PRIVILEGES statement on your slaves to put
the new privileges into effect. Also if you use
FLUSH TABLES when renaming a MyISAM table that is part of a
MERGE table, you have to issue FLUSH TABLES
manually on the slaves.
As of MySQL 4.1.1, these statements are written to the binary log
(unless you specify NO_WRITE_TO_BINLOG, or its alias LOCAL).
Exceptions are that FLUSH LOGS, FLUSH MASTER,
FLUSH SLAVE, and FLUSH TABLES WITH READ LOCK are not logged in
any case. (Any of them may cause problems if replicated to a slave.)
For a syntax example, see section 13.5.5.2 FLUSH Syntax.
SELECT queries to different
slaves.
MEMORY (HEAP) tables become empty.
As of MySQL 4.0.18, the master replicates this effect as follows:
The first time that the master uses each MEMORY table after startup,
it notifies slaves that the table needs to be emptied by writing a
DELETE FROM statement for the table to its binary log.
See section 14.3 The MEMORY (HEAP) Storage Engine
for more details.
STOP SLAVE statement.
SHOW STATUS to check the value of the Slave_open_temp_tables
variable.
mysqladmin shutdown command to
shut down the slave.
START SLAVE.
--log-slave-updates option specified.
Note, however, that many statements do not work correctly in this kind of
setup unless your client code is written to take care of the potential
problems that can occur from updates that occur in different sequence
on different servers.
This means that you can create a setup such as this:
A -> B -> C -> AServer IDs are encoded in the binary log events, so server A knows when an event that it reads was originally created by itself and does not execute the event (unless server A was started with the
--replicate-same-server-id option, which is meaningful only in rare
setups). Thus, there are no infinite loops. But this circular
setup works only if you perform no conflicting
updates between the tables. In other words, if you insert data in both
A and C, you should never insert a row in A that may have a key that
conflicts with a row inserted in C. You should also not update
the same rows on two servers if the order in which the updates are
applied is significant.
START SLAVE.
--master-connect-retry option.)
The slave also is able to deal with
network connectivity outages. However, the slave does notice the
network outage only after receiving no data from the master for
slave_net_timeout seconds. If your outages are short, you may want
to decrease slave_net_timeout.
See section 5.2.3 Server System Variables.
InnoDB tables and the --innodb-safe-binlog option on the
master. See section 5.9.4 The Binary Log.
MyISAM tables, it is possible
to have a statement that only partially updates a table and returns an
error code. This can happen, for example, on a multiple-row insert that has
one row violating a key constraint, or if a long update statement is killed
after updating some of the rows. If that happens on the master, the slave
thread exits and waits for the database administrator
to decide what to do about it unless
the error code is legitimate and the statement execution results in the same
error code. If this error code validation behavior is not desirable, some or
all errors can be masked out (ignored) with the --slave-skip-errors
option. This option is available starting with MySQL 3.23.47.
BEGIN/COMMIT segment, updates to the binary log may be out of sync
if some thread changes the non-transactional table before the
transaction commits. This is because the transaction is written to the
binary log only when it is committed.
COMMIT or not written at all if you use
ROLLBACK. You must take this into account when updating both
transactional tables and non-transactional tables within the same
transaction. (This is true not only for replication, but also if you are
using binary logging for backups.) In version 4.0.15, we changed the logging
behavior for transactions that mix updates to transactional and
non-transactional tables, which solves the problems (order of statements is
good in the binary log, and all needed statements are written to the binary log
even in case of ROLLBACK). The problem that remains is when a second
connection updates the non-transactional table while the first connection's
transaction is not finished yet; wrong order can still occur, because the
second connection's update is written immediately after it is done.
LOAD DATA INFILE from a 3.23 master, the
values of the Exec_Master_Log_Pos and Relay_Log_Space columns of
SHOW SLAVE STATUS become incorrect.
The incorrectness of Exec_Master_Log_Pos causes a problem when you
stop and restart replication; so it is a good idea to correct the value before
this, by doing FLUSH LOGS on the master.
These bugs are fixed in MySQL 5.0.0 slaves.
The following table lists replication problems in MySQL 3.23 that are fixed in MySQL 4.0:
LOAD DATA INFILE is handled properly, as long as the data file
still resides on the master server at the time of update
propagation.
LOAD DATA LOCAL INFILE is no longer skipped on the slave as it
was in 3.23.
RAND() in updates does not replicate properly.
Use RAND(some_non_rand_expr) if you are replicating updates with
RAND(). You can, for example, use UNIX_TIMESTAMP() as the
argument to RAND().
On both the master and the slave, you must use the server-id option
to establish a unique replication ID for each server. You should pick a unique
positive integer in the range from 1 to 2^32 - 1 for each master and slave.
Example: server-id=3
The options that you can use on the master server for controlling binary logging are described in section 5.9.4 The Binary Log.
The following table describes the options you can use on slave replication servers. You can specify them on the command line or in an option file.
Some slave server replication options are handled in a special way, in the sense that they are ignored if a `master.info' file exists when the slave starts and contains values for the options. The following options are handled this way:
--master-host
--master-user
--master-password
--master-port
--master-connect-retry
As of MySQL 4.1.1, the following options also are handled specially:
--master-ssl
--master-ssl-ca
--master-ssl-capath
--master-ssl-cert
--master-ssl-cipher
--master-ssl-key
The `master.info' file format in 4.1.1 changed to include values corresponding to the SSL options. In addition, the 4.1.1 file format includes as its first line the number of lines in the file. If you upgrade an older server to 4.1.1, the new server upgrades the `master.info' file to the new format automatically when it starts. However, if you downgrade a 4.1.1 or newer server to a version older than 4.1.1, you should manually remove the first line before starting the older server for the first time. Note that, in this case, the downgraded server no longer can use an SSL connection to communicate with the master.
If no `master.info' file exists when the slave server starts,
it uses values for those options that are specified in option files
or on the command line. This occurs when you start the server
as a replication slave for the very first time, or when you have run
RESET SLAVE and shut down and restarted the slave server.
If the `master.info' file exists when the slave server starts, the server ignores those options. Instead, it uses the values found in the `master.info' file.
If you restart the slave server with different values of the startup options
that correspond to values in the `master.info' file, the different
values have no effect, because the server continues to use the
`master.info' file. To use different values, you must either restart
after removing the `master.info' file or (preferably) use the
CHANGE MASTER TO statement to reset the values while the slave is
running.
Suppose that you specify this option in your `my.cnf' file:
[mysqld] master-host=some_host
The first time you start the server as a replication slave, it reads and
uses that option from the `my.cnf' file. The server then records the
value in the `master.info' file. The next time you start the server,
it reads the master host value from the `master.info' file only and
ignores the value in the option file. If you modify the `my.cnf' file
to specify a different master host of some_other_host, the change
still has no effect. You should use CHANGE MASTER TO instead.
Because the server gives an existing `master.info' file precedence
over the startup options just described, you might prefer not to use startup
options for these values at all, and instead specify them by using the
CHANGE MASTER TO statement.
See section 13.6.2.1 CHANGE MASTER TO Syntax.
This example shows a more extensive use of startup options to configure a slave server:
[mysqld] server-id=2 master-host=db-master.mycompany.com master-port=3306 master-user=pertinax master-password=freitag master-connect-retry=60 report-host=db-slave.mycompany.com
The following list describes startup options for controlling replication:
Many of these options can be reset while the server is running by using the
CHANGE MASTER TO statement. Others, such as the --replicate-*
options, can be set only when the slave server starts. We plan to fix this.
--log-slave-updates
--log-bin option to
enable binary logging. --log-slave-updates is used when you want to
chain replication servers. For example, you might want a setup like this:
A -> B -> CThat is, A serves as the master for the slave B, and B serves as the master for the slave C. For this to work, B must be both a master and a slave. You must start both A and B with
--log-bin to enable binary logging,
and B with the --log-slave-updates option.
--log-warnings
--skip-log-warnings.
As of MySQL 4.0.21 and 4.1.3, aborted connections are not logged to the error
log unless the value is greater than 1.
This option is not limited to replication use only. It produces warnings
across a spectrum of server activities.
--master-connect-retry=seconds
--master-host=host
--master-info-file=file_name
--master-password=password
--master-port=port_number
configure options, this should be 3306.
--master-ssl
--master-ssl-ca=file_name
--master-ssl-capath=directory_name
--master-ssl-cert=file_name
--master-ssl-cipher=cipher_list
--master-ssl-key=file_name
--ssl,
--ssl-ca,
--ssl-capath,
--ssl-cert,
--ssl-cipher,
--ssl-key
options described in
section 5.6.7.5 SSL Command-Line Options.
The values in the `master.info' file take precedence if they can be read.
These options are operational as of MySQL 4.1.1.
--master-user=username
REPLICATION SLAVE privilege. (Prior to MySQL 4.0.2, it must have the
FILE privilege instead.)
The value in the `master.info' file takes precedence if it can be read.
If the master user is not set, user test is assumed.
--max-relay-log-size=#
--read-only
SUPER privilege. This can be useful to ensure
that a slave server accepts no updates from clients.
This option is available as of MySQL 4.0.14.
--relay-log=file_name
host_name-relay-bin.nnnnnn, where host_name is the name of
the slave server host and nnnnnn indicates that relay logs are
created in numbered sequence.
You can specify the option to create hostname-independent relay log names, or
if your relay logs tend to be big (and you don't want to decrease
max_relay_log_size) and you need to put them in some area
different from the data directory, or if you want to increase speed by
balancing load between disks.
--relay-log-index=file_name
host_name-relay-bin.index, where host_name is the name of
the slave server.
--relay-log-info-file=file_name
--relay-log-purge={0|1}
SET GLOBAL
relay_log_purge.
This option is available as of MySQL 4.1.1.
--relay-log-space-limit=#
--relay-log-space-limit to less than twice the value
of --max-relay-log-size (or --max-binlog-size if
--max-relay-log-size is 0). In that case, there is a chance that the
I/O thread waits for free space because --relay-log-space-limit
is exceeded, but the SQL thread has no relay log to purge and is
unable to satisfy the I/O thread. This forces the I/O thread to temporarily
ignore --relay-log-space-limit.
--replicate-do-db=db_name
USE)
is db_name.
To specify more than one database, use this option multiple
times, once for each database. Note that this does not replicate
cross-database statements such as UPDATE some_db.some_table
SET foo='bar' while having selected a different database or no database. If you
need cross-database updates to work, make sure that you have MySQL 3.23.28 or
later, and use --replicate-wild-do-table=db_name.%.
Please read the notes that follow this option list.
An example of what does not work as you might expect: If the slave is
started with --replicate-do-db=sales and you issue the following
statements on the master, the UPDATE statement is not
replicated:
USE prices; UPDATE sales.january SET amount=amount+1000;If you need cross-database updates to work, use
--replicate-wild-do-table=db_name.% instead.
The main reason for this ``just-check-the-default-database''
behavior is that it's difficult from the statement
alone to know whether or not it should be replicated (for example, if you
are using multiple-table DELETE or multiple-table UPDATE
statements
that go across multiple databases). It's also very fast to just check
the default database.
--replicate-do-table=db_name.tbl_name
--replicate-do-db.
Please read the notes that follow this option list.
--replicate-ignore-db=db_name
USE)
is db_name. To specify more than one database to
ignore, use this option multiple times, once for each database.
You should not use this option if you are using cross-database updates
and you don't want these updates to be replicated.
Please read the notes that follow this option list.
An example of what does not work as you might expect: If the slave is
started with --replicate-ignore-db=sales and you issue the following
statements on the master, the UPDATE statement is not replicated:
USE prices; UPDATE sales.january SET amount=amount+1000;If you need cross-database updates to work, use
--replicate-wild-ignore-table=db_name.% instead.
--replicate-ignore-table=db_name.tbl_name
--replicate-ignore-db.
Please read the notes that follow this option list.
--replicate-wild-do-table=db_name.tbl_name
LIKE pattern-matching operator. To specify
more than one table, use this option multiple times, once for each
table. This works for cross-database updates.
Please read the notes that follow this option list.
Example: --replicate-wild-do-table=foo%.bar% replicates only
updates that use a table where the database name starts with foo
and the table name starts with bar.
If the table name pattern is %, it matches any table name and the
option also applies to database-level statements (CREATE DATABASE, DROP DATABASE, and
ALTER DATABASE).
For example, if you use --replicate-wild-do-table=foo%.%,
database-level statements are replicated
if the database name matches the pattern foo%.
To include literal wildcard characters in the database or table name
patterns, escape them with a backslash. For example, to replicate all tables
of a database that is named my_own%db, but not replicate tables
from the my1ownAABCdb database, you should escape the `_' and
`%' characters like this: --replicate-wild-do-table=my\_own\%db.
If you're using the option on the command line, you might need to double
the backslashes or quote the option value, depending on your command
interpreter. For example, with the bash shell, you would need to
type --replicate-wild-do-table=my\\_own\\%db.
--replicate-wild-ignore-table=db_name.tbl_name
--replicate-wild-ignore-table=foo%.bar% does not replicate
updates that use a table where the database name starts with foo
and the table name starts with bar.
For information about how matching works, see the description of
the --replicate-wild-do-table option.
The rules for including literal wildcard characters in the option value
are the same as for
--replicate-wild-ignore-table as well.
--replicate-rewrite-db=from_name->to_name
USE)
to to_name if it was from_name on the master.
Only statements involving tables are affected
(not statements such as CREATE DATABASE, DROP DATABASE,
and ALTER DATABASE),
and only if from_name was the default database on the master.
This does not work for cross-database updates.
Note that the database name translation is done before --replicate-*
rules are tested.
If you use this option on the command line and the `>' character is
special to your command interpreter, quote the option value. For example:
shell> mysqld --replicate-rewrite-db="olddb->newdb"
--replicate-same-server-id
--log-slave-updates is used.
Be careful that starting from MySQL 4.1, by default the slave I/O thread does
not even write binary log events to the relay log if they have the slave's server
id (this optimization helps save disk usage compared to 4.0). So if you want to
use --replicate-same-server-id in 4.1 versions, be sure to start the
slave with this option before you make the slave read its own events which you
want the slave SQL thread to execute.
--report-host=host
SHOW SLAVE
HOSTS on the master server. Leave the value unset if you do not want the
slave to register itself with the master. Note that it is not sufficient for
the master to simply read the IP number of the slave from the TCP/IP socket
after the slave connects. Due to NAT and other routing issues, that IP
may not be valid for connecting to the slave from the master or other hosts.
This option is available as of MySQL 4.0.0.
--report-port=port_number
--skip-slave-start
START SLAVE statement.
--slave_compressed_protocol={0|1}
--slave-load-tmpdir=file_name
tmpdir system variable.
When the slave SQL thread replicates a LOAD DATA INFILE statement, it
extracts the to-be-loaded file from the relay log into temporary files,
then loads these into the table. If the file loaded on the master was
huge, the temporary files on the slave are huge, too. Therefore, it might
be advisable to use this option to tell the slave to put temporary files in
a directory located in some filesystem that has a lot of available space.
In that case, you may also use the --relay-log option to place
the relay logs in that filesystem, because the relay logs
are huge as well.
--slave-load-tmpdir should point to a disk-based filesystem, not a
memory-based one: The slave needs the
temporary files used to replicate LOAD DATA INFILE to survive a
machine's restart.
The directory also should not be one that is cleared by the operating system
during the system startup process.
--slave-net-timeout=seconds
--master-connect-retry option.
--slave-skip-errors= [err_code1,err_code2,... | all]
SHOW SLAVE STATUS.
The server error codes are listed in section 24 Error Handling in MySQL.
You can (but should not) also use the very non-recommended value of all
which ignores all error messages and keeps barging along regardless of what
happens. Needless to say, if you use it, we make no promises regarding your
data integrity. Please do not complain if your data on the slave is not
anywhere close to what it is on the master in this case. You have been
warned.
Examples:
--slave-skip-errors=1062,1053 --slave-skip-errors=all
The --replicate-* rules are evaluated as follows to determine whether a
statement is executed by the slave or ignored:
--replicate-do-db or --replicate-ignore-db
rules?
--binlog-do-db and --binlog-ignore-db
(see section 5.9.4 The Binary Log). What is the result of the test?
--replicate-*-table rules?
INSERT INTO sales SELECT * FROM prices: only
sales are compared to the rules). If several tables are to be
updated (multiple-table statement),
the first matching table (matching ``do'' or ``ignore'') wins.
That is, the first table is compared to the rules. Then, if no decision could
be mad, the second table is compared to the rules, and so forth.
--replicate-do-table rules?
--replicate-ignore-table rules?
--replicate-wild-do-table rules?
--replicate-wild-ignore-table rules?
--replicate-*-table rule was matched.
Is there another table to test against these rules?
--replicate-do-table or --replicate-wild-do-table
rules?
Q: How do I configure a slave if the master is running and I do not want to stop it?
A: There are several options. If you have taken a backup of the
master at some point and recorded the binary log name and offset (from the
output of SHOW MASTER STATUS ) corresponding to the snapshot, use
the following procedure:
mysql> CHANGE MASTER TO
-> MASTER_HOST='master_host_name',
-> MASTER_USER='master_user_name',
-> MASTER_PASSWORD='master_pass',
-> MASTER_LOG_FILE='recorded_log_file_name',
-> MASTER_LOG_POS=recorded_log_position;
START SLAVE on the slave.
If you do not have a backup of the master server, here is a quick procedure for creating one. All steps should be performed on the master host.
mysql> FLUSH TABLES WITH READ LOCK;
shell> tar zcf /tmp/backup.tar.gz /var/lib/mysql
mysql> SHOW MASTER STATUS;
mysql> UNLOCK TABLES;
An alternative is to make an SQL dump of the master instead of a binary copy
as in the preceding procedure. To do this, you can use mysqldump
--master-data on your master and later load the SQL dump into your slave.
However, this is slower than making a binary copy.
No matter which of the two methods you use, afterward follow the instructions for the case when you have a snapshot and have recorded the log name and offset. You can use the same snapshot to set up several slaves. Once you have the snapshot of the master, you can wait to set up a slave as long as the binary logs of the master are left intact. The two practical limitations on the length of time you can wait are the amount of disk space available to retain binary logs on the master and the length of time it takes the slave to catch up.
You can also use LOAD DATA FROM MASTER. This is a convenient
statement that transfers a snapshot to the slave and adjusts the log name
and offset all at once. In the future, LOAD DATA FROM MASTER will be
the recommended way to set up a slave. Be warned, however, that it works
only for MyISAM tables and it may hold a read lock for a long time.
It is not yet implemented as efficiently as we would like. If you have large
tables, the preferred method at this time is still to make a binary snapshot
on the master server after executing FLUSH TABLES WITH READ LOCK.
Q: Does the slave need to be connected to the master all the time?
A: No, it does not. The slave can go down or stay disconnected for hours or even days, then reconnect and catch up on the updates. For example, you can set up a master/slave relationship over a dial-up link where the link is up only sporadically and for short periods of time. The implication of this is that, at any given time, the slave is not guaranteed to be in sync with the master unless you take some special measures. In the future, we will have the option to block the master until at least one slave is in sync.
Q: How do I know how late a slave is compared to the master? In other words, how do I know the date of the last query replicated by the slave?
A:
If the slave is 4.1.1 or newer, read the Seconds_Behind_Master column
in SHOW SLAVE STATUS. For older versions, the following applies.
This is possible only if SHOW SLAVE STATUS on the slave shows that the
SQL thread is running (or for MySQL 3.23, that the slave thread is running),
and that the thread has executed at least one event from the master.
See section 6.3 Replication Implementation Details.
When the slave SQL thread executes an event read from the master, it
modifies its own time to the event timestamp (this is why TIMESTAMP
is well replicated). In the Time column in the output of
SHOW PROCESSLIST, the number of seconds displayed for the slave SQL
thread is the number of seconds between the timestamp of the last replicated
event and the real time of the slave machine. You can use this to determine
the date of the last replicated event. Note that if your slave has been
disconnected from the master for one hour, and then reconnects, you may
immediately see Time values like 3600 for the slave SQL thread in
SHOW PROCESSLIST. This would be because the slave is executing
statements that are one hour old.
Q: How do I force the master to block updates until the slave catches up?
A: Use the following procedure:
mysql> FLUSH TABLES WITH READ LOCK; mysql> SHOW MASTER STATUS;Record the log name and the offset from the output of the
SHOW
statement. These are the replication coordinates.
MASTER_POS_WAIT() function are the replication coordinate values
obtained in the previous step:
mysql> SELECT MASTER_POS_WAIT('log_name', log_offset);
The SELECT statement blocks until the slave reaches the specified
log file and offset. At that point, the slave is in sync with the master
and the statement returns.
mysql> UNLOCK TABLES;
Q: What issues should I be aware of when setting up two-way replication?
A: MySQL replication currently does not support any locking protocol between master and slave to guarantee the atomicity of a distributed (cross-server) update. In other words, it is possible for client A to make an update to co-master 1, and in the meantime, before it propagates to co-master 2, client B could make an update to co-master 2 that makes the update of client A work differently than it did on co-master 1. Thus, when the update of client A makes it to co-master 2, it produces tables that are different than what you have on co-master 1, even after all the updates from co-master 2 have also propagated. This means that you should not co-chain two servers in a two-way replication relationship unless you are sure that your updates can safely happen in any order, or unless you take care of mis-ordered updates somehow in the client code.
You must also realize that two-way replication actually does not improve performance very much (if at all), as far as updates are concerned. Both servers need to do the same number of updates each, as you would have one server do. The only difference is that there is a little less lock contention, because the updates originating on another server are serialized in one slave thread. Even this benefit might be offset by network delays.
Q: How can I use replication to improve performance of my system?
A: You should set up one server as the master and direct all
writes to it. Then configure as many slaves as you have the budget and
rackspace for, and distribute the reads among the master and the slaves.
You can also start the slaves with the --skip-innodb, --skip-bdb,
--low-priority-updates, and --delay-key-write=ALL options
to get speed improvements on the slave end. In this case, the slave
uses non-transactional MyISAM tables instead of InnoDB and
BDB tables to get more speed.
Q: What should I do to prepare client code in my own applications to use performance-enhancing replication?
A: If the part of your code that is responsible for database access has been properly abstracted/modularized, converting it to run with a replicated setup should be very smooth and easy. Just change the implementation of your database access to send all writes to the master, and to send reads to either the master or a slave. If your code does not have this level of abstraction, setting up a replicated system gives you the opportunity and motivation to it clean up. You should start by creating a wrapper library or module with the following functions:
safe_writer_connect()
safe_reader_connect()
safe_reader_statement()
safe_writer_statement()
safe_ in each function name means that the function takes care
of handling all the error conditions.
You can use different names for the
functions. The important thing is to have a unified interface for connecting
for reads, connecting for writes, doing a read, and doing a write.
You should then convert your client code to use the wrapper library. This may be a painful and scary process at first, but it pays off in the long run. All applications that use the approach just described are able to take advantage of a master/slave configuration, even one involving multiple slaves. The code is a lot easier to maintain, and adding troubleshooting options is trivial. You just need to modify one or two functions; for example, to log how long each statement took, or which statement among your many thousands gave you an error.
If you have
written a lot of code, you may want to automate the conversion
task by using the replace utility that comes with standard MySQL
distributions, or just write your own conversion script. Ideally, your
code uses consistent programming style conventions. If not, then you
are probably better off rewriting it anyway, or at least going through
and manually regularizing it to use a consistent style.
Q: When and how much can MySQL replication improve the performance of my system?
A: MySQL replication is most beneficial for a system with frequent reads and infrequent writes. In theory, by using a single-master/multiple-slave setup, you can scale the system by adding more slaves until you either run out of network bandwidth, or your update load grows to the point that the master cannot handle it.
In order to determine how many slaves you can get before the added benefits
begin to level out, and how much you can improve performance of your site,
you need to know your query patterns, and to determine empirically by
benchmarking the relationship between the throughput for reads (reads per
second, or max_reads) and for writes (max_writes) on a typical
master and a typical slave. The example here shows a rather simplified
calculation of what you can get with replication for a hypothetical system.
Let's say that system load consists of 10% writes and 90% reads, and we
have determined by benchmarking that max_reads is 1200 -
2 * max_writes. In other words, the system can do 1,200 reads per
second with no writes, the average write is twice as slow as the average
read, and the relationship is linear. Let us suppose that the master
and each slave have the same capacity, and that we have one master and N
slaves. Then we have for each server (master or slave):
reads = 1200 - 2 * writes
reads = 9 * writes / (N + 1) (reads are split, but writes go
to all servers)
9 * writes / (N + 1) + 2 * writes = 1200
writes = 1200 / (2 + 9/(N+1))
The last equation indicates that the maximum number of writes for N slaves, given a maximum possible read rate of 1,200 per minute and a ratio of nine reads per write.
This analysis yields the following conclusions:
Note that these computations assume infinite network bandwidth and neglect several other factors that could turn out to be significant on your system. In many cases, you may not be able to perform a computation similar to the one just shown that accurately predicts what will happen on your system if you add N replication slaves. However, answering the following questions should help you decide whether and how much replication will improve the performance of your system:
Q: How can I use replication to provide redundancy/high availability?
A: With the currently available features, you would have to set up a master and a slave (or several slaves), and write a script that monitors the master to see whether it is up. Then instruct your applications and the slaves to change master in case of failure. Some suggestions:
CHANGE MASTER TO
statement.
bind you can use `nsupdate' to dynamically update your DNS.
--log-bin option and without
--log-slave-updates. This way the slave is ready to become a
master as soon as you issue STOP SLAVE; RESET MASTER, and
CHANGE MASTER TO on the other slaves.
For example, assume that you have the following setup:
WC
\
v
WC----> M
/ | \
/ | \
v v v
S1 S2 S3
M means the master, S the slaves, WC the clients that issue database writes
and reads; clients that issue only database reads are not represented,
because they need not switch. S1, S2, and S3 are slaves running with
--log-bin and without --log-slave-updates.
Because updates received by a slave from the master are not logged in the
binary log unless --log-slave-updates is specified, the binary log on
each slave is empty. If for some reason M becomes unavailable, you can
pick one slave to become the new master. For example, if you pick S1,
all WC should be redirected to S1, and S2 and S3 should replicate from S1.
Make sure that all slaves have processed any statements in their relay log.
On each slave, issue STOP SLAVE IO_THREAD, then check the output
of SHOW PROCESSLIST until you see Has read all relay log.
When this is true for all slaves, they can be reconfigured to the new setup.
On the slave S1 being promoted to become the master, issue
STOP SLAVE and RESET MASTER.
On the other slaves S2 and S3, use STOP SLAVE and CHANGE MASTER
TO MASTER_HOST='S1' (where 'S1' represents the real hostname of
S1). To CHANGE MASTER, add all information about how to connect to
S1 from S2 or S3 (user, password, port). In CHANGE MASTER, there is
no need to specify the name of S1's binary log or binary log position to
read from: We know it is the first binary log and position 4, which are
the defaults for CHANGE MASTER. Finally, use START SLAVE
on S2 and S3.
Then instruct all WC to direct their statements to S1. From that point on,
all updates statements sent by WC to S1 are written to the binary log of S1,
which contains every update statement sent to S1 since M died.
The result is this configuration:
WC
/
|
WC | M(unavailable)
\ |
\ |
v v
S1<--S2 S3
^ |
+-------+
When M is up again, you just have to issue on it the same CHANGE
MASTER as the one issued on S2 and S3, so that M becomes a slave of S1 and
picks all the WC writes it has missed while it was down. To make M a
master again (because it is the most powerful machine, for example), use
the preceding procedure as if S1 was unavailable and M was to be the new
master. During the procedure, don't forget to run RESET MASTER on M
before making S1, S2, and S3 slaves of M. Otherwise, they may pick up old
WC writes from before the point at which M became unavailable.
We are currently working on integrating an automatic master election system into MySQL, but until it is ready, you have to create your own monitoring tools.
If you have followed the instructions, and your replication setup is not working, first check the following:
SHOW MASTER STATUS.
If it is, Position is non-zero. If not, verify that you are
running the master with the log-bin and server-id options.
SHOW SLAVE STATUS to check whether the
Slave_IO_Running and Slave_SQL_Running values are both
Yes.
If not, verify the options that were used when starting the slave server.
SHOW PROCESSLIST, find the I/O and SQL threads and check their
State column to see how they display.
See section 6.3 Replication Implementation Details.
If the I/O thread state says Connecting to master, verify the
privileges for the replication user on the master, master hostname, your
DNS setup, whether the master is actually running, and whether it is reachable
from the slave.
START SLAVE.
mysql> SET GLOBAL SQL_SLAVE_SKIP_COUNTER = n; mysql> START SLAVE;The value of
n should be 1 if the next statement from the master
does not use AUTO_INCREMENT or LAST_INSERT_ID(). Otherwise,
the value should be 2. The reason for using a value of 2 for statements
that use AUTO_INCREMENT or LAST_INSERT_ID() is that they
take two events in the binary log of the master.
When you have determined that there is no user error involved, and replication still either does not work at all or is unstable, it is time to send us a bug report. We need to get as much information as possible from you to be able to track down the bug. Please do spend some time and effort preparing a good bug report.
If you have a repeatable test case that demonstrates the bug, please enter it into our bugs database at http://bugs.mysql.com/. If you have a phantom problem (one that you cannot duplicate ``at will''), use the following procedure:
--log-slave-updates and --log-bin
options.
They cause the slave to log the updates that it receives from the master
into its own binary logs.
SHOW MASTER STATUS from the master at the time
you have discovered the problem
SHOW SLAVE STATUS from the master at the time
you have discovered the problem
mysqlbinlog to examine the binary logs. The following should
be helpful
to find the trouble query, for example:
shell> mysqlbinlog -j pos_from_slave_status \
/path/to/log_from_slave_status | head
Once you have collected the evidence for the phantom problem, try hard to isolate it into a separate test case first. Then enter the problem into our bugs database at http://bugs.mysql.com/ with as much information as possible.
Optimization is a complex task because ultimately it requires understanding of the entire system to be optimized. Although it may be possible to perform some local optimizations with little knowledge of your system or application, the more optimal you want your system to become, the more you have to know about it.
This chapter tries to explain and give some examples of different ways to optimize MySQL. Remember, however, that there are always additional ways to make the system even faster, although they may require increasing effort to achieve.
The most important factor in making a system fast is its basic design. You also need to know what kinds of things your system is doing, and what your bottlenecks are.
The most common system bottlenecks are:
When using the MyISAM storage engine, MySQL uses extremely fast table
locking that allows multiple readers or a single writer. The biggest problem
with this storage engine occurs when you have a steady stream of mixed
updates and slow selects on a single table. If this is a problem for
certain tables, you can use another storage engine for them. See section 14 MySQL Storage Engines and Table Types.
MySQL can work with both transactional and non-transactional tables.
To be able to work smoothly with non-transactional tables (which can't
roll back if something goes wrong), MySQL has the following rules
(when not running in strict mode or if you use the IGNORE
specifier to INSERT or UPDATE).
NULL.
(This behavior can be changed by using the
ERROR_FOR_DIVISION_BY_ZERO SQL mode).
If you are using non-transactional tables, you should not use MySQL to check column content. In general, the safest (and often fastest) way is to let the application ensure that it passes only legal values to the database.
For more information about this, see section 1.5.6 How MySQL Deals with Constraints and section 13.1.4 INSERT Syntax or
section 5.2.2 The Server SQL Mode.
Because all SQL servers implement different parts of standard SQL, it takes work to write portable SQL applications. It is very easy to achieve portability for very simple selects and inserts, but becomes more difficult the more capabilities you require. If you want an application that is fast with many database systems, it becomes even harder!
To make a complex application portable, you need to determine which SQL servers it must work with, then determine what features those servers support.
All database systems have some weak points. That is, they have different design compromises that lead to different behavior.
You can use the MySQL crash-me program to find functions, types, and
limits that you can use with a selection of database servers.
crash-me does not check for every possible feature, but it is still
reasonably comprehensive, performing about 450 tests.
An example of the type of information crash-me can provide is that
you shouldn't have column names longer than 18 characters
if you want to be able to use Informix or DB2.
The crash-me program and the MySQL benchmarks are all very database
independent. By taking a look at how they are written, you can get
a feeling for what you have to do to make your own applications database
independent. The programs can be found in the `sql-bench' directory
of MySQL source distributions. They are written in Perl and use the DBI
database interface. Use of DBI in itself solves part of the portability
problem because it provides database-independent access methods.
For crash-me results, visit
http://dev.mysql.com/tech-resources/crash-me.php.
See http://dev.mysql.com/tech-resources/benchmarks/ for the results
from the benchmarks.
If you strive for database independence, you need to get a good feeling
for each SQL server's bottlenecks. For example, MySQL is very fast in
retrieving and updating records for MyISAM tables, but has
a problem in mixing slow readers and writers on the same table. Oracle,
on the other hand, has a big problem when you try to access rows that
you have recently updated (until they are flushed to disk). Transactional
databases in general are not very good at generating summary tables from
log tables, because in this case row locking is almost useless.
To make your application really database independent, you need to define an easily extendable interface through which you manipulate your data. As C++ is available on most systems, it makes sense to use a C++ class-based interface to the databases.
If you use some feature that is specific to a given database system (such
as the REPLACE statement, which is specific to MySQL), you should
implement the same feature for other SQL servers by coding an alternative
method. Although the alternative may be slower, it allows the other
servers to perform the same tasks.
With MySQL, you can use the /*! */ syntax to add MySQL-specific
keywords to a query. The code inside /**/ is treated as a
comment (and ignored) by most other SQL servers.
If high performance is more important than exactness, as in some Web applications, it is possible to create an application layer that caches all results to give you even higher performance. By letting old results ``expire'' after a while, you can keep the cache reasonably fresh. This provides a method to handle high load spikes, in which case you can dynamically increase the cache and set the expiration timeout higher until things get back to normal.
In this case, the table creation information should contain information of the initial size of the cache and how often the table should normally be refreshed.
An alternative to implementing an application cache is to use the MySQL query cache. By enabling the query cache, the server handles the details of determining whether a query result can be reused. This simplifies your application. See section 5.11 The MySQL Query Cache.
This section describes an early application for MySQL.
During MySQL initial development, the features of MySQL were made to fit our largest customer, which handled data warehousing for a couple of the largest retailers in Sweden.
From all stores, we got weekly summaries of all bonus card transactions, and were expected to provide useful information for the store owners to help them find how their advertising campaigns were affecting their own customers.
The volume of data was quite huge (about seven million summary transactions per month), and we had data for 4-10 years that we needed to present to the users. We got weekly requests from our customers, who wanted to get ``instant'' access to new reports from this data.
We solved this problem by storing all information per month in compressed ``transaction'' tables. We had a set of simple macros that generated summary tables grouped by different criteria (product group, customer id, store, and so on) from the tables in which the transactions were stored. The reports were Web pages that were dynamically generated by a small Perl script. This script parsed a Web page, executed the SQL statements in it, and inserted the results. We would have used PHP or mod_perl instead, but they were not available at the time.
For graphical data, we wrote a simple tool in C that could process SQL query results and produce GIF images based on those results. This tool also was dynamically executed from the Perl script that parses the Web pages.
In most cases, a new report could be created simply by copying an existing script and modifying the SQL query in it. In some cases, we needed to add more columns to an existing summary table or generate a new one. This also was quite simple because we kept all transaction-storage tables on disk. (This amounted to about 50GB of transaction tables and 200GB of other customer data.)
We also let our customers access the summary tables directly with ODBC so that the advanced users could experiment with the data themselves.
This system worked well and we had no problems handling the data with quite modest Sun Ultra SPARCstation hardware (2x200MHz). Eventually the system was migrated to Linux.
This section should contain a technical description of the MySQL
benchmark suite (and crash-me), but that description has not yet
been written. Currently, you can get a good idea of the benchmarks by
looking at the code and results in the `sql-bench' directory in any
MySQL source distribution.
This benchmark suite is meant to tell any user what operations a given SQL implementation performs well or poorly.
Note that this benchmark is single-threaded, so it measures the minimum time for the operations performed. We plan to add multi-threaded tests to the benchmark suite in the future.
To use the benchmark suite, the following requirements must be satisfied:
DBD::mysql, DBD::Pg, and DBD::DB2 modules installed.
See section 2.13 Perl Installation Notes.
After you obtain a MySQL source distribution, you can find the benchmark
suite located in its `sql-bench' directory. To run the benchmark tests,
build MySQL, then
change location into the `sql-bench' directory and execute the run-all-tests
script:
shell> cd sql-bench shell> perl run-all-tests --server=server_name
server_name is one of the supported servers. To get a list of all options and supported servers, invoke this command:
shell> perl run-all-tests --help
The crash-me script also is located in the `sql-bench' directory.
crash-me tries to determine what features a database supports and
what its capabilities and limitations are by actually running
queries. For example, it determines:
VARCHAR column can be
You can find the results from crash-me for many different database
servers at http://dev.mysql.com/tech-resources/crash-me.php.
For more information about benchmark results, visit
http://dev.mysql.com/tech-resources/benchmarks/.
You should definitely benchmark your application and database to find out where the bottlenecks are. By fixing a bottleneck (or by replacing it with a ``dummy module''), you can then easily identify the next bottleneck. Even if the overall performance for your application currently is acceptable, you should at least make a plan for each bottleneck, and decide how to solve it if someday you really need the extra performance.
For an example of portable benchmark programs, look at the MySQL benchmark suite. See section 7.1.4 The MySQL Benchmark Suite. You can take any program from this suite and modify it for your needs. By doing this, you can try different solutions to your problem and test which really is fastest for you.
Another free benchmark suite is the Open Source Database Benchmark, available at http://osdb.sourceforge.net/.
It is very common for a problem to occur only when the system is very heavily loaded. We have had many customers who contact us when they have a (tested) system in production and have encountered load problems. In most cases, performance problems turn out to be due to issues of basic database design (for example, table scans are not good at high load) or problems with the operating system or libraries. Most of the time, these problems would be a lot easier to fix if the systems were not in production.
To avoid problems like this, you should put some effort into benchmarking your whole application under the worst possible load! You can use Super Smack for this. It is available at http://jeremy.zawodny.com/mysql/super-smack/. As the name suggests, it can bring a system to its knees if you ask it, so make sure to use it only on your development systems.
SELECT Statements and Other QueriesFirst, one factor affects all statements: The more complex your permission setup is, the more overhead you have.
Using simpler permissions when you issue GRANT statements enables
MySQL to reduce permission-checking overhead when clients execute
statements. For example, if you don't grant any table-level or column-level
privileges, the server need not ever check the contents of the
tables_priv and columns_priv tables. Similarly, if you place
no resource limits on any accounts, the server does not have to perform
resource counting. If you have a very high query volume, it may be worth
the time to use a simplified grant structure to reduce permission-checking
overhead.
If your problem is with some specific MySQL expression or function, you can
use the BENCHMARK() function from the mysql client program
to perform a timing test. Its syntax is
BENCHMARK(loop_count,expression). For example:
mysql> SELECT BENCHMARK(1000000,1+1); +------------------------+ | BENCHMARK(1000000,1+1) | +------------------------+ | 0 | +------------------------+ 1 row in set (0.32 sec)
This result was obtained on a Pentium II 400MHz system. It shows that MySQL can execute 1,000,000 simple addition expressions in 0.32 seconds on that system.
All MySQL functions should be very optimized, but there may be some
exceptions. BENCHMARK() is a great tool to find out if this is a
problem with your query.
EXPLAIN Syntax (Get Information About a SELECT)EXPLAIN tbl_name
Or:
EXPLAIN SELECT select_options
The EXPLAIN statement can be used either as a synonym for
DESCRIBE or as a way to obtain information about how MySQL executes
a SELECT statement:
EXPLAIN tbl_name syntax is synonymous with DESCRIBE tbl_name
or
SHOW COLUMNS FROM tbl_name.
SELECT statement with the keyword EXPLAIN,
MySQL explains how it would process the SELECT, providing
information about how tables are joined and in which order.
This section provides information about the second use of EXPLAIN.
With the help of EXPLAIN, you can see when you must add indexes
to tables to get a faster SELECT that uses indexes to find
records.
If you have a problem with incorrect index usage, you should run
ANALYZE TABLE to update table statistics such as cardinality of
keys, which can affect the choices the optimizer makes. See section 13.5.2.1 ANALYZE TABLE Syntax.
You can also see whether the optimizer joins the tables in an optimal order.
To force the optimizer to use a join order corresponding to the order
in which the tables are named in the SELECT statement, begin the
statement with SELECT STRAIGHT_JOIN rather than just SELECT.
EXPLAIN returns a row of information for each table used in the
SELECT statement. The tables are listed in the output in the order
that MySQL would read them while processing the query. MySQL resolves
all joins using a single-sweep
multi-join method. This means that MySQL reads a row from the first
table, then finds a matching row in the second table, then in the third table,
and so on. When all tables are processed, it outputs the selected columns and
backtracks through the table list until a table is found for which there are
more matching rows. The next row is read from this table and the process
continues with the next table.
In MySQL version 4.1, the EXPLAIN output format was changed to work
better with constructs such as UNION statements, subqueries, and
derived tables. Most notable is the addition of two new columns: id
and select_type. You do not see these columns when using servers
older than MySQL 4.1.
Each output row from EXPLAIN provides information about one table, and
each row consists of the following columns:
id
SELECT identifier. This is the sequential number of the
SELECT within the query.
select_type
SELECT, which can be any of the following:
SIMPLE
SELECT (not using UNION or subqueries)
PRIMARY
SELECT
UNION
SELECT statement in a UNION
DEPENDENT UNION
SELECT statement in a UNION, dependent on outer
query
UNION RESULT
UNION.
SUBQUERY
SELECT in subquery
DEPENDENT SUBQUERY
SELECT in subquery, dependent on outer query
DERIVED
SELECT (subquery in FROM clause)
table
type
system
const join type.
const
const tables are very fast because they are read only once!
const is used when you compare all parts of a
PRIMARY KEY or UNIQUE index with constant values. In the
following queries, tbl_name can be used as a const table:
SELECT * FROM tbl_name WHERE primary_key=1; SELECT * FROM tbl_name WHERE primary_key_part1=1 AND primary_key_part2=2;
eq_ref
const types, this is the best
possible join type. It is used when all parts of an index are used by
the join and the index is a PRIMARY KEY or UNIQUE index.
eq_ref can be used for indexed columns that are compared using the
= operator. The comparison value can be a constant or an expression
that uses columns from tables that are read before this table.
In the following examples, MySQL can use an eq_ref join to process
ref_table:
SELECT * FROM ref_table,other_table WHERE ref_table.key_column=other_table.column; SELECT * FROM ref_table,other_table WHERE ref_table.key_column_part1=other_table.column AND ref_table.key_column_part2=1;
ref
ref is used
if the join uses only a leftmost prefix of the key or if the key is not
a PRIMARY KEY or UNIQUE index (in other words, if the join
cannot select a single row based on the key value). If the key that is
used matches only a few rows, this is a good join type.
ref can be used for indexed columns that are compared using the =
operator.
In the following examples, MySQL can use a ref join to process
ref_table:
SELECT * FROM ref_table WHERE key_column=expr; SELECT * FROM ref_table,other_table WHERE ref_table.key_column=other_table.column; SELECT * FROM ref_table,other_table WHERE ref_table.key_column_part1=other_table.column AND ref_table.key_column_part2=1;
ref_or_null
ref, but with the addition that MySQL
does an extra search for rows that contain NULL values. This join
type optimization is new for MySQL 4.1.1 and is mostly used when resolving
subqueries.
In the following examples, MySQL can use a ref_or_null join to process
ref_table:
SELECT * FROM ref_table WHERE key_column=expr OR key_column IS NULL;See section 7.2.7 How MySQL Optimizes
IS NULL.
index_merge
key column contains a list of indexes used, and
key_len contains a list of the longest key parts for the indexes
used. For more information, see
section 7.2.6 Index Merge Optimization.
unique_subquery
ref for some IN subqueries of the following
form:
value IN (SELECT primary_key FROM single_table WHERE some_expr)
unique_subquery is just an index lookup function that replaces the
subquery completely for better efficiency.
index_subquery
unique_subquery. It replaces IN subqueries, but
it works for non-unique indexes in subqueries of the following form:
value IN (SELECT key_column FROM single_table WHERE some_expr)
range
key column indicates which index is used.
The key_len contains the longest key part that was used.
The ref column is NULL for this type.
range can be used for when a key column is compared to a
constant using any of the =, <>, >, >=, <,
<=, IS NULL, <=>, BETWEEN, or IN operators:
SELECT * FROM tbl_name WHERE key_column = 10; SELECT * FROM tbl_name WHERE key_column BETWEEN 10 and 20; SELECT * FROM tbl_name WHERE key_column IN (10,20,30); SELECT * FROM tbl_name WHERE key_part1= 10 AND key_part2 IN (10,20,30);
index
ALL, except that only the index tree
is scanned. This usually is faster than ALL, because the index
file usually is smaller than the data file.
MySQL can use this join type when the query uses only columns that are
part of a single index.
ALL
const, and usually very bad in all other
cases. Normally, you can avoid ALL by adding indexes that allow row
retrieval from the table based on constant values or column values from
earlier tables.
possible_keys
possible_keys column indicates which indexes MySQL could use to
find the rows in this table. Note that this column is totally independent of
the order of the tables as displayed in the output from EXPLAIN. That
means that some of the keys in possible_keys might not be usable in
practice with the generated table order.
If this column is NULL, there are no relevant indexes. In this case,
you may be able to improve the performance of your query by examining
the WHERE clause to see whether it refers to some column or columns
that would be suitable for indexing. If so, create an appropriate index
and check the query with EXPLAIN again.
See section 13.2.2 ALTER TABLE Syntax.
To see what indexes a table has, use SHOW INDEX FROM tbl_name.
key
key column indicates the key (index) that MySQL actually decided
to use. The key is NULL if no index was chosen. To force MySQL
to use or ignore an index listed in the possible_keys column, use
FORCE INDEX, USE INDEX, or IGNORE INDEX in your query.
See section 13.1.7 SELECT Syntax.
For MyISAM and BDB tables, running ANALYZE TABLE
helps the optimizer choose better indexes. For MyISAM tables,
myisamchk --analyze does the same. See section 13.5.2.1 ANALYZE TABLE Syntax and section 5.7.3 Table Maintenance and Crash Recovery.
key_len
key_len column indicates the length of the key that MySQL
decided to use. The length is NULL if the key column says
NULL. Note that the value of key_len allows you to determine
how many parts of a multiple-part key MySQL actually uses.
ref
ref column shows which columns or constants are used with the
key to select rows from the table.
rows
rows column indicates the number of rows MySQL
believes it must examine to execute the query.
Extra
Distinct
Not exists
LEFT JOIN optimization on the
query and does not examine more rows in this table for the previous row
combination after it finds one row that matches the LEFT JOIN criteria.
Here is an example of the type of query that can be optimized this way:
SELECT * FROM t1 LEFT JOIN t2 ON t1.id=t2.id WHERE t2.id IS NULL;Assume that
t2.id is defined as NOT NULL. In this case,
MySQL scans t1 and looks up the rows in t2 using the values
of t1.id. If MySQL finds a matching row in t2, it knows that
t2.id can never be NULL, and does not scan through the rest
of the rows in t2 that have the same id value. In other
words, for each row in t1, MySQL needs to do only a single lookup
in t2, regardless of how many rows actually match in t2.
range checked for each record (index map: #)range or index_merge access method to
retrieve rows. The applicability criteria are as described in section 7.2.5 Range Optimization
and section 7.2.6 Index Merge Optimization, with the exception that all column values for the
preceding table are known and considered to be constants.
This is not very fast, but is faster than performing a join with no index
at all.
Using filesort
WHERE clause. The keys then are
sorted and the rows are retrieved in sorted order.
See section 7.2.10 How MySQL Optimizes ORDER BY.
Using index
Using temporary
GROUP BY
and ORDER BY clauses that list columns differently.
Using where
WHERE clause is used to restrict which rows to match
against the next table or send to the client. Unless you specifically intend
to fetch or examine all rows from the table, you may have something wrong
in your query if the Extra value is not Using where
and the table join type is ALL or index.
If you want to make your queries as fast as possible, you should look out for
Extra values of Using filesort and Using temporary.
Using sort_union(...)
Using union(...)
Using intersect(...)
index_merge
join type. See section 7.2.6 Index Merge Optimization for more information.
Using index for group-by
Using index way of accessing a table, Using
index for group-by indicates that MySQL found an index that can be used
to retrieve all columns of a GROUP BY or DISTINCT query
without any extra disk access to the actual table. Additionally, the index
is used in the most efficient way so that for each group, only a few
index entries are read. For details, see
section 7.2.11 How MySQL Optimizes GROUP BY.
You can get a good indication of how good a join is by taking the
product of the values in the rows column of the EXPLAIN
output. This should tell you roughly how many rows MySQL must examine to
execute the query. If you restrict queries with the max_join_size
system variable, this product also is used to determine which multiple-table
SELECT statements to execute.
See section 7.5.2 Tuning Server Parameters.
The following example shows how a multiple-table join can be optimized
progressively based on the information provided by EXPLAIN.
Suppose that you have the SELECT statement shown here and you plan to
examine it using EXPLAIN:
EXPLAIN SELECT tt.TicketNumber, tt.TimeIn,
tt.ProjectReference, tt.EstimatedShipDate,
tt.ActualShipDate, tt.ClientID,
tt.ServiceCodes, tt.RepetitiveID,
tt.CurrentProcess, tt.CurrentDPPerson,
tt.RecordVolume, tt.DPPrinted, et.COUNTRY,
et_1.COUNTRY, do.CUSTNAME
FROM tt, et, et AS et_1, do
WHERE tt.SubmitTime IS NULL
AND tt.ActualPC = et.EMPLOYID
AND tt.AssignedPC = et_1.EMPLOYID
AND tt.ClientID = do.CUSTNMBR;
For this example, make the following assumptions:
| Table | Column | Column Type |
tt | ActualPC | CHAR(10)
|
tt | AssignedPC | CHAR(10)
|
tt | ClientID | CHAR(10)
|
et | EMPLOYID | CHAR(15)
|
do | CUSTNMBR | CHAR(15)
|
| Table | Index |
tt | ActualPC
|
tt | AssignedPC
|
tt | ClientID
|
et | EMPLOYID (primary key)
|
do | CUSTNMBR (primary key)
|
tt.ActualPC values are not evenly distributed.
Initially, before any optimizations have been performed, the EXPLAIN
statement produces the following information:
table type possible_keys key key_len ref rows Extra
et ALL PRIMARY NULL NULL NULL 74
do ALL PRIMARY NULL NULL NULL 2135
et_1 ALL PRIMARY NULL NULL NULL 74
tt ALL AssignedPC, NULL NULL NULL 3872
ClientID,
ActualPC
range checked for each record (key map: 35)
Because type is ALL for each table, this output indicates
that MySQL is generating a Cartesian product of all the tables; that is,
every combination of rows. This takes quite a long time, because the
product of the number of rows in each table must be examined. For the case
at hand, this product is 74 * 2135 * 74 * 3872 = 45,268,558,720 rows.
If the tables were bigger, you can only imagine how long it would take.
One problem here is that MySQL can use indexes on columns more efficiently
if they are declared the same. (For ISAM tables, indexes may not be
used at all unless the columns are declared the same.) In this context,
VARCHAR and CHAR are the same unless they are declared as
different lengths. Because tt.ActualPC is declared as CHAR(10)
and et.EMPLOYID is declared as CHAR(15), there is a length
mismatch.
To fix this disparity between column lengths, use ALTER TABLE to
lengthen ActualPC from 10 characters to 15 characters:
mysql> ALTER TABLE tt MODIFY ActualPC VARCHAR(15);
tt.ActualPC and et.EMPLOYID are both VARCHAR(15).
Executing the EXPLAIN statement again produces this result:
table type possible_keys key key_len ref rows Extra
tt ALL AssignedPC, NULL NULL NULL 3872 Using
ClientID, where
ActualPC
do ALL PRIMARY NULL NULL NULL 2135
range checked for each record (key map: 1)
et_1 ALL PRIMARY NULL NULL NULL 74
range checked for each record (key map: 1)
et eq_ref PRIMARY PRIMARY 15 tt.ActualPC 1
This is not perfect, but is much better: The product of the rows
values is less by a factor of 74. This version is executed in a couple
of seconds.
A second alteration can be made to eliminate the column length mismatches
for the tt.AssignedPC = et_1.EMPLOYID and tt.ClientID =
do.CUSTNMBR comparisons:
mysql> ALTER TABLE tt MODIFY AssignedPC VARCHAR(15),
-> MODIFY ClientID VARCHAR(15);
EXPLAIN produces the output shown here:
table type possible_keys key key_len ref rows Extra
et ALL PRIMARY NULL NULL NULL 74
tt ref AssignedPC, ActualPC 15 et.EMPLOYID 52 Using
ClientID, where
ActualPC
et_1 eq_ref PRIMARY PRIMARY 15 tt.AssignedPC 1
do eq_ref PRIMARY PRIMARY 15 tt.ClientID 1
This is almost as good as it can get.
The remaining problem is that, by default, MySQL assumes that values
in the tt.ActualPC column are evenly distributed, and that is not the
case for the tt table. Fortunately, it is easy to tell MySQL
to analyze the key distribution:
mysql> ANALYZE TABLE tt;
The join is perfect, and EXPLAIN produces this result:
table type possible_keys key key_len ref rows Extra
tt ALL AssignedPC NULL NULL NULL 3872 Using
ClientID, where
ActualPC
et eq_ref PRIMARY PRIMARY 15 tt.ActualPC 1
et_1 eq_ref PRIMARY PRIMARY 15 tt.AssignedPC 1
do eq_ref PRIMARY PRIMARY 15 tt.ClientID 1
Note that the rows column in the output from EXPLAIN is an
educated guess from the MySQL join optimizer. You should check whether the
numbers are even close to the truth. If not, you may get better performance
by using STRAIGHT_JOIN in your SELECT statement and trying
to list the tables in a different order in the FROM clause.
In most cases, you can estimate the performance by counting disk seeks.
For small tables, you can usually find a row in one disk seek (because the
index is probably cached). For bigger tables, you can estimate that,
using B-tree indexes, you need this many seeks to find a row:
log(row_count) / log(index_block_length / 3 * 2 /
(index_length + data_pointer_length)) +
1.
In MySQL, an index block is usually 1024 bytes and the data
pointer is usually 4 bytes. For a 500,000-row table with an
index length of 3 bytes (medium integer), the formula indicates
log(500,000)/log(1024/3*2/(3+4)) + 1 = 4 seeks.
This index would require storage of about 500,000 * 7 * 3/2 = 5.2MB (assuming a typical index buffer fill ratio of 2/3), so you probably have much of the index in memory and you probably need only one or two calls to read data to find the row.
For writes, however, you need four seek requests (as above) to find where to place the new index and normally two seeks to update the index and write the row.
Note that the preceding discussion doesn't mean that your application
performance slowly degenerates by log N. As long as everything
is cached by the OS or the MySQL server, things become only marginally
slower as the table gets bigger. After the data gets too big to be cached,
things start to go much slower until your applications are only bound
by disk-seeks (which increase by log N). To avoid this, increase the key
cache size as the data grows. For MyISAM tables, the key cache
size is controlled by the key_buffer_size system variable.
See section 7.5.2 Tuning Server Parameters.
SELECT Queries
In general, when you want to make a slow SELECT ... WHERE query
faster, the first thing to check is whether you can add an index.
All references between different tables should usually be done with
indexes. You can use the EXPLAIN statement to determine which
indexes are used for a SELECT.
See section 7.4.5 How MySQL Uses Indexes and
section 7.2.1 EXPLAIN Syntax (Get Information About a SELECT).
Some general tips for speeding up queries on MyISAM tables:
ANALYZE TABLE or
run myisamchk --analyze on a table after it has been loaded with
data. This updates a value for each index part that indicates the average
number of rows that have the same value. (For unique indexes, this is
always 1.) MySQL uses this to decide which index to choose when you
join two tables based on a non-constant expression. You can check the
result from the table analysis by using SHOW INDEX FROM tbl_name
and examining the Cardinality value. myisamchk --description
--verbose shows index distribution information.
myisamchk
--sort-index --sort-records=1 (if you want to sort on index 1). This is
a good way to make queries faster if you have a unique index from which
you want to read all records in order according to the index. Note that
the first time you sort a large table this way, it may take a long time.
WHERE Clauses
This section discusses optimizations that can be made for processing
WHERE clauses. The examples use SELECT statements, but
the same optimizations apply for WHERE clauses in DELETE
and UPDATE statements.
Note that work on the MySQL optimizer is ongoing, so this section is incomplete. MySQL does many optimizations, not all of which are documented here.
Some of the optimizations performed by MySQL are listed here:
((a AND b) AND c OR (((a AND b) AND (c AND d)))) -> (a AND b AND c) OR (a AND b AND c AND d)
(a<b AND b=c) AND a=5 -> b>5 AND b=c AND a=5
(B>=5 AND B=5) OR (B=6 AND 5=5) OR (B=7 AND 5=6) -> B=5 OR B=6
COUNT(*) on a single table without a WHERE is retrieved
directly from the table information for MyISAM and HEAP tables.
This is also done for any NOT NULL expression when used with only one
table.
SELECT statements are impossible and returns no rows.
HAVING is merged with WHERE if you don't use GROUP BY
or group functions (COUNT(), MIN(), and so on).
WHERE is constructed to get a fast
WHERE evaluation for the table and also to skip records as
soon as possible.
WHERE clause on a PRIMARY KEY
or a UNIQUE index, where all index parts are compared to constant
expressions and are defined as NOT NULL.
SELECT * FROM t WHERE primary_key=1;
SELECT * FROM t1,t2
WHERE t1.primary_key=1 AND t2.primary_key=t1.id;
ORDER BY and GROUP
BY clauses come from the same table, that table is preferred first when
joining.
ORDER BY clause and a different GROUP BY
clause, or if the ORDER BY or GROUP BY contains columns
from tables other than the first table in the join queue, a temporary
table is created.
SQL_SMALL_RESULT, MySQL uses an in-memory
temporary table.
HAVING clause
are skipped.
Some examples of queries that are very fast:
SELECT COUNT(*) FROM tbl_name;
SELECT MIN(key_part1),MAX(key_part1) FROM tbl_name;
SELECT MAX(key_part2) FROM tbl_name
WHERE key_part1=constant;
SELECT ... FROM tbl_name
ORDER BY key_part1,key_part2,... LIMIT 10;
SELECT ... FROM tbl_name
ORDER BY key_part1 DESC, key_part2 DESC, ... LIMIT 10;
The following queries are resolved using only the index tree, assuming that the indexed columns are numeric:
SELECT key_part1,key_part2 FROM tbl_name WHERE key_part1=val;
SELECT COUNT(*) FROM tbl_name
WHERE key_part1=val1 AND key_part2=val2;
SELECT key_part2 FROM tbl_name GROUP BY key_part1;
The following queries use indexing to retrieve the rows in sorted order without a separate sorting pass:
SELECT ... FROM tbl_name
ORDER BY key_part1,key_part2,... ;
SELECT ... FROM tbl_name
ORDER BY key_part1 DESC, key_part2 DESC, ... ;
The range access method uses a single index to retrieve a subset
of table records that are contained within one or several index value
intervals. It can be used for a single-part or multiple-part index.
A detailed description of how intervals are extracted from the
WHERE clause is given in the following sections.
For a single-part index, index value intervals can be conveniently
represented by corresponding conditions in the WHERE clause, so
we'll talk about ``range conditions'' instead of intervals.
The definition of a range condition for a single-part index is as follows:
BTREE and HASH indexes, comparison of a key part with
a constant value is a range condition when using the =, <=>,
IN, IS NULL, or IS NOT NULL operators.
BTREE indexes, comparison of a key part with a constant
value is a range condition when using the >, <, >=,
<=, BETWEEN, !=, or <> operators, or LIKE
'pattern' (where 'pattern' doesn't start with a
wildcard).
OR
or AND form a range condition.
``Constant value'' in the preceding descriptions means one of the following:
const or system table from the same join
Here are some examples of queries with range conditions in the
WHERE clause:
SELECT * FROM t1 WHERE key_col > 1 AND key_col < 10; SELECT * FROM t1 WHERE key_col = 1 OR key_col IN (15,18,20); SELECT * FROM t1 WHERE key_col LIKE 'ab%' OR key_col BETWEEN 'bar' AND 'foo';
Note that some non-constant values may be converted to constants during the constant propagation phase.
MySQL tries to extract range conditions from the WHERE clause for
each of the possible indexes. During the extraction process, conditions
that can't be used for constructing the range condition are dropped,
conditions that produce overlapping ranges are combined, and conditions that
produce empty ranges are removed.
For example, consider the following statement, where key1 is an
indexed column and nonkey is not indexed:
SELECT * FROM t1 WHERE (key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR (key1 < 'bar' AND nonkey = 4) OR (key1 < 'uux' AND key1 > 'z');
The extraction process for key key1 is as follows:
WHERE clause:
(key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR (key1 < 'bar' AND nonkey = 4) OR (key1 < 'uux' AND key1 > 'z')
nonkey = 4 and key1 LIKE '%b' because they cannot be
used for a range scan. The right way to remove them is to replace them
with TRUE, so that we don't miss any matching records when doing
the range scan. Having replaced them with TRUE, we get:
(key1 < 'abc' AND (key1 LIKE 'abcde%' OR TRUE)) OR (key1 < 'bar' AND TRUE) OR (key1 < 'uux' AND key1 > 'z')
(key1 LIKE 'abcde%' OR TRUE) is always true
(key1 < 'uux' AND key1 > 'z') is always false
(key1 < 'abc' AND TRUE) OR (key1 < 'bar' AND TRUE) OR (FALSE)Removing unnecessary
TRUE and FALSE constants, we obtain
(key1 < 'abc') OR (key1 < 'bar')
(key1 < 'bar')
In general (and as demonstrated in the example), the condition used for
a range scan is less restrictive than the WHERE clause. MySQL
performs an additional check to filter out rows that satisfy the range
condition but not the full WHERE clause.
The range condition extraction algorithm can handle nested
AND/OR constructs of arbitrary depth, and its output doesn't
depend on the order in which conditions appear in WHERE clause.
Range conditions on a multiple-part index are an extension of range conditions for a single-part index. A range condition on a multiple-part index restricts index records to lie within one or several key tuple intervals. Key tuple intervals are defined over a set of key tuples, using ordering from the index.
For example, consider a multiple-part index defined as
key1(key_part1, key_part2, key_part3), and the
following set of key tuples listed in key order:
key_part1 key_part2 key_part3 NULL 1 'abc' NULL 1 'xyz' NULL 2 'foo' 1 1 'abc' 1 1 'xyz' 1 2 'abc' 2 1 'aaa'
The condition key_part1 = 1 defines this interval:
(1, -inf, -inf) <= (key_part1, key_part2, key_part3) < (1, +inf, +inf)
The interval covers the 4th, 5th, and 6th tuples in the preceding data set and can be used by the range access method.
By contrast, the condition key_part3 = 'abc' does not define a single
interval and cannot be used by the range access method.
The following descriptions indicate how range conditions work for multiple-part indexes in greater detail.
HASH indexes, each interval containing identical values
can be used. This means that the interval can be produced only for
conditions in the following form:
key_part1 cmp const1
AND key_part2 cmp const2
AND ...
AND key_partN cmp constN;
Here, const1, const2, ... are constants, cmp is one of
the =, <=>, or IS NULL comparison operators, and the
conditions cover all index parts. (That is, there are N conditions,
one for each part of an N-part index.)
See section 7.2.5.1 Range Access Method for Single-Part Indexes for the definition of
what is considered to be a constant.
For example, the following is a range condition for a three-part
HASH index:
key_part1 = 1 AND key_part2 IS NULL AND key_part3 = 'foo'
BTREE index, an interval might be usable for conditions
combined with AND, where each condition compares a key part with
a constant value using =, <=>, IS NULL, >,
<, >=, <=, !=, <>, BETWEEN, or
LIKE 'pattern' (where 'pattern' doesn't start
with a wildcard). An interval can be used as long as it is possible to
determine a single key tuple containing all records that match the condition
(or two intervals if <> or != is used). For example, for
this condition:
key_part1 = 'foo' AND key_part2 >= 10 AND key_part3 > 10The single interval is:
('foo', 10, 10)
< (key_part1, key_part2, key_part3)
< ('foo', +inf, +inf)
It is possible that
the created interval contains more records than the initial condition.
For example, the preceding interval includes the value ('foo', 11, 0),
which does not satisfy the original condition.
OR, they form a condition that covers a set of records
contained within the union of their intervals. If the conditions are combined
with AND, they form a condition that covers a set of records
contained within the intersection of their intervals. For example, for
this condition on a two-part index:
(key_part1 = 1 AND key_part2 < 2) OR (key_part1 > 5)The intervals is:
(1, -inf) < (key_part1, key_part2) < (1, 2) (5, -inf) < (key_part1, key_part2)In this example, the interval on the first line uses one key part for the left bound and two key parts for the right bound. The interval on the second line uses only one key part. The
key_len column in the EXPLAIN
output indicates the maximum length of the key prefix used.
In some cases, key_len may indicate that a key part was used, but
that might be not what you would expect. Suppose that key_part1
and key_part2 can be NULL. Then the key_len column
displays two key part lengths for the following condition:
key_part1 >= 1 AND key_part2 < 2But in fact, the condition is converted to this:
key_part1 >= 1 AND key_part2 IS NOT NULL
section 7.2.5.1 Range Access Method for Single-Part Indexes describes how optimizations are performed to combine or eliminate intervals for range conditions on single-part index. Analogous steps are performed for range conditions on multiple-part keys.
The Index Merge (index_merge) method is used to retrieve rows with
several ref, ref_or_null, or range scans and merge
the results into one. This method is employed when the table condition
is a disjunction of conditions for which ref, ref_or_null,
or range could be used with different keys.
This ``join'' type optimization is new in MySQL 5.0.0, and represents a significant change in behavior with regard to indexes, because the old rule was that the server is only ever able to use at most one index for each referenced table.
In EXPLAIN output, this method appears as index_merge in the
type column. In this case, the key column contains a list of
indexes used, and key_len contains a list of the longest key parts
for those indexes.
Examples:
SELECT * FROM tbl_name WHERE key_part1 = 10 OR key_part2 = 20;
SELECT * FROM tbl_name
WHERE (key_part1 = 10 OR key_part2 = 20) AND non_key_part=30;
SELECT * FROM t1, t2
WHERE (t1.key1 IN (1,2) OR t1.key2 LIKE 'value%')
AND t2.key1=t1.some_col;
SELECT * FROM t1, t2
WHERE t1.key1=1
AND (t2.key1=t1.some_col OR t2.key2=t1.some_col2);
The Index Merge method has several access algorithms (seen in the
Extra field of EXPLAIN output):
The following sections describe these methods in greater detail.
Note: The Index Merge optimization algorithm has the following known deficiencies:
SELECT * FROM t1 WHERE (goodkey1 < 10 OR goodkey2 < 20) AND badkey < 30;For this query, two plans are possible:
(goodkey1 < 10 OR goodkey2 < 20)
condition.
badkey < 30 condition.
index_merge by using
IGNORE INDEX or FORCE INDEX. The following queries are
executed using Index Merge:
SELECT * FROM t1 FORCE INDEX(goodkey1,goodkey2) WHERE (goodkey1 < 10 OR goodkey2 < 20) AND badkey < 30; SELECT * FROM t1 IGNORE INDEX(badkey) WHERE (goodkey1 < 10 OR goodkey2 < 20) AND badkey < 30;
WHERE clause with deep
AND/OR nesting and MySQL doesn't choose the optimal plan,
try distributing terms using the following identity laws:
(x AND y) OR z = (x OR z) AND (y OR z) (x OR y) AND z = (x AND z) OR (y AND z)
The choice between different possible variants of the index_merge
access method and other access methods is based on cost estimates of
various available options.
This access algorithm can be employed when a WHERE clause was
converted to several range conditions on different keys combined with
AND, and each condition is one of the following:
key_part1=const1 AND key_part2=const2 ... AND key_partN=constN
InnoDB
or BDB
table.
Here are some examples:
SELECT * FROM innodb_table WHERE primary_key < 10 AND key_col1=20; SELECT * FROM tbl_name WHERE (key1_part1=1 AND key1_part2=2) AND key2=2;
The Index Merge intersection algorithm performs simultaneous scans on all used indexes and produces the intersection of row sequences that it receives from the merged index scans.
If all columns used in the query are covered by the used indexes, full
table records are not retrieved and (EXPLAIN output contains
Using index in Extra field in this case). Here is an example
of such query:
SELECT COUNT(*) FROM t1 WHERE key1=1 AND key2=1;
If the used indexes don't cover all columns used in the query, full records are retrieved only when the range conditions for all used keys are satisfied.
If one of the merged conditions is a condition over a primary key of an
InnoDB or BDB table, it is not used for record retrieval,
but is used to filter out records retrieved using other conditions.
The applicability criteria for this algorithm are similar to those of the
Index Merge method intersection algorithm. The algorithm can be
employed when the table WHERE clause was converted to several range
conditions on different keys combined with OR, and each condition
is one of the following:
key_part1=const1 AND key_part2=const2 ... AND key_partN=constN
InnoDB or BDB table.
Here are some examples:
SELECT * FROM t1 WHERE key1=1 OR key2=2 OR key3=3; SELECT * FROM innodb_table WHERE (key1=1 AND key2=2) OR (key3='foo' AND key4='bar') AND key5=5;
This access algorithm is employed when the WHERE clause was converted
to several range conditions combined by OR, but for which the
Index Merge method union algorithm is not applicable.
Here are some examples:
SELECT * FROM tbl_name WHERE key_col1 < 10 OR key_col2 < 20;
SELECT * FROM tbl_name
WHERE (key_col1 > 10 OR key_col2 = 20) AND nonkey_col=30;
The difference between the sort-union algorithm and the union algorithm is that the sort-union algorithm must first fetch row IDs for all records and sort them before returning any records.
IS NULL
MySQL can do the same optimization on col_name IS NULL that it can do
with col_name = constant_value. For example, MySQL can use
indexes and ranges to search for NULL with IS NULL.
SELECT * FROM tbl_name WHERE key_col IS NULL;
SELECT * FROM tbl_name WHERE key_col <=> NULL;
SELECT * FROM tbl_name
WHERE key_col=const1 OR key_col=const2 OR key_col IS NULL;
If a WHERE clause includes a col_name IS NULL condition for a
column that is declared as NOT NULL, that expression is
optimized away. This optimization does not occur in cases when the column
might produce NULL anyway; for example, if it comes from a table on
the right side of a LEFT JOIN.
MySQL 4.1.1 and up can additionally optimize the combination
col_name = expr AND col_name IS NULL,
a form that is common in resolved subqueries.
EXPLAIN shows ref_or_null when this
optimization is used.
This optimization can handle one IS NULL for any key part.
Some examples of queries that are optimized, assuming that there is an index
on columns a and b of table t2:
SELECT * FROM t1 WHERE t1.a=expr OR t1.a IS NULL;
SELECT * FROM t1, t2 WHERE t1.a=t2.a OR t2.a IS NULL;
SELECT * FROM t1, t2
WHERE (t1.a=t2.a OR t2.a IS NULL) AND t2.b=t1.b;
SELECT * FROM t1, t2
WHERE t1.a=t2.a AND (t2.b=t1.b OR t2.b IS NULL);
SELECT * FROM t1, t2
WHERE (t1.a=t2.a AND t2.a IS NULL AND ...)
OR (t1.a=t2.a AND t2.a IS NULL AND ...);
ref_or_null works by first doing a read on the reference key,
and then a separate search for rows with a NULL key value.
Note that the optimization can handle only one IS NULL level.
In the following query, MySQL uses key lookups only on the expression
(t1.a=t2.a AND t2.a IS NULL) and is not able to use the key part on
b:
SELECT * FROM t1, t2
WHERE (t1.a=t2.a AND t2.a IS NULL)
OR (t1.b=t2.b AND t2.b IS NULL);
DISTINCT
DISTINCT combined with ORDER BY
needs a temporary table in many cases.
Note that because DISTINCT may use GROUP BY, you should be
aware of how MySQL works with columns in ORDER BY or HAVING
clauses that are not part of the selected columns.
See section 12.9.3 GROUP BY with Hidden Fields.
In most cases, a DISTINCT clause can be considered as a special case
of GROUP BY. For example, the following two queries are equivalent:
SELECT DISTINCT c1, c2, c3 FROM t1 WHERE c1 > const; SELECT c1, c2, c3 FROM t1 WHERE c1 > const GROUP BY c1, c2, c3;
Due to this equivalence, the optimizations applicable to GROUP BY
queries can be also applied to queries with a DISTINCT clause. Thus,
for more details on the optimization possibilities for DISTINCT
queries, see section 7.2.11 How MySQL Optimizes GROUP BY.
When combining LIMIT row_count with DISTINCT, MySQL stops
as soon as it finds row_count unique rows.
If you don't use columns from all tables named in a query, MySQL stops
scanning the not-used tables as soon as it finds the first match.
In the following case, assuming that t1 is used before t2
(which you can check with EXPLAIN), MySQL stops reading from t2
(for any particular row in t1) when the first row in t2
is found:
SELECT DISTINCT t1.a FROM t1, t2 where t1.a=t2.a;
LEFT JOIN and RIGHT JOIN
A LEFT JOIN B join_condition is implemented in MySQL as follows:
B is set to depend on table A and all tables
on which A depends.
A is set to depend on all tables (except B)
that are used in the LEFT JOIN condition.
LEFT JOIN condition is used to decide how to retrieve rows
from table B. (In other words, any condition in the WHERE clause
is not used.)
WHERE optimizations are done.
A that matches the WHERE clause, but there
is no row in B that matches the ON condition,
an extra B row is generated with all columns set to NULL.
LEFT JOIN to find rows that don't exist in some
table and you have the following test: col_name IS NULL in the
WHERE part, where col_name is a column that is declared as
NOT NULL, MySQL stops searching for more rows
(for a particular key combination) after it has found one row that
matches the LEFT JOIN condition.
RIGHT JOIN is implemented analogously to LEFT JOIN, with the
roles of the tables reversed.
The join optimizer calculates the order in which tables should be joined.
The table read order forced by LEFT JOIN and STRAIGHT_JOIN
helps the join optimizer do its work much more quickly, because there are
fewer table permutations to check.
Note that this means that if you do a query of the following type,
MySQL does a full scan on b because the LEFT JOIN forces
it to be read before d:
SELECT *
FROM a,b LEFT JOIN c ON (c.key=a.key) LEFT JOIN d ON (d.key=a.key)
WHERE b.key=d.key;
The fix in this case is to rewrite the query as follows:
SELECT *
FROM b,a LEFT JOIN c ON (c.key=a.key) LEFT JOIN d ON (d.key=a.key)
WHERE b.key=d.key;
Starting from 4.0.14, MySQL does the following LEFT JOIN optimization:
If the WHERE condition is always false for the generated
NULL row, the LEFT JOIN is changed to a normal join.
For example, the WHERE clause would be
false in the following query
if t2.column1 would be NULL:
SELECT * FROM t1 LEFT JOIN t2 ON (column1) WHERE t2.column2=5;
Therefore, it's safe to convert the query to a normal join:
SELECT * FROM t1, t2 WHERE t2.column2=5 AND t1.column1=t2.column1;
This can be made faster because MySQL can use table t2 before
table t1 if this would result in a better query plan. To force a
specific table order, use STRAIGHT_JOIN.
ORDER BY
In some cases, MySQL can use an index to satisfy an ORDER BY
clause without doing any extra sorting.
The index can also be used even if the ORDER BY doesn't match the
index exactly, as long as all the unused index parts and all the extra
are ORDER BY columns are constants in the WHERE
clause. The following queries use the index to resolve the
ORDER BY part:
SELECT * FROM t1 ORDER BY key_part1,key_part2,... ;
SELECT * FROM t1 WHERE key_part1=constant ORDER BY key_part2;
SELECT * FROM t1 ORDER BY key_part1 DESC, key_part2 DESC;
SELECT * FROM t1
WHERE key_part1=1 ORDER BY key_part1 DESC, key_part2 DESC;
In some cases, MySQL cannot use indexes to resolve the ORDER
BY, although it still uses indexes to find the rows that
match the WHERE clause. These cases include the following:
ORDER BY on different keys:
SELECT * FROM t1 ORDER BY key1, key2;
ORDER BY on non-consecutive key parts:
SELECT * FROM t1 WHERE key2=constant ORDER BY key_part2;
ASC and DESC:
SELECT * FROM t1 ORDER BY key_part1 DESC, key_part2 ASC;
ORDER BY:
SELECT * FROM t1 WHERE key2=constant ORDER BY key1;
ORDER
BY are not all from the first non-constant table that is used to
retrieve rows. (This is the first table in the EXPLAIN output that
doesn't have a const join type.)
ORDER BY and GROUP BY expressions.
HASH index in a HEAP table.
With EXPLAIN SELECT ... ORDER BY, you can check whether MySQL can use
indexes to resolve the query. It cannot if you see Using filesort in
the Extra column.
See section 7.2.1 EXPLAIN Syntax (Get Information About a SELECT).
In those cases where MySQL must sort the result, it uses the following
filesort algorithm before MySQL 4.1:
WHERE clause are skipped.
sort_buffer_size
system variable.
MERGEBUFF (7) regions to one block in
another temporary file. Repeat until all blocks from the first file
are in the second file.
MERGEBUFF2 (15)
blocks left.
read_rnd_buffer_size system variable.
The code for this step is in the `sql/records.cc' source file.
One problem with this approach is that it reads rows twice: One time when
evaluating the WHERE clause, and again after sorting the pair values.
And even if the rows were accessed successively the first time (for example,
if a table scan is done), the second time they are accessed randomly. (The
sort keys are ordered, but the row positions are not.)
In MySQL 4.1 and up, a filesort optimization is used that records not
only the sort key value and row position, but also the columns required for
the query. This avoids reading the rows twice. The modified filesort
algorithm works like this:
WHERE clause, as before.
Using the modified filesort algorithm, the tuples are longer than the
pairs used in the original method, and fewer of them fit in the sort buffer
(the size of which is given by sort_buffer_size). As a result, it is
possible for the extra I/O to make the modified approach slower, not faster.
To avoid a slowdown, the optimization is used only if the total size of the
extra columns in the sort tuple does not exceed the value of the
max_length_for_sort_data system variable. (A symptom of setting the
value of this variable too high is that you should see high disk activity and
low CPU activity.)
If you want to increase ORDER BY speed, first see whether you can get
MySQL to use indexes rather than an extra sorting phase. If this is not
possible, you can try the following strategies:
sort_buffer_size variable.
read_rnd_buffer_size variable.
tmpdir to point to a dedicated filesystem with lots of empty
space. If you use MySQL 4.1 or later, this option accepts several paths
that are used in round-robin fashion. Paths should be separated by colon
characters (`:') on Unix and semicolon characters (`;') on
Windows, NetWare, and OS/2. You can use this feature to spread the load
across several directories. Note: The paths should be for
directories in filesystems that are located on different physical
disks, not different partitions of the same disk.
By default, MySQL sorts all GROUP BY col1, col2, ... queries as if
you specified ORDER BY col1, col2, ... in the query as well. If you
include an ORDER BY clause explicitly that contains the same column
list, MySQL optimizes it away without any speed penalty, although the sorting
still occurs. If a query includes GROUP BY but you want to avoid the
overhead of sorting the result, you can suppress sorting by specifying
ORDER BY NULL. For example:
INSERT INTO foo SELECT a, COUNT(*) FROM bar GROUP BY a ORDER BY NULL;
GROUP BY
The most general way to satisfy a GROUP BY clause is to scan the whole
table and create a new temporary table where all rows from each group are
consecutive, and then use this temporary table to discover groups and apply
aggregate functions (if any). In some cases, MySQL is able to do much better
than that and to avoid creation of temporary tables by using index access.
The most important preconditions for using indexes for GROUP BY are
that all GROUP BY columns reference attributes from the same index,
and the index stores its keys in order (for example, this is a B-Tree index,
and not a HASH index). Whether usage of temporary tables can be replaced by
index access also depends on which parts of an index are used in a query, the
conditions specified for these parts, and the selected aggregate functions.
There are two ways to execute a GROUP BY query via index access,
as detailed in the following sections. In the first method, the grouping
operation is applied together with all range predicates (if any). The second
method first performs a range scan, and then groups the resulting tuples.
The most efficient way is when the index is used to directly retrieve
the group fields. With this access method, MySQL uses the property of
some index types (for example, B-Trees) that the keys are ordered. This
property allows use of lookup groups in an index without having to consider
all keys in the index that satisfy all WHERE conditions. Since
this access method considers only a fraction of the keys in an index,
it is called ``loose index scan.'' When there is no WHERE clause,
a loose index scan reads as many keys as the number of groups, which
may be a much smaller number than all keys. If the WHERE clause
contains range predicates (described in section 7.2.1 EXPLAIN Syntax (Get Information About a SELECT),
under the range join type), a loose index scan looks up the first key of
each group that satisfies the range conditions, and again reads the least
possible number of keys. This is possible under the following conditions:
GROUP BY includes the first consecutive parts of the index
(if instead of GROUP BY, the query has a DISTINCT clause,
then all distinct attributes refer to the beginning of the index).
MIN() and MAX(),
and all of them refer to the same column.
GROUP BY referenced in the
query must be constants (that is, they must be referenced in equalities
with constants), except for the argument of MIN() or MAX()
functions.
The EXPLAIN output for such queries shows Using index for
group-by in the Extra column.
The following queries provide several examples that fall into this
category, assuming there is an index idx(c1, c2, c3) on table
t1(c1,c2,c3,c4):
SELECT c1, c2 FROM t1 GROUP BY c1, c2; SELECT DISTINCT c1, c2 FROM t1; SELECT c1, MIN(c2) FROM t1 GROUP BY c1; SELECT c1, c2 FROM t1 WHERE c1 < const GROUP BY c1, c2; SELECT MAX(c3), MIN(c3), c1, c2 FROM t1 WHERE c2 > const GROUP BY c1, c2; SELECT c2 FROM t1 WHERE c1 < const GROUP BY c1, c2; SELECT c1, c2 FROM t1 WHERE c3 = const GROUP BY c1, c2;
The following queries cannot be executed with this quick select method, for the reasons given:
MIN() or MAX():
SELECT c1, SUM(c2) FROM t1 GROUP BY c1;
GROUP BY do not refer to the beginning of the index:
SELECT c1,c2 FROM t1 GROUP BY c2, c3;
GROUP BY parts,
and for which there is no equality with a constant:
SELECT c1,c3 FROM t1 GROUP BY c1, c2;
A tight index scan may be either a full index scan or a range index scan, depending on the query conditions.
When the conditions for a loose index scan are not met, it is still
possible to avoid creation of temporary tables for GROUP BY
queries. If there are range conditions in the WHERE clause, this
method reads only the keys that satisfy these conditions. Otherwise,
it performs an index scan. Since this method reads all keys in each range
defined by the WHERE clause, or scans the whole index if there are
no range conditions, we term it a ``tight index scan.'' Notice that with a
tight index scan, the grouping operation is performed after all keys that
satisfy the range conditions have been found.
For this method to work, it is sufficient that for all columns in a query
referring to key parts before or in between the GROUP BY key parts,
there is a constant equality condition. The constants from the equality
conditions fill in the ``gaps'' in the search keys so that it is possible
to form complete prefixes of the index. Then these index prefixes can
be used for index lookups. If we require sorting of the GROUP BY
result, and it is possible to form search keys that are prefixes of the
index, MySQL also avoids sorting because searching with prefixes in
an ordered index retrieves all keys in order.
The following queries do not work with the first method above, but
still work with the second index access method (assuming we have the
aforementioned index idx on table t1):
GROUP BY, but it is covered by the condition (c2 = 'a').
SELECT c1, c2, c3 FROM t1 WHERE c2 = 'a' GROUP BY c1, c3;
GROUP BY does not begin from the first key part, but there is a
condition that provides a constant for that key part:
SELECT c1, c2, c3 FROM t1 WHERE c1 = 'a' GROUP BY c2, c3;
LIMIT
In some cases, MySQL handles a query differently when you are
using LIMIT row_count and not using HAVING:
LIMIT, MySQL
uses indexes in some cases when normally it would prefer to do a
full table scan.
LIMIT row_count with ORDER BY, MySQL ends the
sorting as soon as it has found the first row_count lines rather
than sorting the whole table.
LIMIT row_count with DISTINCT, MySQL stops
as soon as it finds row_count unique rows.
GROUP BY can be resolved by reading the key in order
(or doing a sort on the key) and then calculating summaries until the
key value changes. In this case, LIMIT row_count does not calculate any
unnecessary GROUP BY values.
SQL_CALC_FOUND_ROWS.
LIMIT 0 always quickly returns an empty set. This is useful
to check the query or to get the column types of the result columns.
LIMIT row_count is used to calculate how much space is required.
The output from EXPLAIN shows ALL in the type
column when MySQL uses a table scan to resolve a query. This usually happens
under the following conditions:
ON or WHERE clause
for indexed columns.
WHERE Clauses.
For small tables, a table scan often is appropriate. For large tables, try the following techniques to avoid having the optimizer incorrectly choose a table scan:
ANALYZE TABLE tbl_name to update the key distributions for the
scanned table. See section 13.5.2.1 ANALYZE TABLE Syntax.
FORCE INDEX for the scanned table to tell MySQL that table
scans are very expensive compared to using the given index.
See section 13.1.7 SELECT Syntax.
SELECT * FROM t1, t2 FORCE INDEX (index_for_column) WHERE t1.col_name=t2.col_name;
mysqld with the --max-seeks-for-key=1000 option or use
SET max_seeks_for_key=1000 to tell the optimizer to assume that no
key scan causes more than 1,000 key seeks.
See section 5.2.3 Server System Variables.
INSERT StatementsThe time to insert a record is determined by the following factors, where the numbers indicate approximate proportions:
This does not take into consideration the initial overhead to open tables, which is done once for each concurrently running query.
The size of the table slows down the insertion of indexes by log N, assuming B-tree indexes.
You can use the following methods to speed up inserts:
INSERT statements with multiple VALUES lists to insert several
rows at a time. This is much faster (many times faster in some cases) than
using separate single-row INSERT statements. If you are adding data
to a non-empty table, you may tune the bulk_insert_buffer_size
variable to make it even faster.
See section 5.2.3 Server System Variables.
INSERT DELAYED statement. See section 13.1.4 INSERT Syntax.
MyISAM tables you can insert rows at the same time that
SELECT statements are running if there are no deleted rows in the
tables.
LOAD DATA INFILE. This
is usually 20 times faster than using a lot of INSERT statements.
See section 13.1.5 LOAD DATA INFILE Syntax.
LOAD DATA INFILE run even
faster when the table has many indexes. Use the following procedure:
CREATE TABLE.
FLUSH TABLES statement or a mysqladmin flush-tables
command.
myisamchk --keys-used=0 -rq /path/to/db/tbl_name. This
removes all use of indexes for the table.
LOAD DATA INFILE. This does not
update any indexes and therefore is very fast.
myisampack
to make it smaller. See section 14.1.3.3 Compressed Table Characteristics.
myisamchk -r -q
/path/to/db/tbl_name. This creates the index tree in memory before
writing it to disk, which is much faster because it avoids lots of disk
seeks. The resulting index tree is also perfectly balanced.
FLUSH TABLES statement or a mysqladmin flush-tables
command.
LOAD DATA INFILE also performs the preceding optimization
if you insert into an empty MyISAM table; the main difference is that you can let
myisamchk allocate much more temporary memory for the index creation
than you might want the server to allocate for index re-creation when it
executes the LOAD DATA INFILE statement.
As of MySQL 4.0, you can also use
ALTER TABLE tbl_name DISABLE KEYS instead of
myisamchk --keys-used=0 -rq /path/to/db/tbl_name and
ALTER TABLE tbl_name ENABLE KEYS instead of
myisamchk -r -q /path/to/db/tbl_name. This way you can also skip the
FLUSH TABLES steps.
INSERT operations that are done
with multiple statements by locking your tables:
LOCK TABLES a WRITE; INSERT INTO a VALUES (1,23),(2,34),(4,33); INSERT INTO a VALUES (8,26),(6,29); UNLOCK TABLES;A performance benefit occurs because the index buffer is flushed to disk only once, after all
INSERT statements have completed. Normally there would
be as many index buffer flushes as there are different INSERT
statements. Explicit locking statements are not needed if you can insert
all rows with a single statement.
For transactional tables, you should use BEGIN/COMMIT instead of
LOCK TABLES to get a speedup.
Locking also lowers the total time of multiple-connection tests, although the
maximum wait time for individual connections might go up because they wait for
locks. For example:
Connection 1 does 1000 inserts Connections 2, 3, and 4 do 1 insert Connection 5 does 1000 insertsIf you don't use locking, connections 2, 3, and 4 finish before 1 and 5. If you use locking, connections 2, 3, and 4 probably do not finish before 1 or 5, but the total time should be about 40% faster.
INSERT, UPDATE, and DELETE operations are very
fast in MySQL, but you can obtain better overall performance by
adding locks around everything that does more than about five inserts or
updates in a row. If you do very many inserts in a row, you could do a
LOCK TABLES followed by an UNLOCK TABLES once in a while
(about each 1,000 rows) to allow other threads access to the table. This
would still result in a nice performance gain.
INSERT is still much slower for loading data than LOAD DATA
INFILE, even when using the strategies just outlined.
MyISAM tables, for both LOAD DATA
INFILE and INSERT, enlarge the key cache by increasing the
key_buffer_size system variable.
See section 7.5.2 Tuning Server Parameters.
UPDATE Statements
Update statements are optimized as a SELECT query with the additional
overhead of a write. The speed of the write depends on the amount of
data being updated and the number of indexes that are updated. Indexes that
are not changed does not get updated.
Also, another way to get fast updates is to delay updates and then do many updates in a row later. Doing many updates in a row is much quicker than doing one at a time if you lock the table.
Note that for a MyISAM table that uses dynamic record format,
updating a record to a longer total length may split the record. If you do
this often, it is very important to use OPTIMIZE TABLE occasionally.
See section 13.5.2.5 OPTIMIZE TABLE Syntax.
DELETE StatementsThe time to delete individual records is exactly proportional to the number of indexes. To delete records more quickly, you can increase the size of the key cache. See section 7.5.2 Tuning Server Parameters.
If you want to delete all rows in the table, use TRUNCATE TABLE
tbl_name rather than DELETE FROM tbl_name.
See section 13.1.9 TRUNCATE Syntax.
This section lists a number of miscellaneous tips for improving query processing speed:
thread_cache_size variable. See section 7.5.2 Tuning Server Parameters.
EXPLAIN
statement. See section 7.2.1 EXPLAIN Syntax (Get Information About a SELECT).
SELECT queries on MyISAM tables that are
updated frequently, to avoid problems with table locking that occur
due to contention between readers and writers.
MyISAM tables that have no deleted rows, you can insert rows at
the end at the same time that another query is reading from the table. If this
is important for you, you should consider using the table in ways that avoid
deleting rows. Another possibility is to run OPTIMIZE TABLE after you
have deleted a lot of rows.
ALTER TABLE ... ORDER BY expr1, expr2, ... if you mostly
retrieve rows in expr1, expr2, ... order. By using this option after
extensive changes to the table, you may be able to get higher performance.
SELECT * FROM tbl_name
WHERE hash_col=MD5(CONCAT(col1,col2))
AND col1='constant' AND col2='constant';
MyISAM tables that change a lot, you should try to avoid all
variable-length columns (VARCHAR, BLOB, and TEXT). The
table uses dynamic record format if it includes even a single
variable-length column.
See section 14 MySQL Storage Engines and Table Types.
MyISAM table with dynamic record format (see above) that you can
change to a fixed record size,
or if you very often need to scan the table but do not need
most of the columns. See section 14 MySQL Storage Engines and Table Types.
UPDATE tbl_name SET count_col=count_col+1 WHERE key_col=constant;This is really important when you use MySQL storage engines such as
MyISAM and ISAM that have only table-level locking (multiple
readers / single writers). This also gives better performance with most
databases, because the row locking manager in this case has less to do.
BLOB
column. In this case, you must add some extra code in your application to
pack and unpack information in the BLOB values, but this may save a
lot of accesses at some stage. This is practical when you have data that
doesn't conform to a rows-and-columns table structure.
INSERT DELAYED when you do not need to know when your
data is written. This speeds things up because many records can be written
with a single disk write.
INSERT LOW_PRIORITY when you want to give SELECT
statements higher priority than your inserts.
SELECT HIGH_PRIORITY to get retrievals that jump the
queue. That is, the SELECT is done even if there is another client
waiting to do a write.
INSERT statements to store many rows with one
SQL statement (many SQL servers support this).
LOAD DATA INFILE to load large amounts of data. This is
faster than using INSERT statements.
AUTO_INCREMENT columns to generate unique values.
OPTIMIZE TABLE once in a while to avoid fragmentation
with MyISAM tables
when
using a dynamic table format.
See section 14.1.3 MyISAM Table Storage Formats.
HEAP tables when possible to get more speed.
See section 14 MySQL Storage Engines and Table Types.
customer,
use a column name of name instead of customer_name. To make
your names portable to other SQL servers, you should keep them shorter than
18 characters.
MyISAM storage engine directly, you could
get a speed increase of two to five times compared to using the SQL interface.
To be able to do this, the data must be on the same server as
the application, and usually it should only be accessed by one process
(because external file locking is really slow). One could eliminate these
problems by introducing low-level MyISAM commands in the
MySQL server (this could be one easy way to get more
performance if needed). By carefully designing the database interface,
it should be quite easy to support this types of optimization.
MyISAM table with the DELAY_KEY_WRITE=1 table
option makes index updates faster because they are not flushed to disk
until the table is closed. The downside is that if something kills the
server while such a table is open, you should ensure that they are okay by
running the server with the --myisam-recover option, or by
running myisamchk before restarting the server. (However, even in
this case, you should not lose anything by using DELAY_KEY_WRITE,
because the key information can always be generated from the data rows.)
Currently, MySQL supports table-level locking for ISAM,
MyISAM, and MEMORY (HEAP) tables, page-level locking
for BDB tables, and row-level locking for InnoDB tables.
In many cases, you can make an educated guess about which locking type is best for an application, but generally it's very hard to say that a given lock type is better than another. Everything depends on the application and different parts of an application may require different lock types.
To decide whether you want to use a storage engine with row-level locking,
you should look at what your application does and what mix of select
and update statements it uses. For example, most Web applications do lots
of selects, very few deletes, updates based mainly on key values, and
inserts into some specific tables. The base MySQL MyISAM setup is
very well tuned for this.
Table locking in MySQL is deadlock-free for storage engines that use table-level locking. Deadlock avoidance is managed by always requesting all needed locks at once at the beginning of a query and always locking the tables in the same order.
The table-locking method MySQL uses for WRITE locks works as follows:
The table-locking method MySQL uses for READ locks works as follows:
When a lock is released, the lock is made available to the threads in the write lock queue, then to the threads in the read lock queue.
This means that if you have many updates for a table, SELECT
statements wait until there are no more updates.
Starting in MySQL 3.23.33, you can analyze the table lock contention
on your system by checking the Table_locks_waited and
Table_locks_immediate status variables:
mysql> SHOW STATUS LIKE 'Table%'; +-----------------------+---------+ | Variable_name | Value | +-----------------------+---------+ | Table_locks_immediate | 1151552 | | Table_locks_waited | 15324 | +-----------------------+---------+
As of MySQL 3.23.7 (3.23.25 for Windows), you can freely mix concurrent
INSERT and SELECT statements for a MyISAM table without
locks if the INSERT statements are non-conflicting. That is, you can
insert rows into a MyISAM table at the same time other clients are
reading from it. No conflict occurs if the data file contains no free
blocks in the middle, because in that case, records always are inserted at
the end of the data file. (Holes can result from rows having been deleted
from or updated in the middle of the table.) If there are holes, concurrent
inserts are re-enabled automatically when all holes have been filled with
new data.
If you want to do many INSERT and SELECT operations on a table
when concurrent inserts are not possible, you can insert rows in a temporary
table and update the real table with the records from the temporary table
once in a while. This can be done with the following code:
mysql> LOCK TABLES real_table WRITE, insert_table WRITE; mysql> INSERT INTO real_table SELECT * FROM insert_table; mysql> TRUNCATE TABLE insert_table; mysql> UNLOCK TABLES;
InnoDB uses row locks and BDB uses page locks. For the
InnoDB and BDB storage engines, deadlock is possible. This is
because InnoDB automatically acquires row locks and BDB
acquires page locks during the processing of SQL statements, not at the
start of the transaction.
Advantages of row-level locking:
Disadvantages of row-level locking:
GROUP
BY operations on a large part of the data or if you often must scan the
entire table.
Table locks are superior to page-level or row-level locks in the following cases:
UPDATE tbl_name SET column=value WHERE unique_key_col=key_value; DELETE FROM tbl_name WHERE unique_key_col=key_value;
SELECT combined with concurrent INSERT statements, and very
few UPDATE and DELETE statements.
GROUP BY operations on the entire table without any writers.
Options other than row-level or page-level locking:
Versioning (such as we use in MySQL for concurrent inserts) where you can have one writer at the same time as many readers. This means that the database/table supports different views for the data depending on when you started to access it. Other names for this are time travel, copy on write, or copy on demand.
Copy on demand is in many cases much better than page-level or row-level locking. However, the worst case does use much more memory than when using normal locks.
Instead of using row-level locks, you can use application-level locks,
such as GET_LOCK() and RELEASE_LOCK() in MySQL. These are
advisory locks, so they work only in well-behaved applications.
To achieve a very high lock speed, MySQL uses table locking (instead of
page, row, or column locking) for all storage engines except InnoDB
and BDB.
For InnoDB and BDB tables, MySQL only uses table locking if
you explicitly lock the table with LOCK TABLES. For these table
types, we recommend you to not use LOCK TABLES at all, because
InnoDB uses automatic row-level locking and BDB uses
page-level locking to ensure transaction isolation.
For large tables, table locking is much better than row locking for most applications, but there are some pitfalls.
Table locking enables many threads to read from a table at the same time, but if a thread wants to write to a table, it must first get exclusive access. During the update, all other threads that want to access this particular table must wait until the update is done.
Table updates normally are considered to be more important than table
retrievals, so they are given higher priority. This should ensure that
updates to a table are not ``starved'' even if there is heavy SELECT
activity for the table.
Table locking causes problems in cases such as when a thread is waiting because the disk is full and free space needs to become available before the thread can proceed. In this case, all threads that want to access the problem table are also put in a waiting state until more disk space is made available.
Table locking is also disadvantageous under the following scenario:
SELECT that takes a long time to run.
UPDATE on the same table. This client
waits until the SELECT is finished.
SELECT statement on the same table.
Because
UPDATE has higher priority than SELECT, this SELECT
waits for the UPDATE to finish. It also waits for the first
SELECT to finish!
The following list describes some ways to avoid or reduce contention caused by table locking:
SELECT statements to run faster. You might have to
create some summary tables to do this.
mysqld with --low-priority-updates. This gives
all statements that update (modify) a table lower priority than SELECT
statements. In this case, the second SELECT statement in the preceding
scenario would execute before the INSERT statement, and would not need
to wait for the first SELECT to finish.
SET LOW_PRIORITY_UPDATES=1 statement.
See section 13.5.3 SET Syntax.
INSERT, UPDATE, or DELETE
statement lower priority with the LOW_PRIORITY attribute.
SELECT statement higher priority with the
HIGH_PRIORITY attribute. See section 13.1.7 SELECT Syntax.
mysqld with a low value for
the max_write_lock_count system variable to force MySQL to
temporarily elevate the priority of all SELECT statements that are
waiting for a table after a specific number of inserts to the table occur.
This allows READ locks after a certain number of WRITE locks.
INSERT combined with SELECT, switch
to using MyISAM tables, which support concurrent SELECT and
INSERT statements.
INSERT DELAYED
may be of great help.
See section 13.1.4.2 INSERT DELAYED Syntax.
SELECT and DELETE statements,
the LIMIT option to DELETE may help.
See section 13.1.1 DELETE Syntax.
SQL_BUFFER_RESULT with SELECT statements can help to
make the duration of table locks shorter.
See section 13.1.7 SELECT Syntax.
Here are some tips about table locking in MySQL:
LOCK TABLES to speed up things (many updates within
a single lock is much faster than updates without locks). Splitting
table contents into separate tables may also help.
InnoDB or
BDB tables.
See section 15 The InnoDB Storage Engine.
See section 14.4 The BDB (BerkeleyDB) Storage Engine.
MySQL keeps row data and index data in separate files. Many (almost all) other databases mix row and index data in the same file. We believe that the MySQL choice is better for a very wide range of modern systems.
Another way to store the row data is to keep the information for each column in a separate area (examples are SDBM and Focus). This causes a performance hit for every query that accesses more than one column. Because this degenerates so quickly when more than one column is accessed, we believe that this model is not good for general-purpose databases.
The more common case is that the index and data are stored together (as in Oracle/Sybase, et al). In this case, you find the row information at the leaf page of the index. The good thing with this layout is that it, in many cases, depending on how well the index is cached, saves a disk read. The bad things with this layout are:
One of the most basic optimizations is to design your tables to take as little space on the disk as possible. This can give huge improvements because disk reads are faster, and smaller tables normally require less main memory while their contents are being actively processed during query execution. Indexing also is a lesser resource burden if done on smaller columns.
MySQL supports a lot of different table types and row formats. For each table, you can decide which storage/index method to use. Choosing the right table format for your application may give you a big performance gain. See section 14 MySQL Storage Engines and Table Types.
You can get better performance on a table and minimize storage space using the techniques listed here:
MEDIUMINT is often better than INT.
NOT NULL if possible. It makes everything
faster and you save one bit per column. If you really need
NULL in your application, you should definitely use it. Just avoid
having it on all columns by default.
MyISAM tables, if you don't have any variable-length columns
(VARCHAR, TEXT, or BLOB columns), a fixed-size record
format is used. This is faster but unfortunately may waste some space.
See section 14.1.3 MyISAM Table Storage Formats.
You can hint that you want to have fixed length rows even if you have
VARCHAR columns with the CREATE option
ROW_FORMAT=fixed.
InnoDB tables use a more
compact storage format. In earlier versions of MySQL, InnoDB records
contain some redundant information, such as the number of columns and
the length of each column, even for fixed-size columns. By default,
tables are created in the compact format
(ROW_FORMAT=COMPACT). If you wish to downgrade to older
versions of MySQL/InnoDB, you can request the old format with
ROW_FORMAT=REDUNDANT.
The compact InnoDB format also changes the way how CHAR columns
containing UTF-8 data are stored. In the ROW_FORMAT=REDUNDANT
format, a UTF-8 CHAR(n) occupies 3*n bytes, given
that the maximum length of a UTF-8 encoded character is 3 bytes.
Since many languages can be written mostly with single-byte UTF-8
characters, a fixed storage length often wastes space. The
ROW_FORMAT=COMPACT format allocates a variable amount of
n..3*n bytes for these columns by stripping trailing
spaces if necessary. The minimum storage length is kept as n
bytes in order to facilitate in-place updates in typical cases.
All MySQL column types can be indexed. Use of indexes on the
relevant columns is the best way to improve the performance of SELECT
operations.
The maximum number of indexes per table and the maximum index length is defined per storage engine. See section 14 MySQL Storage Engines and Table Types. All storage engines support at least 16 indexes per table and a total index length of at least 256 bytes. Most storage engines have higher limits.
With col_name(length) syntax in an index specification,
you can create an index that uses only the first length characters of
a CHAR or VARCHAR column. Indexing only a prefix of column
values like this can make the index file much smaller.
The MyISAM and (as of MySQL 4.0.14) InnoDB storage engines also
support indexing on BLOB and TEXT columns. When indexing
a BLOB or TEXT column, you must specify a prefix
length for the index. For example:
CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));
Prefixes can be up to 255 bytes long (or 1000 bytes for MyISAM
and InnoDB tables as of MySQL 4.1.2). Note that prefix limits
are measured in bytes, whereas the prefix length in CREATE TABLE
statements is interpreted as number of characters. Take this into account
when specifying a prefix length for a column that uses a multi-byte
character set.
As of MySQL 3.23.23, you can also create FULLTEXT indexes.
They are used for full-text searches. Only the MyISAM table type
supports FULLTEXT indexes and only for CHAR, VARCHAR,
and TEXT columns. Indexing always happens over the entire column and
partial (prefix) indexing is not supported. See section 12.6 Full-Text Search Functions for
details.
As of MySQL 4.1.0, you can create indexes on spatial column types.
Currently, spatial types are supported only by the MyISAM storage
engine. Spatial indexes use R-trees.
The MEMORY (HEAP) storage engine uses hash indexes by default.
It also supports B-tree indexes as of MySQL 4.1.0.
MySQL can create indexes on multiple columns. An index may consist of up to 15 columns. For certain column types, you can index a prefix of the column (see section 7.4.3 Column Indexes).
A multiple-column index can be considered a sorted array containing values that are created by concatenating the values of the indexed columns.
MySQL uses multiple-column indexes in such a way that queries are
fast when you specify a known quantity for the first column of the index in a
WHERE clause, even if you don't specify values for the other columns.
Suppose that a table has the following specification:
CREATE TABLE test (
id INT NOT NULL,
last_name CHAR(30) NOT NULL,
first_name CHAR(30) NOT NULL,
PRIMARY KEY (id),
INDEX name (last_name,first_name));
The name index is an index over last_name and
first_name. The index can be used for queries that specify
values in a known range for last_name, or for both last_name
and first_name.
Therefore, the name index is used in the following queries:
SELECT * FROM test WHERE last_name='Widenius';
SELECT * FROM test
WHERE last_name='Widenius' AND first_name='Michael';
SELECT * FROM test
WHERE last_name='Widenius'
AND (first_name='Michael' OR first_name='Monty');
SELECT * FROM test
WHERE last_name='Widenius'
AND first_name >='M' AND first_name < 'N';
However, the name index is not used in the following
queries:
SELECT * FROM test WHERE first_name='Michael';
SELECT * FROM test
WHERE last_name='Widenius' OR first_name='Michael';
The manner in which MySQL uses indexes to improve query performance is discussed further in the next section.
Indexes are used to find rows with specific column values fast. Without an index, MySQL has to start with the first record and then read through the whole table to find the relevant rows. The larger the table, the more this costs. If the table has an index for the columns in question, MySQL can quickly determine the position to seek to in the middle of the data file without having to look at all the data. If a table has 1,000 rows, this is at least 100 times faster than reading sequentially. Note that if you need to access almost all 1,000 rows, it is faster to read sequentially, because that minimizes disk seeks.
Most MySQL indexes (PRIMARY KEY, UNIQUE, INDEX, and
FULLTEXT) are stored in B-trees. Exceptions are that indexes on
spatial column types use R-trees, and MEMORY (HEAP) tables
support hash indexes.
Strings are automatically prefix- and end-space compressed.
See section 13.2.5 CREATE INDEX Syntax.
In general, indexes are used as described in the following discussion.
Characteristics specific to hash indexes (as used in MEMORY tables)
are described at the end of this section.
Indexes are used for these operations:
WHERE clause.
MIN() or MAX() value for a specific indexed column
key_col. This is optimized by a preprocessor that checks whether you are
using WHERE key_part_# = constant on all key parts that occur before
key_col in the index. In this case, MySQL does a single key
lookup for each MIN() or MAX() expression and replace it
with a constant. If all expressions are replaced with constants, the
query returns at once. For example:
SELECT MIN(key_part2),MAX(key_part2) FROM tbl_name WHERE key_part1=10;
ORDER BY key_part1,
key_part2). If all key parts are followed by DESC, the key
is read in reverse order.
See section 7.2.10 How MySQL Optimizes ORDER BY.
SELECT key_part3 FROM tbl_name WHERE key_part1=1
Suppose that you issue the following SELECT statement:
mysql> SELECT * FROM tbl_name WHERE col1=val1 AND col2=val2;
If a multiple-column index exists on col1 and col2, the
appropriate rows can be fetched directly. If separate single-column
indexes exist on col1 and col2, the optimizer tries to
find the most restrictive index by deciding which index finds fewer
rows and using that index to fetch the rows.
If the table has a multiple-column index, any leftmost prefix of the
index can be used by the optimizer to find rows. For example, if you
have a three-column index on (col1, col2, col3), you have indexed
search capabilities on (col1), (col1, col2), and
(col1, col2, col3).
MySQL can't use a partial index if the columns don't form a
leftmost prefix of the index. Suppose that you have the SELECT
statements shown here:
SELECT * FROM tbl_name WHERE col1=val1; SELECT * FROM tbl_name WHERE col2=val2; SELECT * FROM tbl_name WHERE col2=val2 AND col3=val3;
If an index exists on (col1, col2, col3), only the first of the preceding
queries uses the index. The second and third queries do involve
indexed columns, but (col2) and (col2, col3) are not
leftmost prefixes of (col1, col2, col3).
A B-tree index can be used for column comparisons in expressions that use
the =, >, >=, <, <=, or BETWEEN
operators. The index also can be used for LIKE comparisons if the
argument to LIKE is a constant string that doesn't start with a
wildcard character. For example, the following SELECT statements
use indexes:
SELECT * FROM tbl_name WHERE key_col LIKE 'Patrick%'; SELECT * FROM tbl_name WHERE key_col LIKE 'Pat%_ck%';
In the first statement, only rows with 'Patrick' <= key_col <
'Patricl' are considered. In the second statement, only rows with
'Pat' <= key_col < 'Pau' are considered.
The following SELECT statements do not use indexes:
SELECT * FROM tbl_name WHERE key_col LIKE '%Patrick%'; SELECT * FROM tbl_name WHERE key_col LIKE other_col;
In the first statement, the LIKE value begins with a wildcard
character. In the second statement, the LIKE value is not a
constant.
MySQL 4.0 and up performs an additional LIKE optimization. If you use
... LIKE '%string%' and string is longer than three characters,
MySQL uses the Turbo Boyer-Moore algorithm to initialize the
pattern for the string and then use this pattern to perform the search
quicker.
Searching using col_name IS NULL uses indexes if col_name
is indexed.
Any index that doesn't span all AND levels in the WHERE clause
is not used to optimize the query. In other words, to be able to use an
index, a prefix of the index must be used in every AND group.
The following WHERE clauses use indexes:
... WHERE index_part1=1 AND index_part2=2 AND other_column=3
/* index = 1 OR index = 2 */
... WHERE index=1 OR A=10 AND index=2
/* optimized like "index_part1='hello'" */
... WHERE index_part1='hello' AND index_part3=5
/* Can use index on index1 but not on index2 or index3 */
... WHERE index1=1 AND index2=2 OR index1=3 AND index3=3;
These WHERE clauses do not use indexes:
/* index_part1 is not used */
... WHERE index_part2=1 AND index_part3=2
/* Index is not used in both AND parts */
... WHERE index=1 OR A=10
/* No index spans all rows */
... WHERE index_part1=1 OR index_part2=10
Sometimes MySQL does not use an index, even if one is available. One way
this occurs is when the optimizer estimates that using the index would
require MySQL to access a large percentage of the rows in the table.
(In this case, a table scan is probably much faster, because it
requires fewer seeks.) However, if such a query uses LIMIT to
only retrieve part of the rows, MySQL uses an index anyway, because
it can much more quickly find the few rows to return in the result.
Hash indexes have somewhat different characteristics than those just discussed:
= or
<=> operators (but are very fast). They are not used for
comparison operators such as < that find a range of values.
ORDER BY
operations. (This type of index cannot be used to search for the next entry
in order.)
MyISAM
table to a hash-indexed MEMORY table.
MyISAM Key Cache
To minimize disk I/O, the MyISAM storage engine employs a strategy that
is used by many database management systems. It exploits a cache
mechanism to keep the most frequently accessed table blocks in memory:
This section first describes the basic operation of the MyISAM key
cache. Then it discusses changes made in MySQL 4.1 that improve key cache
performance and that enable you to better control cache operation:
The key cache mechanism also is used for ISAM tables. However, the
significance of this fact is on the wane. ISAM table use has been
decreasing since MySQL 3.23 when MyISAM was introduced. MySQL 4.1
carries this trend further; the ISAM storage engine is disabled by
default.
You can control the size of the key cache by means of the
key_buffer_size system variable. If this variable is set equal
to zero, no key cache is used. The key cache also is not used if the
key_buffer_size value is too small to allocate the minimal number
of block buffers (8).
When the key cache is not operational, index files are accessed using only the native filesystem buffering provided by the operating system. (In other words, table index blocks are accessed using the same strategy as that employed for table data blocks.)
An index block is a contiguous unit of access to the MyISAM index files.
Usually the size of an index block is equal to the size of nodes of the
index B-tree. (Indexes are represented on disk using a B-tree data structure.
Nodes at the bottom of the tree are leaf nodes. Nodes above the leaf nodes
are non-leaf nodes.)
All block buffers in a key cache structure are the same size. This size can be equal to, greater than, or less than the size of a table index block. Usually one these two values is a multiple of the other.
When data from any table index block must be accessed, the server first checks whether it is available in some block buffer of the key cache. If it is, the server accesses data in the key cache rather than on disk. That is, it reads from the cache or writes into it rather than reading from or writing to disk. Otherwise, the server chooses a cache block buffer containing a different table index block (or blocks) and replaces the data there by a copy of required table index block. As soon as the new index block is in the cache, the index data can be accessed.
If it happens that a block selected for replacement has been modified, the block is considered ``dirty.'' In this case, before being replaced, its contents are flushed to the table index from which it came.
Usually the server follows an LRU (Least Recently Used) strategy: When choosing a block for replacement, it selects the least recently used index block. To be able to make such a choice easy, the key cache module maintains a special queue (LRU chain) of all used blocks. When a block is accessed, it is placed at the end of the queue. When blocks need to be replaced, blocks at the beginning of the queue are the least recently used and become the first candidates for eviction.
Prior to MySQL 4.1, access to the key cache is serialized: No two threads can access key cache buffers simultaneously. The server processes a request for an index block only after it has finished processing the previous request. As a result, a request for an index block not present in any key cache buffer blocks access by other threads while a buffer is being updated to contain the requested index block.
Starting from version 4.1.0, the server supports shared access to the key cache:
Shared access to the key cache allows the server to improve throughput significantly.
Shared access to the key cache improves performance but does not eliminate contention among threads entirely. They still compete for control structures that manage access to the key cache buffers. To reduce key cache access contention further, MySQL 4.1.1 offers the feature of multiple key caches. This allows you to assign different table indexes to different key caches.
When there can be multiple key caches, the server must know which cache to
use when processing queries for a given MyISAM table. By default, all
MyISAM table indexes are cached in the default key cache. To assign
table indexes to a specific key cache, use the CACHE INDEX statement.
For example, the following statement assigns indexes from the tables
t1, t2, and t3 to the key cache named hot_cache:
mysql> CACHE INDEX t1, t2, t3 IN hot_cache; +---------+--------------------+----------+----------+ | Table | Op | Msg_type | Msg_text | +---------+--------------------+----------+----------+ | test.t1 | assign_to_keycache | status | OK | | test.t2 | assign_to_keycache | status | OK | | test.t3 | assign_to_keycache | status | OK | +---------+--------------------+----------+----------+
Note: If the server has been built with the ISAM storage
engine enabled, ISAM tables use the key cache mechanism. However,
ISAM indexes use only the default key cache and cannot be reassigned to
a different cache.
The key cache referred to in a CACHE INDEX statement can be created
by setting its size with a SET GLOBAL parameter setting statement or by
using server startup options. For example:
mysql> SET GLOBAL keycache1.key_buffer_size=128*1024;
To destroy a key cache, set its size to zero:
mysql> SET GLOBAL keycache1.key_buffer_size=0;
Key cache variables are structured system variables that have a name and
components. For keycache1.key_buffer_size, keycache1 is the
cache variable name and key_buffer_size is the cache component.
See section 9.4.1 Structured System Variables for a description of the syntax used
for referring to structured key cache system variables.
By default, table indexes are assigned to the main (default) key cache created at the server startup. When a key cache is destroyed, all indexes assigned to it are reassigned to the default key cache.
For a busy server, we recommend a strategy that uses three key caches:
One reason the use of three key caches is beneficial is that access to one key cache structure does not block access to the others. Queries that access tables assigned to one cache do not compete with queries that access tables assigned to another cache. Performance gains occur for other reasons as well:
CACHE INDEX sets up an association between a table and a key cache,
but the association is lost each time the server restarts. If you want the
association to take effect each time the server starts, one way to accomplish
this is to use an option file: Include variable settings that configure
your key caches, and an init-file option that names a file containing
CACHE INDEX statements to be executed. For example:
key_buffer_size = 4G hot_cache.key_buffer_size = 2G cold_cache.key_buffer_size = 2G init_file=/path/to/data-directory/mysqld_init.sql
The statements in `mysqld_init.sql' are executed each time the
server starts. It should contain one SQL statement per line. The following
example assigns several tables each to hot_cache and cold_cache:
CACHE INDEX a.t1, a.t2, b.t3 IN hot_cache CACHE INDEX a.t4, b.t5, b.t6 IN cold_cache
By default, the key cache management system of MySQL 4.1 uses the LRU strategy for choosing key cache blocks to be evicted, but it also supports a more sophisticated method called the "midpoint insertion strategy."
When using the midpoint insertion strategy, the LRU chain is divided into
two parts: a hot sub-chain and a warm sub-chain. The division point between
two parts is not fixed, but the key cache management system takes care that
the warm part is not ``too short,'' always containing at least
key_cache_division_limit percent of the key cache blocks.
key_cache_division_limit is a component of structured key cache
variables, so its value is a parameter that can be set per cache.
When an index block is read from a table into the key cache, it is placed at the end of the warm sub-chain. After a certain number of hits (accesses of the block), it is promoted to the hot sub-chain. At present, the number of hits required to promote a block (3) is the same for all index blocks. In the future, we will allow the hit count to depend on the B-tree level of the node corresponding to an index block: Fewer hits are required for promotion of an index block if it contains a non-leaf node from the upper levels of the index B-tree than if it contains a leaf node.
A block promoted into the hot sub-chain is placed at the end of the chain.
The block then circulates within this sub-chain. If the block stays at the
beginning of the sub-chain for a long enough time, it is demoted to the warm
chain. This time is determined by the value of the
key_cache_age_threshold component of the key cache.
The threshold value prescribes that, for a key cache containing N
blocks, the block at the beginning of the hot sub-chain not accessed within
the last N*key_cache_age_threshold/100 hits is to be moved to the
beginning of the warm sub-chain. It then becomes the first candidate for
eviction, because blocks for replacement always are taken from the beginning
of the warm sub-chain.
The midpoint insertion strategy allows you to keep more-valued blocks
always in the cache. If you prefer to use the plain LRU strategy, leave the
key_cache_division_limit value set to its default of 100.
The midpoint insertion strategy helps to improve performance when execution
of a query that requires an index scan effectively pushes out of the cache
all the index blocks corresponding to valuable high-level B-tree nodes. To
avoid this, you must use a midpoint insertion strategy with the
key_cache_division_limit set to much less than 100. Then valuable
frequently hit nodes are preserved in the hot sub-chain during an index
scan operation as well.
If there are enough blocks in a key cache to hold blocks of an entire index, or at least the blocks corresponding to its non-leaf nodes, then it makes sense to preload the key cache with index blocks before starting to use it. Preloading allows you to put the table index blocks into a key cache buffer in the most efficient way: by reading the index blocks from disk sequentially.
Without preloading, the blocks are still placed into the key cache as needed by queries. Although the blocks will stay in the cache, because there are enough buffers for all of them, they are fetched from disk in a random order, not sequentially.
To preload an index into a cache, use the LOAD INDEX INTO CACHE
statement. For example,
the following statement preloads nodes (index blocks) of indexes of the
tables t1 and t2:
mysql> LOAD INDEX INTO CACHE t1, t2 IGNORE LEAVES; +---------+--------------+----------+----------+ | Table | Op | Msg_type | Msg_text | +---------+--------------+----------+----------+ | test.t1 | preload_keys | status | OK | | test.t2 | preload_keys | status | OK | +---------+--------------+----------+----------+
The IGNORE LEAVES modifier causes only blocks for the non-leaf
nodes of the index to be preloaded. Thus,
the statement shown preloads all index blocks from t1, but only
blocks for the non-leaf nodes from t2.
If an index has been assigned to a key cache using a
CACHE INDEX statement, preloading places index blocks into that cache.
Otherwise, the index is loaded into the default key cache.
MySQL 4.1 introduces a new key_cache_block_size variable on
a per-key cache basis. This variable specifies the size of the block
buffers for a key cache. It is intended to allow tuning of the performance
of I/O operations for index files.
The best performance for I/O operations is achieved when the size of read buffers is equal to the size of the native operating system I/O buffers. But setting the size of key nodes equal to the size of the I/O buffer does not always ensure the best overall performance. When reading the big leaf nodes, the server pulls in a lot of unnecessary data, effectively preventing reading other leaf nodes.
Currently, you cannot control the size of the index blocks in a table. This
size is set by the server when the `.MYI' index file is created,
depending on the size of the keys in the indexes present in the table
definition. In most cases, it is set equal to the I/O buffer size. In the
future, this will be changed and then the key_cache_block_size variable
is fully employed.
A key cache can be restructured at any time by updating its parameter values. For example:
mysql> SET GLOBAL cold_cache.key_buffer_size=4*1024*1024;
If you assign to either the key_buffer_size or
key_cache_block_size key cache component a value that differs from
the component's current value, the server destroys the cache's old
structure and creates a new one based on the new values. If the cache
contains any dirty blocks, the server saves them to disk before destroying
and re-creating the cache. Restructuring does not occur if you set other key
cache parameters.
When restructuring a key cache, the server first flushes the contents of any dirty buffers to disk. After that, the cache contents become unavailable. However, restructuring does not block queries that need to use indexes assigned to the cache. Instead, the server directly accesses the table indexes using native filesystem caching. Filesystem caching is not as efficient as using a key cache, so although queries execute, a slowdown can be anticipated. Once the cache has been restructured, it becomes available again for caching indexes assigned to it, and the use of filesystem caching for the indexes ceases.
When you execute a mysqladmin status command, you'll see something
like this:
Uptime: 426 Running threads: 1 Questions: 11082 Reloads: 1 Open tables: 12
The Open tables value of 12 can be somewhat puzzling if you have
only six tables.
MySQL is multi-threaded, so there may be many clients issuing queries for a
given table simultaneously. To minimize the problem with multiple client threads
having different states on the same table, the table is opened independently
by each concurrent thread. This takes some memory but normally increases
performance. With MyISAM tables, one extra file descriptor is
required for the data file for each client that has the table open. (By
contrast, the index file descriptor is shared between all threads.) The
ISAM storage engine shares this behavior.
You can read more about this topic in the next section. See section 7.4.8 How MySQL Opens and Closes Tables.
The table_cache, max_connections, and max_tmp_tables
system variables affect the maximum number of files the server keeps open.
If you increase one or more of these values, you may run up against a limit
imposed by your operating system on the per-process number of open file
descriptors. Many operating systems allow you to increase the open-files
limit, although the method varies widely from system to system. Consult your
operating system documentation to determine whether it is possible to
increase the limit and how to do so.
table_cache is related to max_connections. For example,
for 200 concurrent running connections, you should have a table cache size of
at least 200 * N, where N is the maximum number of tables
in a join. You also need to reserve some extra file descriptors for
temporary tables and files.
Make sure that your operating system can handle the number of open file
descriptors implied by the table_cache setting. If
table_cache is set too high, MySQL may run out of file
descriptors and refuse connections, fail to perform queries, and be very
unreliable. You also have to take into account that the MyISAM storage
engine needs two file descriptors for each unique open table. You can
increase the number of file descriptors available for MySQL with
the --open-files-limit startup option to mysqld_safe.
See section A.2.17 File Not Found.
The cache of open tables is kept at a level of table_cache
entries. The default value is 64; this can be changed with the
--table_cache option to mysqld. Note that MySQL may
temporarily open even more tables to be able to execute queries.
An unused table is closed and removed from the table cache under the following circumstances:
table_cache entries and
a thread is no longer using a table.
FLUSH TABLES statement or executes a mysqladmin flush-tables
or mysqladmin refresh command.
When the table cache fills up, the server uses the following procedure to locate a cache entry to use:
When the cache is in a temporarily extended state and a table goes from a used to unused state, the table is closed and released from the cache.
A table is opened for each concurrent access. This means the table needs to be opened twice if two threads access the same table or if a thread accesses the table twice in the same query (for example, by joining the table to itself). Each concurrent open requires an entry in the table cache. The first open of any table takes two file descriptors: one for the data file and one for the index file. Each additional use of the table takes only one file descriptor, for the data file. The index file descriptor is shared among all threads.
If you are opening a table with the HANDLER tbl_name OPEN
statement, a dedicated table object is allocated for the thread.
This table object is not shared by other threads and is not closed
until the thread calls HANDLER tbl_name CLOSE or the thread
terminates. When this happens, the table is put back in the table cache
(if the cache isn't full).
See section 13.1.3 HANDLER Syntax.
You can determine whether your table cache is too small by checking the
mysqld status variable Opened_tables:
mysql> SHOW STATUS LIKE 'Opened_tables'; +---------------+-------+ | Variable_name | Value | +---------------+-------+ | Opened_tables | 2741 | +---------------+-------+
If the value is quite big, even when you haven't issued a lot of FLUSH
TABLES statements, you should increase your table cache size.
See section 5.2.3 Server System Variables and section 5.2.4 Server Status Variables.
If you have many MyISAM or ISAM tables in a database
directory, open, close, and create operations are slow. If you execute
SELECT statements on many different tables, there is a little
overhead when the table cache is full, because for every table that has to
be opened, another must be closed. You can reduce this overhead by making
the table cache larger.
We start with system-level factors, because some of these decisions must be made very early to achieve large performance gains. In other cases, a quick look at this section may suffice. However, it is always nice to have a sense of how much can be gained by changing things at this level.
The default operating system to use is very important! To get the best use of multiple-CPU machines, you should use Solaris (because its threads implementation works really well) or Linux (because the 2.4 kernel has really good SMP support). Note that older Linux kernels have a 2GB filesize limit by default. If you have such a kernel and a desperate need for files larger than 2GB, you should get the Large File Support (LFS) patch for the ext2 filesystem. Other filesystems such as ReiserFS and XFS do not have this 2GB limitation.
Before using MySQL in production, we advise you to test it on your intended platform.
--skip-external-locking MySQL option to avoid external
locking. This option is on by default as of MySQL 4.0.
Before that, it is on by default when compiling with
MIT-pthreads, because flock() isn't fully supported by
MIT-pthreads on all platforms. It's also on by default for Linux
because Linux file locking is not yet safe.
Note that the --skip-external-locking option does not affect MySQL's
functionality as long as you run only one server. Just remember to take
down the server (or lock and flush the relevant tables) before you run
myisamchk. On some systems this option is mandatory, because the
external locking does not work in any case.
The only case when you can't use --skip-external-locking is if you run
multiple MySQL servers (not clients) on the same data,
or if you run myisamchk to check (not repair) a table without telling
the server to flush and lock the tables first.
You can still use LOCK TABLES and UNLOCK TABLES even if you
are using --skip-external-locking.
You can determine the default buffer sizes used by the mysqld server
with this command (prior to MySQL 4.1, omit --verbose):
shell> mysqld --verbose --help
This command produces a list of all mysqld options and configurable
system variables. The output includes the default variable values and
looks something like this:
back_log current value: 5 bdb_cache_size current value: 1048540 binlog_cache_size current value: 32768 connect_timeout current value: 5 delayed_insert_limit current value: 100 delayed_insert_timeout current value: 300 delayed_queue_size current value: 1000 flush_time current value: 0 interactive_timeout current value: 28800 join_buffer_size current value: 131072 key_buffer_size current value: 1048540 long_query_time current value: 10 lower_case_table_names current value: 0 max_allowed_packet current value: 1048576 max_binlog_cache_size current value: 4294967295 max_connect_errors current value: 10 max_connections current value: 100 max_delayed_threads current value: 20 max_heap_table_size current value: 16777216 max_join_size current value: 4294967295 max_sort_length current value: 1024 max_tmp_tables current value: 32 max_write_lock_count current value: 4294967295 myisam_sort_buffer_size current value: 8388608 net_buffer_length current value: 16384 net_read_timeout current value: 30 net_retry_count current value: 10 net_write_timeout current value: 60 read_buffer_size current value: 131072 read_rnd_buffer_size current value: 262144 slow_launch_time current value: 2 sort_buffer current value: 2097116 table_cache current value: 64 thread_concurrency current value: 10 thread_stack current value: 131072 tmp_table_size current value: 1048576 wait_timeout current value: 28800
If there is a mysqld server currently running, you can see what
values it actually is using for the system variables by connecting to it and
issuing this statement:
mysql> SHOW VARIABLES;
You can also see some statistical and status indicators for a running server by issuing this statement:
mysql> SHOW STATUS;
System variable and status information also can be obtained using
mysqladmin:
shell> mysqladmin variables shell> mysqladmin extended-status
You can find a full description for all system and status variables in section 5.2.3 Server System Variables and section 5.2.4 Server Status Variables.
MySQL uses algorithms that are very scalable, so you can usually run with very little memory. However, normally you get better performance by giving MySQL more memory.
When tuning a MySQL server, the two most important variables to configure
are key_buffer_size and table_cache. You should first feel
confident that you have these set appropriately before trying to change
any other variables.
The following examples indicate some typical variable values for different
runtime configurations. The examples use the mysqld_safe script and
use --var_name=value syntax to set the variable var_name to the value
value. This syntax is available as of MySQL 4.0. For older versions
of MySQL, take the following differences into account:
safe_mysqld rather than mysqld_safe.
--set-variable=var_name=value or -O
var_name=value syntax.
_size, you may need to specify them
without _size. For example, the old name for sort_buffer_size is
sort_buffer. The old name for read_buffer_size is
record_buffer. To see which variables your version of the server
recognizes, use mysqld --help.
If you have at least 256MB of memory and many tables and want maximum performance with a moderate number of clients, you should use something like this:
shell> mysqld_safe --key_buffer_size=64M --table_cache=256 \
--sort_buffer_size=4M --read_buffer_size=1M &
If you have only 128MB of memory and only a few tables, but you still do a lot of sorting, you can use something like this:
shell> mysqld_safe --key_buffer_size=16M --sort_buffer_size=1M
If there are very many simultaneous connections, swapping problems
may occur unless mysqld has been configured to use very
little memory for each connection. mysqld performs better
if you have enough memory for all connections.
With little memory and lots of connections, use something like this:
shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=100K \
--read_buffer_size=100K &
Or even this:
shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=16K \
--table_cache=32 --read_buffer_size=8K \
--net_buffer_length=1K &
If you are doing GROUP BY or ORDER BY operations on tables
that are much larger than your available memory, you should increase the
value of read_rnd_buffer_size to speed up the reading of rows after
sorting operations.
When you have installed MySQL, the `support-files' directory contains some different `my.cnf' sample files: `my-huge.cnf', `my-large.cnf', `my-medium.cnf', and `my-small.cnf'. You can use these as a basis for optimizing your system.
Note that if you specify an option on the command line for mysqld or
mysqld_safe, it remains in effect only for that invocation of the server.
To use the option every time the server runs, put it in an option file.
To see the effects of a parameter change, do something like this (prior to
MySQL 4.1, omit --verbose):
shell> mysqld --key_buffer_size=32M --verbose --help
The variable values are listed near the end of the output.
Make sure that the --verbose and --help options are
last. Otherwise, the effect of any options listed after them on the command
line are not reflected in the output.
For information on tuning the InnoDB storage engine, see
section 15.12 InnoDB Performance Tuning Tips.
The task of the query optimizer is to find an optimal plan for executing an SQL query. Because the difference in performance between ``good'' and ``bad'' plans can be orders of magnitude (that is, seconds versus hours or even days), most query optimizers, including that of MySQL, perform more or less exhaustive search for an optimal plan among all possible query evaluation plans. For join queries, the number of possible plans investigated by the MySQL optimizer grows exponentially with the number of tables referenced in a query. For small numbers of tables (typically less than 7-10) this is not a problem. However, when bigger queries are submitted, the time spent in query optimization may easily become the major bottleneck in the server performance.
MySQL 5.0.1 introduces a new more flexible method for query optimization that allows the user to control how exhaustive the optimizer is in its search for an optimal query evaluation plan. The general idea is that the fewer plans that are investigated by the optimizer, the less time it spends in compiling a query. On the other hand, because the optimizer skips some plans, it may miss finding an optimal plan.
The behavior of the optimizer with respect to the number of plans it evaluates can be controlled via two system variables:
optimizer_prune_level variable tells the optimizer to skip
certain plans based on estimates of the number of rows accessed for each
table. Our experience shows that this kind of ``educated guess'' rarely
misses optimal plans, while it may dramatically reduce query compilation
times. That is why this option is on (optimizer_prune_level=1)
by default. However, if you believe that the optimizer missed better query
plans, then this option can be switched off (optimizer_prune_level=0)
with the risk that query compilation may take much longer. Notice that
even with the use of this heuristic, the optimizer still explores a
roughly exponential number of plans.
optimizer_search_depth variable tells how far in the
``future'' of each incomplete plan the optimizer should look in order
to evaluate whether it should be expanded further. Smaller values of
optimizer_search_depth may result in orders of magnitude smaller query
compilation times. For example, queries with 12-13 or more tables may easily
require hours and even days to compile if optimizer_search_depth
is close to the number of tables in the query. At the same time, if
compiled with optimizer_search_depth equal to 3 or 4, the compiler
may compile in less than a minute for the same query. If you are unsure of
what a reasonable value is for optimizer_search_depth, this variable
can be set to 0 to tell the optimizer to determine the value automatically.
Most of the following tests were performed on Linux with the MySQL benchmarks, but they should give some indication for other operating systems and workloads.
You get the fastest executables when you link with -static.
On Linux, you get the fastest code when compiling with pgcc
and -O3. You need about 200MB memory to compile `sql_yacc.cc'
with these options, because gcc/pgcc needs a lot of memory to
make all functions inline. You should also set CXX=gcc when
configuring MySQL to avoid inclusion of the libstdc++
library, which is not needed. Note that with some versions of pgcc,
the resulting code runs only on true Pentium processors, even if you
use the compiler option indicating that you want the resulting code to work on
all x586-type processors (such as AMD).
By just using a better compiler and better compiler options, you can get a 10-30% speed increase in your application. This is particularly important if you compile the MySQL server yourself.
We have tested both the Cygnus CodeFusion and Fujitsu compilers, but when we tested them, neither was sufficiently bug-free to allow MySQL to be compiled with optimizations enabled.
The standard MySQL binary distributions are compiled with support for all
character sets. When you compile MySQL yourself, you should include support
only for the character sets that you are going to use. This is controlled by
the --with-charset option to configure.
Here is a list of some measurements that we have made:
pgcc and compile everything with -O6, the
mysqld server is 1% faster than with gcc 2.95.2.
-static), the result is 13%
slower on Linux. Note that you still can use a dynamically linked
MySQL library for your client applications. It is the server that is most
critical for performance.
mysqld binary with strip mysqld,
the resulting binary can be up to 4% faster.
localhost,
MySQL uses a socket file by default.)
--with-debug=full, most queries are 20% slower.
Some queries may take substantially longer; for example,
the MySQL benchmarks ran 35% slower. If you use --with-debug (without
=full),
the slowdown is only 15%. For a version of mysqld that has
been compiled with --with-debug=full, you can disable memory
checking at runtime by starting it with the --skip-safemalloc
option. The execution speed should then be close to that obtained when
configuring with --with-debug.
gcc 3.2.
gcc 2.95.2 for UltraSPARC with the
-mcpu=v8 -Wa,-xarch=v8plusa options gives 4% more performance.
gcc without frame pointers
(-fomit-frame-pointer or -fomit-frame-pointer -ffixed-ebp)
makes mysqld 1-4% faster.
Binary MySQL distributions for Linux that are provided by MySQL AB used
to be compiled with pgcc. We had to go back to regular gcc
due to a bug in pgcc that would generate code that does
not run on AMD. We will continue using gcc until that bug is resolved.
In the meantime, if you have a non-AMD machine, you can get a faster
binary by compiling with pgcc. The standard MySQL
Linux binary is linked statically to make it faster and more portable.
The following list indicates some of the ways that the mysqld server
uses memory. Where applicable, the name of the system variable relevant
to the memory use is given:
key_buffer_size) is shared by all
threads; other buffers used by the server are allocated as
needed. See section 7.5.2 Tuning Server Parameters.
thread_stack)
net_buffer_length)
net_buffer_length)
max_allowed_packet when needed. While
a query is running, a copy of the current query string is also allocated.
ISAM and MyISAM tables are memory mapped. This
is because the 32-bit memory space of 4GB is not large enough for most
big tables. When systems with a 64-bit address space become more
common, we may add general support for memory mapping.
read_buffer_size).
read_rnd_buffer_size).
HEAP)
tables. Temporary tables with a large record length (calculated as the
sum of all column lengths) or that contain BLOB columns are
stored on disk.
One problem before MySQL 3.23.2 is that if an internal in-memory
heap table exceeds the size of tmp_table_size, the error The
table tbl_name is full occurs. From 3.23.2 on, this is handled
automatically by changing the in-memory heap table to a disk-based
MyISAM table as necessary. To work around this problem for older
servers, you can increase the temporary table size by setting the
tmp_table_size option to mysqld, or by setting the SQL option
SQL_BIG_TABLES in the client program.
See section 13.5.3 SET Syntax.
In MySQL 3.20, the maximum size of the temporary table is
record_buffer*16; if you are using this version, you have to increase
the value of record_buffer. You can also start mysqld with the
--big-tables option to always store temporary tables on disk.
However, this affects the speed of many complicated queries.
malloc() and
free().
MyISAM and ISAM table that is opened, the index file
is opened once and the data file is opened once for each concurrently running
thread. For each concurrent thread, a table structure, column structures for
each column, and a buffer of size 3 * N are allocated (where N
is the maximum row length, not counting BLOB columns). A BLOB
column requires five to eight bytes plus the length of the BLOB data.
The MyISAM and ISAM storage engines maintain one extra row
buffer for internal use.
BLOB columns, a buffer is enlarged dynamically
to read in larger BLOB values. If you scan a table, a buffer as large
as the largest BLOB value is allocated.
FLUSH TABLES statement or mysqladmin flush-tables command
closes all tables that are not in use at once and marks all in-use tables to be
closed when the currently executing thread finishes. This effectively frees
most in-use memory. FLUSH TABLES does not return until all tables have
been closed.
ps and other system status programs may report that mysqld
uses a lot of memory. This may be caused by thread stacks on different
memory addresses. For example, the Solaris version of ps counts
the unused memory between stacks as used memory. You can verify this by
checking available swap with swap -s. We have tested
mysqld with several memory-leakage detectors (both commercial and open
source), so there should be no memory leaks.
When a new client connects to mysqld, mysqld spawns a
new thread to handle the request. This thread first checks whether the
hostname is in the hostname cache. If not, the thread attempts to resolve the
hostname:
gethostbyaddr_r() and
gethostbyname_r() calls, the thread uses them to perform hostname
resolution.
gethostbyaddr() and
gethostbyname() instead. In this case, no other thread
can resolve hostnames that are not in the hostname cache until the
first thread unlocks the mutex.
You can disable DNS hostname lookups by starting mysqld with the
--skip-name-resolve option. However, in this case, you can use only IP
numbers in the MySQL grant tables.
If you have a very slow DNS and many hosts, you can get more performance by
either disabling DNS lookups with --skip-name-resolve or by
increasing the HOST_CACHE_SIZE define (default value: 128) and
recompiling mysqld.
You can disable the hostname cache by starting the server with the
--skip-host-cache option. To clear the hostname cache, issue a
FLUSH HOSTS statement or execute the mysqladmin flush-hosts
command.
If you want to disallow TCP/IP connections entirely, start mysqld with
the --skip-networking option.
MyISAM tables, you symlink the index file and/or
data file from their usual location in the data directory to another disk
(that may also be striped). This makes both the seek and read times better,
assuming that the disk is not used for other purposes as well. See section 7.6.1 Using Symbolic Links.
hdparm to
configure your disk's interface. (Up to 100% under load is not uncommon.)
The following hdparm options should be quite good for MySQL, and
probably for many other applications:
hdparm -m 16 -d 1Note that performance and reliability when using this command depends on your hardware, so we strongly suggest that you test your system thoroughly after using
hdparm. Please consult the hdparm
manual page for more information. If hdparm is not used wisely,
filesystem corruption may result, so back up everything before
experimenting!
-o noatime option. That skips updates
to the last access time in inodes on the filesystem, which avoids
some disk seeks.
On many operating systems, you can set a filesystem to be updated
asynchronously by mounting it with the -o async option. If your
computer is reasonably stable, this should give you more performance without
sacrificing too much reliability. (This flag is on by default on Linux.)
You can move tables and databases from the database directory to other locations and replace them with symbolic links to the new locations. You might want to do this, for example, to move a database to a file system with more free space or increase the speed of your system by spreading your tables to different disk.
The recommended way to do this is to just symlink databases to a different disk. Symlink tables only as a last resort.
On Unix, the way to symlink a database is to first create a directory on some disk where you have free space and then create a symlink to it from the MySQL data directory.
shell> mkdir /dr1/databases/test shell> ln -s /dr1/databases/test /path/to/datadir
MySQL doesn't support linking one directory to multiple
databases. Replacing a database directory with a symbolic link
works fine as long as you don't make a symbolic link between databases.
Suppose that you have a database db1 under the MySQL data
directory, and then make a symlink db2 that points to db1:
shell> cd /path/to/datadir shell> ln -s db1 db2
For any table tbl_a in db1, there also appears to be
a table tbl_a in db2. If one client updates db1.tbl_a
and another client updates db2.tbl_a, there are problems.
If you really need to do this, you can change one of the source files. The file to modify depends on your version of MySQL. For MySQL 4.0 and up, look for the following statement in the `mysys/my_symlink.c' file:
if (!(MyFlags & MY_RESOLVE_LINK) ||
(!lstat(filename,&stat_buff) && S_ISLNK(stat_buff.st_mode)))
Before MySQL 4.0, look for this statement in the `mysys/mf_format.c' file:
if (flag & 32 || (!lstat(to,&stat_buff) && S_ISLNK(stat_buff.st_mode)))
Change the statement to this:
if (1)
On Windows, you can use internal symbolic links to directories by compiling
MySQL with -DUSE_SYMDIR. This allows you to put different
databases on different disks. See section 7.6.1.3 Using Symbolic Links for Databases on Windows.
(It is necessary to define USE_SYMDIR explicitly only before
MySQL 4.0. As of MySQL 4.0, symbolic link support is enabled by default for
all Windows servers.)
Before MySQL 4.0, you should not symlink tables unless you are
very careful with them. The problem is that if you run ALTER
TABLE, REPAIR TABLE, or OPTIMIZE TABLE on a symlinked
table, the symlinks are removed and replaced by the original
files. This happens because these statements work by creating a
temporary file in the database directory and replacing the original
file with the temporary file when the statement operation is complete.
You should not symlink tables on systems that don't have a fully
working realpath() call. (At least Linux and Solaris support
realpath()). You can check whether your system supports symbolic links
by issuing a SHOW VARIABLES LIKE 'have_symlink' statement.
In MySQL 4.0, symlinks are fully supported only for MyISAM
tables. For other table types, you may get strange problems
if you try to use symbolic links on files in the operating system with
any of the preceding statements.
The handling of symbolic links for MyISAM tables in MySQL 4.0 works
the following way:
ln -s
if mysqld is not running. With SQL, you can instruct the server to
perform the symlinking by using the DATA DIRECTORY and INDEX
DIRECTORY options to CREATE TABLE.
See section 13.2.6 CREATE TABLE Syntax.
myisamchk does not replace a symlink with the data file or index file.
It works directly on the file a symlink points to. Any temporary files
are created in the directory where the data file or index file is
located.
mysqld as root or allow
users to have write access to the MySQL database directories.
ALTER TABLE ... RENAME and you don't move
the table to another database, the symlinks in the database directory
are renamed to the new names and the data file and index file are
renamed accordingly.
ALTER TABLE ... RENAME to move a table to another database,
the table is moved to the other database directory. The old
symlinks and the files to which they pointed are deleted. In other words,
the new table is not symlinked.
--skip-symbolic-links
option to mysqld to ensure that no one can use mysqld to drop
or rename a file outside of the data directory.
SHOW CREATE TABLE doesn't report if a table has symbolic links
prior to MySQL 4.0.15. This is also true for mysqldump, which uses
SHOW CREATE TABLE to generate CREATE TABLE statements.
Table symlink operations that are not yet supported:
ALTER TABLE ignores the DATA DIRECTORY and INDEX
DIRECTORY table options.
BACKUP TABLE and RESTORE TABLE don't respect symbolic
links.
db1 under the MySQL data directory,
a table tbl1 in this database, and in the db1 directory you
make a symlink tbl2 that points to tbl1:
shell> cd /path/to/datadir/db1 shell> ln -s tbl1.frm tbl2.frm shell> ln -s tbl1.MYD tbl2.MYD shell> ln -s tbl1.MYI tbl2.MYIThere are problems if one thread reads
db1.tbl1 and another
thread updates db1.tbl2:
tbl1 has not been
updated so it returns outdated results).
ALTER statements on tbl2 also fail.
Beginning with MySQL 3.23.16, the mysqld-max
and mysql-max-nt servers for Windows are
compiled with the -DUSE_SYMDIR option. This allows you to put a
database directory on a different disk by setting up a symbolic link to it.
This is similar to the way that symbolic links work on Unix, although the
procedure for setting up the link is different.
As of MySQL 4.0, symbolic links are enabled by default. If you don't need them,
you can disable them with the skip-symbolic-links option:
[mysqld] skip-symbolic-links
Before MySQL 4.0, symbolic links are disabled by default. To enable them, you should put the following entry in your `my.cnf' or `my.ini' file:
[mysqld] symbolic-links
On Windows, you make a symbolic link to a MySQL database by creating a file in the data directory that contains the path to the destination directory. The file should be named `db_name.sym', where db_name is the database name.
Suppose that the MySQL data directory is `C:\mysql\data'
and you want to have database foo located at `D:\data\foo'.
Set up a symlink like this:
D:\data\foo\.
After that, all tables created in the database foo are created in
`D:\data\foo'. Note that the symbolic link is not used if a
directory with the database name exists in the MySQL data directory.
There are many different MySQL client programs that connect to the server to access databases or perform administrative tasks. Other utilities are available as well. These do not communicate with the server but perform MySQL-related operations.
This chapter provides a brief overview of these programs and then a more detailed description of each one. The descriptions indicate how to invoke the programs and the options they understand. See section 4 Using MySQL Programs for general information on invoking programs and specifying program options.
The following list briefly describes the MySQL client programs and utilities:
myisampack
MyISAM tables to produce smaller read-only
tables.
See section 8.2 myisampack, the MySQL Compressed Read-only Table Generator.
mysql
mysql, the Command-Line Tool.
mysqlaccess
mysqladmin
mysqladmin can also be used to retrieve version,
process, and status information from the server.
See section 8.4 mysqladmin, Administering a MySQL Server.
mysqlbinlog
mysqlbinlog Binary Log Utility.
mysqlcc
mysqlcc, the MySQL Control Center.
mysqlcheck
mysqlcheck Table Maintenance and Repair Program.
mysqldump
mysqldump Database Backup Program.
mysqlhotcopy
MyISAM or ISAM tables
while the server is running.
See section 8.9 The mysqlhotcopy Database Backup Program.
mysqlimport
LOAD DATA INFILE.
See section 8.10 The mysqlimport Data Import Program.
mysqlshow
mysqlshow, Showing Databases, Tables, and Columns.
perror
perror, Explaining Error Codes.
replace
replace String-Replacement Utility.
Each MySQL program takes many different options. However, every MySQL program
provides a --help option that you can use to get a full description
of the program's different options. For example, try mysql --help.
MySQL clients that communicate with the server using the
mysqlclient library use the following environment variables:
MYSQL_UNIX_PORT
| The default Unix socket file; used for connections to localhost
|
MYSQL_TCP_PORT
| The default port number; used for TCP/IP connections |
MYSQL_PWD
| The default password |
MYSQL_DEBUG
| Debug trace options when debugging |
TMPDIR
| The directory where temporary tables and files are created |
Use of MYSQL_PWD is insecure.
See section 5.6.6 Keeping Your Password Secure.
You can override the default option values or values specified in environment variables for all standard programs by specifying options in an option file or on the command line. section 4.3 Specifying Program Options.
myisampack, the MySQL Compressed Read-only Table Generator
The myisampack utility compresses MyISAM tables.
myisampack works by compressing each column in the table separately.
Usually, myisampack packs the data file 40%-70%.
When the table is used later, the information needed to decompress columns is read into memory. This results in much better performance when accessing individual records, because you only have to uncompress exactly one record, not a much larger disk block as when using Stacker on MS-DOS.
MySQL uses mmap() when possible to perform memory mapping on
compressed tables. If mmap() doesn't work, MySQL falls back to
normal read/write file operations.
A similar utility, pack_isam, compresses ISAM tables. Because
ISAM tables are deprecated, this section discusses only
myisampack, but the general procedures for using myisampack
are also true for pack_isam unless otherwise specified.
Please note the following:
mysqld server was invoked with the
--skip-external-locking option, it is not a good idea to invoke
myisampack if the table might be updated by the server during the
packing process.
myisampack can pack BLOB or TEXT columns.
The older pack_isam program for ISAM tables cannot.
Invoke myisampack like this:
shell> myisampack [options] filename ...
Each filename should be the name of an index (`.MYI') file. If you are not in the database directory, you should specify the pathname to the file. It is permissible to omit the `.MYI' extension.
myisampack supports the following options:
--help, -?
--backup, -b
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
--force, -f
myisampack exists.
(myisampack creates a temporary file named `tbl_name.TMD' while
it compresses the table. If you kill myisampack, the `.TMD'
file might not be deleted.) Normally, myisampack exits with an
error if it finds that `tbl_name.TMD' exists. With --force,
myisampack packs the table anyway.
--join=big_tbl_name, -j big_tbl_name
--packlength=#, -p #
myisampack stores all rows with length pointers of 1, 2, or 3
bytes. In most normal cases, myisampack can determine the right length
value before it begins packing the file, but it may notice during the packing
process that it could have used a shorter length. In this case,
myisampack prints a note that the next time you pack the same file,
you could use a shorter record length.
--silent, -s
--test, -t
--tmp_dir=path, -T path
--verbose, -v
--version, -V
--wait, -w
mysqld server was
invoked with the --skip-external-locking option, it is not a good idea
to invoke myisampack if the table might be updated by the server during
the packing process.
The following sequence of commands illustrates a typical table compression session:
shell> ls -l station.* -rw-rw-r-- 1 monty my 994128 Apr 17 19:00 station.MYD -rw-rw-r-- 1 monty my 53248 Apr 17 19:00 station.MYI -rw-rw-r-- 1 monty my 5767 Apr 17 19:00 station.frm shell> myisamchk -dvv station MyISAM file: station Isam-version: 2 Creation time: 1996-03-13 10:08:58 Recover time: 1997-02-02 3:06:43 Data records: 1192 Deleted blocks: 0 Datafile parts: 1192 Deleted data: 0 Datafile pointer (bytes): 2 Keyfile pointer (bytes): 2 Max datafile length: 54657023 Max keyfile length: 33554431 Recordlength: 834 Record format: Fixed length table description: Key Start Len Index Type Root Blocksize Rec/key 1 2 4 unique unsigned long 1024 1024 1 2 32 30 multip. text 10240 1024 1 Field Start Length Type 1 1 1 2 2 4 3 6 4 4 10 1 5 11 20 6 31 1 7 32 30 8 62 35 9 97 35 10 132 35 11 167 4 12 171 16 13 187 35 14 222 4 15 226 16 16 242 20 17 262 20 18 282 20 19 302 30 20 332 4 21 336 4 22 340 1 23 341 8 24 349 8 25 357 8 26 365 2 27 367 2 28 369 4 29 373 4 30 377 1 31 378 2 32 380 8 33 388 4 34 392 4 35 396 4 36 400 4 37 404 1 38 405 4 39 409 4 40 413 4 41 417 4 42 421 4 43 425 4 44 429 20 45 449 30 46 479 1 47 480 1 48 481 79 49 560 79 50 639 79 51 718 79 52 797 8 53 805 1 54 806 1 55 807 20 56 827 4 57 831 4 shell> myisampack station.MYI Compressing station.MYI: (1192 records) - Calculating statistics normal: 20 empty-space: 16 empty-zero: 12 empty-fill: 11 pre-space: 0 end-space: 12 table-lookups: 5 zero: 7 Original trees: 57 After join: 17 - Compressing file 87.14% Remember to run myisamchk -rq on compressed tables shell> ls -l station.* -rw-rw-r-- 1 monty my 127874 Apr 17 19:00 station.MYD -rw-rw-r-- 1 monty my 55296 Apr 17 19:04 station.MYI -rw-rw-r-- 1 monty my 5767 Apr 17 19:00 station.frm shell> myisamchk -dvv station MyISAM file: station Isam-version: 2 Creation time: 1996-03-13 10:08:58 Recover time: 1997-04-17 19:04:26 Data records: 1192 Deleted blocks: 0 Datafile parts: 1192 Deleted data: 0 Datafile pointer (bytes): 3 Keyfile pointer (bytes): 1 Max datafile length: 16777215 Max keyfile length: 131071 Recordlength: 834 Record format: Compressed table description: Key Start Len Index Type Root Blocksize Rec/key 1 2 4 unique unsigned long 10240 1024 1 2 32 30 multip. text 54272 1024 1 Field Start Length Type Huff tree Bits 1 1 1 constant 1 0 2 2 4 zerofill(1) 2 9 3 6 4 no zeros, zerofill(1) 2 9 4 10 1 3 9 5 11 20 table-lookup 4 0 6 31 1 3 9 7 32 30 no endspace, not_always 5 9 8 62 35 no endspace, not_always, no empty 6 9 9 97 35 no empty 7 9 10 132 35 no endspace, not_always, no empty 6 9 11 167 4 zerofill(1) 2 9 12 171 16 no endspace, not_always, no empty 5 9 13 187 35 no endspace, not_always, no empty 6 9 14 222 4 zerofill(1) 2 9 15 226 16 no endspace, not_always, no empty 5 9 16 242 20 no endspace, not_always 8 9 17 262 20 no endspace, no empty 8 9 18 282 20 no endspace, no empty 5 9 19 302 30 no endspace, no empty 6 9 20 332 4 always zero 2 9 21 336 4 always zero 2 9 22 340 1 3 9 23 341 8 table-lookup 9 0 24 349 8 table-lookup 10 0 25 357 8 always zero 2 9 26 365 2 2 9 27 367 2 no zeros, zerofill(1) 2 9 28 369 4 no zeros, zerofill(1) 2 9 29 373 4 table-lookup 11 0 30 377 1 3 9 31 378 2 no zeros, zerofill(1) 2 9 32 380 8 no zeros 2 9 33 388 4 always zero 2 9 34 392 4 table-lookup 12 0 35 396 4 no zeros, zerofill(1) 13 9 36 400 4 no zeros, zerofill(1) 2 9 37 404 1 2 9 38 405 4 no zeros 2 9 39 409 4 always zero 2 9 40 413 4 no zeros 2 9 41 417 4 always zero 2 9 42 421 4 no zeros 2 9 43 425 4 always zero 2 9 44 429 20 no empty 3 9 45 449 30 no empty 3 9 46 479 1 14 4 47 480 1 14 4 48 481 79 no endspace, no empty 15 9 49 560 79 no empty 2 9 50 639 79 no empty 2 9 51 718 79 no endspace 16 9 52 797 8 no empty 2 9 53 805 1 17 1 54 806 1 3 9 55 807 20 no empty 3 9 56 827 4 no zeros, zerofill(2) 2 9 57 831 4 no zeros, zerofill(1) 2 9
myisampack displays the following kinds of information:
normal
empty-space
empty-zero
empty-fill
BIGINT
column (eight bytes) can be stored as a TINYINT column (one byte) if
all its values are in the range from -128 to 127.
pre-space
end-space
table-lookup
ENUM before Huffman compression.
zero
Original trees
After join
After a table has been compressed, myisamchk -dvv prints additional
information about each column:
Type
constant
no endspace
no endspace, not_always
no endspace, no empty
table-lookup
ENUM.
zerofill(n)
no zeros
always zero
Huff tree
Bits
After you run myisampack, you must run
myisamchk to re-create any indexes. At this time, you
can also sort the index blocks and create statistics needed for
the MySQL optimizer to work more efficiently:
shell> myisamchk -rq --sort-index --analyze tbl_name.MYI
A similar procedure applies for ISAM tables. After using
pack_isam, use isamchk to re-create the indexes:
shell> isamchk -rq --sort-index --analyze tbl_name.ISM
After you have installed the packed table into the MySQL database directory,
you should execute mysqladmin flush-tables to force mysqld
to start using the new table.
To unpack a packed table, use the --unpack option to myisamchk
or isamchk.
mysql, the Command-Line Tool
mysql is a simple SQL shell (with GNU readline capabilities).
It supports interactive and non-interactive use. When used interactively,
query results are presented in an ASCII-table format. When used
non-interactively (for example, as a filter), the result is presented in
tab-separated format. The output format can be changed using command-line
options.
If you have problems due to insufficient memory for large result sets, use the
--quick option. This forces mysql to retrieve results from
the server a row at a time rather than retrieving the entire result set
and buffering it in memory before displaying it. This is done by using
mysql_use_result() rather than mysql_store_result() to
retrieve the result set.
Using mysql is very easy. Invoke it from the prompt of your command
interpreter as follows:
shell> mysql db_name
Or:
shell> mysql --user=user_name --password=your_password db_name
Then type an SQL statement, end it with `;', \g, or \G
and press Enter.
You can run a script simply like this:
shell> mysql db_name < script.sql > output.tab
mysql supports the following options:
--help, -?
--batch, -B
mysql doesn't use the history file.
--character-sets-dir=path
--compress, -C
--database=db_name, -D db_name
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
The default is 'd:t:o,/tmp/mysql.trace'.
--debug-info, -T
--default-character-set=charset
--execute=statement, -e statement
--batch.
--force, -f
--host=host_name, -h host_name
--html, -H
--ignore-space, -i
IGNORE_SPACE in
section 5.2.2 The Server SQL Mode.
--local-infile[={0|1}]
LOCAL capability for LOAD DATA INFILE.
With no value, the option enables LOCAL. It may be given as
--local-infile=0 or --local-infile=1 to explicitly disable
or enable LOCAL. Enabling LOCAL has no effect if the server
does not also support it.
--named-commands, -G
quit and \q both
are recognized.
--no-auto-rehash, -A
mysql to start faster,
but you must issue the rehash command if you want to use table and
column name completion.
--no-beep, -b
--no-named-commands, -g
\* form only, or use
named commands only at the beginning of a line ending with a semicolon
(`;'). As of MySQL 3.23.22, mysql starts with this option
enabled by default! However, even with this option, long-format
commands still work from the first line.
--no-pager
mysql Commands.
--no-tee
mysql Commands.
--one-database, -O
--pager[=command]
PAGER environment
variable. Valid pagers are less, more, cat [>
filename], and so forth. This option works only on Unix. It does not
work in batch mode.
Output paging is discussed further in
section 8.3.1 mysql Commands.
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--prompt=format_str
mysql>.
The special sequences that the prompt can contain are described in
section 8.3.1 mysql Commands.
--protocol={TCP | SOCKET | PIPE | MEMORY}
--quick, -q
mysql
doesn't use the history file.
--raw, -r
--batch option.
--reconnect
--skip-reconnect.
New in MySQL 4.1.0.
--safe-updates, --i-am-a-dummy, -U
UPDATE and DELETE statements that specify rows
to affect using key values. If you have this option in an option file,
you can override it by using --safe-updates on the command line.
See section 8.3.3 mysql Tips for more information about
this option.
--sigint-ignore
SIGINT signals (typically the result of typing Control-C).
This option was added in MySQL 4.1.6.
--silent, -s
--skip-column-names, -N
--skip-line-numbers, -L
--socket=path, -S path
--table, -t
--tee=file_name
mysql Commands.
--unbuffered, -n
--user=user_name, -u user_name
--verbose, -v
-v -v -v produces the table output format even in batch
mode.)
--version, -V
--vertical, -E
\G.
--wait, -w
--xml, -X
You can also set the following variables by using --var_name=value
options:
connect_timeout
max_allowed_packet
max_join_size
--safe-updates.
(Default value is 1,000,000.)
net_buffer_length
select_limit
SELECT statements when using
--safe-updates.
(Default value is 1,000.)
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
On Unix, the mysql client writes a record of executed statements to a
history file. By default, the history file is named `.mysql_history'
and is created in your home directory. To specify a different file,
set the value of the MYSQL_HISTFILE environment variable.
If you do not want to maintain a history file, first remove `.mysql_history' if it exists, and then use either of the following techniques:
MYSQL_HISTFILE variable to `/dev/null'. To cause this
setting to take effect each time you log in, put the setting in one of
your shell's startup files.
shell> ln -s /dev/null $HOME/.mysql_historyYou need do this only once.
mysql Commands
mysql sends SQL statements that you issue to the server to be
executed. There is also a set of commands that mysql itself
interprets. For a list of these commands, type help or \h at
the mysql> prompt:
mysql> help
MySQL commands:
? (\h) Synonym for `help'.
clear (\c) Clear command.
connect (\r) Reconnect to the server.
Optional arguments are db and host.
delimiter (\d) Set query delimiter.
edit (\e) Edit command with $EDITOR.
ego (\G) Send command to mysql server,
display result vertically.
exit (\q) Exit mysql. Same as quit.
go (\g) Send command to mysql server.
help (\h) Display this help.
nopager (\n) Disable pager, print to stdout.
notee (\t) Don't write into outfile.
pager (\P) Set PAGER [to_pager].
Print the query results via PAGER.
print (\p) Print current command.
prompt (\R) Change your mysql prompt.
quit (\q) Quit mysql.
rehash (\#) Rebuild completion hash.
source (\.) Execute an SQL script file.
Takes a file name as an argument.
status (\s) Get status information from the server.
system (\!) Execute a system shell command.
tee (\T) Set outfile [to_outfile].
Append everything into given outfile.
use (\u) Use another database.
Takes database name as argument.
Each command has both a long and short form. The long form is not case sensitive; the short form is. The long form can be followed by an optional semicolon terminator, but the short form should not.
The edit, nopager, pager, and system commands
work only in Unix.
The status command provides some information about the
connection and the server you are using. If you are running in
--safe-updates mode, status also prints the values for
the mysql variables that affect your queries.
To log queries and their output, use the tee command. All the data
displayed on the screen is appended into a given file. This can be very
useful for debugging purposes also. You can enable this feature on the
command line with the --tee option, or interactively with the tee
command. The tee file can be disabled interactively with the
notee command. Executing tee again re-enables logging.
Without a parameter, the previous file is used. Note that tee
flushes query results to the file after each statement, just before mysql
prints its next prompt.
Browsing or searching query results in interactive mode by using Unix
programs such as less, more, or any other similar program is
possible with the --pager option. If you specify no value for the
option, mysql checks the value of the PAGER environment
variable and sets the pager to that. Output paging can be enabled
interactively with the pager command and disabled with
nopager. The command takes an optional argument; if given, the
paging program is set to that. With no argument, the pager is set to the
pager that was set on the command line, or stdout if no pager was
specified.
Output paging works only in Unix because it uses the popen()
function, which doesn't exist on Windows. For Windows, the tee
option can be used instead to save query output, although this is not as
convenient as pager for browsing output in some situations.
A few tips about the pager command:
mysql> pager cat > /tmp/log.txtYou can also pass any options for the program that you want to use as your pager:
mysql> pager less -n -i -S
-S option. You may find it very
useful for browsing wide query results. Sometimes a very wide result set is
difficult to read on the screen. The -S option to less can
make the result set much more readable because you can scroll it
horizontally using the left-arrow and right-arrow keys. You can also use
-S interactively within less to switch the horizontal-browse
mode on and off. For more information, read the less manual page:
shell> man less
mysql> pager cat | tee /dr1/tmp/res.txt \
| tee /dr2/tmp/res2.txt | less -n -i -S
In this example, the command would send query results to two files in two
different directories on two different filesystems mounted on `/dr1'
and `/dr2', yet still display the results onscreen via less.
You can also combine the tee and pager functions. Have a
tee file enabled and pager set to less, and you are
able to browse the results using the less program and still have
everything appended into a file the same time. The difference between the
Unix tee used with the pager command and the mysql
built-in tee command is that the built-in tee works even if
you don't have the Unix tee available. The built-in tee also
logs everything that is printed on the screen, whereas the Unix tee
used with pager doesn't log quite that much. Additionally, tee
file logging can be turned on and off interactively from within
mysql. This is useful when you want to log some queries to a file,
but not others.
From MySQL 4.0.2 on, the default mysql> prompt can be reconfigured.
The string for defining the prompt can contain the following special
sequences:
| Option | Description |
\v | The server version |
\d | The current database |
\h | The server host |
\p | The current TCP/IP host |
\u | Your username |
\U | Your full user_name@host_name account name
|
\\ | A literal `\' backslash character |
\n | A newline character |
\t | A tab character |
\ | A space (a space follows the backslash) |
\_ | A space |
\R | The current time, in 24-hour military time (0-23) |
\r | The current time, standard 12-hour time (1-12) |
\m | Minutes of the current time |
\y | The current year, two digits |
\Y | The current year, four digits |
\D | The full current date |
\s | Seconds of the current time |
\w | The current day of the week in three-letter format (Mon, Tue, ...) |
\P | am/pm |
\o | The current month in numeric format |
\O | The current month in three-letter format (Jan, Feb, ...) |
\c | A counter that increments for each statement you issue |
\S | Semicolon |
\' | Single quote |
\" | Double quote |
`\' followed by any other letter just becomes that letter.
If you specify the prompt command with no argument, mysql resets
the prompt to the default of mysql>.
You can set the prompt in several ways:
MYSQL_PS1 environment variable to a prompt string. For
example:
shell> export MYSQL_PS1="(\u@\h) [\d]> "
prompt option in the [mysql] group of any MySQL
option file, such as `/etc/my.cnf' or the `.my.cnf' file in
your home directory.
For example:
[mysql] prompt=(\\u@\\h) [\\d]>\\_In this example, note that the backslashes are doubled. If you set the prompt using the
prompt option in an option
file, it is advisable to double the backslashes when using the special
prompt options. There is
some overlap in the set of allowable prompt options and the set of special
escape sequences that are recognized in option files.
(These sequences are listed in section 4.3.2 Using Option Files.)
The overlap may cause you problems if you use single backslashes.
For example, \s is interpreted as a space rather than as the
current seconds value. The following example shows how to define a prompt
within an option file to
include the current time in HH:MM:SS> format:
[mysql] prompt="\\r:\\m:\\s> "
--prompt option on the command line to mysql.
For example:
shell> mysql --prompt="(\u@\h) [\d]> " (user@host) [database]>
prompt (or
\R) command. For example:
mysql> prompt (\u@\h) [\d]>\_ PROMPT set to '(\u@\h) [\d]>\_' (user@host) [database]> (user@host) [database]> prompt Returning to default PROMPT of mysql> mysql>
The mysql client typically is used interactively, like this:
shell> mysql db_name
However, it's also possible to put your SQL statements in a file and then
tell mysql to read its input from that file. To do so, create a text
file `text_file' that contains the statements you wish to execute.
Then invoke mysql as shown here:
shell> mysql db_name < text_file
You can also start your text file with a USE db_name statement. In
this case, it is unnecessary to specify the database name on the command
line:
shell> mysql < text_file
If you are running mysql, you can execute an SQL
script file using the source or \. command:
mysql> source filename mysql> \. filename
Sometimes you may want your script to display progress information to the user; for this you can insert some lines like
SELECT '<info_to_display>' AS ' ';
which outputs <info_to_display>.
For more information about batch mode, see section 3.5 Using mysql in Batch Mode.
mysql Tips
This section describes some techniques that can help you use mysql more
effectively.
Some query results are much more readable when displayed vertically, instead of in the usual horizontal table format. Queries can be displayed vertically by terminating the query with \G instead of a semicolon. For example, longer text values that include newlines often are much easier to read with vertical output:
mysql> SELECT * FROM mails WHERE LENGTH(txt) < 300 LIMIT 300,1\G
*************************** 1. row ***************************
msg_nro: 3068
date: 2000-03-01 23:29:50
time_zone: +0200
mail_from: Monty
reply: monty@no.spam.com
mail_to: "Thimble Smith" <tim@no.spam.com>
sbj: UTF-8
txt: >>>>> "Thimble" == Thimble Smith writes:
Thimble> Hi. I think this is a good idea. Is anyone familiar
Thimble> with UTF-8 or Unicode? Otherwise, I'll put this on my
Thimble> TODO list and see what happens.
Yes, please do that.
Regards,
Monty
file: inbox-jani-1
hash: 190402944
1 row in set (0.09 sec)
--safe-updates Option
For beginners, a useful startup option is --safe-updates (or
--i-am-a-dummy, which has the same effect). This option was
introduced in MySQL 3.23.11. It is helpful for cases when you might
have issued a DELETE FROM tbl_name statement but forgotten the
WHERE clause. Normally, such a statement deletes all rows from the
table. With --safe-updates, you can delete rows only by specifying
the key values that identify them. This helps prevent accidents.
When you use the --safe-updates option, mysql issues the
following statement when it connects to the MySQL server:
SET SQL_SAFE_UPDATES=1,SQL_SELECT_LIMIT=1000, SQL_MAX_JOIN_SIZE=1000000;
See section 13.5.3 SET Syntax.
The SET statement has the following effects:
UPDATE or DELETE statement
unless you specify a key constraint in the WHERE clause or provide a
LIMIT clause (or both).
For example:
UPDATE tbl_name SET not_key_column=# WHERE key_column=#; UPDATE tbl_name SET not_key_column=# LIMIT 1;
SELECT results are automatically limited to 1,000 rows
unless the statement includes a LIMIT clause.
SELECT statements that probably need to examine
more than 1,000,000 row combinations are aborted.
To specify limits other than 1,000 and 1,000,000, you can override the
defaults by using --select_limit and --max_join_size options:
shell> mysql --safe-updates --select_limit=500 --max_join_size=10000
mysql Auto-Reconnect
If the mysql client loses its connection to the server while sending
a query, it immediately and automatically tries to reconnect once to the
server and send the query again. However, even if mysql succeeds in
reconnecting, your first connection has ended and all your previous session
objects and settings are lost: temporary tables, the autocommit mode, and
user and session variables. This behavior may be dangerous for you, as in
the following example where the server was shut down and restarted without
you knowing it:
mysql> SET @a=1; Query OK, 0 rows affected (0.05 sec) mysql> INSERT INTO t VALUES(@a); ERROR 2006: MySQL server has gone away No connection. Trying to reconnect... Connection id: 1 Current database: test Query OK, 1 row affected (1.30 sec) mysql> SELECT * FROM t; +------+ | a | +------+ | NULL | +------+ 1 row in set (0.05 sec)
The @a user variable has been lost with the connection, and after
the reconnection it is undefined. If it is important to have mysql
terminate with an error if the connection has been lost, you can start the
mysql client with the --skip-reconnect option.
mysqladmin, Administering a MySQL Server
mysqladmin is a client for performing administrative operations.
You can use it to check the server's configuration and current status, create
and drop databases, and more.
Invoke mysqladmin like this:
shell> mysqladmin [options] command [command-option] command ...
mysqladmin supports the following commands:
create db_name
debug
drop db_name
extended-status
flush-hosts
flush-logs
flush-privileges
reload).
flush-status
flush-tables
flush-threads
kill id,id,...
old-password new-password
password command but stores the password using
the old (pre-4.1) password-hashing format. This command was added in MySQL
4.1.0.
password new-password
new-password
for the account that you use with mysqladmin for connecting to the
server.
If new-password contains spaces or other characters that are special
to your command interpreter, you need to enclose it within quotes.
On Windows, be sure to use double quotes rather than single quotes;
single quotes are not be stripped from the password, they are
interpreted as part of the password. For example:
shell> mysqladmin password "my new password"
ping
mysqladmin is 0 if the server is running,
1 if it is not. Beginning with MySQL 4.0.22, the status is 0 even in case
of an error such as Access denied, because that means the server is
running but disallowed the connection, which is different from the server
not running.
processlist
SHOW PROCESSLIST statement.
If the --verbose option is given, the output is like that of
SHOW FULL PROCESSLIST.
reload
refresh
shutdown
start-slave
status
stop-slave
variables
version
All commands can be shortened to any unique prefix. For example:
shell> mysqladmin proc stat +----+-------+-----------+----+-------------+------+-------+------+ | Id | User | Host | db | Command | Time | State | Info | +----+-------+-----------+----+-------------+------+-------+------+ | 6 | monty | localhost | | Processlist | 0 | | | +----+-------+-----------+----+-------------+------+-------+------+ Uptime: 10077 Threads: 1 Questions: 9 Slow queries: 0 Opens: 6 Flush tables: 1 Open tables: 2 Memory in use: 1092K Max memory used: 1116K
The mysqladmin status command result displays the following values:
Uptime
Threads
Questions
Slow queries
long_query_time
seconds. See section 5.9.5 The Slow Query Log.
Opens
Flush tables
flush ..., refresh, and reload commands the
server has executed.
Open tables
Memory in use
mysqld code.
This value is displayed only when MySQL has been compiled with
--with-debug=full.
Maximum memory used
mysqld code.
This value is displayed only when MySQL has been compiled with
--with-debug=full.
If you execute mysqladmin shutdown when connecting to a local server
using a Unix socket file, mysqladmin waits until the server's process
ID file has been removed, to ensure that the server has stopped properly.
mysqladmin supports the following options:
--help, -?
--character-sets-dir=path
--compress, -C
--count=#, -c #
--sleep
(-i).
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
The default is 'd:t:o,/tmp/mysqladmin.trace'.
--default-character-set=charset
--force, -f
drop database command.
With multiple commands, continue even if an error occurs.
--host=host_name, -h host_name
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--protocol={TCP | SOCKET | PIPE | MEMORY}
--relative, -r
-i. Currently, this option works only with the extended-status
command.
--silent, -s
--sleep=delay, -i delay
--socket=path, -S path
--user=user_name, -u user_name
--verbose, -v
--version, -V
--vertical, -E
--relative, but
prints output vertically.
--wait[=#], -w[#]
You can also set the following variables by using --var_name=value
options:
connect_timeout
shutdown_timeout
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
mysqlbinlog Binary Log Utility
The binary log files that the server generates are written in binary format.
To examine these files in text format, use the mysqlbinlog utility.
It is available as of MySQL 3.23.14.
Invoke mysqlbinlog like this:
shell> mysqlbinlog [options] log-file ...
For example, to display the contents of the binary log `binlog.000003', use this command:
shell> mysqlbinlog binlog.0000003
The output includes all statements contained in `binlog.000003', together with other information such as the time each statement took, the thread ID of the client that issued it, the timestamp when it was issued, and so forth.
Normally, you use mysqlbinlog to read binary log files directly and
apply them to the local MySQL server. It is also possible to read binary
logs from a remote server by using the --read-from-remote-server
option.
When you read remote binary logs, the connection parameter options can be
given to indicate how to connect to the server, but they are ignored unless
you also specify the --read-from-remote-server option. These options
are --host, --password, --port, --protocol,
--socket, and --user.
You can also use mysqlbinlog to read relay log files written by a
slave server in a replication setup. Relay logs have the same format as
binary log files.
The binary log is discussed further in section 5.9.4 The Binary Log.
mysqlbinlog supports the following options:
--help, -?
--database=db_name, -d db_name
--force-read, -f
mysqlbinlog reads a binary log event that
it does not recognize, it prints a warning, ignores the event, and continues.
Without this option, mysqlbinlog stops if it reads such an event.
--host=host_name, -h host_name
--local-load=path, -l path
LOAD DATA INFILE in the specified
directory.
--offset=N, -o N
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--position=N, -j N
--start-position instead (starting from MySQL 4.1.4).
--protocol={TCP | SOCKET | PIPE | MEMORY}
--read-from-remote-server, -R
--host, --password, --port,
--protocol,
--socket, and --user.
--result-file=name, -r name
--short-form, -s
--socket=path, -S path
--start-datetime=datetime
datetime argument. The datetime value is
relative to the local time zone on the machine where you run
mysqlbinlog. The value should be in a format accepted for the
DATETIME or TIMESTAMP data types. For example:
shell> mysqlbinlog --start-datetime="2004-12-25 11:25:56" binlog.000003This option is available as of MySQL 4.1.4. It is useful for point-in-time recovery.
--stop-datetime=datetime
datetime argument. See the description of the
--start-datetime option for information about the datetime
value. This option is available as of MySQL 4.1.4. It is useful for
point-in-time recovery.
--start-position=N
N argument. Available as of MySQL 4.1.4 (previously named
--position).
--stop-position=N
N argument. Available as of MySQL 4.1.4.
--to-last-log, -t
--read-from-remote-server. Available as of MySQL 4.1.2.
--disable-log-bin, -D
--to-last-log option and are sending the output to the same
MySQL server. This option also is useful when restoring after a crash
to avoid duplication of the statements you have logged. Note:
This option requires that you have the SUPER privilege. Available
as of MySQL 4.1.8.
--user=user_name, -u user_name
--version, -V
You can also set the following variable by using --var_name=value
options:
open_files_limit
You can pipe the output of mysqlbinlog into a mysql client to
execute the statements contained in the binary log. This is used to recover
from a crash when you have an old backup (see section 5.7.1 Database Backups):
shell> mysqlbinlog hostname-bin.000001 | mysql
Or:
shell> mysqlbinlog hostname-bin.[0-9]* | mysql
You can also redirect the output of mysqlbinlog to a text file
instead, if you need to modify the statement log first (for example, to
remove statements that you don't want to execute for some reason). After
editing the file, execute the statements that it contains by using it as
input to the mysql program.
mysqlbinlog has the --position option, which prints only
those statements with an offset in the binary log greater than or equal to
a given position (the given position must match the start of one event). It
also has options to stop or start when it sees an event of a given date and
time. This enables you to perform point-in-time recovery using the
--stop-datetime option (to be able to say, for example, "roll forward
my databases to how they were today at 10:30 AM").
If you have more than one binary log to execute on the MySQL server, the safe method is to process them all using a single connection to the server. Here is an example that demonstrates what may be unsafe:
shell> mysqlbinlog hostname-bin.000001 | mysql # DANGER!! shell> mysqlbinlog hostname-bin.000002 | mysql # DANGER!!
Processing binary logs this way using different connections to the server
causes problems if the first log file contains a CREATE TEMPORARY
TABLE statement and the second log contains a statement that uses the
temporary table. When the first mysql process terminates, the server
drops the temporary table. When the second mysql process attempts
to use the table, the server reports ``unknown table.''
To avoid problems like this, use a single connection to execute the contents of all binary logs that you want to process. Here is one way to do that:
shell> mysqlbinlog hostname-bin.000001 hostname-bin.000002 | mysql
Another approach is to do this:
shell> mysqlbinlog hostname-bin.000001 > /tmp/statements.sql shell> mysqlbinlog hostname-bin.000002 >> /tmp/statements.sql shell> mysql -e "source /tmp/statements.sql"
In MySQL 3.23, the binary log did not contain the data to load for
LOAD DATA INFILE statements. To execute such a statement from a
binary log file, the original data file was needed. Starting from MySQL
4.0.14, the binary log does contain the data, so mysqlbinlog can
produce output that reproduces the LOAD DATA INFILE operation without
the original data file. mysqlbinlog copies the data to a temporary
file and writes a LOAD DATA LOCAL INFILE statement that refers to the
file. The default location of the directory where these files are written
is system-specific. To specify a directory explicitly, use the
--local-load option.
Because mysqlbinlog converts LOAD DATA INFILE statements to
LOAD DATA LOCAL INFILE statements (that is, it adds LOCAL),
both the client and the server that you use to process the statements must be
configured to allow LOCAL capability.
See section 5.4.4 Security Issues with LOAD DATA LOCAL.
Warning: The temporary files created for LOAD DATA LOCAL
statements are not automatically deleted
because they are needed until you actually execute those statements. You
should delete the temporary files yourself after you no longer need the
statement log. The files can be found in the temporary file directory and
have names like `original_file_name-#-#'.
In the future, we will fix this problem by allowing mysqlbinlog
to connect directly to a mysqld server. Then it is possible
to safely remove the log files automatically as soon as the LOAD DATA
INFILE statements have been executed.
Before MySQL 4.1, mysqlbinlog could not prepare output suitable for
mysql if the binary log contained interlaced statements originating
from different clients that used temporary tables of the same name. This is
fixed in MySQL 4.1. However, the problem still existed for LOAD DATA
INFILE statements until it was fixed in MySQL 4.1.8.
mysqlcc, the MySQL Control Center
mysqlcc, the MySQL Control Center, is a platform-independent client that
provides a graphical user interface (GUI) to the MySQL database server.
It supports interactive use, including syntax highlighting and tab completion.
It provides database and table management, and allows server administration.
mysqlcc is deprecated and it is recommended that users choose the new
MySQL Administrator and MySQL Query Browser, found at http://dev.mysql.com/downloads/.
Currently, mysqlcc runs on Windows and Linux platforms.
Invoke mysqlcc by double-clicking its icon in a graphical environment.
From the command line, invoke it like this:
shell> mysqlcc [options]
mysqlcc supports the following options:
--help, -?
--blocking_queries, -b
--compress, -C
--connection_name=name, -c name
--server.
--database=db_name, -d db_name
--history_size=#, -H #
--host=host_name, -h host_name
--local-infile[={0|1}]
LOCAL capability for LOAD DATA INFILE.
With no value, the option enables LOCAL. It may be given as
--local-infile=0 or --local-infile=1 to explicitly disable
or enable LOCAL. Enabling LOCAL has no effect if the server
does not also support it.
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--plugins_path=name, -g name
--port=port_num, -P port_num
--query, -q
--register, -r
--server=name, -s name
--socket=path, -S path
--syntax, -y
--syntax_file=name, -Y name
--translations_path=name, -T name
--user=user_name, -u user_name
--version, -V
You can also set the following variables by using --var_name=value
options:
connect_timeout
max_allowed_packet
max_join_size
net_buffer_length
select_limit
SELECT statements.
(Default value is 1,000.)
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
mysqlcheck Table Maintenance and Repair Program
The mysqlcheck client checks and repairs MyISAM tables. It
can also optimize and analyze tables. mysqlcheck is available as of
MySQL 3.23.38.
mysqlcheck is similar in function to myisamchk, but works
differently. The main operational difference is that mysqlcheck must
be used when the mysqld server is running, whereas myisamchk
should be used when it is not. The benefit of using mysqlcheck is
that you do not have to stop the server to check or repair your tables.
mysqlcheck uses the SQL statements CHECK TABLE, REPAIR
TABLE, ANALYZE TABLE, and OPTIMIZE TABLE in a convenient way
for the user. It determines which statements to use for the operation you want
to perform, then sends the statements to the server to be executed.
There are three general ways to invoke mysqlcheck:
shell> mysqlcheck [options] db_name [tables] shell> mysqlcheck [options] --databases DB1 [DB2 DB3...] shell> mysqlcheck [options] --all-databases
If you don't name any tables or use the --databases or
--all-databases option, entire databases are checked.
mysqlcheck has a special feature compared to the other clients. The
default behavior of checking tables (--check) can be changed by renaming
the binary. If you want to have a tool that repairs tables by default, you
should just make a copy of mysqlcheck named mysqlrepair, or make
a symbolic link to mysqlcheck named mysqlrepair. If you invoke
mysqlrepair, it repairs tables on command.
The following names can be used to change mysqlcheck default behavior:
mysqlrepair | The default option is --repair
|
mysqlanalyze | The default option is --analyze
|
mysqloptimize | The default option is --optimize
|
mysqlcheck supports the following options:
--help, -?
--all-databases, -A
--databases option and naming all the databases on the command line.
--all-in-1, -1
--analyze, -a
--auto-repair
--character-sets-dir=path
--check, -c
--check-only-changed, -C
--compress
--databases, -B
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
--default-character-set=charset
--extended, -e
--fast, -F
--force, -f
--host=host_name, -h host_name
--medium-check, -m
--extended operation.
This finds only 99.99% of all errors, which should be good enough in most cases.
--optimize, -o
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--protocol={TCP | SOCKET | PIPE | MEMORY}
--quick, -q
--repair, -r
--silent, -s
--socket=path, -S path
--tables
--databases or -B option. All arguments
following the option are regarded as table names.
--user=user_name, -u user_name
--verbose, -v
--version, -V
mysqldump Database Backup Program
The mysqldump client can be used
to dump a database or a collection of databases for backup or for
transferring the data to another SQL server (not necessarily a MySQL
server). The dump contains SQL statements to create the table
and/or populate the table.
If you are doing a backup on the server, and your tables all are
MyISAM tables, you could consider using
the mysqlhotcopy instead (faster backup, faster
restore). See section 8.9 The mysqlhotcopy Database Backup Program.
There are three general ways to invoke mysqldump:
shell> mysqldump [options] db_name [tables] shell> mysqldump [options] --databases DB1 [DB2 DB3...] shell> mysqldump [options] --all-databases
If you don't name any tables or use the --databases or
--all-databases option, entire databases are dumped.
To get a list of the options your version of mysqldump supports,
execute mysqldump --help.
If you run mysqldump without the --quick or
--opt option, mysqldump loads the whole result set into
memory before dumping the result. This probably is a problem if
you are dumping a big database. As of MySQL 4.1, --opt is on by
default, but can be disabled with --skip-opt.
If you are using a recent copy of the mysqldump program
to generate a dump to be reloaded into a very old MySQL
server, you should not use the --opt or -e options.
Before MySQL 4.1.2,
out-of-range numeric values such as -inf and inf, as well
as NaN (not-a-number) values are dumped by mysqldump as NULL.
You can see this using the following sample table:
mysql> CREATE TABLE t (f DOUBLE); mysql> INSERT INTO t VALUES(1e+111111111111111111111); mysql> INSERT INTO t VALUES(-1e111111111111111111111); mysql> SELECT f FROM t; +------+ | f | +------+ | inf | | -inf | +------+
For this table, mysqldump produces the following data output:
-- -- Dumping data for table `t` -- INSERT INTO t VALUES (NULL); INSERT INTO t VALUES (NULL);
The significance of this behavior is that if you dump and restore the
table, the new table has contents that differ from the original contents.
This problem is fixed as of MySQL 4.1.2; you cannot insert inf in the
table, so this mysqldump behavior is only relevant when you deal
with old servers.
mysqldump supports the following options:
--help, -?
--add-drop-table
DROP TABLE statement before each CREATE TABLE statement.
--add-locks
LOCK TABLES and UNLOCK TABLES
statements. This results in faster inserts when the dump file is reloaded.
See section 7.2.14 Speed of INSERT Statements.
--all-databases, -A
--databases option and naming all the databases on the command line.
--allow-keywords
--comments[={0|1}]
0, suppresses additional information in the dump file such
as program version, server version, and host. --skip-comments has the
same effect as --comments=0. The default value is 1 to not
suppress the extra information. New in MySQL 4.0.17.
--compact
--skip-add-drop-table, --no-set-names,
--skip-disable-keys, and --skip-add-locks options. New in
MySQL 4.1.2.
--compatible=name
name can be
ansi,
mysql323,
mysql40,
postgresql,
oracle,
mssql,
db2,
maxdb,
no_key_options,
no_table_options,
or
no_field_options.
To use several values, separate them by commas.
These values have the same meaning as the corresponding options for setting
the server SQL mode.
See section 5.2.2 The Server SQL Mode.
This option requires a server version of 4.1.0 or higher.
With older servers, it does nothing.
--complete-insert, -c
INSERT statements that include column names.
--compress, -C
--create-options
CREATE TABLE statements.
Before MySQL 4.1.2, use --all instead.
--databases, -B
mysqldump treats the first name
argument on the command line as a database name and following names as table
names. With this option, it treats all name arguments as database names.
CREATE DATABASE IF NOT EXISTS db_name and USE
db_name statements are included in the output before each new
database.
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
--default-character-set=charset
mysqldump from MySQL 4.1.2 or later
uses utf8, and earlier versions use latin1.
--delayed-insert
INSERT DELAYED statements.
--delete-master-logs
--first-slave before MySQL 4.1.8
and enables --master-data thereafter.
It was added in MySQL 3.23.57 (for MySQL 3.23) and MySQL 4.0.13 (for MySQL
4.0).
--disable-keys, -K
INSERT statements with
/*!40000 ALTER TABLE tbl_name DISABLE KEYS */; and
/*!40000 ALTER TABLE tbl_name ENABLE KEYS */; statements.
This makes loading the dump file into a MySQL 4.0 server faster because the
indexes are created after all rows are inserted.
This option is effective only for MyISAM tables.
--extended-insert, -e
INSERT syntax that include several VALUES lists.
This results in a smaller dump file and speeds up inserts when the file is
reloaded.
--fields-terminated-by=...
--fields-enclosed-by=...
--fields-optionally-enclosed-by=...
--fields-escaped-by=...
--lines-terminated-by=...
-T option and have the same
meaning as the corresponding clauses for LOAD DATA INFILE.
See section 13.1.5 LOAD DATA INFILE Syntax.
--first-slave, -x
--lock-all-tables in MySQL 4.1.8.
--flush-logs, -F
RELOAD privilege. Note that if you
use this option in combination with the --all-databases (or
-A) option, the logs are flushed for each database dumped.
The exception is when using --lock-all-tables
or --master-data:
In this case, the logs are flushed only once, corresponding to the moment
that all tables are locked. If you want your dump and the log flush to
happen at exactly the same moment, you should use --flush-logs
together with either --lock-all-tables or --master-data.
--force, -f
--host=host_name, -h host_name
localhost.
--hex-blob
'abc' becomes 0x616263). The affected columns are BINARY,
VARBINARY, and BLOB in MySQL 4.1 and up, and CHAR
BINARY, VARCHAR BINARY, and BLOB in MySQL 4.0. This option
was added in MySQL 4.0.23 and 4.1.8.
--lock-all-tables, -x
--single-transaction and --lock-tables. Added in
MySQL 4.1.8.
--lock-tables, -l
READ LOCAL to allow concurrent inserts in the case of MyISAM
tables. For InnoDB tables, --single-transaction is a much better
option, because it does not need to lock the tables at all.
Please note that when dumping multiple databases, --lock-tables locks
tables for each database separately. So, this option does not guarantee
that the tables in the dump file are logically consistent between
databases. Tables in different databases may be dumped in completely
different states.
--master-data[=value]
RELOAD privilege. If the option
value is equal to 1, the position and filename are written to the dump
output in the form of a CHANGE MASTER statement that makes a
slave server start from the correct position in the master's binary logs if
you use this SQL dump of the master to set up a slave. If the option value
is equal to 2, the CHANGE MASTER statement is written as an SQL
comment. This is the default action if value is omitted. value
may be given as of MySQL 4.1.8; before that, do not specify an option value.
The --master-data option turns on --lock-all-tables, unless
--single-transaction also is specified (in which case, a
global read lock is only acquired a short time at the beginning of the
dump. See also the description for
--single-transaction. In all cases,
any action on logs happens at the exact moment of the dump.
This option automatically turns off --lock-tables.
--no-create-db, -n
CREATE DATABASE /*!32312 IF NOT EXISTS*/
db_name statements that are otherwise included in the output if the
--databases or --all-databases option is given.
--no-create-info, -t
CREATE TABLE statements that re-create each dumped table.
--no-data, -d
--opt
--add-drop-table
--add-locks --create-options --disable-keys --extended-insert
--lock-tables --quick --set-charset. It should
give you a fast dump operation and produce a dump file that can be reloaded
into a MySQL server quickly. As of MySQL 4.1, --opt is on by default,
but can be disabled with --skip-opt. To disable only certain of the
options enabled by --opt, use their --skip forms; for example,
--skip-add-drop-table or --skip-quick.
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--protocol={TCP | SOCKET | PIPE | MEMORY}
--quick, -q
mysqldump to retrieve rows for a table from
the server a row at a time rather than retrieving the entire row set
and buffering it in memory before writing it out.
--quote-names, -Q
ANSI_QUOTES option, names are
quoted within `"' characters.
As of MySQL 4.1.1, --quote-names is on by default,
but can be disabled with --skip-quote-names.
--result-file=file, -r file
--set-charset
SET NAMES default_character_set to the output. This option
is enabled by default. To suppress the SET NAMES statement, use
--skip-set-charset. This option was added in MySQL 4.1.2.
--single-transaction
BEGIN SQL statement before dumping data from
the server. It is useful only with InnoDB tables, because then it
dumps the consistent state of the database at the time when
BEGIN was issued without blocking any applications.
When using this option, you should keep in mind that only InnoDB
tables are dumped in a consistent state. For example, any MyISAM or
HEAP tables dumped while using this option may still change
state.
The --single-transaction option was added in MySQL 4.0.2.
This option is mutually exclusive with the --lock-tables option,
because LOCK TABLES causes any pending transactions to be committed
implicitly.
To dump big tables, you should combine this option with --quick.
--socket=path, -S path
localhost (which is the
default host).
--skip-comments
--comments option.
--tab=path, -T path
mysqldump
creates a `tbl_name.sql' file that contains the CREATE TABLE
statement that creates the table, and a `tbl_name.txt' file that
contains its data. The option value is the directory in which to write the
files.
By default, the `.txt' data files are formatted using tab characters
between column values and a newline at the end of each line. The format can
be specified explicitly using the --fields-xxx and
--lines--xxx options.
Note: This option should be used only when mysqldump is
run on the same machine as the mysqld server. You must have the
FILE privilege, and the server must have permission to write files in
the directory that you specify.
--tables
--databases or -B option. All arguments
following the option are regarded as table names.
--user=user_name, -u user_name
--verbose, -v
--version, -V
--where='where-condition', -w 'where-condition'
WHERE condition. Note that
quotes around the condition are mandatory if it contains spaces or
characters that are special to your command interpreter.
Examples:
"--where=user='jimf'" "-wuserid>1" "-wuserid<1"
--xml, -X
You can also set the following variables by using --var_name=value
options:
max_allowed_packet
net_buffer_length
--extended-insert or --opt), mysqldump creates
rows up to net_buffer_length length. If you increase this
variable, you should also ensure that the net_buffer_length
variable in the MySQL server is at least this large.
It is also possible to set variables by using
--set-variable=var_name=value or -O var_name=value
syntax. However, this syntax is deprecated as of MySQL 4.0.
The most common use of mysqldump is probably for making a backup of
an entire database:
shell> mysqldump --opt db_name > backup-file.sql
You can read the dump file back into the server like this:
shell> mysql db_name < backup-file.sql
Or like this:
shell> mysql -e "source /path-to-backup/backup-file.sql" db_name
mysqldump is also very useful for populating databases by copying
data from one MySQL server to another:
shell> mysqldump --opt db_name | mysql --host=remote_host -C db_name
It is possible to dump several databases with one command:
shell> mysqldump --databases db_name1 [db_name2 ...] > my_databases.sql
If you want to dump all databases, use the --all-databases option:
shell> mysqldump --all-databases > all_databases.sql
If tables are stored in the InnoDB storage engine, mysqldump provides a
way of making an online backup of these (see command below). This backup just
needs to acquire a global read lock on all tables (using FLUSH TABLES
WITH READ LOCK) at the beginning of the dump. As soon as this lock has been
acquired, the binary log coordinates are read and lock is released. So if and
only if one long updating statement is running when the FLUSH... is
issued, the MySQL server may get stalled until that long statement finishes,
and then the dump becomes lock-free. So if the MySQL server receives only
short (in the sense of "short execution time") updating statements, even if
there are plenty of them, the initial lock period should not be noticeable.
shell> mysqldump --all-databases --single-transaction > all_databases.sql
For point-in-time recovery (also known as "roll-forward", when you need to restore an old backup and replay the changes which happened since that backup), it is often useful to rotate the binary log (see section 5.9.4 The Binary Log) or at least know the binary log coordinates to which the dump corresponds:
shell> mysqldump --all-databases --master-data=2 > all_databases.sql or shell> mysqldump --all-databases --flush-logs --master-data=2 > all_databases.sql
The simultaneous use of --master-data and --single-transaction
works as of MySQL 4.1.8. It provides a convenient way to make an online backup
suitable for point-in-time recovery, if tables are stored in the
InnoDB storage engine.
For more information on making backups, see section 5.7.1 Database Backups.
mysqlhotcopy Database Backup Program
mysqlhotcopy is a Perl script that was originally written and
contributed by Tim Bunce. It uses LOCK TABLES,
FLUSH TABLES, and cp or scp to quickly make a backup of
a database. It's the fastest way to make a backup of the database or single
tables, but it can be run only on the same machine where the database
directories are located. mysqlhotcopy works only for backing up
MyISAM and ISAM tables.
It runs on Unix, and as of MySQL 4.0.18 also on NetWare.
shell> mysqlhotcopy db_name [/path/to/new_directory]
shell> mysqlhotcopy db_name_1 ... db_name_n /path/to/new_directory
Back up tables in the given database that match a regular expression:
shell> mysqlhotcopy db_name./regex/
The regular expression for the table name can be negated by prefixing it with a tilde (`~'):
shell> mysqlhotcopy db_name./~regex/
mysqlhotcopy supports the following options:
--help, -?
--allowold
_old
suffix).
--checkpoint=db_name.tbl_name
--debug
--dryrun, -n
--flushlog
--keepold
--method=#
cp or scp).
--noindices
myisamchk -rq
for MyISAM tables or isamchk -rq for ISAM tables.
--password=password, -ppassword
--port=port_num, -P port_num
--quiet, -q
--regexp=expr
--socket=path, -S path
--suffix=str
--tmpdir=path
--user=user_name, -u user_name
mysqlhotcopy reads the [client] and [mysqlhotcopy]
option groups from option files.
To execute mysqlhotcopy, you must have access to the files
for the tables that you are backing up, the SELECT privilege
for those tables, and the RELOAD privilege (to be able to
execute FLUSH TABLES).
Use perldoc for additional mysqlhotcopy documentation:
shell> perldoc mysqlhotcopy
mysqlimport Data Import Program
The mysqlimport client provides a command-line interface to the
LOAD DATA INFILE SQL statement. Most options to mysqlimport
correspond directly to clauses of LOAD DATA INFILE.
See section 13.1.5 LOAD DATA INFILE Syntax.
Invoke mysqlimport like this:
shell> mysqlimport [options] db_name textfile1 [textfile2 ...]
For each text file named on the command line, mysqlimport strips any
extension from the filename and uses the result to determine the name of the
table into which to import the file's contents. For example, files named
`patient.txt', `patient.text', and `patient' all would be
imported into a table named patient.
mysqlimport supports the following options:
--help, -?
--columns=column_list, -c column_list
--compress, -C
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
--delete, -D
--fields-terminated-by=...
--fields-enclosed-by=...
--fields-optionally-enclosed-by=...
--fields-escaped-by=...
--lines-terminated-by=...
LOAD DATA INFILE. See section 13.1.5 LOAD DATA INFILE Syntax.
--force, -f
--force,
mysqlimport exits if a table doesn't exist.
--host=host_name, -h host_name
localhost.
--ignore, -i
--replace option.
--ignore-lines=n
--local, -L
--lock-tables, -l
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--protocol={TCP | SOCKET | PIPE | MEMORY}
--replace, -r
--replace and --ignore options control handling of input
records that duplicate existing records on unique key values. If you specify
--replace, new rows replace existing rows that have the same unique key
value. If you specify --ignore, input rows that duplicate an existing
row on a unique key value are skipped. If you don't specify either option, an
error occurs when a duplicate key value is found, and the rest of the text
file is ignored.
--silent, -s
--socket=path, -S path
localhost (which is the
default host).
--user=user_name, -u user_name
--verbose, -v
--version, -V
Here is a sample session that demonstrates use of mysqlimport:
shell> mysql -e 'CREATE TABLE imptest(id INT, n VARCHAR(30))' test shell> ed a 100 Max Sydow 101 Count Dracula . w imptest.txt 32 q shell> od -c imptest.txt 0000000 1 0 0 \t M a x S y d o w \n 1 0 0000020 1 \t C o u n t D r a c u l a \n 0000040 shell> mysqlimport --local test imptest.txt test.imptest: Records: 2 Deleted: 0 Skipped: 0 Warnings: 0 shell> mysql -e 'SELECT * FROM imptest' test +------+---------------+ | id | n | +------+---------------+ | 100 | Max Sydow | | 101 | Count Dracula | +------+---------------+
mysqlshow, Showing Databases, Tables, and Columns
The mysqlshow client can be used to quickly look at which databases
exist, their tables, and a table's columns or indexes.
mysqlshow provides a command-line interface to several SQL
SHOW statements. The same information can be obtained by using those
statements directly. For example, you can issue them from the mysql
client program.
See section 13.5.4 SHOW Syntax.
Invoke mysqlshow like this:
shell> mysqlshow [options] [db_name [tbl_name [col_name]]]
Note that in newer MySQL versions, you see only those database, tables, or columns for which you have some privileges.
If the last argument contains shell or SQL wildcard characters (`*',
`?', `%', or `_'), only those names that are matched by the
wildcard are shown. If a database name contains any underscores, those
should be escaped with a backslash (some Unix shells require two) in
order to get a list of the proper tables or columns. `*' and `?'
characters are converted into SQL `%' and `_' wildcard characters.
This might cause some confusion when you try to display the columns for a
table with a `_' in the name, because in this case mysqlshow
shows you only the table names that match the pattern. This is easily fixed
by adding an extra `%' last on the command line as a separate
argument.
mysqlshow supports the following options:
--help, -?
--character-sets-dir=path
--compress, -C
--debug[=debug_options], -# [debug_options]
'd:t:o,file_name'.
--default-character-set=charset
--host=host_name, -h host_name
--keys, -k
--password[=password], -p[password]
-p), you cannot have a space between the
option and the password. If you omit the password value following the
--password or -p option on the command line, you are
prompted for one.
--port=port_num, -P port_num
--protocol={TCP | SOCKET | PIPE | MEMORY}
--show-table-type
SHOW FULL TABLES.
New in MySQL 5.0.4.
--socket=path, -S path
localhost (which is the
default host).
--status, -i
--user=user_name, -u user_name
--verbose, -v
--version, -V
perror, Explaining Error CodesFor most system errors, MySQL displays, in addition to an internal text message, the system error code in one of the following styles:
message ... (errno: #) message ... (Errcode: #)
You can find out what the error code means by either examining the
documentation for your system or by using the perror utility.
perror prints a description for a system error code or for a storage
engine (table handler) error code.
Invoke perror like this:
shell> perror [options] errorcode ...
Example:
shell> perror 13 64 Error code 13: Permission denied Error code 64: Machine is not on the network
Note that the meaning of system error messages may be dependent on your operating system. A given error code may mean different things on different operating systems.
replace String-Replacement Utility
The replace utility program changes strings in place in files or on
the standard input. It uses a finite state machine to match longer strings
first. It can be used to swap strings. For example, the following command
swaps a and b in the given files, `file1' and `file2':
shell> replace a b b a -- file1 file2 ...
Use the -- option to indicate where the string-replacement list
ends and the filenames begin.
Any file named on the command line is modified in place, so you may want to make a copy of the original before converting it.
If no files are named on the command line, replace reads the standard
input and writes to the standard output. In this case, no -- option is
needed.
The replace program is used by msql2mysql.
See section 22.1.1 msql2mysql, Convert mSQL Programs for Use with MySQL.
replace supports the following options:
-?, -I
-# debug_options
debug_options string often is
'd:t:o,file_name'.
-s
-v
-V
This chapter discusses the rules for writing the following elements of SQL statements when using MySQL:
This section describes how to write literal values in MySQL. These include
strings, numbers, hexadecimal values, boolean values, and NULL. The section also
covers the various nuances and ``gotchas'' that
you may run into when dealing with these basic types in MySQL.
A string is a sequence of characters, surrounded by either single quote (`'') or double quote (`"') characters. Examples:
'a string' "another string"
If the server SQL mode has ANSI_QUOTES enabled, string literals can be
quoted only with single quotes. A string quoted with double quotes is
interpreted as an identifier.
As of MySQL 4.1.1, string literals may have an optional character set
introducer and COLLATE clause:
[_charset_name]'string' [COLLATE collation_name]
Examples:
SELECT _latin1'string'; SELECT _latin1'string' COLLATE latin1_danish_ci;
For more information about these forms of string syntax, see section 10.3.7 Character String Literal Character Set and Collation.
Within a string, certain sequences have special meaning. Each of these sequences begins with a backslash (`\'), known as the escape character. MySQL recognizes the following escape sequences:
These sequences are case sensitive. For example, `\b' is interpreted as a backspace, but `\B' is interpreted as `B'.
The `\%' and `\_' sequences are used to search for literal instances of `%' and `_' in pattern-matching contexts where they would otherwise be interpreted as wildcard characters. See section 12.3.1 String Comparison Functions. Note that if you use `\%' or `\_' in other contexts, they return the strings `\%' and `\_' and not `%' and `_'.
In all other escape sequences, backslash is ignored. That is, the escaped character is interpreted as if it was not escaped.
There are several ways to include quotes within a string:
The following SELECT statements demonstrate how quoting and
escaping work:
mysql> SELECT 'hello', '"hello"', '""hello""', 'hel''lo', '\'hello'; +-------+---------+-----------+--------+--------+ | hello | "hello" | ""hello"" | hel'lo | 'hello | +-------+---------+-----------+--------+--------+ mysql> SELECT "hello", "'hello'", "''hello''", "hel""lo", "\"hello"; +-------+---------+-----------+--------+--------+ | hello | 'hello' | ''hello'' | hel"lo | "hello | +-------+---------+-----------+--------+--------+ mysql> SELECT 'This\nIs\nFour\nLines'; +--------------------+ | This Is Four Lines | +--------------------+ mysql> SELECT 'disappearing\ backslash'; +------------------------+ | disappearing backslash | +------------------------+
If you want to insert binary data into a string column (such as a
BLOB), the following characters must be represented by escape
sequences:
NUL
| NUL byte (ASCII 0).
Represent this character by `\0' (a backslash followed by an ASCII `0' character).
|
\
| Backslash (ASCII 92). Represent this character by `\\'. |
'
| Single quote (ASCII 39). Represent this character by `\''. |
"
| Double quote (ASCII 34). Represent this character by `\"'. |
When writing application programs, any string that might contain any of these special characters must be properly escaped before the string is used as a data value in an SQL statement that is sent to the MySQL server. You can do this in two ways:
mysql_real_escape_string()
C API function to escape characters.
See section 22.2.3.47 mysql_real_escape_string().
The Perl DBI interface provides a
quote method to convert special characters to the proper escape
sequences. See section 22.4 MySQL Perl API.
Integers are represented as a sequence of digits. Floats use `.' as a decimal separator. Either type of number may be preceded by `-' to indicate a negative value.
Examples of valid integers:
1221 0 -32
Examples of valid floating-point numbers:
294.42 -32032.6809e+10 148.00
An integer may be used in a floating-point context; it is interpreted as the equivalent floating-point number.
MySQL supports hexadecimal values. In numeric contexts, these act like integers (64-bit precision). In string contexts, these act like binary strings, where each pair of hex digits is converted to a character:
mysql> SELECT x'4D7953514C';
-> 'MySQL'
mysql> SELECT 0xa+0;
-> 10
mysql> SELECT 0x5061756c;
-> 'Paul'
In MySQL 4.1 (and in MySQL 4.0 when using the --new option), the default
type of a hexadecimal value is a string. If you want to ensure that
the value is treated as a number, you can use CAST(... AS UNSIGNED):
mysql> SELECT 0x41, CAST(0x41 AS UNSIGNED);
-> 'A', 65
The 0x syntax is based on ODBC. Hexadecimal strings are often used by
ODBC to supply values for BLOB columns.
The x'hexstring' syntax is new in 4.0 and is based on standard SQL.
Beginning with MySQL 4.0.1, you can convert a string or a number to a string
in hexadecimal format with the HEX() function:
mysql> SELECT HEX('cat');
-> '636174'
mysql> SELECT 0x636174;
-> 'cat'
Beginning with MySQL 4.1, the constant TRUE evaluates to 1 and
the constant FALSE evaluates to 0. The constant names can be
written in any lettercase.
mysql> SELECT TRUE, true, FALSE, false;
-> 1, 1, 0, 0
Beginning with MySQL 5.0.3, bit-field values can be written using
b'value' notation. value is a binary value written using
0s and 1s.
Bit-field notation is convenient for specifying values to be assigned to
BIT columns:
mysql> CREATE TABLE t (b BIT(8)); mysql> INSERT INTO t SET b = b'11111111'; mysql> INSERT INTO t SET b = b'1010'; +------+----------+----------+----------+ | b+0 | BIN(b+0) | OCT(b+0) | HEX(b+0) | +------+----------+----------+----------+ | 255 | 11111111 | 377 | FF | | 10 | 1010 | 12 | A | +------+----------+----------+----------+
NULL Values
The NULL value means ``no data.''
NULL can be written in any lettercase.
Be aware that the NULL value is different from values such
as 0 for numeric types or the empty string for string types.
See section A.5.3 Problems with NULL Values.
For text file import or export operations performed with LOAD DATA
INFILE or SELECT ... INTO OUTFILE, NULL is represented by
the \N sequence.
See section 13.1.5 LOAD DATA INFILE Syntax.
Database, table, index, column, and alias names are identifiers. This section describes the allowable syntax for identifiers in MySQL.
The following table describes the maximum length and allowable characters for each type of identifier.
| Identifier | Maximum Length (bytes) | Allowed Characters |
| Database | 64 | Any character that is allowed in a directory name, except `/', `\', or `.' |
| Table | 64 | Any character that is allowed in a filename, except `/', `\', or `.' |
| Column | 64 | All characters |
| Index | 64 | All characters |
| Alias | 255 | All characters |
In addition to the restrictions noted in the table, no identifier can contain ASCII 0 or a byte with a value of 255. Database, table, and column names should not end with space characters. Before MySQL 4.1, identifier quote characters should not be used in identifiers.
Beginning with MySQL 4.1, identifiers are stored using Unicode (UTF8).
This applies to identifiers in table definitions that stored in `.frm'
files and to identifiers stored in the grant tables in the mysql
database. Although Unicode identifiers can include multi-byte characters, note
that the maximum lengths shown in the table are byte counts. If an identifier
does contain multi-byte characters, the number of characters allowed in
the identifier is less than the value shown in the table.
An identifier may be quoted or unquoted. If an identifier is a reserved word or contains special characters, you must quote it whenever you refer to it. For a list of reserved words, see section 9.6 Treatment of Reserved Words in MySQL. Special characters are those outside the set of alphanumeric characters from the current character set, `_', and `$'.
The identifier quote character is the backtick (``'):
mysql> SELECT * FROM `select` WHERE `select`.id > 100;
If the server SQL mode includes the ANSI_QUOTES mode option,
it is also allowable to quote identifiers with double quotes:
mysql> CREATE TABLE "test" (col INT); ERROR 1064: You have an error in your SQL syntax. (...) mysql> SET sql_mode='ANSI_QUOTES'; mysql> CREATE TABLE "test" (col INT); Query OK, 0 rows affected (0.00 sec)
See section 5.2.2 The Server SQL Mode.
As of MySQL 4.1, identifier quote characters can be included within an
identifier if you quote the identifier. If the character to be included within
the identifier is the same as that used to quote the identifier itself,
double the character. The following statement creates a table named a`b
that contains a column named c"d:
mysql> CREATE TABLE `a``b` (`c"d` INT);
Identifier quoting was introduced in MySQL 3.23.6 to allow use of identifiers that are reserved words or that contain special characters. Before 3.23.6, you cannot use identifiers that require quotes, so the rules for legal identifiers are more restrictive:
--default-character-set option
to mysqld.
See section 5.8.1 The Character Set Used for Data and Sorting.
It is recommended that you do not use names like 1e, because
an expression like 1e+1 is ambiguous. It might be interpreted as the
expression 1e + 1 or as the number 1e+1, depending on context.
MySQL allows names that consist of a single identifier or multiple identifiers. The components of a multiple-part name should be separated by period (`.') characters. The initial parts of a multiple-part name act as qualifiers that affect the context within which the final identifier is interpreted.
In MySQL you can refer to a column using any of the following forms:
| Column Reference | Meaning |
| col_name | The column col_name from whichever table used in the query contains a column of that name. |
| tbl_name.col_name | The column col_name from table tbl_name of the default database. |
| db_name.tbl_name.col_name | The column col_name from table tbl_name of the database db_name. This syntax is unavailable before MySQL 3.22. |
If any components of a multiple-part name require quoting, quote them
individually rather than quoting the name as a whole. For example,
`my-table`.`my-column` is legal, whereas `my-table.my-column` is
not.
You need not specify a tbl_name or db_name.tbl_name prefix for
a column reference in a statement unless the reference would be ambiguous.
Suppose that tables t1 and t2 each contain a column
c, and you retrieve c in a SELECT statement that uses
both t1 and t2. In this case, c is ambiguous because it
is not unique among the tables used in the statement. You must qualify it
with a table name as t1.c or t2.c to indicate which table you
mean. Similarly, to retrieve from a table t in database db1
and from a table t in database db2 in the same statement,
you must refer to columns in those tables as db1.t.col_name
and db2.t.col_name.
The syntax .tbl_name means the table tbl_name in the current database. This syntax is accepted for ODBC compatibility because some ODBC programs prefix table names with a `.' character.
In MySQL, databases correspond to directories within the data directory. Tables within a database correspond to at least one file within the database directory (and possibly more, depending on the storage engine). Consequently, the case sensitivity of the underlying operating system determines the case sensitivity of database and table names. This means database and table names are not case sensitive in Windows, and case sensitive in most varieties of Unix. One notable exception is Mac OS X, which is Unix-based but uses a default filesystem type (HFS+) that is not case sensitive. However, Mac OS X also supports UFS volumes, which are case sensitive just as on any Unix. See section 1.5.4 MySQL Extensions to Standard SQL.
Note: Although database and table names are not case sensitive on
some platforms, you should not refer to a given database or table using
different
cases within the same query. The following query would not work because it
refers to a table both as my_table and as MY_TABLE:
mysql> SELECT * FROM my_table WHERE MY_TABLE.col=1;
Column names, index names, and column aliases are not case sensitive on any platform.
Table aliases are case sensitive before MySQL 4.1.1. The following
query would not work because it refers to the alias both as a and
as A:
mysql> SELECT col_name FROM tbl_name AS a
-> WHERE a.col_name = 1 OR A.col_name = 2;
If you have trouble remembering the allowable lettercase for database and table names, adopt a consistent convention, such as always creating databases and tables using lowercase names.
How table and database names are stored on disk and used in MySQL is defined by the
lower_case_table_names system variable, which you can set when
starting mysqld. lower_case_table_names can take one of
the following values:
| Value | Meaning |
0 | Table and database names are stored on disk using the lettercase specified in the CREATE TABLE or CREATE DATABASE statement. Name comparisons are case sensitive. This is the default on Unix systems. Note that if you force this to 0 with --lower-case-table-names=0 on a case-insensitive filesystem and access MyISAM tablenames using different lettercases, this may lead to index corruption.
|
1 | Table names are stored in lowercase on disk and name comparisons are not case sensitive. MySQL converts all table names to lowercase on storage and lookup. This behavior also applies to database names as of MySQL 4.0.2, and to table aliases as of 4.1.1. This value is the default on Windows and Mac OS X systems. |
2 | Table and database names are stored on disk using the lettercase specified in the CREATE TABLE or CREATE DATABASE statement, but MySQL converts them to lowercase on lookup. Name comparisons are not case sensitive. Note: This works only on filesystems that are not case sensitive! InnoDB table names are stored in lowercase, as for lower_case_table_names=1. Setting lower_case_table_names to 2 can be done as of MySQL 4.0.18.
|
If you are using MySQL on only one platform, you don't normally have to
change the lower_case_table_names variable. However, you may
encounter difficulties if you want to transfer tables between platforms
that differ in filesystem case sensitivity. For example, on Unix, you
can have two different tables named my_table and MY_TABLE,
but on Windows those names are considered the same. To avoid data
transfer problems stemming from database or table name lettercase, you
have two options:
lower_case_table_names=1 on all systems. The main disadvantage
with this is that when you use SHOW TABLES or SHOW DATABASES,
you don't see the names in their original lettercase.
lower_case_table_names=0 on Unix and lower_case_table_names=2
on Windows. This preserves the lettercase of database and table names.
The disadvantage of this is that you must ensure that your queries always refer
to your database and table names with the correct lettercase on Windows. If
you transfer your queries to Unix, where lettercase is significant, they do
not work if the lettercase is incorrect.
Note that before setting lower_case_table_names to 1 on Unix, you must
first convert your old database and table names to lowercase before restarting
mysqld.
MySQL supports user variables as of version 3.23.6. You can store a value in a user variable and refer to it later, which allows you to pass values from one statement to another. User variables are connection-specific. That is, a variable defined by one client cannot be seen or used by other clients. All variables for a client connection are automatically freed when the client exits.
User variables are written as @var_name, where the variable name
var_name may consist of alphanumeric characters from the current
character set, `.', `_', and `$'. The default character set
is ISO-8859-1 (Latin1). This may be changed with the
--default-character-set option to mysqld. See section 5.8.1 The Character Set Used for Data and Sorting. User variable names are not case sensitive beginning with MySQL 5.0.
Before that, they are case sensitive.
One way to set a user variable is by issuing a SET statement:
SET @var_name = expr [, @var_name = expr] ...
For SET, either = or := can be used as the assignment
operator. The expr assigned to each variable can evaluate
to an integer, real, string, or NULL value.
You can also assign a value to a user variable in statements other than
SET. In this case, the assignment operator must be := and not
= because = is treated as a comparison operator
in non-SET statements:
mysql> SET @t1=0, @t2=0, @t3=0; mysql> SELECT @t1:=(@t2:=1)+@t3:=4,@t1,@t2,@t3; +----------------------+------+------+------+ | @t1:=(@t2:=1)+@t3:=4 | @t1 | @t2 | @t3 | +----------------------+------+------+------+ | 5 | 5 | 1 | 4 | +----------------------+------+------+------+
User variables may be used where expressions are allowed. This
does not currently include contexts that explicitly require a number, such
as in the LIMIT clause of a SELECT statement, or the
IGNORE number LINES clause of a LOAD DATA statement.
If you refer to a variable that has not been initialized, its value
is NULL.
Beginning with MySQL 4.1.1, if a user variable is assigned a string value, it also has the same character set and collation as the string. The coercibility of user variables is ``implicit'' as of MySQL 4.1.11 and 5.0.3. (This is the same coercibility as table column values.)
Note: In a SELECT statement, each expression is evaluated
only when sent to the client. This means that in a HAVING,
GROUP BY, or ORDER BY clause, you cannot refer to an expression
that involves variables that are set in the SELECT list. For example,
the following statement does not work as expected:
mysql> SELECT (@aa:=id) AS a, (@aa+3) AS b FROM tbl_name HAVING b=5;
The reference to b in the HAVING clause refers to an alias
for an expression in the SELECT list that uses @aa. This
does not work as expected: @aa does not contain the value of the
current row, but the value of id from the previous selected row.
The general rule is to never assign and use the same variable in the same statement.
Another issue with setting a variable and using it in the same statement is that the default result type of a variable is based on the type of the variable at the start of the statement. The following example illustrates this:
mysql> SET @a='test'; mysql> SELECT @a,(@a:=20) FROM tbl_name;
For this SELECT statement, MySQL reports to the client that
column one is a string and converts all accesses of @a to strings,
even though @a is set to a number for the second row. After the
SELECT statement executes, @a is regarded as a
number for the next statement.
To avoid problems with this behavior, either do not set and use the same
variable within a single statement, or else set the variable to 0,
0.0, or '' to define its type before you use it.
An unassigned variable has a value of NULL with a type of string.
Starting from MySQL 4.0.3, we provide better access to a lot of system and connection variables. Many variables can be changed dynamically while the server is running. This allows you to modify server operation without having to stop and restart it.
The mysqld server maintains two kinds of variables.
Global variables affect the overall operation of the server.
Session variables affect its operation for individual client connections.
When the server starts, it initializes all global variables to their default
values. These defaults may be changed by options specified in option files
or on the command line. After the server starts, those global variables
that are dynamic can be changed by connecting to the server and issuing
a SET GLOBAL var_name statement. To change a global variable,
you must have the SUPER privilege.
The server also maintains a set of session variables for each client
that connects. The client's session variables are initialized at connect
time using the current values of the corresponding global variables. For
those session variables that are dynamic, the client can change them
by issuing a SET SESSION var_name statement. Setting a session
variable requires no special privilege, but a client can change only its
own session variables, not those of any other client.
A change to a global variable is visible to any client that accesses that
global variable. However, it affects the corresponding session variable
that is initialized from the global variable only for clients that connect
after the change. It does not affect the session variable for any client
that is currently connected (not even that of the client that issues the
SET GLOBAL statement).
Global or session variables may be set or retrieved using several syntax
forms. The following examples use sort_buffer_size as a sample variable
name.
To set the value of a GLOBAL variable, use one
of the following syntaxes:
mysql> SET GLOBAL sort_buffer_size=value; mysql> SET @@global.sort_buffer_size=value;
To set the value of a SESSION variable, use one of the
following syntaxes:
mysql> SET SESSION sort_buffer_size=value; mysql> SET @@session.sort_buffer_size=value; mysql> SET sort_buffer_size=value;
LOCAL is a synonym for SESSION.
If you don't specify GLOBAL, SESSION, or LOCAL when
setting a variable, SESSION is the default.
See section 13.5.3 SET Syntax.
To retrieve the value of a GLOBAL variable, use one of the
following statements:
mysql> SELECT @@global.sort_buffer_size; mysql> SHOW GLOBAL VARIABLES like 'sort_buffer_size';
To retrieve the value of a SESSION variable, use one of the
following statements:
mysql> SELECT @@sort_buffer_size; mysql> SELECT @@session.sort_buffer_size; mysql> SHOW SESSION VARIABLES like 'sort_buffer_size';
Here, too, LOCAL is a synonym for SESSION.
When you retrieve a variable with SELECT @@var_name (that is, you
do not specify global., session., or local., MySQL returns
the SESSION value if it exists and the GLOBAL value otherwise.
For SHOW VARIABLES, if you do not specify GLOBAL,
SESSION, or LOCAL, MySQL returns the SESSION value.
The reason for requiring the GLOBAL keyword when setting
GLOBAL-only variables but not when retrieving them is to prevent
problems in the future. If we remove a SESSION
variable with the same name as a GLOBAL variable, a client with the
SUPER privilege might accidentally change the GLOBAL variable
rather than just the SESSION variable for its own connection. If we
add a SESSION variable with the same name as a GLOBAL
variable, a client that intends to change the GLOBAL variable might
find only its own SESSION variable changed.
Further information about system startup options and system
variables can be found in section 5.2.1 mysqld Command-Line Options and
section 5.2.3 Server System Variables.
A list of the variables that can be set at runtime is given in
section 5.2.3.1 Dynamic System Variables.
Structured system variables are supported beginning with MySQL 4.1.1. A structured variable differs from a regular system variable in two respects:
Currently, MySQL supports one structured variable type. It specifies parameters that govern the operation of key caches. A key cache structured variable has these components:
key_buffer_size
key_cache_block_size
key_cache_division_limit
key_cache_age_threshold
The purpose of this section is to describe the syntax for referring to
structured variables. Key cache variables are used for syntax examples,
but specific details about how key caches operate are found elsewhere, in
section 7.4.6 The MyISAM Key Cache.
To refer to a component of a structured variable instance, you can use a
compound name in instance_name.component_name format. Examples:
hot_cache.key_buffer_size hot_cache.key_cache_block_size cold_cache.key_cache_block_size
For each structured system variable, an instance with the name of
default is always predefined. If you refer to a component of a
structured variable without any instance name, the default instance
is used. Thus, default.key_buffer_size and key_buffer_size
both refer to the same system variable.
The naming rules for structured variable instances and components are as follows:
default,
so default is not unique across variable types.
hot-cache is not legal, but `hot-cache` is.
global, session, and local are not legal instance
names. This avoids a conflict with notation such as @@global.var_name
for referring to non-structured system variables.
At the moment, the first two rules have no possibility of being violated because the only structured variable type is the one for key caches. These rules assume greater significance if some other type of structured variable is created in the future.
With one exception, it is allowable to refer to structured variable components using compound names in any context where simple variable names can occur. For example, you can assign a value to a structured variable using a command-line option:
shell> mysqld --hot_cache.key_buffer_size=64K
In an option file, do this:
[mysqld] hot_cache.key_buffer_size=64K
If you start the server with such an option, it creates a key cache
named hot_cache with a size of 64KB in addition to the default
key cache that has a default size of 8MB.
Suppose that you start the server as follows:
shell> mysqld --key_buffer_size=256K \
--extra_cache.key_buffer_size=128K \
--extra_cache.key_cache_block_size=2048
In this case, the server sets the size of the default key cache to 256KB.
(You could also have written --default.key_buffer_size=256K.)
In addition, the server creates a second key cache named extra_cache
that has a size of 128KB, with the size of block buffers for caching
table index blocks set to 2048 bytes.
The following example starts the server with three different key caches having sizes in a 3:1:1 ratio:
shell> mysqld --key_buffer_size=6M \
--hot_cache.key_buffer_size=2M \
--cold_cache.key_buffer_size=2M
Structured variable values may be set and retrieved at runtime as well.
For example, to set a key cache named hot_cache to a size of 10MB,
use either of these statements:
mysql> SET GLOBAL hot_cache.key_buffer_size = 10*1024*1024; mysql> SET @@global.hot_cache.key_buffer_size = 10*1024*1024;
To retrieve the cache size, do this:
mysql> SELECT @@global.hot_cache.key_buffer_size;
However, the following statement does not work. The variable is not
interpreted as a compound name, but as a simple string for a LIKE
pattern-matching operation:
mysql> SHOW GLOBAL VARIABLES LIKE 'hot_cache.key_buffer_size';
This is the exception to being able to use structured variable names anywhere a simple variable name may occur.
The MySQL server supports three comment styles:
The following example demonstrates all three comment styles:
mysql> SELECT 1+1; # This comment continues to the end of line mysql> SELECT 1+1; -- This comment continues to the end of line mysql> SELECT 1 /* this is an in-line comment */ + 1; mysql> SELECT 1+ /* this is a multiple-line comment */ 1;
The comment syntax just described applies to how the mysqld server
parses SQL statements. The mysql client program also performs some
parsing of statements before sending them to the server. (For example, it
does this to determine statement boundaries within a multiple-statement input
line.) However, there are some limitations on the way that mysql
parses /* ... */ comments:
mysql interactively, you can tell that it
has gotten confused like this because the prompt changes from mysql>
to '>, ">, or `>.
This problem was fixed in MySQL 4.1.1.
/*! ... */) marks portions of SQL statements for conditional
execution. For more information and examples, see section 1.5.4 MySQL Extensions to Standard SQL.
For affected versions of MySQL,
these limitations apply both when you run mysql interactively
and when you put commands in a file and use mysql in batch mode to
process the file with mysql < file_name.
A common problem stems from trying to use an identifier such as a table or
column name that is the name of a built-in MySQL data type or function,
such as TIMESTAMP or GROUP. You're allowed
to do this (for example, ABS is allowed as a column name). However,
by default, no whitespace is allowed in function invocations between the
function name and the following `(' character. This requirement allows
a function call to be distinguished from a reference to a column name.
A side effect of this behavior is that omitting a space in some contexts causes an identifier to be interpreted as a function name. For example, this statement is legal:
mysql> CREATE TABLE abs (val INT);
But omitting the space after abs causes a syntax error because the
statement then appears to invoke the ABS() function:
mysql> CREATE TABLE abs(val INT);
If the server SQL mode includes the IGNORE_SPACE mode value, the
server allows function invocations to have whitespace between a function
name and the following `(' character. This causes function names to be
treated as reserved words. As a result, identifiers that are the same as
function names must be quoted as described in section 9.2 Database, Table, Index, Column, and Alias Names. The server
SQL mode is controlled as described in section 5.2.2 The Server SQL Mode.
The words in the following table are explicitly reserved in MySQL. Most of
them are forbidden by standard SQL as column and/or table names (for example,
GROUP). A few are reserved because MySQL needs them and (currently)
uses a yacc parser. A reserved word can be used as an identifier if
you quote it.
| Word | Word | Word |
ADD
| ALL
| ALTER
|
ANALYZE
| AND
| AS
|
ASC
| ASENSITIVE
| BEFORE
|
BETWEEN
| BIGINT
| BINARY
|
BLOB
| BOTH
| BY
|
CALL
| CASCADE
| CASE
|
CHANGE
| CHAR
| CHARACTER
|
CHECK
| COLLATE
| COLUMN
|
CONDITION
| CONNECTION
| CONSTRAINT
|
CONTINUE
| CONVERT
| CREATE
|
CROSS
| CURRENT_DATE
| CURRENT_TIME
|
CURRENT_TIMESTAMP
| CURRENT_USER
| CURSOR
|
DATABASE
| DATABASES
| DAY_HOUR
|
DAY_MICROSECOND
| DAY_MINUTE
| DAY_SECOND
|
DEC
| DECIMAL
| DECLARE
|
DEFAULT
| DELAYED
| DELETE
|
DESC
| DESCRIBE
| DETERMINISTIC
|
DISTINCT
| DISTINCTROW
| DIV
|
DOUBLE
| DROP
| DUAL
|
EACH
| ELSE
| ELSEIF
|
ENCLOSED
| ESCAPED
| EXISTS
|
EXIT
| EXPLAIN
| FALSE
|
FETCH
| FLOAT
| FOR
|
FORCE
| FOREIGN
| FROM
|
FULLTEXT
| GOTO
| GRANT
|
GROUP
| HAVING
| HIGH_PRIORITY
|
HOUR_MICROSECOND
| HOUR_MINUTE
| HOUR_SECOND
|
IF
| IGNORE
| IN
|
INDEX
| INFILE
| INNER
|
INOUT
| INSENSITIVE
| INSERT
|
INT
| INTEGER
| INTERVAL
|
INTO
| IS
| ITERATE
|
JOIN
| KEY
| KEYS
|
KILL
| LEADING
| LEAVE
|
LEFT
| LIKE
| LIMIT
|
LINES
| LOAD
| LOCALTIME
|
LOCALTIMESTAMP
| LOCK
| LONG
|
LONGBLOB
| LONGTEXT
| LOOP
|
LOW_PRIORITY
| MATCH
| MEDIUMBLOB
|
MEDIUMINT
| MEDIUMTEXT
| MIDDLEINT
|
MINUTE_MICROSECOND
| MINUTE_SECOND
| MOD
|
MODIFIES
| NATURAL
| NOT
|
NO_WRITE_TO_BINLOG
| NULL
| NUMERIC
|
ON
| OPTIMIZE
| OPTION
|
OPTIONALLY
| OR
| ORDER
|
OUT
| OUTER
| OUTFILE
|
PRECISION
| PRIMARY
| PROCEDURE
|
PURGE
| READ
| READS
|
REAL
| REFERENCES
| REGEXP
|
RENAME
| REPEAT
| REPLACE
|
REQUIRE
| RESTRICT
| RETURN
|
REVOKE
| RIGHT
| RLIKE
|
SCHEMA
| SCHEMAS
| SECOND_MICROSECOND
|
SELECT
| SENSITIVE
| SEPARATOR
|
SET
| SHOW
| SMALLINT
|
SONAME
| SPATIAL
| SPECIFIC
|
SQL
| SQLEXCEPTION
| SQLSTATE
|
SQLWARNING
| SQL_BIG_RESULT
| SQL_CALC_FOUND_ROWS
|
SQL_SMALL_RESULT
| SSL
| STARTING
|
STRAIGHT_JOIN
| TABLE
| TERMINATED
|
THEN
| TINYBLOB
| TINYINT
|
TINYTEXT
| TO
| TRAILING
|
TRIGGER
| TRUE
| UNDO
|
UNION
| UNIQUE
| UNLOCK
|
UNSIGNED
| UPDATE
| USAGE
|
USE
| USING
| UTC_DATE
|
UTC_TIME
| UTC_TIMESTAMP
| VALUES
|
VARBINARY
| VARCHAR
| VARCHARACTER
|
VARYING
| WHEN
| WHERE
|
WHILE
| WITH
| WRITE
|
XOR
| YEAR_MONTH
| ZEROFILL
|
MySQL allows some keywords to be used as unquoted identifiers because many people previously used them. Examples are those in the following list:
ACTION
BIT
DATE
ENUM
NO
TEXT
TIME
TIMESTAMP
Improved support for character set handling was added to MySQL in Version 4.1. The features described here are as implemented in MySQL 4.1.1. (MySQL 4.1.0 has some but not all of these features, and some of them are implemented differently.)
This chapter discusses the following topics:
Character set support currently is included in the MyISAM,
MEMORY (HEAP), and (as of MySQL 4.1.2) InnoDB storage
engines. The ISAM storage engine does not include character set
support; there are no plans to change this, because ISAM is
deprecated.
A character set is a set of symbols and encodings. A collation is a set of rules for comparing characters in a character set. Let's make the distinction clear with an example of an imaginary character set.
Suppose that we have an alphabet with four letters: `A', `B', `a', `b'. We give each letter a number: `A' = 0, `B' = 1, `a' = 2, `b' = 3. The letter `A' is a symbol, the number 0 is the encoding for `A', and the combination of all four letters and their encodings is a character set.
Suppose that we want to compare two string values, `A' and `B'. The simplest way to do this is to look at the encodings: 0 for `A' and 1 for `B'. Because 0 is less than 1, we say `A' is less than `B'. What we've just done is apply a collation to our character set. The collation is a set of rules (only one rule in this case): ``compare the encodings.'' We call this simplest of all possible collations a binary collation.
But what if we want to say that the lowercase and uppercase letters are equivalent? Then we would have at least two rules: (1) treat the lowercase letters `a' and `b' as equivalent to `A' and `B'; (2) then compare the encodings. We call this a case-insensitive collation. It's a little more complex than a binary collation.
In real life, most character sets have many characters: not just `A' and `B' but whole alphabets, sometimes multiple alphabets or eastern writing systems with thousands of characters, along with many special symbols and punctuation marks. Also in real life, most collations have many rules: not just case insensitivity but also accent insensitivity (an ``accent'' is a mark attached to a character as in German `Ö') and multiple-character mappings (such as the rule that `Ö' = `OE' in one of the two German collations).
MySQL 4.1 can do these things for you:
In these respects, not only is MySQL 4.1 far more flexible than MySQL 4.0, it also is far ahead of other DBMSs. However, to use the new features effectively, you need to learn what character sets and collations are available, how to change their defaults, and what the various string operators do with them.
The MySQL server can support multiple character sets. To list the available
character sets, use the SHOW CHARACTER SET statement:
mysql> SHOW CHARACTER SET; +----------+-----------------------------+---------------------+--------+ | Charset | Description | Default collation | Maxlen | +----------+-----------------------------+---------------------+--------+ | big5 | Big5 Traditional Chinese | big5_chinese_ci | 2 | | dec8 | DEC West European | dec8_swedish_ci | 1 | | cp850 | DOS West European | cp850_general_ci | 1 | | hp8 | HP West European | hp8_english_ci | 1 | | koi8r | KOI8-R Relcom Russian | koi8r_general_ci | 1 | | latin1 | ISO 8859-1 West European | latin1_swedish_ci | 1 | | latin2 | ISO 8859-2 Central European | latin2_general_ci | 1 | | swe7 | 7bit Swedish | swe7_swedish_ci | 1 | | ascii | US ASCII | ascii_general_ci | 1 | | ujis | EUC-JP Japanese | ujis_japanese_ci | 3 | | sjis | Shift-JIS Japanese | sjis_japanese_ci | 2 | | hebrew | ISO 8859-8 Hebrew | hebrew_general_ci | 1 | | tis620 | TIS620 Thai | tis620_thai_ci | 1 | | euckr | EUC-KR Korean | euckr_korean_ci | 2 | ...
Any given character set always has at least one collation. It may have several collations.
To list the collations for a character set, use the SHOW COLLATION
statement. For example, to see the collations for the latin1
(``ISO-8859-1 West European'') character set, use this statement to find
those collation names that begin with latin1:
mysql> SHOW COLLATION LIKE 'latin1%'; +-------------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +-------------------+---------+----+---------+----------+---------+ | latin1_german1_ci | latin1 | 5 | | | 0 | | latin1_swedish_ci | latin1 | 8 | Yes | Yes | 1 | | latin1_danish_ci | latin1 | 15 | | | 0 | | latin1_german2_ci | latin1 | 31 | | Yes | 2 | | latin1_bin | latin1 | 47 | | Yes | 1 | | latin1_general_ci | latin1 | 48 | | | 0 | | latin1_general_cs | latin1 | 49 | | | 0 | | latin1_spanish_ci | latin1 | 94 | | | 0 | +-------------------+---------+----+---------+----------+---------+
The latin1 collations have the following meanings:
| Collation | Meaning |
latin1_bin | Binary according to latin1 encoding
|
latin1_danish_ci | Danish/Norwegian |
latin1_general_ci | Multilingual |
latin1_general_cs | Multilingual, case sensitive |
latin1_german1_ci | German DIN-1 |
latin1_german2_ci | German DIN-2 |
latin1_spanish_ci | Modern Spanish |
latin1_swedish_ci | Swedish/Finnish |
Collations have these general characteristics:
latin1 is
latin1_swedish_ci.
_ci (case
insensitive), _cs (case sensitive), or _bin (binary).
There are default settings for character sets and collations at four levels: server, database, table, and connection. The following description may appear complex, but it has been found in practice that multiple-level defaulting leads to natural and obvious results.
The MySQL Server has a server character set and a server collation, which may not be null.
MySQL determines the server character set and server collation thus:
At the server level, the decision is simple. The server
character set and collation depend initially on the
options that you use when you start mysqld. You can use
--default-character-set for the character set, and
along with it you can add --default-collation for the
collation. If you don't specify a character set, that is the same as saying
--default-character-set=latin1. If you specify only a character set
(for example, latin1) but not a collation, that is the same as saying
--default-charset=latin1 --default-collation=latin1_swedish_ci
because latin1_swedish_ci is the default collation for latin1.
Therefore, the following three commands all have the same effect:
shell> mysqld
shell> mysqld --default-character-set=latin1
shell> mysqld --default-character-set=latin1 \
--default-collation=latin1_swedish_ci
One way to change the settings is by recompiling. If you want to
change the default server character set and collation when building
from sources, use: --with-charset and --with-collation
as arguments for configure. For example:
shell> ./configure --with-charset=latin1
Or:
shell> ./configure --with-charset=latin1 \
--with-collation=latin1_german1_ci
Both mysqld and configure verify that the character
set/collation combination is valid. If not, each program displays an error
message and terminates.
The current server character set and collation are available as the values of
the character_set_server and collation_server system variables.
These variables can be changed at runtime.
Every database has a database character set and a database
collation, which may not be null. The CREATE DATABASE and ALTER
DATABASE statements have optional clauses for specifying the
database character set and collation:
CREATE DATABASE db_name
[[DEFAULT] CHARACTER SET charset_name]
[[DEFAULT] COLLATE collation_name]
ALTER DATABASE db_name
[[DEFAULT] CHARACTER SET charset_name]
[[DEFAULT] COLLATE collation_name]
Example:
CREATE DATABASE db_name
DEFAULT CHARACTER SET latin1 COLLATE latin1_swedish_ci;
MySQL chooses the database character set and database collation thus:
CHARACTER SET X and COLLATE Y were specified, then
character set X and collation Y.
CHARACTER SET X was specified without COLLATE, then
character set X and its default collation.
MySQL's CREATE DATABASE ... DEFAULT CHARACTER SET ... syntax is
analogous to the standard SQL CREATE SCHEMA ... CHARACTER SET ...
syntax. Because of this, it is possible to create databases with
different character sets and collations on the same MySQL
server.
The database character set and collation are used as default
values if the table character set and collation are not specified
in CREATE TABLE statements. They have no other purpose.
The character set and collation for the default database are available as
the values of the character_set_database and
collation_database system variables. The server sets these variables
whenever the default database changes. If there is no default database, the
variables have the same value as the corresponding server-level variables,
character_set_server and collation_server.
Every table has a table character set and a table collation, which
may not be null. The CREATE TABLE and ALTER TABLE statements
have optional clauses for specifying the table character set and
collation:
CREATE TABLE tbl_name (column_list)
[DEFAULT CHARACTER SET charset_name [COLLATE collation_name]]
ALTER TABLE tbl_name
[DEFAULT CHARACTER SET charset_name] [COLLATE collation_name]
Example:
CREATE TABLE t1 ( ... )
DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;
MySQL chooses the table character set and collation thus:
CHARACTER SET X and COLLATE Y were specified, then
character set X and collation Y.
CHARACTER SET X was specified without COLLATE, then
character set X and its default collation.
The table character set and collation are used as default values if the column character set and collation are not specified in individual column definitions. The table character set and collation are MySQL extensions; there are no such things in standard SQL.
Every ``character'' column (that is, a column of type CHAR,
VARCHAR, or TEXT) has a column character set and a column
collation, which may not be null. Column definition syntax has optional
clauses for specifying the column character set and collation:
col_name {CHAR | VARCHAR | TEXT} (col_length)
[CHARACTER SET charset_name [COLLATE collation_name]]
Example:
CREATE TABLE Table1
(
column1 VARCHAR(5) CHARACTER SET latin1 COLLATE latin1_german1_ci
);
MySQL chooses the column character set and collation thus:
CHARACTER SET X and COLLATE Y were specified, then
character set X and collation Y.
CHARACTER SET X was specified without COLLATE, then
character set X and its default collation.
The CHARACTER SET and COLLATE clauses are standard SQL.
The following examples show how MySQL determines default character set and collation values.
CREATE TABLE t1
(
c1 CHAR(10) CHARACTER SET latin1 COLLATE latin1_german1_ci
) DEFAULT CHARACTER SET latin2 COLLATE latin2_bin;
Here we have a column with a latin1 character set
and a latin1_german1_ci collation. The definition is explicit, so
that's straightforward. Notice that there's no problem storing a
latin1 column in a latin2 table.
CREATE TABLE t1
(
c1 CHAR(10) CHARACTER SET latin1
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;
This time we have a column with a latin1 character
set and a default collation. Although it might seem natural,
the default collation is not taken from the table level. Instead,
because the default collation for latin1 is always
latin1_swedish_ci,
column c1 has a collation of latin1_swedish_ci (not
latin1_danish_ci).
CREATE TABLE t1
(
c1 CHAR(10)
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;
We have a column with a default character set and
a default collation. In this circumstance, MySQL looks up to the
table level for inspiration in determining the column character set and
collation. So, the character set for column c1 is
latin1 and its collation is latin1_danish_ci.
CREATE DATABASE d1
DEFAULT CHARACTER SET latin2 COLLATE latin2_czech_ci;
USE d1;
CREATE TABLE t1
(
c1 CHAR(10)
);
We create a column without specifying its
character set and collation. We're also not specifying a character
set and a collation at the table level. In this circumstance, MySQL
looks up to the database level for inspiration. (The database's
settings become the table's settings, and thereafter become the
column's setting.) So, the character set for column c1 is latin2
and its collation is latin2_czech_ci.
Several character set and collation system variables relate to a client's interaction with the server. Some of these have been mentioned in earlier sections:
character_set_server and collation_server variables.
character_set_database and collation_database
variables.
Additional character set and collation variables are involved in handling traffic for the connection between a client and the server. Every client has connection-related character set and collation variables.
Consider what a ``connection'' is: It's what you make when you connect to the server. The client sends SQL statements, such as queries, over the connection to the server. The server sends responses, such as result sets, over the connection back to the client. This leads to several questions about character set and collation handling for client connections, each of which can be answered in terms of system variables:
character_set_client variable to be the
character set in which queries are sent by the client.
character_set_connection and collation_connection
are used by the server. It converts queries sent by the client from
character_set_client to character_set_connection
(except for string literals that have an introducer such as _latin1 or
_utf8).
collation_connection is important for comparisons of literal strings.
For comparisons of strings with column values, it does not matter because
columns have a higher collation precedence.
character_set_results variable indicates the character set in
which the server returns query results to the client. This includes result
data such as column values, and result metadata such as column names.
You can fine-tune the settings for these variables, or you can depend on the defaults (in which case, you can skip this section).
There are two statements that affect the connection character sets:
SET NAMES 'charset_name' SET CHARACTER SET charset_name
SET NAMES indicates what is in the SQL statements that the client
sends. Thus, SET NAMES 'cp1251' tells the server ``future incoming
messages from this client are in character set cp1251.'' It
also specifies the character set for results that the server sends back to
the client. (For example, it indicates what character set column values
are if you use a SELECT statement.)
A SET NAMES 'x' statement
is equivalent to these three statements:
mysql> SET character_set_client = x; mysql> SET character_set_results = x; mysql> SET character_set_connection = x;
Setting character_set_connection to x also sets
collation_connection to the default collation for x.
SET CHARACTER SET is similar but sets the connection character set
and collation to be those of the default database. A SET CHARACTER SET
x statement is equivalent to these three statements:
mysql> SET character_set_client = x; mysql> SET character_set_results = x; mysql> SET collation_connection = @@collation_database;
When a client connects, it sends to the server the name of the character set
that it wants to use. The server sets the character_set_client,
character_set_results, and character_set_connection variables
to that character set. (In effect, the server performs a SET NAMES
operation using the character set.)
With the mysql client, it is not necessary to execute SET NAMES
every time you start up if you want to use a character set different from
the default. You can add the --default-character-set option setting
to your mysql statement line, or in your option file. For example,
the following option file setting changes the three character set variables
set to koi8r each time you run mysql:
[mysql] default-character-set=koi8r
Example: Suppose that column1 is defined as CHAR(5) CHARACTER
SET latin2. If you do not say SET NAMES or SET CHARACTER SET,
then for SELECT column1 FROM t, the server sends back all the
values for column1 using the character set that the client specified
when it connected. On the other hand, if you say SET NAMES 'latin1'
or SET CHARACTER SET latin1, then just before sending results back,
the server converts the latin2 values to latin1.
Conversion may be lossy if there are characters that are not in both
character sets.
If you do not want the server to perform any conversion, set
character_set_results to NULL:
mysql> SET character_set_results = NULL;
Every character string literal has a character set and a collation, which may not be null.
A character string literal may have an optional character set
introducer and COLLATE clause:
[_charset_name]'string' [COLLATE collation_name]
Examples:
SELECT 'string'; SELECT _latin1'string'; SELECT _latin1'string' COLLATE latin1_danish_ci;
For the simple statement SELECT 'string', the string has the character
set and collation defined by the character_set_connection and
collation_connection system variables.
The _charset_name expression is formally called
an introducer. It tells the parser,
``the string that is about to follow is in character set X.''
Because this has confused people in the past, we emphasize
that an introducer does not cause any conversion, it is strictly a
signal that does not change the string's value. An introducer is
also legal before standard hex literal and numeric hex literal notation
(x'literal' and 0xnnnn), and before ? (parameter
substitution when using prepared statements within a programming language
interface).
Examples:
SELECT _latin1 x'AABBCC'; SELECT _latin1 0xAABBCC; SELECT _latin1 ?;
MySQL determines a literal's character set and collation thus:
COLLATE Y were specified, then
character set X and collation Y
COLLATE is not specified, then
character set X and its default collation
character_set_connection and collation_connection system
variables
Examples:
latin1 character set and latin1_german1_ci
collation:
SELECT _latin1'Müller' COLLATE latin1_german1_ci;
latin1 character set and its default collation (that is,
latin1_swedish_ci):
SELECT _latin1'Müller';
SELECT 'Müller';
Character set introducers and the COLLATE clause are implemented
according to standard SQL specifications.
COLLATE in SQL Statements
With the COLLATE clause, you can override whatever the default
collation is for a comparison. COLLATE may be used in
various parts of SQL statements. Here are some examples:
ORDER BY:
SELECT k FROM t1 ORDER BY k COLLATE latin1_german2_ci;
AS:
SELECT k COLLATE latin1_german2_ci AS k1 FROM t1 ORDER BY k1;
GROUP BY:
SELECT k FROM t1 GROUP BY k COLLATE latin1_german2_ci;
SELECT MAX(k COLLATE latin1_german2_ci) FROM t1;
DISTINCT:
SELECT DISTINCT k COLLATE latin1_german2_ci FROM t1;
WHERE:
SELECT * FROM t1 WHERE _latin1 'Müller' COLLATE latin1_german2_ci = k;
HAVING:
SELECT k FROM t1 GROUP BY k HAVING k = _latin1 'Müller' COLLATE latin1_german2_ci;
COLLATE Clause Precedence
The COLLATE clause has high precedence (higher than ||),
so the following two expressions are equivalent:
x || y COLLATE z x || (y COLLATE z)
BINARY Operator
The BINARY operator is a shorthand for a COLLATE clause.
BINARY 'x' is equivalent to 'x' COLLATE y, where y is
the name of the binary collation for the character set of 'x'. Every
character set has a binary collation. For example, the binary collation for
the latin1 character set is latin1_bin, so if the column
a is of character set latin1, the following two statements have
the same effect:
SELECT * FROM t1 ORDER BY BINARY a; SELECT * FROM t1 ORDER BY a COLLATE latin1_bin;
In the great majority of queries, it is obvious what collation
MySQL uses to resolve a comparison operation. For example, in the
following cases, it should be clear that the collation is ``the
column collation of column x'':
SELECT x FROM T ORDER BY x; SELECT x FROM T WHERE x = x; SELECT DISTINCT x FROM T;
However, when multiple operands are involved, there can be ambiguity. For example:
SELECT x FROM T WHERE x = 'Y';
Should this query use the collation of the column x, or of the
string literal 'Y'?
Standard SQL resolves such questions using what used to be
called ``coercibility'' rules. The essence is: Because x and 'Y'
both have collations, whose collation takes precedence? It's complex,
but the following rules take care of most situations:
COLLATE clause has a coercibility of 0.
(Not coercible at all.)
USER() or VERSION()) has a coercibility of 3.
NULL or an expression that is derived from NULL has a coercibility of 5.
The preceding coercibility values are current as of MySQL 4.1.11 and 5.0.3. See the note later in this section for additional version-related information.
Those rules resolve ambiguities thus:
Examples:
column1 = 'A' | Use collation of column1
|
column1 = 'A' COLLATE x | Use collation of 'A'
|
column1 COLLATE x = 'A' COLLATE y | Error |
The COERCIBILITY() function can be used to determine the coercibility
of a string expression:
mysql> SELECT COERCIBILITY('A' COLLATE latin1_swedish_ci);
-> 0
mysql> SELECT COERCIBILITY(VERSION());
-> 3
mysql> SELECT COERCIBILITY('A');
-> 4
See section 12.8.3 Information Functions.
Before MySQL 4.1.11 and 5.0.3, there is no system constant or ignorable
coercibility. Functions such as USER() have a coercibility of 2
rather than 3, and literals have a coercibility of 3 rather than 4.
Recall that each character set has one or more
collations, and each collation is associated with one and only one
character set. Therefore, the following statement
causes an error message because the latin2_bin collation is not
legal with the latin1 character set:
mysql> SELECT _latin1 'x' COLLATE latin2_bin; ERROR 1251: COLLATION 'latin2_bin' is not valid for CHARACTER SET 'latin1'
In some cases, expressions that worked before MySQL 4.1 fail in early versions of MySQL 4.1 if you do not take character set and collation into account. For example, before 4.1, this statement works as is:
mysql> SELECT SUBSTRING_INDEX(USER(),'@',1); +-------------------------------+ | SUBSTRING_INDEX(USER(),'@',1) | +-------------------------------+ | root | +-------------------------------+
The statement also works as is in MySQL 4.1 as of 4.1.8: In MySQL 4.1,
usernames are stored using the utf8 character set
(see section 10.6 UTF8 for Metadata). The literal string '@' has the server
character set (latin1 by default). Although the character sets are
different, MySQL can coerce the latin1 string to the character set
(and collation) of USER() without data loss. It does so, performs the
substring operation, and returns a result that has a character set of
utf8.
However, in versions of MySQL 4.1 before 4.1.8, the statement fails:
mysql> SELECT SUBSTRING_INDEX(USER(),'@',1); ERROR 1267 (HY000): Illegal mix of collations (utf8_general_ci,IMPLICIT) and (latin1_swedish_ci,COERCIBLE) for operation 'substr_index'
This happens because the automatic character set conversion of '@'
does not occur and the string operands have different character sets
(and thus different collations):
mysql> SELECT COLLATION(USER()), COLLATION('@');
+-------------------+-------------------+
| COLLATION(USER()) | COLLATION('@') |
+-------------------+-------------------+
| utf8_general_ci | latin1_swedish_ci |
+-------------------+-------------------+
One way to deal with this is to upgrade to MySQL 4.1.8 or later. If that is
not possible, you can tell MySQL to interpret the literal string as
utf8:
mysql> SELECT SUBSTRING_INDEX(USER(),_utf8'@',1); +------------------------------------+ | SUBSTRING_INDEX(USER(),_utf8'@',1) | +------------------------------------+ | root | +------------------------------------+
Another way is to change the connection character set and collation to
utf8. You can do that with SET NAMES 'utf8' or by setting
the character_set_connection and collation_connection system
variables directly.
Suppose that column X in table T has these latin1 column values:
Muffler Müller MX Systems MySQL
And suppose that the column values are retrieved using the following statement:
SELECT X FROM T ORDER BY X COLLATE collation_name;
The resulting order of the values for different collations is shown in this table:
latin1_swedish_ci | latin1_german1_ci | latin1_german2_ci
|
| Muffler | Muffler | Müller |
| MX Systems | Müller | Muffler |
| Müller | MX Systems | MX Systems |
| MySQL | MySQL | MySQL |
The table is an example that shows what the effect would
be if we used different collations in an ORDER BY clause. The
character that causes the different sort orders in this example is the U with
two dots over it, which the Germans call U-umlaut, but we'll call
it U-diaeresis.
SELECT using the
Swedish/Finnish collating rule, which says that U-diaeresis sorts
with Y.
SELECT using the
German DIN-1 rule, which says that U-diaeresis sorts with U.
SELECT using the German
DIN-2 rule, which says that U-diaeresis sorts with UE.
Three different collations, three different results. That's what MySQL is here to handle. By using the appropriate collation, you can choose the sort order you want.
This section describes operations that take character set information into account as of MySQL 4.1.
MySQL has many operators and functions that return a string. This section answers the question: What is the character set and collation of such a string?
For simple functions that take string input and return a string result as
output, the output's character set and collation are the same as those of
the principal input value. For example, UPPER(X) returns a string
whose character string and collation are the same as that of X.
The same applies for
INSTR(),
LCASE(),
LOWER(),
LTRIM(),
MID(),
REPEAT(),
REPLACE(),
REVERSE(),
RIGHT(),
RPAD(),
RTRIM(),
SOUNDEX(),
SUBSTRING(),
TRIM(),
UCASE(), and
UPPER().
(Also note: The REPLACE() function, unlike all other functions,
ignores the collation of the string input and performs a
case-insensitive comparison every time.)
For operations that combine multiple string inputs and return a single string output, the ``aggregation rules'' of standard SQL apply:
COLLATE X occurs, then use X
COLLATE X and COLLATE Y occur, then error
X, then use X
For example, with CASE ... WHEN a THEN b WHEN b THEN c COLLATE X
END, the resultant collation is X. The same applies for
CASE,
UNION,
||,
CONCAT(),
ELT(),
GREATEST(),
IF(), and
LEAST().
For operations that convert to character data, the character set and
collation of the strings that result from the operations are defined by the
character_set_connection and collation_connection system
variables. This applies for
CAST(),
CHAR(),
CONV(),
FORMAT(),
HEX(), and
SPACE().
CONVERT()
CONVERT() provides a way to convert data between different
character sets. The syntax is:
CONVERT(expr USING transcoding_name)
In MySQL, transcoding names are the same as the corresponding character set names.
Examples:
SELECT CONVERT(_latin1'Müller' USING utf8);
INSERT INTO utf8table (utf8column)
SELECT CONVERT(latin1field USING utf8) FROM latin1table;
CONVERT(... USING ...) is implemented according to the standard SQL
specification.
CAST()
You may also use CAST() to convert a string to a different character
set. The syntax is:
CAST(character_string AS character_data_type CHARACTER SET charset_name)
Example:
SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8);
If you use CAST() without specifying CHARACTER SET,
the resulting character set and collation are defined by the
character_set_connection and collation_connection system
variables. If you use CAST() with CHARACTER SET X, then
the resulting character set and collation are X and the default
collation of X.
You may not use a COLLATE clause inside a CAST(), but you may use
it outside. That is, CAST(... COLLATE ...) is illegal, but
CAST(...) COLLATE ... is legal.
Example:
SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8) COLLATE utf8_bin;
SHOW Statements
Several SHOW statements are new or modified in MySQL 4.1 to provide
additional character set information.
SHOW CHARACTER SET,
SHOW COLLATION, and
SHOW CREATE DATABASE are new.
SHOW CREATE TABLE and
SHOW COLUMNS are modified.
The SHOW CHARACTER SET command shows all available character sets.
It takes an optional LIKE clause that indicates which character set
names to match. For example:
mysql> SHOW CHARACTER SET LIKE 'latin%'; +---------+-----------------------------+-------------------+--------+ | Charset | Description | Default collation | Maxlen | +---------+-----------------------------+-------------------+--------+ | latin1 | ISO 8859-1 West European | latin1_swedish_ci | 1 | | latin2 | ISO 8859-2 Central European | latin2_general_ci | 1 | | latin5 | ISO 8859-9 Turkish | latin5_turkish_ci | 1 | | latin7 | ISO 8859-13 Baltic | latin7_general_ci | 1 | +---------+-----------------------------+-------------------+--------+
See section 13.5.4.1 SHOW CHARACTER SET Syntax.
The output from SHOW COLLATION includes all available character
sets.
It takes an optional LIKE clause that indicates which collation
names to match. For example:
mysql> SHOW COLLATION LIKE 'latin1%'; +-------------------+---------+----+---------+----------+---------+ | Collation | Charset | Id | Default | Compiled | Sortlen | +-------------------+---------+----+---------+----------+---------+ | latin1_german1_ci | latin1 | 5 | | | 0 | | latin1_swedish_ci | latin1 | 8 | Yes | Yes | 0 | | latin1_danish_ci | latin1 | 15 | | | 0 | | latin1_german2_ci | latin1 | 31 | | Yes | 2 | | latin1_bin | latin1 | 47 | | Yes | 0 | | latin1_general_ci | latin1 | 48 | | | 0 | | latin1_general_cs | latin1 | 49 | | | 0 | | latin1_spanish_ci | latin1 | 94 | | | 0 | +-------------------+---------+----+---------+----------+---------+
See section 13.5.4.2 SHOW COLLATION Syntax.
SHOW CREATE DATABASE displays the CREATE DATABASE statement
that creates a given database. The result includes all database
options. DEFAULT CHARACTER SET and COLLATE are supported. All
database options are stored in a text file named `db.opt' that can
be found in the database directory.
mysql> SHOW CREATE DATABASE a\G
*************************** 1. row ***************************
Database: a
Create Database: CREATE DATABASE `a`
/*!40100 DEFAULT CHARACTER SET macce */
See section 13.5.4.4 SHOW CREATE DATABASE Syntax.
SHOW CREATE TABLE is similar, but displays the CREATE TABLE
statement to create a given table. The column definitions indicate any
character set specifications, and the table options include character set
information.
See section 13.5.4.5 SHOW CREATE TABLE Syntax.
The SHOW COLUMNS statement displays the collations of a table's
columns when invoked as SHOW FULL COLUMNS.
Columns with CHAR, VARCHAR, or TEXT data types have
non-NULL collations. Numeric and other non-character types have
NULL collations. For example:
mysql> SHOW FULL COLUMNS FROM t; +-------+---------+------------+------+-----+---------+-------+ | Field | Type | Collation | Null | Key | Default | Extra | +-------+---------+------------+------+-----+---------+-------+ | a | char(1) | latin1_bin | YES | | NULL | | | b | int(11) | NULL | YES | | NULL | | +-------+---------+------------+------+-----+---------+-------+
The character set is not part of the display. (The character set name is implied by the collation name.)
See section 13.5.4.3 SHOW COLUMNS Syntax.
As of MySQL version 4.1, there are two new character sets for storing Unicode data:
ucs2, the UCS-2 Unicode character set.
utf8, the UTF8 encoding of the Unicode character set.
In UCS-2 (binary Unicode representation), every character is represented by a two-byte Unicode code with the most significant byte first. For example: "LATIN CAPITAL LETTER A" has the code 0x0041 and it's stored as a two-byte sequence: 0x00 0x41. "CYRILLIC SMALL LETTER YERU" (Unicode 0x044B) is stored as a two-byte sequence: 0x04 0x4B. For Unicode characters and their codes, please refer to the Unicode Home Page.
A temporary restriction is that UCS-2 cannot yet be used as a client
character set. That means that SET NAMES 'ucs2' does not work.
The UTF8 character set (transform Unicode representation) is an alternative way to store Unicode data. It is implemented according to RFC 3629. The idea of the UTF8 character set is that various Unicode characters are encoded using byte sequences of different lengths:
RFC 3629 describes encoding sequences that take from one to four bytes. Currently, MySQL UTF8 support does not include four-byte sequences. (An older standard for UTF8 encoding is given by RFC 2279, which describes UTF8 sequences that take from one to six bytes. RFC 3629 renders RFC 2279 obsolete and sequences with five and six bytes now are not used.)
Tip: To save space with UTF8, use VARCHAR instead of CHAR.
Otherwise, MySQL has to reserve 30 bytes for a CHAR(10) CHARACTER
SET utf8 column, because that's the maximum possible length.
The metadata is the data about the data. Anything that
describes the database, as opposed to being the contents of the
database, is metadata. Thus column names, database names,
usernames, version names, and most of the string results from SHOW are
metadata.
Representation of metadata must satisfy these requirements:
SHOW
wouldn't work properly because different rows in the same column would be
in different character sets.
In order to satisfy both requirements, MySQL stores metadata in a Unicode character set, namely UTF8. This does not cause any disruption if you never use accented characters. But if you do, you should be aware that metadata is in UTF8.
This means that the USER(), CURRENT_USER(), DATABASE(),
and VERSION() functions have the UTF8 character set by default, as do
synonyms such as SESSION_USER() and SYSTEM_USER().
The server sets the character_set_system system variable to the
name of the metadata character set:
mysql> SHOW VARIABLES LIKE 'character_set_system'; +----------------------+-------+ | Variable_name | Value | +----------------------+-------+ | character_set_system | utf8 | +----------------------+-------+
Storage of metadata using Unicode does not mean that the headers
of columns and the results of DESCRIBE functions are in the
character_set_system character set by default. When you say
SELECT column1 FROM t, the name column1 itself is
returned from the server to the client in the character set as determined
by the SET NAMES statement. More specifically, the character
set used is determined by the value of the character_set_results
system variable. If this variable is set to NULL, no conversion is
performed and the server returns metadata using its original character set
(the set indicated by character_set_system).
If you want the server to pass metadata results back in a
non-UTF8 character set, then use SET NAMES to force the
server to perform character set conversion (see section 10.3.6 Connection Character Sets and Collations),
or else set the client to do the conversion. It is
always more efficient to set the client to do the conversion, but
this option is not available for many clients until late in
the MySQL 4.x product cycle.
If you are just using, for example, the USER() function for
comparison or assignment within a single statement, don't worry.
MySQL does some automatic conversion for you.
SELECT * FROM Table1 WHERE USER() = latin1_column;
This works because the contents of latin1_column are
automatically converted to UTF8 before the comparison.
INSERT INTO Table1 (latin1_column) SELECT USER();
This works because the contents of USER() are automatically
converted to latin1 before the assignment.
Automatic conversion is not fully implemented yet, but should work
correctly in a later version.
Although automatic conversion is not in the SQL standard, the SQL standard document does say that every character set is (in terms of supported characters) a ``subset'' of Unicode. Since it is a well-known principle that ``what applies to a superset can apply to a subset,'' we believe that a collation for Unicode can apply for comparisons with non-Unicode strings.
For MaxDB compatibility these two statements are the same:
CREATE TABLE t1 (f1 CHAR(n) UNICODE); CREATE TABLE t1 (f1 CHAR(n) CHARACTER SET ucs2);
In MySQL 4.1, character set configuration is stored in XML files, one file per character set. In previous versions, this information was stored in `.conf' files.
Before MySQL 4.1, NCHAR and CHAR were synonymous. ANSI
defines NCHAR or NATIONAL CHAR as a way to indicate that a
CHAR
column should use some predefined character set. MySQL 4.1 and up uses utf8 as
that predefined character set. For example, these column type declarations
are equivalent:
CHAR(10) CHARACTER SET utf8 NATIONAL CHARACTER(10) NCHAR(10)
As are these:
VARCHAR(10) CHARACTER SET utf8 NATIONAL VARCHAR(10) NCHAR VARCHAR(10) NATIONAL CHARACTER VARYING(10) NATIONAL CHAR VARYING(10)
You can use N'literal' to create a string in
the national character set.
These two statements are equivalent:
SELECT N'some text'; SELECT _utf8'some text';
What about upgrading from older versions of MySQL? MySQL 4.1 is almost upward compatible with MySQL 4.0 and earlier for the simple reason that almost all the features are new, so there's nothing in earlier versions to conflict with. However, there are some differences and a few things to be aware of.
Most important: The ``MySQL 4.0 character set'' has the properties of both ``MySQL 4.1 character sets'' and ``MySQL 4.1 collations.'' You have to unlearn this. Henceforth, we does not bundle character set/collation properties in the same conglomerate object.
There is a special treatment of national character sets in MySQL
4.1. NCHAR is not the same as CHAR, and N'...' literals
are not the same as '...' literals.
Finally, there is a different file format for storing information about character sets and collations. Make sure that you have reinstalled the `/share/mysql/charsets/' directory containing the new configuration files.
If you want to start mysqld from a 4.1.x distribution with data
created by MySQL 4.0, you should start the server with the same
character set and collation. In this case, you won't need to reindex
your data.
There are two ways to do so:
shell> ./configure --with-charset=... --with-collation=... shell> ./mysqld --default-character-set=... --default-collation=...
If you used mysqld with, for example, the MySQL 4.0 danish
character set, you should use the latin1 character set and
the latin1_danish_ci collation:
shell> ./configure --with-charset=latin1 \
--with-collation=latin1_danish_ci
shell> ./mysqld --default-character-set=latin1 \
--default-collation=latin1_danish_ci
Use the table shown in section 10.10.1 4.0 Character Sets and Corresponding 4.1 Character Set/Collation Pairs to find old 4.0 character set names and their 4.1 character set/collation pair equivalents.
If you have non-latin1 data stored in a 4.0 latin1 table
and want to convert the table column definitions to reflect the actual
character set of the data, use the instructions in section 10.10.2 Converting 4.0 Character Columns to 4.1 Format.
| ID | 4.0 Character Set | 4.1 Character Set | 4.1 Collation |
| 1 | big5 | big5 | big5_chinese_ci
|
| 2 | czech | latin2 | latin2_czech_ci
|
| 3 | dec8 | dec8 | dec8_swedish_ci
|
| 4 | dos | cp850 | cp850_general_ci
|
| 5 | german1 | latin1 | latin1_german1_ci
|
| 6 | hp8 | hp8 | hp8_english_ci
|
| 7 | koi8_ru | koi8r | koi8r_general_ci
|
| 8 | latin1 | latin1 | latin1_swedish_ci
|
| 9 | latin2 | latin2 | latin2_general_ci
|
| 10 | swe7 | swe7 | swe7_swedish_ci
|
| 11 | usa7 | ascii | ascii_general_ci
|
| 12 | ujis | ujis | ujis_japanese_ci
|
| 13 | sjis | sjis | sjis_japanese_ci
|
| 14 | cp1251 | cp1251 | cp1251_bulgarian_ci
|
| 15 | danish | latin1 | latin1_danish_ci
|
| 16 | hebrew | hebrew | hebrew_general_ci
|
| 17 | win1251 | (removed) | (removed)
|
| 18 | tis620 | tis620 | tis620_thai_ci
|
| 19 | euc_kr | euckr | euckr_korean_ci
|
| 20 | estonia | latin7 | latin7_estonian_ci
|
| 21 | hungarian | latin2 | latin2_hungarian_ci
|
| 22 | koi8_ukr | koi8u | koi8u_ukrainian_ci
|
| 23 | win1251ukr | cp1251 | cp1251_ukrainian_ci
|
| 24 | gb2312 | gb2312 | gb2312_chinese_ci
|
| 25 | greek | greek | greek_general_ci
|
| 26 | win1250 | cp1250 | cp1250_general_ci
|
| 27 | croat | latin2 | latin2_croatian_ci
|
| 28 | gbk | gbk | gbk_chinese_ci
|
| 29 | cp1257 | cp1257 | cp1257_lithuanian_ci
|
| 30 | latin5 | latin5 | latin5_turkish_ci
|
| 31 | latin1_de | latin1 | latin1_german2_ci
|
Normally, the server runs using the latin1 character set by default.
If you have been storing column data that actually is in some other
character set that the 4.1 server supports directly, you can convert the
column. However, you should avoid trying to convert directly from
latin1 to the "real" character set. This may result in data loss.
Instead, convert the column to a binary column type, and then from the
binary type to a non-binary type with the desired character set. Conversion
to and from binary involves no attempt at character value conversion and
preserves your data intact. For example, suppose that you have a 4.0 table with
three columns that are used to store values represented in latin1,
latin2, and utf8:
CREATE TABLE t
(
latin1_col CHAR(50),
latin2_col CHAR(100),
utf8_col CHAR(150)
);
After upgrading to MySQL 4.1, you want to convert this table to leave
latin1_col alone but change the latin2_col and utf8_col
columns to have character sets of latin2 and utf8. First,
back up your table, then convert the columns as follows:
ALTER TABLE t MODIFY latin2_col BINARY(100); ALTER TABLE t MODIFY utf8_col BINARY(150); ALTER TABLE t MODIFY latin2_col CHAR(100) CHARACTER SET latin2; ALTER TABLE t MODIFY utf8_col CHAR(150) CHARACTER SET utf8;
The first two statements ``remove'' the character set information from the
latin2_col and utf8_col columns. The second two statements
assign the proper character sets to the two columns.
If you like, you can combine the to-binary conversions and from-binary conversions into single statements:
ALTER TABLE t
MODIFY latin2_col BINARY(100),
MODIFY utf8_col BINARY(150);
ALTER TABLE t
MODIFY latin2_col CHAR(100) CHARACTER SET latin2,
MODIFY utf8_col CHAR(150) CHARACTER SET utf8;
If you specified attributes when creating a column initially, you should
also specify them when altering the table with ALTER TABLE. For
example, if you specified NOT NULL and an explicit DEFAULT
value, you should also provide them in the ALTER TABLE statement.
Otherwise, the resulting column definition will not include those attributes.
Here is an annotated list of character sets and collations that MySQL supports. Because options and installation settings differ, some sites might not have all items listed, and some sites might have items not listed.
MySQL supports 70+ collations for 30+ character sets. The character sets and
their default collations are displayed by the
SHOW CHARACTER SET statement.
(The output actually includes another column that is not shown so that the
example fits better on the page.)
mysql> SHOW CHARACTER SET; +----------+-----------------------------+---------------------+ | Charset | Description | Default collation | +----------+-----------------------------+---------------------+ | big5 | Big5 Traditional Chinese | big5_chinese_ci | | dec8 | DEC West European | dec8_swedish_ci | | cp850 | DOS West European | cp850_general_ci | | hp8 | HP West European | hp8_english_ci | | koi8r | KOI8-R Relcom Russian | koi8r_general_ci | | latin1 | ISO 8859-1 West European | latin1_swedish_ci | | latin2 | ISO 8859-2 Central European | latin2_general_ci | | swe7 | 7bit Swedish | swe7_swedish_ci | | ascii | US ASCII | ascii_general_ci | | ujis | EUC-JP Japanese | ujis_japanese_ci | | sjis | Shift-JIS Japanese | sjis_japanese_ci | | hebrew | ISO 8859-8 Hebrew | hebrew_general_ci | | tis620 | TIS620 Thai | tis620_thai_ci | | euckr | EUC-KR Korean | euckr_korean_ci | | koi8u | KOI8-U Ukrainian | koi8u_general_ci | | gb2312 | GB2312 Simplified Chinese | gb2312_chinese_ci | | greek | ISO 8859-7 Greek | greek_general_ci | | cp1250 | Windows Central European | cp1250_general_ci | | gbk | GBK Simplified Chinese | gbk_chinese_ci | | latin5 | ISO 8859-9 Turkish | latin5_turkish_ci | | armscii8 | ARMSCII-8 Armenian | armscii8_general_ci | | utf8 | UTF-8 Unicode | utf8_general_ci | | ucs2 | UCS-2 Unicode | ucs2_general_ci | | cp866 | DOS Russian | cp866_general_ci | | keybcs2 | DOS Kamenicky Czech-Slovak | keybcs2_general_ci | | macce | Mac Central European | macce_general_ci | | macroman | Mac West European | macroman_general_ci | | cp852 | DOS Central European | cp852_general_ci | | latin7 | ISO 8859-13 Baltic | latin7_general_ci | | cp1251 | Windows Cyrillic | cp1251_general_ci | | cp1256 | Windows Arabic | cp1256_general_ci | | cp1257 | Windows Baltic | cp1257_general_ci | | binary | Binary pseudo charset | binary | | geostd8 | GEOSTD8 Georgian | geostd8_general_ci | | cp932 | SJIS for Windows Japanese | cp932_japanese_ci | | eucjpms | UJIS for Windows Japanese | eucjpms_japanese_ci | +----------+-----------------------------+---------------------+
MySQL has two Unicode character sets. You can store texts in about 650 languages using these character sets. We have added several collations for these two new sets, with more to come.
ucs2 (UCS-2 Unicode) collations:
ucs2_bin
ucs2_czech_ci
ucs2_danish_ci
ucs2_estonian_ci
ucs2_general_ci (default)
ucs2_icelandic_ci
ucs2_latvian_ci
ucs2_lithuanian_ci
ucs2_persian_ci
ucs2_polish_ci
ucs2_roman_ci
ucs2_romanian_ci
ucs2_slovak_ci
ucs2_slovenian_ci
ucs2_spanish2_ci
ucs2_spanish_ci
ucs2_swedish_ci
ucs2_turkish_ci
ucs2_unicode_ci
utf8 (UTF-8 Unicode) collations:
utf8_bin
utf8_czech_ci
utf8_danish_ci
utf8_estonian_ci
utf8_general_ci (default)
utf8_icelandic_ci
utf8_latvian_ci
utf8_lithuanian_ci
utf8_persian_ci
utf8_polish_ci
utf8_roman_ci
utf8_romanian_ci
utf8_slovak_ci
utf8_slovenian_ci
utf8_spanish2_ci
utf8_spanish_ci
utf8_swedish_ci
utf8_turkish_ci
utf8_unicode_ci
The utf8_unicode_ci collation is implemented according to the Unicode
Collation Algorithm (UCA) described at
http://www.unicode.org/reports/tr10/.
The collation uses the default UCA weight keys:
http://www.unicode.org/Public/UCA/latest/allkeys.txt.
(The following discussion uses utf8_unicode_ci, but it is also
true for ucs2_unicode_ci.)
Currently, the utf8_unicode_ci collation has only partial support for
the Unicode Collation Algorithm. Some characters are not supported yet.
Also, combining marks are not fully supported. This affects primarily
Vietnamese and some minority languages in Russia such as Udmurt, Tatar,
Bashkir, and Mari.
The most significant feature in utf8_unicode_ci is that it supports
expansions, that is, when one character compares equal to several characters.
For example, in German and some other languages `ß' is equal
to `ss'.
utf8_general_ci is a legacy collation that does not support
expansions. It can only compare characters one to one. This means that
comparisons for the utf8_general_ci collation are faster, but
slightly less correct, than comparisons for utf8_unicode_ci).
For example, the following equalities hold in both utf8_general_ci
and utf8_unicode_ci:
Ä = A Ö = O Ü = U
A difference between the collations is that this is true for
utf8_general_ci:
ß = s
Whereas this is true for utf8_unicode_ci:
ß = ss
Language-specific collations for the utf8 character set are
implemented only if the default order provided by utf8_unicode_ci
does not work for a language well. For example, utf8_unicode_ci
works fine for German and French, so there is no need to create special
utf8 collations for these two languages.
utf8_general_ci is fine for both German and French, too, with an
exception that `ß' is equal to `s', not to `ss'. If that
is acceptable for your application, use utf8_general_ci because it is
faster. Otherwise, use utf8_unicode_ci because it is ``smarter.''
utf8_swedish_ci, like other utf8 language-specific collations,
is derived from utf8_unicode_ci with additional language rules. For
example, in Swedish, the following relationship holds, which is not
something expected by a German or French speaker:
Ü = Y < Ö
The utf8_spanish_ci and utf8_spanish2_ci collations correspond
to modern Spanish and traditional Spanish, respectively. In both
collations, `ñ' (n-tilde) is a separate letter between `n' and
`o'. In addition, for traditional Spanish, `ch' is a separate
letter between `c' and d, and `ll' is a separate letter
between `l' and `m'
West European Character Sets cover most West European languages, such as French, Spanish, Catalan, Basque, Portuguese, Italian, Albanian, Dutch, German, Danish, Swedish, Norwegian, Finnish, Faroese, Icelandic, Irish, Scottish, and English.
ascii (US ASCII) collations:
ascii_bin
ascii_general_ci (default)
cp850 (DOS West European) collations:
cp850_bin
cp850_general_ci (default)
dec8 (DEC West European) collations:
dec8_bin
dec8_swedish_ci (default)
hp8 (HP West European) collations:
hp8_bin
hp8_english_ci (default)
latin1 (ISO 8859-1 West European) collations:
latin1_bin
latin1_danish_ci
latin1_general_ci
latin1_general_cs
latin1_german1_ci
latin1_german2_ci
latin1_spanish_ci
latin1_swedish_ci (default)
latin1 is the default character set.
The latin1_swedish_ci collation is the default that probably is
used by the majority of MySQL customers. It is constantly stated
that this is based on the Swedish/Finnish collation rules, but you
can find Swedes and Finns who disagree with that statement.
The latin1_german1_ci and latin1_german2_ci
collations are based on the DIN-1 and DIN-2 standards,
where DIN stands for Deutsches Institut für Normung (that is,
the German answer to ANSI).
DIN-1 is called the dictionary collation and DIN-2 is called the
phone-book collation.
latin1_german1_ci (dictionary) rules:
Ä = A Ö = O Ü = U ß = s
latin1_german2_ci (phone-book) rules:
Ä = AE Ö = OE Ü = UE ß = ss
latin1_spanish_ci collation, `ñ' (n-tilde) is a
separate letter between `n' and `o'.
macroman (Mac West European) collations:
macroman_bin
macroman_general_ci (default)
swe7 (7bit Swedish) collations:
swe7_bin
swe7_swedish_ci (default)
We have some support for character sets used in the Czech Republic, Slovakia, Hungary, Romania, Slovenia, Croatia, and Poland.
cp1250 (Windows Central European) collations:
cp1250_bin
cp1250_czech_cs
cp1250_general_ci (default)
cp852 (DOS Central European) collations:
cp852_bin
cp852_general_ci (default)
keybcs2 (DOS Kamenicky Czech-Slovak) collations:
keybcs2_bin
keybcs2_general_ci (default)
latin2 (ISO 8859-2 Central European) collations:
latin2_bin
latin2_croatian_ci
latin2_czech_cs
latin2_general_ci (default)
latin2_hungarian_ci
macce (Mac Central European) collations:
macce_bin
macce_general_ci (default)
armscii8 (ARMSCII-8 Armenian) collations:
armscii8_bin
armscii8_general_ci (default)
cp1256 (Windows Arabic) collations:
cp1256_bin
cp1256_general_ci (default)
geostd8 (GEOSTD8 Georgian) collations:
geostd8_bin
geostd8_general_ci (default)
greek (ISO 8859-7 Greek) collations:
greek_bin
greek_general_ci (default)
hebrew (ISO 8859-8 Hebrew) collations:
hebrew_bin
hebrew_general_ci (default)
latin5 (ISO 8859-9 Turkish) collations:
latin5_bin
latin5_turkish_ci (default)
The Baltic character sets cover Estonian, Latvian, and Lithuanian languages. There are two Baltic character sets currently supported:
cp1257 (Windows Baltic) collations:
cp1257_bin
cp1257_general_ci (default)
cp1257_lithuanian_ci
latin7 (ISO 8859-13 Baltic) collations:
latin7_bin
latin7_estonian_cs
latin7_general_ci (default)
latin7_general_cs
Here are the Cyrillic character sets and collations for use with Belarusian, Bulgarian, Russian, and Ukrainian languages.
cp1251 (Windows Cyrillic) collations:
cp1251_bin
cp1251_bulgarian_ci
cp1251_general_ci (default)
cp1251_general_cs
cp1251_ukrainian_ci
cp866 (DOS Russian) collations:
cp866_bin
cp866_general_ci (default)
koi8r (KOI8-R Relcom Russian) collations:
koi8r_bin
koi8r_general_ci (default)
koi8u (KOI8-U Ukrainian) collations:
koi8u_bin
koi8u_general_ci (default)
The Asian character sets that we support include Chinese, Japanese, Korean, and Thai. These can be complicated. For example, the Chinese sets must allow for thousands of different characters.
big5 (Big5 Traditional Chinese) collations:
big5_bin
big5_chinese_ci (default)
cp932 (SJIS for Windows Japanese) collations:
cp932_bin
cp932_japanese_ci (default)
eucjpms (UJIS for Windows Japanese) collations:
eucjpms_bin
eucjpms_japanese_ci (default)
euckr (EUC-KR Korean) collations:
euckr_bin
euckr_korean_ci (default)
gb2312 (GB2312 Simplified Chinese) collations:
gb2312_bin
gb2312_chinese_ci (default)
gbk (GBK Simplified Chinese) collations:
gbk_bin
gbk_chinese_ci (default)
sjis (Shift-JIS Japanese) collations:
sjis_bin
sjis_japanese_ci (default)
tis620 (TIS620 Thai) collations:
tis620_bin
tis620_thai_ci (default)
ujis (EUC-JP Japanese) collations:
ujis_bin
ujis_japanese_ci (default)
MySQL supports a number of column types in several categories: numeric types, date and time types, and string (character) types. This chapter first gives an overview of these column types, and then provides a more detailed description of the properties of the types in each category, and a summary of the column type storage requirements. The overview is intentionally brief. The more detailed descriptions should be consulted for additional information about particular column types, such as the allowable formats in which you can specify values.
MySQL versions 4.1 and up support extensions for handing spatial data. Information about spatial types is provided in section 18 Spatial Extensions in MySQL.
Several of the column type descriptions use these conventions:
M
D
A summary of the numeric column types follows. For additional information, see section 11.2 Numeric Types. Column storage requirements are given in section 11.5 Column Type Storage Requirements.
M indicates the maximum display width. The maximum legal display width is 255. Display width is unrelated to the storage size or range of values a type can contain, as described in section 11.2 Numeric Types.
If you specify ZEROFILL for a numeric column, MySQL
automatically adds the UNSIGNED attribute to the column.
SERIAL is an alias for BIGINT UNSIGNED NOT NULL AUTO_INCREMENT.
SERIAL DEFAULT VALUE in the definition of an integer column is an
alias for NOT NULL AUTO_INCREMENT UNIQUE.
Warning: You should be aware that when you use subtraction
between integer values where one is of type UNSIGNED, the result
is unsigned. See section 12.7 Cast Functions and Operators.
BIT[(M)]
BIT is
supported only for MyISAM.
This data type was added in MySQL 5.0.3. Before 5.0.3, BIT is a
synonym for TINYINT(1).
TINYINT[(M)] [UNSIGNED] [ZEROFILL]
-128 to 127. The
unsigned range is 0 to 255.
BOOL
BOOLEAN
TINYINT(1).
The BOOLEAN synonym was added in MySQL 4.1.0.
A value of zero is considered false. Non-zero values are considered true.
In the future,
full boolean type handling will be introduced in accordance with standard SQL.
SMALLINT[(M)] [UNSIGNED] [ZEROFILL]
-32768 to 32767. The
unsigned range is 0 to 65535.
MEDIUMINT[(M)] [UNSIGNED] [ZEROFILL]
-8388608 to
8388607. The unsigned range is 0 to 16777215.
INT[(M)] [UNSIGNED] [ZEROFILL]
-2147483648 to
2147483647. The unsigned range is 0 to 4294967295.
INTEGER[(M)] [UNSIGNED] [ZEROFILL]
INT.
BIGINT[(M)] [UNSIGNED] [ZEROFILL]
-9223372036854775808 to
9223372036854775807. The unsigned range is 0 to
18446744073709551615.
Some things you should be aware of with respect to BIGINT columns:
BIGINT or DOUBLE
values, so you shouldn't use unsigned big integers larger than
9223372036854775807 (63 bits) except with bit functions! If you
do that, some of the last digits in the result may be wrong because of
rounding errors when converting a BIGINT value to a DOUBLE.
MySQL 4.0 can handle BIGINT in the following cases:
BIGINT column.
MIN(col_name) or MAX(col_name), where
col_name refers to a BIGINT column.
+, -, *, and so on) where
both operands are integers.
BIGINT column by
storing it using a string. In this case, MySQL performs a string-to-number
conversion that involves no intermediate double-precision representation.
-, +, and * operators use BIGINT
arithmetic when both operands are integer values. This means that if
you multiply two big integers (or results from functions that return
integers), you may get unexpected results when the result is larger than
9223372036854775807.
FLOAT(p) [UNSIGNED] [ZEROFILL]
FLOAT
and DOUBLE types described immediately following. FLOAT(p)
has the same range as the corresponding FLOAT and DOUBLE
types, but the display width and number of decimals are undefined.
As of MySQL 3.23, this is a true floating-point value. In
earlier MySQL versions, FLOAT(p) always has two decimals.
This syntax is provided for ODBC compatibility.
Using FLOAT might give you some unexpected problems because
all calculations in MySQL are done with double precision.
See section A.5.7 Solving Problems with No Matching Rows.
FLOAT[(M,D)] [UNSIGNED] [ZEROFILL]
-3.402823466E+38 to -1.175494351E-38, 0,
and 1.175494351E-38 to 3.402823466E+38. If
UNSIGNED is specified, negative values are disallowed. M
is the display width and D is the number of decimals. FLOAT
without arguments or FLOAT(p) (where p is in the range from
0 to 24) stands for a single-precision floating-point number.
DOUBLE[(M,D)] [UNSIGNED] [ZEROFILL]
-1.7976931348623157E+308 to
-2.2250738585072014E-308, 0, and
2.2250738585072014E-308 to 1.7976931348623157E+308. If
UNSIGNED is specified, negative values are disallowed.
M is the display width and D is the number of decimals.
DOUBLE without arguments or FLOAT(p) (where
p is in the
range from 25 to 53) stands for a double-precision floating-point number.
DOUBLE PRECISION[(M,D)] [UNSIGNED] [ZEROFILL]
REAL[(M,D)] [UNSIGNED] [ZEROFILL]
DOUBLE.
Exception: If the server SQL mode includes the REAL_AS_FLOAT option,
REAL is a synonym for FLOAT rather than DOUBLE.
DECIMAL[(M[,D])] [UNSIGNED] [ZEROFILL]
DECIMAL is 64. The maximum number of supported
decimals (D) is 30. If UNSIGNED is specified, negative
values are disallowed.
If D is omitted, the default is 0. If M is omitted, the
default is 10.
All basic calculations (+, -, *, /) with DECIMAL columns are
done with a precision of 64 decimal digits.
Before MySQL 5.0.3:
An unpacked fixed-point number. Behaves like a CHAR column;
``unpacked'' means the number is stored as a string, using one character for
each digit of the value. M is the total number of digits and
D is the number of decimals. The decimal point and (for negative
numbers) the `-' sign are not counted in M, although space for
them is reserved. If D is 0, values have no decimal point or
fractional part. The maximum range of DECIMAL values is the same as
for DOUBLE, but the actual range for a given DECIMAL column
may be constrained by the choice of M and D. If
UNSIGNED is specified, negative values are disallowed.
If D is omitted, the default is 0. If M is omitted, the
default is 10.
Before MySQL 3.23:
As just described, with the exception that the M value must be large
enough to include the space needed for the sign and the decimal point
characters.
DEC[(M[,D])] [UNSIGNED] [ZEROFILL]
NUMERIC[(M[,D])] [UNSIGNED] [ZEROFILL]
FIXED[(M[,D])] [UNSIGNED] [ZEROFILL]
DECIMAL. The FIXED synonym was added
in MySQL 4.1.0 for compatibility with other servers.
A summary of the temporal column types follows. For additional information, see section 11.3 Date and Time Types. Column storage requirements are given in section 11.5 Column Type Storage Requirements.
DATE
'1000-01-01' to '9999-12-31'.
MySQL displays DATE values in 'YYYY-MM-DD' format, but
allows you to assign values to DATE columns using either strings or
numbers.
DATETIME
'1000-01-01
00:00:00' to '9999-12-31 23:59:59'. MySQL displays
DATETIME values in 'YYYY-MM-DD HH:MM:SS' format, but allows you
to assign values to DATETIME columns using either strings or numbers.
TIMESTAMP[(M)]
'1970-01-01 00:00:00' to partway through the
year 2037.
A TIMESTAMP column is useful for recording the date and time of an
INSERT or UPDATE operation. The first TIMESTAMP column
in a table is automatically set to the date and time of the most recent
operation if you don't assign it a value yourself. You can also set any
TIMESTAMP column to the current date and time by assigning it a
NULL value.
From MySQL 4.1 on, TIMESTAMP is returned as a string with the format
'YYYY-MM-DD HH:MM:SS'. If you want to obtain the value as a number,
you should add +0 to the timestamp column. Different timestamp
display widths are not supported.
In MySQL 4.0 and earlier, TIMESTAMP values are displayed in
YYYYMMDDHHMMSS, YYMMDDHHMMSS, YYYYMMDD, or YYMMDD
format, depending on whether M is 14 (or missing), 12,
8, or 6, but allows you to assign values to TIMESTAMP
columns using either strings or numbers.
The M argument affects only how a TIMESTAMP column is displayed,
not storage. Its values always are stored using four bytes each.
From MySQL 4.0.12, the --new option can be used
to make the server behave as in MySQL 4.1.
Note that TIMESTAMP(M) columns where M is 8 or 14 are reported to
be numbers, whereas other TIMESTAMP(M) columns are reported to be
strings. This is just to ensure that you can reliably dump and restore
the table with these types.
TIME
'-838:59:59' to '838:59:59'.
MySQL displays TIME values in 'HH:MM:SS' format, but
allows you to assign values to TIME columns using either strings or
numbers.
YEAR[(2|4)]
1901 to 2155, and 0000.
In two-digit format, the allowable values are
70 to 69, representing years from
1970 to 2069. MySQL displays YEAR values in
YYYY format, but allows you to assign values to YEAR columns
using either strings or numbers. The YEAR type is unavailable prior
to MySQL 3.22.
A summary of the string column types follows. For additional information, see section 11.4 String Types. Column storage requirements are given in section 11.5 Column Type Storage Requirements.
In some cases, MySQL may change a string column to a type different from
that given in a CREATE TABLE or ALTER TABLE statement.
See section 13.2.6.1 Silent Column Specification Changes.
As of MySQL 4.1, several changes affect string data types:
CHARACTER
SET attribute to specify the character set and, optionally, a collation.
This applies to CHAR, VARCHAR, the TEXT types,
ENUM, and SET. For example:
CREATE TABLE t
(
c1 CHAR(20) CHARACTER SET utf8,
c2 CHAR(20) CHARACTER SET latin1 COLLATE latin1_bin
);
This table definition creates a column named c1 that has a character
set of utf8 with the default collation for that character set, and a
column named c2 that has a character set of latin1 and the
binary collation for the character set. The binary collation is not case
sensitive.
CHAR, VARCHAR, and the TEXT types,
the BINARY attribute causes the column to be assigned the binary
collation of the column character set. For earlier versions, BINARY
causes CHAR and VARCHAR to be treated as binary strings and is
disallowed for the TEXT types.
CHAR and
VARCHAR columns, you can declare the column with the BINARY
attribute to cause sorting and comparison to use the underlying character
code values rather then a lexical ordering.
For more details about character set support in MySQL 4.1 and up, see section 10 Character Set Support.
[NATIONAL] CHAR(M) [BINARY | ASCII | UNICODE]
CHAR values are
retrieved.
From MySQL 4.1.0 to 5.0.2, a CHAR column with a length specification
greater than 255 is converted to the smallest TEXT type that can hold
values of the given length. For example, CHAR(500) is converted to
TEXT, and CHAR(200000) is converted to MEDIUMTEXT.
This is a compatibility feature. However, this conversion causes the column
to become a variable-length column, and also affects trailing-space removal.
CHAR is shorthand for CHARACTER.
NATIONAL CHAR (or its equivalent short form, NCHAR) is the
standard SQL way to define that a CHAR column should use the default
character set. This is the default in MySQL.
As of MySQL 4.1.2, the BINARY attribute is shorthand for specifying
the binary collation of the column character set. Sorting and comparison is
based on numeric character values. Before 4.1.2, BINARY attribute
causes the column to be treated as a binary string. Sorting and comparison
is based on numeric byte values.
From MySQL 4.1.0 on, column type CHAR BYTE is an alias for
CHAR BINARY. This is a compatibility feature.
From MySQL 4.1.0 on, the ASCII attribute can be specified for
CHAR. It assigns the latin1 character set.
From MySQL 4.1.1 on, the UNICODE attribute can be specified for
CHAR. It assigns the ucs2 character set.
MySQL allows you to create a column of type CHAR(0). This is mainly
useful when you have to be compliant with some old applications that depend
on the existence of a column but that do not actually use the value. This
is also quite nice when you need a column that can take only two values: A
CHAR(0) column that is not defined as NOT NULL occupies only
one bit and can take only the values NULL and '' (the empty
string).
CHAR
CHAR(1).
[NATIONAL] VARCHAR(M) [BINARY]
VARCHAR in MySQL 5.0 is determined by the maximum row size and the
character set you use. The maximum effective length is 65,532 bytes.)
Note: Before 5.0.3, trailing spaces were removed when
VARCHAR values were stored, which differs from the standard SQL
specification.
From MySQL 4.1.0 to 5.0.2, a VARCHAR column with a length
specification greater than 255 is converted to the smallest TEXT
type that can hold values of the given length. For example,
VARCHAR(500) is converted to TEXT, and
VARCHAR(200000) is converted to MEDIUMTEXT. This is a
compatibility feature. However, this conversion affects trailing-space
removal.
VARCHAR is shorthand for CHARACTER VARYING.
As of MySQL 4.1.2, the BINARY attribute is shorthand for specifying
the binary collation of the column character set. Sorting and comparison is
based on numeric character values. Before 4.1.2, BINARY attribute
causes the column to be treated as a binary string. Sorting and comparison
is based on numeric byte values.
Starting from MySQL 5.0.3, VARCHAR is stored with a one-byte or
two-byte length prefix + data. The length prefix is two bytes if the
VARCHAR column is declared with a length greater than 255.
BINARY(M)
BINARY type is similar to the CHAR type, but stores
binary byte strings rather than non-binary character strings.
This type was added in MySQL 4.1.2.
VARBINARY(M)
VARBINARY type is similar to the VARCHAR type, but stores
binary byte strings rather than non-binary character strings.
This type was added in MySQL 4.1.2.
TINYBLOB
BLOB column with a maximum length of 255
(2^8 - 1) bytes.
TINYTEXT
TEXT column with a maximum length of 255
(2^8 - 1) characters.
BLOB
BLOB column with a maximum length of 65,535
(2^16 - 1) bytes.
TEXT
TEXT column with a maximum length of 65,535
(2^16 - 1) characters.
MEDIUMBLOB
BLOB column with a maximum length of 16,777,215
(2^24 - 1) bytes.
MEDIUMTEXT
TEXT column with a maximum length of 16,777,215
(2^24 - 1) characters.
LONGBLOB
BLOB column with a maximum length of 4,294,967,295 or
4GB (2^32 - 1) bytes. Up to MySQL
3.23, the client/server protocol and MyISAM tables had a limit
of 16MB per communication packet / table row. From MySQL 4.0, the maximum
allowed length of LONGBLOB columns depends on the
configured maximum packet size in the client/server protocol and available
memory.
LONGTEXT
TEXT column with a maximum length of 4,294,967,295 or
4GB (2^32 - 1) characters. Up to MySQL
3.23, the client/server protocol and MyISAM tables had a limit
of 16MB per communication packet / table row. From MySQL 4.0, the maximum
allowed length of LONGTEXT columns depends on the
configured maximum packet size in the client/server protocol and available
memory.
ENUM('value1','value2',...)
'value1', 'value2', ...,
NULL or the special '' error value. An ENUM column can
have a maximum of 65,535 distinct values.
ENUM values are represented internally as integers.
SET('value1','value2',...)
'value1', 'value2',
... A SET column can have a maximum of 64 members.
SET values are represented internally as integers.
MySQL supports all of the standard SQL numeric data types. These
types include the exact numeric data types (INTEGER,
SMALLINT, DECIMAL, and NUMERIC), as well as the
approximate numeric data types (FLOAT, REAL, and
DOUBLE PRECISION). The keyword INT is a synonym for
INTEGER, and the keyword DEC is a synonym for
DECIMAL.
As of MySQL 5.0.3, a BIT data type is available for storing bit-field
values. (Before 5.0.3, MySQL interprets BIT as TINYINT(1).)
Currently, BIT is supported only for MyISAM.
As an extension to the SQL standard, MySQL also supports the integer types
TINYINT, MEDIUMINT, and BIGINT. The following table
shows the required storage and range for each of the integer types.
| Type | Bytes | Minimum Value | Maximum Value |
| (Signed/Unsigned) | (Signed/Unsigned) | ||
TINYINT | 1 | -128 | 127
|
0 | 255
| ||
SMALLINT | 2 | -32768 | 32767
|
0 | 65535
| ||
MEDIUMINT | 3 | -8388608 | 8388607
|
0 | 16777215
| ||
INT | 4 | -2147483648 | 2147483647
|
0 | 4294967295
| ||
BIGINT | 8 | -9223372036854775808 | 9223372036854775807
|
0 | 18446744073709551615
|
Another extension is supported by MySQL for optionally
specifying the display width of an integer value in parentheses following
the base keyword for the type (for example, INT(4)). This optional
display width specification is used to left-pad the display of values
having a width less than the width specified for the column.
The display width does not constrain the range of values that can be stored in the column, nor the number of digits that are displayed for values having a width exceeding that specified for the column.
When used in conjunction with the optional extension attribute
ZEROFILL, the default padding of spaces is replaced with zeros.
For example, for a column declared as INT(5) ZEROFILL, a value
of 4 is retrieved as 00004. Note that if you store larger
values than the display width in an integer column, you may experience
problems when MySQL generates temporary tables for some
complicated joins, because in these cases MySQL trusts that the
data did fit into the original column width.
All integer types can have an optional (non-standard) attribute
UNSIGNED. Unsigned values can be used when you want to allow only
non-negative numbers in a column and you need a bigger upper numeric
range for the column.
As of MySQL 4.0.2, floating-point and fixed-point types also can be
UNSIGNED. As with integer types, this attribute prevents negative
values from being stored in the column. However, unlike the integer types,
the upper range of column values remains the same.
If you specify ZEROFILL for a numeric column, MySQL
automatically adds the UNSIGNED attribute to the column.
For floating-point column types, MySQL uses four bytes for single-precision values and eight bytes for double-precision values.
The FLOAT type is used to represent approximate numeric data types.
The SQL standard allows an optional specification of the precision
(but not the range of the exponent) in bits following the keyword
FLOAT in parentheses. The MySQL implementation also supports this
optional precision specification, but the precision value is used only to
determine storage size. A precision from 0 to 23 results in four-byte
single-precision FLOAT column. A precision from 24 to 53 results
in eight-byte double-precision DOUBLE column.
When the keyword
FLOAT is used for a column type without a precision specification,
MySQL uses four bytes to store the values. MySQL also supports variant
syntax with two numbers given in parentheses following the FLOAT
keyword. The first number represents the display width
and the second number specifies the number of digits to be stored and
displayed following the decimal point (as with DECIMAL and
NUMERIC). When MySQL is asked to store a number for
such a column with more decimal digits following the decimal point than
specified for the column, the value is rounded to eliminate the extra
digits when the value is stored.
In standard SQL, the REAL and DOUBLE PRECISION types do not accept
precision specifications. MySQL supports a variant syntax with two numbers
given in parentheses following the type name. The first number represents
the display width and the second number specifies the number of digits to
be stored and displayed following the decimal point.
As an extension to the SQL standard, MySQL recognizes DOUBLE
as a synonym for the DOUBLE PRECISION type. In contrast with the
standard's requirement that the precision for REAL be smaller than
that used for DOUBLE PRECISION, MySQL implements both as eight-byte
double-precision floating-point values (unless the server SQL mode
includes the REAL_AS_FLOAT option).
For maximum portability, code requiring storage of approximate numeric
data values should use FLOAT or DOUBLE PRECISION with no
specification of precision or number of decimal points.
The DECIMAL and NUMERIC types are implemented as the same
type by MySQL. They are
used to store values for which it is important to preserve exact precision,
for example with monetary data. When declaring a column of one of these
types, the precision and scale can be (and usually is) specified; for
example:
salary DECIMAL(5,2)
In this example, 5 is the precision and 2 is the scale. The
precision represents the number of significant decimal digits that are
stored for values, and the scale represents the number of digits that
can be stored following the decimal point.
MySQL stores DECIMAL and NUMERIC values as strings, rather
than as binary floating-point numbers, in order to preserve the decimal
precision of those values. One character is used for each digit of the
value, the decimal point (if the scale is greater than 0), and the `-' sign
(for negative numbers). If the scale is 0, DECIMAL and
NUMERIC values contain no decimal point or fractional part.
Standard SQL requires that the salary column
be able to store any value with five digits and two decimals. In this case,
therefore, the range of values that can be stored in the salary
column is from -999.99 to 999.99. MySQL varies from this in
two ways:
9999.99. For positive numbers, MySQL uses the
byte reserved for the sign to extend the upper end of the range.
DECIMAL columns in MySQL before 3.23 are stored differently and
cannot represent all the values required by standard SQL. This is because
for a type of DECIMAL(M,D), the value of M includes the bytes
for the sign and the decimal point. The range of the salary column
before MySQL 3.23 would be -9.99 to 99.99.
In standard SQL, the syntax DECIMAL(M) is equivalent to
DECIMAL(M,0). Similarly, the syntax DECIMAL is equivalent
to DECIMAL(M,0), where the implementation is allowed to decide the
value of M. As of MySQL 3.23.6, both of these variant forms of the
DECIMAL and NUMERIC data types are supported. The default value
of M is 10. Before 3.23.6,
M and D both must be specified explicitly.
The maximum range of DECIMAL and NUMERIC values is the
same as for DOUBLE, but the actual range for a given
DECIMAL or NUMERIC column can be constrained by the
precision or scale for a given column. When such a column
is assigned a value with more digits following the decimal point than
are allowed by the specified scale, the value is converted to that
scale. (The precise behavior is operating system-specific, but
generally the effect is truncation to the allowable number of digits.)
As of MySQL 5.0.3, the BIT data type can be used to store bit-field
values. A type of BIT(M) allows for storage of M-bit
values. M can range from 1 to 64.
To specify bit values, b'value' notation can be used.
value is a binary value written using 0s and 1s. For example,
b'111' and b'100000000' represent 7 and 128, respectively.
See section 9.1.5 Bit-Field Values.
When asked to store a value in a numeric column that is outside the column type's allowable range, MySQL clips the value to the appropriate endpoint of the range and stores the resulting value instead.
For example, the range of an INT column is -2147483648
to 2147483647. If you try to insert -9999999999 into an
INT column, MySQL clips the value to the lower endpoint of the
range and stores -2147483648 instead. Similarly, if you try to
insert 9999999999, MySQL clips the value to the upper endpoint of
the range and stores 2147483647 instead.
If the INT column is UNSIGNED, the size of the column's
range is the same but its endpoints shift up to 0 and 4294967295.
If you try to store -9999999999 and 9999999999,
the values stored in the column are 0 and 4294967296.
When a floating-point or fixed-point column is assigned a value that exceeds the range implied by the specified (or default) precision and scale, MySQL stores the value representing the corresponding end point of that range.
Conversions that occur due to clipping are reported as ``warnings'' for
ALTER TABLE, LOAD DATA INFILE, UPDATE, and
multiple-row INSERT statements.
The date and time types for representing temporal values are DATETIME, DATE,
TIMESTAMP, TIME, and YEAR. Each temporal type has a
range of legal values, as well as a ``zero'' value that is used when you
specify an illegal value that MySQL cannot represent. The TIMESTAMP
type has special automatic updating behavior, described later on.
Starting from MySQL 5.0.2, MySQL gives warnings/errors if you try to insert
an illegal date. You can get MySQL to accept certain dates, such as
'1999-11-31', by using the ALLOW_INVALID_DATES SQL mode.
(Before 5.0.2, this mode was the default behavior for MySQL).
This is useful when you want to store the ``possibly wrong'' value the user has
specified (for example, in a web form) in the database for future processing.
Under this mode, MySQL verifies only that the month is in the range from 0
to 12 and that the day is in the range from 0 to 31. These ranges
are defined to include zero because MySQL allows you to store dates where the
day or month and day are zero in a DATE or DATETIME column.
This is extremely useful for applications that need to store a birthdate for
which you don't know the exact date. In this case, you simply store the date
as '1999-00-00' or '1999-01-00'. If you store dates such as
these, you should not expect to get correct results for functions such as
DATE_SUB() or DATE_ADD that require complete dates. (If you
don't want to allow zero in dates, you can use the NO_ZERO_IN_DATE
SQL mode).
MySQL also allows you to store '0000-00-00' as a ``dummy date''
(if you are not using the NO_ZERO_DATE SQL mode). This is in some
cases is more convenient (and uses less space in data and index) than
using NULL values.
By setting the sql_mode system variable to the appropriate mode
values, You can more exactly what kind of dates you want MySQL to support.
See section 5.2.2 The Server SQL Mode.
Here are some general considerations to keep in mind when working with date and time types:
00-69 are converted to 2000-2069.
70-99 are converted to 1970-1999.
'98-09-04'), rather than
in the month-day-year or day-month-year orders commonly used elsewhere (for
example, '09-04-98', '04-09-98').
TIME values are clipped to the
appropriate endpoint of the TIME range.
The following table shows the format of the ``zero'' value for each
type. Note that the use of these values produces warnings if the
NO_ZERO_DATE SQL mode is enabled.
| Column Type | ``Zero'' Value |
DATETIME | '0000-00-00 00:00:00'
|
DATE | '0000-00-00'
|
TIMESTAMP | 00000000000000
|
TIME | '00:00:00'
|
YEAR | 0000
|
'0' or 0, which are easier to write.
NULL in MyODBC 2.50.12 and above,
because ODBC can't handle such values.
DATETIME, DATE, and TIMESTAMP Types
The DATETIME, DATE, and TIMESTAMP types are related.
This section describes their characteristics, how they are similar, and how
they differ.
The DATETIME type is used when you need values that contain both date
and time information. MySQL retrieves and displays DATETIME
values in 'YYYY-MM-DD HH:MM:SS' format. The supported range is
'1000-01-01 00:00:00' to '9999-12-31 23:59:59'. (``Supported''
means that although earlier values might work, there is no guarantee)
The DATE type is used when you need only a date value, without a time
part. MySQL retrieves and displays DATE values in
'YYYY-MM-DD' format. The supported range is '1000-01-01' to
'9999-12-31'.
The TIMESTAMP column type has varying properties,
depending on the MySQL version and the SQL mode the server is running in.
These properties are described later in this section.
You can specify DATETIME, DATE, and TIMESTAMP values using
any of a common set of formats:
'YYYY-MM-DD HH:MM:SS' or 'YY-MM-DD
HH:MM:SS' format. A ``relaxed'' syntax is allowed: Any punctuation
character may be used as the delimiter between date parts or time parts.
For example, '98-12-31 11:30:45', '98.12.31 11+30+45',
'98/12/31 11*30*45', and '98@12@31 11^30^45' are
equivalent.
'YYYY-MM-DD' or 'YY-MM-DD' format.
A ``relaxed'' syntax is allowed here, too. For example, '98-12-31',
'98.12.31', '98/12/31', and '98@12@31' are
equivalent.
'YYYYMMDDHHMMSS' or
'YYMMDDHHMMSS' format, provided that the string makes sense as a
date. For example, '19970523091528' and '970523091528' are
interpreted as '1997-05-23 09:15:28', but '971122129015' is
illegal (it has a nonsensical minute part) and becomes '0000-00-00
00:00:00'.
'YYYYMMDD' or 'YYMMDD'
format, provided that the string makes sense as a date. For example,
'19970523' and '970523' are interpreted as
'1997-05-23', but '971332' is illegal (it has nonsensical month
and day parts) and becomes '0000-00-00'.
YYYYMMDDHHMMSS or YYMMDDHHMMSS
format, provided that the number makes sense as a date. For example,
19830905132800 and 830905132800 are interpreted as
'1983-09-05 13:28:00'.
YYYYMMDD or YYMMDD
format, provided that the number makes sense as a date. For example,
19830905 and 830905 are interpreted as '1983-09-05'.
DATETIME, DATE, or TIMESTAMP context, such as
NOW() or CURRENT_DATE.
Illegal DATETIME, DATE, or TIMESTAMP values are converted
to the ``zero'' value of the appropriate type ('0000-00-00 00:00:00',
'0000-00-00', or 00000000000000).
For values specified as strings that include date part delimiters, it is not
necessary to specify two digits for month or day values that are less than
10. '1979-6-9' is the same as '1979-06-09'. Similarly,
for values specified as strings that include time part delimiters, it is not
necessary to specify two digits for hour, minute, or second values that are
less than 10. '1979-10-30 1:2:3' is the same as
'1979-10-30 01:02:03'.
Values specified as numbers should be 6, 8, 12, or 14 digits long. If a
number is 8 or 14 digits long, it is assumed to be in YYYYMMDD or
YYYYMMDDHHMMSS format and that the year is given by the first 4
digits. If the number is 6 or 12 digits long, it is assumed to be in
YYMMDD or YYMMDDHHMMSS format and that the year is given by the
first 2 digits. Numbers that are not one of these lengths are interpreted
as though padded with leading zeros to the closest length.
Values specified as non-delimited strings are interpreted using their length
as given. If the string is 8 or 14 characters long, the year is assumed to
be given by the first 4 characters. Otherwise, the year is assumed to be
given by the first 2 characters. The string is interpreted from left to
right to find year, month, day, hour, minute, and second values, for as many
parts as are present in the string. This means you should not use strings
that have fewer than 6 characters. For example, if you specify '9903',
thinking that represents March, 1999, MySQL
inserts a ``zero'' date into your table. This is because the year and month
values are 99 and 03, but the day part is completely missing, so
the value is not a legal date. However, as of MySQL 3.23, you can explicitly
specify a value of zero to represent missing month or day parts. For example,
you can use '990300' to insert the value '1999-03-00'.
You can to some extent assign values of one date type to an object of a different date type. However, there may be some alteration of the value or loss of information:
DATE value to a DATETIME or TIMESTAMP
object, the time part of the resulting value is set to '00:00:00'
because the DATE value contains no time information.
DATETIME or TIMESTAMP value to a DATE
object, the time part of the resulting value is deleted because the
DATE type stores no time information.
DATETIME, DATE, and TIMESTAMP
values all can be specified using the same set of formats, the types do not
all have the same range of values. For example, TIMESTAMP values
cannot be earlier than 1970 or later than 2037. This means
that a date such as '1968-01-01', while legal as a DATETIME or
DATE value, is not a valid TIMESTAMP value and is
converted to 0 if assigned to such an object.
Be aware of certain pitfalls when specifying date values:
'10:11:12' might look like a time value
because of the `:' delimiter, but if used in a date context is
interpreted as the year '2010-11-12'. The value '10:45:15'
is converted to '0000-00-00' because '45' is not a legal
month.
'0000-00-00'. Please note that this still allows you to store
invalid dates such as '2002-04-31'. To ensure that a date is valid,
perform a check in your application.
00-69 are converted to 2000-2069.
70-99 are converted to 1970-1999.
TIMESTAMP Properties Prior to MySQL 4.1
The TIMESTAMP column type provides a type that you can use to
automatically mark INSERT or UPDATE operations with the current
date and time. If you have multiple TIMESTAMP columns in a table,
only the first one is updated automatically. (From MySQL 4.1.2 on, you can
specify which TIMESTAMP column updates;
see section 11.3.1.2 TIMESTAMP Properties as of MySQL 4.1.)
Automatic updating of the first TIMESTAMP column in a table occurs
under any of the following conditions:
NULL.
INSERT or
LOAD DATA INFILE statement.
UPDATE statement and some
other column changes value. An UPDATE that sets a column
to the value it does not cause the TIMESTAMP column to be
updated; if you set a column to its current value, MySQL
ignores the update for efficiency.
TIMESTAMP columns other than the first can also be set to the current
date and time. Just set the column to NULL or to any function that
produces the current date and time (NOW(), CURRENT_TIMESTAMP).
You can set any TIMESTAMP column to a value different from the current
date and time by setting it explicitly to the desired value. This is true
even for the first TIMESTAMP column. You can use this property if,
for example, you want a TIMESTAMP to be set to the current date and
time when you create a row, but not to be changed whenever the row is updated
later:
TIMESTAMP column explicitly to its current value:
UPDATE tbl_name
SET timestamp_col = timestamp_col,
other_col1 = new_value1,
other_col2 = new_value2, ...
Another way to maintain a column that records row-creation time is to use
a DATETIME column that you initialize to NOW() when the row
is created and leave alone for subsequent updates.
TIMESTAMP values may range from the beginning of 1970 to partway
through the year 2037, with a resolution of one second. Values are displayed
as numbers. When you store a value in a TIMESTAMP column, it is
assumed to be represented in the current time zone, and is converted to
UTC for storage. When you retrieve the value, it is converted from UTC
back to the local time zone for display. Before MySQL 4.1.3, the server
has a single time zone. As of 4.1.3, clients can set their time zone on
a per-connection basis, as described in Time zone support.
The format in which MySQL retrieves and displays TIMESTAMP
values depends on the display size, as illustrated by the following table. The
``full'' TIMESTAMP format is 14 digits, but TIMESTAMP columns may
be created with shorter display sizes:
| Column Type | Display Format |
TIMESTAMP(14) | YYYYMMDDHHMMSS
|
TIMESTAMP(12) | YYMMDDHHMMSS
|
TIMESTAMP(10) | YYMMDDHHMM
|
TIMESTAMP(8) | YYYYMMDD
|
TIMESTAMP(6) | YYMMDD
|
TIMESTAMP(4) | YYMM
|
TIMESTAMP(2) | YY
|
All TIMESTAMP columns have the same storage size, regardless of
display size. The most common display sizes are 6, 8, 12, and 14. You can
specify an arbitrary display size at table creation time, but values of 0 or
greater than 14 are coerced to 14. Odd-valued sizes in the range from 1 to
13 are coerced to the next higher even number.
TIMESTAMP columns store legal values using the full precision with
which the value was specified, regardless of the display size. This has
several implications:
TIMESTAMP(4) or TIMESTAMP(2). Otherwise, the value is not
a legal date and 0 is stored.
ALTER TABLE to widen a narrow TIMESTAMP column,
information is displayed that previously was ``hidden.''
TIMESTAMP column does not cause information to
be lost, except in the sense that less information is shown when the values
are displayed.
mysqldump for the database, do not
use TIMESTAMP(4) or TIMESTAMP(2). The display format
for these column types are not legal dates and 0 will be stored
instead. This inconsistency is fixed starting with MySQL 4.1, where
display width is ignored. To prepare for transition to versions after
4.0, you should change to use display widths of 6 or more, which will
produce a legal display format. You can change the display width of
TIMESTAMP column types, without losing any information, by
using ALTER TABLE as indicated above.
If you need to print the timestamps for external applications, you can
use MID() to extract the relevant part of the timestamp: for
example, to imitate the TIMESTAMP(4) display format.
TIMESTAMP values are stored to full precision, the only
function that operates directly on the underlying stored value is
UNIX_TIMESTAMP(). Other functions operate on the formatted retrieved
value. This means you cannot use a function such as HOUR() or
SECOND() unless the relevant part of the TIMESTAMP value is
included in the formatted value. For example, the HH part of a
TIMESTAMP column is not displayed unless the display size is at least
10, so trying to use HOUR() on shorter TIMESTAMP values
produces a meaningless result.
TIMESTAMP Properties as of MySQL 4.1
In MySQL 4.1 and up, the properties of the TIMESTAMP column type change
in the ways described in this section.
From MySQL 4.1.0 on, TIMESTAMP display format differs from that of
earlier MySQL releases:
TIMESTAMP columns are displayed in the same format as DATETIME
columns.
TIMESTAMP(2),
TIMESTAMP(4), and so on, the display width is ignored.
Beginning with MySQL 4.1.1, the MySQL server can be run in MAXDB
mode. When the server runs in this mode, TIMESTAMP is identical
with DATETIME. That is, if the server is running in MAXDB
mode at the time that a table is created, TIMESTAMP columns
are created as DATETIME columns. As a result, such columns use
DATETIME display format, have the same range of values, and there is
no automatic initialization or updating to the current date and time.
To enable MAXDB mode,
set the server SQL mode to MAXDB at startup using the
--sql-mode=MAXDB server option or by setting the global
sql_mode variable at runtime:
mysql> SET GLOBAL sql_mode=MAXDB;
A client can cause the server to run in MAXDB mode for its own
connection as follows:
mysql> SET SESSION sql_mode=MAXDB;
As of MySQL 5.0.2, MySQL does not accept timestamp values that include
a zero in the day or month column or values that are not a valid date.
(The exception is the special value '0000-00-00 00:00:00'.)
Beginning with MySQL 4.1.2, you have more flexible control over when
automatic TIMESTAMP initialization and updating occur and which
column should have those behaviors:
TIMESTAMP column to automatically initialize
or update to the current date and time. This no longer need be the first
TIMESTAMP column.
The following discussion describes the revised syntax and behavior.
Note that this information applies only to TIMESTAMP columns for
tables not created with MAXDB mode enabled. As noted earlier in
this section, MAXDB mode causes columns to be created as
DATETIME columns.
The following items summarize the pre-4.1.2 properties for TIMESTAMP
initialization and updating:
The first TIMESTAMP column in table row automatically is set to
the current timestamp when the record is created if the column is set to
NULL or is not specified at all.
The first TIMESTAMP column in table row automatically is updated
to the current timestamp when the value of any other column in the row
is changed, unless the TIMESTAMP column explicitly is assigned a
value other than NULL.
If a DEFAULT value is specified for the first TIMESTAMP
column when the table is created, it is silently ignored.
Other TIMESTAMP columns in the table can be set to the current
TIMESTAMP by assigning NULL to them, but they do not update
automatically.
As of 4.1.2, you have more flexibility in deciding which TIMESTAMP
column automatically is initialized and updated to the current timestamp.
The rules are as follows:
If a DEFAULT value is specified for the first TIMESTAMP column
in a table, it is not ignored. The default can be CURRENT_TIMESTAMP
or a constant date and time value.
DEFAULT NULL is the same as DEFAULT CURRENT_TIMESTAMP for
the first TIMESTAMP column. For any other TIMESTAMP
column, DEFAULT NULL is treated as DEFAULT 0.
Any single TIMESTAMP column in a table can be set to be the one that
is initialized to the current timestamp and/or updated automatically.
In a CREATE TABLE statement, the first TIMESTAMP column can
be declared in any of the following ways:
DEFAULT CURRENT_TIMESTAMP and ON UPDATE
CURRENT_TIMESTAMP clauses, the column has the current timestamp for its
default value, and is automatically updated.
DEFAULT nor ON UPDATE clauses, it is the same
as DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP.
DEFAULT CURRENT_TIMESTAMP clause and no ON UPDATE
clause, the column has the current timestamp for its default value but is
not automatically updated.
DEFAULT clause and with an ON UPDATE CURRENT_TIMESTAMP
clause, the column has a default of 0 and is automatically updated.
DEFAULT value, the column has the given default. If
the column has an ON UPDATE CURRENT_TIMESTAMP clause, it is
automatically updated, otherwise not.
In other words, you can use the current timestamp for both the initial
value and the auto-update value, or either one, or neither. (For example,
you can specify ON UPDATE to get auto-update without also having
the column auto-initialized.)
Any of CURRENT_TIMESTAMP, CURRENT_TIMESTAMP(), or NOW()
can be used in the DEFAULT and ON UPDATE clauses. They
all have the same effect.
The order of the two attributes does not matter. If both DEFAULT
and ON UPDATE are specified for a TIMESTAMP column, either
can precede the other.
Example. These statements are equivalent:
CREATE TABLE t (ts TIMESTAMP);
CREATE TABLE t (ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP);
CREATE TABLE t (ts TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
DEFAULT CURRENT_TIMESTAMP);
To specify automatic default or updating for a TIMESTAMP column other
than the first one, you must suppress the automatic initialization and update behaviors
for the first TIMESTAMP column by explicitly assigning it a constant
DEFAULT value (for example, DEFAULT 0 or DEFAULT
'2003-01-01 00:00:00'). Then for the other TIMESTAMP column, the
rules are the same as for the first TIMESTAMP column, except that
you cannot omit both of the DEFAULT and ON UPDATE clauses.
If you do that, no automatic initialization or updating occurs.
Example. These statements are equivalent:
CREATE TABLE t (
ts1 TIMESTAMP DEFAULT 0,
ts2 TIMESTAMP DEFAULT CURRENT_TIMESTAMP
ON UPDATE CURRENT_TIMESTAMP);
CREATE TABLE t (
ts1 TIMESTAMP DEFAULT 0,
ts2 TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
DEFAULT CURRENT_TIMESTAMP);
Beginning with MySQL 4.1.3, you can set the current time zone on a
per-connection basis, as described in Time zone support.
TIMESTAMP values still are stored in UTC, but are converted
from the current time zone for storage, and converted back to the
current time zone for retrieval. As long as the time zone setting
remains the same, you get back the same value you store. If you
store a TIMESTAMP value, then change the time zone and
retrieve the value, it is different than the value you stored.
This occurs because the same time zone is not used for conversion in
both directions. The current time zone is available as the value of
the time_zone system variable.
Beginning with MySQL 4.1.6, you can include the NULL attribute
in the definition of a TIMESTAMP column to allow the column
to contain NULL values. For example:
CREATE TABLE t ( ts1 TIMESTAMP NULL DEFAULT NULL, ts2 TIMESTAMP NULL DEFAULT 0, ts3 TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP );
Before MySQL 4.1.6 (and even as of 4.1.6 if the NULL attribute is not
specified), setting the column to NULL sets it to the current
timestamp.
TIME Type
MySQL retrieves and displays TIME values in 'HH:MM:SS'
format (or 'HHH:MM:SS' format for large hours values). TIME
values may range from '-838:59:59' to '838:59:59'. The reason
the hours part may be so large is that the TIME type may be used not
only to represent a time of day (which must be less than 24 hours), but also
elapsed time or a time interval between two events (which may be much greater
than 24 hours, or even negative).
You can specify TIME values in a variety of formats:
'D HH:MM:SS.fraction' format.
You can also use one of the following ``relaxed'' syntaxes:
'HH:MM:SS.fraction', 'HH:MM:SS', 'HH:MM', 'D
HH:MM:SS', 'D HH:MM', 'D HH', or 'SS'. Here D
represents days and can have a value from 0 to 34.
Note that MySQL doesn't yet store the fraction part.
'HHMMSS' format, provided that
it makes sense as a time. For example, '101112' is understood as
'10:11:12', but '109712' is illegal (it has a nonsensical
minute part) and becomes '00:00:00'.
HHMMSS format, provided that it makes sense as a time.
For example, 101112 is understood as '10:11:12'. The following
alternative formats are also understood: SS, MMSS, HHMMSS,
HHMMSS.fraction. Note that MySQL doesn't yet store the
fraction part.
TIME context, such as CURRENT_TIME.
For TIME values specified as strings that include a time part
delimiter, it is not necessary to specify two digits for hours, minutes, or
seconds values that are less than 10. '8:3:2' is the same as
'08:03:02'.
Be careful about assigning ``short'' TIME values to a TIME
column. Without colons, MySQL interprets values using the
assumption that the rightmost digits represent seconds. (MySQL
interprets TIME values as elapsed time rather than as time of
day.) For example, you might think of '1112' and 1112 as
meaning '11:12:00' (12 minutes after 11 o'clock), but
MySQL interprets them as '00:11:12' (11 minutes, 12 seconds).
Similarly, '12' and 12 are interpreted as '00:00:12'.
TIME values with colons, by contrast, are always treated as
time of the day. That is '11:12' mean '11:12:00',
not '00:11:12'.
Values that lie outside the TIME range
but are otherwise legal are clipped to the closest
endpoint of the range. For example, '-850:00:00' and
'850:00:00' are converted to '-838:59:59' and
'838:59:59'.
Illegal TIME values are converted to '00:00:00'. Note that
because '00:00:00' is itself a legal TIME value, there is no way
to tell, from a value of '00:00:00' stored in a table, whether the
original value was specified as '00:00:00' or whether it was illegal.
YEAR Type
The YEAR type is a one-byte type used for representing years.
MySQL retrieves and displays YEAR values in YYYY
format. The range is 1901 to 2155.
You can specify YEAR values in a variety of formats:
'1901' to '2155'.
1901 to 2155.
'00' to '99'. Values in the
ranges '00' to '69' and '70' to '99' are
converted to YEAR values in the ranges 2000 to 2069 and
1970 to 1999.
1 to 99. Values in the
ranges 1 to 69 and 70 to 99 are converted to
YEAR values in the ranges 2001 to 2069 and 1970
to 1999. Note that the range for two-digit numbers is slightly
different from the range for two-digit strings, because you cannot specify zero
directly as a number and have it be interpreted as 2000. You
must specify it as a string '0' or '00' or it is
interpreted as 0000.
YEAR context, such as NOW().
Illegal YEAR values are converted to 0000.
MySQL itself is year 2000 (Y2K) safe (see section 1.2.5 Year 2000 Compliance), but input values presented to MySQL may not be. Any input containing two-digit year values is ambiguous, because the century is unknown. Such values must be interpreted into four-digit form because MySQL stores years internally using four digits.
For DATETIME, DATE, TIMESTAMP, and YEAR types,
MySQL interprets dates with ambiguous year values using the
following rules:
00-69 are converted to 2000-2069.
70-99 are converted to 1970-1999.
Remember that these rules provide only reasonable guesses as to what your data values mean. If the heuristics used by MySQL do not produce the correct values, you should provide unambiguous input containing four-digit year values.
ORDER BY properly sorts TIMESTAMP or YEAR values that
have two-digit years.
Some functions like MIN() and MAX() convert a
TIMESTAMP or YEAR to a number. This means that a value with a
two-digit year does not work properly with these functions. The fix in this
case is to convert the TIMESTAMP or YEAR to four-digit year
format or use something like MIN(DATE_ADD(timestamp,INTERVAL 0
DAYS)).
The string types are CHAR, VARCHAR, BINARY,
VARBINARY, BLOB, TEXT, ENUM, and SET.
This section describes how these types work and how to use them in your
queries.
CHAR and VARCHAR Types
The CHAR and VARCHAR types are similar, but differ in the
way they are stored and retrieved. As of MySQL 5.0.3, they also differ in
maximum length and in whether trailing spaces are retained.
The CHAR and VARCHAR types are declared with a length that
indicates the maximum number of characters you want to store. For example,
CHAR(30) can hold up to 30 characters. (Before MySQL 4.1, the length
is interpreted as number of bytes.)
The length of a CHAR column is fixed to the length that you declare
when you create the table. The length can be any value from 0 to 255.
(Before MySQL 3.23, the length of CHAR may be from 1 to 255.)
When CHAR values are stored, they are right-padded with spaces to the
specified length. When CHAR values are retrieved, trailing spaces are
removed.
Values in VARCHAR columns are variable-length strings. The length
can be specified as 1 to 255 before MySQL 4.0.2, 0 to 255 as of MySQL 4.0.2,
and 0 to 65,535 as of MySQL 5.0.3. (The maximum actual length of a
VARCHAR in MySQL 5.0 is determined by the maximum row size and the
character set you use. The maximum effective length is 65,532 bytes.)
In contrast to CHAR, VARCHAR values are stored using only as
many characters as are needed, plus one byte to record the length (two bytes
for columns that are declared with a length longer than 255).
VARCHAR values are not padded when they are stored. Handling of
trailing spaces is version-dependent. As of MySQL 5.0.3, trailing spaces are
retained when values are stored and retrieved, in conformance with standard
SQL. Before MySQL 5.0.3, trailing spaces are removed from values when they
are stored into a VARCHAR column; this means the spaces also are absent
from retrieved values.
No lettercase conversion takes place during storage or retrieval.
If you assign a value to a CHAR or VARCHAR column that
exceeds the column's maximum length, the value is truncated to fit.
If the truncated characters are not spaces, a warning is generated.
You can cause an error to occur rather than an warning by using ``strict''
SQL mode.
See section 5.2.2 The Server SQL Mode.
Before MySQL 5.0.3, if you need a data type for which trailing spaces are
not removed, consider using a BLOB or TEXT type. Also,
if you want to store binary values such as results from an encryption
or compression function that might contain arbitrary byte values, use a
BLOB column rather than a CHAR or VARCHAR column, to
avoid potential problems with trailing space removal that would change
data values.
The following table illustrates the differences between the two types of columns
by showing the result of storing various string values into CHAR(4)
and VARCHAR(4) columns:
| Value | CHAR(4) | Storage Required | VARCHAR(4) | Storage Required |
'' | ' ' | 4 bytes | '' | 1 byte |
'ab' | 'ab ' | 4 bytes | 'ab' | 3 bytes |
'abcd' | 'abcd' | 4 bytes | 'abcd' | 5 bytes |
'abcdefgh' | 'abcd' | 4 bytes | 'abcd' | 5 bytes |
The values retrieved from the CHAR(4) and VARCHAR(4) columns
are the same in each case, because trailing spaces are removed from
CHAR columns upon retrieval.
As of MySQL 4.1, values in CHAR and VARCHAR columns are sorted
and compared according to the collation of the character set assigned to
the column. Before MySQL 4.1, sorting and comparison are based on
the collation of the server character set; you can declare the column
with the BINARY attribute to cause sorting and comparison to be based
on the numeric values of the bytes in column values. BINARY doesn't
affect how column values are stored or retrieved.
The BINARY attribute is sticky. This means that if a column marked
BINARY is used in an expression, the whole expression is treated as a
BINARY value.
From MySQL 4.1.0 on, column type CHAR BYTE is an alias for
CHAR BINARY. This is a compatibility feature.
From MySQL 4.1.0 on, the ASCII attribute can be specified for
CHAR. It assigns the latin1 character set.
From MySQL 4.1.1 on, the UNICODE attribute can be specified for
CHAR. It assigns the ucs2 character set.
MySQL may silently change the type of a CHAR or VARCHAR
column at table creation time.
See section 13.2.6.1 Silent Column Specification Changes.
BINARY and VARBINARY Types
The BINARY and VARBINARY types are similar to CHAR and
VARCHAR, except that they contain binary strings rather than
non-binary strings. That is, they contain byte strings rather than character
strings. This means they have no character set, and sorting and comparison
is based on the numeric values of the bytes in column values.
The allowable maximum length and handling of trailing spaces is the same for
BINARY and VARBINARY as it is for CHAR and
VARCHAR, except that the length for BINARY and VARBINARY
is a length in bytes rather than in characters.
Before MySQL 4.1.2, BINARY(M) and VARBINARY(M) are
treated as CHAR(M) BINARY and VARCHAR(M) BINARY.
As of MySQL 4.1.2, BINARY and VARBINARY are available as distinct
data types, and for CHAR(M) BINARY and VARCHAR(M)
BINARY, the BINARY attribute does not cause the column to be treated
as a binary string column. Instead, it causes the binary collation for the
column character set to be used, but the column itself contains non-binary
character strings rather than binary byte strings. For example, in 4.1
and up, CHAR(5) BINARY is treated as CHAR(5) CHARACTER SET
latin1 COLLATE latin1_bin, assuming that the default character set is
latin1.
BLOB and TEXT Types
A BLOB is a binary large object that can hold a variable amount of
data. The four BLOB types, TINYBLOB, BLOB,
MEDIUMBLOB, and LONGBLOB, differ only in the maximum length of
the values they can hold.
See section 11.5 Column Type Storage Requirements.
The four TEXT types, TINYTEXT, TEXT, MEDIUMTEXT,
and LONGTEXT, correspond to the four BLOB types and have
the same maximum lengths and storage requirements.
BLOB columns are treated as binary strings (byte strings). TEXT
columns are treated as non-binary strings (character strings). BLOB
columns have no character set, and sorting and comparison is based on the
numeric values of the bytes in column values. TEXT columns
have a character set, and values are sorted and compared based on the
collation of the character set assigned to the column as of MySQL 4.1.
Before 4.1, TEXT sorting and comparison are based on the collation
of the server character set.
No lettercase conversion takes place during storage or retrieval.
If you assign a value to a BLOB or TEXT column that exceeds
the column type's maximum length, the value is truncated to fit.
If the truncated characters are not spaces, a warning is generated.
You can cause an error to occur rather than an warning by using ``strict''
SQL mode.
See section 5.2.2 The Server SQL Mode.
In most respects, you can regard a BLOB column as a VARBINARY
column that can be as big as you like. Similarly, you can regard a
TEXT column as a VARCHAR column.
BLOB and TEXT differ from VARBINARY and VARCHAR in
the following ways::
BLOB and TEXT columns
when values are stored or retrieved. Before MySQL 5.0.3, this differs from
VARBINARY and VARCHAR, for which trailing spaces are removed
when values are stored.
Note that TEXT is on comparison space extended to fit the compared
object, exactly like CHAR and VARCHAR.
BLOB and TEXT columns only as of MySQL
3.23.2 for MyISAM tables or MySQL 4.0.14 for InnoDB tables.
Older versions of MySQL did not support indexing these column types.
BLOB and TEXT columns, you must specify an index
prefix length. For CHAR and VARCHAR, a prefix length is
optional.
BLOB and TEXT columns cannot have DEFAULT values.
From MySQL 4.1.0 on, LONG and LONG VARCHAR map to the
MEDIUMTEXT data type. This is a compatibility feature. If you use the
BINARY attribute with a TEXT column type, the column is assigned
the binary collation of the column character set.
MySQL Connector/ODBC defines BLOB values as LONGVARBINARY and
TEXT values as LONGVARCHAR.
Because BLOB and TEXT values may be extremely long, you
may encounter some constraints in using them:
max_sort_length bytes of the
column are used when sorting. The default value of max_sort_length
is 1024; this value can be changed using the --max_sort_length
option when starting the mysqld server.
See section 5.2.3 Server System Variables.
As of MySQL 4.0.3, you can make more bytes significant in sorting or grouping
by increasing the value of max_sort_length at runtime. Any client
can change the value of its session max_sort_length variable:
mysql> SET max_sort_length = 2000;
mysql> SELECT id, comment FROM tbl_name
-> ORDER BY comment;
Another way to use GROUP BY or ORDER BY on a BLOB or
TEXT column containing long values when you want more than
max_sort_length bytes to be significant is to convert the column
value into a fixed-length object. The standard way to do this is with the
SUBSTRING function. For example, the following statement causes
2000 bytes of the comment column to be taken into account for sorting:
mysql> SELECT id, SUBSTRING(comment,1,2000) FROM tbl_name
-> ORDER BY SUBSTRING(comment,1,2000);
Before MySQL 3.23.2, you can group on an expression involving BLOB or
TEXT values by using a column alias or by specifying the column
position:
mysql> SELECT id, SUBSTRING(comment,1,2000) AS b
-> FROM tbl_name GROUP BY b;
mysql> SELECT id, SUBSTRING(comment,1,2000)
-> FROM tbl_name GROUP BY 2;
BLOB or TEXT object is determined by its
type, but the largest value you actually can transmit between the client and
server is determined by the amount of available memory and the size of the
communications buffers. You can change the message buffer size by changing
the value of the
max_allowed_packet variable, but you must
do so for both the server and your client program.
For example, both mysql and mysqldump allow you to change the
client-side
max_allowed_packet value.
See
section 7.5.2 Tuning Server Parameters,
section 8.3 mysql, the Command-Line Tool,
and
section 8.8 The mysqldump Database Backup Program.
Each BLOB or TEXT value is represented
internally by a separately allocated object. This is in contrast to all
other column types, for which storage is allocated once per column when
the table is opened.
ENUM Type
An ENUM is a string object with a value chosen from a list
of allowed values that are enumerated explicitly in the column specification
at table creation time.
The value may also be the empty string ('') or NULL under
certain circumstances:
ENUM (that is, a string not
present in the list of allowed values), the empty string is inserted
instead as a special error value. This string can be distinguished from a
``normal'' empty string by the fact that this string has the numerical value
0. More about this later.
ENUM column is declared to allow NULL, the NULL
value is a legal value for the column, and the default value is NULL.
If an ENUM column is declared NOT NULL, its default value
is the first element of the list of allowed values.
Each enumeration value has an index:
SELECT statement to find rows into which invalid
ENUM values were assigned:
mysql> SELECT * FROM tbl_name WHERE enum_col=0;
NULL value is NULL.
For example, a column specified as ENUM('one', 'two', 'three') can
have any of the values shown here. The index of each value is also shown:
| Value | Index |
NULL | NULL
|
'' | 0 |
'one' | 1 |
'two' | 2 |
'three' | 3 |
An enumeration can have a maximum of 65,535 elements.
Starting from MySQL 3.23.51, trailing spaces are automatically deleted from
ENUM member values when the table is created.
Values stored into an ENUM column are displayed when retrieved using
the lettercase that was used in the column definition. Before MySQL 4.1.1,
lettercase is irrelevant when you assign values to an ENUM column.
As of 4.1.1, ENUM columns can be assigned a character set and
collation. For binary or case-sensitive collations, lettercase does matter
when you assign values to to the column.
If you retrieve an ENUM value in a numeric context, the column value's
index is returned. For example, you can retrieve numeric values from
an ENUM column like this:
mysql> SELECT enum_col+0 FROM tbl_name;
If you store a number into an ENUM column, the number is treated as an
index, and the value stored is the enumeration member with that index.
(However, this does not work with LOAD DATA, which treats all
input as strings.)
It's not advisable to define an ENUM column with enumeration values
that look like numbers, because this can easily become confusing. For example,
the following column has enumeration members with string values of
'0', '1', and '2',
but numeric index values of
1, 2, and 3:
numbers ENUM('0','1','2')
ENUM values are sorted according to the order in which the enumeration
members were listed in the column specification. (In other words,
ENUM values are sorted according to their index numbers.) For
example, 'a' sorts before 'b' for ENUM('a', 'b'), but
'b' sorts before 'a' for ENUM('b', 'a'). The empty
string sorts before non-empty strings, and NULL values sort before
all other enumeration values.
To prevent unexpected results, specify the ENUM list in alphabetical
order. You can also use GROUP BY CAST(col AS VARCHAR) or
GROUP BY CONCAT(col) to make sure that the column
is sorted lexically rather than by index number.
If you want to determine all possible values for an ENUM column,
use SHOW COLUMNS FROM tbl_name LIKE enum_col and parse
the ENUM definition in the second column of the output.
SET Type
A SET is a string object that can have zero or more values, each of
which must be chosen from a list of allowed values specified when the table
is created. SET column values that consist of multiple set members
are specified with members separated by commas (`,'). A consequence of
this is that SET member values cannot themselves contain commas.
For example, a column specified as SET('one', 'two') NOT NULL can have
any of these values:
'' 'one' 'two' 'one,two'
A SET can have a maximum of 64 different members.
Starting from MySQL 3.23.51, trailing spaces are automatically deleted from
SET member values when the table is created.
Values stored into an SET column are displayed when retrieved using
the lettercase that was used in the column definition. Before MySQL 4.1.1,
lettercase is irrelevant when you assign values to an SET column.
As of 4.1.1, SET columns can be assigned a character set and
collation. For binary or case-sensitive collations, lettercase does matter
when you assign values to to the column.
MySQL stores SET values numerically, with the low-order bit
of the stored value corresponding to the first set member. If you retrieve a
SET value in a numeric context, the value retrieved has bits set
corresponding to the set members that make up the column value. For example,
you can retrieve numeric values from a SET column like this:
mysql> SELECT set_col+0 FROM tbl_name;
If a number is stored into a SET column, the bits that
are set in the binary representation of the number determine the
set members in the column value. For a column specified as
SET('a','b','c','d'), the members have the following decimal and
binary values:
SET Member | Decimal Value | Binary Value |
'a' | 1 | 0001
|
'b' | 2 | 0010
|
'c' | 4 | 0100
|
'd' | 8 | 1000
|
If you assign a value of 9 to this column, that is 1001 in
binary, so the first and fourth SET value members 'a' and
'd' are selected and the resulting value is 'a,d'.
For a value containing more than one SET element, it does not matter
what order the elements are listed in when you insert the value. It also
does not matter how many times a given element is listed in the value.
When the value is retrieved later, each element in the value appears
once, with elements listed according to the order in which they were
specified at table creation time. If a column is specified as
SET('a','b','c','d'), then 'a,d', 'd,a', and
'd,a,a,d,d' all appear as 'a,d' when retrieved.
If you set a SET column to an unsupported value, the value
is ignored.
SET values are sorted numerically. NULL values sort before
non-NULL SET values.
Normally, you search for SET values using
the FIND_IN_SET() function or the LIKE operator:
mysql> SELECT * FROM tbl_name WHERE FIND_IN_SET('value',set_col)>0;
mysql> SELECT * FROM tbl_name WHERE set_col LIKE '%value%';
The first statement finds rows where set_col contains the value set member. The second is similar, but not the same: It finds rows where set_col contains value anywhere, even as a substring of another set member.
The following statements also are legal:
mysql> SELECT * FROM tbl_name WHERE set_col & 1; mysql> SELECT * FROM tbl_name WHERE set_col = 'val1,val2';
The first of these statements looks for values containing the first set
member. The second looks for an exact match. Be careful with comparisons
of the second type. Comparing set values to 'val1,val2'
returns different results than comparing values to 'val2,val1'.
You should specify the values in the same order they are listed in the
column definition.
If you want to determine all possible values for a SET column,
use SHOW COLUMNS FROM tbl_name LIKE set_col and parse
the SET definition in the second column of the output.
The storage requirements for each of the column types supported by MySQL are listed by category.
The maximum size of a row in a MyISAM table is 65,534 bytes. Each
BLOB and TEXT column accounts for only five to nine bytes
toward this size.
If a MyISAM or ISAM table includes any variable-length column
types, the record format is also variable length. When a table
is created, MySQL may, under certain conditions, change a column from a
variable-length type to a fixed-length type or vice versa. See section 13.2.6.1 Silent Column Specification Changes.
| Column Type | Storage Required |
TINYINT | 1 byte |
SMALLINT | 2 bytes |
MEDIUMINT | 3 bytes |
INT, INTEGER | 4 bytes |
BIGINT | 8 bytes |
FLOAT(p) | 4 bytes if 0 <= p <= 24, 8 bytes if 25 <= p <= 53 |
FLOAT | 4 bytes |
DOUBLE [PRECISION], item REAL | 8 bytes |
DECIMAL(M,D), NUMERIC(M,D) | M+2 bytes if D > 0, M+1 bytes if D = 0 (D+2, if M < D)
|
BIT(M) | approximately (M+7)/8 bytes |
| Column Type | Storage Required |
DATE | 3 bytes |
DATETIME | 8 bytes |
TIMESTAMP | 4 bytes |
TIME | 3 bytes |
YEAR | 1 byte |
| Column Type | Storage Required |
CHAR(M) | M bytes, 0 <= M <= 255
|
VARCHAR(M) | L+1 bytes, where L <= M and 0 <= M <= 255
|
BINARY(M) | M bytes, 0 <= M <= 255
|
VARBINARY(M) | L+1 bytes, where L <= M and 0 <= M <= 255
|
TINYBLOB, TINYTEXT | L+1 bytes, where L < 2^8 |
BLOB, TEXT | L+2 bytes, where L < 2^16 |
MEDIUMBLOB, MEDIUMTEXT | L+3 bytes, where L < 2^24 |
LONGBLOB, LONGTEXT | L+4 bytes, where L < 2^32 |
ENUM('value1','value2',...) | 1 or 2 bytes, depending on the number of enumeration values (65,535 values maximum) |
SET('value1','value2',...) | 1, 2, 3, 4, or 8 bytes, depending on the number of set members (64 members maximum) |
VARCHAR and the BLOB and TEXT types are variable-length
types. For each, the storage requirements depend on the actual length of
column values (represented by L in the preceding table), rather than
on the type's maximum possible size. For example, a VARCHAR(10)
column can hold a string with a maximum length of 10. The actual
storage required is the length of the string (L), plus 1 byte to
record the length of the string. For the string 'abcd', L is 4
and the storage requirement is 5 bytes.
For the CHAR, VARCHAR, and TEXT types, L and
M in the preceding table should be interpreted as number of bytes
before MySQL 4.1 and as number of characters thereafter. Lengths for these
types in columns specifications indicate number of characters from MySQL 4.1
on. The number of extra bytes for recording lengths for variable-length data
types is unchanged. For example, L+1 bytes to store a TINYTEXT
value before MySQL 4.1 becomes L characters + 1 byte to store the
length as of MySQL 4.1.
As of MySQL 5.0.3, the NDBCLUSTER engine supports only fixed-width
columns. This means that a VARCHAR column from a table in a MySQL
CLuster will behave almost as if it were of type CHAR (except that
each record still has one extra byte overhead). For example, in a Cluster
table, each record in a column declared as VARCHAR(100) will
take up 101 bytes for storage, regardless of the length of the string
actually stored in any given record.
The BLOB and TEXT types require 1, 2, 3, or 4 bytes to record
the length of the column value, depending on the maximum possible length of
the type. See section 11.4.3 The BLOB and TEXT Types.
The size of an ENUM object is determined by the number of
different enumeration values. One byte is used for enumerations with up
to 255 possible values. Two bytes are used for enumerations with up to
65,535 values. See section 11.4.4 The ENUM Type.
The size of a SET object is determined by the number of different
set members. If the set size is N, the object occupies (N+7)/8
bytes, rounded up to 1, 2, 3, 4, or 8 bytes. A SET can have a maximum
of 64 members. See section 11.4.5 The SET Type.
For the most efficient use of storage, try to use the most precise type in
all cases. For example, if an integer column is used for values in the
range from 1 to 99999, MEDIUMINT UNSIGNED is the
best type. Of the types that represent all the required values, it uses
the least amount of storage.
Tables created with MySQL 5.0.3 and above uses a a new storage format
for DECIMAL columns. All basic calculation (+,-,*,/) with
DECIMAL columns are done with precision of 64 decimal digits.
See section 11.1.1 Overview of Numeric Types.
For earlier MySQL version, accurate representation of monetary values was
a common problem. In these MySQL version, you should also use the
DECIMAL type. In this case the value is stored as a string, so no
loss of accuracy should occur on storage. Calculations on these
DECIMAL values are however done using double-precision
operations. If accuracy is not too important or if speed is important,
the DOUBLE type may also be good enough.
For high precision, you can always convert to a fixed-point type stored
in a BIGINT. This allows you to do all calculations with 64-bit
integers and convert results back to floating-point values only when
necessary.
To make it easier to use code written for SQL implementations from other vendors, MySQL maps column types as shown in the following table. These mappings make it easier to import table definitions from other database engines into MySQL:
| Other Vendor Type | MySQL Type |
BINARY(M) | CHAR(M) BINARY (before MySQL 4.1.2)
|
BOOL | TINYINT
|
BOOLEAN | TINYINT
|
CHAR VARYING(M) | VARCHAR(M)
|
DEC | DECIMAL
|
FIXED | DECIMAL (MySQL 4.1.0 on)
|
FLOAT4 | FLOAT
|
FLOAT8 | DOUBLE
|
INT1 | TINYINT
|
INT2 | SMALLINT
|
INT3 | MEDIUMINT
|
INT4 | INT
|
INT8 | BIGINT
|
LONG VARBINARY | MEDIUMBLOB
|
LONG VARCHAR | MEDIUMTEXT
|
LONG | MEDIUMTEXT (MySQL 4.1.0 on)
|
MIDDLEINT | MEDIUMINT
|
NUMERIC | DECIMAL
|
VARBINARY(M) | VARCHAR(M) BINARY (before MySQL 4.1.2)
|
As of MySQL 4.1.2, BINARY and VARBINARY are distinct data types
and are not converted to CHAR BINARY and VARCHAR BINARY.
Column type mapping occurs at table creation time, after which the original
type specifications are discarded. If you create a table with types used
by other vendors and then issue a DESCRIBE tbl_name statement,
MySQL reports the table structure using the equivalent MySQL types.
Expressions can be used at several points in SQL statements, such as in the
ORDER BY or HAVING clauses of SELECT statements, in the
WHERE clause of a SELECT, DELETE, or UPDATE
statement, or in SET statements. Expressions can be written using
literal values, column values, NULL, functions, and operators.
This chapter describes the functions and operators that are allowed for
writing expressions in MySQL.
An expression that contains NULL always produces a NULL value
unless otherwise indicated in the documentation for a particular function or
operator.
Note: By default, there must be no whitespace between a function name and the parenthesis following it. This helps the MySQL parser distinguish between function calls and references to tables or columns that happen to have the same name as a function. Spaces around function arguments are permitted, though.
You can tell the MySQL server to accept spaces after function names by
starting it with the --sql-mode=IGNORE_SPACE option. Individual client
programs can request this behavior by using the
CLIENT_IGNORE_SPACE option for mysql_real_connect().
In either case, all function names become reserved words.
See section 5.2.2 The Server SQL Mode.
For the sake of brevity, most examples in this chapter display the output
from the mysql program in abbreviated form. Instead of showing
examples in this format:
mysql> SELECT MOD(29,9); +-----------+ | mod(29,9) | +-----------+ | 2 | +-----------+ 1 rows in set (0.00 sec)
This format is used instead:
mysql> SELECT MOD(29,9);
-> 2
Operator precedences are shown in the following list, from lowest precedence to the highest. Operators that are shown together on a line have the same precedence.
:= ||, OR, XOR &&, AND NOT BETWEEN, CASE, WHEN, THEN, ELSE =, <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN | & <<, >> -, + *, /, DIV, %, MOD ^ - (unary minus), ~ (unary bit inversion) ! BINARY, COLLATE
The precedence shown for NOT is as of MySQL 5.0.2. For earlier
versions, or from 5.0.2 on if the HIGH_NOT_PRECEDENCE SQL mode is
enabled, the precedence of NOT is the same as that of the !
operator.
See section 5.2.2 The Server SQL Mode.
( ... )
mysql> SELECT 1+2*3;
-> 7
mysql> SELECT (1+2)*3;
-> 9
Comparison operations result in a value of 1 (TRUE), 0 (FALSE),
or NULL. These operations work for both numbers and strings. Strings
are automatically converted to numbers and numbers to strings as necessary.
Some of the functions in this section (such as LEAST() and
GREATEST()) return values other than 1 (TRUE), 0
(FALSE), or NULL. However, the value they return is based on
comparison operations performed as described by the following rules.
MySQL compares values using the following rules:
NULL, the result of the comparison is
NULL, except for the NULL-safe <=> equality comparison
operator.
TIMESTAMP or DATETIME column and
the other argument is a constant, the constant is converted
to a timestamp before the comparison is performed. This is done to be more
ODBC-friendly. Note that this is not done for arguments in IN()!
To be safe, always use complete datetime/date/time strings when doing
comparisons.
By default, string comparisons are not case sensitive and use the current character set (ISO-8859-1 Latin1 by default, which also works excellently for English).
To convert a value to a specific type for comparison purposes, you can
use the CAST() function. String values can be converted to a
different character set using CONVERT().
See section 12.7 Cast Functions and Operators.
The following examples illustrate conversion of strings to numbers for comparison operations:
mysql> SELECT 1 > '6x';
-> 0
mysql> SELECT 7 > '6x';
-> 1
mysql> SELECT 0 > 'x6';
-> 0
mysql> SELECT 0 = 'x6';
-> 1
Note that when you are comparing a string column with a number, MySQL can't use an index on the column to quickly look up the value. If str_col is an indexed string column, the index cannot be used when performing the lookup in the following statement:
SELECT * FROM tbl_name WHERE str_col=1;
The reason for this is that there are many different strings that may
convert to the value 1: '1', ' 1', '1a', ...
=
mysql> SELECT 1 = 0;
-> 0
mysql> SELECT '0' = 0;
-> 1
mysql> SELECT '0.0' = 0;
-> 1
mysql> SELECT '0.01' = 0;
-> 0
mysql> SELECT '.01' = 0.01;
-> 1
<=>
NULL-safe equal.
This operator performs an equality comparison like the = operator, but
returns 1 rather than NULL if both operands are NULL,
and 0 rather than NULL if one operand is NULL.
mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL;
-> 1, 1, 0
mysql> SELECT 1 = 1, NULL = NULL, 1 = NULL;
-> 1, NULL, NULL
<=> was added in MySQL 3.23.0.
<>
!=
mysql> SELECT '.01' <> '0.01';
-> 1
mysql> SELECT .01 <> '0.01';
-> 0
mysql> SELECT 'zapp' <> 'zappp';
-> 1
<=
mysql> SELECT 0.1 <= 2;
-> 1
<
mysql> SELECT 2 < 2;
-> 0
>=
mysql> SELECT 2 >= 2;
-> 1
>
mysql> SELECT 2 > 2;
-> 0
IS boolean_value
IS NOT boolean_value
TRUE, FALSE, or UNKNOWN.
mysql> SELECT 1 IS TRUE, 0 IS FALSE, NULL IS UNKNOWN;
-> 1, 1, 1
mysql> SELECT 1 IS NOT UNKNOWN, 0 IS NOT UNKNOWN, NULL IS NOT UNKNOWN;
-> 1, 1, 0
IS [NOT] boolean_value syntax was added in MySQL 5.0.2.
IS NULL
IS NOT NULL
NULL.
mysql> SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL;
-> 0, 0, 1
mysql> SELECT 1 IS NOT NULL, 0 IS NOT NULL, NULL IS NOT NULL;
-> 1, 1, 0
To be able to work well with ODBC programs, MySQL supports the following
extra features when using IS NULL:
AUTO_INCREMENT value
by issuing a statement of the following form immediately after generating the
value:
SELECT * FROM tbl_name WHERE auto_col IS NULLThis behavior can be disabled by setting
SQL_AUTO_IS_NULL=0.
See section 13.5.3 SET Syntax.
DATE and DATETIME columns that are declared as NOT
NULL, you can find the special date '0000-00-00' by using a statement
like this:
SELECT * FROM tbl_name WHERE date_column IS NULLThis is needed to get some ODBC applications to work because ODBC doesn't support a
'0000-00-00' date value.
expr BETWEEN min AND max
BETWEEN returns 1,
otherwise it returns 0. This is equivalent to the expression
(min <= expr AND expr <= max) if all the arguments are of the
same type. Otherwise type conversion takes place according to the rules
described at the beginning of this section, but applied to all the three
arguments. Note: Before MySQL
4.0.5, arguments were converted to the type of expr instead.
mysql> SELECT 1 BETWEEN 2 AND 3;
-> 0
mysql> SELECT 'b' BETWEEN 'a' AND 'c';
-> 1
mysql> SELECT 2 BETWEEN 2 AND '3';
-> 1
mysql> SELECT 2 BETWEEN 2 AND 'x-3';
-> 0
expr NOT BETWEEN min AND max
NOT (expr BETWEEN min AND max).
COALESCE(value,...)
NULL value in the list.
mysql> SELECT COALESCE(NULL,1);
-> 1
mysql> SELECT COALESCE(NULL,NULL,NULL);
-> NULL
COALESCE() was added in MySQL 3.23.3.
GREATEST(value1,value2,...)
LEAST().
mysql> SELECT GREATEST(2,0);
-> 2
mysql> SELECT GREATEST(34.0,3.0,5.0,767.0);
-> 767.0
mysql> SELECT GREATEST('B','A','C');
-> 'C'
Before MySQL 3.22.5, you can use MAX()
instead of GREATEST().
expr IN (value,...)
1 if expr is any of the values in the IN list,
else returns 0. If all values are constants, they are
evaluated according to the type of expr and sorted. The search for the
item then is done using a binary search. This means IN is very quick
if the IN value list consists entirely of constants. If expr
is a case-sensitive string expression, the string comparison is performed in
case-sensitive fashion.
mysql> SELECT 2 IN (0,3,5,'wefwf');
-> 0
mysql> SELECT 'wefwf' IN (0,3,5,'wefwf');
-> 1
The number of values in the IN list is only limited by the
max_allowed_packet value.
To comply with the SQL standard,
from MySQL 4.1 on
IN returns NULL
not only if the expression on the left hand side is NULL, but also if
no match is found in the list and one of the expressions in the list is
NULL.
From MySQL 4.1 on, IN() syntax also is used to write certain types of
subqueries.
See section 13.1.8.3 Subqueries with ANY, IN, and SOME.
expr NOT IN (value,...)
NOT (expr IN (value,...)).
ISNULL(expr)
NULL, ISNULL() returns 1, otherwise
it returns 0.
mysql> SELECT ISNULL(1+1);
-> 0
mysql> SELECT ISNULL(1/0);
-> 1
A comparison of NULL values using = is always
false.
INTERVAL(N,N1,N2,N3,...)
0 if N < N1, 1 if N < N2
and so on or -1 if N is NULL. All arguments are treated
as integers. It is required that N1 < N2 < N3 <
... < Nn for this function to work correctly. This is because
a binary search is used (very fast).
mysql> SELECT INTERVAL(23, 1, 15, 17, 30, 44, 200);
-> 3
mysql> SELECT INTERVAL(10, 1, 10, 100, 1000);
-> 2
mysql> SELECT INTERVAL(22, 23, 30, 44, 200);
-> 0
LEAST(value1,value2,...)
INTEGER context or all arguments
are integer-valued, they are compared as integers.
REAL context or all arguments are
real-valued, they are compared as reals.
mysql> SELECT LEAST(2,0);
-> 0
mysql> SELECT LEAST(34.0,3.0,5.0,767.0);
-> 3.0
mysql> SELECT LEAST('B','A','C');
-> 'A'
Before MySQL 3.22.5, you can use MIN()
instead of LEAST().
Note that the preceding conversion rules can produce strange results in some
borderline cases:
mysql> SELECT CAST(LEAST(3600, 9223372036854775808.0) as SIGNED);
-> -9223372036854775808
This happens because MySQL reads 9223372036854775808.0 in an
integer context. The integer representation is not good enough to
hold the value, so it wraps to a signed integer.
In SQL, all logical operators evaluate to TRUE, FALSE, or NULL (UNKNOWN).
In MySQL, these are implemented as 1 (TRUE), 0 (FALSE),
and NULL. Most of this is common to different SQL database servers,
although some servers may return any non-zero value for TRUE.
NOT
!
1 if the operand is 0,
to 0 if the operand is non-zero,
and NOT NULL returns NULL.
mysql> SELECT NOT 10;
-> 0
mysql> SELECT NOT 0;
-> 1
mysql> SELECT NOT NULL;
-> NULL
mysql> SELECT ! (1+1);
-> 0
mysql> SELECT ! 1+1;
-> 1
The last example produces 1 because the expression evaluates
the same way as (!1)+1.
AND
&&
1 if all operands are non-zero and not NULL,
to 0 if one or more operands are 0,
otherwise NULL is returned.
mysql> SELECT 1 && 1;
-> 1
mysql> SELECT 1 && 0;
-> 0
mysql> SELECT 1 && NULL;
-> NULL
mysql> SELECT 0 && NULL;
-> 0
mysql> SELECT NULL && 0;
-> 0
Please note that MySQL versions prior to 4.0.5 stop evaluation when
a NULL is encountered, rather than continuing the process to
check for possible 0 values. This means that in these versions,
SELECT (NULL AND 0) returns NULL instead of 0.
As of MySQL 4.0.5, the code has been re-engineered so that the result is
always as prescribed by the SQL standards while still using the
optimization wherever possible.
OR
||
NULL, the result is 1 if any
operand is non-zero, and 0 otherwise. With a NULL operand,
the result is 1 if the other operand is non-zero, and NULL
otherwise. If both operands are NULL, the result is NULL.
mysql> SELECT 1 || 1;
-> 1
mysql> SELECT 1 || 0;
-> 1
mysql> SELECT 0 || 0;
-> 0
mysql> SELECT 0 || NULL;
-> NULL
mysql> SELECT 1 || NULL;
-> 1
XOR
NULL if either operand is NULL.
For non-NULL operands, evaluates to 1 if an odd number
of operands is non-zero,
otherwise 0 is returned.
mysql> SELECT 1 XOR 1;
-> 0
mysql> SELECT 1 XOR 0;
-> 1
mysql> SELECT 1 XOR NULL;
-> NULL
mysql> SELECT 1 XOR 1 XOR 1;
-> 1
a XOR b is mathematically equal to
(a AND (NOT b)) OR ((NOT a) and b).
XOR was added in MySQL 4.0.2.
CASE value WHEN [compare-value] THEN result [WHEN [compare-value] THEN result ...] [ELSE result] END
CASE WHEN [condition] THEN result [WHEN [condition] THEN result ...] [ELSE result] END
value=compare-value. The second version returns the result for
the first condition that is true. If there was no matching result
value, the result after ELSE is returned, or NULL if there is no
ELSE part.
mysql> SELECT CASE 1 WHEN 1 THEN 'one'
-> WHEN 2 THEN 'two' ELSE 'more' END;
-> 'one'
mysql> SELECT CASE WHEN 1>0 THEN 'true' ELSE 'false' END;
-> 'true'
mysql> SELECT CASE BINARY 'B'
-> WHEN 'a' THEN 1 WHEN 'b' THEN 2 END;
-> NULL
The type of the return value (INTEGER, DOUBLE, or
STRING) is the same as the type of the first returned value (the
expression after the first THEN).
CASE was added in MySQL 3.23.3.
IF(expr1,expr2,expr3)
expr1 <> 0 and expr1 <> NULL) then
IF() returns expr2, else it returns expr3.
IF() returns a numeric or string value, depending on the context
in which it is used.
mysql> SELECT IF(1>2,2,3);
-> 3
mysql> SELECT IF(1<2,'yes','no');
-> 'yes'
mysql> SELECT IF(STRCMP('test','test1'),'no','yes');
-> 'no'
If only one of expr2 or expr3 is explicitly NULL, the
result type of the IF() function is the type of non-NULL
expression. (This behavior is new in MySQL 4.0.3.)
expr1 is evaluated as an integer value, which means that if you are
testing floating-point or string values, you should do so using a comparison
operation.
mysql> SELECT IF(0.1,1,0);
-> 0
mysql> SELECT IF(0.1<>0,1,0);
-> 1
In the first case shown, IF(0.1) returns 0 because 0.1
is converted to an integer value, resulting in a test of IF(0). This
may not be what you expect. In the second case, the comparison tests the
original floating-point value to see whether it is non-zero. The result
of the comparison is used as an integer.
The default return type of IF() (which may matter when it is
stored into a temporary table) is calculated in MySQL
3.23 as follows:
| Expression | Return Value |
expr2 or expr3 returns a string | string |
expr2 or expr3 returns a floating-point value | floating-point |
expr2 or expr3 returns an integer | integer |
expr2 and expr3 are strings, the result is case
sensitive if either string is case sensitive (starting from MySQL
3.23.51).
IFNULL(expr1,expr2)
NULL, IFNULL() returns expr1,
else it returns expr2. IFNULL() returns a numeric or string
value, depending on the context in which it is used.
mysql> SELECT IFNULL(1,0);
-> 1
mysql> SELECT IFNULL(NULL,10);
-> 10
mysql> SELECT IFNULL(1/0,10);
-> 10
mysql> SELECT IFNULL(1/0,'yes');
-> 'yes'
In MySQL 4.0.6 and above, the default result value of
IFNULL(expr1,expr2) is the more ``general'' of the two expressions,
in the order STRING, REAL, or INTEGER. The difference
from earlier MySQL versions is mostly notable when you create a table
based on expressions or MySQL has to internally store a value from
IFNULL() in a temporary table.
CREATE TABLE tmp SELECT IFNULL(1,'test') AS test;As of MySQL 4.0.6, the type for the
test column is CHAR(4),
whereas in earlier versions the type would be BIGINT.
NULLIF(expr1,expr2)
NULL if expr1 = expr2 is true, else returns expr1.
This is the same as CASE WHEN expr1 = expr2 THEN NULL ELSE expr1 END.
mysql> SELECT NULLIF(1,1);
-> NULL
mysql> SELECT NULLIF(1,2);
-> 1
Note that MySQL evaluates expr1 twice if the arguments are not equal.
NULLIF() was added in MySQL 3.23.15.
String-valued functions return NULL if the length of the result would
be greater than the value of the max_allowed_packet system variable.
See section 7.5.2 Tuning Server Parameters.
For functions that operate on string positions, the first position is numbered 1.
ASCII(str)
0 if str is the empty string. Returns
NULL if str is NULL.
ASCII() works for characters with numeric values from 0 to
255.
mysql> SELECT ASCII('2');
-> 50
mysql> SELECT ASCII(2);
-> 50
mysql> SELECT ASCII('dx');
-> 100
See also the ORD() function.
BIN(N)
BIGINT) number. This is equivalent to
CONV(N,10,2). Returns NULL if N is NULL.
mysql> SELECT BIN(12);
-> '1100'
BIT_LENGTH(str)
mysql> SELECT BIT_LENGTH('text');
-> 32
BIT_LENGTH() was added in MySQL 4.0.2.
CHAR(N,...)
CHAR() interprets the arguments as integers and returns a string
consisting of the characters given by the code values of those
integers. NULL values are skipped.
mysql> SELECT CHAR(77,121,83,81,'76');
-> 'MySQL'
mysql> SELECT CHAR(77,77.3,'77.3');
-> 'MMM'
CHAR_LENGTH(str)
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
CHARACTER_LENGTH(str)
CHARACTER_LENGTH() is a synonym for CHAR_LENGTH().
COMPRESS(string_to_compress)
zlib. Otherwise, the return
value is always NULL. The compressed string can be uncompressed with
UNCOMPRESS().
mysql> SELECT LENGTH(COMPRESS(REPEAT('a',1000)));
-> 21
mysql> SELECT LENGTH(COMPRESS(''));
-> 0
mysql> SELECT LENGTH(COMPRESS('a'));
-> 13
mysql> SELECT LENGTH(COMPRESS(REPEAT('a',16)));
-> 15
The compressed string contents are stored the following way:
CHAR
or VARCHAR column. (Use of CHAR or VARCHAR to store
compressed strings is not recommended. It is better to use a BLOB
column instead.)
COMPRESS() was added in MySQL 4.1.1.
CONCAT(str1,str2,...)
NULL if any argument is NULL. May have one or more arguments.
If all arguments are non-binary strings, the result is a non-binary string.
If the arguments include any binary strings, the result is a binary string.
A numeric argument is converted to its equivalent binary string form.
mysql> SELECT CONCAT('My', 'S', 'QL');
-> 'MySQL'
mysql> SELECT CONCAT('My', NULL, 'QL');
-> NULL
mysql> SELECT CONCAT(14.3);
-> '14.3'
CONCAT_WS(separator,str1,str2,...)
CONCAT_WS() stands for CONCAT With Separator and is a special form of
CONCAT(). The first argument is the separator for the rest of the
arguments.
The separator is added between the strings to be concatenated.
The separator can be a string as can the rest of the
arguments. If the separator is NULL, the result is NULL.
The function skips any NULL values after the
separator argument.
mysql> SELECT CONCAT_WS(',','First name','Second name','Last Name');
-> 'First name,Second name,Last Name'
mysql> SELECT CONCAT_WS(',','First name',NULL,'Last Name');
-> 'First name,Last Name'
Before MySQL 4.0.14, CONCAT_WS() skips empty strings as well as
NULL values.
CONV(N,from_base,to_base)
NULL if any argument is NULL.
The argument N is interpreted as an integer, but may be specified as
an integer or a string. The minimum base is 2 and the maximum base is
36. If to_base is a negative number, N is regarded as a
signed number. Otherwise, N is treated as unsigned. CONV() works
with 64-bit precision.
mysql> SELECT CONV('a',16,2);
-> '1010'
mysql> SELECT CONV('6E',18,8);
-> '172'
mysql> SELECT CONV(-17,10,-18);
-> '-H'
mysql> SELECT CONV(10+'10'+'10'+0xa,10,10);
-> '40'
ELT(N,str1,str2,str3,...)
1, str2 if N =
2, and so on. Returns NULL if N is less than 1
or greater than the number of arguments. ELT() is the complement of
FIELD().
mysql> SELECT ELT(1, 'ej', 'Heja', 'hej', 'foo');
-> 'ej'
mysql> SELECT ELT(4, 'ej', 'Heja', 'hej', 'foo');
-> 'foo'
EXPORT_SET(bits,on,off[,separator[,number_of_bits]])
mysql> SELECT EXPORT_SET(5,'Y','N',',',4);
-> 'Y,N,Y,N'
mysql> SELECT EXPORT_SET(6,'1','0',',',10);
-> '0,1,1,0,0,0,0,0,0,0'
FIELD(str,str1,str2,str3,...)
... list.
Returns 0 if str is not found.
If str is NULL, the return value is 0 because
NULL fails equality comparison with any value.
FIELD() is the complement of ELT().
mysql> SELECT FIELD('ej', 'Hej', 'ej', 'Heja', 'hej', 'foo');
-> 2
mysql> SELECT FIELD('fo', 'Hej', 'ej', 'Heja', 'hej', 'foo');
-> 0
FIND_IN_SET(str,strlist)
1 to N if the string str is in the string list
strlist consisting of N substrings. A string list is a string
composed of substrings separated by `,' characters. If the first
argument is a constant string and the second is a column of type SET,
the FIND_IN_SET() function is optimized to use bit arithmetic.
Returns 0 if str is not in strlist or if strlist
is the empty string. Returns NULL if either argument is NULL.
This function does not work properly if the first argument contains a comma
(`,') character.
mysql> SELECT FIND_IN_SET('b','a,b,c,d');
-> 2
HEX(N_or_S)
BIGINT) number.
This is equivalent to CONV(N,10,16).
From MySQL 4.0.1 and up,
if N_OR_S is a string, returns a hexadecimal string of N_OR_S
where each character in N_OR_S is converted to two hexadecimal digits.
mysql> SELECT HEX(255);
-> 'FF'
mysql> SELECT 0x616263;
-> 'abc'
mysql> SELECT HEX('abc');
-> 616263
INSERT(str,pos,len,newstr)
NULL if any argument is null.
mysql> SELECT INSERT('Quadratic', 3, 4, 'What');
-> 'QuWhattic'
mysql> SELECT INSERT('Quadratic', -1, 4, 'What');
-> 'Quadratic'
mysql> SELECT INSERT('Quadratic', 3, 100, 'What');
-> 'QuWhat'
This function is multi-byte safe.
INSTR(str,substr)
LOCATE(), except that the arguments are swapped.
mysql> SELECT INSTR('foobarbar', 'bar');
-> 4
mysql> SELECT INSTR('xbar', 'foobar');
-> 0
This function is multi-byte safe. In MySQL 3.23, this function is case
sensitive. For 4.0 on, it is case sensitive only if either argument is a
binary string.
LCASE(str)
LCASE() is a synonym for LOWER().
LEFT(str,len)
mysql> SELECT LEFT('foobarbar', 5);
-> 'fooba'
LENGTH(str)
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
mysql> SELECT LENGTH('text');
-> 4
LOAD_FILE(file_name)
FILE privilege. The file must
be readable by all and be smaller than max_allowed_packet bytes.
If the file doesn't exist or cannot be read because one of the preceding
conditions is not satisfied, the function returns NULL.
mysql> UPDATE tbl_name
SET blob_column=LOAD_FILE('/tmp/picture')
WHERE id=1;
Before MySQL 3.23, you must read the file inside your application and create
an INSERT statement to update the database with the file contents.
If you are using the MySQL++ library, one way to do this can be found in the
MySQL++ manual, available at
http://dev.mysql.com/doc/.
LOCATE(substr,str)
LOCATE(substr,str,pos)
0 if substr is not in str.
mysql> SELECT LOCATE('bar', 'foobarbar');
-> 4
mysql> SELECT LOCATE('xbar', 'foobar');
-> 0
mysql> SELECT LOCATE('bar', 'foobarbar',5);
-> 7
This function is multi-byte safe. In MySQL 3.23, this function is case
sensitive. For 4.0 on, it is case sensitive only if either argument is a
binary string.
LOWER(str)
mysql> SELECT LOWER('QUADRATICALLY');
-> 'quadratically'
This function is multi-byte safe.
LPAD(str,len,padstr)
mysql> SELECT LPAD('hi',4,'??');
-> '??hi'
mysql> SELECT LPAD('hi',1,'??');
-> 'h'
LTRIM(str)
mysql> SELECT LTRIM(' barbar');
-> 'barbar'
This function is multi-byte safe.
MAKE_SET(bits,str1,str2,...)
NULL values in str1, str2, ...
are not appended to the result.
mysql> SELECT MAKE_SET(1,'a','b','c');
-> 'a'
mysql> SELECT MAKE_SET(1 | 4,'hello','nice','world');
-> 'hello,world'
mysql> SELECT MAKE_SET(1 | 4,'hello','nice',NULL,'world');
-> 'hello'
mysql> SELECT MAKE_SET(0,'a','b','c');
-> ''
MID(str,pos,len)
MID(str,pos,len) is a synonym for
SUBSTRING(str,pos,len).
OCT(N)
BIGINT)number. This is equivalent to
CONV(N,10,8).
Returns NULL if N is NULL.
mysql> SELECT OCT(12);
-> '14'
OCTET_LENGTH(str)
OCTET_LENGTH() is a synonym for LENGTH().
ORD(str)
(1st byte code) + (2nd byte code * 256) + (3rd byte code * 256^2) ...If the leftmost character is not a multi-byte character,
ORD()
returns the same value as the ASCII() function.
mysql> SELECT ORD('2');
-> 50
POSITION(substr IN str)
POSITION(substr IN str) is a synonym for LOCATE(substr,str).
QUOTE(str)
NULL, the return value is the word ``NULL'' without surrounding
single quotes.
The QUOTE() function was added in MySQL 4.0.3.
mysql> SELECT QUOTE('Don\'t!');
-> 'Don\'t!'
mysql> SELECT QUOTE(NULL);
-> NULL
REPEAT(str,count)
count <= 0, returns an empty string. Returns NULL if
str or count are NULL.
mysql> SELECT REPEAT('MySQL', 3);
-> 'MySQLMySQLMySQL'
REPLACE(str,from_str,to_str)
mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
-> 'WwWwWw.mysql.com'
This function is multi-byte safe.
REVERSE(str)
mysql> SELECT REVERSE('abc');
-> 'cba'
This function is multi-byte safe.
RIGHT(str,len)
mysql> SELECT RIGHT('foobarbar', 4);
-> 'rbar'
This function is multi-byte safe.
RPAD(str,len,padstr)
mysql> SELECT RPAD('hi',5,'?');
-> 'hi???'
mysql> SELECT RPAD('hi',1,'?');
-> 'h'
This function is multi-byte safe.
RTRIM(str)
mysql> SELECT RTRIM('barbar ');
-> 'barbar'
This function is multi-byte safe.
SOUNDEX(str)
SOUNDEX() function returns an
arbitrarily long string. You can use SUBSTRING() on the result to get
a standard soundex string. All non-alphabetic characters are ignored in the
given string. All international alphabetic characters outside the A-Z range
are treated as vowels.
mysql> SELECT SOUNDEX('Hello');
-> 'H400'
mysql> SELECT SOUNDEX('Quadratically');
-> 'Q36324'
Note: This function implements the original Soundex algorithm,
not the more popular enhanced version (also described by D. Knuth).
The difference is that original version discards vowels first and then
duplicates, whereas the enhanced version discards duplicates first and
then vowels.
expr1 SOUNDS LIKE expr2
SOUNDEX(expr1) = SOUNDEX(expr2). It is
available only in MySQL 4.1 or later.
SPACE(N)
mysql> SELECT SPACE(6);
-> ' '
SUBSTRING(str,pos)
SUBSTRING(str FROM pos)
SUBSTRING(str,pos,len)
SUBSTRING(str FROM pos FOR len)
FROM are standard SQL syntax.
mysql> SELECT SUBSTRING('Quadratically',5);
-> 'ratically'
mysql> SELECT SUBSTRING('foobarbar' FROM 4);
-> 'barbar'
mysql> SELECT SUBSTRING('Quadratically',5,6);
-> 'ratica'
This function is multi-byte safe.
SUBSTRING_INDEX(str,delim,count)
mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', 2);
-> 'www.mysql'
mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', -2);
-> 'mysql.com'
This function is multi-byte safe.
TRIM([{BOTH | LEADING | TRAILING} [remstr] FROM] str)
TRIM(remstr FROM] str)
BOTH, LEADING, or
TRAILING is given, BOTH is assumed. If remstr is optional
and not specified, spaces are removed.
mysql> SELECT TRIM(' bar ');
-> 'bar'
mysql> SELECT TRIM(LEADING 'x' FROM 'xxxbarxxx');
-> 'barxxx'
mysql> SELECT TRIM(BOTH 'x' FROM 'xxxbarxxx');
-> 'bar'
mysql> SELECT TRIM(TRAILING 'xyz' FROM 'barxxyz');
-> 'barx'
This function is multi-byte safe.
UCASE(str)
UCASE() is a synonym for UPPER().
UNCOMPRESS(string_to_uncompress)
COMPRESS() function.
If the argument is not a compressed value, the result is NULL.
This function requires MySQL to have been compiled with a compression library
such as zlib. Otherwise, the return value is always NULL.
mysql> SELECT UNCOMPRESS(COMPRESS('any string'));
-> 'any string'
mysql> SELECT UNCOMPRESS('any string');
-> NULL
UNCOMPRESS() was added in MySQL 4.1.1.
UNCOMPRESSED_LENGTH(compressed_string)
mysql> SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)));
-> 30
UNCOMPRESSED_LENGTH() was added in MySQL 4.1.1.
UNHEX(str)
HEX(str). That is, it interprets each pair of
hexadecimal digits in the argument as a number and converts it to the
character represented by the number. The resulting characters are returned as
a binary string.
mysql> SELECT UNHEX('4D7953514C');
-> 'MySQL'
mysql> SELECT 0x4D7953514C;
-> 'MySQL'
mysql> SELECT UNHEX(HEX('string'));
-> 'string'
mysql> SELECT HEX(UNHEX('1267'));
-> '1267'
UNHEX() was added in MySQL 4.1.2.
UPPER(str)
mysql> SELECT UPPER('Hej');
-> 'HEJ'
This function is multi-byte safe.
MySQL automatically converts numbers to strings as necessary, and vice versa.
mysql> SELECT 1+'1';
-> 2
mysql> SELECT CONCAT(2,' test');
-> '2 test'
If you want to convert a number to a string explicitly, use the CAST()
or CONCAT() function:
mysql> SELECT 38.8, CAST(38.8 AS CHAR);
-> 38.8, '38.8'
mysql> SELECT 38.8, CONCAT(38.8);
-> 38.8, '38.8'
CAST() is preferable, but it is unavailable before MySQL 4.0.2.
If a string function is given a binary string as an argument, the resulting string is also a binary string. A number converted to a string is treated as a binary string. This affects only comparisons.
Normally, if any expression in a string comparison is case sensitive, the comparison is performed in case-sensitive fashion.
expr LIKE pat [ESCAPE 'escape-char']
1 (TRUE) or 0
(FALSE). If either expr or pat is NULL, the result is
NULL.
The pattern need not be a literal string. For example, it can be specified
as a string expression or table column.
With LIKE you can use the following two wildcard characters
in the pattern:
| Character | Description |
% | Matches any number of characters, even zero characters |
_ | Matches exactly one character |
mysql> SELECT 'David!' LIKE 'David_';
-> 1
mysql> SELECT 'David!' LIKE '%D%v%';
-> 1
To test for literal instances of a wildcard character, precede the character
with the escape character. If you don't specify the ESCAPE character,
`\' is assumed.
| String | Description |
\% | Matches one `%' character |
\_ | Matches one `_' character |
mysql> SELECT 'David!' LIKE 'David\_';
-> 0
mysql> SELECT 'David_' LIKE 'David\_';
-> 1
To specify a different escape character, use the ESCAPE clause:
mysql> SELECT 'David_' LIKE 'David|_' ESCAPE '|';
-> 1
The following two statements illustrate that string comparisons are
not case sensitive unless one of the operands is a binary string:
mysql> SELECT 'abc' LIKE 'ABC';
-> 1
mysql> SELECT 'abc' LIKE BINARY 'ABC';
-> 0
In MySQL, LIKE is allowed on numeric expressions. (This is an
extension to the standard SQL LIKE.)
mysql> SELECT 10 LIKE '1%';
-> 1
Note: Because MySQL uses the C escape syntax in strings (for example,
`\n' to represent newline), you must double any `\' that you use in your LIKE
strings. For example, to search for `\n', specify it as `\\n'. To
search for `\', specify it as `\\\\' (the backslashes are stripped
once by the parser and another time when the pattern match is done, leaving
a single backslash to be matched).
expr NOT LIKE pat [ESCAPE 'escape-char']
NOT (expr LIKE pat [ESCAPE 'escape-char']).
expr NOT REGEXP pat
expr NOT RLIKE pat
NOT (expr REGEXP pat).
expr REGEXP pat
expr RLIKE pat
1
if expr matches pat, otherwise returns 0. If either
expr or pat is NULL, the result is NULL.
RLIKE is a synonym for REGEXP, provided for mSQL
compatibility.
The pattern need not be a literal string. For example, it can be specified
as a string expression or table column.
Note: Because MySQL uses the C escape syntax in strings (for example,
`\n' to represent newline), you must double any `\' that you
use in your REGEXP strings.
As of MySQL 3.23.4, REGEXP is not case sensitive for normal (not
binary) strings.
mysql> SELECT 'Monty!' REGEXP 'm%y%%';
-> 0
mysql> SELECT 'Monty!' REGEXP '.*';
-> 1
mysql> SELECT 'new*\n*line' REGEXP 'new\\*.\\*line';
-> 1
mysql> SELECT 'a' REGEXP 'A', 'a' REGEXP BINARY 'A';
-> 1 0
mysql> SELECT 'a' REGEXP '^[a-d]';
-> 1
REGEXP and RLIKE use the current character set (ISO-8859-1
Latin1 by default) when deciding the type of a character.
However, these operators are not multi-byte safe.
STRCMP(expr1,expr2)
STRCMP()
returns 0 if the strings are the same, -1 if the first
argument is smaller than the second according to the current sort order,
and 1 otherwise.
mysql> SELECT STRCMP('text', 'text2');
-> -1
mysql> SELECT STRCMP('text2', 'text');
-> 1
mysql> SELECT STRCMP('text', 'text');
-> 0
As of MySQL 4.0,
STRCMP() uses the current character set when performing comparisons.
This makes the default comparison behavior case insensitive unless
one or both of the operands are binary strings.
Before MySQL 4.0, STRCMP() is case sensitive.
The usual arithmetic operators are available. Note that in the case of
-, +, and *, the result is calculated with
BIGINT (64-bit) precision if both arguments are integers.
If one of the arguments is an unsigned integer, and the other argument
is also an integer, the result is an unsigned integer.
See section 12.7 Cast Functions and Operators.
+
mysql> SELECT 3+5;
-> 8
-
mysql> SELECT 3-5;
-> -2
-
mysql> SELECT - 2;
-> -2
Note that if this operator is used with a BIGINT, the return value is a
BIGINT! This means that you should avoid using - on integers that
may have the value of -2^63!
*
mysql> SELECT 3*5;
-> 15
mysql> SELECT 18014398509481984*18014398509481984.0;
-> 324518553658426726783156020576256.0
mysql> SELECT 18014398509481984*18014398509481984;
-> 0
The result of the last expression is incorrect because the result of the
integer multiplication exceeds the 64-bit range of BIGINT
calculations.
/
mysql> SELECT 3/5;
-> 0.60
Division by zero produces a NULL result:
mysql> SELECT 102/(1-1);
-> NULL
A division is calculated with BIGINT arithmetic only if performed
in a context where its result are converted to an integer.
DIV
FLOOR() but safe with BIGINT values.
mysql> SELECT 5 DIV 2;
-> 2
DIV is new in MySQL 4.1.0.
All mathematical functions return NULL in case of an error.
ABS(X)
mysql> SELECT ABS(2);
-> 2
mysql> SELECT ABS(-32);
-> 32
This function is safe to use with BIGINT values.
ACOS(X)
NULL if X is not in the range -1 to
1.
mysql> SELECT ACOS(1);
-> 0.000000
mysql> SELECT ACOS(1.0001);
-> NULL
mysql> SELECT ACOS(0);
-> 1.570796
ASIN(X)
NULL if X is not in the range -1 to
1.
mysql> SELECT ASIN(0.2);
-> 0.201358
mysql> SELECT ASIN('foo');
-> 0.000000
ATAN(X)
mysql> SELECT ATAN(2);
-> 1.107149
mysql> SELECT ATAN(-2);
-> -1.107149
ATAN(Y,X)
ATAN2(Y,X)
Y / X, except that the
signs of both arguments are used to determine the quadrant of the
result.
mysql> SELECT ATAN(-2,2);
-> -0.785398
mysql> SELECT ATAN2(PI(),0);
-> 1.570796
CEILING(X)
CEIL(X)
mysql> SELECT CEILING(1.23);
-> 2
mysql> SELECT CEIL(-1.23);
-> -1
Note that the return value is converted to a BIGINT!
The CEIL() alias was added in MySQL 4.0.6.
COS(X)
mysql> SELECT COS(PI());
-> -1.000000
COT(X)
mysql> SELECT COT(12);
-> -1.57267341
mysql> SELECT COT(0);
-> NULL
CRC32(expr)
NULL if the argument is NULL.
The argument is expected be a string and is treated as one if it is not.
mysql> SELECT CRC32('MySQL');
-> 3259397556
CRC32() is available as of MySQL 4.1.0.
DEGREES(X)
mysql> SELECT DEGREES(PI());
-> 180.000000
EXP(X)
e (the base of natural logarithms) raised to
the power of X.
mysql> SELECT EXP(2);
-> 7.389056
mysql> SELECT EXP(-2);
-> 0.135335
FLOOR(X)
mysql> SELECT FLOOR(1.23);
-> 1
mysql> SELECT FLOOR(-1.23);
-> -2
Note that the return value is converted to a BIGINT!
LN(X)
mysql> SELECT LN(2);
-> 0.693147
mysql> SELECT LN(-2);
-> NULL
This function was added in MySQL 4.0.3.
It is synonymous with LOG(X) in MySQL.
LOG(X)
LOG(B,X)
mysql> SELECT LOG(2);
-> 0.693147
mysql> SELECT LOG(-2);
-> NULL
If called with two parameters, this function returns the logarithm of
X for an arbitrary base B.
mysql> SELECT LOG(2,65536);
-> 16.000000
mysql> SELECT LOG(1,100);
-> NULL
The arbitrary base option was added in MySQL 4.0.3.
LOG(B,X) is equivalent to LOG(X)/LOG(B).
LOG2(X)
X.
mysql> SELECT LOG2(65536);
-> 16.000000
mysql> SELECT LOG2(-100);
-> NULL
LOG2() is useful for finding out how many bits a number would
require for storage.
This function was added in MySQL 4.0.3.
In earlier versions, you can use LOG(X)/LOG(2) instead.
LOG10(X)
mysql> SELECT LOG10(2);
-> 0.301030
mysql> SELECT LOG10(100);
-> 2.000000
mysql> SELECT LOG10(-100);
-> NULL
MOD(N,M)
N % M
N MOD M
mysql> SELECT MOD(234, 10);
-> 4
mysql> SELECT 253 % 7;
-> 1
mysql> SELECT MOD(29,9);
-> 2
mysql> SELECT 29 MOD 9;
-> 2
This function is safe to use with BIGINT values.
The N MOD M syntax works only as of MySQL 4.1.
As of MySQL 4.1.7, MOD() works on values with a fractional part and
returns the exact remainder after division:
mysql> SELECT MOD(34.5,3);
-> 1.5
Before MySQL 4.1.7, MOD() rounds arguments with a fractional value
to integers and returns an integer result:
mysql> SELECT MOD(34.5,3);
-> 2
PI()
mysql> SELECT PI();
-> 3.141593
mysql> SELECT PI()+0.000000000000000000;
-> 3.141592653589793116
POW(X,Y)
POWER(X,Y)
mysql> SELECT POW(2,2);
-> 4.000000
mysql> SELECT POW(2,-2);
-> 0.250000
RADIANS(X)
mysql> SELECT RADIANS(90);
-> 1.570796
RAND()
RAND(N)
0 to 1.0.
If an integer argument N is specified, it is used as the seed value
(producing a repeatable sequence).
mysql> SELECT RAND();
-> 0.9233482386203
mysql> SELECT RAND(20);
-> 0.15888261251047
mysql> SELECT RAND(20);
-> 0.15888261251047
mysql> SELECT RAND();
-> 0.63553050033332
mysql> SELECT RAND();
-> 0.70100469486881
You can't use a column with RAND() values in an ORDER BY
clause, because ORDER BY would evaluate the column multiple times.
As of MySQL 3.23, you can retrieve rows in random order like this:
mysql> SELECT * FROM tbl_name ORDER BY RAND();
ORDER BY RAND() combined with LIMIT is useful for selecting
a random sample of a set of rows:
mysql> SELECT * FROM table1, table2 WHERE a=b AND c<d
-> ORDER BY RAND() LIMIT 1000;
Note that RAND() in a WHERE clause is re-evaluated
every time the WHERE is executed.
RAND() is not meant to be a perfect random generator, but instead a
fast way to generate ad hoc random numbers that is portable between
platforms for the same MySQL version.
ROUND(X)
ROUND(X,D)
mysql> SELECT ROUND(-1.23);
-> -1
mysql> SELECT ROUND(-1.58);
-> -2
mysql> SELECT ROUND(1.58);
-> 2
mysql> SELECT ROUND(1.298, 1);
-> 1.3
mysql> SELECT ROUND(1.298, 0);
-> 1
mysql> SELECT ROUND(23.298, -1);
-> 20
Note that the behavior of ROUND() when the argument
is halfway between two integers depends on the C library
implementation. Different implementations round to the nearest even number,
always up, always down, or always toward zero. If you need
one kind of rounding, you should use a well-defined function
such as TRUNCATE() or FLOOR() instead.
SIGN(X)
-1, 0, or 1, depending
on whether X is negative, zero, or positive.
mysql> SELECT SIGN(-32);
-> -1
mysql> SELECT SIGN(0);
-> 0
mysql> SELECT SIGN(234);
-> 1
SIN(X)
mysql> SELECT SIN(PI());
-> 0.000000
SQRT(X)
mysql> SELECT SQRT(4);
-> 2.000000
mysql> SELECT SQRT(20);
-> 4.472136
TAN(X)
mysql> SELECT TAN(PI()+1);
-> 1.557408
TRUNCATE(X,D)
0, the result has no decimal point or fractional part.
D can be negative to truncate (make zero) D digits left of the
decimal point of the value X.
mysql> SELECT TRUNCATE(1.223,1);
-> 1.2
mysql> SELECT TRUNCATE(1.999,1);
-> 1.9
mysql> SELECT TRUNCATE(1.999,0);
-> 1
mysql> SELECT TRUNCATE(-1.999,1);
-> -1.9
mysql> SELECT TRUNCATE(122,-2);
-> 100
Starting from MySQL 3.23.51, all numbers are rounded toward zero.
Note that decimal numbers are normally not stored as exact numbers in
computers, but as double-precision values, so you may be surprised by the
following result:
mysql> SELECT TRUNCATE(10.28*100,0);
-> 1027
This happens because 10.28 is actually stored as something like
10.2799999999999999.
This section describes the functions that can be used to manipulate temporal values. See section 11.3 Date and Time Types for a description of the range of values each date and time type has and the valid formats in which values may be specified.
Here is an example that uses date functions. The following query selects
all records with a date_col value from within the last 30 days:
mysql> SELECT something FROM tbl_name
-> WHERE DATE_SUB(CURDATE(),INTERVAL 30 DAY) <= date_col;
Note that the query also selects records with dates that lie in the future.
Functions that expect date values usually accept datetime values and ignore the time part. Functions that expect time values usually accept datetime values and ignore the date part.
Functions that return the current date or time each are evaluated only once
per query at the start of query execution. This means that multiple references
to a function such as NOW() within a single query always produce
the same result. This principle also applies to CURDATE(),
CURTIME(), UTC_DATE(), UTC_TIME(), UTC_TIMESTAMP(),
and to any of their synonyms.
Beginning with MySQL 4.1.3, the CURRENT_TIMESTAMP(),
CURRENT_TIME(), CURRENT_DATE(), and FROM_UNIXTIME()
functions return values in the connection's current time zone, which is
available as the value of the time_zone system variable. Also,
UNIX_TIMESTAMP() assumes that its argument is a datetime value in
the current time zone. See section 5.8.8 MySQL Server Time Zone Support.
The return value ranges in the following function descriptions apply for
complete dates. If a date is a ``zero'' value or an incomplete date such
as '2001-11-00', functions that extract a part of a date may return
0. For example, DAYOFMONTH('2001-11-00') returns 0.
ADDDATE(date,INTERVAL expr type)
ADDDATE(expr,days)
INTERVAL form of the second argument,
ADDDATE() is a synonym for DATE_ADD(). The related
function SUBDATE() is a synonym for DATE_SUB().
For information on the INTERVAL argument, see the
discussion for DATE_ADD().
mysql> SELECT DATE_ADD('1998-01-02', INTERVAL 31 DAY);
-> '1998-02-02'
mysql> SELECT ADDDATE('1998-01-02', INTERVAL 31 DAY);
-> '1998-02-02'
As of MySQL 4.1.1, the second syntax is allowed, where expr is a date
or datetime expression and days is the number of days to be added to
expr.
mysql> SELECT ADDDATE('1998-01-02', 31);
-> '1998-02-02'
ADDTIME(expr,expr2)
ADDTIME() adds expr2 to expr and returns the result.
expr is a time or datetime expression, and expr2 is a time
expression.
mysql> SELECT ADDTIME('1997-12-31 23:59:59.999999',
-> '1 1:1:1.000002');
-> '1998-01-02 01:01:01.000001'
mysql> SELECT ADDTIME('01:00:00.999999', '02:00:00.999998');
-> '03:00:01.999997'
ADDTIME() was added in MySQL 4.1.1.
CONVERT_TZ(dt,from_tz,to_tz)
CONVERT_TZ()
converts a datetime value dt from time zone given by from_tz
to the time zone given by to_tz and returns the resulting value.
Time zones may be specified as described in section 5.8.8 MySQL Server Time Zone Support.
This function returns NULL if the arguments are invalid.
If the value falls out of the supported range of the TIMESTAMP
type when converted fom from_tz to UTC, no conversion occurs.
The TIMESTAMP range is described at
section 11.1.2 Overview of Date and Time Types.
mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','GMT','MET');
-> '2004-01-01 13:00:00'
mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','+00:00','-07:00');
-> '2004-01-01 05:00:00'
To use named time zones such as 'MET' or 'Europe/Moscow',
the time zone tables must be properly set up. See
section 5.8.8 MySQL Server Time Zone Support for instructions.
CONVERT_TZ() was added in MySQL 4.1.3.
CURDATE()
'YYYY-MM-DD' or YYYYMMDD
format, depending on whether the function is used in a string or numeric
context.
mysql> SELECT CURDATE();
-> '1997-12-15'
mysql> SELECT CURDATE() + 0;
-> 19971215
CURRENT_DATE
CURRENT_DATE()
CURRENT_DATE and CURRENT_DATE() are synonyms for
CURDATE().
CURTIME()
'HH:MM:SS' or HHMMSS
format, depending on whether the function is used in a string or numeric
context.
mysql> SELECT CURTIME();
-> '23:50:26'
mysql> SELECT CURTIME() + 0;
-> 235026
CURRENT_TIME
CURRENT_TIME()
CURRENT_TIME and CURRENT_TIME() are synonyms for
CURTIME().
CURRENT_TIMESTAMP
CURRENT_TIMESTAMP()
CURRENT_TIMESTAMP and CURRENT_TIMESTAMP() are synonyms for
NOW().
DATE(expr)
mysql> SELECT DATE('2003-12-31 01:02:03');
-> '2003-12-31'
DATE() is available as of MySQL 4.1.1.
DATEDIFF(expr,expr2)
DATEDIFF() returns the number of days between the start date
expr and the end date expr2.
expr and expr2 are date or date-and-time expressions.
Only the date parts of the values are used in the calculation.
mysql> SELECT DATEDIFF('1997-12-31 23:59:59','1997-12-30');
-> 1
mysql> SELECT DATEDIFF('1997-11-30 23:59:59','1997-12-31');
-> -31
DATEDIFF() was added in MySQL 4.1.1.
DATE_ADD(date,INTERVAL expr type)
DATE_SUB(date,INTERVAL expr type)
DATETIME or DATE value specifying the starting
date. expr is an expression specifying the interval value to be added
or subtracted from the starting date. expr is a string; it may start
with a `-' for negative intervals. type is a keyword indicating
how the expression should be interpreted.
The INTERVAL keyword and the type specifier are not case
sensitive.
The following table shows how the type and expr arguments
are related:
| type Value | Expected expr Format |
MICROSECOND | MICROSECONDS
|
SECOND | SECONDS
|
MINUTE | MINUTES
|
HOUR | HOURS
|
DAY | DAYS
|
WEEK | WEEKS
|
MONTH | MONTHS
|
QUARTER | QUARTERS
|
YEAR | YEARS
|
SECOND_MICROSECOND | 'SECONDS.MICROSECONDS'
|
MINUTE_MICROSECOND | 'MINUTES.MICROSECONDS'
|
MINUTE_SECOND | 'MINUTES:SECONDS'
|
HOUR_MICROSECOND | 'HOURS.MICROSECONDS'
|
HOUR_SECOND | 'HOURS:MINUTES:SECONDS'
|
HOUR_MINUTE | 'HOURS:MINUTES'
|
DAY_MICROSECOND | 'DAYS.MICROSECONDS'
|
DAY_SECOND | 'DAYS HOURS:MINUTES:SECONDS'
|
DAY_MINUTE | 'DAYS HOURS:MINUTES'
|
DAY_HOUR | 'DAYS HOURS'
|
YEAR_MONTH | 'YEARS-MONTHS'
|
DAY_MICROSECOND, HOUR_MICROSECOND,
MINUTE_MICROSECOND, SECOND_MICROSECOND,
and MICROSECOND are allowed as of MySQL 4.1.1.
The values QUARTER and WEEK are allowed as of MySQL 5.0.0.
MySQL allows any punctuation delimiter in the expr format.
Those shown in the table are the suggested delimiters. If the date
argument is a DATE value and your calculations involve only
YEAR, MONTH, and DAY parts (that is, no time parts), the
result is a DATE value. Otherwise, the result is a DATETIME
value.
As of MySQL 3.23, INTERVAL expr type is allowed on either
side of the + operator if the expression on the other side is a
date or datetime value.
For the - operator, INTERVAL expr type is allowed only on
the right side, because
it makes no sense to subtract a date or datetime value from an interval.
(See examples below.)
mysql> SELECT '1997-12-31 23:59:59' + INTERVAL 1 SECOND;
-> '1998-01-01 00:00:00'
mysql> SELECT INTERVAL 1 DAY + '1997-12-31';
-> '1998-01-01'
mysql> SELECT '1998-01-01' - INTERVAL 1 SECOND;
-> '1997-12-31 23:59:59'
mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
-> INTERVAL 1 SECOND);
-> '1998-01-01 00:00:00'
mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
-> INTERVAL 1 DAY);
-> '1998-01-01 23:59:59'
mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
-> INTERVAL '1:1' MINUTE_SECOND);
-> '1998-01-01 00:01:00'
mysql> SELECT DATE_SUB('1998-01-01 00:00:00',
-> INTERVAL '1 1:1:1' DAY_SECOND);
-> '1997-12-30 22:58:59'
mysql> SELECT DATE_ADD('1998-01-01 00:00:00',
-> INTERVAL '-1 10' DAY_HOUR);
-> '1997-12-30 14:00:00'
mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY);
-> '1997-12-02'
mysql> SELECT DATE_ADD('1992-12-31 23:59:59.000002',
-> INTERVAL '1.999999' SECOND_MICROSECOND);
-> '1993-01-01 00:00:01.000001'
If you specify an interval value that is too short (does not include all the
interval parts that would be expected from the type keyword),
MySQL assumes that you have left out the leftmost parts of the interval
value. For example, if you specify a type of DAY_SECOND, the
value of expr is expected to have days, hours, minutes, and seconds
parts. If you specify a value like '1:10', MySQL assumes
that the days and hours parts are missing and the value represents minutes
and seconds. In other words, '1:10' DAY_SECOND is interpreted in such
a way that it is equivalent to '1:10' MINUTE_SECOND. This is
analogous to the way that MySQL interprets TIME values
as representing elapsed time rather than as time of day.
If you add to or subtract from a date value something that
contains a time part, the result is automatically converted to a
datetime value:
mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 DAY);
-> '1999-01-02'
mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 HOUR);
-> '1999-01-01 01:00:00'
If you use really malformed dates, the result is NULL. If you add
MONTH, YEAR_MONTH, or YEAR and the resulting date
has a day that is larger than the maximum day for the new month, the day is
adjusted to the maximum days in the new month:
mysql> SELECT DATE_ADD('1998-01-30', INTERVAL 1 MONTH);
-> '1998-02-28'
DATE_FORMAT(date,format)
| Specifier | Description |
%a | Abbreviated weekday name (Sun..Sat)
|
%b | Abbreviated month name (Jan..Dec)
|
%c | Month, numeric (0..12)
|
%D | Day of the month with English suffix (0th, 1st, 2nd, 3rd, ...)
|
%d | Day of the month, numeric (00..31)
|
%e | Day of the month, numeric (0..31)
|
%f | Microseconds (000000..999999)
|
%H | Hour (00..23)
|
%h | Hour (01..12)
|
%I | Hour (01..12)
|
%i | Minutes, numeric (00..59)
|
%j | Day of year (001..366)
|
%k | Hour (0..23)
|
%l | Hour (1..12)
|
%M | Month name (January..December)
|
%m | Month, numeric (00..12)
|
%p | AM or PM
|
%r | Time, 12-hour (hh:mm:ss followed by AM or PM)
|
%S | Seconds (00..59)
|
%s | Seconds (00..59)
|
%T | Time, 24-hour (hh:mm:ss)
|
%U | Week (00..53), where Sunday is the first day of the week
|
%u | Week (00..53), where Monday is the first day of the week
|
%V | Week (01..53), where Sunday is the first day of the week; used with %X
|
%v | Week (01..53), where Monday is the first day of the week; used with %x
|
%W | Weekday name (Sunday..Saturday)
|
%w | Day of the week (0=Sunday..6=Saturday)
|
%X | Year for the week where Sunday is the first day of the week, numeric, four digits; used with %V
|
%x | Year for the week, where Monday is the first day of the week, numeric, four digits; used with %v
|
%Y | Year, numeric, four digits |
%y | Year, numeric, two digits |
%% | A literal `%'. |
%v, %V, %x, and %X format specifiers are
available as of MySQL 3.23.8. %f is available as of MySQL 4.1.1.
As of MySQL 3.23, the `%' character is required before
format specifier characters. In earlier versions of MySQL,
`%' was optional.
The reason the ranges for the month and day specifiers begin with zero
is that MySQL allows incomplete dates such as '2004-00-00' to be
stored as of MySQL 3.23.
mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%W %M %Y');
-> 'Saturday October 1997'
mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%H:%i:%s');
-> '22:23:00'
mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00',
'%D %y %a %d %m %b %j');
-> '4th 97 Sat 04 10 Oct 277'
mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00',
'%H %k %I %r %T %S %w');
-> '22 22 10 10:23:00 PM 22:23:00 00 6'
mysql> SELECT DATE_FORMAT('1999-01-01', '%X %V');
-> '1998 52'
DAY(date)
DAY() is a synonym for DAYOFMONTH().
It is available as of MySQL 4.1.1.
DAYNAME(date)
mysql> SELECT DAYNAME('1998-02-05');
-> 'Thursday'
DAYOFMONTH(date)
1 to
31.
mysql> SELECT DAYOFMONTH('1998-02-03');
-> 3
DAYOFWEEK(date)
1 = Sunday, 2 = Monday, ..., 7 =
Saturday). These index values correspond to the ODBC standard.
mysql> SELECT DAYOFWEEK('1998-02-03');
-> 3
DAYOFYEAR(date)
1 to
366.
mysql> SELECT DAYOFYEAR('1998-02-03');
-> 34
EXTRACT(type FROM date)
EXTRACT() function uses the same kinds of interval type
specifiers as DATE_ADD() or DATE_SUB(), but extracts parts
from the date rather than performing date arithmetic.
mysql> SELECT EXTRACT(YEAR FROM '1999-07-02');
-> 1999
mysql> SELECT EXTRACT(YEAR_MONTH FROM '1999-07-02 01:02:03');
-> 199907
mysql> SELECT EXTRACT(DAY_MINUTE FROM '1999-07-02 01:02:03');
-> 20102
mysql> SELECT EXTRACT(MICROSECOND
-> FROM '2003-01-02 10:30:00.00123');
-> 123
EXTRACT() was added in MySQL 3.23.0.
FROM_DAYS(N)
DATE value.
mysql> SELECT FROM_DAYS(729669);
-> '1997-10-07'
FROM_DAYS() is not intended for use with values that precede the
advent of the Gregorian calendar (1582), because it does not take into account
the days that were lost when the calendar was changed.
FROM_UNIXTIME(unix_timestamp)
FROM_UNIXTIME(unix_timestamp,format)
'YYYY-MM-DD HH:MM:SS' or YYYYMMDDHHMMSS format, depending on
whether the function is used in a string or numeric context.
mysql> SELECT FROM_UNIXTIME(875996580);
-> '1997-10-04 22:23:00'
mysql> SELECT FROM_UNIXTIME(875996580) + 0;
-> 19971004222300
If format is given, the result is formatted according to the
format string. format may contain the same specifiers as
those listed in the entry for the DATE_FORMAT() function.
mysql> SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(),
-> '%Y %D %M %h:%i:%s %x');
-> '2003 6th August 06:22:58 2003'
GET_FORMAT(DATE|TIME|DATETIME, 'EUR'|'USA'|'JIS'|'ISO'|'INTERNAL')
DATE_FORMAT() and the STR_TO_DATE() functions.
The three possible values for the first argument
and the five possible values for the second argument result in 15 possible
format strings (for the specifiers used, see the table in the
DATE_FORMAT() function description).
| Function Call | Result |
GET_FORMAT(DATE,'USA') | '%m.%d.%Y'
|
GET_FORMAT(DATE,'JIS') | '%Y-%m-%d'
|
GET_FORMAT(DATE,'ISO') | '%Y-%m-%d'
|
GET_FORMAT(DATE,'EUR') | '%d.%m.%Y'
|
GET_FORMAT(DATE,'INTERNAL') | '%Y%m%d'
|
GET_FORMAT(DATETIME,'USA') | '%Y-%m-%d-%H.%i.%s'
|
GET_FORMAT(DATETIME,'JIS') | '%Y-%m-%d %H:%i:%s'
|
GET_FORMAT(DATETIME,'ISO') | '%Y-%m-%d %H:%i:%s'
|
GET_FORMAT(DATETIME,'EUR') | '%Y-%m-%d-%H.%i.%s'
|
GET_FORMAT(DATETIME,'INTERNAL') | '%Y%m%d%H%i%s'
|
GET_FORMAT(TIME,'USA') | '%h:%i:%s %p'
|
GET_FORMAT(TIME,'JIS') | '%H:%i:%s'
|
GET_FORMAT(TIME,'ISO') | '%H:%i:%s'
|
GET_FORMAT(TIME,'EUR') | '%H.%i.%S'
|
GET_FORMAT(TIME,'INTERNAL') | '%H%i%s'
|
TIMESTAMP can also be used;
GET_FORMAT() returns the same values as for DATETIME.
mysql> SELECT DATE_FORMAT('2003-10-03',GET_FORMAT(DATE,'EUR'));
-> '03.10.2003'
mysql> SELECT STR_TO_DATE('10.31.2003',GET_FORMAT(DATE,'USA'));
-> 2003-10-31
GET_FORMAT() is available as of MySQL 4.1.1.
See section 13.5.3 SET Syntax.
HOUR(time)
0 to 23 for time-of-day values.
mysql> SELECT HOUR('10:05:03');
-> 10
However, the range of TIME values actually is much larger, so
HOUR can return values greater than 23.
mysql> SELECT HOUR('272:59:59');
-> 272
LAST_DAY(date)
NULL if the argument is invalid.
mysql> SELECT LAST_DAY('2003-02-05');
-> '2003-02-28'
mysql> SELECT LAST_DAY('2004-02-05');
-> '2004-02-29'
mysql> SELECT LAST_DAY('2004-01-01 01:01:01');
-> '2004-01-31'
mysql> SELECT LAST_DAY('2003-03-32');
-> NULL
LAST_DAY() is available as of MySQL 4.1.1.
LOCALTIME
LOCALTIME()
LOCALTIME and LOCALTIME() are synonyms for
NOW().
They were added in MySQL 4.0.6.
LOCALTIMESTAMP
LOCALTIMESTAMP()
LOCALTIMESTAMP and LOCALTIMESTAMP() are synonyms for
NOW().
They were added in MySQL 4.0.6.
MAKEDATE(year,dayofyear)
NULL.
mysql> SELECT MAKEDATE(2001,31), MAKEDATE(2001,32);
-> '2001-01-31', '2001-02-01'
mysql> SELECT MAKEDATE(2001,365), MAKEDATE(2004,365);
-> '2001-12-31', '2004-12-30'
mysql> SELECT MAKEDATE(2001,0);
-> NULL
MAKEDATE() is available as of MySQL 4.1.1.
MAKETIME(hour,minute,second)
mysql> SELECT MAKETIME(12,15,30);
-> '12:15:30'
MAKETIME() is available as of MySQL 4.1.1.
MICROSECOND(expr)
0 to 999999.
mysql> SELECT MICROSECOND('12:00:00.123456');
-> 123456
mysql> SELECT MICROSECOND('1997-12-31 23:59:59.000010');
-> 10
MICROSECOND() is available as of MySQL 4.1.1.
MINUTE(time)
0 to 59.
mysql> SELECT MINUTE('98-02-03 10:05:03');
-> 5
MONTH(date)
1 to 12.
mysql> SELECT MONTH('1998-02-03');
-> 2
MONTHNAME(date)
mysql> SELECT MONTHNAME('1998-02-05');
-> 'February'
NOW()
'YYYY-MM-DD HH:MM:SS'
or YYYYMMDDHHMMSS format, depending on whether the function is used in
a string or numeric context.
mysql> SELECT NOW();
-> '1997-12-15 23:50:26'
mysql> SELECT NOW() + 0;
-> 19971215235026
PERIOD_ADD(P,N)
YYMM or
YYYYMM). Returns a value in the format YYYYMM.
Note that the period argument P is not a date value.
mysql> SELECT PERIOD_ADD(9801,2);
-> 199803
PERIOD_DIFF(P1,P2)
YYMM or YYYYMM.
Note that the period arguments P1 and P2 are not
date values.
mysql> SELECT PERIOD_DIFF(9802,199703);
-> 11
QUARTER(date)
1
to 4.
mysql> SELECT QUARTER('98-04-01');
-> 2
SECOND(time)
0 to 59.
mysql> SELECT SECOND('10:05:03');
-> 3
SEC_TO_TIME(seconds)
'HH:MM:SS' or HHMMSS format, depending on whether
the function is used in a string or numeric context.
mysql> SELECT SEC_TO_TIME(2378);
-> '00:39:38'
mysql> SELECT SEC_TO_TIME(2378) + 0;
-> 3938
STR_TO_DATE(str,format)
DATE_FORMAT() function. It takes a
string str and a format string format.
STR_TO_DATE() returns a DATETIME value if the format
string contains both date and time parts, or a DATE or TIME
value if the string contains only date or time parts.
The date, time, or datetime values contained in str should be given
in the format indicated by format. For the specifiers that can be
used in format, see the table in the DATE_FORMAT() function
description. All other characters are just taken verbatim, thus not being
interpreted.
If str contains an illegal date, time, or datetime value,
STR_TO_DATE() returns NULL. Starting from MySQL 5.0.3, an
illegal value also produces a warning.
mysql> SELECT STR_TO_DATE('03.10.2003 09.20',
-> '%d.%m.%Y %H.%i');
-> '2003-10-03 09:20:00'
mysql> SELECT STR_TO_DATE('10arp', '%carp');
-> '0000-10-00 00:00:00'
mysql> SELECT STR_TO_DATE('2003-15-10 00:00:00',
-> '%Y-%m-%d %H:%i:%s');
-> NULL
Range checking on the parts of date values is as described in
section 11.3.1 The DATETIME, DATE, and TIMESTAMP Types. This means, for example, that a date with
a day part larger than the number of days in a month is allowable as long
as the day part is in the range from 1 to 31. Also, ``zero'' dates or dates
with part values of 0 are allowed.
mysql> SELECT STR_TO_DATE('00/00/0000', '%m/%d/%Y');
-> '0000-00-00'
mysql> SELECT STR_TO_DATE('04/31/2004', '%m/%d/%Y');
-> '2004-04-31'
STR_TO_DATE() is available as of MySQL 4.1.1.
SUBDATE(date,INTERVAL expr type)
SUBDATE(expr,days)
INTERVAL form of the second argument,
SUBDATE() is a synonym for DATE_SUB().
For information on the INTERVAL argument, see the
discussion for DATE_ADD().
mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY);
-> '1997-12-02'
mysql> SELECT SUBDATE('1998-01-02', INTERVAL 31 DAY);
-> '1997-12-02'
As of MySQL 4.1.1, the second syntax is allowed, where expr is a date
or datetime expression and days is the number of days to be
subtracted from expr.
mysql> SELECT SUBDATE('1998-01-02 12:00:00', 31);
-> '1997-12-02 12:00:00'
SUBTIME(expr,expr2)
SUBTIME() subtracts expr2 from expr and returns the result.
expr is a time or datetime expression, and expr2 is a time
expression.
mysql> SELECT SUBTIME('1997-12-31 23:59:59.999999',
-> '1 1:1:1.000002');
-> '1997-12-30 22:58:58.999997'
mysql> SELECT SUBTIME('01:00:00.999999', '02:00:00.999998');
-> '-00:59:59.999999'
SUBTIME() was added in MySQL 4.1.1.
SYSDATE()
SYSDATE() is a synonym for NOW().
TIME(expr)
mysql> SELECT TIME('2003-12-31 01:02:03');
-> '01:02:03'
mysql> SELECT TIME('2003-12-31 01:02:03.000123');
-> '01:02:03.000123'
TIME() is available as of MySQL 4.1.1.
TIMEDIFF(expr,expr2)
TIMEDIFF() returns the time between the start time
expr and the end time expr2.
expr and expr2 are time or date-and-time expressions, but both
must be of the same type.
mysql> SELECT TIMEDIFF('2000:01:01 00:00:00',
-> '2000:01:01 00:00:00.000001');
-> '-00:00:00.000001'
mysql> SELECT TIMEDIFF('1997-12-31 23:59:59.000001',
-> '1997-12-30 01:01:01.000002');
-> '46:58:57.999999'
TIMEDIFF() was added in MySQL 4.1.1.
TIMESTAMP(expr)
TIMESTAMP(expr,expr2)
mysql> SELECT TIMESTAMP('2003-12-31');
-> '2003-12-31 00:00:00'
mysql> SELECT TIMESTAMP('2003-12-31 12:00:00','12:00:00');
-> '2004-01-01 00:00:00'
TIMESTAMP() is available as of MySQL 4.1.1.
TIMESTAMPADD(interval,int_expr,datetime_expr)
interval argument, which should be one of the following values:
FRAC_SECOND,
SECOND,
MINUTE,
HOUR,
DAY,
WEEK,
MONTH,
QUARTER,
or
YEAR.
The interval value may be specified using one of keywords as shown,
or with a prefix of SQL_TSI_. For example, DAY or
SQL_TSI_DAY both are legal.
mysql> SELECT TIMESTAMPADD(MINUTE,1,'2003-01-02');
-> '2003-01-02 00:01:00'
mysql> SELECT TIM