MySQL Reference Manual for version 4.1.7.
1 General Information
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/Free Software 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 section 1.4 MySQL Support and Licensing.
The MySQL Web site (http://www.mysql.com/) provides the latest information about the MySQL software.
The following list describes some sections of particular interest in this manual:
- For information about the company behind the MySQL Database Server, see section 1.3 Overview of MySQL AB.
- For a discussion about the capabilities of the MySQL Database Server, see section 1.2.2 The Main Features of MySQL.
- For installation instructions, see section 2 Installing MySQL.
- For tips on porting the MySQL Database Software to new architectures or operating systems, see section D Porting to Other Systems.
- For information about upgrading from a Version 4.0 release, see section 2.5.2 Upgrading from Version 4.0 to 4.1.
- For information about upgrading from a Version 3.23 release, see section 2.5.3 Upgrading from Version 3.23 to 4.0.
- For information about upgrading from a Version 3.22 release, see section 2.5.4 Upgrading from Version 3.22 to 3.23.
- For a tutorial introduction to the MySQL Database Server, see section 3 MySQL Tutorial.
- For examples of SQL and benchmarking information, see the benchmarking directory (`sql-bench' in the distribution).
- For a history of new features and bugfixes, see section C MySQL Change History.
- For a list of currently known bugs and misfeatures, see section 1.8.7 Known Errors and Design Deficiencies in MySQL.
- For future plans, see section 1.6 MySQL and the Future (the TODO).
- For a list of all the contributors to this project, see section B Credits.
Important:
Reports of errors (often called ``bugs''), as well as questions and comments, should be sent to the general MySQL mailing list. See section 1.7.1.1 The MySQL Mailing Lists. See section 1.7.1.3 How to Report Bugs or Problems.
The @command{mysqlbug} script should be used to generate bug reports on Unix. (Windows distributions contain a file named `mysqlbug.txt' in the base directory that can be used as a template for a bug report.)
For source distributions, the @command{mysqlbug} script can be found in the
`scripts' directory. For binary distributions, @command{mysqlbug}
can be found in the `bin' directory (`/usr/bin' for the
MySQL-server
RPM package).
If you have found a sensitive security bug in MySQL Server, please let us know immediately by sending an email message to [email protected].
1.1 About This Manual
This is the Reference Manual for the MySQL Database System. It documents MySQL up to Version 4.1.7, 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 will 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 @command{texi2html}. The plain text and Info versions are produced with @command{makeinfo}. The PostScript version is produced using @command{texi2dvi} and @command{dvips}. The PDF version is produced with @command{pdftex}.
If you have any suggestions concerning additions or corrections to this manual, please send them to the documentation team at [email protected].
This manual was initially written by David Axmark and Michael ``Monty'' Widenius. It is now maintained by the MySQL Documentation Team, consisting of Arjen Lentz, Paul DuBois, and Stefan Hinz. For the many other contributors, see section B Credits.
The copyright (2004) to this manual is owned by the Swedish company MySQL AB. See section 1.4.2 Copyrights and Licenses Used by MySQL. 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.
1.1.1 Conventions Used in This Manual
This manual uses certain typographical conventions:
constant
-
Constant-width font is used for command names and options; SQL statements;
database, table, and column names; C and Perl code; and environment variables.
Example: ``To see how @command{mysqladmin} works, invoke it with the
--help
option.'' - constant italic
- Italic constant-width font is used to indicate variable input for which you should substitute a value of your own choosing.
- `filename'
- Constant-width font with surrounding quotes is used for filenames and pathnames. Example: ``The distribution is installed under the `/usr/local/' directory.''
- `c'
- Constant-width font with surrounding quotes is also used to indicate character sequences. Example: ``To specify a wildcard, use the `%' character.''
- italic
- Italic font is used for emphasis, like this.
- boldface
- Boldface font is used in table headings and to convey especially strong emphasis.
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
@command{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 @command{sh} or @command{csh}. On Windows, the equivalent program is @command{command.com} or @command{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 @command{csh} or @command{tcsh}, you must issue commands somewhat differently. You would execute the sequence just shown like this:
shell> setenv VARNAME value shell> some_command
1.2 Overview of the MySQL Database Management System
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. See section 1.3 Overview of MySQL AB.
The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL software and MySQL AB.
- MySQL is a database management system.
- A database is a structured collection of data. It may be anything from a simple shopping list to a picture gallery or the vast amounts of information in a corporate network. To add, access, and process data stored in a computer database, you need a database management system such as MySQL Server. Since computers are very good at handling large amounts of data, database management systems play a central role in computing, as standalone utilities or as parts of other applications.
- MySQL is a relational database management system.
- A relational database stores data in separate tables rather than putting all the data in one big storeroom. This adds speed and flexibility. The SQL part of ``MySQL'' stands for ``Structured Query Language.'' SQL is the most common standardized language used to access databases and is defined by the ANSI/ISO SQL Standard. 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.
- MySQL software is Open Source.
- Open Source means that it is possible for anyone to use and modify the software. Anybody can download the MySQL software from the Internet and use it without paying anything. If you wish, you may study the source code and change it to suit your needs. The MySQL software uses the GPL (GNU General Public License), http://www.fsf.org/licenses/, to define what you may and may not do with the software in different situations. If you feel uncomfortable with the GPL or need to embed MySQL code into a commercial application, you can buy a commercially licensed version from us. See section 1.4.3 MySQL Licenses.
- The MySQL Database Server is very fast, reliable, and easy to use.
- If that is what you are looking for, you should give it a try. MySQL Server also has a practical set of features developed in close cooperation with our users. You can find a performance comparison of MySQL Server with other database managers on our benchmark page. See section 7.1.4 The MySQL Benchmark Suite. MySQL Server was originally developed to handle large databases much faster than existing solutions and has been successfully used in highly demanding production environments for several years. Although under constant development, MySQL Server today offers a rich and useful set of functions. Its connectivity, speed, and security make MySQL Server highly suited for accessing databases on the Internet.
- MySQL Server works in client/server or embedded systems.
- The MySQL Database Software is a client/server system that consists of a multi-threaded SQL server that supports different backends, several different client programs and libraries, administrative tools, and a wide range of application programming interfaces (APIs). We also provide MySQL Server as an embedded multi-threaded library that you can link into your application to get a smaller, faster, easier-to-manage product.
- A large amount of contributed MySQL software is available.
- It is very likely that you will find that your favorite application or language already supports the MySQL Database Server.
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.
1.2.1 History of MySQL
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.
1.2.2 The Main Features of MySQL
The following list describes some of the important characteristics of the MySQL Database Software. See also section 1.5 MySQL Development Roadmap for more information about current and upcoming features.
- Internals and Portability
-
- Written in C and C++.
- Tested with a broad range of different compilers.
- Works on many different platforms. See section 2.1.1 Operating Systems Supported by MySQL.
- Uses GNU Automake, Autoconf, and Libtool for portability.
- APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are available. See section 21 MySQL APIs.
- Fully multi-threaded using kernel threads. It can easily use multiple CPUs if they are available.
- Provides transactional and non-transactional storage engines.
-
Uses very fast B-tree disk tables (
MyISAM
) with index compression. - Relatively easy to add another storage engine. This is useful if you want to add an SQL interface to an in-house database.
- A very fast thread-based memory allocation system.
- Very fast joins using an optimized one-sweep multi-join.
- In-memory hash tables, which are used as temporary tables.
- SQL functions are implemented using a highly optimized class library and should be as fast as possible. Usually there is no memory allocation at all after query initialization.
- The MySQL code is tested with Purify (a commercial memory leakage detector) as well as with Valgrind, a GPL tool (http://developer.kde.org/~sewardj/).
- The server is available as a separate program for use in a client/server networked environment. It is also available as a library that can be embedded (linked) into standalone applications. Such applications can be used in isolation or in environments where no network is available.
- Column Types
-
-
Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes
long,
FLOAT
,DOUBLE
,CHAR
,VARCHAR
,TEXT
,BLOB
,DATE
,TIME
,DATETIME
,TIMESTAMP
,YEAR
,SET
,ENUM
, and OpenGIS spatial types. See section 12 Column Types. - Fixed-length and variable-length records.
-
Many column types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes
long,
- Statements and Functions
-
-
Full operator and function support in the
SELECT
andWHERE
clauses of queries. For example:mysql> SELECT CONCAT(first_name, ' ', last_name) -> FROM citizen -> WHERE income/dependents > 10000 AND age > 30;
-
Full support for SQL
GROUP BY
andORDER BY
clauses. Support for group functions (COUNT()
,COUNT(DISTINCT ...)
,AVG()
,STD()
,SUM()
,MAX()
,MIN()
, andGROUP_CONCAT()
). -
Support for
LEFT OUTER JOIN
andRIGHT OUTER JOIN
with both standard SQL and ODBC syntax. - Support for aliases on tables and columns as required by standard SQL.
-
DELETE
,INSERT
,REPLACE
, andUPDATE
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. -
The MySQL-specific
SHOW
command can be used to retrieve information about databases, tables, and indexes. TheEXPLAIN
command can be used to determine how the optimizer resolves a query. -
Function names do not clash with table or column names. For example,
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 10.6 Treatment of Reserved Words in MySQL. - You can mix tables from different databases in the same query (as of MySQL 3.22).
-
Full operator and function support in the
- Security
-
- A privilege and password system that is very flexible and secure, and that allows host-based verification. Passwords are secure because all password traffic is encrypted when you connect to a server.
- Scalability and Limits
-
- Handles large databases. We use MySQL Server with databases that contain 50 million records. We also know of users who use MySQL Server with 60,000 tables and about 5,000,000,000 rows.
-
Up to 64 indexes per table are allowed (32 before MySQL 4.1.2). Each index may
consist of 1 to 16 columns or parts of columns. The maximum index width is
1000 bytes (500 before MySQL 4.1.2).
An index may use a prefix of a column for
CHAR
,VARCHAR
,BLOB
, orTEXT
column types.
- Connectivity
-
- Clients can connect to the MySQL server using TCP/IP sockets on any platform. On Windows systems in the NT family (NT, 2000, or XP), clients can connect using named pipes. On Unix systems, clients can connect using Unix domain socket files.
- The Connector/ODBC (MyODBC) interface provides MySQL support for client programs that use ODBC (Open Database Connectivity) connections. For example, you can use MS Access to connect to your MySQL server. Clients can be run on Windows or Unix. MyODBC source is available. All ODBC 2.5 functions are supported, as are many others. See section 22.1 MySQL ODBC Support.
- The Connector/J interface provides MySQL support for Java client programs that use JDBC connections. Clients can be run on Windows or Unix. Connector/J source is available. See section 22.2 MySQL Java Connectivity (JDBC).
- Localization
-
- The server can provide error messages to clients in many languages. See section 5.8.2 Setting the Error Message Language.
-
Full support for several different character sets, including
latin1
(ISO-8859-1),german
,big5
,ujis
, and more. For example, the Scandinavian characters `@^a', `@"a' and `@"o' are allowed in table and column names. Unicode support is available as of MySQL 4.1. - All data is saved in the chosen character set. All comparisons for normal string columns are case-insensitive.
- Sorting is done according to the chosen character set (using Swedish collation by default). It is possible to change this when the MySQL server is started. To see an example of very advanced sorting, look at the Czech sorting code. MySQL Server supports many different character sets that can be specified at compile time and runtime.
- Clients and Tools
-
-
The MySQL server has built-in support for SQL statements to check,
optimize, and repair tables. These statements are available from the
command line through the @command{mysqlcheck} client. MySQL also includes
@command{myisamchk}, a very fast command-line utility for performing these
operations on
MyISAM
tables. See section 5 Database Administration. -
All MySQL programs can be invoked with the
--help
or-?
options to obtain online assistance.
-
The MySQL server has built-in support for SQL statements to check,
optimize, and repair tables. These statements are available from the
command line through the @command{mysqlcheck} client. MySQL also includes
@command{myisamchk}, a very fast command-line utility for performing these
operations on
1.2.3 MySQL Stability
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.8.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:
- Replication (Stable)
- Large groups of servers using replication are in production use, with good results. Work on enhanced replication features is continuing in MySQL 5.x.
InnoDB
tables (Stable)-
The
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)-
The
Berkeley DB
code is very stable, but we are still improving theBDB
transactional storage engine interface in MySQL Server. - Full-text searches (Stable)
- Full-text searching is widely used. Important feature enhancements were added in MySQL 4.0 and 4.1.
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.
1.2.4 How Big MySQL Tables Can Be
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 now usually is 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:
Operating System | File-size Limit |
Linux-Intel 32-bit | 2GB, much more when using LFS |
Linux-Alpha | 8TB (?) |
Solaris 2.5.1 | 2GB (4GB possible with patch) |
Solaris 2.6 | 4GB (can be changed with flag) |
Solaris 2.7 Intel | 4GB |
Solaris 2.7 UltraSPARC | 512GB |
NetWare w/NSS filesystem | 8TB |
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. Most
current Linux distributions are based on kernel 2.4 and already include all
the required LFS patches. 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.
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 @command{myisamchk -dv tbl_name}.
See section 14.5.3 SET
and SHOW
Syntax.
If you need a MyISAM
table that will be 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 14.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 14.2.2 ALTER TABLE
Syntax.
Other ways to work around file-size limits for MyISAM
tables are as
follows:
- If your large table is read-only, you can use @command{myisampack} to compress it. @command{myisampack} usually compresses a table by at least 50%, so you can have, in effect, much bigger tables. @command{myisampack} also can merge multiple tables into a single table. @xref{myisampack, , @command{myisampack}}.
-
Another way to get around the operating system file limit for
MyISAM
data files is by using theRAID
options. See section 14.2.6CREATE TABLE
Syntax. -
MySQL includes a
MERGE
library that allows you to handle a collection ofMyISAM
tables that have identical structure as a singleMERGE
table. See section 15.2 TheMERGE
Storage Engine.
1.2.5 Year 2000 Compliance
The MySQL Server itself has no problems with Year 2000 (Y2K) compliance:
-
MySQL Server uses Unix time functions that handle dates into the year
2037
forTIMESTAMP
values. ForDATE
andDATETIME
values, dates through the year9999
are accepted. - All MySQL date functions are implemented in one source file, `sql/time.cc', and are coded very carefully to be year 2000-safe.
-
In MySQL 3.22 and later, the
YEAR
column type can store years0
and1901
to2155
in one byte and display them using two or four digits. All two-digit years are considered to be in the range1970
to2069
, which means that if you store01
in aYEAR
column, MySQL Server treats it as2001
.
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 12.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.
1.3 Overview of MySQL AB
MySQL AB is the company of the MySQL founders and main developers. MySQL AB was originally established in Sweden by David Axmark, Allan Larsson, and Michael ``Monty'' Widenius.
The developers of the MySQL server are all employed by the company. We are a virtual organization with people in a dozen countries around the world. We communicate extensively over the Internet every day with one another and with our users, supporters, and partners.
We are dedicated to developing the MySQL database software and promoting it to new users. MySQL AB owns the copyright to the MySQL source code, the MySQL logo and (registered) trademark, and this manual. See section 1.2 Overview of the MySQL Database Management System.
The MySQL core values show our dedication to MySQL and Open Source.
These core values direct how MySQL AB works with the MySQL server software:
- To be the best and the most widely used database in the world
- To be available and affordable by all
- To be easy to use
- To be continuously improved while remaining fast and safe
- To be fun to use and improve
- To be free from bugs
These are the core values of the company MySQL AB and its employees:
- We subscribe to the Open Source philosophy and support the Open Source community
- We aim to be good citizens
- We prefer partners that share our values and mindset
- We answer email and provide support
- We are a virtual company, networking with others
- We work against software patents
The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL and MySQL AB.
By the way, the ``AB'' part of the company name is the acronym for the Swedish ``aktiebolag,'' or ``stock company.'' It translates to ``MySQL, Inc.'' In fact, MySQL, Inc. and MySQL GmbH are examples of MySQL AB subsidiaries. They are located in the US and Germany, respectively.
1.3.1 The Business Model and Services of MySQL AB
One of the most common questions we encounter is, ``How can you make a living from something you give away for free?'' This is how:
- MySQL AB makes money on support, services, commercial licenses, and royalties.
- We use these revenues to fund product development and to expand the MySQL business.
The company has been profitable since its inception. In October 2001, we accepted venture financing from leading Scandinavian investors and a handful of business angels. This investment is used to solidify our business model and build a basis for sustainable growth.
1.3.1.1 Support
MySQL AB is run and owned by the founders and main developers of the MySQL database. The developers are committed to providing support to customers and other users in order to stay in touch with their needs and problems. All our support is provided by qualified developers. Really tricky questions are answered by Michael ``Monty'' Widenius, principal author of the MySQL Server.
Paying customers receive high-quality support directly from MySQL AB. MySQL AB also provides the MySQL mailing lists as a community resource where anyone may ask questions.
For more information and ordering support at various levels, see section 1.4 MySQL Support and Licensing.
1.3.1.2 Training and Certification
MySQL AB delivers MySQL and related training worldwide. We offer both open courses and in-house courses tailored to the specific needs of your company. MySQL Training is also available through our partners, the Authorized MySQL Training Centers.
Our training material uses the same sample databases used in our documentation and our sample applications, and is always updated to reflect the latest MySQL version. Our trainers are backed by the development team to guarantee the quality of the training and the continuous development of the course material. This also ensures that no questions raised during the courses remain unanswered.
Attending our training courses will enable you to achieve your MySQL application goals. You will also:
- Save time
- Improve the performance of your applications
- Reduce or eliminate the need for additional hardware, decreasing cost
- Enhance security.
- Increase customer and co-worker satisfaction
- Prepare yourself for MySQL Certification
If you are interested in our training as a potential participant or as a training partner, please visit the training section at http://www.mysql.com/training/, or send email to [email protected].
For details about the MySQL Certification Program, please see http://www.mysql.com/certification/.
1.3.1.3 Consulting
MySQL AB and its Authorized Partners offer consulting services to users of MySQL Server and to those who embed MySQL Server in their own software, all over the world.
Our consultants can help you design and tune your databases, construct efficient queries, tune your platform for optimal performance, resolve migration issues, set up replication, build robust transactional applications, and more. We also help customers embed MySQL Server in their products and applications for large-scale deployment.
Our consultants work in close collaboration with our development team, which ensures the technical quality of our professional services. Consulting assignments range from two-day power-start sessions to projects that span weeks and months. Our expertise covers not only MySQL Server, it also extends into programming and scripting languages such as PHP, Perl, and more.
If you are interested in our consulting services or want to become a consulting partner, please visit the consulting section of our Web site at http://www.mysql.com/consulting/ or contact our consulting staff at [email protected].
1.3.1.4 Commercial Licenses
The MySQL database is released under the GNU General Public License (GPL). This means that the MySQL software can be used free of charge under the GPL. If you do not want to be bound by the GPL terms (such as the requirement that your application must also be GPL), you may purchase a commercial license for the same product from MySQL AB; see https://order.mysql.com/. Since MySQL AB owns the copyright to the MySQL source code, we are able to employ Dual Licensing, which means that the same product is available under GPL and under a commercial license. This does not in any way affect the Open Source commitment of MySQL AB. For details about when a commercial license is required, please see section 1.4.3 MySQL Licenses.
We also sell commercial licenses of third-party Open Source GPL
software that adds value to MySQL Server. A good example is the
InnoDB
transactional storage engine that offers ACID
support, row-level locking, crash recovery, multi-versioning, foreign
key support, and more. See section 16 The InnoDB
Storage Engine.
1.3.1.5 Partnering
MySQL AB has a worldwide partner program that covers training courses, consulting and support, publications, plus reselling and distributing MySQL and related products. MySQL AB Partners get visibility on the http://www.mysql.com/ Web site and the right to use special versions of the MySQL (registered) trademarks to identify their products and promote their business.
If you are interested in becoming a MySQL AB Partner, please email [email protected].
The word MySQL and the MySQL dolphin logo are (registered) trademarks of MySQL AB. See section 1.4.4 MySQL AB Logos and Trademarks. These trademarks represent a significant value that the MySQL founders have built over the years.
The MySQL Web site (http://www.mysql.com/) is popular among developers and users. In December 2003, we served 16 million page views. Our visitors represent a group that makes purchase decisions and recommendations for both software and hardware. Twelve percent of our visitors authorize purchase decisions, and only nine percent have no involvement at all in purchase decisions. More than 65% have made one or more online business purchases within the last half-year, and 70% plan to make one in the next few months.
1.3.2 Contact Information
The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL and MySQL AB.
For press services and inquiries not covered in our news releases (http://www.mysql.com/news-and-events/), please send email to [email protected].
If you have a support contract with MySQL AB, you will get timely, precise answers to your technical questions about the MySQL software. For more information, see section 1.4.1 Support Offered by MySQL AB. On our Web site, see http://www.mysql.com/support/, or send email to [email protected].
For information about MySQL training, please visit the training section at http://www.mysql.com/training/, or send email to [email protected]. See section 1.3.1.2 Training and Certification.
For information on the MySQL Certification Program, please see http://www.mysql.com/certification/. See section 1.3.1.2 Training and Certification.
If you're interested in consulting, please visit the consulting section of our Web site at http://www.mysql.com/consulting/, or send email to [email protected]. See section 1.3.1.3 Consulting.
Commercial licenses may be purchased online at https://order.mysql.com/. There you will also find information on how to fax your purchase order to MySQL AB. More information about licensing can be found at http://www.mysql.com/products/licensing/. If you have questions regarding licensing or you want a quote for high-volume licensing, please fill in the contact form on our Web site (http://www.mysql.com/), or send email to [email protected] (for licensing questions) or to [email protected] (for sales inquiries). See section 1.4.3 MySQL Licenses.
If you represent a business that is interested in partnering with MySQL AB, please send email to [email protected]. See section 1.3.1.5 Partnering.
For more information on the MySQL trademark policy, refer to http://www.mysql.com/company/trademark.html, or send email to [email protected]. See section 1.4.4 MySQL AB Logos and Trademarks.
If you are interested in any of the MySQL AB jobs listed in our jobs section (http://www.mysql.com/company/jobs/), please send email to [email protected]. Please do not send your CV as an attachment, but rather as plain text at the end of your email message.
For general discussion among our many users, please direct your attention to the appropriate mailing list. See section 1.7.1 MySQL Mailing Lists.
Reports of errors (often called ``bugs''), as well as questions and comments, should be sent to the general MySQL mailing list. See section 1.7.1.1 The MySQL Mailing Lists. If you have found a sensitive security bug in MySQL Server, please let us know immediately by sending email to [email protected]. See section 1.7.1.3 How to Report Bugs or Problems.
If you have benchmark results that we can publish, please contact us via email at [email protected].
If you have suggestions concerning additions or corrections to this manual, please send them to the documentation team via email at [email protected].
For questions or comments about the workings or content of the MySQL Web site (http://www.mysql.com/), please send email to [email protected].
MySQL AB has a privacy policy, which can be read at http://www.mysql.com/company/privacy.html. For any queries regarding this policy, please send email to [email protected].
For all other inquiries, please send email to [email protected].
1.4 MySQL Support and Licensing
This section describes MySQL support and licensing arrangements.
1.4.1 Support Offered by MySQL AB
Technical support from MySQL AB means individualized answers to your unique problems direct from the software engineers who code the MySQL database engine.
We try to take a broad and inclusive view of technical support. Almost any problem involving MySQL software is important to us if it's important to you. Typically customers seek help on how to get different commands and utilities to work, remove performance bottlenecks, restore crashed systems, understand the impact of operating system or networking issues on MySQL, set up best practices for backup and recovery, utilize APIs, and so on. Our support covers only the MySQL server and our own utilities, not third-party products that access the MySQL server, although we try to help with these where we can.
Detailed information about our various support options is given at http://www.mysql.com/support/, where support contracts can also be ordered online. To contact our sales staff, send email to [email protected].
Technical support is like life insurance. You can live happily without it for years. However, when your hour arrives, it becomes critically important, but it's too late to buy it. If you use MySQL Server for important applications and encounter sudden difficulties, it may be too time-consuming to figure out all the answers yourself. You may need immediate access to the most experienced MySQL troubleshooters available, those employed by MySQL AB.
1.4.2 Copyrights and Licenses Used by MySQL
MySQL AB owns the copyright to the MySQL source code, the MySQL logos and (registered) trademarks, and this manual. See section 1.3 Overview of MySQL AB. Several different licenses are relevant to the MySQL distribution:
-
All the MySQL-specific source in the server, the
mysqlclient
library and the client, as well as the GNUreadline
library, are covered by the GNU General Public License. See section G GNU General Public License. The text of this license can be found as the file `COPYING' in MySQL distributions. -
The GNU
getopt
library is covered by the GNU Lesser General Public License. See http://www.fsf.org/licenses/. -
Some parts of the source (the
regexp
library) are covered by a Berkeley-style copyright. - Older versions of MySQL (3.22 and earlier) are subject to a stricter license (http://www.mysql.com/products/licensing/mypl.html). See the documentation of the specific version for information.
-
The MySQL Reference Manual is not distributed
under a GPL-style license. Use of the manual is subject to the
following terms:
- Conversion to other formats is allowed, but the actual content may not be altered or edited in any way.
- You may create a printed copy for your own personal use.
- For all other uses, such as selling printed copies or using (parts of) the manual in another publication, prior written agreement from MySQL AB is required.
For information about how the MySQL licenses work in practice, please refer to section 1.4.3 MySQL Licenses and section 1.4.4 MySQL AB Logos and Trademarks.
1.4.3 MySQL Licenses
The MySQL software is released under the GNU General Public License (GPL), which is probably the best known Open Source license. The formal terms of the GPL license can be found at http://www.fsf.org/licenses/. See also http://www.fsf.org/licenses/gpl-faq.html and http://www.gnu.org/philosophy/enforcing-gpl.html.
Our GPL licensing is supported by an optional license exception that enables many Free/Libre and Open Source Software (``FLOSS'') applications to include the GPL-licensed MySQL client libraries despite the fact that not all FLOSS licenses are compatible with the GPL. For details, see http://www.mysql.com/products/licensing/foss-exception.html.
Because the MySQL software is released under the GPL, it may often be used for free, but for certain uses you may want or need to buy commercial licenses from MySQL AB at https://order.mysql.com/. See http://www.mysql.com/products/licensing/ for more information.
Older versions of MySQL (3.22 and earlier) are subject to a stricter license (http://www.mysql.com/products/licensing/mypl.html). See the documentation of the specific version for information.
Please note that the use of the MySQL software under commercial license, GPL, or the old MySQL license does not automatically give you the right to use MySQL AB (registered) trademarks. See section 1.4.4 MySQL AB Logos and Trademarks.
1.4.3.1 Using the MySQL Software Under a Commercial License
The GPL license is contagious in the sense that when a program is linked to a GPL program, all the source code for all the parts of the resulting product must also be released under the GPL. If you do not follow this GPL requirement, you break the license terms and forfeit your right to use the GPL program altogether. You also risk damages.
You need a commercial license under these conditions:
- When you link a program with any GPL code from the MySQL software and don't want the resulting product to be licensed under GPL, perhaps because you want to build a commercial product or keep the added non-GPL code closed source for other reasons. When purchasing commercial licenses, you are not using the MySQL software under GPL even though it's the same code.
- When you distribute a non-GPL application that works only with the MySQL software and ship it with the MySQL software. This type of solution is considered to be linking even if it's done over a network.
- When you distribute copies of the MySQL software without providing the source code as required under the GPL license.
- When you want to support the further development of the MySQL database even if you don't formally need a commercial license. Purchasing support directly from MySQL AB is another good way of contributing to the development of the MySQL software, with immediate advantages for you. See section 1.4.1 Support Offered by MySQL AB.
Our GPL licensing is supported by an optional license exception that enables many Free/Libre and Open Source Software (``FLOSS'') applications to include the GPL-licensed MySQL client libraries despite the fact that not all FLOSS licenses are compatible with the GPL. For details, see http://www.mysql.com/products/licensing/foss-exception.html.
If you require a commercial license, you will need one for each installation of the MySQL software. This covers any number of CPUs on a machine, and there is no artificial limit on the number of clients that connect to the server in any way.
For commercial licenses, please visit our Web site at http://www.mysql.com/products/licensing/. For support contracts, see http://www.mysql.com/support/. If you have special needs, please contact our sales staff via email at [email protected].
1.4.3.2 Using the MySQL Software for Free Under GPL
You can use the MySQL software for free under the GPL if you adhere to the conditions of the GPL. For additional details about the GPL, including answers to common questions, see the generic FAQ from the Free Software Foundation at http://www.fsf.org/licenses/gpl-faq.html.
Our GPL licensing is supported by an optional license exception that enables many Free/Libre and Open Source Software (``FLOSS'') applications to include the GPL-licensed MySQL client libraries despite the fact that not all FLOSS licenses are compatible with the GPL. For details, see http://www.mysql.com/products/licensing/foss-exception.html.
Common uses of the GPL include:
- When you distribute both your own application and the MySQL source code under the GPL with your product.
- When you distribute the MySQL source code bundled with other programs that are not linked to or dependent on the MySQL system for their functionality even if you sell the distribution commercially. This is called ``mere aggregation'' in the GPL license.
- When you are not distributing any part of the MySQL system, you can use it for free.
- When you are an Internet Service Provider (ISP), offering Web hosting with MySQL servers for your customers. We encourage people to use ISPs that have MySQL support, because doing so will give them the confidence that their ISP will, in fact, have the resources to solve any problems they may experience with the MySQL installation. Even if an ISP does not have a commercial license for MySQL Server, their customers should at least be given read access to the source of the MySQL installation so that the customers can verify that it is correctly patched.
- When you use the MySQL database software in conjunction with a Web server, you do not need a commercial license (so long as it is not a product you distribute). This is true even if you run a commercial Web server that uses MySQL Server, because you are not distributing any part of the MySQL system. However, in this case we would like you to purchase MySQL support because the MySQL software is helping your enterprise.
If your use of MySQL database software does not require a commercial license, we encourage you to purchase support from MySQL AB anyway. This way you contribute toward MySQL development and also gain immediate advantages for yourself. See section 1.4.1 Support Offered by MySQL AB.
If you use the MySQL database software in a commercial context such that you profit by its use, we ask that you further the development of the MySQL software by purchasing some level of support. We feel that if the MySQL database helps your business, it is reasonable to ask that you help MySQL AB. (Otherwise, if you ask us support questions, you are not only using for free something into which we've put a lot a work, you're asking us to provide free support, too.)
1.4.4 MySQL AB Logos and Trademarks
Many users of the MySQL database want to display the MySQL AB dolphin logo on their Web sites, books, or boxed products. We welcome and encourage this, although it should be noted that the word MySQL and the MySQL dolphin logo are (registered) trademarks of MySQL AB and may only be used as stated in our trademark policy at http://www.mysql.com/company/trademark.html.
1.4.4.1 The Original MySQL Logo
The MySQL dolphin logo was designed by the Finnish advertising agency Priority in 2001. The dolphin was chosen as a suitable symbol for the MySQL database management system, which is like a smart, fast, and lean animal, effortlessly navigating oceans of data. We also happen to like dolphins.
The original MySQL logo may only be used by representatives of MySQL AB and by those having a written agreement allowing them to do so.
1.4.4.2 MySQL Logos That May Be Used Without Written Permission
We have designed a set of special Conditional Use logos that may be downloaded from our Web site at http://www.mysql.com/press/logos.html and used on third-party Web sites without written permission from MySQL AB. The use of these logos is not entirely unrestricted but, as the name implies, subject to our trademark policy that is also available on our Web site. You should read through the trademark policy if you plan to use them. The requirements are basically as follows:
- Use the logo you need as displayed on the http://www.mysql.com/ site. You may scale it to fit your needs, but may not change colors or design, or alter the graphics in any way.
- Make it evident that you, and not MySQL AB, are the creator and owner of the site that displays the MySQL (registered) trademark.
- Don't use the trademark in a way that is detrimental to MySQL AB or to the value of MySQL AB trademarks. We reserve the right to revoke the right to use the MySQL AB trademark.
- If you use the trademark on a Web site, make it clickable, leading directly to http://www.mysql.com/.
- If you use the MySQL database under GPL in an application, your application must be Open Source and must be able to connect to a MySQL server.
Contact us via email at [email protected] to inquire about special arrangements to fit your needs.
1.4.4.3 When You Need Written Permission to Use MySQL Logos
You need written permission from MySQL AB before using MySQL logos in the following cases:
- When displaying any MySQL AB logo anywhere except on your Web site.
- When displaying any MySQL AB logo except the Conditional Use logos (mentioned previously) on Web sites or elsewhere.
Due to legal and commercial reasons, we monitor the use of MySQL (registered) trademarks on products, books, and other items. We usually require a fee for displaying MySQL AB logos on commercial products, since we think it is reasonable that some of the revenue is returned to fund further development of the MySQL database.
1.4.4.4 MySQL AB Partnership Logos
MySQL partnership logos may be used only by companies and persons having a written partnership agreement with MySQL AB. Partnerships include certification as a MySQL trainer or consultant. For more information, please see section 1.3.1.5 Partnering.
1.4.4.5 Using the Word MySQL in Printed Text or Presentations
MySQL AB welcomes references to the MySQL database, but it should be
noted that the word MySQL is a registered trademark of MySQL AB.
Because of this, you must append the ``registered trademark'' notice
symbol (R
) to
the first or most prominent use of the word MySQL in a text and,
where appropriate, state that MySQL is a registered trademark of
MySQL AB. For more information, please refer to our trademark policy at
http://www.mysql.com/company/trademark.html.
1.4.4.6 Using the Word MySQL in Company and Product Names
Use of the word MySQL in company or product names or in Internet domain names is not allowed without written permission from MySQL AB. http://www.mysql.com/company/contact/.
1.5 MySQL Development Roadmap
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 production release series is MySQL 4.0, which was declared stable for production use as of Version 4.0.12, released in March 2003. This means that future 4.0 development is limited only to bugfixes. For the older MySQL 3.23 series, only critical bugfixes are made.
4.1 is available in gamma status and will soon move to production stage.
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.5 Upgrading/Downgrading 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 (already implemented in 3.23 for InnoDB )
|
Triggers | 5.0 and 5.1 |
Full outer join | 5.1 |
Constraints | 5.1 |
1.5.1 MySQL 4.0 in a Nutshell
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.
1.5.1.1 Features Available in MySQL 4.0
- Speed enhancements
-
- MySQL 4.0 has a query cache that can give a huge speed boost to applications with repetitive queries. See section 5.11 The MySQL Query Cache.
-
Version 4.0 further increases the speed of MySQL Server
in a number of areas, such as bulk
INSERT
statements, searching on packed indexes, full-text searching (usingFULLTEXT
indexes), andCOUNT(DISTINCT)
.
- Embedded MySQL Server introduced
-
- The new Embedded Server library can easily be used to create standalone and embedded applications. The embedded server provides an alternative to using MySQL in a client/server environment. See section 1.5.1.2 The Embedded MySQL Server.
InnoDB
storage engine as standard-
-
The
InnoDB
storage engine is offered as a standard feature of the MySQL server. This means full support for ACID transactions, foreign keys with cascadingUPDATE
andDELETE
, and row-level locking are now standard features. See section 16 TheInnoDB
Storage Engine.
-
The
- New functionality
-
-
The enhanced
FULLTEXT
search properties of MySQL Server 4.0 enablesFULLTEXT
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 13.6 Full-Text Search Functions.
-
The enhanced
- Standards compliance, portability, and migration
-
-
Many users will also be happy to learn that MySQL Server now supports the
UNION
statement, a long-awaited standard SQL feature. - MySQL runs natively on the Novell NetWare platform beginning with NetWare 6.0. See section 2.2.4 Installing MySQL on NetWare.
-
Features to simplify migration from other database systems to MySQL
Server include
TRUNCATE TABLE
(as in Oracle).
-
Many users will also be happy to learn that MySQL Server now supports the
- Internationalization
-
-
Our German, Austrian, and Swiss users will note that MySQL 4.0 now
supports a new character set,
latin1_de
, which ensures that the German sorting order sorts words with umlauts in the same order as do German telephone books.
-
Our German, Austrian, and Swiss users will note that MySQL 4.0 now
supports a new character set,
- Usability enhancements
-
In the process of implementing features for new users, we have not forgotten
requests from our loyal community of existing users.
-
Most @command{mysqld} parameters (startup options) can be set without taking
down the server. This is a convenient feature for database administrators
(DBAs).
See section 14.5.3.1
SET
Syntax. -
Multiple-table
DELETE
andUPDATE
statements have been added. -
On Windows, symbolic link handling at the database level is enabled by default.
On Unix, the
MyISAM
storage engine supports symbolic linking at the table level (and not just the database level as before). -
SQL_CALC_FOUND_ROWS
andFOUND_ROWS()
are new functions that make it possible to find out the number of rows aSELECT
query that includes aLIMIT
clause would have returned without that clause.
-
Most @command{mysqld} parameters (startup options) can be set without taking
down the server. This is a convenient feature for database administrators
(DBAs).
See section 14.5.3.1
The news section of this manual includes a more in-depth list of features. See section C.3 Changes in release 4.0.x (Production).
1.5.1.2 The Embedded MySQL Server
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
will 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.
The embedded MySQL library uses the same interface as the normal
client library, so it is convenient and easy to use.
See section 21.2.15 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. |
1.5.2 MySQL 4.1 in a Nutshell
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. Already well-known for its stability, speed, and ease of use, MySQL Server is now able to fulfill the requirement checklists of very demanding buyers.
MySQL 4.1 is now available in gamma status, and will be production soon.
1.5.2.1 Features Available in MySQL 4.1
This section lists features implemented in MySQL 4.1.
New features currently being coded are or will be available in MySQL 5.0. See section 1.6.1 New Features Planned for 5.0.
- Support for subqueries and derived tables
-
-
A ``subquery'' is a
SELECT
statement nested within another statement. A ``derived table'' (an unnamed view) is a subquery in theFROM
clause of another statement. See section 14.1.8 Subquery Syntax.
-
A ``subquery'' is a
- Speed enhancements
-
- Faster binary client/server protocol with support for prepared statements and parameter binding. See section 21.2.4 C API Prepared Statements.
-
BTREE
indexing is supported forHEAP
tables, significantly improving response time for non-exact searches.
- New functionality
-
-
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. -
The
MyISAM
storage engine supports OpenGIS spatial types for storing geographical data. See section 19 Spatial Extensions in MySQL. - Replication can be done over SSL connections.
-
- Standards compliance, portability, and migration
-
- The new client/server protocol adds the ability to pass multiple warnings to the client, rather than only a single result. This makes it much easier to track problems that occur in operations such as bulk data loading.
-
SHOW WARNINGS
shows warnings for the last command. See section 14.5.3.21SHOW WARNINGS
Syntax.
- Internationalization and Localization
-
-
To support applications that require the use of local languages,
the MySQL software offers extensive
Unicode support through the
utf8
anducs2
character sets. - Character sets can be defined per column, table, and database. This allows for a high degree of flexibility in application design, particularly for multi-language Web sites.
- For documentation for this improved character set support, see section 11 Character Set Support.
- Per-connection time zones are supported, allowing individual clients to select their own time zone when necessary.
-
To support applications that require the use of local languages,
the MySQL software offers extensive
Unicode support through the
- Usability enhancements
-
-
In response to popular demand, we have added a server-based
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, thehelp
command of the @command{mysql} command-line client has been modified to have this capability. - In the new client/server protocol, multiple statements can be issued with a single call. See section 21.2.8 C API Handling of Multiple Query Execution.
- The new client/server protocol also supports returning multiple result sets. This might occur as a result of sending multiple statements, for example.
-
A new
INSERT ... ON DUPLICATE KEY UPDATE ...
syntax has been implemented. This allows you toUPDATE
an existing row if theINSERT
would have caused a duplicate in aPRIMARY
orUNIQUE
index. See section 14.1.4INSERT
Syntax. -
A new aggregate function,
GROUP_CONCAT()
adds the extremely useful capability of concatenating column values from grouped rows into a single result string. See section 13.9 Functions and Modifiers for Use withGROUP BY
Clauses.
-
In response to popular demand, we have added a server-based
The news section of this manual includes a more in-depth list of features. See section C.2 Changes in release 4.1.x (Gamma).
1.5.2.2 Stepwise Rollout
The gamma version of MySQL 4.1 is available for download. See section 1.5.2.3 Ready for Immediate Development Use.
MySQL 4.1 is currently in the Gamma stage (indicating that a production release is just weeks ahead). At the end of this process, MySQL 4.1 will become the new production release.
Development is already ongoing for version 5.0.
1.5.2.3 Ready for Immediate Development Use
MySQL 4.1 is currently in the gamma stage, 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 C.2 Changes in release 4.1.x (Gamma).
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.3.3 Installing from the Development Source Tree.
1.5.3 MySQL 5.0: The Next Development Release
New development for MySQL is focused on the 5.0 release, featuring stored procedures, updatable views, rudimentary triggers, and other new features. See section 1.6.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.3.3 Installing from the Development Source Tree. As of December 2003, binary builds of version 5.0 have also been available.
1.6 MySQL and the Future (the TODO)
This section summarizes the features that we plan to implement in MySQL Server. The items are ordered by release series. Within a list, items are shown in approximately the order they will be done.
Note: If you are an enterprise-level user with an urgent need for a particular feature, please contact [email protected] to discuss sponsoring options. Targeted financing by sponsor companies allows us to allocate additional resources for specific purposes. One example of a feature sponsored in the past is replication.
1.6.1 New Features Planned for 5.0
The following features are planned for inclusion into MySQL 5.0. Some of the features such as stored procedures are complete and are included in MySQL 5.0 alpha, which is available now. Others such as cursors are only partially available. Expect these and other features to mature and be fully supported in upcoming releases.
Note that because we have many developers that are working on different projects, there will also be many additional features. There is also a small chance that some of these features will be added to MySQL 4.1. For a list what is already done in MySQL 4.1, see section 1.5.2.1 Features Available in MySQL 4.1.
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.3.3 Installing from the Development Source Tree. As of December 2003, binary builds of version 5.0 are also available.
- Views
-
-
Views, implemented in stepwise fashion up to full functionality.
See section 1.8.5.6 Views. See section 14.2.7
CREATE VIEW
Syntax.
-
Views, implemented in stepwise fashion up to full functionality.
See section 1.8.5.6 Views. See section 14.2.7
- Stored Procedures
-
- Stored procedures currently are implemented, based on the SQL:2003 standard. See section 20 Stored Procedures and Functions.
- New functionality
-
- Elementary cursor support. See section 20.1.8 Cursors.
-
The ability to specify explicitly for
MyISAM
tables that an index should be created as anRTREE
index. (In MySQL 4.1,RTREE
indexes are used internally for geometrical data that use GIS data types, but cannot be created on request.) -
Dynamic length rows for
MEMORY
tables.
- Standards compliance, portability and migration
-
-
Support for Data Dictionary /
INFORMATION_SCHEMA
. -
Add true
VARCHAR
support (column lengths longer than 255, and no stripping of trailing whitespace). There is already support for this in theMyISAM
storage engine, but it is not yet available at the user level.
-
Support for Data Dictionary /
- Speed enhancements
-
-
SHOW COLUMNS FROM tbl_name
(used by the @command{mysql} client to allow expansions of column names) should not open the table, only the definition file. This will require less memory and be much faster. -
Allow
DELETE
onMyISAM
tables to use the record cache. To do this, we need to update the threads record cache when we update the `.MYD' file. -
Better support for
MEMORY
tables:- Dynamic length rows.
- Faster row handling (less copying).
-
- Usability enhancements
-
-
Resolving the issue of
RENAME TABLE
on a table used in an activeMERGE
table possibly corrupting the table.
-
Resolving the issue of
The news section of this manual includes a more in-depth list of features. See section C.1 Changes in release 5.0.x (Development).
1.6.2 New Features Planned for 5.1
- New functionality
-
-
FOREIGN KEY
support for all table types, not justInnoDB
. - Column-level constraints. See section 1.8.6 How MySQL Deals with Constraints.
- Online backup with very low performance penalty. The online backup will make it easy to add a new replication slave without taking down the master.
-
- Speed enhancements
-
- New text based table definition file format (`.frm' files) and a table cache for table definitions. This will enable us to do faster queries of table structures and do more efficient foreign key support.
-
Optimize the
BIT
type to take one bit. (BIT
now takes one byte; it is treated as a synonym forTINYINT
.)
- Usability enhancements
-
- Add options to the client/server protocol to get progress notes for long running commands.
-
Implement
RENAME DATABASE
. To make this safe for all storage engines, it should work as follows:- Create the new database.
-
For every table, do a rename of the table to another database, as
we do with the
RENAME
command. - Drop the old database.
- New internal file interface change. This will make all file handling much more general and make it easier to add extensions like RAID.
1.6.3 New Features Planned for the Near Future
- New functionality
-
-
Oracle-like
CONNECT BY PRIOR
to search tree-like (hierarchical) structures. - Add all missing standard SQL and ODBC 3.0 types.
-
Add
SUM(DISTINCT)
. -
INSERT SQL_CONCURRENT
and @command{mysqld --concurrent-insert} to do a concurrent insert at the end of a table if the table is read-locked. -
Allow variables to be updated in
UPDATE
statements. For example:UPDATE foo SET @a:=a+b,[email protected], [email protected]+c
. -
Change when user variables are updated so that you can use them with
GROUP BY
, as in the following statement:SELECT id, @a:=COUNT(*), SUM(sum_col)/@a FROM tbl_name GROUP BY id
. -
Add an
IMAGE
option toLOAD DATA INFILE
to not updateTIMESTAMP
andAUTO_INCREMENT
columns. -
Add
LOAD DATA INFILE ... UPDATE
syntax that works like this:- For tables with primary keys, if an input record contains a primary key value, existing rows matching that primary key value are updated from the remainder of the input columns. However, columns corresponding to columns that are missing from the input record are not touched.
-
For tables with primary keys, if an input record does not contain the primary
key value or is missing some part of the key, the record is treated as
LOAD DATA INFILE ... REPLACE INTO
.
-
Make
LOAD DATA INFILE
understand syntax like this:LOAD DATA INFILE 'file_name.txt' INTO TABLE tbl_name TEXT_FIELDS (text_col1, text_col2, text_col3) SET table_col1=CONCAT(text_col1, text_col2), table_col3=23 IGNORE text_col3
This can be used to skip over extra columns in the text file, or update columns based on expressions of the read data. -
New functions for working with
SET
type columns:ADD_TO_SET(value,set)
REMOVE_FROM_SET(value,set)
- If you abort @command{mysql} in the middle of a query, you should open another connection and kill the old running query. Alternatively, an attempt should be made to detect this in the server.
-
Add a storage engine interface for table information so that you can use it as a system
table. This would be a bit slow if you requested information about all tables,
but very flexible.
SHOW INFO FROM tbl_name
for basic table information should be implemented. -
Allow
SELECT a FROM tbl_name1 LEFT JOIN tbl_name2 USING (a)
; in this casea
is assumed to come from tbl_name1. -
DELETE
andREPLACE
options to theUPDATE
statement (this will delete rows when a duplicate-key error occurs while updating). -
Change the format of
DATETIME
to store fractions of seconds. -
Make it possible to use the new GNU
regexp
library instead of the current one (the new library should be much faster than the current one).
-
Oracle-like
- Standards compliance, portability and migration
-
-
Add
ANY()
,EVERY()
, andSOME()
group functions. In standard SQL, these work only on boolean columns, but we can extend these to work on any columns or expressions by treating a value of zero as FALSE and non-zero values as TRUE. -
Fix the type of
MAX(column)
to be the same as the column type:mysql> CREATE TABLE t1 (a DATE); mysql> INSERT INTO t1 VALUES (NOW()); mysql> CREATE TABLE t2 SELECT MAX(a) FROM t1; mysql> SHOW COLUMNS FROM t2;
-
Add
- Speed enhancements
-
-
Don't allow more than a defined number of threads to run
MyISAM
recovery at the same time. -
Change
INSERT INTO ... SELECT
to optionally use concurrent inserts. - Add an option to periodically flush key pages for tables with delayed keys if they haven't been used in a while.
- Allow join on key parts (optimization issue).
- Add a log file analyzer that can extract information about which tables are hit most often, how often multiple-table joins are executed, and so on. This should help users identify areas of table design that could be optimized to execute much more efficient queries.
-
Don't allow more than a defined number of threads to run
- Usability enhancements
-
-
Return the original column types when doing
SELECT MIN(column) ... GROUP BY
. -
Make it possible to specify
long_query_time
with a granularity in microseconds. -
Link the @command{myisampack} code into the server so that it can perform
PACK
orCOMPRESS
operations. -
Add a temporary key buffer cache during
INSERT/DELETE/UPDATE
so that we can gracefully recover if the index file gets full. -
If you perform an
ALTER TABLE
on a table that is symlinked to another disk, create temporary tables on that disk. -
Implement a
DATE/DATETIME
type that handles time zone information properly, to make dealing with dates in different time zones easier. -
Fix @command{configure} so that all libraries (like
MyISAM
) can be compiled without threads. -
Allow user variables as
LIMIT
arguments; for example,LIMIT @a,@b
. - Automatic output from @command{mysql} to a Web browser.
-
LOCK DATABASES
(with various options). -
Many more variables for
SHOW STATUS
. Record reads and updates. Selects on a single table and selects with joins. Mean number of tables in selects. Number ofORDER BY
andGROUP BY
queries. -
@command{mysqladmin copy database new-database}; this requires a
COPY
operation to be added to @command{mysqld}. - Processlist output should indicate the number of queries/threads.
-
SHOW HOSTS
for printing information about the hostname cache. -
Change table names from empty strings to
NULL
for calculated columns. -
Don't use
Item_copy_string
on numerical values to avoid number-to-string-to-number conversion in case ofSELECT COUNT(*)*(id+0) FROM tbl_name GROUP BY id
. -
Change so that
ALTER TABLE
doesn't abort clients that executeINSERT DELAYED
. -
Fix so that when columns are referenced in an
UPDATE
clause, they contain the old values from before the update started.
-
Return the original column types when doing
- New operating systems
-
- Port the MySQL clients to LynxOS.
1.6.4 New Features Planned for the Mid-Term Future
-
Implement function:
get_changed_tables(timeout,table1,table2,...)
. -
Change reading through tables to use
mmap()
when possible. Now only compressed tables usemmap()
. -
Make the automatic timestamp code nicer. Add timestamps to the update
log with
SET TIMESTAMP=val;
. - Use read/write mutex in some places to get more speed.
- Automatically close some tables if a table, temporary table, or temporary file gets error 23 (too many open files).
-
Better constant propagation. When an occurrence of col_name=n
is found in an expression, for some constant
n
, replace other occurrences of col_name within the expression withn
. Currently, this is done only for some simple cases. - Change all const expressions with calculated expressions if possible.
- Optimize key = expr comparisons. At the moment, only key = column or key = constant comparisons are optimized.
- Join some of the copy functions for nicer code.
- Change `sql_yacc.yy' to an inline parser to reduce its size and get better error messages.
- Change the parser to use only one rule per different number of arguments in function.
- Use of full calculation names in the order part (for Access97).
-
MINUS
,INTERSECT
, andFULL OUTER JOIN
. (CurrentlyUNION
andLEFT|RIGHT OUTER JOIN
are supported.) -
Allow
SQL_OPTION MAX_SELECT_TIME=val
, for placing a time limit on a query. - Allow updates to be logged to a database.
-
Enhance
LIMIT
to allow retrieval of data from the end of a result set. - Alarm around client connect/read/write functions.
- Please note the changes to @command{mysqld_safe}: According to FSSTND (which Debian tries to follow), PID files should go into `/var/run/<progname>.pid' and log files into `/var/log'. It would be nice if you could put the "DATADIR" in the first declaration of "pidfile" and "log" so that the placement of these files can be changed with a single statement.
- Allow a client to request logging.
-
Allow the
LOAD DATA INFILE
statement to read files that have been compressed with @command{gzip}. -
Fix sorting and grouping of
BLOB
columns (partly solved now). - Change to use semaphores when counting threads. One should first implement a semaphore library for MIT-pthreads.
-
Add full support for
JOIN
with parentheses. - As an alternative to the one-thread-per-connection model, manage a pool of threads to handle queries.
-
Allow
GET_LOCK()
to obtain more than one lock. When doing this, it is also necessary to handle the possible deadlocks this change will introduce.
1.6.5 New Features We Don't Plan to Implement
We aim toward full compliance with ANSI/ISO SQL. There are no features we plan not to implement.
1.7 MySQL Information Sources
1.7.1 MySQL Mailing Lists
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 will receive all postings to the list as email messages. You can also send your own questions and answers to the list.
1.7.1.1 The MySQL Mailing Lists
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
- This list is for announcements of new versions of MySQL and related programs. This is a low-volume list to which all MySQL users should subscribe.
mysql
- This is the main list for general MySQL discussion. Please note that some topics are better discussed on the more-specialized lists. If you post to the wrong list, you may not get an answer.
bugs
- This list will be of interest to you if you want to stay informed about issues reported since the last release of MySQL or if you want to be actively involved in the process of bug hunting and fixing. See section 1.7.1.3 How to Report Bugs or Problems.
internals
- This list is for people who work on the MySQL code. This is also the forum for discussions on MySQL development and for posting patches.
mysqldoc
- This list is for people who work on the MySQL documentation: people from MySQL AB, translators, and other community members.
benchmarks
- This list is for anyone interested in performance issues. Discussions concentrate on database performance (not limited to MySQL), but also include broader categories such as performance of the kernel, filesystem, disk system, and so on.
packagers
- This list is for discussions on packaging and distributing MySQL. This is the forum used by distribution maintainers to exchange ideas on packaging MySQL and on ensuring that MySQL looks and feels as similar as possible on all supported platforms and operating systems.
java
- This list is for discussions about the MySQL server and Java. It is mostly used to discuss JDBC drivers, including MySQL Connector/J.
win32
- This list is for all topics concerning the MySQL software on Microsoft operating systems, such as Windows 9x, Me, NT, 2000, and XP.
myodbc
- This list is for all topics concerning connecting to the MySQL server with ODBC.
gui-tools
-
This list is for all topics concerning MySQL GUI tools, including
MySQL Administrator
and theMySQL Control Center
graphical client. cluster
- This list is for discussion of MySQL Cluster.
dotnet
- This list is for discussion of the MySQL server and the .NET platform. Mostly related to the MySQL Connector/Net provider.
plusplus
- This list is for all topics concerning programming with the C++ API for MySQL.
perl
-
This list is for all topics concerning the Perl support for MySQL with
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 will put you in direct contact with MySQL developers. See section 1.4.1 Support Offered by MySQL AB.
The following table shows some MySQL mailing lists in languages other than English. These lists are not operated by MySQL AB.
[email protected]
- A French mailing list.
[email protected]
-
A Korean mailing list.
Email
subscribe mysql [email protected]
to this list. [email protected]
-
A German mailing list.
Email
subscribe mysql-de [email protected]
to this list. You can find information about this mailing list at http://www.4t2.com/mysql/. [email protected]
-
A Portuguese mailing list.
Email
subscribe mysql-br [email protected]
to this list. [email protected]
-
A Spanish mailing list.
Email
subscribe mysql [email protected]
to this list.
1.7.1.2 Asking Questions or Reporting Bugs
Before posting a bug report or question, please do the following:
- Start by searching the MySQL online manual at http://dev.mysql.com/doc/. We try to keep the manual up to date by updating it frequently with solutions to newly found problems. The change history (http://dev.mysql.com/doc/mysql/en/News.html) can be particularly useful since it is quite possible that a newer version already contains a solution to your problem.
- Search in the bugs database at http://bugs.mysql.com/ to see whether the bug has already been reported and fixed.
- Search the MySQL mailing list archives at http://lists.mysql.com/.
- You can also use http://www.mysql.com/search/ to search all the Web pages (including the manual) that are located at the MySQL AB Web site.
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.
1.7.1.3 How to Report Bugs or Problems
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 will also be able to 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 will help 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 @command{mysqlbug} script to generate a bug report (or a report about any problem). @command{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 @command{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 @command{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/ will be 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 [email protected].
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 @command{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 already 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 D.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 22.1.1.9 How to Report MyODBC Problems or Bugs.
Please remember that many of the people who will read your report will
do so using an 80-column display. When generating reports or examples
using the @command{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:
- The version number of the MySQL distribution you are using (for example, MySQL 4.0.12). You can find out which version you are running by executing @command{mysqladmin version}. The @command{mysqladmin} program can be found in the `bin' directory under your MySQL installation directory.
- The manufacturer and model of the machine on which you experience the problem.
-
The operating system name and version. If you work with Windows, you
can usually get the name and version number by double-clicking your
My Computer icon and pulling down the ``Help/About Windows'' menu.
For most Unix-like operating systems, you can get this information by
executing the command
uname -a
. - Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include these values.
- If you are using a source distribution of the MySQL software, the name and version number of the compiler used are needed. If you have a binary distribution, the distribution name is needed.
- If the problem occurs during compilation, include the exact error messages and also a few lines of context around the offending code in the file where the error occurs.
- If @command{mysqld} died, you should also report the query that crashed @command{mysqld}. You can usually find this out by running @command{mysqld} with query logging enabled, and then looking in the log after @command{mysqld} crashes See section D.1.5 Using Log Files to Find Cause of Errors in @command{mysqld}.
- If a database table is related to the problem, include the output from @command{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 will help us create a situation matching the one you have.
-
For speed-related bugs or problems with
SELECT
statements, you should always include the output ofEXPLAIN SELECT ...
, and at least the number of rows that theSELECT
statement produces. You should also include the output fromSHOW 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 @command{mysqlbug} script. The example uses the @command{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>
- If a bug or problem occurs while running @command{mysqld}, try to provide an input script that will reproduce 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 @command{mysqladmin variables extended-status processlist} in your mail to provide some information on how your system is performing.
- If you can't produce a test case with only a few rows, or if the test table is too big to be mailed to the mailing list (more than 10 rows), you should dump your tables using @command{mysqldump} and create a `README' file that describes your problem. Create a compressed archive of your files using @command{tar} and @command{gzip} or @command{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/.
- If you think that the MySQL server produces a strange result from a query, include not only the result, but also your opinion of what the result should be, and an account describing the basis for your opinion.
- When giving an example of the problem, it's better to use the variable names, table names, and so on that exist in your actual situation than to come up with new names. The problem could be related to the name of a variable or table. These cases are rare, perhaps, but it is better to be safe than sorry. After all, it should be easier for you to provide an example that uses your actual situation, and it is by all means better for us. In case you have data that you don't want to show to others, you can use FTP to transfer it to ftp://ftp.mysql.com/pub/mysql/upload/. If the information is really top secret and you don't want to show it even to us, then go ahead and provide an example using other names, but please regard this as the last choice.
- Include all the options given to the relevant programs, if possible. For example, indicate the options that you use when you start the @command{mysqld} server as well as the options that you use to run any MySQL client programs. The options to programs such as @command{mysqld} and @command{mysql}, and to the @command{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.
- If your question is related to the privilege system, please include the output of @command{mysqlaccess}, the output of @command{mysqladmin reload}, and all the error messages you get when trying to connect. When you test your privileges, you should first run @command{mysqlaccess}. After this, execute @command{mysqladmin reload version} and try to connect with the program that gives you trouble. @command{mysqlaccess} can be found in the `bin' directory under your MySQL installation directory.
- If you have a patch for a bug, do include it. But don't assume that the patch is all we need, or that we will use it, if you don't provide some necessary information such as test cases showing the bug that your patch fixes. We might find problems with your patch or we might not understand it at all; if so, we can't use it. If we can't verify exactly what the purpose of the patch is, we won't use it. Test cases will help us here. Show that the patch will handle all the situations that may occur. If we find a borderline case (even a rare one) where the patch won't work, it may be useless.
- Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the MySQL team can't guess such things without first using a debugger to determine the real cause of a bug.
- Indicate in your bug report that you have checked the reference manual and mail archive so that others know you have tried to solve the problem yourself.
-
If you get a
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 [email protected] 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 C MySQL Change History. -
If your problem is that your data appears corrupt or you get errors
when you access a particular table, you should first check and then try
to repair your tables with
CHECK TABLE
andREPAIR TABLE
or with @command{myisamchk}. See section 5 Database Administration. If you are running Windows, please verify thatlower_case_table_names
is 1 or 2 withSHOW VARIABLES LIKE 'lower_case_table_names'
. - If you often get corrupted tables, you should try to find out when and why this happens. In this case, the error log in the MySQL data directory may contain some information about what happened. (This is the file with the `.err' suffix in the name.) See section 5.9.1 The Error Log. Please include any relevant information from this file in your bug report. Normally @command{mysqld} should never crash a table if nothing killed it in the middle of an update. If you can find the cause of @command{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 possible, download and install the most recent version of MySQL Server and check whether it solves your problem. All versions of the MySQL software are thoroughly tested and should work without problems. We believe in making everything as backward-compatible as possible, and you should be able to switch MySQL versions without difficulty. See section 2.1.2 Choosing Which MySQL Distribution to Install.
If you are a support customer, please cross-post the bug report to [email protected] 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 22.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.
1.7.1.4 Guidelines for Answering Questions on the Mailing List
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.
1.7.2 MySQL Community Support on IRC (Internet Relay Chat)
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:
- freenode (see http://www.freenode.net/ for servers)
#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.
- EFnet (see http://www.efnet.org/ for servers)
#mysql
MySQL questions.
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.
1.8 MySQL Standards Compliance
This section describes how MySQL relates to the ANSI/ISO SQL standards. MySQL Server has many extensions to the SQL standard, and here you will find out what they are and how to use them. You will 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 14.1.3 HANDLER
Syntax.
We will 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 already offer significant functionality.
Database cluster support now exists through third-party clustering solutions as well as the integration of our acquired NDB Cluster technology into a new storage engine, available from version 4.1.2. See section 17 MySQL Cluster.
We are also looking at providing XML support in the database server.
1.8.1 What Standards MySQL Follows
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.
1.8.2 Selecting SQL Modes
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 @command{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.
1.8.3 Running MySQL in ANSI Mode
You can tell @command{mysqld} to use the ANSI mode with the --ansi
startup option. See section 5.2.1 @command{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,ONLY_FULL_GROUP_BY
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,ONLY_FULL_GROUP_BY';
See section 1.8.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 will be 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,ONLY_FULL_GROUP_BY,ANSI';
1.8.4 MySQL Extensions to Standard SQL
MySQL Server includes some extensions that you probably will not find in
other SQL databases. Be warned that if you use them, your code will not 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 will parse 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 will be 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 will use the TEMPORARY
keyword.
The following descriptions list MySQL extensions, organized by category.
- Organization of data on disk
-
MySQL Server maps each database to a directory under the MySQL
data directory, and tables within a database to filenames in the database
directory.
This has a few implications:
- Database names and table names are case sensitive in MySQL Server on operating systems that have case-sensitive filenames (such as most Unix systems). See section 10.2.2 Identifier Case Sensitivity.
-
You can use standard system commands to back up, rename, move, delete, and copy
tables that are managed by the
MyISAM
orISAM
storage engines. For example, to rename aMyISAM
table, rename the `.MYD', `.MYI', and `.frm' files to which the table corresponds.
- General language syntax
-
- Strings may be enclosed by either `"' or `'', not just by `''.
- Use of `\' as an escape character in strings.
-
In SQL statements, you can access tables from different databases
with the db_name.tbl_name syntax. Some SQL servers provide
the same functionality but call this
User space
. MySQL Server doesn't support tablespaces such as used in statements like this:CREATE TABLE ralph.my_table...IN my_tablespace
.
- SQL statement syntax
-
-
The
ANALYZE TABLE
,CHECK TABLE
,OPTIMIZE TABLE
, andREPAIR TABLE
statements. -
The
CREATE DATABASE
andDROP DATABASE
statements. See section 14.2.4CREATE DATABASE
Syntax. -
The
DO
statement. -
EXPLAIN SELECT
to get a description of how tables are joined. -
The
FLUSH
andRESET
statements. -
The
SET
statement. See section 14.5.3.1SET
Syntax. -
The
SHOW
statement. See section 14.5.3SET
andSHOW
Syntax. -
Use of
LOAD DATA INFILE
. In many cases, this syntax is compatible with Oracle'sLOAD DATA INFILE
. See section 14.1.5LOAD DATA INFILE
Syntax. -
Use of
RENAME TABLE
. See section 14.2.12RENAME TABLE
Syntax. -
Use of
REPLACE
instead ofDELETE
+INSERT
. See section 14.1.6REPLACE
Syntax. -
Use of
CHANGE col_name
,DROP col_name
, orDROP INDEX
,IGNORE
orRENAME
in anALTER TABLE
statement. Use of multipleADD
,ALTER
,DROP
, orCHANGE
clauses in anALTER TABLE
statement. See section 14.2.2ALTER TABLE
Syntax. -
Use of index names, indexes on a prefix of a field, and use of
INDEX
orKEY
in aCREATE TABLE
statement. See section 14.2.6CREATE TABLE
Syntax. -
Use of
TEMPORARY
orIF NOT EXISTS
withCREATE TABLE
. -
Use of
IF EXISTS
withDROP TABLE
. -
You can drop multiple tables with a single
DROP TABLE
statement. -
The
ORDER BY
andLIMIT
clauses of theUPDATE
andDELETE
statements. -
INSERT INTO ... SET col_name = ...
syntax. -
The
DELAYED
clause of theINSERT
andREPLACE
statements. -
The
LOW_PRIORITY
clause of theINSERT
,REPLACE
,DELETE
, andUPDATE
statements. -
Use of
INTO OUTFILE
andSTRAIGHT_JOIN
in aSELECT
statement. See section 14.1.7SELECT
Syntax. -
The
SQL_SMALL_RESULT
option in aSELECT
statement. -
You don't need to name all selected columns in the
GROUP BY
part. This gives better performance for some very specific, but quite normal queries. See section 13.9 Functions and Modifiers for Use withGROUP BY
Clauses. -
You can specify
ASC
andDESC
withGROUP BY
. -
The ability to set variables in a statement with the
:=
assignment operator:mysql> SELECT @a:=SUM(total),@b=COUNT(*),@a/@b AS avg -> FROM test_table; mysql> SELECT @t1:=(@t2:=1)[email protected]:=4,@t1,@t2,@t3;
-
The
- Column types
-
-
The column types
MEDIUMINT
,SET
,ENUM
, and the differentBLOB
andTEXT
types. -
The column attributes
AUTO_INCREMENT
,BINARY
,NULL
,UNSIGNED
, andZEROFILL
.
-
The column types
- Functions and operators
-
- To make it easier for users who come from other SQL environments, MySQL Server supports aliases for many functions. For example, all string functions support both standard SQL syntax and ODBC syntax.
-
MySQL Server understands the
||
and&&
operators to mean logical OR and AND, as in the C programming language. In MySQL Server,||
andOR
are synonyms, as are&&
andAND
. Because of this nice syntax, MySQL Server doesn't support the standard SQL||
operator for string concatenation; useCONCAT()
instead. BecauseCONCAT()
takes any number of arguments, it's easy to convert use of the||
operator to MySQL Server. -
Use of
COUNT(DISTINCT list)
wherelist
has more than one element. -
All string comparisons are case-insensitive by default, with sort
ordering determined by the current character set (ISO-8859-1 Latin1 by
default). If you don't like this, you should declare your columns with
the
BINARY
attribute or use theBINARY
cast, which causes comparisons to be done using the underlying character code values rather then a lexical ordering. -
The
%
operator is a synonym forMOD()
. That is,N % M
is equivalent toMOD(N,M)
.%
is supported for C programmers and for compatibility with PostgreSQL. -
The
=
,<>
,<=
,<
,>=
,>
,<<
,>>
,<=>
,AND
,OR
, orLIKE
operators may be used in column comparisons to the left of theFROM
inSELECT
statements. For example:mysql> SELECT col1=1 AND col2=2 FROM tbl_name;
-
The
LAST_INSERT_ID()
function that returns the most recentAUTO_INCREMENT
value. See section 13.8.3 Information Functions. -
LIKE
is allowed on numeric columns. -
The
REGEXP
andNOT REGEXP
extended regular expression operators. -
CONCAT()
orCHAR()
with one argument or more than two arguments. (In MySQL Server, these functions can take any number of arguments.) - The
BIT_COUNT()
,CASE
,ELT()
,FROM_DAYS()
,FORMAT()
,IF()
,PASSWORD()
,ENCRYPT()
,MD5()
,ENCODE()
,DECODE()
,PERIOD_ADD()
,PERIOD_DIFF()
,TO_DAYS()
, andWEEKDAY()
functions. -
Use of
TRIM()
to trim substrings. Standard SQL supports removal of single characters only. -
The
GROUP BY
functionsSTD()
,BIT_OR()
,BIT_AND()
,BIT_XOR()
, andGROUP_CONCAT()
. See section 13.9 Functions and Modifiers for Use withGROUP BY
Clauses.
For a prioritized list indicating when new extensions will be 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 1.6 MySQL and the Future (the TODO).
1.8.5 MySQL Differences from Standard SQL
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:
-
For
VARCHAR
columns, trailing spaces are removed when the value is stored. See section 1.8.7 Known Errors and Design Deficiencies in MySQL. -
In some cases,
CHAR
columns are silently converted toVARCHAR
columns when you define a table or alter its structure. See section 14.2.6.1 Silent Column Specification Changes. -
Privileges for a table are not automatically revoked when you delete a
table. You must explicitly issue a
REVOKE
statement to revoke privileges for a table. See section 14.5.1.2GRANT
andREVOKE
Syntax.
1.8.5.1 Subqueries
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 14.1.8 Subquery Syntax.
For MySQL versions older than 4.1, most subqueries can be rewritten using joins or other methods. See section 14.1.8.11 Rewriting Subqueries as Joins for Earlier MySQL Versions for examples that show how to do this.
1.8.5.2 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 14.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 20.1.6.3 SELECT ... INTO
Statement.
1.8.5.3 Transactions and Atomic Operations
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 15 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?
-
If your applications are written in a way that is dependent on being able
to call
ROLLBACK
rather thanCOMMIT
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. -
More often than not, critical transactional updates can be rewritten to be
atomic. Generally speaking, all integrity problems that transactions
solve can be done with
LOCK TABLES
or atomic updates, ensuring that you never will get an automatic abort from the server, which is a common problem with transactional database systems. - Even a transactional system can lose data if the server goes down. The difference between different systems lies in just how small the time-lag is where they could lose data. No system is 100% secure, only ``secure enough.'' Even Oracle, reputed to be the safest of transactional database systems, is reported to sometimes lose data in such situations. To be safe with MySQL Server, whether or not using transactional tables, you only need to have backups and have binary logging turned on. With this you can recover from any situation that you could with any other transactional database system. It is always good to have backups, regardless of which database system you use.
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 will stall
until any 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 new inserted records will 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 14.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 will never be an automatic rollback (which can happen with transactional tables if you are not very careful). MySQL Server also guarantees that there will not be any dirty reads.
Following are some techniques for working with non-transactional tables:
-
Loops that need transactions normally can be coded with the help of
LOCK TABLES
, and you don't need cursors to update records on the fly. -
To avoid using
ROLLBACK
, you can use the following strategy:-
Use
LOCK TABLES
to lock all the tables you want to access. - Test the conditions that must be true before performing the update.
- Update if everything is okay.
-
Use
UNLOCK TABLES
to release your locks.
-
Use
-
You can also use functions to update records in a single operation.
You can get a very efficient application by using the following
techniques:
- Modify columns relative to their current value.
- Update only those columns that actually have changed.
WHERE
clause in theUPDATE
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 typicalUPDATE
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 thepay_back
ormoney_owed_to_us
columns. -
In many cases, users have wanted
LOCK TABLES
and/orROLLBACK
for the purpose of managing unique identifiers. This can be handled much more efficiently without locking or rolling back by using anAUTO_INCREMENT
column and either theLAST_INSERT_ID()
SQL function or themysql_insert_id()
C API function. See section 13.8.3 Information Functions. See section 21.2.3.134mysql_insert_id()
. You can generally code around the need for row-level locking. Some situations really do need it, andInnoDB
tables support row-level locking. WithMyISAM
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 androw_flag
wasn't already 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;
1.8.5.4 Stored Procedures and Triggers
Stored procedures are implemented in MySQL version 5.0. See section 20 Stored Procedures and Functions.
Triggers are currently being implemented, with basic functionality in MySQL version 5.0, with further development planned for version 5.1. A ``trigger'' is effectively a type of stored procedure, one that is invoked when a particular event occurs. For example, you could set up a stored procedure that is triggered each time a record is deleted from a transactional table, and that stored procedure automatically deletes the corresponding customer from a customer table when all their transactions are deleted.
1.8.5.5 Foreign Keys
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 16.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 @command{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:
- Assuming proper design of the relationships, foreign key constraints make it more difficult for a programmer to introduce an inconsistency into the database.
- Centralized checking of constraints by the database server makes it unnecessary to perform these checks on the application side. This eliminates the possibility that different applications may not all check the constraints in the same way.
- Using cascading updates and deletes can simplify the application code.
- Properly designed foreign key rules aid in documenting relationships between tables.
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:
- In the absence of server-side foreign key relationship checking, the application itself must handle relationship issues. For example, it must take care to insert rows into tables in the proper order, and to avoid creating orphaned child records. It must also be able to recover from errors that occur in the middle of multiple-record insert operations.
-
If
ON DELETE
is the only referential integrity capability an application needs, note that as of MySQL Server 4.0, you can use multiple-tableDELETE
statements to delete rows from many tables with a single statement. See section 14.1.1DELETE
Syntax. -
A workaround for the lack of
ON DELETE
is to add the appropriateDELETE
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 support addresses many referential integrity issues, but it is still necessary to design key relationships carefully to avoid circular rules or incorrect combinations of cascading deletes.
-
It is not uncommon for a DBA to create a topology of relationships that
makes it difficult to restore individual tables from a backup.
(MySQL alleviates this difficulty by allowing you to temporarily disable
foreign key checks when reloading a table that depends on other tables.
See section 16.7.4
FOREIGN KEY
Constraints. As of MySQL 4.1.1, @command{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 14.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.
1.8.5.6 Views
Views (updatable) are being implemented in the 5.0 version of MySQL Server.
They are already available in binary releases from 5.0.1 and up.
See section 14.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.''
1.8.5.7 `--' as the Start of a Comment
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 10.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 @command{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 @command{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
1.8.6 How MySQL Deals with Constraints
MySQL allows you to work with both transactional tables that allow rollback and non-transactional tables that do not, so constraint handling is a bit different in MySQL than in other databases.
We have to handle the case when you have updated a lot of rows in a non-transactional table that cannot roll back when an error occurs.
The basic philosophy is to try to give an error for anything that we can detect at compile time but try to recover from any errors we get at runtime. We do this in most cases, but not yet for all. See section 1.6.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.
The following sections describe what happens for the different types of constraints.
1.8.6.1 Constraint PRIMARY KEY
/ UNIQUE
Normally you will get an error 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 will automatically roll back the transaction. If you are
using a non-transactional storage engine, MySQL will stop at the incorrect
row and leave any remaining rows unprocessed.
To make life easier, MySQL supports an IGNORE
keyword for
most commands that can cause a key violation (such as INSERT IGNORE
and UPDATE IGNORE
). In this case, MySQL will ignore any key
violation and continue with processing the next row. You can get
information about what MySQL did with the mysql_info()
C API function.
See section 21.2.3.126 mysql_info()
.
In MySQL 4.1 and up, you also can use the SHOW WARNINGS
statement.
See section 14.5.3.21 SHOW WARNINGS
Syntax.
Note that, for the moment, only InnoDB
tables support foreign keys.
See section 16.7.4 FOREIGN KEY
Constraints.
Foreign key support in MyISAM
tables is scheduled for implementation
in MySQL 5.1.
1.8.6.2 Constraint NOT NULL
and DEFAULT
Values
To be able to support easy handling of non-transactional tables, all columns in MySQL have implicit/explicit default values.
The following holds true when you are not using the STRICT_ALL_TABLES
or if you are using STRICT_TRANS_TABLES
and the first update to
a non-transactional table didn't produce an error. See section 5.2.2 The Server SQL Mode.
It's also true if you are using INSERT IGNORE
or UPDATE IGNORE
.
If you insert an ``incorrect'' value into a column, such as a NULL
into a NOT NULL
column or a too-large numerical value into a
numerical column, MySQL sets the column to the ``best possible value''
instead of producing an error:
- If you try to store a value outside the range in a numerical column, MySQL Server instead stores zero, the smallest possible value, or the largest possible value in the column.
- For strings, MySQL stores either the empty string or the longest possible string that can be in the column.
- If you try to store a string that doesn't start with a number into a numerical column, MySQL Server stores 0.
-
If you try to store
NULL
into a column that doesn't takeNULL
values, MySQL Server stores 0 or''
(the empty string) instead. This last behavior can, for single-row inserts, be changed when MySQL is built by using the-DDONT_USE_DEFAULT_FIELDS
compile option.) See section 2.3.2 Typical @command{configure} Options options}. This causesINSERT
statements to generate an error unless you explicitly specify values for all columns that require a non-NULL
value. -
MySQL allows you to store some incorrect date values into
DATE
andDATETIME
columns (like'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. -
If you don't specify a column that doesn't have a default value in an
INSERT
statement, MySQL will insert an empty string for string columns and 0 for numerical columns.
The reason for the preceding rules is that we can't check these conditions until the query 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 other words, if you are using STRICT_ALL_TABLES
, you risk getting
half updates. A safer setting is to use STRICT_TRANS_TABLES
. In this
case, a wrong value causes MySQL to roll back, if it can, all updates done
so far (that is, if we have updated only transactional tables).
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.
1.8.6.3 Constraint ENUM
and SET
In MySQL 4.x and earlier, ENUM
is not a real constraint, but is a
more efficient way to define columns that can contain only a given set of
values. This is for the same reasons that NOT NULL
is not honored.
See section 1.8.6.2 Constraint NOT NULL
and DEFAULT
Values.
ENUM
columns always have a default value. If you don't specify
a default value, then it will be 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 12.4.3 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 12.4.4 The SET
Type.
As of MySQL 5.0.2, strict SQL mode is implemented. See section 5.2.2 The Server SQL Mode.
If strict mode is not enabled, values entered into ENUM
and SET
columns are handled as just described for MySQL 4.x. If strict mode is
enabled, the definition of a ENUM
or SET
column acts as a
constraint on values entered into the column. An error occurs for values
that do not satisify these conditions:
-
An
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 asENUM('a','b','c')
, values such as''
,'d'
, and'ax'
are illegal. -
A
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 asSET('a','b','c')
, values such as'd'
, and'a,b,c,d'
are illegal.
In strict mode, errors for invalid values can be suppressed 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
that any invalid substrings are deleted. For example, 'a,x,b,y'
results in a value of 'a,b'
, as described earlier.
1.8.7 Known Errors and Design Deficiencies in MySQL
1.8.7.1 Errors in 3.23 Fixed in a Later MySQL Version
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.''
- You should avoid using spaces at the end of column names because this can cause weird behavior. (Fixed in MySQL 4.0.) (Bug #4196)
-
You can get a deadlock (hung thread) if you use
LOCK TABLE
to lock multiple tables and then in the same connection useDROP TABLE
to drop one of them while another thread is trying to lock it. (To break the deadlock, you can useKILL
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 returnNULL
but instead returns the maximum value for the column. This issue is resolved as of MySQL 4.0.11. -
DELETE FROM heap_table
without aWHERE
clause doesn't work on a lockedHEAP
table.
1.8.7.2 Errors in 4.0 Fixed in a Later MySQL Version
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.''
-
In a
UNION
, the firstSELECT
determines the type,max_length
, andNULL
properties for the resulting columns. This issue is resolved as of MySQL 4.1.1; the property values are based on the rows from allUNION
parts. -
In
DELETE
with many tables, you can't refer to tables to be deleted through an alias. This is fixed as of MySQL 4.1. -
You cannot mix
UNION ALL
andUNION DISTINCT
in the same query. If you useALL
for oneUNION
, it is used for all of them. This is fixed as of MySQL 4.1.2. The rules for mixedUNION
types are given in section 14.1.7.2UNION
Syntax. -
FLUSH TABLES WITH READ LOCK
does not blockCREATE TABLE
, which may cause a problem with the binary log position when doing a full backup of tables and the binary log.
1.8.7.3 Open Bugs and Design Deficiencies in MySQL
The following problems are known and fixing them is a high priority:
-
Even if you are using
lower_case_table_names=2
(which enables MySQL to remember the used case for databases and table names) MySQL will not on case insensitive systems remember the used case for database names for the functionDATABASE()
or in various logs. -
Dropping a
FOREIGN KEY
constraint doesn't work in replication because the constraint may have another name on the slave. -
REPLACE
(andLOAD DATA
with theREPLACE
option) does not triggerON DELETE CASCADE
. -
DISTINCT
withORDER BY
doesn't work insideGROUP_CONCAT()
if you don't use all and only those columns that are in theDISTINCT
list. -
If one user has a long-running transaction and another user drops a
table that is updated in the transaction, there is small chance that the
binary log may contain the
DROP TABLE
command before the table is used in the transaction itself. We plan to fix this in 5.0 by having theDROP TABLE
wait until the table is not used in any transaction. -
When inserting a big integer value (between 2^63 and 2^64-1) into a
decimal/string column, it is inserted as a negative value because
the number is evaluated in a signed integer context. We plan to fix this in
MySQL 4.1.
FLUSH TABLES WITH READ LOCK
does not blockCOMMIT
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 aBDB
table may in some cases make the table unusable until you restart @command{mysqld}. If this happens, you will see errors of the following form in the MySQL error file:001207 22:07:56 bdb: log_flush: LSN past current end-of-log
-
MySQL accepts parentheses in the
FROM
clause of aSELECT
statement, but silently ignores them. The reason for not giving an error is that many clients that automatically generate queries add parentheses in theFROM
clause even where they are not needed. -
Concatenating many
RIGHT JOINS
or combiningLEFT
andRIGHT
join in the same query may not give a correct answer because MySQL only generatesNULL
rows for the table preceding aLEFT
or before aRIGHT
join. This will be fixed in 5.0 at the same time we add support for parentheses in theFROM
clause. -
Don't execute
ALTER TABLE
on aBDB
table on which you are running multiple-statement transactions until all those transactions complete. (The transaction will probably be ignored.) -
ANALYZE TABLE
,OPTIMIZE TABLE
, andREPAIR TABLE
may cause problems on tables for which you are usingINSERT DELAYED
. -
Doing a
LOCK TABLE ...
andFLUSH 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 manyBDB
tables in a database, it will take a long time to use the @command{mysql} client on the database if you are not using the-A
option or if you are usingrehash
. This is especially notable when you have a large table cache. -
Replication uses query-level logging: The master writes the executed
queries to the binary log. This is a very fast, compact, and efficient
logging method that works perfectly in most cases.
Although we have never heard of it actually occurring, it is theoretically
possible for the data on the master and slave to become different if a
query is designed in such a way that the data modification is
non-deterministic; that is, left to the will of the query optimizer. (That
generally is not a good practice anyway, even outside of replication!)
For example:
-
CREATE ... SELECT
orINSERT ... SELECT
statements that insert zero orNULL
values into anAUTO_INCREMENT
column. -
DELETE
if you are deleting rows from a table that has foreign keys withON 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, forINSERT ... SELECT
with noORDER BY
, theSELECT
may return rows in a different order (which will result in a row having different ranks, hence getting a different number in theAUTO_INCREMENT
column), depending on the choices made by the optimizers on the master and slave. A query will be optimized differently on the master and slave only if:-
The files used by the two queries are not exactly the same; for
example,
OPTIMIZE TABLE
was run on the master tables and not on the slave tables. (To fix this,OPTIMIZE TABLE
,ANALYZE TABLE
, andREPAIR TABLE
are written to the binary log as of MySQL 4.1.1). -
The table is stored using a different storage engine on the master than
on the slave. (It is possible to use different storage engines on the master
and slave. For example, you can use
InnoDB
on the master, butMyISAM
on the slave if the slave has less available disk space.) -
MySQL buffer sizes (
key_buffer_size
, and so on) are different on the master and slave. - The master and slave run different MySQL versions, and the optimizer code differs between these versions.
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 anORDER BY
clause when needed. -
The following problems are known and will be fixed in due time:
-
Log filenames are based on the server hostname (if you don't specify a
filename with the startup option). For now you have to use options like
--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. See section 5.2.1 @command{mysqld} Command-Line Options. -
@command{mysqlbinlog} will not delete temporary files left after a
LOAD DATA INFILE
command. @xref{mysqlbinlog, , @command{mysqlbinlog}}. -
RENAME
doesn't work withTEMPORARY
tables or tables used in aMERGE
table. -
When using the
RPAD()
function in a query that has to be resolved by using a temporary table, all resulting strings will have rightmost spaces removed. This is an example of such a query:SELECT RPAD(t1.column1, 50, ' ') AS f2, RPAD(t2.column2, 50, ' ') AS f1 FROM table1 as t1 LEFT JOIN table2 AS t2 ON t1.record=t2.joinID ORDER BY t2.record;
The final result of this bug is that you will not be able to get spaces on the right side of the resulting values. The problem also occurs for any other string function that adds spaces to the right. The reason for this is due to the fact thatHEAP
tables, which are used first for temporary tables, are not capable of handlingVARCHAR
columns. This behavior exists in all versions of MySQL. It will be fixed in one of the 4.1 series releases. -
Due to the way table definition files are stored, you cannot use
character 255 (
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. -
When using
SET CHARACTER SET
, you can't use translated characters in database, table, and column names. -
You can't use `_' or `%' with
ESCAPE
inLIKE ... ESCAPE
. -
If you have a
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. - You cannot build the server in another directory when using MIT-pthreads. Because this requires changes to MIT-pthreads, we are not likely to fix this. See section 2.3.5 MIT-pthreads Notes.
-
BLOB
andTEXT
values can't ``reliably'' be used inGROUP BY
orORDER BY
orDISTINCT
. Only the firstmax_sort_length
bytes are used when comparingBLOB
values in these cases. The default value ofmax_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;
-
Numeric
calculations are done with
BIGINT
orDOUBLE
(both are normally 64 bits long). Which precision you get depends on the function. The general rule is that bit functions are done withBIGINT
precision,IF
andELT()
withBIGINT
orDOUBLE
precision, and the rest withDOUBLE
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 betterBIGINT
handling than 3.23. -
All string columns, except
BLOB
andTEXT
columns, automatically have all trailing spaces removed when retrieved. ForCHAR
types, this is okay. The bug is that in MySQL Server,VARCHAR
columns are treated the same way. -
You can have only up to 255
ENUM
andSET
columns in one table. -
In
MIN()
,MAX()
, and other aggregate functions, MySQL currently comparesENUM
andSET
columns by their string value rather than by the string's relative position in the set. -
@command{mysqld_safe} redirects all messages from @command{mysqld} to the
@command{mysqld} log. One problem with this is that if you execute
@command{mysqladmin refresh} to close and reopen the log,
stdout
andstderr
are still redirected to the old log. If you use--log
extensively, you should edit @command{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 @command{mysqladmin refresh}. -
In the
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 incrementsKEY
by2
, not1
:mysql> UPDATE tbl_name SET KEY=KEY+1,KEY=KEY+1;
-
You can refer to multiple temporary tables in the same query, but
you cannot refer to any given temporary table more than once.
For example, the following doesn't work:
mysql> SELECT * FROM temp_table, temp_table AS t2; ERROR 1137: Can't reopen table: 'temp_table'
-
The optimizer may handle
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 theDISTINCT
comparison. We will probably change this in the future to never compare the hidden columns when executingDISTINCT
. An example of this is:SELECT DISTINCT mp3id FROM band_downloads WHERE userid = 9 ORDER BY id DESC;
andSELECT 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 hiddenid
column may differ). Note that this happens only for queries where you don't have theORDER BY
columns in the result. - Because MySQL Server allows you to work with table types that don't support transactions, and thus can't roll back data, some things behave a little differently in MySQL Server than in other SQL servers. This is just to ensure that MySQL Server never needs to do a rollback for an SQL statement. This may be a little awkward at times because column values must be checked in the application, but this will actually give you a nice speed increase because it allows MySQL Server to do some optimizations that otherwise would be very hard to do. If you set a column to an incorrect value, MySQL Server will, instead of doing a rollback, store the ``best possible value'' in the column. For information about how this occurs, see section 1.8.6 How MySQL Deals with Constraints.
-
If you execute a
PROCEDURE
on a query that returns an empty set, in some cases thePROCEDURE
will not transform the columns. -
Creation of a table of type
MERGE
doesn't check whether the underlying tables are of compatible types. -
If you use
ALTER TABLE
first to add aUNIQUE
index to a table used in aMERGE
table and then to add a normal index on theMERGE
table, the key order will be different for the tables if there was an old key that was not unique in the table. This is becauseALTER TABLE
putsUNIQUE
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:
-
In the following case you can get a core dump:
- Delayed insert handler has pending inserts to a table.
-
LOCK TABLE
withWRITE
. -
FLUSH TABLES
.
-
Before MySQL Server 3.23.2, an
UPDATE
that updated a key with aWHERE
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 will work because MySQL Server will not use an index on expressions in theWHERE
clause. - Before MySQL Server 3.23, all numeric types were treated as fixed-point fields. That means that you had to specify how many decimals a floating-point field should have. All results were returned with the correct number of decimals.
For information about platform-specific bugs, see the installation and porting instructions in section 2.6 Operating System-Specific Notes and section D Porting to Other Systems.
2 Installing MySQL
This chapter describes how to obtain and install MySQL:
- Determine whether your platform is supported. Please note that not all supported systems are equally good for running MySQL on them. On some it is much more robust and efficient than others. See section 2.1.1 Operating Systems Supported by MySQL for details.
- Choose which distribution to install. Several versions of MySQL are available, and most are available in several distribution formats. You can choose from pre-packaged distributions containing binary (precompiled) programs or source code. When in doubt, use a binary distribution. We also provide public access to our current source tree for those who want to see our most recent developments and help us test new code. To determine which version and type of distribution you should use, see section 2.1.2 Choosing Which MySQL Distribution to Install.
-
Download the distribution that you want to install.
For a list of sites from which you can obtain MySQL, see
section 2.1.3 How to Get MySQL.
You can verify the integrity of the distribution using the instructions in
section 2.1.4 Verifying Package Integrity Using MD5 Checksums or
GnuPG
. - Install the distribution. To install MySQL from a binary distribution, use the instructions in section 2.2 Standard MySQL Installation Using a Binary Distribution. To install MySQL from a source distribution or from the current development source tree, use the instructions in section 2.3 MySQL Installation Using a Source Distribution. Note: If you plan to upgrade an existing version of MySQL to a newer version rather than installing MySQL for the first time, see section 2.5 Upgrading/Downgrading MySQL for information about upgrade procedures and about issues that you should consider before upgrading. If you encounter installation difficulties, see section 2.6 Operating System-Specific Notes for information on solving problems for particular platforms.
- Perform any necessary post-installation setup. After installing MySQL, read section 2.4 Post-Installation Setup and Testing. This section contains important information about making sure the MySQL server is working properly. It also describes how to secure the initial MySQL user accounts, which have no passwords until you assign passwords. The section applies whether you install MySQL using a binary or source distribution.
- If you want to run the MySQL benchmark scripts, Perl support for MySQL must be available. See section 2.7 Perl Installation Notes.
2.1 General Installation Issues
Before installing MySQL, you should do the following:
- Determine whether or not MySQL runs on your platform.
- Choose a distribution to install.
- Download the distribution and verify its integrity.
This section contains the information necessary to carry out these steps. After doing so, you can use the instructions in later sections of the chapter to install the distribution that you choose.
2.1.1 Operating Systems Supported by MySQL
This section lists the operating systems on which you can expect to be able to run MySQL.
We use GNU Autoconf, so it is possible to port MySQL to all modern systems that have a C++ compiler and a working implementation of POSIX threads. (Thread support is needed for the server. To compile only the client code, the only requirement is a C++ compiler.) We use and develop the software ourselves primarily on Linux (SuSE and Red Hat), FreeBSD, and Sun Solaris (Versions 8 and 9).
MySQL has been reported to compile successfully on the following combinations of operating system and thread package. Note that for many operating systems, native thread support works only in the latest versions.
- AIX 4.x, 5.x with native threads. See section 2.6.5.3 IBM-AIX notes.
- Amiga.
- BSDI 2.x with the MIT-pthreads package. See section 2.6.4.5 BSD/OS Version 2.x Notes.
- BSDI 3.0, 3.1 and 4.x with native threads. See section 2.6.4.5 BSD/OS Version 2.x Notes.
- Digital Unix 4.x with native threads. See section 2.6.5.5 Alpha-DEC-UNIX Notes (Tru64).
- FreeBSD 2.x with the MIT-pthreads package. See section 2.6.4.1 FreeBSD Notes.
- FreeBSD 3.x and 4.x with native threads. See section 2.6.4.1 FreeBSD Notes.
- FreeBSD 4.x with LinuxThreads. See section 2.6.4.1 FreeBSD Notes.
- HP-UX 10.20 with the DCE threads or the MIT-pthreads package. See section 2.6.5.1 HP-UX Version 10.20 Notes.
- HP-UX 11.x with the native threads. See section 2.6.5.2 HP-UX Version 11.x Notes.
-
Linux 2.0+ with LinuxThreads 0.7.1+ or
glibc
2.0.7+ for various CPU architectures. See section 2.6.1 Linux Notes. - Mac OS X. See section 2.6.2 Mac OS X Notes.
- NetBSD 1.3/1.4 Intel and NetBSD 1.3 Alpha (requires GNU make). See section 2.6.4.2 NetBSD Notes.
- Novell NetWare 6.0. See section 2.2.4 Installing MySQL on NetWare.
- OpenBSD > 2.5 with native threads. OpenBSD < 2.5 with the MIT-pthreads package. See section 2.6.4.3 OpenBSD 2.5 Notes.
- OS/2 Warp 3, FixPack 29 and OS/2 Warp 4, FixPack 4. See section 2.6.6 OS/2 Notes.
- SCO OpenServer with a recent port of the FSU Pthreads package. See section 2.6.5.8 SCO Notes.
- SCO UnixWare 7.1.x. See section 2.6.5.9 SCO UnixWare Version 7.1.x Notes.
- SGI Irix 6.x with native threads. See section 2.6.5.7 SGI Irix Notes.
- Solaris 2.5 and above with native threads on SPARC and x86. See section 2.6.3 Solaris Notes.
- SunOS 4.x with the MIT-pthreads package. See section 2.6.3 Solaris Notes.
- Tru64 Unix. See section 2.6.5.5 Alpha-DEC-UNIX Notes (Tru64).
- Windows 9x, Me, NT, 2000, and XP. See section 2.2.1 Installing MySQL on Windows.
Not all platforms are equally well-suited for running MySQL. How well a certain platform is suited for a high-load mission-critical MySQL server is determined by the following factors:
- General stability of the thread library. A platform may have an excellent reputation otherwise, but MySQL will be only as stable as the thread library if that library is unstable in the code that is called by MySQL, even if everything else is perfect.
- The capability of the kernel and the thread library to take advantage of symmetric multi-processor (SMP) systems. In other words, when a process creates a thread, it should be possible for that thread to run on a different CPU than the original process.
-
The capability of the kernel and the thread library to run many threads that
acquire and release a mutex over a short critical region frequently without
excessive context switches. If the implementation of
pthread_mutex_lock()
is too anxious to yield CPU time, this will hurt MySQL tremendously. If this issue is not taken care of, adding extra CPUs will actually make MySQL slower. - General filesystem stability and performance.
- If your tables are big, the ability of the filesystem to deal with large files at all and to deal with them efficiently.
- Our level of expertise here at MySQL AB with the platform. If we know a platform well, we enable platform-specific optimizations and fixes at compile time. We can also provide advice on configuring your system optimally for MySQL.
- The amount of testing we have done internally for similar configurations.
- The number of users that have successfully run MySQL on the platform in similar configurations. If this number is high, the chances of encountering platform-specific surprises are much smaller.
Based on the preceding criteria, the best platforms for running
MySQL at this point are x86 with SuSE Linux using a 2.4 kernel, and
ReiserFS (or any similar Linux distribution) and SPARC with Solaris
(2.7-9). FreeBSD comes third, but we really hope it will join the top
club once the thread library is improved. We also hope that at some
point we will be 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 will require 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.7.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.
2.1.2 Choosing Which MySQL Distribution to Install
When preparing to install MySQL, you should decide which version to use. MySQL development occurs in several release series, and you can pick the one that best fits your needs. After deciding which version to install, you can choose a distribution format. Releases are available in binary or source format.
2.1.2.1 Choosing Which Version of MySQL to Install
The first decision to make is whether you want to use a production (stable) release or a development release. In the MySQL development process, multiple release series co-exist, each at a different stage of maturity:
- MySQL 5.0 is the newest development release series and is under very active development for new features. Alpha releases have been issued to allow more widespread testing.
- MySQL 4.1 is in gamma status, soon moving to production status.
- MySQL 4.0 is the current stable (production-quality) release series. New releases are issued for bugfixes. No new features are added that could diminish the code stability.
- MySQL 3.23 is the old stable (production-quality) release series. This series is retired, so new releases are issued only to fix critical bugs.
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 will not affect anything that's already 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.0. All MySQL releases, even those from development series, are checked with the MySQL benchmarks and an extensive test suite before being issued.
If you are running an 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 will be 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:
-
The first number (
4
) is the major version and also describes the file format. All Version 4 releases have the same file format. -
The second number (
1
) is the release level. Taken together, the major version and release level constitute the release series number. -
The third 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 C 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 will be tested before issuing a release. For this reason, there should be no known bugs in any MySQL release. -
beta
means 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 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. -
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. - If there is no suffix, it means that the version has been run for a while at many different sites with no reports of bugs other than platform-specific bugs. Only critical bugfixes are applied to the release. This is what we call a production (stable) 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:
- An internal test suite
- The `mysql-test' directory contains an extensive set of test cases. We run these tests for virtually every server binary. See section 24.1.2 MySQL Test Suite for more information about this test suite.
- The MySQL benchmark suite
- This suite runs a range of common queries. It is also a test to see whether the latest batch of optimizations actually made the code faster. See section 7.1.4 The MySQL Benchmark Suite.
- The
crash-me
test - This test tries to determine what features the database supports and what its capabilities and limitations are. See section 7.1.4 The MySQL Benchmark Suite.
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.
2.1.2.2 Choosing a Distribution Format
After choosing which version of MySQL to install, you should decide whether to use a binary distribution or a source distribution. In most cases, you should probably use a binary distribution, if one exists for your platform. Binary distributions are available in native format for many platforms, such as RPM files for Linux or DMG package installers for Mac OS X. Distributions also are available as Zip archives or compressed @command{tar} files.
Reasons to choose a binary distribution include the following:
- Binary distributions generally are easier to install than source distributions.
-
To satisfy different user requirements, we provide two
different binary versions: one compiled with the non-transactional storage
engines (a small, fast binary), and one configured with the most
important extended options like transaction-safe tables. Both versions
are compiled from the same source distribution. All native MySQL
clients can connect to servers from either MySQL version.
The extended MySQL binary distribution is marked with the
-max
suffix and is configured with the same options as @command{mysqld-max}. @xref{mysqld-max, , @command{mysqld-max}}. If you want to use theMySQL-Max
RPM, you must first install the standardMySQL-server
RPM.
Under some circumstances, you probably will be better off installing MySQL from a source distribution:
- You want to install MySQL at some explicit location. The standard binary distributions are ``ready to run'' at any place, but you may want to have even more flexibility to place MySQL components where you want.
-
You want to configure @command{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]
- You want to configure @command{mysqld} without some features that are included in the standard binary distributions. For example, distributions normally are compiled with support for all character sets. If you want a smaller MySQL server, you can recompile it with support for only the character sets you need.
-
You have a special compiler (such as
pgcc
) or want to use compiler options that are better optimized for your processor. Binary distributions are compiled with options that should work on a variety of processors from the same processor family. - You want to use the latest sources from one of the BitKeeper repositories to have access to all current bugfixes. For example, if you have found a bug and reported it to the MySQL development team, the bugfix will be committed to the source repository and you can access it there. The bugfix will not appear in a release until a release actually is issued.
- You want to read (or modify) the C and C++ code that makes up MySQL. For this purpose, you should get a source distribution, because the source code is always the ultimate manual.
- Source distributions contain more tests and examples than binary distributions.
2.1.2.3 How and When Updates Are Released
MySQL is evolving quite rapidly 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 extended email-supported customers want and try to help them out.
No one has to download a new release. The News section will tell you if the new release has something you really want. See section C MySQL Change History.
We use the following policy when updating MySQL:
- Releases are issued within each series. For each release, the last number in the version is one more than the previous release within the same series.
- Production (stable) releases are meant to appear about 1-2 times a year. However, if small bugs are found, a release with only bugfixes will be issued.
- Working releases/bugfixes to old releases are meant to appear about every 4-8 weeks.
- Binary distributions for some platforms are made by us for major releases. Other people may make binary distributions for other systems, but probably less frequently.
- We make fixes available as soon as we have identified and corrected small or non-critical but annoying bugs. The fixes are available immediately from our public BitKeeper repositories, and will be included in the next release.
- If by any chance a fatal bug is found in a release, we will make a new release as soon as possible. (We would like other companies to do this, too!)
2.1.2.4 Release Philosophy--No Known Bugs in Releases
We put a lot of time and effort into making our releases bug-free. To our knowledge, we have not 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.8.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:
- We monitor bugs from our customer support list, the bugs database at http://bugs.mysql.com/, and the MySQL external mailing lists.
- All reported bugs for live versions are entered into the bugs database.
- When we fix a bug, we always try to make a test case for it and include it into our test system to ensure that the bug will never recur without being detected. (About 90% of all fixed bugs have a test case.)
- We create test cases for all new features we add to MySQL.
- Before we start to build a new MySQL release, we ensure that all reported repeatable bugs for the MySQL version (3.23.x, 4.0.x, etc) are fixed. If something is impossible to fix (due to some internal design decision in MySQL), we document this in the manual. See section 1.8.7 Known Errors and Design Deficiencies in MySQL.
- We do a build on all platforms for which we support binaries (15+ platforms) and run our test suite and benchmark suite on all of them.
- We will not publish a binary for a platform for which the test or benchmark suite fails. If the problem is due to a general error in the source, we fix it and do the build plus tests on all systems again from scratch.
- The build and test process takes 2-3 days. If we receive a report regarding a fatal bug during this process (for example, one that causes a core dump), we fix the problem and restart the build process.
-
After publishing the binaries on http://dev.mysql.com/, we send
out an announcement message to the
mysql
andannounce
mailing lists. See section 1.7.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. - To quickly give our users access to the latest MySQL features, we do a new MySQL release every 4-8 weeks. Source code snapshots are built daily and are available at http://downloads.mysql.com/snapshots.php.
-
If, despite our best efforts, we get any bug reports after the release is done
that there was something critically wrong with the build on a specific
platform, we will fix it at once and build a new
'a'
release for that platform. Thanks to our large user base, problems are found quickly. -
Our track record for making good releases is quite good. In the last
150 releases, we had to do a new build for fewer than 10 releases. In three
of these cases, the bug was a faulty
glibc
library on one of our build machines that took us a long time to track down.
2.1.2.5 MySQL Binaries Compiled by MySQL AB
As a service of MySQL AB, we provide a set of binary distributions of MySQL that are compiled on systems at our site or on systems where supporters of MySQL kindly have given us access to their machines.
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 @command{tar} files (.tar.gz
files).
See section 2.2 Standard MySQL Installation Using a Binary Distribution.
For Windows distributions, see section 2.2.1 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
@command{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
@command{bin/mysqlbug} of every binary @command{tar} file distribution.
The following binaries are built on MySQL AB development systems:
- Linux 2.4.xx x86 with @command{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
- Linux 2.4.x x86 with @command{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
- Linux 2.4.xx Intel Itanium 2 with @command{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
- Linux 2.4.xx Intel Itanium with @command{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
- Linux 2.4.xx alpha with
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
- Linux 2.x.xx ppc with @command{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
- Linux 2.4.xx s390 with @command{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
- Linux 2.4.xx x86_64 (AMD64) with @command{gcc 3.2.1:}
-
CXX=gcc ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex --enable-thread-safe-client --enable-local-infile --disable-shared
- Sun Solaris 8 x86 with @command{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
- Sun Solaris 8 SPARC with @command{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
- Sun Solaris 8 SPARC 64-bit with @command{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
- Sun Solaris 9 SPARC with @command{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
- Sun Solaris 9 SPARC with
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
- IBM AIX 4.3.2 ppc with @command{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
- IBM AIX 4.3.3 ppc with
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
- IBM AIX 5.1.0 ppc with @command{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
- IBM AIX 5.2.0 ppc with
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
- HP-UX 10.20 pa-risc1.1 with @command{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
- HP-UX 11.00 pa-risc with
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
- HP-UX 11.11 pa-risc2.0 64bit with
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
- HP-UX 11.11 pa-risc2.0 32bit with
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
- HP-UX 11.22 ia64 64bit with
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
- Apple Mac OS X 10.2 powerpc with @command{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
- FreeBSD 4.7 i386 with @command{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
- FreeBSD 4.7 i386 using LinuxThreads with @command{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
- QNX Neutrino 6.2.1 i386 with @command{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.
- SCO Unix 3.2v5.0.6 i386 with @command{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
- SCO OpenUnix 8.0.0 i386 with @command{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
- Compaq Tru64 OSF/1 V5.1 732 alpha with
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-prefix=/usr/local/mysql --with-named-thread-libs="-lpthread -lmach -lexc -lc" --disable-shared --with-mysqld-ldflags=-all-static
- SGI Irix 6.5 IP32 with @command{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
- FreeBSD/sparc64 5.0 with @command{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.
- Linux 2.2.xx SPARC with @command{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
- Linux 2.2.x with x686 with @command{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
- SunOS 4.1.4 2 sun4c with @command{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
- SunOS 5.5.1 (and above) sun4u with @command{egcs 1.0.3a or 2.90.27 or}
-
@command{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
- SunOS 5.6 i86pc with @command{gcc 2.8.1:}
-
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-low-memory --with-extra-charsets=complex
- BSDI BSD/OS 3.1 i386 with @command{gcc 2.7.2.1:}
-
CC=gcc CXX=gcc CXXFLAGS=-O ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
- BSDI BSD/OS 2.1 i386 with @command{gcc 2.7.2:}
-
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql --with-extra-charsets=complex
- AIX 4.2 with @command{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.7.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
@command{configure} commands and remove any -fomit-frame-pointer
options.
2.1.3 How to Get MySQL
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 will 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/.
2.1.4 Verifying Package Integrity Using MD5 Checksums or GnuPG
After you have downloaded the MySQL package that suits your needs and before you attempt to install it, you should make sure that it is intact and has not been tampered with. MySQL AB offers three means of integrity checking:
- MD5 checksums
-
Cryptographic signatures using
GnuPG
, the GNU Privacy Guard - For RPM packages, the built-in RPM integrity verification mechanism
The following sections describe how to use these methods.
If you notice that the MD5 checksum or GPG signatures do not match, first try to download the respective package one more time, perhaps from another mirror site. If you repeatedly cannot successfully verify the integrity of the package, please notify us about such incidents, including the full package name and the download site you have been using, at [email protected] or [email protected]. Do not report downloading problems using the bug-reporting system.
2.1.4.1 Verifying the MD5 Checksum
After you have downloaded a MySQL package, you should make sure that its MD5
checksum matches the one provided on the MySQL download pages. Each package
has an individual checksum that you can verify with the following command,
where package_name
is the name of the package you downloaded:
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 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 is available from http://www.fourmilab.ch/md5/.
2.1.4.2 Signature Checking Using GnuPG
Another method of verifying the integrity and authenticity of a package is to use cryptographic signatures. This is more reliable than using MD5 checksums, but requires more work.
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
already 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
[email protected]
. 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) <[email protected]> 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) <[email protected]>"
The Good signature
message indicates that everything is all right.
You can ignore the insecure memory
warning.
2.1.4.3 Signature Checking Using RPM
For RPM packages, there is no separate signature. RPM packages have a built-in GPG signature and MD5 checksum. You can verify a package by running the following command:
shell> rpm --checksig package_name.rpm
Example:
shell> rpm --checksig MySQL-server-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 @command{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
2.1.5 Installation Layouts
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', which has the following subdirectories:
Directory | Contents of Directory |
`bin' | Client programs and the @command{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 @command{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 @command{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 @command{mysqld} server |
`data' | Log files, databases |
`docs' | Documentation, ChangeLog |
`include' | Include (header) files |
`lib' | Libraries |
`scripts' | @command{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 @command{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:
- The @command{mysqld} server is installed in the `libexec' directory rather than in the `bin' directory.
- The data directory is `var' rather than `data'.
- @command{mysql_install_db} is installed in the `bin' directory rather than in the `scripts' directory.
- The header file and library directories are `include/mysql' and `lib/mysql' rather than `include' and `lib'.
You can create your own binary installation from a compiled source distribution by executing the `scripts/make_binary_distribution' script from the top directory of the source distribution.
2.2 Standard MySQL Installation Using a Binary Distribution
This section covers the installation of MySQL on platforms where we offer packages using the native packaging format of the respective platform. (This is also known as performing a ``binary install.'') However, binary distributions of MySQL are available for many other platforms as well. See section 2.2.5 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.
2.2.1 Installing MySQL on Windows
The installation process for MySQL on Windows has the following steps:
- Obtain and install the distribution.
- Set up an option file if necessary.
- Select the server you want to use.
- Start the server.
- Assign passwords to the initial MySQL accounts.
MySQL for Windows is available in two distribution formats:
- The binary distribution contains a setup program that installs everything you need so that you can start the server immediately.
- The source distribution contains all the code and support files for building the executables using the VC++ 6.0 compiler.
Generally speaking, you should use the binary distribution. It's simpler, and you need no additional tools to get MySQL up and running.
This section describes how to install MySQL on Windows using a binary distribution. To install using a source distribution, see section 2.3.6 Installing MySQL from Source on Windows.
2.2.1.1 Windows System Requirements
To run MySQL on Windows, you need the following:
- A 32-bit Windows operating system such as 9x, Me, NT, 2000, or XP. The NT family (Windows NT, 2000, and XP) permits you to run the MySQL server as a service. See section 2.2.1.7 Starting MySQL as a Windows Service.
- TCP/IP protocol support.
- A copy of the MySQL binary distribution for Windows, which can be downloaded from http://dev.mysql.com/downloads/. See section 2.1.3 How to Get MySQL. Note: If you download the distribution via FTP, we recommend the use of an adequate FTP client with a resume feature to avoid corruption of files during the download process.
-
WinZip
or other Windows tool that can read `.zip' files, to unpack the distribution file. - Enough space on the hard drive to unpack, install, and create the databases in accordance with your requirements.
- If you plan to connect to the MySQL server via ODBC, you also need a Connector/ODBC driver. See section 22.1 MySQL ODBC Support.
-
If you need tables with a size larger than 4GB, install MySQL
on an NTFS or newer filesystem. Don't forget to use
MAX_ROWS
andAVG_ROW_LENGTH
when you create tables. See section 14.2.6CREATE TABLE
Syntax.
2.2.1.2 Installing a Windows Binary Distribution
To install MySQL on Windows using a binary distribution, follow this procedure:
- If you are working on a Windows NT, 2000, or XP machine, make sure that you have logged in as a user with administrator privileges.
-
If you are doing an upgrade of an earlier MySQL installation,
it is necessary to stop the current server.
On Windows NT, 2000, or XP machines, if you are running the server
as a Windows service, stop it as follows from the command prompt:
C:\> NET STOP MySQL
If you plan to use a different server after the upgrade (for example, if you want to run @command{mysqld-max} rather than @command{mysqld}), remove the existing service:C:\> C:\mysql\bin\mysqld --remove
You can reinstall the service to use the proper server after upgrading. If you are not running the MySQL server as a service, stop it like this:C:\> C:\mysql\bin\mysqladmin -u root shutdown
-
Exit the
WinMySQLAdmin
program if it is running. - Unzip the distribution file to a temporary directory.
-
Run the
setup.exe
program to begin the installation process. If you want to install MySQL into a location other than the default directory (`C:\mysql'), use theBrowse
button to specify your preferred directory. If you do not install MySQL into the default location, you will need to specify the location whenever you start the server. The easiest way to do this is to use an option file, as described in section 2.2.1.3 Preparing the Windows MySQL Environment. - Finish the install process.
Important note:
Early alpha Windows distributions for MySQL 4.1 do not contain an
installer program. A 4.1 distribution is a Zip file that you just
unzip in the location where you want to install MySQL. For example,
to install `mysql-4.1.1-alpha-win.zip' as `C:\mysql', unzip
the distribution file on the C:
drive, then rename the resulting
`mysql-4.1.1-alpha' directory to `mysql'.
If you are upgrading to MySQL 4.1 from an earlier version, you will want to
preserve your existing `data' directory that contains the grant tables
in the mysql
database and your own databases. Before installing 4.1,
stop the server if it is running, and save your `data' directory to
another location. Then either rename the existing `C:\mysql' directory
or remove it. Install 4.1 as described in the preceding paragraph, and then
replace its `data' directory with your old `data' directory.
This will avoid the loss of your current databases.
Start the new server and update the grant tables.
See section 2.5.8 Upgrading the Grant Tables.
Please see section 2.2.1.8 Troubleshooting a MySQL Installation Under Windows if you encounter difficulties during installation.
2.2.1.3 Preparing the Windows MySQL Environment
If you need to specify startup options when you run the server, you can indicate them on the command line or place them in an option file. For options that will be used every time the server starts, you will find it most convenient to use an option file to specify your MySQL configuration. This is true particularly under the following circumstances:
- The installation or data directory locations are different from the default locations (`C:\mysql' and `C:\mysql\data').
-
You need to tune the server settings.
For example, to use the
InnoDB
transactional tables in MySQL 3.23, you must manually add some extra lines to the option file, as described in section 16.4InnoDB
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 configureInnoDB
explicitly. You may still do so if you wish, and an option file will be useful in this case, too.)
On Windows, the MySQL installer places the data directory directly under the directory where you install MySQL. If you would like to use a data directory in a different location, you should copy the entire contents of the `data' directory to the new location. For example, by default, the installer places MySQL in `C:\mysql' and the data directory in `C:\mysql\data'. If you want to use a data directory of `E:\mydata', you must do two things:
- Move the data directory from `C:\mysql\data' to `E:\mydata'.
-
Use a
--datadir
option to specify the new data directory location each time you start the server.
When the MySQL server starts on Windows, it looks for options in
two files: the `my.ini' file in the Windows directory, and
the `C:\my.cnf' file. The Windows directory typically is
named something like `C:\WINDOWS' or `C:\WinNT'. You
can determine its exact location from the value of the WINDIR
environment variable using the following command:
C:\> echo %WINDIR%
MySQL looks for options first in the `my.ini' file, then in
the `my.cnf' file. However, to avoid confusion, it's best if
you use only one file. If your PC uses a boot loader where the
C:
drive isn't the boot drive, your only option is to use
the `my.ini' file. Whichever option file you use, it must be a plain
text file.
An option file can be created and modified with any text editor,
such as 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.
Another way to manage an option file is to use the WinMySQLAdmin
tool. You can find WinMySQLAdmin
in the `bin' directory
of your MySQL installation, as well as a help file containing
instructions for using it. WinMySQLAdmin
has the capability
of editing your option file, but note these points:
-
WinMySQLAdmin
uses only the `my.ini' file. -
If
WinMySQLAdmin
finds a `C:\my.cnf' file, it will in fact rename it to `C:\my_cnf.bak' to disable it.
Now you are ready to start the server.
2.2.1.4 Selecting a Windows 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 |
@command{mysqld} | Compiled with full debugging and automatic memory allocation checking, symbolic links, and InnoDB and BDB tables.
|
@command{mysqld-opt} | Optimized binary. From version 4.0 on, InnoDB is enabled. Before 4.0, this server includes no transactional table support.
|
@command{mysqld-nt} | Optimized binary for Windows NT, 2000, and XP with support for named pipes. |
@command{mysqld-max} | Optimized binary with support for symbolic links, and InnoDB and BDB tables.
|
@command{mysqld-max-nt} | Like @command{mysqld-max}, but compiled with support for named pipes. |
We have found that the server with the most generic name
(@command{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 @command{mysqld-opt} is a better general-use
server choice to make instead if you don't need debugging suport
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 inadvertantly, some name changes were made from MySQL 4.1.2 to 4.1.4: @command{mysqld} has been renamed to @command{mysqld-debug} and @command{mysqld-opt} has been renamed to @command{mysqld}. Thus, the server that includes debugging support indicates that in its name, and the server named @command{mysqld} is an efficient default choice. The other servers still have their same names. The resulting servers are named like this:
Binary | Description |
@command{mysqld-debug} | Compiled with full debugging and automatic memory allocation checking, symbolic links, and InnoDB and BDB tables.
|
@command{mysqld} | Optimized binary with InnoDB support.
|
@command{mysqld-nt} | Optimized binary for Windows NT, 2000, and XP with support for named pipes. |
@command{mysqld-max} | Optimized binary with support for symbolic links, and InnoDB and BDB tables.
|
@command{mysqld-max-nt} | Like @command{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 @command{mysqld-debug} but not one named @command{mysqld}. In this case, you should have have a server @command{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.
MySQL supports TCP/IP on all Windows platforms. The @command{mysqld-nt}
and mysql-max-nt
servers support named pipes on NT, 2000, and XP.
However, the default is to use TCP/IP regardless of the platform.
(Named pipes are slower than TCP/IP in many Windows configurations.)
Named pipe use is subject to these conditions:
-
Starting from MySQL 3.23.50, named pipes are enabled only
if you start the server with the
--enable-named-pipe
option. It is now necessary to use this option explicitly because some users have experienced problems shutting down the MySQL server when named pipes were used. - Named pipe connections are allowed only by the @command{mysqld-nt} or @command{mysqld-max-nt} servers, and only if the server is run on a version of Windows that supports named pipes (NT, 2000, XP).
- These servers can be run on Windows 98 or Me, but only if TCP/IP is installed; named pipe connections cannot be used.
- On Windows 95, these servers cannot be used.
Note: Most of the examples in the following sections use @command{mysqld} as the server name. If you choose to use a different server, such as @command{mysqld-opt}, make the appropriate substitutions in the commands that are shown in the examples. One good reason to choose a different server is that because @command{mysqld} contains full debugging support, it uses more memory and runs slower than the other Windows servers.
2.2.1.5 Starting the Server for the First Time
On Windows 95, 98, or Me, MySQL clients always connect to the server using TCP/IP. (This will allow any machine on your network to connect to your MySQL server.) Because of this, you must make sure that TCP/IP support is installed on your machine before starting MySQL. You can find TCP/IP on your Windows CD-ROM.
Note that if you are using an old Windows 95 release (for example, OSR2), it's likely that you have an old Winsock package; MySQL requires Winsock 2! You can get the newest Winsock from http://www.microsoft.com/. Windows 98 has the new Winsock 2 library, so it is unnecessary to update the library.
On NT-based systems such as Windows NT, 2000, or XP, clients have two options. They can use TCP/IP, or they can use a named pipe if the server supports named pipe connections.
In MySQL 4.1 and up, Windows servers also support shared-memory connections
if started with the --shared-memory
option. Clients can connect
this way by using the --protocol=memory
option.
For information about which server binary to run, see section 2.2.1.4 Selecting a Windows Server.
This section gives a general overview of starting the MySQL server. The following sections provide more specific information for particular versions of Windows.
The examples in these sections assume that MySQL is installed under the default location of `C:\mysql'. Adjust the pathnames shown in the examples if you have MySQL installed in a different location.
Testing is best done from a command prompt in a console window (a ``DOS window''). This way you can have the server display status messages in the window where they are easy to see. If something is wrong with your configuration, these messages will make it easier for you to identify and fix any problems.
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 will continue to write to the console any further diagnostic output it produces. You can open a new console window in which to run client programs.
If you omit the --console
option, the server writes diagnostic output
to the error log in the data directory (`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.4 Post-Installation Setup and Testing.
2.2.1.6 Starting MySQL from the Windows Command Line
The MySQL server can be started manually from the command line. This can be done on any version of Windows.
To start the @command{mysqld} server from the command line, you should start a console window (a ``DOS window'') and enter this command:
C:\> C:\mysql\bin\mysqld
On non-NT versions of Windows, this will start @command{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, or XP, the server will run in the foreground and no command prompt will appear until the server exits. Because of this, you should open another console window to run client programs while the server is running.
You can stop the MySQL server by executing this command:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility @command{mysqladmin} to
connect to the server and tell it to shut down. The command connects
as root
, which is the default administrative account in the
MySQL grant system. Note that users in the MySQL grant system
are wholly independent from any login users under Windows.
If @command{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 @command{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 @command{mysqld} with
--standalone --debug
.
In this case, @command{mysqld} will write a log file
`C:\mysqld.trace' that should contain the reason why
@command{mysqld} doesn't start. See section D.1.2 Creating Trace Files.
Use @command{mysqld --help} to display all the options that @command{mysqld} understands!
2.2.1.7 Starting MySQL as a Windows Service
On the NT family (Windows NT, 2000, or XP), the recommended way to run MySQL
is to install it as a Windows service. Then Windows starts and stops the MySQL
server automatically when Windows starts and stops. A server installed as a
service can also be controlled from the command line using @command{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 or XP). It is advisable to close the Services
utility
while performing server installation or removal operations from this command
line. This prevents some odd errors.
To get MySQL to work with TCP/IP on Windows NT 4, you must install service pack 3 (or newer).
Before installing MySQL as a Windows service, you should first stop the current server if it is running by using the following command:
C:\> C:\mysql\bin\mysqladmin -u root shutdown
This invokes the MySQL administrative utility @command{mysqladmin} to
connect to the server and tell it to shut down. The command connects
as root
, which is the default administrative account in the
MySQL grant system. Note that users in the MySQL grant system
are wholly independent from any login users under Windows.
Now install the server as a service:
C:\> mysqld --install
If you have problems installing @command{mysqld} as a service using just the server name, try installing it using its full pathname:
C:\> C:\mysql\bin\mysqld --install
As of MySQL 4.0.2, you can specify a specific service name after the
--install
option. As of MySQL 4.0.3, you can in addition specify a
--defaults-file
option after the service name to indicate where the
server should obtain options when it starts. The rules that determine the
service name and option files the server uses are as follows:
-
If you specify no service name, the server uses the default service name of
MySQL
and the server reads options from the[mysqld]
group in the standard option files. -
If you specify a service name after the
--install
option, the server ignores the[mysqld]
option group and instead reads options from the group that has the same name as the service. The server reads options from the standard option files. -
If you specify a
--defaults-file
option after the service name, the server ignores the standard option files and reads options only from the[mysqld]
group of the named file.
Note: Prior to MySQL 4.0.17, a server installed as a Windows service has problems starting if its pathname or the service name contains spaces. For this reason, avoid installing MySQL in a directory such as `C:\Program Files' or using a service name containing spaces.
In the usual case that you install the server with --install
but no service name, the server is installed with a service
name of MySQL
.
As a more complex example, consider the following command:
C:\> C:\mysql\bin\mysqld --install mysql --defaults-file=C:\my-opts.cnf
Here, a service name is given after the --install
option. If no
--defaults-file
option had been given, this command would have the
effect of causing the server to read the [mysql]
group from the
standard option files. (This would be a bad idea, because that option group
is for use by the @command{mysql} client program.) However, because the
--defaults-file
option is present, the server reads options only from
the named file, and only from the [mysqld]
option group.
You can also specify options as ``Start parameters
'' in the
Windows Services
utility before you start the MySQL service.
Once a MySQL server is installed as a service, Windows will start
the service automatically whenever Windows starts. The service also
can be started immediately from the Services
utility, or by
using the command @command{NET START MySQL}. The @command{NET} command
is not case sensitive.
When run as a service, @command{mysqld} has no access to a console window, so no messages can be seen there. If @command{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'.
When @command{mysqld} is running as a service, it can be stopped by
using the Services
utility, the command @command{NET STOP
MySQL}, or the command @command{mysqladmin shutdown}. If the service
is running when Windows shuts down, Windows will stop the server
automatically.
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
had 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 @command{mysqladmin shutdown}.
This change to tell Windows to wait longer when stopping the MySQL server
works for Windows 2000 and XP. It does not work for Windows NT, where Windows
waits only 20 seconds for a service to shut down, and after that kills the
service process. You can increase this default by opening the Registry
Editor `\winnt\system32\regedt32.exe' and editing the value of
WaitToKillServiceTimeout
at
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
in the Registry tree. Specify the new larger value in milliseconds.
For example, the value 120000 tells Windows NT to wait up to 120 seconds.
If you don't want to start @command{mysqld} as a service, you can start it from the command line. For instructions, see section 2.2.1.6 Starting MySQL from the Windows Command Line.
Please see section 2.2.1.8 Troubleshooting a MySQL Installation Under Windows if you encounter difficulties during installation.
2.2.1.8 Troubleshooting a MySQL Installation Under Windows
When installing and running MySQL for the first time, you may encounter certain errors that prevent the MySQL server from starting. The purpose of this section is to help you diagnose and correct some of these errors.
Your first resource when troubleshooting server issues is the error log. The MySQL server uses the error log to record information relevant to the error that 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 @command{NET START mysql} command from the command line after installing @command{mysqld} as a service to see any error messages regarding the starting of the MySQL server as a service. See section 2.2.1.7 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 will
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.2.1.3 Preparing the Windows MySQL Environment.
2.2.1.9 Running MySQL Client Programs on Windows
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 @command{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 @command{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 should use the --protocol=PIPE
option.
There are two versions of the MySQL command-line tool:
Binary | Description |
@command{mysql} | Compiled on native Windows, offering limited text editing capabilities. |
@command{mysqlc} | Compiled with the Cygnus GNU compiler and libraries, which offers readline editing.
|
If you want to use @command{mysqlc}, you must have a copy of the
`cygwinb19.dll' library installed somewhere that @command{mysqlc}
can find it. Current distributions of MySQL include this library
in the same directory as @command{mysqlc} (the `bin' directory
under the base directory of your MySQL installation). If your
distribution does not have the cygwinb19.dll
library in the
`bin' directory, look for it in the lib
directory and
copy it to your Windows system directory
(`\Windows\system' or a similar place).
2.2.1.10 MySQL on Windows Compared to MySQL on Unix
MySQL for Windows has by now proven itself to be very stable. The Windows version of MySQL has the same features as the corresponding Unix version, with the following exceptions:
- Windows 95 and threads
- Windows 95 leaks about 200 bytes of main memory for each thread creation. Each connection in MySQL creates a new thread, so you shouldn't run @command{mysqld} for an extended time on Windows 95 if your server handles many connections! Other versions of Windows don't suffer from this bug.
- Limited number of ports
- Windows systems have about 4,000 ports available for client connections, and after a connection on a port closes, it takes two to four minutes before the port can be reused. In situations where clients connect to and disconnect from the server at a high rate, it is possible for all available ports to be used up before closed ports become available again. If this happens, the MySQL server will appear to have become unresponsive even though it is running. Note that ports may be used by other applications running on the machine as well, in which case the number of ports available to MySQL is lower. For more information, see http://support.microsoft.com/default.aspx?scid=kb;en-us;196271.
- Concurrent reads
-
MySQL depends on the
pread()
andpwrite()
calls to be able to mixINSERT
andSELECT
. Currently we use mutexes to emulatepread()
/pwrite()
. We will, in the long run, replace the file level interface with a virtual interface so that we can use thereadfile()
/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 will not be able to run as many concurrent threads on NT, 2000, and XP as on Unix. - Blocking read
-
MySQL uses a blocking read for each connection, which has the following
implications if named pipe connections are enabled:
- A connection will not be disconnected automatically after eight hours, as happens with the Unix version of MySQL.
- If a connection hangs, it's impossible to break it without killing MySQL.
- @command{mysqladmin kill} will not work on a sleeping connection.
- @command{mysqladmin shutdown} can't abort as long as there are sleeping connections.
ALTER TABLE
-
While you are executing an
ALTER TABLE
statement, the table is locked from being used by other threads. This has to do with the fact that on Windows, you can't delete a file that is in use by another thread. In the future, we may find some way to work around this problem. DROP TABLE
-
DROP TABLE
on a table that is in use by aMERGE
table will not work on Windows because theMERGE
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 allMERGE
tables (withFLUSH TABLES
) or drop theMERGE
table before dropping the table. We will fix this at the same time we introduce views. DATA DIRECTORY
andINDEX DIRECTORY
-
The
DATA DIRECTORY
andINDEX DIRECTORY
options forCREATE TABLE
are ignored on Windows, because Windows doesn't support symbolic links. These options also are ignored on systems that have a non-functionalrealpath()
call. DROP DATABASE
- You cannot drop a database that is in use by some thread.
- Killing MySQL from the Task Manager
- You cannot kill MySQL from the Task Manager or with the shutdown utility in Windows 95. You must take it down with @command{mysqladmin shutdown}.
- Case-insensitive names
- Filenames are not case sensitive on Windows, so MySQL database and table names are also not case sensitive on Windows. The only restriction is that database and table names must be specified using the same case throughout a given statement. See section 10.2.2 Identifier Case Sensitivity.
- The `\' pathname separator character
-
Pathname components in Windows 95 are separated by the `\' character,
which is also the escape character in MySQL. If you are using
LOAD DATA INFILE
orSELECT ... INTO OUTFILE
, use Unix-style filenames with `/' characters:mysql> LOAD DATA INFILE 'C:/tmp/skr.txt' INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:/tmp/skr.txt' FROM skr;
Alternatively, you must double the `\' character:mysql> LOAD DATA INFILE 'C:\\tmp\\skr.txt' INTO TABLE skr; mysql> SELECT * INTO OUTFILE 'C:\\tmp\\skr.txt' FROM skr;
- Problems with pipes.
-
Pipes do not work reliably from the Windows command-line prompt. If the
pipe includes the character
^Z
/CHAR(24)
, Windows will think it has encountered end-of-file and abort the program. This is mainly a problem when you try to apply a binary log as follows:C:\> mysqlbinlog binary-log-name | mysql --user=root
If you have a problem applying the log and suspect that it is because of a^Z
/CHAR(24)
character, you can use the following workaround:C:\> mysqlbinlog binary-log-file --result-file=/tmp/bin.sql C:\> mysql --user=root --execute "source /tmp/bin.sql"
The latter command also can be used to reliably read in any SQL file that may contain binary data. Can't open named pipe
error-
If you use a MySQL 3.22 server on Windows NT with the newest MySQL client
programs, you will get the following error:
error 2017: can't open named pipe to host: . pipe...
This happens because the release version of MySQL uses named pipes on NT by default. You can avoid this error by using the--host=localhost
option to the new MySQL clients or by creating an option file `C:\my.cnf' that contains the following information:[client] host = localhost
Starting from 3.23.50, named pipes are enabled only if @command{mysqld-nt} or @command{mysqld-max-nt} is started with--enable-named-pipe
. Access denied for user
error-
If you attempt to run a MySQL client program to connect to a server
running on the same machine, but get the error
Access denied for user 'some-user'@'unknown' to database 'mysql'
, this means that MySQL 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:
- Add some nice start and shutdown icons to the MySQL installation.
- It would be really nice to be able to kill @command{mysqld} from the Task Manager in Windows 95. For the moment, you must use @command{mysqladmin shutdown}.
-
Port
readline
to Windows for use in the @command{mysql} command-line tool. - GUI versions of the standard MySQL clients (@command{mysql}, @command{mysqlshow}, @command{mysqladmin}, and @command{mysqldump}) would be nice.
- It would be nice if the socket read and write functions in `net.c' were interruptible. This would make it possible to kill open threads with @command{mysqladmin kill} on Windows.
- Add macros to use the faster thread-safe increment/decrement methods provided by Windows.
2.2.2 Installing MySQL on Linux
The recommended way to install MySQL on Linux is by using the RPM
packages. The MySQL RPMs are currently built on a SuSE Linux 7.3
system, but should work on most versions of Linux that support @command{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.6.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.
@xref{mysqld-max, , @command{mysqld-max}}.
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 will need this unless you only want to connect to a MySQL server running on another machine. Note: Server RPM files were calledMySQL-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 theMySQL-server
RPM does not. You must install theMySQL-server
RPM first, because theMySQL-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 theDBD::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 ofMySQL-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
already 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.4.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 already 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
@command{mysqld} server should be up and running after installation.
You should now be able to start using MySQL.
If something goes wrong, you can find more information in the binary installation section. See section 2.2.5 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.4 Post-Installation Setup and Testing.
2.2.3 Installing MySQL on Mac OS X
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 @command{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 will guide 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 will install itself into
`/usr/local/mysql-VERSION' and will also install a symbolic link,
`/usr/local/mysql', pointing to the new location. If a directory named
`/usr/local/mysql' already exists, it will be renamed to
`/usr/local/mysql.bak' first. Additionally, the installer will create the
grant tables in the mysql
database by executing @command{mysql_install_db}
after the installation.
The installation layout is similar to that of a @command{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 already 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 @command{mysqld} with @command{safe_mysqld} instead of @command{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.5.8 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 will be 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 an already 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 now 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.4 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 @command{mysql} and @command{mysqladmin} from the command line. The syntax for @command{tcsh} is:
alias mysql /usr/local/mysql/bin/mysql alias mysqladmin /usr/local/mysql/bin/mysqladmin
For @command{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 @command{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'.
2.2.4 Installing MySQL on NetWare
Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers will 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:
- NetWare 6.5 Support Pack 2 installed and updated with the latest LibC, or NetWare 6.0 with Support Pack 4 installed and updated with the latest LibC. NetWare 6.5 Support Pack 2 and other updates are available at http://support.novell.com/filefinder/18197/index.html. NetWare 6.0 Support Pack 4 and other updates are available at http://support.novell.com/filefinder/13659/index.html. The latest LibC is available at http://developer.novell.com/ndk/libc.htm. Steps to update LibC can be found here: http://developer.novell.com/ndk/doc/libc/index.html?page=/ndk/doc/libc/libc_enu/data/ajjl0r0.html
- The system must meet Novell's minimum requirements to run the respective version of NetWare.
- MySQL data, as well as the binaries themselves, must be installed on an NSS volume; traditional volumes are not supported.
To install MySQL for NetWare, use the following procedure:
-
If you are upgrading from a prior installation, stop the MySQL server.
This is done from the server console, using the following command:
SERVER: mysqladmin -u root shutdown
- Log on to the target server from a client machine with access to the location where you will install MySQL.
- Extract the binary package Zip file onto the server. Be sure to allow the paths in the Zip file to be used. It is safe to simply extract the file to `SYS:\'. If you are upgrading from a prior installation, you may need to copy the data directory (for example, `SYS:MYSQL\DATA') now, as well as `my.cnf', if you have customized it. You can then delete the old copy of MySQL.
- You might want to rename the directory to something more consistent and easy to use. We recommend using `SYS:MYSQL'; examples in this manual use this name to refer to the installation directory in general.
-
At the server console, add a search path for the directory containing the
MySQL NLMs. For example:
SERVER: SEARCH ADD SYS:MYSQL\BIN
- Initialize the data directory and the grant tables, if needed, by executing @command{mysql_install_db} at the server console.
- Start the MySQL server using @command{mysqld_safe} at the server console.
-
To finish the installation, you should also add the following commands to
autoexec.ncf
. For example, if your MySQL installation is in `SYS:MYSQL' and you want MySQL to start automatically, you could add these lines:#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE
If you are running MySQL on NetWare 6.0, we strongly suggest that you use the--skip-external-locking
option on the command line:#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --skip-external-locking
It will also be necessary to useCHECK TABLE
andREPAIR TABLE
instead of @command{myisamchk}, because @command{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. @command{mysqld_safe} on NetWare provides a screen presence. When you unload (shut down) the @command{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 @command{mysqld_safe}. For example:#Starts the MySQL 4.0.x database server SEARCH ADD SYS:MYSQL\BIN MYSQLD_SAFE --autoclose
- The latest Netware Perl and PHP modules for MySQL can be downloaded from http://developer.novell.com/ndk/perl5.htm and http://developer.novell.com/ndk/php2.htm respectively.
The behavior of @command{mysqld_safe} on NetWare is described further in @ref{mysqld_safe, , @command{mysqld_safe}}.
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.4 Post-Installation Setup and Testing.
2.2.5 Installing MySQL on Other Unix-Like Systems
This section covers the installation of MySQL binary distributions that are
provided for various platforms in the form of compressed @command{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 @command{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 @command{tar} file binary distribution:
-
GNU
gunzip
to uncompress the distribution. - A reasonable @command{tar} to unpack the distribution. GNU @command{tar} is known to work. Some operating systems come with a pre-installed version of @command{tar} that is known to have problems. For example, Mac OS X @command{tar} and Sun @command{tar} are known to have problems with long filenames. On Mac OS X, you can use the pre-installed @command{gnutar} program. On other systems with a deficient @command{tar}, you should install GNU @command{tar} first.
If you run into problems, please always use @command{mysqlbug} when posting questions to a MySQL mailing list. Even if the problem isn't a bug, @command{mysqlbug} gathers system information that will help others solve your problem. By not using @command{mysqlbug}, you lessen the likelihood of getting a solution to your problem. You will find @command{mysqlbug} in the `bin' directory after you unpack the distribution. See section 1.7.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 @command{bin/safe_mysqld} for @command{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.4 Post-Installation Setup and Testing.
A more detailed version of the preceding description for installing a binary distribution follows:
-
Add a login user and group for @command{mysqld} to run as:
shell> groupadd mysql shell> useradd -g mysql mysql
These commands add themysql
group and themysql
user. The syntax for @command{useradd} and @command{groupadd} may differ slightly on different versions of Unix. They may also be called @command{adduser} and @command{addgroup}. You might want to call the user and group something else instead ofmysql
. If so, substitute the appropriate name in the following steps. -
Pick the directory under which you want to unpack the distribution, and
change location into it. In the following example, we unpack the
distribution under `/usr/local'. (The instructions, therefore, assume
that you have permission to create files and directories in
`/usr/local'. If that directory is protected, you will need to perform
the installation as
root
.)shell> cd /usr/local
- Obtain a distribution file from one of the sites listed in section 2.1.3 How to Get MySQL. For a given release, binary distributions for all platforms are built from the same MySQL source distribution.
-
Unpack the distribution, which will create the installation directory.
Then create a symbolic link to that directory:
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf - shell> ln -s full-path-to-mysql-VERSION-OS mysql
The @command{tar} command creates a directory named `mysql-VERSION-OS'. Theln
command makes a symbolic link to that directory. This lets you refer more easily to the installation directory as `/usr/local/mysql'. With GNU @command{tar}, no separate invocation ofgunzip
is necessary. You can replace the first line with the following alternative command to uncompress and extract the distribution:shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
-
Change location into the installation directory:
shell> cd mysql
You will find several files and subdirectories in themysql
directory. The most important for installation purposes are the `bin' and `scripts' subdirectories.- `bin'
-
This directory contains client programs and the server.
You should add the full pathname of this directory to your
PATH
environment variable so that your shell finds the MySQL programs properly. See section E Environment Variables. - `scripts'
-
This directory contains the @command{mysql_install_db} script used to initialize
the
mysql
database containing the grant tables that store the server access permissions.
-
If you haven't installed MySQL before, you must create the MySQL grant tables:
shell> scripts/mysql_install_db --user=mysql
If you run the command asroot
, 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, @command{mysql_install_db} left the server running after creating the grant tables. This is no longer true; you will need to restart the server after performing the remaining steps in this procedure. -
Change the ownership of program binaries to
root
and ownership of the data directory to the user that you will run @command{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 theroot
user. The second changes the owner attribute of the data directory to themysql
user. The third changes the group attribute to themysql
group. -
If you would like MySQL to start automatically when you boot your
machine, you can copy
support-files/mysql.server
to the location where your system has its startup files. More information can be found in thesupport-files/mysql.server
script itself and in section 2.4.2.2 Starting and Stopping MySQL Automatically. -
You can set up new accounts using the @command{bin/mysql_setpermission} script if
you install the
DBI
andDBD::mysql
Perl modules. For instructions, see section 2.7 Perl Installation Notes. -
If you would like to use @command{mysqlaccess} and have the MySQL
distribution in some non-standard place, you must change the location where
@command{mysqlaccess} expects to find the @command{mysql} client. Edit the
`bin/mysqlaccess' script at approximately line 18. Search for a line
that looks like this:
$MYSQL = '/usr/local/bin/mysql'; # path to mysql executable
Change the path to reflect the location wheremysql
actually is stored on your system. If you do not do this, you will get aBroken pipe
error when you run @command{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 @command{bin/safe_mysqld} for @command{bin/mysqld_safe} in the command.
More information about @command{mysqld_safe} is given in @ref{mysqld_safe, , @command{mysqld_safe}}.
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.4 Post-Installation Setup and Testing.
2.3 MySQL Installation Using a Source Distribution
Before you proceed with the source installation, check first to see whether our binary is available for your platform and whether it will work 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 @command{tar}
archives and have names of the form `mysql-VERSION.tar.gz', where
VERSION is a number like 4.1.7
.
You need the following tools to build and install MySQL from source:
-
GNU
gunzip
to uncompress the distribution. - A reasonable @command{tar} to unpack the distribution. GNU @command{tar} is known to work. Some operating systems come with a pre-installed version of @command{tar} that is known to have problems. For example, Mac OS X @command{tar} and Sun @command{tar} are known to have problems with long filenames. On Mac OS X, you can use the pre-installed @command{gnutar} program. On other systems with a deficient @command{tar}, you should install GNU @command{tar} first.
-
A working ANSI C++ compiler. @command{gcc} 2.95.2 or later, @command{egcs} 1.0.2
or later or @command{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 @command{gcc}. @command{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 @command{gcc} 2.7.x, you must upgrade your @command{gcc} to be able to compile MySQL. @command{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. @command{gcc} 2.95.2 or later is recommended when compiling MySQL 3.23.x. - A good @command{make} program. GNU @command{make} is always recommended and is sometimes required. If you have problems, we recommend trying GNU @command{make} 3.75 or newer.
If you are using a version of @command{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 will give you a fast and stable binary.
If you run into problems, please always use @command{mysqlbug} when posting questions to a MySQL mailing list. Even if the problem isn't a bug, @command{mysqlbug} gathers system information that will help others solve your problem. By not using @command{mysqlbug}, you lessen the likelihood of getting a solution to your problem. You will find @command{mysqlbug} in the `scripts' directory after you unpack the distribution. See section 1.7.1.3 How to Report Bugs or Problems.
2.3.1 Source Installation Overview
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 @command{bin/safe_mysqld} for @command{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 will make a binary RPM that you can install. For older versions of RPM, you may have to replace the command @command{rpmbuild} with @command{rpm} instead.
Note: This procedure does not set up any passwords for MySQL accounts. After following the procedure, proceed to section 2.4 Post-Installation Setup and Testing, for post-installation setup and testing.
A more detailed version of the preceding description for installing MySQL from a source distribution follows:
-
Add a login user and group for @command{mysqld} to run as:
shell> groupadd mysql shell> useradd -g mysql mysql
These commands add themysql
group and themysql
user. The syntax for @command{useradd} and @command{groupadd} may differ slightly on different versions of Unix. They may also be called @command{adduser} and @command{addgroup}. You might want to call the user and group something else instead ofmysql
. If so, substitute the appropriate name in the following steps. - Pick the directory under which you want to unpack the distribution, and change location into it.
- Obtain a distribution file from one of the sites listed in section 2.1.3 How to Get MySQL.
-
Unpack the distribution into the current directory:
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -
This command creates a directory named `mysql-VERSION'. With GNU @command{tar}, no separate invocation ofgunzip
is necessary. You can use the following alternative command to uncompress and extract the distribution:shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
-
Change location into the top-level directory of the unpacked distribution:
shell> cd mysql-VERSION
Note that currently you must configure and build MySQL from this top-level directory. You cannot build it in a different directory. -
Configure the release and compile everything:
shell> ./configure --prefix=/usr/local/mysql shell> make
When you run @command{configure}, you might want to specify some options. Run @command{./configure --help} for a list of options. @ref{configure options, , @command{configure} options}, discusses some of the more useful options. If @command{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 @command{configure}. Post the bug report using the @command{mysqlbug} script. See section 1.7.1.3 How to Report Bugs or Problems. If the compile fails, see section 2.3.4 Dealing with Problems Compiling MySQL for help. -
Install the distribution:
shell> make install
If you want to set up an option file, use one of those present in the `support-files' directory as a template. For example:shell> cp support-files/my-medium.cnf /etc/my.cnf
You might need to run these commands asroot
. If you want to configure support forInnoDB
tables, you should edit the/etc/my.cnf
file, remove the#
character before the option lines that start withinnodb_...
, and modify the option values to be what you want. See section 4.3.2 Using Option Files and section 16.4InnoDB
Configuration. -
Change location into the installation directory:
shell> cd /usr/local/mysql
-
If you haven't installed MySQL before, you must create the MySQL grant tables:
shell> bin/mysql_install_db --user=mysql
If you run the command asroot
, 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, @command{mysql_install_db} left the server running after creating the grant tables. This is no longer true; you will need to restart the server after performing the remaining steps in this procedure. -
Change the ownership of program binaries to
root
and ownership of the data directory to the user that you will run @command{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 theroot
user. The second changes the owner attribute of the data directory to themysql
user. The third changes the group attribute to themysql
group. -
If you would like MySQL to start automatically when you boot your
machine, you can copy
support-files/mysql.server
to the location where your system has its startup files. More information can be found in thesupport-files/mysql.server
script itself and in section 2.4.2.2 Starting and Stopping MySQL Automatically. -
You can set up new accounts using the @command{bin/mysql_setpermission} script if
you install the
DBI
andDBD::mysql
Perl modules. For instructions, see section 2.7 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 @command{safe_mysqld} for @command{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 @command{mysqld_safe} is given in @ref{mysqld_safe, , @command{mysqld_safe}}.
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.4 Post-Installation Setup and Testing.
2.3.2 Typical @command{configure} Options
The @command{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 @command{configure} command line. You can also affect @command{configure} using certain environment variables. See section E Environment Variables. For a list of options supported by @command{configure}, run this command:
shell> ./configure --help
Some of the more commonly used @command{configure} options are described here:
-
To compile just the MySQL client libraries and client programs and
not the server, use the
--without-server
option:shell> ./configure --without-server
If you don't have a C++ compiler, @command{mysql} will not compile (it is the one client program that requires C++). In this case, you can remove the code in @command{configure} that tests for the C++ compiler and then run @command{./configure} with the--without-server
option. The compile step will still try to build @command{mysql}, but you can ignore any warnings about `mysql.cc'. (If @command{make} stops, try @command{make -k} to tell it to continue with the rest of the build even if errors occur.) -
If you want to build the embedded MySQL library (
libmysqld.a
) you should use the--with-embedded-server
option. -
If you don't want your log files and database directories located under
`/usr/local/var', use a @command{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. -
If you are using Unix and you want the MySQL socket located somewhere
other than the default location (normally in the directory `/tmp' or
`/var/run'), use a @command{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'. -
If you want to compile statically linked programs (for example, to make a
binary distribution, to get more speed, or to work around problems with some
Red Hat Linux distributions), run @command{configure} like this:
shell> ./configure --with-client-ldflags=-all-static \ --with-mysqld-ldflags=-all-static
-
If you are using @command{gcc} and don't have
libg++
orlibstdc++
installed, you can tell @command{configure} to use @command{gcc} as your C++ compiler:shell> CC=gcc CXX=gcc ./configure
When you use @command{gcc} as your C++ compiler, it will not attempt to link inlibg++
orlibstdc++
. 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.- @command{gcc 2.7.2:}
-
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"
- @command{egcs 1.0.3a:}
-
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors \ -fno-exceptions -fno-rtti"
- @command{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"
--prefix=/usr/local/mysql --enable-assembler \ --with-mysqld-ldflags=-all-static
The full @command{configure} line would, in other words, be something like the following for all recent @command{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-static
The 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 @command{configure}. In this case, @command{configure} will not build a shared `libmysqlclient.so.#' library. -
By default, MySQL uses the
latin1
(ISO-8859-1) character set. To change the default set, use the--with-charset
option:shell> ./configure --with-charset=CHARSET
CHARSET may be one ofbig5
,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
, orwin1251ukr
. 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 thelatin1_swedish_ci
collation. To change this, use the--with-collation
option:shell> ./configure --with-collation=COLLATION
To change both the character set and the collation, use both the--with-charset
and--with-collation
options. The collation must be a legal collation for the character set. (Use theSHOW 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 theSET CHARACTER SET
statement. See section 14.5.3.1SET
Syntax. Warning: If you change character sets after having created any tables, you will have to run @command{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 @command{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, orall
to include all character sets into the binaries. -
To configure MySQL with debugging code, use the
--with-debug
option:shell> ./configure --with-debug
This causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. See section D.1 Debugging a MySQL Server. -
If your client programs are using threads, you also must compile a
thread-safe version of the MySQL client library with the
--enable-thread-safe-client
configure option. This will create alibmysqlclient_r
library with which you should link your threaded applications. See section 21.2.14 How to Make a Threaded Client. - Options that pertain to particular systems can be found in the system-specific section of this manual. See section 2.6 Operating System-Specific Notes.
2.3.3 Installing from the Development Source Tree
Caution: You should read this section only if you are interested in helping us test our new code. If you just want to get MySQL up and running on your system, you should use a standard release distribution (either a binary or source distribution will do).
To obtain our most recent development source tree, use these instructions:
- Download BitKeeper from http://www.bitmover.com/cgi-bin/download.cgi. You will need Bitkeeper 3.0 or newer to access our repository.
- Follow the instructions to install it.
-
After BitKeeper has been installed, first go to the directory you
want to work from, and then use one of the following commands to clone
the MySQL version branch of your choice:
To clone the old 3.23 branch, use this command:
shell> bk clone bk://mysql.bkbits.net/mysql-3.23 mysql-3.23
To clone the 4.0 stable (production) branch, use this command:shell> bk clone bk://mysql.bkbits.net/mysql-4.0 mysql-4.0
To clone the 4.1 gamma branch, use this command:shell> bk clone bk://mysql.bkbits.net/mysql-4.1 mysql-4.1
To clone the 5.0 development branch, use this command:shell> bk clone bk://mysql.bkbits.net/mysql-5.0 mysql-5.0
In the preceding examples, the source tree will be 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 variablehttp_proxy
to point to your proxy:shell> export http_proxy="http://your.proxy.server:8080/"
Now, simply replace thebk://
withhttp://
when doing a clone. Example:shell> bk clone http://mysql.bkbits.net/mysql-4.1 mysql-4.1
The initial download of the source tree may take a while, depending on the speed of your connection. Please be patient. -
You will need GNU @command{make}, @command{autoconf} 2.53 (or newer),
@command{automake} 1.5, @command{libtool} 1.5, and @command{m4} to run the next
set of commands. Even though many operating systems already come with their
own implementation of @command{make}, chances are high that the compilation
will fail with strange error messages. Therefore, it is highly recommended
that you use GNU @command{make} (sometimes named @command{gmake}) instead.
Fortunately, a large number of operating systems already ship with the GNU
toolchain preinstalled or supply installable packages of these. In any case,
they can also be downloaded from the following locations:
- http://www.gnu.org/software/autoconf/
- http://www.gnu.org/software/automake/
- http://www.gnu.org/software/libtool/
- http://www.gnu.org/software/m4/
- http://www.gnu.org/software/make/
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded
Note: The maximum table size is not actually exceeded; the error is caused by bugs in older versions of @command{bison}. Versions of MySQL before version 4.1 may also compile with other @command{yacc} implementations (for example, BSD @command{yacc} 91.7.30). For later versions, GNU @command{bison} is required. The following example shows the typical commands required to configure a source tree. The firstcd
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 make
The command lines that change directory into the `innobase' and `bdb/dist' directories are used to configure theInnoDB
and Berkeley DB (BDB
) storage engines. You can omit these command lines if you to not requireInnoDB
orBDB
support. If you get some strange errors during this stage, verify that you really have @command{libtool} installed. A collection of our standard configuration scripts is located in the `BUILD/' subdirectory. You may find it more convenient to use the `BUILD/compile-pentium-debug' script than the preceding set of shell commands. To compile on a different architecture, modify the script by removing flags that are Pentium-specific. -
When the build is done, run @command{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 @command{./configure} with different values for the
--prefix
,--with-tcp-port
, and--unix-socket-path
options than those used for your production server. - Play hard with your new installation and try to make the new features crash. Start by running @command{make test}. See section 24.1.2 MySQL Test Suite.
-
If you have gotten to the @command{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 acommand not found
error or a similar problem, do not report it. Instead, make sure that all the necessary tools are installed and that yourPATH
variable is set correctly so that your shell can find them. -
After the initial
bk clone
operation to obtain the source tree, you should runbk pull
periodically to get updates. -
You can examine the change history for the tree with all the diffs by using
bk revtool
. If you see some funny diffs or code that you have a question about, do not hesitate to send email to the MySQLinternals
mailing list. See section 1.7.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
will produce 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. -
BitKeeper has a nice help utility that you can access via
bk helptool
. -
Please note that any commits (made via
bk ci
orbk citool
) will trigger 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 will not allowbk push
), but rather use thebk 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
2.3.4 Dealing with Problems Compiling MySQL
All MySQL programs compile cleanly for us with no warnings on Solaris or Linux using @command{gcc}. On other systems, warnings may occur due to differences in system include files. See section 2.3.5 MIT-pthreads Notes for warnings that may occur when using MIT-pthreads. For other problems, check the following list.
The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of the following:
- If @command{configure} is run after it already has been run, it may use information that was gathered during its previous invocation. This information is stored in `config.cache'. When @command{configure} starts up, it looks for that file and reads its contents if it exists, on the assumption that the information is still correct. That assumption is invalid when you reconfigure.
- Each time you run @command{configure}, you must run @command{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 @command{configure}:
shell> rm config.cache shell> make clean
Alternatively, you can run @command{make distclean}.
The following list describes some of the problems when compiling MySQL that have been found to occur most often:
-
If you get errors such as the ones shown here when compiling
`sql_yacc.cc', you probably have run out of memory or swap space:
Internal compiler error: program cc1plus got fatal signal 11 Out of virtual memory Virtual memory exhausted
The problem is that @command{gcc} requires a huge amount of memory to compile `sql_yacc.cc' with inline functions. Try running @command{configure} with the--with-low-memory
option:shell> ./configure --with-low-memory
This option causes-fno-inline
to be added to the compile line if you are using @command{gcc} and-O0
if you are using something else. You should try the--with-low-memory
option even if you have so much memory and swap space that you think you can't possibly have run out. This problem has been observed to occur even on systems with generous hardware configurations and the--with-low-memory
option usually fixes it. -
By default, @command{configure} picks @command{c++} as the compiler name and
GNU @command{c++} links with
-lg++
. If you are using @command{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 @command{g++},libg++
, orlibstdc++
. One cause of these problems is that you may not have @command{g++}, or you may have @command{g++} but notlibg++
, orlibstdc++
. 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 @command{gcc} as your C++ compiler. Try setting the environment variableCXX
to"gcc -O3"
. For example:shell> CXX="gcc -O3" ./configure
This works because @command{gcc} compiles C++ sources as well as @command{g++} does, but does not link inlibg++
orlibstdc++
by default. Another way to fix these problems is to install @command{g++},libg++
, andlibstdc++
. We would, however, like to recommend that you not uselibg++
orlibstdc++
with MySQL because this will only increase the binary size of @command{mysqld} without giving you any benefits. Some versions of these libraries have also caused strange problems for MySQL users in the past. Using @command{gcc} as the C++ compiler is also required if you want to compile MySQL with RAID functionality (see section 14.2.6CREATE TABLE
Syntax for more info on RAID table type) and you are using GNU @command{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 @command{gcc} as your C++ compiler by defining theCXX
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
-
If your compile fails with errors such as any of the following,
you must upgrade your version of @command{make} to GNU @command{make}:
making all in mit-pthreads make: Fatal error in reader: Makefile, line 18: Badly formed macro assignment
Or:make: file `Makefile' line 18: Must be a separator (:
Or:pthread.h: No such file or directory
Solaris and FreeBSD are known to have troublesome @command{make} programs. GNU @command{make} Version 3.75 is known to work. -
If you want to define flags to be used by your C or C++ compilers, do so by
adding the flags to the
CFLAGS
andCXXFLAGS
environment variables. You can also specify the compiler names this way usingCC
andCXX
. For example:shell> CC=gcc shell> CFLAGS=-O3 shell> CXX=gcc shell> CXXFLAGS=-O3 shell> export CC CFLAGS CXX CXXFLAGS
See 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. -
If you get an error message like this,
you need to upgrade your @command{gcc} compiler:
client/libmysql.c:273: parse error before `__attribute__'
@command{gcc} 2.8.1 is known to work, but we recommend using @command{gcc} 2.95.2 or @command{egcs} 1.0.3a instead. -
If you get errors such as those shown here when compiling @command{mysqld},
@command{configure} didn't correctly detect the type of the last argument to
accept()
,getsockname()
, orgetpeername()
: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 @command{configure}). Look for these lines:/* Define as the base type of the last arg to accept */ #define SOCKET_SIZE_TYPE XXX
ChangeXXX
tosize_t
orint
, depending on your operating system. (Note that you will have to do this each time you run @command{configure} because @command{configure} regenerates `config.h'.) -
The `sql_yacc.cc' file is generated from `sql_yacc.yy'. Normally
the build process doesn't need to create `sql_yacc.cc', because
MySQL comes with an already generated copy. However, if you do need
to re-create it, you might encounter this error:
"sql_yacc.yy", line xxx fatal: default action causes potential...
This is a sign that your version of @command{yacc} is deficient. You probably need to install @command{bison} (the GNU version of @command{yacc}) and use that instead. -
On Debian Linux 3.0, you need to install
gawk
instead of the defaultmawk
if you want to compile MySQL 4.1 or higher with Berkeley DB support. -
If you need to debug @command{mysqld} or a MySQL client, run
@command{configure} with the
--with-debug
option, then recompile and link your clients with the new client library. See section D.2 Debugging a MySQL Client. -
If you get a compilation error on Linux (for example, SuSE Linux 8.1 or Red Hat
Linux 7.3) similar to the following one:
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from incompatible pointer type libmysql.c:1329: too few arguments to function `gethostbyname_r' libmysql.c:1329: warning: assignment makes pointer from integer without a cast make[2]: *** [libmysql.lo] Error 1
By default, the @command{configure} script attempts to determine the correct number of arguments by using @command{g++} the GNU C++ compiler. This test yields wrong results if @command{g++} is not installed. There are two ways to work around this problem:-
Make sure that the GNU C++ @command{g++} is installed. On some Linux
distributions, the required package is called
gpp
; on others, it is named @command{gcc-c++}. -
Use @command{gcc} as your C++ compiler by setting the
CXX
environment variable to @command{gcc}:export CXX="gcc"
-
Make sure that the GNU C++ @command{g++} is installed. On some Linux
distributions, the required package is called
2.3.5 MIT-pthreads Notes
This section describes some of the issues involved in using MIT-pthreads.
On Linux, you should not use MIT-pthreads. Use the installed LinuxThreads implementation instead. See section 2.6.1 Linux Notes.
If your system does not provide native thread support, you will 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 will create a new subdirectory named
mit-pthreads
.
-
On most systems, you can force MIT-pthreads to be used by running
@command{configure} with the
--with-mit-threads
option:shell> ./configure --with-mit-threads
Building in a non-source directory is not supported when using MIT-pthreads because we want to minimize our changes to this code. -
The checks that determine whether to use MIT-pthreads occur only
during the part of the configuration process that deals with the server
code. If you have configured the distribution using
--without-server
to build only the client code, clients will not know whether MIT-pthreads is being used and will use Unix socket connections by default. Because Unix socket files do not work under MIT-pthreads on some platforms, this means you will need to use-h
or--host
when you run client programs. -
When MySQL is compiled using MIT-pthreads, system locking is
disabled by default for performance reasons. You can tell the server to use
system locking with the
--external-locking
option. This is needed only if you want to be able to run two MySQL servers against the same data files, which is not recommended. -
Sometimes the pthread
bind()
command fails to bind to a socket without any error message (at least on Solaris). The result is that all connections to the server fail. For example:shell> mysqladmin version mysqladmin: connect to server at '' failed; error: 'Can't connect to mysql server on localhost (146)'
The solution to this is to kill the @command{mysqld} server and restart it. This has only happened to us when we have forced down the server and done a restart immediately. -
With MIT-pthreads, the
sleep()
system call isn't interruptible withSIGINT
(break). This is only noticeable when you run @command{mysqladmin --sleep}. You must wait for thesleep()
call to terminate before the interrupt is served and the process stops. -
When linking, you may receive warning messages like these (at least on
Solaris); they can be ignored:
ld: warning: symbol `_iob' has differing sizes: (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4; file /usr/lib/libc.so value=0x140); /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken ld: warning: symbol `__iob' has differing sizes: (file /my/local/pthreads/lib/libpthread.a(findfp.o) value=0x4; file /usr/lib/libc.so value=0x140); /my/local/pthreads/lib/libpthread.a(findfp.o) definition taken
-
Some other warnings also can be ignored:
implicit declaration of function `int strtoll(...)' implicit declaration of function `int strtoul(...)'
-
We haven't gotten
readline
to work with MIT-pthreads. (This isn't needed, but may be interesting for someone.)
2.3.6 Installing MySQL from Source on Windows
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.2.1 Installing MySQL on Windows.
To build MySQL on Windows from source, you need the following compiler and resources available on your Windows system:
- VC++ 6.0 compiler (updated with 4 or 5 SP and pre-processor package). The pre-processor package is necessary for the macro assembler. More details can be found at http://msdn.microsoft.com/vstudio/downloads/updates/sp/vs6/sp5/faq.aspx.
- Approximately 45MB disk space.
- 64MB RAM.
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:
- Obtain a source distribution packaged by MySQL AB for the particular version of MySQL in which you are interested. Prepackaged source distributions are available for released versions of MySQL and can be obtained from http://dev.mysql.com/downloads/.
-
You can package a source distribution yourself from the latest
BitKeeper developer source tree. If you plan to do this, you must
create the package on a Unix system and then transfer it to your
Windows system. (The reason for this is that some of the configuration
and build steps require tools that work only on Unix.) The BitKeeper
approach thus requires:
- A system running Unix, or a Unix-like system such as Linux.
- BitKeeper 3.0 installed on that system. You can obtain BitKeeper from http://www.bitkeeper.com/.
If you are using a Windows source distribution, you can go directly to section 2.3.6.1 Building MySQL Using VC++. To build from the BitKeeper tree, proceed to section 2.3.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.7.1.1 The MySQL Mailing Lists.
2.3.6.1 Building MySQL Using VC++
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:
- Create a work directory (for example, `C:\workdir').
-
Unpack the source distribution in the aforementioned directory using
WinZip
or other Windows tool that can read `.zip' files. - Start the VC++ 6.0 compiler.
-
In the
File
menu, selectOpen Workspace
. - Open the `mysql.dsw' workspace you find in the work directory.
-
From the
Build
menu, select theSet Active Configuration
menu. -
Click over the screen selecting
mysqld - Win32 Debug
and click OK. -
Press
F7
to begin the build of the debug server, libraries, and some client applications. - Compile the release versions that you want in the same way.
-
Debug versions of the programs and libraries are placed in the
`client_debug' and `lib_debug' directories.
Release versions of the programs and libraries are placed in the
`client_release' and `lib_release' directories.
Note that if you want to build both debug and release versions,
you can select the
Build All
option from theBuild
menu. -
Test the server. The server built using the preceding instructions
will expect that the MySQL base directory and data directory are
`C:\mysql' and `C:\mysql\data' by default. If you want
to test your server using the source tree root directory and its
data directory as the base directory and data directory, you will
need to tell the server their pathnames. You can either do this on
the command line with the
--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. - Start your server from the `client_release' or `client_debug' directory, depending on which server you want to use. The general server startup instructions are at section 2.2.1 Installing MySQL on Windows. You'll need to adapt the instructions appropriately if you want to use a different base directory or data directory.
- When the server is running in standalone fashion or as a service based on your configuration, try to connect to it from the @command{mysql} interactive command-line utility that exists in your `client_release' or `client_debug' directory.
When you are satisfied that the programs you have built are working correctly, stop the server. Then install MySQL as follows:
-
Create the directories where you want to install MySQL. For example,
to install into
`C:\mysql', use these commands:
C:\> mkdir C:\mysql C:\> mkdir C:\mysql\bin C:\> mkdir C:\mysql\data C:\> mkdir C:\mysql\share C:\> mkdir C:\mysql\scripts
If 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\opt
If you want to benchmark MySQL, create this directory:C:\> mkdir C:\mysql\sql-bench
Benchmarking requires Perl support. -
From the `workdir' directory, copy into the
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 /E
If 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\include
If 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.2.1 Installing MySQL on Windows.
2.3.6.2 Creating a Windows Source Package from the Latest Development Source
To create a Windows source package from the current BitKeeper source tree, use the 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.
- Clone the BitKeeper source tree for MySQL (version 4.1 or above, as desired). For more information on how to clone the source tree, see the instructions at section 2.3.3 Installing from the Development Source Tree.
-
Configure and build the distribution so that you have a server
binary to work with. One way to do this is to run the following
command in the top-level directory of your source tree:
shell> ./BUILD/compile-pentium-max
-
After making sure that the build process completed successfully,
run the following utility script from top-level directory of your
source tree:
shell> ./scripts/make_win_src_distribution
This script creates a Windows source package to be used on your Windows system. You can supply different options to the script based on your needs. It accepts the following options:--help
- Display a help message.
--debug
- Print information about script operations, do not create package.
--tmp
- Specify the temporary location.
--suffix
- Suffix name for the package.
--dirname
- Directory name to copy files (intermediate).
--silent
- Do not print verbose list of files processed.
--tar
- Create `tar.gz' package instead of `.zip' package.
- Copy or upload to your Windows machine the Windows source package that you have just created. To compile it, use the instructions in section 2.3.6.1 Building MySQL Using VC++.
2.3.7 Compiling MySQL Clients on Windows
In your source files, you should include `my_global.h' before `mysql.h':
#include <my_global.h> #include <mysql.h>
`my_global.h' includes any other files needed for Windows compatibility (such as `windows.h') if you compile your program on Windows.
You can either link your code with the dynamic `libmysql.lib' library, which is just a wrapper to load in `libmysql.dll' on demand, or link with the static `mysqlclient.lib' library.
The MySQL client libraries are compiled as threaded libraries, so you should also compile your code to be multi-threaded.
2.4 Post-Installation Setup and Testing
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.4.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.4.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.
2.4.1 Windows Post-Installation Procedures
On Windows, the data directory and the grant tables do not have to be
created. MySQL Windows distributions include the grant tables already set up
with a set of preinitialized accounts in the mysql
database under the
data directory. You do not run the @command{mysql_install_db} script that
is used on Unix. However, you should assign passwords to the accounts.
The procedure for this is given in section 2.4.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.2.1.5 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.2.1.7 Starting MySQL as a Windows Service.
2.4.2 Unix Post-Installation Procedures
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 @command{mysql_install_db} program. For some installation methods, this program is run for you automatically:
- If you install MySQL on Linux using RPM distributions, the server RPM runs @command{mysql_install_db}.
- If you install MySQL on Mac OS X using a PKG distribution, the installer runs @command{mysql_install_db}.
Otherwise, you'll need to run @command{mysql_install_db} yourself.
The following procedure describes how to initialize the grant tables (if that has not already 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.4.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 @command{mysql_install_db}. Instructions for doing so are given in section 2.4.3 Securing the Initial MySQL Accounts.
In the examples shown here, the server runs under the user ID of the
mysql
login account. This assumes that such an account exists.
Either create the account if it does not exist, or substitute the name of a
different existing login account that you plan to use for running the
server.
-
Change location into the top-level directory of your MySQL installation,
represented here by BASEDIR:
shell> cd BASEDIR
BASEDIR is likely to be something like `/usr/local/mysql' or `/usr/local'. The following steps assume that you are located in this directory. -
If necessary, run the @command{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, @command{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, @command{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 @command{mysql_install_db} is located in the
bin
orscripts
directory:shell> bin/mysql_install_db --user=mysql shell> scripts/mysql_install_db --user=mysql
The @command{mysql_install_db} script creates the data directory, themysql
database that holds all database privileges, and thetest
database that you can use to test MySQL. The script also creates privilege table entries forroot
accounts and anonymous-user accounts. The accounts have no passwords initially. A description of their initial privileges is given in section 2.4.3 Securing the Initial MySQL Accounts. Briefly, these privileges allow the MySQLroot
user to do anything, and allow anybody to create or use databases with a name oftest
or starting withtest_
. It is important to make sure that the database directories and files are owned by themysql
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 @command{mysql_install_db} asroot
. Otherwise, you should execute the script while logged in asmysql
, in which case you can omit the--user
option from the command. @command{mysql_install_db} creates several tables in themysql
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 thetest
database, you can remove it with @command{mysqladmin -u root drop test} after starting the server. If you have problems with @command{mysql_install_db}, see @ref{mysql_install_db, , @command{mysql_install_db}}. There are some alternatives to running the @command{mysql_install_db} script as it is provided in the MySQL distribution:-
If you want the initial privileges to be different from the standard
defaults, you can modify @command{mysql_install_db} before you run it.
However, a preferable technique is to use
GRANT
andREVOKE
to change the privileges after the grant tables have been set up. In other words, you can run @command{mysql_install_db}, and then use @code{mysql -u root mysql} to connect to the server as the MySQLroot
user so that you can issue theGRANT
andREVOKE
statements. If you want to install MySQL on a lot of machines with the same privileges, you can put theGRANT
andREVOKE
statements in a file and execute the file as a script usingmysql
after running @command{mysql_install_db}. For example:shell> bin/mysql_install_db --user=mysql shell> bin/mysql -u root < your_script_file
By doing this, you can avoid having to issue the statements manually on each machine. -
It is possible to re-create the grant tables completely after they have
already been created. You might want to do this if you're just learning how
to use
GRANT
andREVOKE
and have made so many modifications after running @command{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 themysql
database. (This is the directory named `mysql' under the data directory, which is listed as thedatadir
value when you run @command{mysqld --help}.) Then run the @command{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 @command{mysql_install_db}. -
You can start @command{mysqld} manually using the
--skip-grant-tables
option and add the privilege information yourself using @command{mysql}:shell> bin/mysqld_safe --user=mysql --skip-grant-tables & shell> bin/mysql mysql
From @command{mysql}, manually execute the SQL commands contained in @command{mysql_install_db}. Make sure that you run @command{mysqladmin flush-privileges} or @command{mysqladmin reload} afterward to tell the server to reload the grant tables. Note that by not using @command{mysql_install_db}, you not only have to populate the grant tables manually, you also have to create them first.
-
If you want the initial privileges to be different from the standard
defaults, you can modify @command{mysql_install_db} before you run it.
However, a preferable technique is to use
-
Start the MySQL server:
shell> bin/mysqld_safe --user=mysql &
For versions of MySQL older than 4.0, substitute @command{bin/safe_mysqld} for @command{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 runmysql_safe
asroot
. Otherwise, you should execute the script while logged in asmysql
, 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 will appear 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.4.2.3 Starting and Troubleshooting the MySQL Server. -
Use @command{mysqladmin} to verify that the server is running. The following
commands provide simple tests to check whether the server is up and responding
to connections:
shell> bin/mysqladmin version shell> bin/mysqladmin variables
The output from @command{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: 16773K
To see what else you can do with @command{mysqladmin}, invoke it with the--help
option. -
Verify that you can shut down the server:
shell> bin/mysqladmin -u root shutdown
-
Verify that you can restart the server. Do this by using @command{mysqld_safe} or
by invoking @command{mysqld} directly. For example:
shell> bin/mysqld_safe --user=mysql --log &
If @command{mysqld_safe} fails, see section 2.4.2.3 Starting and Troubleshooting the MySQL Server. -
Run some simple tests to verify that you can retrieve information from the
server. The output should be similar to what is shown here:
shell> bin/mysqlshow +-----------+ | Databases | +-----------+ | mysql | | test | +-----------+ shell> bin/mysqlshow mysql Database: mysql +--------------+ | Tables | +--------------+ | columns_priv | | db | | func | | host | | tables_priv | | user | +--------------+ shell> bin/mysql -e "SELECT Host,Db,User FROM db" mysql +------+--------+------+ | host | db | user | +------+--------+------+ | % | test | | | % | test_% | | +------+--------+------+
-
There is a benchmark suite in the `sql-bench' directory (under the
MySQL installation directory) that you can use to compare how
MySQL performs on different platforms. The benchmark suite is written in
Perl. It uses the Perl DBI module to provide a database-independent interface
to the various databases, and some other additional Perl modules are required
to run the benchmark suite. You must have the following modules installed:
DBI DBD::mysql Data::Dumper Data::ShowTable
These modules can be obtained from CPAN (http://www.cpan.org/). See section 2.7.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-tests
If you don't have the `sql-bench' directory, you probably installed MySQL using RPM files other than the source RPM. (The source RPM includes the `sql-bench' benchmark directory.) In this case, you must first install the benchmark suite before you can use it. 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.tst
The expected result of the test can be found in the `./tests/auto_increment.res' file. - At this point, you should have the server running. However, none of the initial MySQL accounts have a password, so you should assign passwords using the instructions in section 2.4.3 Securing the Initial MySQL Accounts.
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.
2.4.2.1 Problems Running @command{mysql_install_db}
The purpose of the @command{mysql_install_db} script is to generate new MySQL privilege tables. It will not overwrite existing MySQL privilege tables, and it will not affect any other data.
If you want to re-create your privilege tables, first stop the @command{mysqld} server if it's running. Then rename the `mysql' directory under the data directory to save it, and then run @command{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 @command{mysql_install_db}:
- @command{mysql_install_db doesn't install the grant tables}
-
You may find that @command{mysql_install_db} fails to install the grant
tables and terminates after displaying the following messages:
Starting mysqld daemon with databases from XXXXXX mysqld ended
In this case, you should examine the error log file very carefully. The log should be located in the directory `XXXXXX' named by the error message, and should indicate why @command{mysqld} didn't start. If you don't understand what happened, include the log when you post a bug report. See section 1.7.1.3 How to Report Bugs or Problems. - There is already a @command{mysqld process running}
- This indicates that the server is already running, in which case the grant tables probably have already been created. If so, you don't have to run @command{mysql_install_db} at all because it need be run only once (when you install MySQL the first time).
- Installing a second @command{mysqld server doesn't work when one server is running}
-
This can happen when you already have an existing MySQL installation, but
want to put a new installation in a different location. For example, you
might have a production installation already, but you want to create a
second installation for testing purposes. Generally the problem that occurs
when you try to run a second server is that it tries to use a network
interface that is already in use by the first server. In this case, you
will see one of the following error messages:
Can't start server: Bind on TCP/IP port: Address already in use Can't start server: Bind on unix socket...
For instructions on setting up multiple servers, see section 5.10 Running Multiple MySQL Servers on the Same Machine. - You don't have write access to `/tmp'
-
If you don't have write access to create temporary files or a Unix socket
file in the default location (the `/tmp' directory), an error will
occur when you run @command{mysql_install_db} or the @command{mysqld} server.
You can specify different temporary directory and Unix socket file locations
by executing these commands prior to starting @command{mysql_install_db} or
@command{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 @command{mysql_install_db} and start the server with these commands:shell> bin/mysql_install_db --user=mysql shell> bin/mysqld_safe --user=mysql &
If @command{mysql_install_db} is located in the `scripts' directory, modify the first command to usescripts/mysql_install_db
. See section A.4.5 How to Protect or Change the MySQL Socket File `/tmp/mysql.sock'. See section E Environment Variables.
2.4.2.2 Starting and Stopping MySQL Automatically
Generally, you start the @command{mysqld} server in one of these ways:
- By invoking @command{mysqld} directly. This works on any platform.
- By running the MySQL server as a Windows service. This can be done on versions of Windows that support services (such as NT, 2000, and XP). The service can be set to start the server automatically when Windows starts, or as a manual service that you start on request. For instructions, see section 2.2.1.7 Starting MySQL as a Windows Service.
- By invoking @command{mysqld_safe}, which tries to determine the proper options for @command{mysqld} and then runs it with those options. This script is used on systems based on BSD Unix. @xref{mysqld_safe, , @command{mysqld_safe}}.
-
By invoking @command{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 @command{mysql.server} script starts the server by invoking @command{mysqld_safe}. @xref{mysql.server, , @command{mysql.server}}. - On Mac OS X, you can install a separate MySQL Startup Item package to enable the automatic startup of MySQL on system startup. The Startup Item starts the server by invoking @command{mysql.server}. See section 2.2.3 Installing MySQL on Mac OS X for details.
The @command{mysql.server} and @command{mysqld_safe} scripts and the Mac OS X Startup Item can be used to start the server manually, or automatically at system startup time. @command{mysql.server} and the Startup Item also can be used to stop the server.
To start or stop the server manually using the @command{mysql.server} script,
invoke it with start
or stop
arguments:
shell> mysql.server start shell> mysql.server stop
Before @command{mysql.server} starts the server, it changes location to the
MySQL installation directory, and then invokes @command{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 @command{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
@command{mysqld_safe}. If you do this, your modified version of
@command{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.)
@command{mysql.server stop} brings down the server by sending a signal to it. You can also stop the server manually by executing @command{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 @command{mysql.server} script will already have been installed in the
`/etc/init.d' directory with the name `mysql'. You need not
install it manually. See section 2.2.2 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 @command{mysqld}.
If you install MySQL from a source distribution or using a binary distribution format that does not install @command{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 @command{mysql.server} manually, copy it to the `/etc/init.d' directory with the name @command{mysql}, and then make it executable. Do this by changing location into the appropriate directory where @command{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 @command{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 @command{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 @command{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.
@command{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 |
@command{mysqld} | [mysqld] , [server] , [mysqld-major-version]
|
@command{mysql.server} | [mysqld] , [mysql.server]
|
@command{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]
will be
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 will
be read only by servers within a given release series.
For backward compatibility, @command{mysql.server} also reads the
[mysql_server]
group and @command{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.
2.4.2.3 Starting and Troubleshooting the MySQL Server
If you have problems starting the server, here are some things you can try:
- Specify any special options needed by the storage engines you are using.
- Make sure that the server knows where to find the data directory.
- Make sure the server can use the data directory. The ownership and permissions of the data directory and its contents must be set such that the server can access and modify them.
- Check the error log to see why the server doesn't start.
- Verify that the network interfaces the server wants to use are available.
Some storage engines have options that control their behavior.
You can create a `my.cnf' file and 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:
-
If you are using
InnoDB
tables, refer to theInnoDB
-specific startup options. In MySQL 3.23, you must configureInnoDB
explicitly or the server will fail to start. From MySQL 4.0 on,InnoDB
uses default values for its configuration options if you specify none. See section 16.4InnoDB
Configuration. -
If you are using
BDB
(Berkeley DB) tables, you should familiarize yourself with the differentBDB
-specific startup options. See section 15.4.3BDB
Startup Options.
When the @command{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 will
not work properly. You can find out what the default path settings are by
invoking @command{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 @command{mysqld} or @command{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 @command{mysqld} the
location of the base directory under which MySQL is installed and it will
look for the data directory there. You can do this with the --basedir
option.
To check the effect of specifying path options, invoke @command{mysqld} with
those options followed by the --verbose
and --help
options.
For example, if you change location into the directory where @command{mysqld} is
installed, and then run the following command, it
will show 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 @command{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 @command{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 @command{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 @command{mysqld} with BDB
table support and
@command{mysqld} dumps core at startup, this could be due to problems with the
BDB
recovery log. In this case, you can try starting @command{mysqld}
with --bdb-no-recover
. If that helps, then you should remove
all BDB
log files from the data directory and try starting @command{mysqld}
again without the --bdb-no-recover
option.
If either of the following errors occur, it means that some other program (perhaps another @command{mysqld} server) is already using the TCP/IP port or Unix socket file that @command{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 @command{ps} to determine whether you have another @command{mysqld} server running. If so, shut down the server before starting @command{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 @command{mysqld} is
trying to use. You'll need to track down what program this is and disable
it, or else tell @command{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 @command{mysqld} to start, you can try to make a trace file
to find the problem by using the --debug
option.
See section D.1.2 Creating Trace Files.
2.4.3 Securing the Initial MySQL Accounts
Part of the MySQL installation process is to set up the mysql
database
containing the grant tables:
- Windows distributions contain preinitialized grant tables that are installed automatically.
- On Unix, the grant tables are populated by the @command{mysql_install_db} program. Some installation methods run this program for you. Others require that you execute it manually. For details, see section 2.4.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:
-
Two accounts are created with a username of
root
. These are superuser accounts that can do anything. The initialroot
account passwords are empty, so anyone can connect to the MySQL server asroot
without a password and be granted all privileges.-
On Windows, one
root
account is for connecting from the local host and the other allows connections from any host. -
On Unix, both
root
accounts are for connections from the local host. Connections must be made from the local host by specifying a hostname oflocalhost
for one account, or the actual hostname or IP number for the other.
-
On Windows, one
-
Two anonymous-user accounts are created, each with an empty username.
The anonymous accounts have no passwords, so anyone can use them to connect
to the MySQL server.
-
On Windows, one anonymous account is for connections from the local host.
It has all privileges, just like the
root
accounts. The other is for connections from any host and has all privileges for thetest
database or other databases with names that start withtest
. -
On Unix, both anonymous accounts are for connections from the local host.
Connections must be made from the local host by specifying a hostname of
localhost
for one account, or the actual hostname or IP number for the other. These accounts have all privileges for thetest
database or other databases with names that start withtest_
.
-
On Windows, one anonymous account is for connections from the local host.
It has all privileges, just like the
As noted, none of the initial accounts have passwords. This means that your MySQL installation is unprotected until you do something about it:
- If you want to prevent clients from connecting as anonymous users without a password, you should either assign passwords to the anonymous accounts or else remove them.
-
You should assign passwords to the MySQL
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 will go 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:
-
Use the
SET PASSWORD
statement - Use the @command{mysqladmin} command-line client program
-
Use the
UPDATE
statement
To assign passwords using SET PASSWORD
, connect to the server as
root
and issue two SET PASSWORD
statements.
Be sure to encrypt the password using the PASSWORD()
function.
For Windows, do this:
shell> mysql -u root mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd'); mysql> SET PASSWORD FOR 'root'@'%' = PASSWORD('newpwd');
For Unix, do this:
shell> mysql -u root mysql> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('newpwd'); mysql> SET PASSWORD FOR 'root'@'host_name' = PASSWORD('newpwd');
In the second SET PASSWORD
statement, replace host_name with
the name of the server host. This is the same hostname that you used when
you assigned the anonymous account passwords.
To assign passwords to the root
accounts using @command{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
@command{mysqladmin} commands to set the password will 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 @command{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.
2.5 Upgrading/Downgrading 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:
- Read the upgrading section for the release series to which you are upgrading. Read the change notes as well. These provide information about new features you can use. For example, before upgrading from MySQL 4.1 to 5.0, read the 5.0 upgrading section (see section 2.5.1 Upgrading from Version 4.1 to 5.0) and read the 5.0 change notes (see section C MySQL Change History).
- Before you do an upgrade, back up your databases.
- If you are running MySQL Server on Windows, see section 2.5.7 Upgrading MySQL Under Windows.
-
An upgrade may involve changes to the grant tables that are stored in the
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.5.8 Upgrading the Grant Tables. - If you are using replication, see section 6.6 Upgrading a Replication Setup for information on upgrading your replication setup.
- If you install a MySQL-Max distribution that includes a server named @command{mysqld-max}, then upgrade later to a non-Max version of MySQL, @command{mysqld_safe} will still attempt to run the old @command{mysqld-max} server. If you perform such an upgrade, you should manually remove the old @command{mysqld-max} server to ensure that @command{mysqld_safe} runs the new @command{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.0. If you change the character set when running MySQL, you must run
@command{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.
If you upgrade or downgrade from one release series to another, there may be incompatibilities in table storage formats. In this case, you can use @command{mysqldump} to dump your tables before upgrading. After upgrading, reload the dump file using @command{mysql} to re-create your tables.
If you are cautious about using new versions, you can always rename your old @command{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 @command{mysqld} to @command{mysqld-4.0.18}. If your new @command{mysqld} then does something unexpected, you can simply shut it down and restart with your old @command{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 @command{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,
@command{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.
2.5.1 Upgrading from Version 4.1 to 5.0
In general, you should do the following when upgrading to MySQL 5.0 from 4.1:
- Check the items in the change list found later in this section to see whether any of them might affect your applications.
- Read the 5.0 news items to see what significant new features you can use in 5.0. See section C.1 Changes in release 5.0.x (Development).
- If you are running MySQL Server on Windows, see section 2.5.7 Upgrading MySQL Under Windows. Also, two of the Windows MySQL servers were renamed. See section 2.2.1.4 Selecting a Windows Server.
-
MySQL 5.0 adds support for stored procedures. This support requires the
proc
table in themysql
database. To create this file, you should run the @command{mysql_fix_privilege_tables} script as described in section 2.5.8 Upgrading the Grant Tables. -
MySQL 5.0 adds support for views. This support requires the extra privilege
columns in the
user
anddb
tables in themysql
database. To create these columns, you should run the @command{mysql_fix_privilege_tables} script as described in section 2.5.8 Upgrading the Grant Tables. - If you are using replication, see section 6.6 Upgrading a Replication Setup for information on upgrading your replication setup.
-
MySQL 5.0.2 adds several new SQL modes that allow stricter control over
rejecting records that have invalid or missing values.
See section 5.2.2 The Server SQL Mode.
See section 1.8.6.2 Constraint
NOT NULL
andDEFAULT
Values. If you want to enable this control but continue to use MySQL's capability for storing incorrect dates such as'2004-02-31'
, you should start the server with--sql_mode=TRADITIONAL,ALLOW_INVALID_DATES
. -
As of MySQL 5.0.2, the
SCHEMA
andSCHEMAS
keywords are accepted as synonyms forDATABASE
andDATABASES
. - The update log is removed in MySQL 5.0.
The following list describes changes that may affect applications and that you should watch out for when upgrading to version 5.0:
- The update log is removed, so if you enabled it in the past, you should enable the binary log instead. See section C.1 Changes in release 5.0.x (Development).
2.5.2 Upgrading from Version 4.0 to 4.1
In general, you should do the following when upgrading to MySQL 4.1 from 4.0:
- Check the items in the change lists found later in this section to see whether any of them might affect your applications. Some of them result in incompatibilities with earlier versions.
- Read the 4.1 news items to see what significant new features you can use in 4.1. See section C.2 Changes in release 4.1.x (Gamma).
-
Important note:
MySQL 4.1 stores table names and column names in
UTF8
. If you have table names or column names that use characters outside of the range from `A' to `Z', you may have to do amysqldump
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 atable 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. - If you are running MySQL Server on Windows, see section 2.5.7 Upgrading MySQL Under Windows. Important note: Early alpha Windows distributions for MySQL 4.1 do not contain an installer program. See section 2.2.1.2 Installing a Windows Binary Distribution for instructions on how to install such a distribution.
-
After upgrading, update the grant tables to have the new longer
Password
column that is needed for more secure handling of passwords. The procedure uses @command{mysql_fix_privilege_tables} and is described in section 2.5.8 Upgrading the Grant Tables. If you don't do this, MySQL will not us the new more secure protocol to authenticate. Implications of the password-handling change for applications are given later in this section. - If you are using replication, see section 6.6 Upgrading a Replication Setup for information on upgrading your replication setup.
-
The Berkeley DB table handler is updated to DB 4.1 (from 3.2) which has
a new log format. If you have to downgrade back to 4.0 you must use
@command{mysqldump} to dump your
BDB
tables in text format and delete alllog.XXXXXXXXXX
files before you start MySQL 4.0 and reload the data. - Character set support has been improved. The server now supports multiple character sets.
-
MySQL 4.1.3 introduces support for per-connection time zones.
See section 5.8.8 MySQL Server Time Zone Support. To enable recognition of named time zones,
you should create the time zone tables in the
mysql
database. For instructions, see section 2.4 Post-Installation Setup and Testing. -
If you are using an old
DBD-mysql
module (Msql-MySQL-modules
) you have to upgrade to use the newerDBD-mysql
module. Anything aboveDBD-mysql
2.xx should be fine. If you don't upgrade, some methods (such asDBI->do()
) will not notice error conditions correctly. -
The
--defaults-file=option-file-name
option now will give an error if the option file doesn't exist. - Some notes about upgrading from MySQL 4.0 to MySQL 4.1 on Netware: Make sure to upgrade Perl and PHP versions. Download and install Perl module for MySQL 4.1 from http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1126 and PHP Extension for MySQL 4.1 from http://forge.novell.com/modules/xfmod/project/showfiles.php?group_id=1078.
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 @command{mysqld}.
See section 5.2.1 @command{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 will 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 will help 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:
-
All tables and string columns now have a character set.
See section 11 Character Set Support.
Character set information is displayed by
SHOW CREATE TABLE
and @command{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. - If you have table columns that store character data represented in a character set that the 4.1 server now supports directly, you can convert the columns to the proper character set using the instructions in section 11.10.2 Converting 4.0 Character Columns to 4.1 Format. Also, database, table, and column identifiers now are stored internally using Unicode (UTF8) regardless of the default character set. See section 10.2 Database, Table, Index, Column, and Alias Names.
-
Incompatible change:
Starting from MySQL 4.1.3,
InnoDB
uses the same character set comparison functions as MySQL for non-latin1_swedish_ci
character strings that are notBINARY
. This changes the sorting order of space and characters with a code < ASCII(32) in those character sets. Forlatin1_swedish_ci
character strings andBINARY
strings,InnoDB
uses its own pad-spaces-at-end comparison method, which stays unchanged. If you have anInnoDB
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 anyCHAR
/VARCHAR
/orTEXT
columns that are notBINARY
but may contain characters with a code < ASCII(32), then you should doALTER TABLE
orOPTIMIZE
table on it to regenerate the index, after upgrading to MySQL 4.1.3 or later. -
MySQL now interprets length specifications in character column
definitions in characters. (Earlier versions interpret them in bytes.)
For example,
CHAR(N)
now means N characters, not N bytes. - The table definition format used in `.frm' files has changed slightly in 4.1. MySQL 4.0 versions from 4.0.11 on can read the new `.frm' format directly, but older versions cannot. If you need to move tables from 4.1 to a version earlier than 4.0.11, you should use @command{mysqldump}. @xref{mysqldump, , @command{mysqldump}}.
-
Important note: If you upgrade to MySQL 4.1.1 or higher, it is
difficult to downgrade back to 4.0 or 4.1.0! That is because, for earlier
versions,
InnoDB
is not aware of multiple tablespaces. -
Incompatible change:
In connection with the support for per-connection time zones in MySQL 4.1.3,
the
timezone
system variable was renamed tosystem_time_zone
. -
Windows servers now support connections from local clients using shared
memory if run with the
--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. -
The interface to aggregated UDF functions has changed a bit. You must now
declare a
xxx_clear()
function for each aggregate functionXXX()
.
Client Changes:
-
@command{mysqldump} now has the
--opt
and--quote-names
options enabled by default. You can turn them off with--skip-opt
and--skip-quote-names
.
SQL Changes:
-
Incompatible change:
In MySQL 4.1.2, the
Type
column in the output fromSHOW TABLE STATUS
was renamed toEngine
. -
Incompatible change:
String comparison now works according to SQL standard: Instead of
stripping end spaces before comparison, we now extend the shorter string
with spaces. The problem with this is that now
'a' > 'a\t'
, which it wasn't before. If you have any tables where you have aCHAR
orVARCHAR
column in which the last character in the column may be less thanASCII(32)
, you should useREPAIR TABLE
or @command{myisamchk} to ensure that the table is correct. -
When using multiple-table
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. -
Incompatible change:
TIMESTAMP
is now 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 12.3.1.2TIMESTAMP
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
toTIMESTAMP
columns when you retrieve them:mysql> SELECT ts_col + 0 FROM tbl_name;
Display widths forTIMESTAMP
columns are no longer supported. For example, if you declare a column asTIMESTAMP(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. -
Incompatible change:
Binary values such as
0xFFDF
now 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 useCAST()
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 useCAST()
, a lexical string comparison will be 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.) -
For functions that produce a
DATE
,DATETIME
, orTIME
value, the result returned to the client now 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 forAUTO_INCREMENT
columns. (In 4.0, aDEFAULT
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 thesql_mode
variable. You should useSET TRANSACTION ISOLATION LEVEL SERIALIZABLE
instead.SERIALIZE
is no longer valid for the--sql-mode
option for @command{mysqld}, either. Use--transaction-isolation=SERIALIZABLE
instead. -
User variables now are not case sensitive. In MySQL 4.1,
SET @x = 0; SET @X = 1; SELECT @x;
creates two variables and returns0
. In MySQL 5.0, it creates one variable and returns1
.
C API Changes:
-
Incompatible change:
The
mysql_shutdown()
C API function has an extra parameter as of MySQL 4.1.3:SHUTDOWN
-level. You should convert anymysql_shutdown(X)
call you have in your application tomysql_shutdown(X,SHUTDOWN_DEFAULT)
. -
Some C API calls such as
mysql_real_query()
now return1
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 will 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.
- Only upgrade the client to use 4.1 client libraries (not the server). No behavior will change (except the return value of some API calls), but you cannot use any of the new features provided by the 4.1 client/server protocol, either. (MySQL 4.1 has an extended client/server protocol that offers such features as prepared statements and multiple result sets.) See section 21.2.4 C API Prepared Statements.
-
Upgrade to 4.1 and run the @command{mysql_fix_privilege_tables} script
to widen the
Password
column in theuser
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. -
Upgrade to 4.1 and run the @command{mysql_fix_privilege_tables} script to widen the
Password
column in theuser
table. If you know that all clients also have been upgraded to 4.1, don't run the server with the--old-passwords
option. Instead, change the passwords on all existing accounts so that they have the new format. A pure-4.1 installation is the most secure. - Some notes about upgrading from MySQL 4.0 to MySQL 4.1 on Netware: Make sure to upgrade Perl and PHP versions. Download Perl 5 for Netware from http://forge.novell.com/modules/xfmod/project/?perl5) and PHP from http://forge.novell.com/modules/xfmod/project/?php.
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
.
2.5.3 Upgrading from Version 3.23 to 4.0
In general, you should do the following when upgrading to MySQL 4.0 from 3.23:
- Check the items in the change lists found later in this section to see whether any of them might affect your applications.
- Read the 4.0 news items to see what significant new features you can use in 4.0. See section C.3 Changes in release 4.0.x (Production).
- If you are running MySQL Server on Windows, see section 2.5.7 Upgrading MySQL Under Windows.
- After upgrading, update the grant tables to add new privileges and features. The procedure uses the @command{mysql_fix_privilege_tables} script and is described in section 2.5.8 Upgrading the Grant Tables.
- If you are using replication, see section 6.6 Upgrading a Replication Setup for information on upgrading your replication setup.
- Edit any MySQL startup scripts or option files to not use any of the deprecated options described later in this section.
-
Convert your old
ISAM
files toMyISAM
files. One way to do this is with themysql_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_name
Note that this should be used only if all tables in the given database areISAM
orMyISAM
tables. To avoid converting tables of other types toMyISAM
, you can explicitly list the names of yourISAM
tables after the database name on the command line. Individual tables can be changed toMyISAM
by using the followingALTER 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';
-
Ensure that you don't have any MySQL clients that use shared libraries
(like the Perl
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 PythonMySQLdb
module.
MySQL 4.0 will work even if you don't perform the preceding actions, but you
will not be able to 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 @command{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:
-
MySQL 4.0 has a lot of new privileges in the
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.5.8 Upgrading the Grant Tables. Until you do this, all accounts have theSHOW DATABASES
,CREATE TEMPORARY TABLES
, andLOCK TABLES
privileges.SUPER
andEXECUTE
privileges take their value fromPROCESS
.REPLICATION SLAVE
andREPLICATION CLIENT
take their values fromFILE
. 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 usingGRANT
commands in the scripts, this is a good time to change your scripts to useGRANT
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 @command{mysqld} Concerning Security. If you getAccess 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 will needREPLICATION SLAVE
(instead ofFILE
) for new slave servers. - @command{safe_mysqld} has been renamed to @command{mysqld_safe}. For backward compatibility, binary distributions will for some time include @command{safe_mysqld} as a symlink to @command{mysqld_safe}.
-
InnoDB
support is now included by default in binary distributions. If you build MySQL from source,InnoDB
is configured in by default. If you do not useInnoDB
and want to save memory when running a server that hasInnoDB
support enabled, use the--skip-innodb
server startup option. To compile MySQL withoutInnoDB
support, run @command{configure} with the--without-innodb
option. -
Values for the startup parameters
myisam_max_extra_sort_file_size
andmyisam_max_extra_sort_file_size
now are given in bytes (they were given in megabytes before 4.0.3). -
@command{mysqld} now has the option
--temp-pool
enabled by default because this gives better performance with some operating systems (most notably Linux). -
The @command{mysqld} startup options
--skip-locking
and--enable-locking
were renamed to--skip-external-locking
and--external-locking
. -
External system locking of
MyISAM
/ISAM
files is now turned off by default. You can turn this on with--external-locking
. (However, this is never needed for most users.) -
The following startup variables and options have been renamed:
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 @command{mysqld_safe})record_buffer
,sort_buffer
, andwarnings
will still work in MySQL 4.0 but are deprecated.
SQL Changes:
-
The following SQL variables have been renamed:
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
-
You have to use
SET GLOBAL SQL_SLAVE_SKIP_COUNTER=skip_count
instead ofSET SQL_SLAVE_SKIP_COUNTER=skip_count
. -
SHOW MASTER STATUS
now returns an empty set if binary logging is not enabled. -
SHOW SLAVE STATUS
now returns an empty set if the slave is not initialized. -
SHOW INDEX
has two more columns than it had in 3.23 (Null
andIndex_type
). -
The format of
SHOW OPEN TABLES
has changed. -
ORDER BY col_name DESC
sortsNULL
values last, as of MySQL 4.0.11. In 3.23 and in earlier 4.0 versions, this was not always consistent. -
CHECK
,LOCALTIME
, andLOCALTIMESTAMP
now are reserved words. -
DOUBLE
andFLOAT
columns now honor theUNSIGNED
flag on storage (before,UNSIGNED
was ignored for these columns). -
The result of all bitwise operators (
|
,&
,<<
,>>
, and~
) is now unsigned. This may cause problems if you are using them in a context where you want a signed result. See section 13.7 Cast Functions and Operators. Note: When you use subtraction between integer values where one is of typeUNSIGNED
, the result will be 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 @command{mysqld}. See section 5.2.2 The Server SQL Mode. -
You should use integers to store values in
BIGINT
columns (instead of using strings, as you did in MySQL 3.23). Using strings will still work, but using integers is more efficient. -
In MySQL 3.23,
INSERT INTO ... SELECT
always hadIGNORE
enabled. As of 4.0.1, MySQL will stop (and possibly roll back) by default in case of an error unless you specifyIGNORE
. -
You should use
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 theAUTO_INCREMENT
counter, andTRUNCATE TABLE
is faster.) -
You will get an error if you have an active transaction or
LOCK TABLES
statement when trying to executeTRUNCATE TABLE
orDROP DATABASE
. -
To use
MATCH ... AGAINST (... IN BOOLEAN MODE)
full-text searches with your tables, you must rebuild their indexes withREPAIR TABLE tbl_name USE_FRM
. If you attempt a boolean full-text search without rebuilding the indexes this way, the search will return incorrect results. See section 13.6.4 Fine-Tuning MySQL Full-Text Search. -
LOCATE()
andINSTR()
are case sensitive if one of the arguments is a binary string. Otherwise they are case insensitive. -
STRCMP()
now 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)
now returns the characters in str converted to hexadecimal. If you want to convert a number to hexadecimal, you should ensure that you callHEX()
with a numeric argument. -
RAND(seed)
returns a different random number series in 4.0 than in 3.23; this was done to further differentiateRAND(seed)
andRAND(seed+1)
. -
The default type returned by
IFNULL(A,B)
is now set to be the more ``general'' of the types ofA
andB
. (The general-to-specific order is string,REAL
,INTEGER
).
C API Changes:
-
The old C API functions
mysql_drop_db()
,mysql_create_db()
, andmysql_connect()
are no longer supported unless you compile MySQL withCFLAGS=-DUSE_OLD_FUNCTIONS
. However, it is preferable to change client programs to use the new 4.0 API instead. -
In the
MYSQL_FIELD
structure,length
andmax_length
have changed fromunsigned int
tounsigned long
. This should not cause any problems, except that they may generate warning messages when used as arguments in theprintf()
class of functions. -
Multi-threaded clients should use
mysql_thread_init()
andmysql_thread_end()
. See section 21.2.14 How to Make a Threaded Client.
Other Changes:
-
If you want to recompile the Perl
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 deprecatedmysql_drop_db()
call.
2.5.4 Upgrading from Version 3.22 to 3.23
MySQL 3.22 and 3.21 clients will 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:
-
MySQL 3.23 supports tables of the new
MyISAM
type and the oldISAM
type. By default, all new tables are created with typeMyISAM
unless you start @command{mysqld} with the--default-table-type=isam
option. You don't have to convert your oldISAM
tables to use them with MySQL 3.23. You can convert anISAM
table toMyISAM
format withALTER TABLE tbl_name TYPE=MyISAM
or the Perl scriptmysql_convert_table_format
. -
All tables that use the
tis620
character set must be fixed with @command{myisamchk -r} orREPAIR TABLE
. -
If you are using the
german
character sort order forISAM
tables, you must repair them with @command{isamchk -r}, because we have made some changes in the sort order.
Client Program Changes:
-
The MySQL client @command{mysql} is now 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. -
If you want your @command{mysqldump} files to be compatible between
MySQL 3.22 and 3.23, you should not use the
--opt
or--all
option to @command{mysqldump}.
SQL Changes:
-
If you do a
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 @command{configure} didn't detect the availability of thereadlink()
system call. -
OPTIMIZE TABLE
now works only forMyISAM
tables. For other table types, you can useALTER TABLE
to optimize the table. DuringOPTIMIZE TABLE
, the table is now locked to prevent it from being used by other threads. -
Date functions that work on parts of dates (such as
MONTH()
) will now return 0 for0000-00-00
dates. In MySQL 3.22, these functions returnedNULL
. -
The default return type of
IF()
now 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 inAUTO_INCREMENT
columns, either;CHECK TABLE
will complain about 0 values because they may change if you dump and restore the table.AUTO_INCREMENT
forMyISAM
tables is now handled at a lower level and is much faster than before. In addition, forMyISAM
tables, old numbers are no longer reused, even if you delete rows from the table. -
CASE
,DELAYED
,ELSE
,END
,FULLTEXT
,INNER
,RIGHT
,THEN
, andWHEN
now are reserved words. -
FLOAT(p)
now is a true floating-point type and not a value with a fixed number of decimals. -
When declaring columns using a
DECIMAL(length,dec)
type, thelength
argument no longer includes a place for the sign or the decimal point. -
A
TIME
string must now be of one of the following formats:[[[DAYS] [H]H:]MM:]SS[.fraction]
or[[[[[H]H]H]H]MM]SS[.fraction]
. -
LIKE
now compares strings using the same character comparison rules as for the=
operator. If you require the old behavior, you can compile MySQL with theCXXFLAGS=-DLIKE_CMP_TOUPPER
flag. -
REGEXP
now is case insensitive if neither of the strings is a binary string. -
When you check or repair
MyISAM
(`.MYI') tables, you should use theCHECK TABLE
statement or the @command{myisamchk} command. ForISAM
(`.ISM') tables, use the @command{isamchk} command. -
Check all your calls to
DATE_FORMAT()
to make sure that there is a `%' before each format character. (MySQL 3.22 already allowed this syntax, but now `%' is required.) -
In MySQL 3.22, the output of
SELECT DISTINCT ...
was almost always sorted. In MySQL 3.23, you must useGROUP BY
orORDER BY
to obtain sorted output. -
SUM()
now returnsNULL
instead of 0 if there are no matching rows. This is required by standard SQL. -
An
AND
orOR
withNULL
values will now returnNULL
instead of 0. This mostly affects queries that useNOT
on anAND/OR
expression asNOT NULL
=NULL
. -
LPAD()
andRPAD()
now shorten the result string if it's longer than the length argument.
C API Changes:
-
mysql_fetch_fields_direct()
now is a function instead of a macro. It now returns a pointer to aMYSQL_FIELD
instead of aMYSQL_FIELD
. -
mysql_num_fields()
no longer can be used on aMYSQL*
object (it's now a function that takes aMYSQL_RES*
value as an argument). With aMYSQL*
object, you now should usemysql_field_count()
instead.
2.5.5 Upgrading from Version 3.21 to 3.22
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 will use the new way to store the date. You can't access these new
columns from an old version of @command{mysqld}.
When upgrading to MySQL 3.23 from an earlier version, note the following changes:
-
After installing MySQL Version 3.22, you should start the new server
and then run the @command{mysql_fix_privilege_tables} script. This will add the
new privileges that you need to use the
GRANT
command. If you forget this, you will getAccess denied
when you try to useALTER TABLE
,CREATE INDEX
, orDROP INDEX
. The procedure for updating the grant tables is described in section 2.5.8 Upgrading the Grant Tables. -
The C API interface to
mysql_real_connect()
has changed. If you have an old client program that calls this function, you must pass a0
for the newdb
argument (or recode the client to send thedb
element for faster connections). You must also callmysql_init()
before callingmysql_real_connect()
. This change was done to allow the newmysql_options()
function to save options in theMYSQL
handler structure. -
The @command{mysqld} variable
key_buffer
has been renamed tokey_buffer_size
, but you can still use the old name in your startup files.
2.5.6 Upgrading from Version 3.20 to 3.21
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 @command{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()
will 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
@command{mysqld}, you will need to make the following changes:
- All client code must be recompiled. If you are using ODBC, you must get the MyODBC 2.x driver.
-
The
scripts/add_long_password
script must be run to convert thePassword
field in themysql.user
table toCHAR(16)
. -
All passwords must be reassigned in the
mysql.user
table to get 62-bit rather than 31-bit passwords. - The table format hasn't changed, so you don't have to convert any tables.
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 will 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 @command{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 @command{mysqld},
old clients will be unable to connect and will 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 now be specified before anyORDER BY
clause. -
The parameters to
LOCATE()
have been swapped. -
There are some new reserved words. The most noticeable are
DATE
,TIME
, andTIMESTAMP
.
2.5.7 Upgrading MySQL Under Windows
When upgrading MySQL under Windows, please follow these steps:
- Download the latest Windows distribution of MySQL.
- Choose a time of day with low usage, where a maintenance break is acceptable.
- Alert the users who still are active about the maintenance break.
-
Stop the running MySQL Server (for example, with @command{NET STOP MySQL} or with
the
Services
utility if you are running MySQL as a service, or with @command{mysqladmin shutdown} otherwise). -
Exit the
WinMySQLAdmin
program if it is running. - Run the installation script of the Windows distribution by clicking the Install button in WinZip and following the installation steps of the script. Important note: Early alpha Windows distributions for MySQL 4.1 do not contain an installer program. See section 2.2.1.2 Installing a Windows Binary Distribution for instructions on how to install such a distribution.
-
You may either overwrite your old MySQL installation (usually located at
`C:\mysql'), or install it into a different directory, such as
C:\mysql4
. Overwriting the old installation is recommended. - Restart the server. For example, use @command{NET START MySQL} if you run MySQL as a service, or invoke @command{mysqld} directly otherwise.
- Update the grant tables. The procedure is described in section 2.5.8 Upgrading the Grant Tables.
Possible error situations:
A system error has occurred. System error 1067 has occurred. The process terminated unexpectedly.
These errors mean that your option file (by default `C:\my.cnf') contains an option that cannot be recognized by MySQL. You can verify that this is the case by trying to restart MySQL with the option file renamed to prevent the server from using it. (For example, rename `C:\my.cnf' to `C:\my_cnf.old'.) Once you have verified it, you need to identify which option is the culprit. Create a new `my.cnf' file and move parts of the old file to it (restarting the server after you move each part) until you determine which option causes server startup to fail.
2.5.8 Upgrading the Grant Tables
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 @command{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 @command{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 @command{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 @command{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 @command{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 will add 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:
-
In MySQL 5.0.2 or later, @command{mysql_fix_privilege_tables}
copies the
Create_priv
value in theuser
table to theCreate_view_priv
andShow_view_priv
columns. -
In 5.0.1, the view-related privileges are not enabled for any accounts, so
you cannot immediately use
GRANT
to give them give them to accounts that should have them. To deal with this, first connect to the server asroot
and issue the following statements to give the privileges to theroot
accounts manually withUPDATE
:mysql> UPDATE mysql.user SET Show_view_priv = 'Y', Create_view_priv = 'Y' -> WHERE User = 'root'; mysql> FLUSH PRIVILEGES;
After this,root
can useGRANT
to give the view privileges to other accounts. Note: You should issue the statements just shown,GRANT ALL
will not work at the global and database levels, becauseGRANT ALL
requires that you actually possess all privileges.
2.5.9 Copying MySQL Databases to Another Machine
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 15.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 @command{mysqldump} instead.
By default, @command{mysqldump} will create a file containing SQL statements. You can then transfer the file to the other machine and feed it as input to the @command{mysql} client.
Try @command{mysqldump --help} to see what options are available. If you are moving the data to a newer version of MySQL, you should use @command{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 @command{mysqldump} and @command{mysqlimport} to transfer
the database.
For big tables, this is much faster than simply using @command{mysqldump}.
In the following commands, DUMPDIR
represents the full pathname
of the directory you use to store the output from @command{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
@command{mysqladmin flush-privileges} so that the server reloads the grant table
information.
2.6 Operating System-Specific Notes
2.6.1 Linux Notes
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 likely will see none of them.
2.6.1.1 Linux Operating System Notes
MySQL needs at least Linux Version 2.0.
Warning: We have seen some strange problems with Linux 2.2.14 and MySQL on SMP systems. We also have reports from some MySQL users that they have encountered serious stability problems using MySQL with kernel 2.2.14. If you are using this kernel, you should upgrade to 2.2.19 (or newer) or to a 2.4 kernel. If you have a multiple-CPU box, then you should seriously consider using 2.4 because it will give you a significant speed boost. Your system also will be more stable.
When using LinuxThreads, you will see a minimum of three @command{mysqld} processes running. These are in fact threads. There will be one thread for the LinuxThreads manager, one thread to handle connections, and one thread to handle alarms and signals.
2.6.1.2 Linux Binary Distribution Notes
The Linux-Intel binary and RPM releases of MySQL are configured for the highest possible speed. We are always trying to use the fastest stable compiler available.
The binary release is linked with -static
, which means you do not
normally need to worry about which version of the system libraries you
have. You need not install LinuxThreads, either. A program linked with
-static
is slightly larger than a dynamically linked program,
but also slightly faster (3-5%). However, one problem with a statically
linked program is that you can't use user-defined functions (UDFs).
If you are going to write or use UDFs (this is something for C or C++
programmers only), you must compile MySQL yourself using dynamic linking.
A known issue with binary distributions is that on older Linux
systems that use libc
(such as Red Hat 4.x or Slackware), you will 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:
-
You probably will see the following error message when you run
@command{mysql_install_db}:
Sorry, the host 'xxxx' could not be looked up
You can deal with this by executing @command{mysql_install_db --force}, which will not execute the @command{resolveip} test in @command{mysql_install_db}. The downside is that you can't use hostnames in the grant tables: Except forlocalhost
, you must use IP numbers instead. If you are using an old version of MySQL that doesn't support--force
, you must manually remove theresolveip
test inmysql_install
using an editor. -
You also may see
the following error when you try to run @command{mysqld} with the
--user
option:getpwnam: No such file or directory
To work around this, start @command{mysqld} by using thesu
command rather than by specifying the--user
option. This causes the system itself to change the user ID of the @command{mysqld} process so that @command{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 @command{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 will 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.
2.6.1.3 Linux Source Distribution Notes
The following notes regarding glibc
apply only to the situation
when you build MySQL
yourself. If you are running Linux on an x86 machine, in most cases it is
much better for you to 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 will need to make some changes to LinuxThreads:
-
Increase
PTHREAD_THREADS_MAX
in `sysdeps/unix/sysv/linux/bits/local_lim.h' to 4096 and decreaseSTACK_SIZE
in `linuxthreads/internals.h' to 256KB. The paths are relative to the root ofglibc
. (Note that MySQL will not be stable with around 600-1000 connections ifSTACK_SIZE
is the default of 2MB.) - Recompile LinuxThreads to produce a new `libpthread.a' library, and relink MySQL against it.
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 will use 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
will occur can be reduced by renicing the @command{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 will need to apply it in the
linuxthreads
directory with
patch -p0 </tmp/linuxthreads-2.2.2.patch
.
We hope it will be 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
will be 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 @command{./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 will resolve them.
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory
This problem can be avoided by one of the following methods:
-
Link clients with the
-Wl,r/full/path/to/libmysqlclient.so
flag rather than with-Lpath
). -
Copy
libmysqclient.so
to `/usr/lib'. -
Add the pathname of the directory where `libmysqlclient.so' is located
to the
LD_RUN_PATH
environment variable before running your client.
If you are using the Fujitsu compiler (fcc/FCC
), you will have
some problems compiling MySQL because the Linux header files are very
@command{gcc} oriented.
The following @command{configure} line should work with @command{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
2.6.1.4 Linux Post-Installation Notes
@command{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.4.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 will be 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 will
be plenty of room for each individual thread stack, but small enough
to keep the stack of some threads from running into the global @command{mysqld}
data. Unfortunately, as we have experimentally discovered, the Linux
implementation of mmap()
will successfully unmap an already mapped
region if you ask it to map out an address already in use, zeroing out the data
on the entire page instead of returning an error. So, the safety of
@command{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 @command{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.6.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 @command{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 now 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 now 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 will give 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 @command{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 @command{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 [email protected] with the results. We will review them for inclusion in the manual.
If you see a dead @command{mysqld} server process with @command{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 @command{mysqld} dies with a SIGSEGV
signal,
you can start @command{mysqld} with the --core-file
option. Note
that you also probably need to raise the core file size by adding
@command{ulimit -c 1000000} to @command{mysqld_safe} or starting
@command{mysqld_safe} with --core-file-size=1000000
.
@xref{mysqld_safe, , @command{mysqld_safe}}.
2.6.1.5 Linux x86 Notes
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
@command{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 @command{mysqld} with the --thread-stack=192K
option. (Use -O thread_stack=192K
before MySQL 4.)
This stack size is now the default on MySQL 4.0.10 and above, so you should
not see the problem.
If you are using @command{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 will get an error about a missing __cxa_pure_virtual
symbol during linking.
On some older Linux distributions, @command{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 @command{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 @command{make install} and try again. This problem has been reported on some Slackware installations.
If you get the following error when linking @command{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 @command{configure} like this:
shell> CXX=gcc ./configure
If @command{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/.
2.6.1.6 Linux SPARC Notes
In some implementations, readdir_r()
is broken. The symptom is
that the SHOW DATABASES
statement always returns an empty set.
This can be fixed by removing HAVE_READDIR_R
from `config.h'
after configuring and before compiling.
2.6.1.7 Linux Alpha Notes
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 @command{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 @command{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 @command{egcs}, the following @command{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:
-
Debugging threaded applications like MySQL will not work with
gdb 4.18
. You should use @command{gdb} 5.1 instead. -
If you try linking @command{mysqld} statically when using @command{gcc}, the
resulting image will dump core at startup time. In other words, do not
use
--with-mysqld-ldflags=-all-static
with @command{gcc}.
2.6.1.8 Linux PowerPC Notes
MySQL should work on MkLinux with the newest glibc
package
(tested with glibc
2.0.7).
2.6.1.9 Linux MIPS Notes
To get MySQL to work on Qube2 (Linux Mips), you need the
newest glibc
libraries. glibc-2.0.7-29C2
is known to
work. You must also use the @command{egcs} C++ compiler
(@command{egcs} 1.0.2-9, @command{gcc} 2.95.2 or newer).
2.6.1.10 Linux IA-64 Notes
To get MySQL to compile on Linux IA-64, we use the following @command{configure} command for building with @command{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.
2.6.2 Mac OS X Notes
On Mac OS X, @command{tar} cannot handle long filenames. If you need to unpack a `.tar.gz' distribution, use @command{gnutar} instead.
2.6.2.1 Mac OS X 10.x (Darwin)
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 @command{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.2.3 Installing MySQL on Mac OS X.
2.6.2.2 Mac OS X Server 1.2 (Rhapsody)
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.2.3 Installing MySQL on Mac OS X.
2.6.3 Solaris Notes
On Solaris, you may run into trouble even before you get the MySQL distribution unpacked! Solaris @command{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 @command{tar} (@command{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.3.5 MIT-pthreads Notes.
If you get the following error from @command{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 @command{gcc} 2.95.2 or 3.2. You can find this at http://gcc.gnu.org/. Note that @command{egcs} 1.1.1 and @command{gcc} 2.8.1 don't work reliably on SPARC!
The recommended @command{configure} line when using @command{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 @command{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 @command{gcc}, add -m64
to
CFLAGS
and CXXFLAGS
and remove --enable-assembler
from
the @command{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 @command{gcc} 3.2 with the -mcpu
flag.
If you create a 64-bit @command{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 @command{configure} line
For compilers older than WorkShop 5.3, you might have to edit the @command{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 @command{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 @command{gcc} (which comes with Solaris 8),
you must add `/opt/sfw/lib' to the environment variable
LD_LIBRARY_PATH
before running @command{configure}.
If you are using the @command{gcc} available from sunfreeware.com
, you may
have many problems. To avoid this, you should recompile @command{gcc} and GNU
binutils
on the machine where you will be running them.
If you get the following error when compiling MySQL with @command{gcc}, it means that your @command{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 @command{gcc} and compile it with your current @command{gcc} compiler. At least for Solaris 2.5, almost all binary versions of @command{gcc} have old, unusable include files that will 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 will get one of the following
errors:
ld: fatal: library -ldl: not found undefined reference to `dlopen' cannot find -lrt
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#: open failed: No such file or directory
This problem can be avoided by one of the following methods:
-
Link clients with the
-Wl,r/full/path/to/libmysqlclient.so
flag rather than with-Lpath
). -
Copy
libmysqclient.so
to `/usr/lib'. -
Add the pathname of the directory where `libmysqlclient.so' is located
to the
LD_RUN_PATH
environment variable before running your client.
If you have problems with @command{configure} trying to link with -lz
when
you don't have zlib
installed, you have two options:
-
If you want to be able to use the compressed communication protocol,
you need to get and install
zlib
fromftp.gnu.org
. -
Run @command{configure} with the
--with-named-z-libs=no
option when building MySQL.
If you are using @command{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 @command{mysqld}, you will 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 @command{mysqld} if you are using the
--user
option.
2.6.3.1 Solaris 2.7/2.8 Notes
Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also apply for Solaris 2.7 and 2.8.
MySQL 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 @command{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 @command{configure} again.
If you get the following errors when you run @command{make}, it's because @command{configure} didn't detect the `curses.h' file (probably because of the error in `/usr/include/widec.h'):
In file included from mysql.cc:50: /usr/include/term.h:1060: syntax error before `,' /usr/include/term.h:1081: syntax error before `;'
The solution to this problem is to do one of the following:
-
Configure with
CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure
. - Edit `/usr/include/widec.h' as indicated in the preceding discussion and re-run @command{configure}.
-
Remove the
#define HAVE_TERM
line from the `config.h' file and run @command{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:
-
Add `/usr/local/lib' to
LD_LIBRARY_PATH
. - Add a link to `libz.so' from `/lib'.
-
If you are using Solaris 8, you can install the optional
zlib
from your Solaris 8 CD distribution. -
Run @command{configure} with the
--with-named-z-libs=no
option when building MySQL.
2.6.3.2 Solaris x86 Notes
On Solaris 8 on x86, @command{mysqld} will dump core if you remove the
debug symbols using strip
.
If you are using @command{gcc} or @command{egcs} on Solaris x86 and you experience problems with core dumps under load, you should use the following @command{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 will avoid 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 @command{gdb}. @xref{Using gdb on mysqld, , Using @command{gdb} on @command{mysqld}}.
2.6.4 BSD Notes
This section provides information about using MySQL on variants of BSD Unix.
2.6.4.1 FreeBSD Notes
FreeBSD 4.x or newer is recommended for running MySQL, because the thread
package is much more integrated.
To get a secure and stable system, you should use only FreeBSD kernels
that are marked -RELEASE
.
The easiest (and preferred) way to install MySQL is to use the
@command{mysql-server} and mysql-client
ports available at
http://www.freebsd.org/.
Using these ports gives you the following benefits:
- A working MySQL with all optimizations enabled that are known to work on your version of FreeBSD.
- Automatic configuration and build.
- Startup scripts installed in `/usr/local/etc/rc.d'.
-
The ability to use
pkg_info -L
to see which files are installed. -
The ability to use
pkg_delete
to remove MySQL if you no longer want it on your machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x, and native threads on 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 @command{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 @command{mysqld} process will suddenly cause 100%
CPU load and will be 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 (@command{gmake}) to work. If GNU @command{make} is not available, you must install it first before compiling MySQL.
The recommended way to compile and install MySQL on FreeBSD with @command{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 @command{configure} will use MIT-pthreads, you should read the MIT-pthreads notes. See section 2.3.5 MIT-pthreads Notes.
If you get an error from @command{make install} that it can't find
`/usr/include/pthreads', @command{configure} didn't detect that you need
MIT-pthreads. To fix this problem, remove `config.cache', then re-run
@command{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 @command{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 @command{mysqld_safe}, or raise
the limits for the @command{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
).
@xref{mysqld_safe, , @command{mysqld_safe}}.
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 will probably help. See section E Environment Variables.
2.6.4.2 NetBSD Notes
To compile on NetBSD, you need GNU @command{make}. Otherwise, the build process will
fail when @command{make} tries to run lint
on C++ files.
2.6.4.3 OpenBSD 2.5 Notes
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
2.6.4.4 OpenBSD 2.8 Notes
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 @command{mysqld_safe} as root
with the following
options:
mysqld_safe --user=mysql --open-files-limit=2048 &
2.6.4.5 BSD/OS Version 2.x Notes
If you get the following error when compiling MySQL, your @command{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 @command{ulimit -v 80000} and run @command{make} again. If this doesn't work and you are using @command{bash}, try switching to @command{csh} or @command{sh}; some BSDI users have reported problems with @command{bash} and @command{ulimit}.
If you are using @command{gcc}, you may also use have to use the
--with-low-memory
flag for @command{configure} to be able to compile
`sql_yacc.cc'.
If you get problems with the current date in MySQL, setting the
TZ
variable will probably help. See section E Environment Variables.
2.6.4.6 BSD/OS Version 3.x Notes
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 @command{mysqld}! This will run
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 @command{ulimit -v 80000} and running @command{make} again.
If this doesn't work and you are using @command{bash}, try switching to
@command{csh} or @command{sh}; some BSDI users have reported problems with
@command{bash} and @command{ulimit}.
2.6.4.7 BSD/OS Version 4.x Notes
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,
@command{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 @command{mysqld} binary after a while can't open tables. This is because some library/system-related bug causes @command{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 @command{configure}, remove the line #define HAVE_REALPATH
from
config.h
before running @command{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).
2.6.5 Other Unix Notes
2.6.5.1 HP-UX Version 10.20 Notes
There are a couple of small problems when compiling MySQL on HP-UX. We recommend that you use @command{gcc} instead of the HP-UX native compiler, because @command{gcc} produces better code.
We recommend using @command{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 @command{configure} line should work with @command{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 @command{configure} line should work with @command{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
2.6.5.2 HP-UX Version 11.x Notes
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 will solve the problem of getting EWOULDBLOCK
from recv()
and EBADF
from accept()
in threaded applications.
If you are using @command{gcc} 2.95.1 on an unpatched HP-UX 11.x system, you will get the 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 @command{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 @command{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 @command{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.
2.6.5.3 IBM-AIX notes
Automatic detection of xlC
is missing from Autoconf, so a number of
variables need to be set before running @command{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 @command{configure}
line, you must also remove the -qstrict
option. This is a limitation in
the IBM C compiler.
If you are using @command{gcc} or @command{egcs} to compile MySQL, you
must use the -fno-exceptions
flag, because the exception
handling in @command{gcc}/@command{egcs} is not thread-safe! (This is tested with
@command{egcs} 1.1.) There are also some known problems with IBM's assembler
that may cause it to generate bad code when used with @command{gcc}.
We recommend the following @command{configure} line with @command{egcs} and @command{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 @command{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 @command{egcs} / @command{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
will produce 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://publib.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/uname.htm.
This will give 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 @command{mysqladmin kill} or @command{mysqladmin shutdown}. Instead, the client will die 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 @command{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 @command{mysqld} process, it's not enough to just use @command{ulimit -d unlimited}. You may also have to modify @command{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.
2.6.5.4 SunOS 4 Notes
On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means you will need GNU @command{make}.
Some SunOS 4 systems have problems with dynamic libraries and @command{libtool}. You can use the following @command{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 @command{mysqld}, there will be some @code{implicit declaration of function} warnings. These can be ignored.
2.6.5.5 Alpha-DEC-UNIX Notes (Tru64)
If you are using @command{egcs} 1.1.2 on Digital Unix, you should upgrade to @command{gcc} 2.95.2, because @command{egcs} on DEC has some serious bugs!
When compiling threaded programs under Digital Unix, the documentation
recommends using the -pthread
option for @command{cc} and @command{cxx} and
the -lmach -lexc
libraries (in addition to -lpthread
). You
should run @command{configure} something like this:
CC="cc -pthread" CXX="cxx -pthread -O" \ ./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"
When compiling @command{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 @command{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
@command{mysqld_safe}, which invokes @command{mysqld} using @command{nohup} for you.
@xref{mysqld_safe, , @command{mysqld_safe}}.
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 @command{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 @command{libtool} when compiling with shared libraries as just shown, when linking @command{mysql}, you should be able to get around this by issuing these commands:
cd mysql /bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \ -O4 -ansi_alias -ansi_args -fast -inline speed \ -speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \ -o mysql mysql.o readline.o sql_string.o completion_hash.o \ ../readline/libreadline.a -lcurses \ ../libmysql/.libs/libmysqlclient.so -lm cd .. gnumake gnumake install scripts/mysql_install_db
2.6.5.6 Alpha-DEC-OSF/1 Notes
If you have problems compiling and have DEC @command{CC} and @command{gcc} installed, try running @command{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 @command{mysqld}). On this system, we
have managed to compile MySQL with the following @command{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.
@command{configure} will use the following thread libraries automatically:
--with-named-thread-libs="-lpthread -lmach -lexc -lc"
.
When using @command{gcc}, you can also try running @command{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 @command{mysqladmin kill} or @command{mysqladmin shutdown}. Instead, the client will die when it issues its next command.
With @command{gcc} 2.95.2, you will probably run into 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 @command{gcc} line, but change -O3
to
-O0
(or add -O0
immediately after @command{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 @command{make}
again.
2.6.5.7 SGI Irix Notes
If you are using Irix Version 6.5.3 or newer, @command{mysqld} will be able to
create threads only if you run it as a user that has CAP_SCHED_MGT
privileges (such as root
) or give the @command{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 @command{configure} and before compiling.
In some Irix implementations, the alloca()
function is broken. If the
@command{mysqld} server dies on some SELECT
statements, remove the lines
from `config.h' that define HAVE_ALLOC
and HAVE_ALLOCA_H
.
If @command{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 @command{gcc}, you can use the following @command{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
2.6.5.8 SCO Notes
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) will have native threads and allow files greater than 2GB. The current maximum file size is 2GB.
We have been able to compile MySQL with the following @command{configure} command on on OpenServer with @command{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
@command{gcc} is available at ftp://ftp.sco.com/pub/openserver5/opensrc/gnutools-5.0.7Kj.
This development system requires the OpenServer Execution Enviroment 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. Currently MySQL-4.0.x is the latest production release. There were some problems with MySQL 4.0.17 and MySQL 4.0.18, but they have now been fixed.
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.
-
Log in as
root
. -
Enable the SUDS driver by editing the `/etc/conf/sdevice.d/suds' file.
Change the
N
in the second field to aY
. -
Use
mkdev aio
or the Hardware/Kernel Manager to enable support for asynchronous I/O and relink the kernel. To allow users to lock down memory for use with this type of I/O, update the aiomemlock(F) file. This file should be updated to include the names of users that can use AIO and the maximum amounts of memory they can lock down. - Many applications use setuid binaries so that you need to specify only a single user. See the documentation provided with the application to see if this is the case for your application.
After you complete this process, reboot the system to create a new kernel incorporating these changes.
By default, the entries in `/etc/conf/cf.d/mtune' are set as follows:
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 @command{./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 will affect the following 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 will be 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 @command{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 will 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 will 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 @command{make}. The `Makefile' in FSU-threads-3.14.tar.gz is already set up to make FSU-threads.
You can run @command{./configure} in the `threads/src' directory and select the SCO OpenServer option. This command copies `Makefile.SCO5' to `Makefile'. Then run @command{make}.
To install in the default `/usr/include' directory, log in as
root
, then cd
to the `thread/src' directory and run
@command{make install}.
Remember that you must use GNU @command{make} when making MySQL.
Note: If you don't start @command{mysqld_safe} as root
, you
probably will get only the default 110 open files per process. @command{mysqld}
will write 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 @command{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:
-
MySQL should automatically detect FSU Pthreads and link @command{mysqld} with
-lgthreads -lsocket -lgthreads
. - The SCO development libraries are re-entrant in FSU Pthreads. SCO claims that its library functions are re-entrant, so they must be re-entrant with FSU Pthreads. FSU Pthreads on OpenServer tries to use the SCO scheme to make re-entrant libraries.
-
FSU Pthreads (at least the version at ftp::/ftp.zenez.com) comes
linked with GNU
malloc
. If you encounter problems with memory usage, make sure that `gmalloc.o' is included in `libgthreads.a' and `libgthreads.so'. -
In FSU Pthreads, the following system calls are pthreads-aware:
read()
,write()
,getmsg()
,connect()
,accept(),
select()
, andwait()
. - The CSSA-2001-SCO.35.2 (the patch is listed in custom as erg711905-dscr_remap security patch (version 2.0.0)) breaks FSU threads and makes @command{mysqld} unstable. You have to remove this one if you want to run @command{mysqld} on an OpenServer 5.0.6 machine.
- SCO provides operating system patches at ftp://ftp.sco.com/pub/openserver5 for OpenServer 5.0.x.
-
SCO provides security fixes and
libsocket.so.2
at ftp://ftp.sco.com/pub/security/OpenServer and ftp://ftp.sco.com/pub/security/sse for OpenServer 5.0.x. -
Pre-OSR506 security fixes. Also, the
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.
Begining with Legend, OpenServer will have native threads and no 2GB file size limit.
2.6.5.9 SCO UnixWare Version 7.1.x Notes
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 @command{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 @command{gcc}, you must use @command{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 will affect the following 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 will be running on the system at one time.
SEMMNU
= SEMMNS
Set the value of SEMMNU
to equal the value of SEMMNS
. You
could probably set this to 75% of SEMMNS
, but this is a conservative estimate.
2.6.6 OS/2 Notes
MySQL uses quite a few open files. Because of this, you should add something like the following to your `CONFIG.SYS' file:
SET EMXOPT=-c -n -h1024
If you don't do this, you will probably run into 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 now called `install.cmd' and is a REXX script, which will set up the default MySQL security settings and create 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 will put 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';
2.6.7 BeOS Notes
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.
2.7 Perl Installation Notes
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 will 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.
2.7.1 Installing Perl on Unix
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 will 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 already 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 @command{tar} archives and build the modules manually. For example, to unpack and build a DBI distribution, use a procedure such as this:
-
Unpack the distribution into the current directory:
shell> gunzip < DBI-VERSION.tar.gz | tar xvf -
This command creates a directory named `DBI-VERSION'. -
Change location into the top-level directory of the unpacked distribution:
shell> cd DBI-VERSION
-
Build the distribution and compile everything:
shell> perl Makefile.PL shell> make shell> make test shell> make install
The @command{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 will fail.
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.''
2.7.2 Installing ActiveState Perl on Windows
On Windows, you should do the following to install the MySQL
DBD
module with ActiveState Perl:
- Get ActiveState Perl from http://www.activestate.com/Products/ActivePerl/ and install it.
- Open a console window (a ``DOS window'').
-
If required, set the
HTTP_proxy
variable. For example, you might try:set HTTP_proxy=my.proxy.com:3128
-
Start the PPM program:
C:\> C:\perl\bin\ppm.pl
-
If you have not already done so, install
DBI
:ppm> install DBI
-
If this succeeds, run the following command:
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";
2.7.3 Problems Using the Perl DBI
/DBD
Interface
If 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:
-
Compile the
DBD::mysql
distribution withperl Makefile.PL -static -config
rather thanperl Makefile.PL
. - Copy `libmysqlclient.so' to the directory where your other shared libraries are located (probably `/usr/lib' or `/lib').
-
Modify the
-L
options used to compileDBD::mysql
to reflect the actual location of `libmysqlclient.so'. - On Linux, you can add the pathname of the directory where `libmysqlclient.so' is located to the `/etc/ld.so.conf' file.
-
Add the pathname of the directory where `libmysqlclient.so' is located
to the
LD_RUN_PATH
environment variable. Some systems useLD_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 @command{gcc} (or using an old binary compiled with
@command{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 @command{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 @command{gcc}. In this case, you can solve the mismatch by compiling both with @command{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 @command{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 @command{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 will not load the DBI
modules
if they were compiled with @command{icc} or @command{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 @command{make perl} will indicate the exact @command{make} command you will need to execute to perform the installation. On SCO, this is @command{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 @command{make perl} indicates the command to use.
3 MySQL Tutorial
This chapter provides a tutorial introduction to MySQL by showing how to use the @command{mysql} client program to create and use a simple database. @command{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. @command{mysql} may also be used in batch mode: you place your queries in a file beforehand, then tell @command{mysql} to execute the contents of the file. Both ways of using @command{mysql} are covered here.
To see a list of options provided by @command{mysql}, invoke it with
the --help
option:
shell> mysql --help
This chapter assumes that @command{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 will 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 already-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.
3.1 Connecting to and Disconnecting from the Server
To connect to the server, you'll usually need to provide a MySQL username when you invoke @command{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 @command{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 @command{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 @command{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.
3.2 Entering Queries
Make sure that you are connected to the server, as discussed in the previous section. Doing so will 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 @command{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 @command{mysql}:
-
A command normally consists of an SQL statement followed by a semicolon.
(There are some exceptions where a semicolon may be omitted.
QUIT
, mentioned earlier, is one of them. We'll get to others later.) -
When you issue a command, @command{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. - @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), @command{mysql} labels the column using the expression itself.
- @command{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 @command{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. @command{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, @command{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 | +--------------------+--------------+ | [email protected] | 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 @command{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 will always be aware of
what @command{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 @command{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 @command{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, @command{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 @command{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 realising what you need to do. Enter a semicolon to
complete the statement, and @command{mysql} will execute it:
mysql> SELECT USER() -> ; +--------------------+ | USER() | +--------------------+ | [email protected] | +--------------------+
The '>
and ">
prompts occur during string collection.
In MySQL, you can write strings surrounded by either `''
or `"' characters (for example, 'hello'
or "goodbye"
),
and @command{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 inadvertantly 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 will happen. Instead of wondering why this
query takes so long, notice the clue provided by the '>
prompt. It
tells you that @command{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 @command{mysql}
interprets it as part of the string that it is collecting! Instead, enter
the closing quote character (so @command{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 @command{mysql}
is ready for a new command.
The `>
prompt is similar to th '>
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 will appear to be ignored by @command{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.
3.3 Creating and Using a Database
Now that 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:
- Create a database
- Create a table
- Load data into the table
- Retrieve data from the table in various ways
- Use multiple tables
The menagerie database will be 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 @command{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 14.5.1.2 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.
3.3.1 Creating and Selecting a Database
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 @command{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 @command{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.
3.3.2 Creating a Table
Creating the database is the easy part, but at this point it's empty, as
SHOW TABLES
will tell 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 will need and what columns will 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 use the database for tasks such as generating reminders for upcoming pet birthdays. (If you think this type of query is somewhat silly, note that it is the same question you might ask in the context of a business database to identify clients to whom you'll soon need to send out birthday greetings, for that computer-assisted personal touch.)
- You can calculate age in relation to dates other than the current date. For example, if you store death date in the database, you can easily calculate how old a pet was when it died.
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 for now:
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 will 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.
Now that 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.
3.3.3 Loading Data into a Table
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.
3.3.4 Retrieving Information from a Table
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.
3.3.4.1 Selecting All Data
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:
-
Edit the file `pet.txt' to correct the error, then empty the table
and reload it using
DELETE
andLOAD 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. -
Fix only the erroneous record with an
UPDATE
statement:mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';
TheUPDATE
changes only the record in question and does not require you to reload the table.
3.3.4.2 Selecting Particular Rows
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 now as 1989, not 1979.
String comparisons normally are case-insensitive, so you can specify the
name as 'bowser'
, 'BOWSER'
, etc. The query result will be
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 | +-------+--------+---------+------+------------+-------+
3.3.4.3 Selecting Particular Columns
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 | +--------+---------+------------+
3.3.4.4 Sorting Rows
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 will be 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.
3.3.4.5 Date Calculations
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
).
3.3.4.6 Working with 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.
3.3.4.7 Pattern Matching
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:
- `.' matches any single character.
- A character class `[...]' matches any character within the brackets. For example, `[abc]' matches `a', `b', or `c'. To name a range of characters, use a dash. `[a-z]' matches any letter, whereas `[0-9]' matches any digit.
- `*' matches zero or more instances of the thing preceding it. For example, `x*' matches any number of `x' characters, `[0-9]*' matches any number of digits, and `.*' matches any number of anything.
-
A
REGEXP
pattern match succeed if the pattern matches anywhere in the value being tested. (This differs from aLIKE
pattern match, which succeeds only if the pattern matches the entire value.) - To anchor a pattern so that it must match the beginning or end of the value being tested, use `^' at the beginning or `$' at the end of the pattern.
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 will match 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 | +-------+--------+---------+------+------------+-------+
3.3.4.8 Counting Rows
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 | +---------+------+----------+
3.3.4.9 Using More Than one Table
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:
- To contain the pet name so you know which animal each event pertains to.
- A date so you know when the event occurred.
- A field to describe the event.
- An event type field, if you want to be able to categorize events.
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:
-
The
FROM
clause lists two tables because the query needs to pull information from both of them. -
When combining (joining) information from multiple tables, you need to
specify how records in one table can be matched to records in the other.
This is easy because they both have a
name
column. The query usesWHERE
clause to match up records in the two tables based on thename
values. -
Because the
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.
3.4 Getting Information About Databases and Tables
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 already 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.
3.5 Using @command{mysql} in Batch Mode
In the previous sections, you used @command{mysql} interactively to enter queries and view the results. You can also run @command{mysql} in batch mode. To do this, put the commands you want to run in a file, then tell @command{mysql} to read its input from the file:
shell> mysql < batch-file
If you are running @command{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 @command{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:
- If you run a query repeatedly (say, every day or every week), making it a script allows you to avoid retyping it each time you execute it.
- You can generate new queries from existing ones that are similar by copying and editing script files.
- Batch mode can also be useful while you're developing a query, particularly for multiple-line commands or multiple-statement sequences of commands. If you make a mistake, you don't have to retype everything. Just edit your script to correct the error, then tell @command{mysql} to execute it again.
-
If you have a query that produces a lot of output, you can run the output
through a pager rather than watching it scroll off the top of your screen:
shell> mysql < batch-file | more
-
You can catch the output in a file for further processing:
shell> mysql < batch-file > mysql.out
- You can distribute your script to other people so they can run the commands, too.
- Some situations do not allow for interactive use, for example, when you run a query from a @command{cron} job. In this case, you must use batch mode.
The default output format is different (more concise) when you run
@command{mysql} in batch mode than when you use it interactively. For
example, the output of SELECT DISTINCT species FROM pet
looks like
this when @command{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 @command{mysql} prompt by
using the source
or \.
command:
mysql> source filename; mysql> \. filename
3.6 Examples of Common Queries
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 @command{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 | +---------+--------+-------+
3.6.1 The Maximum Value for a Column
``What's the highest item number?''
SELECT MAX(article) AS article FROM shop; +---------+ | article | +---------+ | 4 | +---------+
3.6.2 The Row Holding the Maximum of a Certain Column
``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:
-
Get the maximum price value from the table with a
SELECT
statement.mysql> SELECT MAX(price) FROM shop; +------------+ | MAX(price) | +------------+ | 19.95 | +------------+
-
Using the value 19.95 shown by the previous query to be the maximum
article price, write a query to locate and display the corresponding record:
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!
3.6.3 Maximum of Column per Group
``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 | +---------+-------+
3.6.4 The Rows Holding the Group-wise Maximum of a Certain Field
``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:
- Get the list of (article,maxprice) pairs.
- For each article, get the corresponding rows that have the stored maximum price.
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.
3.6.5 Using User Variables
You can use MySQL user variables to remember results without having to store them in temporary variables in the client. See section 10.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 [email protected]_price OR [email protected]_price; +---------+--------+-------+ | article | dealer | price | +---------+--------+-------+ | 0003 | D | 1.25 | | 0004 | D | 19.95 | +---------+--------+-------+
3.6.6 Using Foreign Keys
In MySQL 3.23.44 and up, InnoDB
tables support checking of
foreign key constraints. See section 16 The InnoDB
Storage Engine.
See also section 1.8.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 will work 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'); INSERT INTO shirt VALUES (NULL, 'polo', 'blue', LAST_INSERT_ID()), (NULL, 'dress', 'white', LAST_INSERT_ID()), (NULL, 't-shirt', 'blue', LAST_INSERT_ID()); INSERT INTO person VALUES (NULL, 'Lilliana Angelovska'); INSERT INTO shirt VALUES (NULL, 'dress', 'orange', LAST_INSERT_ID()), (NULL, 'polo', 'red', LAST_INSERT_ID()), (NULL, 'dress', 'blue', LAST_INSERT_ID()), (NULL, 't-shirt', 'white', LAST_INSERT_ID()); 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 | +----+-------+--------+-------+
3.6.7 Searching on Two Keys
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 14.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.
3.6.8 Calculating Visits Per Day
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.
3.6.9 Using 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()
will actually return 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 will be 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.)
3.7 Queries from the Twin Project
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.
3.7.1 Find All Non-distributed Twins
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 sceening 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
-
We want to sort on the concatenated
id
andtvab
in numerical order. Adding0
to the result causes MySQL to treat the result as a number. - column
id
- This identifies a pair of twins. It is a key in all tables.
- column
tvab
-
This identifies a twin in a pair. It has a value of
1
or2
. - column
ptvab
-
This is an inverse of
tvab
. Whentvab
is1
this is2
, 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 |
3.7.2 Show a Table of Twin Pair Status
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 sceening 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;
3.8 Using MySQL with Apache
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.
4 Using MySQL Programs
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.
4.1 Overview of MySQL Programs
MySQL AB provides several types of programs:
- The MYSQL server and server startup scripts:
-
- @command{mysqld} is the MySQL server
- @command{mysqld_safe}, @command{mysql.server}, and @command{mysqld_multi} are server startup scripts
- @command{mysql_install_db} initializes the data directory and the initial databases
- Client programs that access the server:
-
- @command{mysql} is a command-line client for executing SQL statements interactively or in batch mode
- @command{mysqlcc} (MySQL Control Center) is an interactive graphical tool for executing SQL statements and administration
- @command{mysqladmin} is an administrative client
- @command{mysqlcheck} performs table maintenance operations
- @command{mysqldump} and @command{mysqlhotcopy} make database backups
- @command{mysqlimport} imports data files
- @command{mysqlshow} displays information about databases and tables
- Utility programs that operate independently of the server:
-
- @command{myisamchk} performs table maintenance operations
- @command{myisampack} produces compressed, read-only tables
- @command{mysqlbinlog} is a tool for processing binary log files
- @command{perror} displays error code meanings
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.
4.2 Invoking MySQL Programs
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 will see depends on your command interpreter.
Typical prompts are $
for @command{sh} or @command{bash}, %
for
@command{csh} or @command{tcsh}, and C:\>
for Windows
@command{command.com} or @command{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 @command{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.
4.3 Specifying Program Options
You can provide options for MySQL programs in several ways:
- On the command line following the program name. This is most common for options that apply to a specific invocation of the program.
- In an option file that the program reads when it starts. This is common for options that you want the program to use each time it runs.
- In environment variables. These are useful for options that you want to apply each time the program runs, although in practice option files are used more commonly for this purpose. (section 5.10.2 Running Multiple Servers on Unix discusses one situation in which environment variables can be very helpful. It describes a handy technique that uses such variables to specify the TCP/IP port number and Unix socket file for both the server and client programs.)
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.
4.3.1 Using Options on the Command Line
Program options specified on the command line follow these rules:
- Options are given after the command name.
-
An option argument begins with one dash or two dashes, depending on whether
it has a short name or a long name. Many options have both forms.
For example,
-?
and--help
are the short and long forms of the option that instructs a MySQL program to display a help message. -
Option names are case sensitive.
-v
and-V
are both legal and have different meanings. (They are the corresponding short forms of the--verbose
and--version
options.) -
Some options take a value following the option name.
For example,
-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. -
For a long option that takes a value, separate the option name and the value by an `=' sign.
For a short option that takes a value, the option value can immediately follow the option letter,
or there can be a space between.
(
-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 will prompt 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 test
The first command instructs @command{mysql} to use a password value oftest
, but specifies no default database. The second instructs @command{mysql} to prompt for the password value and to usetest
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 @command{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 @command{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 will not exit with
an error if it does not recognize the option, but instead will issue
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 will 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.
4.3.2 Using Option Files
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: @command{myisamchk}, @command{myisampack}, @command{mysql}, @command{mysql.server}, @command{mysqladmin}, @command{mysqlbinlog}, @command{mysqlcc}, @command{mysqlcheck}, @command{mysqld_safe}, @command{mysqldump}, @command{mysqld}, @command{mysqlhotcopy}, @command{mysqlimport}, and @command{mysqlshow}.
On Windows, MySQL programs read startup options from the following files:
Filename | Purpose |
WINDIR\my.ini | Global options |
C:\my.cnf | 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%
On Unix, MySQL programs read startup options from the following files:
Filename | Purpose |
/etc/my.cnf | Global options |
DATADIR/my.cnf | Server-specific options |
defaults-extra-file | The file specified with --defaults-extra-file=path , if any
|
~/.my.cnf | User-specific options |
DATADIR represents the location of the MySQL data directory. 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 @command{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
- Comment lines start with `#' or `;'. As of MySQL 4.0.14, a `#'-comment can start in the middle of a line as well.
[group]
-
group is the name of the program or group for which you want to set
options. After a group line, any opt_name or
set-variable
lines apply to the named group until the end of the option file or another group line is given. opt_name
-
This is equivalent to
--opt_name
on the command line. opt_name=value
-
This is equivalent to
--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 the program variable var_name to the given value.
This is equivalent to
--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 @command{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 will 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 @command{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 will 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). 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
- Don't read any option files.
--print-defaults
- Print the program name and all options that it will get from option files.
--defaults-file=path_name
- Use only the given option file. path_name is the full pathname to the file.
--defaults-extra-file=path_name
- Read this option file after the global option file but before the user option file. path_name is the full pathname to the file.
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 @command{my_print_defaults} program to parse
option files. The following example shows the output that
@command{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.
4.3.3 Using Environment Variables to Specify Options
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. The syntax for
Bourne shell and variants (@command{sh}, @command{bash}, @command{zsh}, etc.) is:
MYSQL_TCP_PORT=3306
For @command{csh} and @command{tcsh}, use this syntax:
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 @command{bash}, or `.tcshrc' for @command{tcsh}. Consult the documentation for your command interpreter for specific details.
section E Environment Variables lists all environment variables that affect MySQL program operation.
4.3.4 Using Options to Set Program Variables
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, @command{mysql} has a max_allowed_packet
variable that
controls the maximum size of its communication buffer.
To set the max_allowed_packet
variable for @command{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.
5 Database Administration
This chapter covers topics that deal with administering a MySQL installation, such as configuring the server, managing user accounts, and performing backups.
5.1 The MySQL Server and Server Startup Scripts
The MySQL server, @command{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.
5.1.1 Overview of the Server-Side Scripts and Utilities
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
@command{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
- The SQL daemon (that is, the MySQL server). To use client programs, this program must be running, because clients gain access to databases by connecting to the server. See section 5.2 Configuring the MySQL Server.
mysqld-max
- A version of the server that includes additional features. @xref{mysqld-max, , @command{mysqld-max}}.
mysqld_safe
- A server startup script. @command{mysqld_safe} attempts to start @command{mysqld-max} if it exists, and @command{mysqld} otherwise. @xref{mysqld_safe, , @command{mysqld_safe}}.
mysql.server
- A server startup script. This script is used on systems that use run directories containing scripts that start system services for particular run levels. It invokes @command{mysqld_safe} to start the MySQL server. @xref{mysql.server, , @command{mysql.server}}.
mysqld_multi
- A server startup script that can start or stop multiple servers installed on the system. @xref{mysqld_multi, , @command{mysqld_multi}}.
mysql_install_db
- This script creates the MySQL grant tables with default privileges. It is usually executed only once, when first installing MySQL on a system.
mysql_fix_privilege_tables
- This script is used after an upgrade install operation, to update the grant tables with any changes that have been made in newer versions of MySQL.
There are several other programs that also are run on the server host:
myisamchk
-
A utility to describe, check, optimize, and repair
MyISAM
tables. @command{myisamchk} is described in section 5.7.2 Table Maintenance and Crash Recovery. make_binary_distribution
-
This program makes a binary release of a compiled MySQL. This could be sent
by FTP to `/pub/mysql/upload/' on
ftp.mysql.com
for the convenience of other MySQL users. mysqlbug
- The MySQL bug reporting script. It can be used to send a bug report to the MySQL mailing list. (You can also visit http://bugs.mysql.com/ to file a bug report online.)
5.1.2 The @command{mysqld-max} Extended MySQL Server
A MySQL-Max server is a version of the @command{mysqld} MySQL server that has been built to include additional features.
The distribution to use depends on your platform:
-
For Windows, MySQL binary distributions include both the standard server
(
mysqld.exe
) and the MySQL-Max server (@command{mysqld-max.exe}), so you need not get a special distribution. Just use a regular Windows distribution, available at http://dev.mysql.com/downloads/mysql-4.0.html. See section 2.2.1 Installing MySQL on Windows. -
For Linux, if you install MySQL using RPM distributions, use the regular
MySQL-server
RPM first to install a standard server named @command{mysqld}. Then use theMySQL-Max
RPM to install a server named @command{mysqld-max}. TheMySQL-Max
RPM presupposes that you have already installed the regular server RPM. See section 2.2.2 Installing MySQL on Linux for more information on the Linux RPM packages. - All other MySQL-Max distributions contain a single server that is named @command{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 @command{configure} options:
--with-server-suffix=-max
-
This option adds a
-max
suffix to the @command{mysqld} version string. --with-innodb
-
This option enables support for the
InnoDB
storage engine. MySQL-Max servers always includeInnoDB
support, but this option actually is needed only for MySQL 3.23. From MySQL 4 on,InnoDB
is included by default in binary distributions, so you do not need a MySQL-Max server to obtainInnoDB
support. --with-bdb
-
This option enables support for the Berkeley DB (
BDB
) storage engine. CFLAGS=-DUSE_SYMDIR
- This define enables symbolic link support for Windows.
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
. The following
table shows which platforms allow MySQL-Max binaries to include BDB
:
System | BDB Support
|
AIX 4.3 | N |
HP-UX 11.0 | N |
Linux-Alpha | N |
Linux-IA-64 | N |
Linux-Intel | Y |
Mac OS X | N |
NetWare | N |
SCO OSR5 | Y |
Solaris-Intel | N |
Solaris-SPARC | Y |
UnixWare | Y |
Windows/NT | Y |
To find out which storage engines your server supports, issue the following statement:
mysql> SHOW ENGINES;
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_bdb | NO | | have_crypt | YES | | have_innodb | YES | | have_isam | NO | | have_raid | NO | | have_symlink | DISABLED | | have_openssl | NO | | have_query_cache | YES | +------------------+----------+
The values in the second column indicate the server's level of support for each feature:
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 16.3 InnoDB
in MySQL 3.23.
You can specify configuration options for the BDB
storage engine, too,
but BDB
will not disable itself if you do not provide them.
See section 15.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.
5.1.3 The @command{mysqld_safe} Server Startup Script
@command{mysqld_safe} is the recommended way to start a @command{mysqld} server on Unix and NetWare. @command{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, @command{mysqld_safe} is named @command{safe_mysqld}. To preserve backward compatibility, MySQL binary distributions for some time will include @command{safe_mysqld} as a symbolic link to @command{mysqld_safe}.
By default, @command{mysqld_safe} tries to start an executable named @command{mysqld-max} if it exists, or @command{mysqld} otherwise. Be aware of the implications of this behavior:
-
On Linux, the
MySQL-Max
RPM relies on this @command{mysqld_safe} behavior. The RPM installs an executable named @command{mysqld-max}, which causes @command{mysqld_safe} to automatically use that executable from that point on. - If you install a MySQL-Max distribution that includes a server named @command{mysqld-max}, then upgrade later to a non-Max version of MySQL, @command{mysqld_safe} will still attempt to run the old @command{mysqld-max} server. If you perform such an upgrade, you should manually remove the old @command{mysqld-max} server to ensure that @command{mysqld_safe} runs the new @command{mysqld} server.
To override the default behavior and specify explicitly which server you
want to run, specify a --mysqld
or --mysqld-version
option to
@command{mysqld_safe}.
Many of the options to @command{mysqld_safe} are the same as the options to @command{mysqld}. See section 5.2.1 @command{mysqld} Command-Line Options.
All options specified to @command{mysqld_safe} on the command line are
passed to @command{mysqld}. If you want to use any options that are specific
to @command{mysqld_safe} and that @command{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.
@command{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.
@command{mysqld_safe} supports the following options:
--basedir=path
- The path to the MySQL installation directory.
--core-file-size=size
- The size of the core file @command{mysqld} should be able to create. The option value is passed to @command{ulimit -c}.
--datadir=path
- The path to the data directory.
--defaults-extra-file=path
- The name of an option file to be read in addition to the usual option files.
--defaults-file=path
- The name of an option file to be read instead of the usual option files.
--err-log=path
-
The old form of the
--log-error
option, to be used before MySQL 4.0. --ledir=path
- The path to the directory containing the @command{mysqld} program. Use this option to explicitly indicate the location of the server.
--log-error=path
- Write the error log to the given file. See section 5.9.1 The Error Log.
--mysqld=prog_name
-
The name of the server program (in the
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
-
This option is similar to the
--mysqld
option, but you specify only the suffix for the server program name. The basename is assumed to be @command{mysqld}. For example, if you use--mysqld-version=max
, @command{mysqld_safe} will start the @command{mysqld-max} program in theledir
directory. If the argument to--mysqld-version
is empty, @command{mysqld_safe} uses @command{mysqld} in theledir
directory. --nice=priority
-
Use the
nice
program to set the server's scheduling priority to the given value. This option was added in MySQL 4.0.14. --no-defaults
- Do not read any option files.
--open-files-limit=count
-
The number of files @command{mysqld} should be able to open. The option value
is passed to @command{ulimit -n}. Note that you need to start
@command{mysqld_safe} as
root
for this to work properly! --pid-file=path
- The path to the process ID file.
--port=port_num
- The port number to use when listening for TCP/IP connections.
--socket=path
- The Unix socket file to use for local connections.
--timezone=zone
-
Set the
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}
- Run the @command{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 @command{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.) @command{mysqld_safe} expects one of the following conditions to be true:
- The server and databases can be found relative to the directory from which @command{mysqld_safe} is invoked. For binary distributions, @command{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 @command{mysqld_safe} from your MySQL installation directory (for example, `/usr/local/mysql' for a binary distribution).
- If the server and databases cannot be found relative to the working directory, @command{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 @command{mysqld_safe} will try 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 @command{mysqld_safe} from the MySQL installation directory:
shell> cd mysql_installation_directory shell> bin/mysqld_safe &
If @command{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 @command{mysqld_safe} script. Instead,
configure @command{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 @command{mysqld_safe} to get it to start the server
properly. However, if you do this, your modified version of
@command{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, @command{mysqld_safe} is a NetWare Loadable Module (NLM) that is ported from the original Unix shell script. It does the following:
- Runs a number of system and option checks.
-
Runs a check on
MyISAM
andISAM
tables. - Provides a screen presence for the MySQL server.
- Starts @command{mysqld}, monitors it, and restarts it if it terminates in error.
- Sends error messages from @command{mysqld} to the `host_name.err' file in the data directory.
- Sends @command{mysqld_safe} screen output to the `host_name.safe' file in the data directory.
5.1.4 The @command{mysql.server} Server Startup Script
MySQL distributions on Unix include a script named @command{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.
@command{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 @command{mysql.server} script will already have been installed in the
`/etc/init.d' directory with the name `mysql'. You need not
install it manually. See section 2.2.2 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 @command{mysqld}.
If you install MySQL from a source distribution or using a binary distribution format that does not install @command{mysql.server} automatically, you can install it manually. Instructions are provided in section 2.4.2.2 Starting and Stopping MySQL Automatically.
@command{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.)
5.1.5 The @command{mysqld_multi} Program for Managing Multiple MySQL Servers
@command{mysqld_multi} is meant for managing several @command{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 @command{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 @command{mysqld}. (See, for example,
section 2.4.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 @command{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, @command{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
@command{mysqld_multi} supports the following options:
--config-file=name
-
Specify the name of an alternative option file. This affects where
@command{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 @command{mysqld_multi} reads its own options, which are always taken from the[mysqld_multi]
group in the usual `my.cnf' file. --example
- Display a sample option file.
--help
- Display a help message and exit.
--log=name
- Specify the name of the log file. If the file exists, log output is appended to it.
--mysqladmin=prog_name
- The @command{mysqladmin} binary to be used to stop servers.
--mysqld=prog_name
-
The @command{mysqld} binary to be used. Note that you can specify
@command{mysqld_safe} as the value for this option also. The options are passed
to @command{mysqld}. Just make sure that you have the directory where @command{mysqld} is
located in your
PATH
environment variable setting or fix @command{mysqld_safe}. --no-log
- Print log information to stdout rather than to the log file. By default, output goes to the log file.
--password=password
- The password of the MySQL account to use when invoking @command{mysqladmin}. Note that the password value is not optional for this option, unlike for other MySQL programs.
--tcp-ip
-
Connect to each MySQL server via the TCP/IP port instead of the Unix socket
file. (If a socket file is missing, the server might still be running,
but accessible only via the TCP/IP port.) By default, connections are
made using the Unix socket file. This option affects
stop
andreport
operations. --user=user_name
- The username of the MySQL account to use when invoking @command{mysqladmin}.
--version
- Display version information and exit.
Some notes about @command{mysqld_multi}:
-
Make sure that the MySQL account used for stopping the @command{mysqld} servers
(with the @command{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 commonmulti_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 will have to do this for each @command{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 asmulti_admin
from the host where you want to run @command{mysqld_multi}. -
The
--pid-file
option is very important if you are using @command{mysqld_safe} to start @command{mysqld} (for example,--mysqld=mysqld_safe
) Every @command{mysqld} should have its own process ID file. The advantage of using @command{mysqld_safe} instead of @command{mysqld} is that @command{mysqld_safe} ``guards'' its @command{mysqld} process and will restart it if the process terminates due to a signal sent usingkill -9
, or for other reasons, such as a segmentation fault. Please note that the @command{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 @command{mysqld_multi}. If you have problems starting, please see the @command{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 ----------------------------------------------------------------
@xref{mysqld_safe, , @command{mysqld_safe}}. The test performed by these lines should be successful, or you might encounter problems. - The Unix socket file and the TCP/IP port number must be different for every @command{mysqld}.
-
You might want to use the
--user
option for @command{mysqld}, but in order to do this you need to run the @command{mysqld_multi} script as the Unixroot
user. Having the option in the option file doesn't matter; you will just get a warning, if you are not the superuser and the @command{mysqld} processes are started under your own Unix account. - Important: Make sure that the data directory is fully accessible to the Unix account that the specific @command{mysqld} process is started as. Do not use the Unix root account for this, unless you know what you are doing.
- Most important: Before using @command{mysqld_multi} be sure that you understand the meanings of the options that are passed to the @command{mysqld} servers and why you would want to have separate @command{mysqld} processes. Beware of the dangers of using multiple @command{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 will 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
@command{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 @command{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.
5.2 Configuring the MySQL Server
This section discusses MySQL server configuration topics:
- Startup options that the server supports
- How to set the server SQL mode
- Server system variables
- Server status variables
5.2.1 @command{mysqld} Command-Line Options
When you start the @command{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.
@command{mysqld} reads options from the [mysqld]
and [server]
groups. @command{mysqld_safe} reads options from the [mysqld]
,
[server]
, [mysqld_safe]
, and [safe_mysqld]
groups. @command{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.
@command{mysqld} accepts many command-line options.
For a list, execute @command{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 @command{mysqld --verbose --help}.
The following list shows some of the most common server options. Additional options are described elsewhere:
- Options that affect security: See section 5.4.3 Startup Options for @command{mysqld} Concerning Security.
- SSL-related options: See section 5.6.7.5 SSL Command-Line Options.
- Binary log control options: See section 5.9.4 The Binary Log.
- Replication-related options: See section 6.8 Replication Startup Options.
-
Options specific to particular storage engines:
See section 15.1.1
MyISAM
Startup Options, section 15.4.3BDB
Startup Options, section 16.5InnoDB
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, -?
-
Display a short help message and exit.
Before MySQL 4.1.1,
--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. --ansi
-
Use standard SQL syntax instead of MySQL syntax. See section 1.8.3 Running MySQL in ANSI Mode.
For more precise control over the server SQL mode, use the
--sql-mode
option instead. --basedir=path, -b path
- The path to the MySQL installation directory. All paths are usually resolved relative to this.
--big-tables
- Allow large result sets by saving all temporary sets in files. This option prevents most ``table full'' errors, but also slows down queries for which in-memory tables would suffice. Since MySQL 3.23.2, the server is able to handle large result sets automatically by using memory for small temporary tables and switching to disk tables where necessary.
--bind-address=IP
- The IP address to bind to.
--console
-
Write the error log messages to stderr/stdout even if
--log-error
is specified. On Windows, @command{mysqld} will not close the console screen if this option is used. --character-sets-dir=path
- The directory where character sets are installed. See section 5.8.1 The Character Set Used for Data and Sorting.
--chroot=path
-
Put the @command{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 achroot()
jail that is 100% closed.) Note that use of this option somewhat limitsLOAD DATA INFILE
andSELECT ... INTO OUTFILE
. --character-set-server=charset
- Use charset as the default server character set. This option is available as of MySQL 4.1.3. See section 5.8.1 The Character Set Used for Data and Sorting.
--core-file
-
Write a core file if @command{mysqld} dies. For some systems, you must also
specify the
--core-file-size
option to @command{mysqld_safe}. @xref{mysqld_safe, , @command{mysqld_safe}}. Note that on some systems, such as Solaris, you will not get a core file if you are also using the--user
option. --collation-server=collation
- Use collation as the default server collation. This option is available as of MySQL 4.1.3. See section 5.8.1 The Character Set Used for Data and Sorting.
--datadir=path, -h path
- The path to the data directory.
--debug[=debug_options], -# [debug_options]
-
If MySQL is configured with
--with-debug
, you can use this option to get a trace file of what @command{mysqld} is doing. The debug_options string often is'd:t:o,file_name'
. See section D.1.2 Creating Trace Files. --default-character-set=charset
-
Use charset as the default character set. This option is deprecated
in favor of
--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
-
Use collation as the default collation. This option is deprecated in
favor of
--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
-
This option is a synonym for
--default-table-type
. It is available as of MySQL 4.1.2. --default-table-type=type
- Set the default table type for tables. See section 15 MySQL Storage Engines and Table Types.
--default-time-zone=type
-
Set the default server time zone. This option sets the global
time_zone
system variable. If this option is not given, the default time zone will be the same as the system time zone (given by the value of thesystem_time_zone
system variable. This option is available as of MySQL 4.1.3. --delay-key-write[= OFF | ON | ALL]
-
How the
DELAYED KEYS
option should be used. Delayed key writing causes key buffers not to be flushed between writes forMyISAM
tables.OFF
disables delayed key writes.ON
enables delayed key writes for those tables that were created with theDELAYED KEYS
option.ALL
delays key writes for allMyISAM
tables. Available as of MySQL 4.0.3. See section 7.5.2 Tuning Server Parameters. See section 15.1.1MyISAM
Startup Options. Note: If you set this variable toALL
, you should not useMyISAM
tables from within another program (such as from another MySQL server or with @command{myisamchk}) when the table is in use. Doing so will lead to index corruption. --delay-key-write-for-all-tables
-
Old form of
--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
-
Read the default keys used by
DES_ENCRYPT()
andDES_DECRYPT()
from this file. --enable-named-pipe
- Enable support for named pipes. This option applies only on Windows NT, 2000, and XP systems, and can be used only with the @command{mysqld-nt} and @command{mysqld-max-nt} servers that support named pipe connections.
--exit-info[=flags], -T [flags]
- This is a bit mask of different flags you can use for debugging the @command{mysqld} server. Do not use this option unless you know exactly what it does!
--external-locking
-
Enable system locking. Note that if you use this option on a system on
which
lockd
does not fully work (as on Linux), you will easily get @command{mysqld} to deadlock. This option previously was named--enable-locking
. Note: If you use this option to enable updates toMyISAM
tables from many MySQL processes, you have to ensure that these conditions are satisfied:- You should not use the query cache for queries that use tables that are updated by another process.
-
You should not use
--delay-key-write=ALL
orDELAY_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
- Flush all changes to disk after each SQL statement. Normally MySQL does a write of all changes to disk only after each SQL statement and lets the operating system handle the synching to disk. See section A.4.2 What to Do If MySQL Keeps Crashing.
--init-file=file
- Read SQL statements from this file at startup. Each statement must be on a single line and should not include comments.
--innodb-safe-binlog
-
Adds consistency guarantees between the content of
InnoDB
tables and the binary log. See section 5.9.4 The Binary Log. --language=lang_name, -L lang_name
- Client error messages in given language. lang_name can be given as the language name or as the full pathname to the directory where the language files are installed. See section 5.8.2 Setting the Error Message Language.
--log[=file], -l [file]
-
Log connections and queries to this file. See section 5.9.2 The General Query Log. If you don't
specify a filename, MySQL will use
host_name.log
as the filename. --log-bin=[file]
-
The binary log file.
Log all queries that change data to this file. Used for backup and
replication. See section 5.9.4 The Binary Log. If you don't specify a filename,
MySQL will use
host_name-bin
as the filename. --log-bin-index[=file]
-
The index file for binary log filenames. See section 5.9.4 The Binary Log.
If you don't specify a filename, MySQL will use
host_name-bin.index
as the filename. --log-error[=file]
-
Log errors and startup messages to this file. See section 5.9.1 The Error Log.
If you don't specify a filename, MySQL will use
host_name.err
as the filename. --log-isam[=file]
-
Log all
ISAM
/MyISAM
changes to this file (used only when debuggingISAM
/MyISAM
). --log-long-format
-
Log some extra information to the log files (update log, binary update log,
and slow queries log, whatever log has been activated). For example,
username and timestamp are logged for queries. If you are using
--log-slow-queries
and--log-long-format
, queries that are not using indexes also are logged to the slow query log. Note that--log-long-format
is deprecated as of MySQL version 4.1, when--log-short-format
was introduced (the 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
-
If you are using this option with
--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 less information to the log files (update log, binary update log, and slow queries log, whatever log has been activated). For example, username and timestamp are not logged for queries. This option was introduced in MySQL 4.1.
--log-slow-queries[=file]
-
Log all queries that have taken more than
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 updates to file# where # is a unique number if not
given. See section 5.9.3 The Update Log. The update log is deprecated and is
removed in MySQL 5.0.0; you should use the binary log instead
(
--log-bin
). See section 5.9.4 The Binary Log. Starting from version 5.0.0, using--log-update
will just turn on the binary log instead (see section C.1.3 Changes in release 5.0.0 (22 Dec 2003: Alpha)). --log-warnings, -W
-
Print out warnings such as
Aborted connection...
to the error log. Enabling this option is recommended, for example, if you use replication (you will 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
-
Table-modifying operations (
INSERT
,REPLACE
,DELETE
,UPDATE
) will 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 bySET LOW_PRIORITY_UPDATES=1
to change the priority in one thread. See section 7.3.2 Table Locking Issues. --memlock
-
Lock the @command{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 @command{mysqld} to swap on disk. Note that use of this option requires that you run the server asroot
, which is normally not a good idea for security reasons. --myisam-recover [=option[,option...]]]
-
Set the
MyISAM
storage engine recovery mode. The option value is any combination of the values ofDEFAULT
,BACKUP
,FORCE
, orQUICK
. 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, @command{mysqld} will, when it opens aMyISAM
table, open check 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, @command{mysqld} will run a check on the table. If the table was corrupted, @command{mysqld} will attempt 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 will 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 will force a repair of a table even if some rows would be deleted, but it will keep 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
-
When using the
NDB
storage engine, it is possible to point out the management server that distributes the cluster configuration by setting the connect string option. --ndbcluster
-
If the binary includes support for the
NDB Cluster
storage engine (from version 4.1.3, the MySQL-Max binaries are built withNDB Cluster
enabled) the default disabling of support for theNDB Cluster
storage engine can be overruled by using this option. Using theNDB Cluster
storage engine is necessary for using MySQL Cluster. See section 17 MySQL Cluster. --new
-
The
--new
option can be used to make the server behave as 4.1 in certain respects, easing a 4.0 to 4.1 upgrade:-
Hexadecimal strings such as
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 12 Column Types.
-
Hexadecimal strings such as
--pid-file=path
- The path to the process ID file used by @command{mysqld_safe}.
--port=port_num, -P port_num
- The port number to use when listening for TCP/IP connections.
--old-protocol, -o
- Use the 3.20 protocol for compatibility with some very old clients. See section 2.5.6 Upgrading from Version 3.20 to 3.21.
--one-thread
- Only use one thread (for debugging under Linux). This option is available only if the server is built with debugging enabled. See section D.1 Debugging a MySQL Server.
--open-files-limit=count
-
To change the number of file descriptors available to @command{mysqld}.
If this is not set or set to 0, then @command{mysqld} will use this value
to reserve file descriptors to use with
setrlimit()
. If this value is 0 then @command{mysqld} will reservemax_connections*5
ormax_connections + table_cache*2
(whichever is larger) number of files. You should try increasing this if @command{mysqld} gives you the error "Too many open files." --safe-mode
- Skip some optimization stages.
--safe-show-database
-
With this option, the
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 now aSHOW 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
-
If this is enabled, a user can't create new users with the
GRANT
statement, if the user doesn't have theINSERT
privilege for themysql.user
table or any column in the table. --secure-auth
- Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available as of MySQL 4.1.1.
--shared-memory
- Enable shared-memory connections by local clients. This option is available only on Windows. It was added in MySQL 4.1.0.
--shared-memory-base-name=name
- The name to use for shared-memory connections. This option is available only on Windows. It was added in MySQL 4.1.0.
--skip-bdb
-
Disable the
BDB
storage engine. This saves memory and might speed up some operations. Do not use this option if you requireBDB
tables. --skip-concurrent-insert
-
Turn off the ability to select and insert at the same time on
MyISAM
tables. (This is to be used only if you think you have found a bug in this feature.) --skip-delay-key-write
-
Ignore the
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
-
Don't use system locking. To use @command{isamchk} or @command{myisamchk},
you must shut down the server. See section 1.2.3 MySQL Stability. In MySQL 3.23, you
can use
CHECK TABLE
andREPAIR TABLE
to check and repairMyISAM
tables. This option previously was named--skip-locking
. --skip-grant-tables
-
This option causes the server not to use the privilege system at all. This
gives everyone full access to all databases! (You can tell a running
server to start using the grant tables again by executing a @command{mysqladmin
flush-privileges} or @command{mysqladmin reload} command, or by issuing a
FLUSH PRIVILEGES
statement.) --skip-host-cache
- Do not use the internal hostname cache for faster name-to-IP resolution. Instead, query the DNS server every time a client connects. See section 7.5.6 How MySQL Uses DNS.
--skip-innodb
-
Disable the
InnoDB
storage engine. This saves memory and disk space and might speed up some operations. Do not use this option if you requireInnoDB
tables. --skip-isam
-
Disable the
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 forISAM
. This option was added in MySQL 4.1.1. --skip-name-resolve
-
Do not resolve hostnames when checking client connections. Use only IP
numbers. If you use this option, all
Host
column values in the grant tables must be IP numbers orlocalhost
. See section 7.5.6 How MySQL Uses DNS. --skip-ndbcluster
-
Disable the
NDB Cluster
storage engine. This is the default for binaries that were built withNDB Cluster
storage engine support, this means that the system will only allocate memory and other resources for this storage engine if it is explicitly enabled. --skip-networking
- Don't listen for TCP/IP connections at all. All interaction with @command{mysqld} must be made via named pipes (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
- Don't use new, possibly wrong routines.
--skip-symlink
-
This is the old form of
--skip-symbolic-links
, for use before MySQL 4.0.13. --symbolic-links, --skip-symbolic-links
-
Enable or disable symbolic link support. This option has different effects on
Windows and Unix:
-
On Windows, enabling symbolic links allows you to establish a symbolic
link to a database directory by creating a
directory.sym
file that contains the path to the real directory. See section 7.6.1.3 Using Symbolic Links for Databases on Windows. -
On Unix, enabling symbolic links means that you can link a
MyISAM
index file or data file to another directory with theINDEX DIRECTORY
orDATA DIRECTORY
options of theCREATE TABLE
statement. If you delete or rename the table, the files that its symbolic links point to also are deleted or renamed. See section 14.2.6CREATE TABLE
Syntax.
-
On Windows, enabling symbolic links allows you to establish a symbolic
link to a database directory by creating a
--skip-safemalloc
-
If MySQL is configured with
--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
-
With this option, the
SHOW DATABASES
statement is allowed only to users who have theSHOW 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 theSHOW DATABASES
privilege or some privilege for the database. --skip-stack-trace
- Don't write stack traces. This option is useful when you are running @command{mysqld} under a debugger. On some systems, you also must use this option to get a core file. See section D.1 Debugging a MySQL Server.
--skip-thread-priority
- Disable using thread priorities for faster response time.
--socket=path
-
On Unix, this option specifies the Unix socket file to
use for local connections. The default value is `/tmp/mysql.sock'.
On Windows, the option specifies the pipe name to use for local connections
that use a named pipe. The default value is
MySQL
. --sql-mode=value[,value[,value...]]
- Set the SQL mode for MySQL. See section 5.2.2 The Server SQL Mode. This option was added in 3.23.41.
--temp-pool
- This option causes most temporary files created by the server to use a small set of names, rather than a unique name for each new file. This works around a problem in the Linux kernel dealing with creating many new files with different names. With the old behavior, Linux seems to ``leak'' memory, because it's being allocated to the directory entry cache rather than to the disk cache.
--transaction-isolation=level
-
Sets the default transaction isolation level, which can be
READ-UNCOMMITTED
,READ-COMMITTED
,REPEATABLE-READ
, orSERIALIZABLE
. See section 14.4.6SET TRANSACTION
Syntax. --tmpdir=path, -t path
-
The path of the directory to use for creating temporary files. It might be
useful if your default
/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 orLOAD DATA INFILE
operations. If files in the temporary file directory are lost when the server restarts, replication will fail. --user={user_name | user_id}, -u {user_name | user_id}
-
Run the @command{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 @command{mysqld} as
root
. The server will change its user ID during its startup sequence, causing it to run as that particular user rather than asroot
. 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 asroot
), @command{mysqld} uses only the first--user
option specified and produces a warning if there are multiple--user
options. Options in `/etc/my.cnf' and `datadir/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 thanroot
. The option in `/etc/my.cnf' will be found before any other--user
options, which ensures that the server runs as a user other thanroot
, and that a warning results if any other--user
option is found. --version, -V
- Display version information and exit.
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 14.5.3.1 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.
5.2.2 The Server SQL Mode
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 @command{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:
ANSI
- Change syntax and behavior to be more conformant to standard SQL. (New in MySQL 4.1.1)
STRICT_TRANS_TABLES
- If a value could not be inserted as given into a transactional table, abort the statement. For a non-transactional table, abort the statement if the value occurs in a single-row statement or the first row of a multiple-row statement. More detail is given later in this section. (New in MySQL 5.0.2)
TRADITIONAL
-
Make MySQL behave like a ``traditional'' SQL database system.
A simple description of this mode is ``give an error instead a warning''
when inserting an incorrect value in a column.
Note: If you are using non-transactional storage engines, the
INSERT
/UPDATE
will abort as soon as the error is noticed, which may not be what you want. (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
-
Don't do full checking of dates. Check only that the month is in the
range from 1 to 12 and the day is in the range from 1 to 31. This is
very convenient for Web applications where you obtain year, month, and day
in three different fields and you want to store exactly what the user
inserted (without date validation). This mode applies to
DATE
andDATETIME
columns. It does not applyTIMESTAMP
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, enableALLOW_INVALID_DATES
as well. ANSI_QUOTES
-
Treat `"' as an identifier quote character (like the
``' quote character) and not as a string quote character. You can still
use ``' to quote identifers in ANSI mode. With
ANSI_QUOTES
enabled, you cannot use double quotes to quote a literal string, because it will be interpreted as an identifier. (New in MySQL 4.0.0) ERROR_FOR_DIVISION_BY_ZERO
-
Produce an error in strict mode (otherwise a warning) when we
encounter a division by zero (or
MOD(X,0)
) during anINSERT
/UPDATE
. If this mode is not given, MySQL instead returnsNULL
for divisions by zero. If used withIGNORE
, MySQL generates a warning for divisions by zero, but the result of the operation isNULL
. (New in MySQL 5.0.2) IGNORE_SPACE
-
Allow spaces between a function name and the `(' character. This forces
all function names to be treated as reserved words. As a result, if you want
to access any database, table, or column name that is a reserved word, you
must quote it. For example, because there is a
USER()
function, the name of theuser
table in themysql
database and theUser
column in that table become reserved, so you must quote them:SELECT "User" FROM mysql."user";
(New in MySQL 4.0.0) NO_AUTO_VALUE_ON_ZERO
-
NO_AUTO_VALUE_ON_ZERO
affects handling ofAUTO_INCREMENT
columns. Normally, you generate the next sequence number for the column by inserting eitherNULL
or0
into it.NO_AUTO_VALUE_ON_ZERO
suppresses this behavior for0
so that onlyNULL
generates the next sequence number. (New in MySQL 4.1.1) This mode can be useful if0
has been stored in a table'sAUTO_INCREMENT
column. (This is not a recommended practice, by the way.) For example, if you dump the table with @command{mysqldump} and then reload it, MySQL normally generates new sequence numbers when it encounters the0
values, resulting in a table with different contents than the one that was dumped. EnablingNO_AUTO_VALUE_ON_ZERO
before reloading the dump file solves this problem. As of MySQL 4.1.1, @command{mysqldump} automatically includes a statement in the dump output to enableNO_AUTO_VALUE_ON_ZERO
. NO_DIR_IN_CREATE
-
When creating a table, ignore all
INDEX DIRECTORY
andDATA DIRECTORY
directives. This option is useful on slave replication servers. (New in MySQL 4.0.15) NO_FIELD_OPTIONS
-
Don't print MySQL-specific column options in the output of
SHOW CREATE TABLE
. This mode is used by @command{mysqldump} in portability mode. (New in MySQL 4.1.1) NO_KEY_OPTIONS
-
Don't print MySQL-specific index options in the output of
SHOW CREATE TABLE
. This mode is used by @command{mysqldump} in portability mode. (New in MySQL 4.1.1) NO_TABLE_OPTIONS
-
Don't print MySQL-specific table options (such as
ENGINE
) in the output ofSHOW CREATE TABLE
. This mode is used by @command{mysqldump} in portability mode. (New in MySQL 4.1.1) NO_ZERO_DATE
-
Don't allow
'0000-00-00'
as a valid date. You can still insert zero dates with theIGNORE
option. (New in MySQL 5.0.2) NO_ZERO_IN_DATE
-
Don't accept dates where the month or day part is 0. If used with the
IGNORE
option, we insert a'0000-00-00'
date for any such date. (New in MySQL 5.0.2) NO_UNSIGNED_SUBTRACTION
-
In subtraction operations, don't mark the result as
UNSIGNED
if one of the operands is unsigned. Note that this makesUNSIGNED BIGINT
not 100% usable in all contexts. See section 13.7 Cast Functions and Operators. (New in MySQL 4.0.2) ONLY_FULL_GROUP_BY
-
Don't allow queries that in the
GROUP BY
part refer to a not selected column. (New in MySQL 4.0.0) PIPES_AS_CONCAT
-
Treat
||
as a string concatenation operator (same asCONCAT()
) rather than as a synonym forOR
. (New in MySQL 4.0.0) REAL_AS_FLOAT
-
Treat
REAL
as a synonym forFLOAT
rather than as a synonym forDOUBLE
. (New in MySQL 4.0.0) STRICT_ALL_TABLES
- Enable strict mode for all storage engines. Invalid data values are rejected. Additional detail follows. (New in MySQL 5.0.2)
STRICT_TRANS_TABLES
- Enable strict mode for transactional storage engines, and when possible for non-transactional storage engines. Additional detail follows. (New in MySQL 5.0.2)
When strict mode is enabled, MySQL returns an error if a value is invalid
or missing (no value given for a column that does not have an explicit
DEFAULT
value in its definition). For transactional tables, this
occurs when either of STRICT_ALL_TABLES
or STRICT_TRANS_TABLES
is enabled. The statement is aborted and rolled back. For non-transactional
tables, MySQL handles invalid or missing values as follows:
If the statement inserts or modifies a single row, an error occurs if a value is invalid or missing. The statement is aborted and the table remains unchanged. If the statement inserts or modifies multiple rows, the effect depends on which strict option is enabled:
-
For
STRICT_ALL_TABLES
, if a value is invalid or missing for the first row, MySQL returns an error and no rows are changed. If a value is invalid or missing for the second or later row, MySQL returns an error and ignores the rest of the rows. However, in this case, the earlier rows will already 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. -
For
STRICT_TRANS_TABLES
, if a value is invalid or missing for the first row, MySQL returns an error and no rows are changed. For the second or later row, if a value is invalid, MySQL insert the closest valid value. If a value is missing, MySQL inserts the implicit default value for the column data type. In this case, MySQL generates a warning rather than an error and continues processing the statement.
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, enable the NO_ZERO_IN_DATE
and NO_ZERO_DATE
SQL modes.
If you are not using strict mode (that is, neither
STRICT_TRANS_TABLES
nor STRICT_ALL_TABLES
is enabled),
MySQL produces a warning for all values that are adjusted when inserted.
See section 14.5.3.21 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).
ANSI
-
Equivalent to
REAL_AS_FLOAT
,PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,ONLY_FULL_GROUP_BY
. See section 1.8.3 Running MySQL in ANSI Mode. DB2
-
Equivalent to
PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,NO_KEY_OPTIONS
,NO_TABLE_OPTIONS
,NO_FIELD_OPTIONS
. MAXDB
-
Equivalent to
PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,NO_KEY_OPTIONS
,NO_TABLE_OPTIONS
,NO_FIELD_OPTIONS
. MSSQL
-
Equivalent to
PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,NO_KEY_OPTIONS
,NO_TABLE_OPTIONS
,NO_FIELD_OPTIONS
. MYSQL323
-
Equivalent to
NO_FIELD_OPTIONS
. MYSQL40
-
Equivalent to
NO_FIELD_OPTIONS
. ORACLE
-
Equivalent to
PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,NO_KEY_OPTIONS
,NO_TABLE_OPTIONS
,NO_FIELD_OPTIONS
. POSTGRESQL
-
Equivalent to
PIPES_AS_CONCAT
,ANSI_QUOTES
,IGNORE_SPACE
,NO_KEY_OPTIONS
,NO_TABLE_OPTIONS
,NO_FIELD_OPTIONS
. TRADITIONAL
-
Equivalent to
STRICT_TRANS_TABLES
,STRICT_ALL_TABLES
,NO_ZERO_IN_DATE
,NO_ZERO_DATE
,ERROR_FOR_DIVISION_BY_ZERO
.
5.2.3 Server System Variables
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 @command{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 already 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 10.4 System Variables for more information.
mysql> SHOW VARIABLES; +---------------------------------+------------------------------+ | Variable_name | Value | +---------------------------------+------------------------------| | back_log | 50 | | basedir | /usr/local/mysql | | bdb_cache_size | 8388572 | | bdb_home | /usr/local/mysql | | bdb_log_buffer_size | 32768 | | bdb_logdir | | | bdb_max_lock | 10000 | | bdb_shared_data | OFF | | bdb_tmpdir | /tmp/ | | bdb_version | Sleepycat Software: ... | | binlog_cache_size | 32768 | | bulk_insert_buffer_size | 8388608 | | character_set | latin1 | | character_sets | latin1 big5 czech euc_kr | | concurrent_insert | ON | | connect_timeout | 5 | | convert_character_set | | | datadir | /usr/local/mysql/data/ | | default_week_format | 0 | | delay_key_write | ON | | delayed_insert_limit | 100 | | delayed_insert_timeout | 300 | | delayed_queue_size | 1000 | | flush | OFF | | flush_time | 0 | | ft_boolean_syntax | + -><()~*:""&| | | ft_max_word_len | 84 | | ft_min_word_len | 4 | | ft_query_expansion_limit | 20 | | ft_stopword_file | (built-in) | | have_bdb | YES | | have_innodb | YES | | have_isam | YES | | have_openssl | YES | | have_query_cache | YES | | have_raid | NO | | have_symlink | DISABLED | | init_file | | | innodb_additional_mem_pool_size | 1048576 | | 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_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 | 5242880 | | innodb_log_files_in_group | 2 | | innodb_log_group_home_dir | ./ | | innodb_mirrored_log_groups | 1 | | innodb_thread_concurrency | 8 | | interactive_timeout | 28800 | | join_buffer_size | 131072 | | key_buffer_size | 16773120 | | key_cache_age_threshold | 300 | | key_cache_block_size | 1024 | | key_cache_division_limit | 100 | | language | /usr/local/mysql/share/... | | large_files_support | ON | | local_infile | ON | | locked_in_memory | OFF | | log | OFF | | log_bin | OFF | | log_slave_updates | OFF | | log_slow_queries | OFF | | log_update | OFF | | log_warnings | 1 | | long_query_time | 10 | | low_priority_updates | OFF | | lower_case_table_names | 0 | | max_allowed_packet | 1047552 | | 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_join_size | 4294967295 | | max_relay_log_size | 0 | | max_sort_length | 1024 | | max_tmp_tables | 32 | | max_user_connections | 0 | | max_write_lock_count | 4294967295 | | myisam_max_extra_sort_file_size | 268435456 | | myisam_max_sort_file_size | 2147483647 | | myisam_recover_options | force | | myisam_repair_threads | 1 | | myisam_sort_buffer_size | 8388608 | | net_buffer_length | 16384 | | net_read_timeout | 30 | | net_retry_count | 10 | | net_write_timeout | 60 | | open_files_limit | 1024 | | pid_file | /usr/local/mysql/name.pid | | port | 3306 | | protocol_version | 10 | | query_cache_limit | 1048576 | | query_cache_size | 0 | | query_cache_type | ON | | read_buffer_size | 131072 | | read_rnd_buffer_size | 262144 | | rpl_recovery_rank | 0 | | 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 | 2097116 | | sql_mode | | | table_cache | 64 | | table_type | MYISAM | | thread_cache_size | 3 | | thread_stack | 131072 | | timezone | EEST | | tmp_table_size | 33554432 | | tmpdir | /tmp/:/mnt/hd2/tmp/ | | tx_isolation | READ-COMMITTED | | version | 4.0.4-beta | | 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 16.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
-
This is
ON
if @command{mysqld} was started with--ansi
. See section 1.8.3 Running MySQL in ANSI Mode. This variable was added in MySQL 3.23.6 and removed in 3.23.41. See the description forsql_mode
. back_log
-
The number of outstanding connection requests MySQL can have. This
comes into play when the main MySQL thread gets very
many connection requests in a very short time. It then takes some time
(although very little) for the main thread to check the connection and start
a new thread. The
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 Unixlisten()
system call should have more details. Check your OS documentation for the maximum value for this variable. Attempting to setback_log
higher than your operating system limit will be ineffective. basedir
-
The MySQL installation base directory. This variable can be set with the
--basedir
option. bdb_cache_size
-
The size of the buffer that is allocated for caching indexes and rows for
BDB
tables. If you don't useBDB
tables, you should start @command{mysqld} with--skip-bdb
to not waste memory for this cache. This variable was added in MySQL 3.23.14. bdb_home
-
The base directory for
BDB
tables. This should be assigned the same value as thedatadir
variable. This variable was added in MySQL 3.23.14. bdb_log_buffer_size
-
The size of the buffer that is allocated for caching indexes and rows for
BDB
tables. If you don't useBDB
tables, you should set this to 0 or start @command{mysqld} with--skip-bdb
to not waste memory for this cache. This variable was added in MySQL 3.23.31. bdb_logdir
-
The directory where the
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
-
The maximum number of locks you can have active on a
BDB
table (10,000 by default). You should increase this if errors such as the following occur when you perform long transactions or when @command{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
-
This is
ON
if you are using--bdb-shared-data
. This variable was added in MySQL 3.23.29. bdb_tmpdir
-
The value of the
--bdb-tmpdir
option. This variable was added in MySQL 3.23.14. bdb_version
-
See the description for
version_bdb
. binlog_cache_size
-
The size of the cache to hold the SQL statements for the binary log during
a transaction. A binary log cache is allocated for each client if the
server supports any transactional storage engines and, starting from MySQL
4.1.2, if the server has binary log enabled (
--log-bin
option). If you often use big, multiple-statement transactions, you can increase this to get more performance. TheBinlog_cache_use
andBinlog_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 forINSERT ... SELECT
,INSERT ... VALUES (...), (...), ...
, andLOAD 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 namedmyisam_bulk_insert_tree_size
. character_set
-
The default character set.
This variable was added in MySQL 3.23.3, then
removed in MySQL 4.1.1 and replaced by the various
character_set_xxx
variables. character_set_client
- The character set for statements that arrive from the client. This variable was added in MySQL 4.1.1.
character_set_connection
- The character set used for literals that do not have a character set introducer and for number-to-string conversion. This variable was added in MySQL 4.1.1.
character_set_database
-
The character set used by the default database.
The server sets this variable whenever the default database changes.
If there is no default database, the variable has the same value as
character_set_server
. This variable was added in MySQL 4.1.1. character_set_results
- The character set used for returning query results to the client. This variable was added in MySQL 4.1.1.
character_set_server
- The server default character set. This variable was added in MySQL 4.1.1.
character_set_system
-
The character set used by the server for storing identifiers.
The value is always
utf8
. This variable was added in MySQL 4.1.1. character_sets
-
The supported character sets.
This variable was added in MySQL 3.23.15 and removed in MySQL 4.1.1.
(Use
SHOW CHARACTER SET
for a list of character sets.) character_sets_dir
- The directory where character sets are installed. This variable was added in MySQL 4.1.2.
collation_connection
- The collation of the connection character set. This variable was added in MySQL 4.1.1.
collation_database
-
The collation used by the default database.
The server sets this variable whenever the default database changes.
If there is no default database, the variable has the same value as
collation_server
. This variable was added in MySQL 4.1.1. collation_server
- The server default collation. This variable was added in MySQL 4.1.1.
concurrent_insert
-
If
ON
(the default), MySQL allowsINSERT
andSELECT
statements to run concurrently forMyISAM
tables that have no free blocks in the middle. You can turn this option off by starting @command{mysqld} with--safe
or--skip-new
. This variable was added in MySQL 3.23.7. connect_timeout
-
The number of seconds the @command{mysqld} server waits for a connect
packet before responding with
Bad handshake
. convert_character_set
-
The current character set mapping that was set by
SET CHARACTER SET
. This variable was removed in MySQL 4.1. datadir
-
The MySQL data directory. This variable can be set with the
--datadir
option. default_week_format
-
The default mode value to use for the
WEEK()
function. This variable is available as of MySQL 4.0.14. delay_key_write
-
This option applies only to
MyISAM
tables. It can have one of the following values to affect handling of theDELAY_KEY_WRITE
table option that can be used inCREATE TABLE
statements.Option Description OFF
DELAYED_KEY_WRITE
is ignored.ON
MySQL honors the DELAY_KEY_WRITE
option forCREATE 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 will speed up writes on keys a lot, but if you use this feature, you should add automatic checking of allMyISAM
tables by starting the server with the--myisam-recover
option (for example,--myisam-recover=BACKUP,FORCE
). See section 5.2.1 @command{mysqld} Command-Line Options and section 15.1.1 @code{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
-
After inserting
delayed_insert_limit
delayed rows, theINSERT DELAYED
handler thread checks whether there are anySELECT
statements pending. If so, it allows them to execute before continuing to insert delayed rows. delayed_insert_timeout
-
How long an
INSERT DELAYED
handler thread should wait forINSERT
statements before terminating. delayed_queue_size
-
This is a per-table limit on the number of
rows to queue when handling
INSERT DELAYED
statements. If the queue becomes full, any client that issues anINSERT DELAYED
statement will wait until there is room in the queue again. expire_logs_days
- The number of days for automatic binary log removal. The default is 0, which means ``no automatic removal.'' This variable was added in MySQL 4.1.0.
flush
-
This is
ON
if you have started @command{mysqld} with the--flush
option. This variable was added in MySQL 3.22.9. flush_time
-
If this is set to a non-zero value, all tables will be closed every
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
-
The list of operators supported by boolean full-text searches performed using
IN BOOLEAN MODE
. This variable was added in MySQL 4.0.1. See section 13.6.1 Boolean Full-Text Searches. The default variable value is'+ -><()~*:""&|'
. The rules for changing the value are as follows:- Operator function is determined by position within the string.
- The replacement value must be 14 characters.
- Each character must be an ASCII non-alphanumeric character.
- Either the first or second character must be a space.
- No duplicates are allowed except the phrase quoting operators in positions 11 and 12. These two characters are not required to be the same, but they are the only two that may be.
- Positions 10, 13, and 14 (which by default are set to `:', `&', and `|') are reserved for future extensions.
ft_max_word_len
-
The maximum length of the word to be included in a
FULLTEXT
index. This variable was added in MySQL 4.0.0. Note:FULLTEXT
indexes must be rebuilt after changing this variable. UseREPAIR TABLE tbl_name QUICK
. ft_min_word_len
-
The minimum length of the word to be included in a
FULLTEXT
index. This variable was added in MySQL 4.0.0. Note:FULLTEXT
indexes must be rebuilt after changing this variable. UseREPAIR TABLE tbl_name QUICK
. ft_query_expansion_limit
-
The number of top matches to use for full-text searches performed using
WITH QUERY EXPANSION
. This variable was added in MySQL 4.1.1. ft_stopword_file
-
The file from which to read the list of stopwords for full-text searches.
All the words from the file are used; comments are not honored.
By default, a built-in list of stopwords is used (as defined in the
`myisam/ft_static.c' file). Setting this variable to the empty string
(
''
) disables stopword filtering. This variable was added in MySQL 4.0.10. Note:FULLTEXT
indexes must be rebuilt after changing this variable. UseREPAIR TABLE tbl_name QUICK
. group_concat_max_len
-
The maximum allowed result length for the
GROUP_CONCAT()
function. This variable was added in MySQL 4.1.0. have_archive
-
YES
if @command{mysqld} supportsARCHIVE
tables. This variable was added in MySQL 4.1.3. have_bdb
-
YES
if @command{mysqld} supportsBDB
tables.DISABLED
if--skip-bdb
is used. This variable was added in MySQL 3.23.30. have_compress
-
Whether the
zlib
compression library is available to the server. If not, theCOMPRESS()
andUNCOMPRESS()
functions cannot be used. This variable was added in MySQL 4.1.1. have_crypt
-
Whether the
crypt()
system call is available to the server. If not, theCRYPT()
function cannot be used. This variable was added in MySQL 4.0.10. have_geometry
- Whether the server supports spatial data types. This variable was added in MySQL 4.1.3.
have_innodb
-
YES
if @command{mysqld} supportsInnoDB
tables.DISABLED
if--skip-innodb
is used. This variable was added in MySQL 3.23.37. have_isam
-
YES
if @command{mysqld} supportsISAM
tables.DISABLED
if--skip-isam
is used. This variable was added in MySQL 3.23.30. have_ndbcluster
-
YES
if @command{mysqld} supportsNDB Cluster
tables.DISABLED
if--skip-ndbcluster
is used. This variable was added in MySQL 4.1.2. have_openssl
-
YES
if @command{mysqld} supports SSL (encryption) of the client/server protocol. This variable was added in MySQL 3.23.43. have_query_cache
-
YES
if @command{mysqld} supports the query cache. This variable was added in MySQL 4.0.2. have_raid
-
YES
if @command{mysqld} supports theRAID
option. This variable was added in MySQL 3.23.30. have_rtree_keys
-
Whether
RTREE
indexes are available. (These are used for spatial indexed inMyISAM
tables.) This variable was added in MySQL 4.1.3. have_symlink
-
Whether symbolic link support is enabled. This is required on Unix for
support of the
DATA DIRECTORY
andINDEX DIRECTORY
table options. This variable was added in MySQL 4.0.0. init_connect
-
A string to be executed by the server for each client that connects.
The string consists of one or more SQL statements. To specify multiple
statements, separate them by semicolon characters.
For example, each client begins by default with autocommit mode enabled.
There is no global server variable to specify that autocommit should be
disabled by default, but
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 ofinit_connect
is not executed for users having theSUPER
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 forSUPER
users enables those to open a connection and fixinit_connect
. This variable was added in MySQL 4.1.2. init_file
-
The name of the file specified with the
--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
-
This variable is similar to
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 theinit_connect
variable. This variable was added in MySQL 4.1.2. innodb_xxx
-
The
InnoDB
system variables are listed at section 16.5InnoDB
Startup Options. interactive_timeout
-
The number of seconds the server waits for activity on an interactive
connection before closing it. An interactive client is defined as a
client that uses the
CLIENT_INTERACTIVE
option tomysql_real_connect()
. See alsowait_timeout
. join_buffer_size
-
The size of the buffer that is used for full joins (joins that do not use
indexes). Normally the best way to get fast joins is to add indexes.
Increase the value of
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
-
Index blocks for
MyISAM
andISAM
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 forkey_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, useLOCK TABLES
. See section 14.4.5LOCK TABLES
andUNLOCK TABLES
Syntax. You can check the performance of the key buffer by issuing aSHOW STATUS
statement and examining theKey_read_requests
,Key_reads
,Key_write_requests
, andKey_writes
status variables. See section 14.5.3SET
andSHOW
Syntax. TheKey_reads/Key_read_requests
ratio should normally be less than 0.01. TheKey_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 theDELAY_KEY_WRITE
table option. The fraction of the key buffer in use can be determined usingkey_buffer_size
in conjunction with theKey_blocks_used
status variable and the buffer block size. From MySQL 4.1.1 on, the buffer block size is available from thekey_cache_block_size
server variable. The fraction of the buffer in use is:(Key_blocks_used * key_cache_block_size) / key_buffer_size
Before MySQL 4.1.1, key cache blocks are 1024 bytes, so the fraction of the key buffer in use is:(Key_blocks_used * 1024) / key_buffer_size
See section 7.4.6 TheMyISAM
Key Cache. key_cache_age_threshold
-
This value controls the demotion of buffers from the hot sub-chain of a key
cache to the warm sub-chain.
Lower values cause demotion to happen more quickly.
The minimum value is 100.
The default value is 300.
This variable was added in MySQL 4.1.1.
See section 7.4.6 The
MyISAM
Key Cache. key_cache_block_size
-
The size in bytes of blocks in the key cache.
The default value is 1024.
This variable was added in MySQL 4.1.1.
See section 7.4.6 The
MyISAM
Key Cache. key_cache_division_limit
-
The division point between the hot and warm sub-chains of the key cache
buffer chain. The value is the percentage of the buffer chain to use for
the warm sub-chain. Allowable values range from 1 to 100.
The default value is 100.
This variable was added in MySQL 4.1.1.
See section 7.4.6 The
MyISAM
Key Cache. language
- The language used for error messages.
large_file_support
- Whether @command{mysqld} was compiled with options for large file support. This variable was added in MySQL 3.23.28.
license
- The type of license the server has. This variable was added in MySQL 4.0.19.
local_infile
-
Whether
LOCAL
is supported forLOAD DATA INFILE
statements. This variable was added in MySQL 4.0.3. locked_in_memory
-
Whether @command{mysqld} was locked in memory with
--memlock
. This variable was added in MySQL 3.23.25. log
- Whether logging of all queries to the general query log is enabled. See section 5.9.2 The General Query Log.
log_bin
- Whether the binary log is enabled. This variable was added in MySQL 3.23.14. See section 5.9.4 The Binary Log.
log_error
- The location of the error log. This variable was added in MySQL 4.0.10.
log_slave_updates
- Whether updates received by a slave server from a master server should be logged to the slave's own binary log. Binary logging must be enabled on the slave for this to have any effect. This variable was added in MySQL 3.23.17. See section 6.8 Replication Startup Options.
log_slow_queries
-
Whether slow queries should be logged. ``Slow'' is determined by the value
of the
long_query_time
variable. This variable was added in MySQL 4.0.2. See section 5.9.5 The Slow Query Log. log_update
- Whether the update log is enabled. This variable was added in MySQL 3.22.18. Note that the binary log is preferable to the update log, which is unavailable as of MySQL 5.0. See section 5.9.3 The Update Log.
log_warnings
- Whether to produce additional warning messages. This variable was added in MySQL 4.0.3. It is enabled by default as of MySQL 4.0.19 and 4.1.2. 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.
long_query_time
-
If a query takes longer than this many seconds, the
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
-
If set to
1
, allINSERT
,UPDATE
,DELETE
, andLOCK TABLE WRITE
statements wait until there is no pendingSELECT
orLOCK TABLE READ
on the affected table. This variable previously was namedsql_low_priority_updates
. It was added in MySQL 3.22.5. lower_case_file_system
-
This variable indicates whether the filesystem where the data directory is
located has case insensitive filenames.
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
-
If set to 1, table names are stored in lowercase on disk and table name
comparisons are not case sensitive. This variable was added in MySQL 3.23.6.
If set to 2 (new in 4.0.18), table names are stored as given but compared
in lowercase. From MySQL 4.0.2, this option also applies to database names.
From 4.1.1, it also applies to table aliases.
See section 10.2.2 Identifier Case Sensitivity.
You should not set this variable to 0 if you are running
MySQL on a system that does not have case-sensitive filenames (such as
Windows or Mac OS X). New in 4.0.18: If this variable is not set at
startup and the
filesystem on which the data directory is located does not have
case-sensitive filenames, MySQL automatically sets
lower_case_table_names
to 2. max_allowed_packet
-
The maximum size of one packet or any generated/intermediate string.
The packet message buffer is initialized to
net_buffer_length
bytes, but can grow up tomax_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 bigBLOB
columns or long strings. It should be as big as the biggestBLOB
you want to use. The protocol limit formax_allowed_packet
is 16MB before MySQL 4.0 and 1GB thereafter. max_binlog_cache_size
-
If a multiple-statement transaction requires more than this amount of memory,
you will get the error
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
-
If a write to the binary log exceeds the given value, rotate the binary
logs. You cannot set this variable to more than 1GB or to less than 4096
bytes. (The minimum before MYSQL 4.0.14 is 1024 bytes.) The default value
is 1GB. This variable was added in MySQL 3.23.33.
Note if you are using transactions: A transaction is written in one chunk to
the binary log, hence it is never split between several binary logs.
Therefore, if you have big transactions, you might see binary logs bigger than
max_binlog_size
. Ifmax_relay_log_size
is 0, the value ofmax_binlog_size
applies to relay logs as well.max_relay_log_size
was added in MySQL 4.0.14. max_connect_errors
-
If there are more than this number of interrupted connections from a host,
that host is blocked from further connections. You can unblock blocked hosts
with the
FLUSH HOSTS
statement. max_connections
-
The number of simultaneous client connections allowed. Increasing this value
increases the number of file descriptors that @command{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
-
Don't start more than this number of threads to handle
INSERT DELAYED
statements. If you try to insert data into a new table after allINSERT DELAYED
threads are in use, the row will be inserted as if theDELAYED
attribute wasn't specified. If you set this to 0, MySQL never creates a thread to handleDELAYED
rows; in effect, this disablesDELAYED
entirely. This variable was added in MySQL 3.23.0. max_error_count
-
The maximum number of error, warning, and note messages to be stored for
display by
SHOW ERRORS
orSHOW WARNINGS
. This variable was added in MySQL 4.1.0. max_heap_table_size
-
This variable sets the maximum size to which
MEMORY
(HEAP
) tables are allowed to grow. The value of the variable is used to calculateMEMORY
tableMAX_ROWS
values. Setting this variable has no effect on any existingMEMORY
table, unless the table is re-created with a statement such asCREATE TABLE
orTRUNCATE TABLE
, or altered withALTER TABLE
. This variable was added in MySQL 3.23.0. max_insert_delayed_threads
-
This variable is a synonym for
max_delayed_threads
. It was added in MySQL 4.0.19. max_join_size
-
Don't allow
SELECT
statements that probably will need to examine more thanmax_join_size
row combinations or are likely to do more thanmax_join_size
disk seeks. By setting this value, you can catchSELECT
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 aWHERE
clause, that take a long time, or that return millions of rows. Setting this variable to a value other thanDEFAULT
resets theSQL_BIG_SELECTS
value to0
. If you set theSQL_BIG_SELECTS
value again, themax_join_size
variable is ignored. If a query result already is in the query cache, no result size check is performed, because the result has already been computed and it does not burden the server to send it to the client. This variable previously was namedsql_max_join_size
. max_length_for_sort_data
-
The cutoff on the size of index values that determines which
filesort
algorithm to use. See section 7.2.10 How MySQL OptimizesORDER BY
. This variable was added in MySQL 4.1.1 max_relay_log_size
-
If a write by a replication slave to its relay log exceeds the given value,
rotate the relay log. This variable enables you to put different size
constraints on relay logs and binary logs. However, setting the variable to
0 makes MySQL use
max_binlog_size
for both binary logs and relay logs. You must setmax_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
-
Limit the assumed maximum number of seeks when looking up rows based on
a key. The MySQL optimizer will assume that no more than this number of
key seeks will be required when searching for matching rows in a table
by scanning a key, regardless of the actual cardinality of the key
(see section 14.5.3.12
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
-
The number of bytes to use when sorting
BLOB
orTEXT
values. Only the firstmax_sort_length
bytes of each value are used; the rest are ignored. max_tmp_tables
- The maximum number of temporary tables a client can keep open at the same time. (This option doesn't yet do anything.)
max_user_connections
- The maximum number of simultaneous connections allowed to any given MySQL account. A value of 0 means ``no limit.'' This variable was added in MySQL 3.23.34.
max_write_lock_count
- After this many write locks, allow some read locks to run in between. This variable was added in MySQL 3.23.7.
myisam_data_pointer_size
-
The default pointer size in bytes, to be used by
CREATE TABLE
forMyISAM
tables when noMAX_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.11The table is full
. myisam_max_extra_sort_file_size
-
If the temporary file used for fast
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
-
The maximum size of the temporary file MySQL is allowed to use while
re-creating a
MyISAM
index (duringREPAIR TABLE
,ALTER TABLE
, orLOAD DATA INFILE
). If the file size would be bigger than this value, the index will be 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
-
The value of the
--myisam-recover
option. This variable was added in MySQL 3.23.36. myisam_repair_threads
-
If this value is greater than 1,
MyISAM
table indexes are created in parallel (each index in its own thread) during theRepair 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
-
The buffer that is allocated when sorting
MyISAM
indexes during aREPAIR TABLE
or when creating indexes withCREATE INDEX
orALTER TABLE
. This variable was added in MySQL 3.23.16. named_pipe
- On Windows, indicates whether the server supports connections over named pipes. This variable was added in MySQL 3.23.50.
net_buffer_length
-
The communication buffer is reset to this size between queries. This should
not normally be changed, but if you have very little memory, you can set it
to the expected length of SQL statements sent by clients. If statements
exceed this length, the buffer is automatically enlarged, up to
max_allowed_packet
bytes. net_read_timeout
-
The number of seconds to wait for more data from a connection before
aborting the read.
When the server is reading from the client,
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 alsoslave_net_timeout
. This variable was added in MySQL 3.23.20. net_retry_count
- If a read on a communication port is interrupted, retry this many times before giving up. This value should be set quite high on FreeBSD because internal interrupts are sent to all threads. This variable was added in MySQL 3.23.7.
net_write_timeout
-
The number of seconds to wait for a block to be written to a connection before
aborting the write.
See also
net_read_timeout
. This variable was added in MySQL 3.23.20. new
- This variable is used in MySQL 4.0 to turn on some 4.1 behaviors. This variable was added in MySQL 4.0.12.
old_passwords
- Whether the server should use pre-4.1-style passwords for MySQL user accounts. This variable was added in MySQL 4.1.1.
open_files_limit
- The number of files that the operating system allows @command{mysqld} to open. This is the real value allowed by the system and might be different from the value you gave @command{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
- Controls the heuristics applied during query optimization to prune less-promising partial plans from the optimizer search space. A value of 0 disables heuristics so that the optimizer performs an exhaustive search. A value of 1 causes the optimizer to prune plans based on the number of rows retrieved by intermediate plans. This variable was added in MySQL 5.0.1.
optimizer_search_depth
- The maximum depth of search performed by the query optimizer. Values larger than the number of relations in a query result in better query plans, but take longer to generate an execution plan for a query. Values smaller than the number of relations in a query return an execution plan quicker, but the resulting plan may be far from being optimal. If set to 0, the system automatically picks a reasonable value. If set to the maximum number of tables used in a query plus 2, the optimizer switches to the original algorithm used before MySQL 5.0.1 that performs an exhaustive search. This variable was added in MySQL 5.0.1.
pid_file
-
The pathname of the process ID (PID) file. This variable can be set
with the
--pid-file
option. This variable was added in MySQL 3.23.23. port
-
The port on which the server listens for TCP/IP connections. This variable
can be set with the
--port
option. preload_buffer_size
- The size of the buffer that is allocated when preloading indexes. This variable was added in MySQL 4.1.1.
protocol_version
- The version of the client/server protocol used by the MySQL server. This variable was added in MySQL 3.23.18.
query_alloc_block_size
- The allocation size of memory blocks that are allocated for objects created during query parsing and execution. If you have problems with memory fragmentation, it might help to increase this a bit. This variable was added in MySQL 4.0.16.
query_cache_limit
- Don't cache results that are bigger than this. The default value is 1MB. This variable was added in MySQL 4.0.1.
query_cache_min_res_unit
- The minimum size for blocks allocated by the query cache. The default value is 4KB. Tuning information for this variable is given in section 5.11.3 Query Cache Configuration. This variable is present from MySQL 4.1.
query_cache_size
-
The amount of memory allocated for caching query results. The default value
is 0, which disables the query cache. Note that this amount of memory will
be allocated even if
query_cache_type
is set to 0. This variable was added in MySQL 4.0.1. query_cache_type
-
Set query cache type. Setting the
GLOBAL
value sets the type for all clients that connect thereafter. Individual clients can set theSESSION
value to affect their own use of the query cache.Option Description 0
orOFF
Don't cache or retrieve results. Note that this will not deallocate the query cache buffer. To do that, you should set query_cache_size
to 0.1
orON
Cache all query results except for those that begin with SELECT SQL_NO_CACHE
.2
orDEMAND
Cache results only for queries that begin with SELECT SQL_CACHE
. query_cache_wlock_invalidate
-
Normally, when one client acquires a
WRITE
lock on aMyISAM
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 aWRITE
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
-
The size of the persistent buffer used for query parsing and execution.
This buffer is not freed between queries.
If you are running complex queries, a larger
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
- The size of blocks that are allocated when doing range optimization. This variable was added in MySQL 4.0.16.
read_buffer_size
-
Each thread that does a sequential scan allocates a buffer of this
size for each table it scans. If you do many sequential scans, you might
want to increase this value.
This variable was added in MySQL 4.0.3.
Previously, it was named
record_buffer
. read_only
-
When the variable is set to
ON
for a replication slave server, it causes the slave to allow no updates except from slave threads or from users with theSUPER
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
- Disables or enables automatic purging of relay logs as soon as they are not needed any more. The default value is 1 (enabled). This variable was added in MySQL 4.1.1.
read_rnd_buffer_size
-
When reading rows in sorted order after a sort, the rows are read through
this buffer to avoid disk seeks. Setting the variable to a large value can
improve
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 namedrecord_rnd_buffer
. safe_show_database
-
Don't show databases for which the user has no database or
table privileges. This can improve security if you're concerned about
people being able to see what databases other users have. See also
skip_show_database
. This variable was removed in MySQL 4.0.5. Instead, use theSHOW DATABASES
privilege to control access by MySQL accounts to database names. secure_auth
-
If the MySQL server has been started with the
--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 isON
, otherwise it isOFF
. 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 will fail 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
-
The value of the
--server-id
option. It is used for master and slave replication servers. This variable was added in MySQL 3.23.26. shared_memory
- Whether or not the server allows shared-memory connections. Currently, only Windows servers support this. This variable was added in MySQL 4.1.1.
shared_memory_base_name
- Whether or not the server allows shared-memory connections. Currently, only Windows servers support this. This variable was added in MySQL 4.1.0.
skip_external_locking
-
This is
OFF
if @command{mysqld} uses external locking. This variable was added in MySQL 4.0.3. Previously, it was namedskip_locking
. skip_networking
-
This is
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. On NetWare, only TCP/IP connections are supported, so do not set this variable toON
. This variable was added in MySQL 3.22.23. skip_show_database
-
This prevents people from using the
SHOW DATABASES
statement if they don't have theSHOW DATABASES
privilege. This can improve security if you're concerned about people being able to see what databases other users have. See alsosafe_show_database
. This variable was added in MySQL 3.23.4. As of MySQL 4.0.2, its effect also depends on theSHOW DATABASES
privilege: If the variable value isON
, theSHOW DATABASES
statement is allowed only to users who have theSHOW DATABASES
privilege, and the statement displays all database names. If the value isOFF
,SHOW DATABASES
is allowed to all users, but displays each database name only if the user has theSHOW DATABASES
privilege or some privilege for the database. slave_compressed_protocol
- Whether to use compression of the slave/master protocol if both the slave and the master support it. This variable was added in MySQL 4.0.3.
slave_net_timeout
- The number of seconds to wait for more data from a master/slave connection before aborting the read. This variable was added in MySQL 3.23.40.
slow_launch_time
-
If creating a thread takes longer than this many seconds, the server
increments the
Slow_launch_threads
status variable. This variable was added in MySQL 3.23.15. socket
- On Unix, this is the Unix socket file used for local client connections. On Windows, this is the name of the named pipe used for local client connections.
sort_buffer_size
-
Each thread that needs to do a sort allocates a buffer of this
size. Increase this value for faster
ORDER BY
orGROUP BY
operations. See section A.4.4 Where MySQL Stores Temporary Files. sql_mode
- The current server SQL mode. This variable was added in MySQL 3.23.41. It can be set dynamically as of MySQL 4.1.1. See section 5.2.2 The Server SQL Mode.
sql_slave_skip_counter
- The number of events from the master that a slave server should skip. It was added in MySQL 3.23.33.
storage_engine
-
This variable is a synonym for
table_type
. It was added in MySQL 4.1.2. sync_binlog
-
If positive, the MySQL server will synchronize its binary log to disk
(
fdatasync()
) after everysync_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 will 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
-
This was added as a command-line option in MySQL 4.0.18, and is also a settable
global variable since MySQL 4.1.3. If set to 1, when a non-temporary table is
created it will synchronize its `.frm' file to disk (
fdatasync()
); this is slower but safer in case of crash. Default is 1. system_time_zone
-
The server system time zone. When the server starts, it attempts to determine
the time zone of the host machine. For example, if the
TZ
environment variable is set, its value is used to setsystem_time_zone
. This variable was added in MySQL 4.1.3. table_cache
-
The number of open tables for all threads. Increasing this value
increases the number of file descriptors that @command{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 ofOpened_tables
is large and you don't doFLUSH TABLES
a lot (which just forces all tables to be closed and reopened), then you should increase the value of thetable_cache
variable. For more information about the table cache, see section 7.4.8 How MySQL Opens and Closes Tables. table_type
-
The default table type (storage engine).
To set the table type at server startup, use the
--default-table-type
option. This variable was added in MySQL 3.23.0. See section 5.2.1 @command{mysqld} Command-Line Options. thread_cache_size
-
How many threads the server should cache for reuse. When a client
disconnects, the client's threads are put in the cache if there aren't
already
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 theConnections
andThreads_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
-
On Solaris, @command{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
-
The stack size for each thread. Many of the limits detected by the
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
-
The current time zone. The initial value of this is
'SYSTEM'
(use the value ofsystem_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
-
The time zone for the server. This is set from the
TZ
environment variable when @command{mysqld} is started. The time zone also can be set by giving a--timezone
argument to @command{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 thesystem_time_zone
variable. See section A.4.6 Time Zone Problems. tmp_table_size
-
If an in-memory temporary table exceeds this size, MySQL
automatically converts it to an on-disk
MyISAM
table. Increase the value oftmp_table_size
if you do many advancedGROUP BY
queries and you have lots of memory. tmpdir
-
The directory used for temporary files and temporary tables.
Starting from MySQL 4.1, this variable can be set to a list of
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.
This feature can be used to
spread the load between several physical disks.
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 orLOAD DATA INFILE
operations. If files in the temporary file directory are lost when the server restarts, replication will fail. This variable was added in MySQL 3.22.4. transaction_alloc_block_size
- The allocation size of memory blocks that are allocated for storing queries that are part of a transaction to be stored in the binary log when doing a commit. This variable was added in MySQL 4.0.16.
transaction_prealloc_size
-
The size of the persistent buffer for
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 ofmalloc()
calls. This variable was added in MySQL 4.0.16. tx_isolation
- The default transaction isolation level. This variable was added in MySQL 4.0.3.
updatable_views_with_limit
-
This variable controls whether updates can be made using a view that
does not contain a primary key in the underlying table, if the update contains
a
LIMIT
clause. (Such updates often are generated by GUI tools.) An update is anUPDATE
orDELETE
statement. Primary key here means aPRIMARY KEY
, or aUNIQUE
index in which no column can containNULL
. The variable can have two values:-
1
orYES
: Issue a warning only (not an error message). This is the default value. -
0
orNO
: Prohibit the update.
-
version
- The version number for the server.
version_bdb
-
The
BDB
storage engine version. This variable was added in MySQL 3.23.31 with the namebdb_version
and renamed toversion_bdb
in MySQL 4.1.1. version_comment
-
The @command{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
- The type of machine MySQL was built on. This variable was added in MySQL 4.1.1.
version_compile_os
- The type of operating system MySQL was built on. This variable was added in MySQL 4.0.19.
wait_timeout
-
The number of seconds the server waits for activity on a non-interactive
connection before closing it.
On thread startup, the session
wait_timeout
value is initialized from the globalwait_timeout
value or from the globalinteractive_timeout
value, depending on the type of client (as defined by theCLIENT_INTERACTIVE
connect option tomysql_real_connect()
). See alsointeractive_timeout
.
5.2.3.1 Dynamic System Variables
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 10.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
|
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
|
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
|
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_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.
5.2.4 Server Status Variables
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
- The number of connections that were aborted because the client died without closing the connection properly. See section A.2.10 Communication Errors and Aborted Connections.
Aborted_connects
- The number of tries to connect to the MySQL server that failed. See section A.2.10 Communication Errors and Aborted Connections.
Binlog_cache_disk_use
-
The number of transactions that used the temporary binary log cache but that
exceeded the value of
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
- The number of transactions that used the temporary binary log cache. This variable was added in MySQL 4.1.2.
Bytes_received
- The number of bytes received from all clients. This variable was added in MySQL 3.23.7.
Bytes_sent
- The number of bytes sent to all clients. This variable was added in MySQL 3.23.7.
Com_xxx
-
The number of times each xxx statement has been executed.
There is one status variable for each type of statement. For example,
Com_delete
andCom_insert
countDELETE
andINSERT
statements. Connections
- The number of connection attempts (successful or not) to the MySQL server.
Created_tmp_disk_tables
- The number of temporary tables on disk created automatically by the server while executing statements. This variable was added in MySQL 3.23.24.
Created_tmp_files
- How many temporary files @command{mysqld} has created. This variable was added in MySQL 3.23.28.
Created_tmp_tables
-
The number of in-memory temporary tables created automatically by the
server while executing statements.
If
Created_tmp_disk_tables
is big, you may want to increase thetmp_table_size
value to cause temporary tables to be memory-based instead of disk-based. Delayed_errors
-
The number of rows written with
INSERT DELAYED
for which some error occurred (probablyduplicate key
). Delayed_insert_threads
-
The number of
INSERT DELAYED
handler threads in use. Delayed_writes
-
The number of
INSERT DELAYED
rows written. Flush_commands
-
The number of executed
FLUSH
statements. Handler_commit
-
The number of internal
COMMIT
statements. This variable was added in MySQL 4.0.2. Handler_discover
-
The MySQL server can ask the
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
- The number of times a row was deleted from a table.
Handler_read_first
-
The number of times the first entry was read from an index. If this is
high, it suggests that the server is doing a lot of full index scans; for
example,
SELECT col1 FROM foo
, assuming thatcol1
is indexed. Handler_read_key
- The number of requests to read a row based on a key. If this is high, it is a good indication that your queries and tables are properly indexed.
Handler_read_next
- The number of requests to read the next row in key order. This will be incremented if you are querying an index column with a range constraint or if you are doing an index scan.
Handler_read_prev
-
The number of requests to read the previous row in key order. This read
method is mainly used to optimize
ORDER BY ... DESC
. This variable was added in MySQL 3.23.6. Handler_read_rnd
- The number of requests to read a row based on a fixed position. This will be high if you are doing a lot of queries that require sorting of the result. You probably have a lot of queries that require MySQL to scan whole tables or you have joins that don't use keys properly.
Handler_read_rnd_next
- The number of requests to read the next row in the data file. This will be high if you are doing a lot of table scans. Generally this suggests that your tables are not properly indexed or that your queries are not written to take advantage of the indexes you have.
Handler_rollback
-
The number of internal
ROLLBACK
statements. This variable was added in MySQL 4.0.2. Handler_update
- The number of requests to update a row in a table.
Handler_write
- The number of requests to insert a row in a table.
Key_blocks_not_flushed
-
The number of key blocks in the key cache that have changed but haven't yet
been flushed to disk.
This variable was added in MySQL 4.1.1.
It used to be known as
Not_flushed_key_blocks
. Key_blocks_unused
- This variable was added in MySQL 4.1.2. section 5.2.3 Server System Variables.
Key_blocks_used
-
The number of used blocks in the key cache.
You can use this value to determine how much of the key cache is in use;
see the discussion of
key_buffer_size
in section 5.2.3 Server System Variables. Key_read_requests
- The number of requests to read a key block from the cache.
Key_reads
-
The number of physical reads of a key block from disk.
If
Key_reads
is big, then yourkey_buffer_size
value is probably too small. The cache miss rate can be calculated asKey_reads
/Key_read_requests
. Key_write_requests
- The number of requests to write a key block to the cache.
Key_writes
- The number of physical writes of a key block to disk.
Last_query_cost
- The total cost of the last compiled query as computed by the query optimizer. Useful for comparing the cost of different query plans for the same query. The default value of -1 means that no query has been compiled yet. This variable was added in MySQL 5.0.1.
Max_used_connections
- The maximum number of connections that have been in use simultaneously since the server started.
Not_flushed_delayed_rows
-
The number of rows waiting to be written in
INSERT DELAY
queues. Not_flushed_key_blocks
-
The old name for
Key_blocks_not_flushed
before MySQL 4.1.1. Open_files
- The number of files that are open.
Open_streams
- The number of streams that are open (used mainly for logging).
Open_tables
- The number of tables that are open.
Opened_tables
-
The number of tables that have been opened.
If
Opened_tables
is big, yourtable_cache
value is probably too small. Qcache_free_blocks
- The number of free memory blocks in query cache.
Qcache_free_memory
- The amount of free memory for query cache.
Qcache_hits
- The number of cache hits.
Qcache_inserts
- The number of queries added to the cache.
Qcache_lowmem_prunes
- The number of queries that were deleted from the cache because of low memory.
Qcache_not_cached
-
The number of non-cached queries
(not cachable, or due to
query_cache_type
). Qcache_queries_in_cache
- The number of queries registered in the cache.
Qcache_total_blocks
- The total number of blocks in the query cache.
Questions
- The number of queries that have been sent to the server.
Rpl_status
- The status of failsafe replication (not yet implemented).
Select_full_join
- The number of joins that do not use indexes. If this value is not 0, you should carefully check the indexes of your tables. This variable was added in MySQL 3.23.25.
Select_full_range_join
- The number of joins that used a range search on a reference table. This variable was added in MySQL 3.23.25.
Select_range
- The number of joins that used ranges on the first table. (It's normally not critical even if this is big.) This variable was added in MySQL 3.23.25.
Select_range_check
- The number of joins without keys that check for key usage after each row. (If this is not 0, you should carefully check the indexes of your tables.) This variable was added in MySQL 3.23.25.
Select_scan
- The number of joins that did a full scan of the first table. This variable was added in MySQL 3.23.25.
Slave_open_temp_tables
- The number of temporary tables currently open by the slave SQL thread. This variable was added in MySQL 3.23.29.
Slave_running
-
This is
ON
if this server is a slave that is connected to a master. This variable was added in MySQL 3.23.16. Slow_launch_threads
-
The number of threads that have taken more than
slow_launch_time
seconds to create. This variable was added in MySQL 3.23.15. Slow_queries
-
The number of queries that have taken more than
long_query_time
seconds. See section 5.9.5 The Slow Query Log. Sort_merge_passes
-
The number of merge passes the sort algorithm has had to do. If this value is
large, you should consider increasing the value of the
sort_buffer_size
system variable. This variable was added in MySQL 3.23.28. Sort_range
- The number of sorts that were done with ranges. This variable was added in MySQL 3.23.25.
Sort_rows
- The number of sorted rows. This variable was added in MySQL 3.23.25.
Sort_scan
- The number of sorts that were done by scanning the table. This variable was added in MySQL 3.23.25.
Ssl_xxx
- Variables used for SSL connections. These variables were added in MySQL 4.0.0.
Table_locks_immediate
- The number of times that a table lock was acquired immediately. This variable was added as of MySQL 3.23.33.
Table_locks_waited
- The number of times that a table lock could not be acquired immediately and a wait was needed. If this is high, and you have performance problems, you should first optimize your queries, and then either split your table or tables or use replication. This variable was added as of MySQL 3.23.33.
Threads_cached
- The number of threads in the thread cache. This variable was added in MySQL 3.23.17.
Threads_connected
- The number of currently open connections.
Threads_created
-
The number of threads created to handle connections.
If
Threads_created
is big, you may want to increase thethread_cache_size
value. The cache hit rate can be calculated asThreads_created
/Connections
. This variable was added in MySQL 3.23.31. Threads_running
- The number of threads that are not sleeping.
Uptime
- The number of seconds the server has been up.
5.3 The MySQL Server Shutdown Process
The server shutdown process can be summarized like this:
- The shutdown process is initiated
- The server creates a shutdown thread if necessary
- The server stops accepting new connections
- The server terminates current activity
- Storage engines are shut down or closed
- The server exits
A more detailed description of the process follows:
-
The shutdown process is initiated
Server shutdown can be initiated several ways. For example, a user with
the
SHUTDOWN
privilege can execute a @command{mysqladmin shutdown} command. @command{mysqladmin} can be used on any platform supported by MySQL. Other operating sytem-specific shutdown initiation methods are possible as well: The server shuts down on Unix when it receives aSIGTERM
signal. A server running as a service on Windows shuts down when the services manager tells it to. -
The server creates a shutdown thread if necessary
Depending on how shutdown was initiated, the server might create a thread to
handle the shutdown process. If shutdown was requested by a client, a
shutdown thread is created. If shutdown is the result of receiving a
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 will appear in the error log:Error: Can't create thread to kill server
- The server stops accepting new connections To prevent new activity from being initiated during shutdown, the server stops accepting new client connections. It does this by closing the network connections to which it normally listens for connections: the TCP/IP port, the Unix socket file, the Windows named pipe.
-
The server terminates current activity
For each thread that is associated with a client connection, the connection
to the client is broken and the thread is marked as killed. Threads die when
they notice that they are so marked. Threads for idle connections die
quickly. Threads that currently are processing queries check their state
periodically and take longer to die. For additional information about
thread termination, see section 14.5.4.3
KILL
Syntax, in particular for the instructions about killedREPAIR TABLE
orOPTIMIZE TABLE
operations onMyISAM
tables. For threads that have an open transaction, the tranaction is rolled back. Note that if a thread is updating a non-transactional table, an operation such as a multiple-rowUPDATE
orINSERT
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. - Storage engines are shut down or closed At this stage, the table cache is flushed and all open tables are closed. Each storage engine performs any actions necessary for tables that it manages. For example, MyISAM flushes any pending index writes for a table. InnoDB flushes its buffer pool to disk, writes the current LSN to the tablespace, and terminates its own internal threads.
- The server exits
5.4 General Security Issues
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.
5.4.1 General Security Guidelines
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:
-
Do not ever give anyone (except MySQL
root
accounts) access to theuser
table in themysql
database! This is critical. The encrypted password is the real password in MySQL. Anyone who knows the password that is listed in theuser
table and has access to the host listed for the account can easily log in as that user. -
Learn the MySQL access privilege system. The
GRANT
andREVOKE
statements are used for controlling access to MySQL. Do not grant any more privileges than necessary. Never grant privileges to all hosts. Checklist:-
Try
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 MySQLroot
user with full privileges! Review the MySQL installation instructions, paying particular attention to the information about setting aroot
password. See section 2.4.3 Securing the Initial MySQL Accounts. -
Use the
SHOW GRANTS
statement and check to see who has access to what. Then use theREVOKE
statement to remove those privileges that are not necessary.
-
Try
-
Do not store any plain-text passwords in your database. If your
computer becomes compromised, the intruder can take the full list of
passwords and use them. Instead, use
MD5()
,SHA1()
, or some other one-way hashing function. - Do not choose passwords from dictionaries. There are special programs to break them. Even passwords like ``xfish98'' are very bad. Much better is ``duag98'' which contains the same word ``fish'' but typed one key to the left on a standard QWERTY keyboard. Another method is to use ``Mhall'' which is taken from the first characters of each word in the sentence ``Mary had a little lamb.'' This is easy to remember and type, but difficult to guess for someone who does not know it.
-
Invest in a firewall. This protects you from at least 50% of all types of
exploits in any software. Put MySQL behind the firewall or in
a demilitarized zone (DMZ).
Checklist:
-
Try to scan your ports from the Internet using a tool such as
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, whereserver_host
is the host on which your MySQL server runs:shell> telnet server_host 3306
If 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. Iftelnet
just hangs or the connection is refused, everything is OK; the port is blocked.
-
Try to scan your ports from the Internet using a tool such as
-
Do not trust any data entered by users of your applications. They can try to trick your
code by entering special or escaped character sequences in Web forms,
URLs, or whatever application you have built. Be sure that your
application remains secure if a user enters something like ``
; 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 asSELECT * FROM table WHERE ID=234
when a user enters the value234
, the user can enter the value234 OR 1=1
to cause the application to generate the querySELECT * 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:- Try to enter `'' and `"' in all your Web forms. If you get any kind of MySQL error, investigate the problem right away.
-
Try to modify any dynamic URLs by adding
%22
(`"'),%23
(`#'), and%27
(`'') in the URL. - Try to modify data types in dynamic URLs from numeric ones to character ones containing characters from previous examples. Your application should be safe against this and similar attacks.
- Try to enter characters, spaces, and special symbols rather than numbers in numeric fields. Your application should remove them before passing them to MySQL or else generate an error. Passing unchecked values to MySQL is very dangerous!
- Check data sizes before passing them to MySQL.
- Consider having your application connect to the database using a different username than the one you use for administrative purposes. Do not give your applications any access privileges they do not need.
-
Many application programming interfaces provide a means of escaping special
characters in data values. Properly used, this prevents application users from
entering values that cause the application to generate statements that have a
different effect than you intend:
-
MySQL C API:
Use the
mysql_real_escape_string()
API call. -
MySQL++:
Use the
escape
andquote
modifiers for query streams. -
PHP:
Use the
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, useaddslashes()
instead. -
Perl DBI:
Use the
quote()
method or use placeholders. -
Java JDBC:
Use a
PreparedStatement
object and placeholders.
-
MySQL C API:
Use the
- Do not transmit plain (unencrypted) data over the Internet. This information is accessible to everyone who has the time and ability to intercept it and use it for their own purposes. Instead, use an encrypted protocol such as SSL or SSH. MySQL supports internal SSL connections as of Version 4.0.0. SSH port-forwarding can be used to create an encrypted (and compressed) tunnel for the communication.
-
Learn to use the
tcpdump
andstrings
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.
5.4.2 Making MySQL Secure Against Attackers
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:
-
Use passwords for all MySQL users. A client program does not necessarily
know the identity of the person running it. It is common for client/server
applications that the user can specify any username to the client program.
For example, anyone can use the @command{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 theSET PASSWORD
statement. It is also possible to update theuser
table in themysql
database directly. For example, to change the password of all MySQL accounts that have a username ofroot
, do this:shell> mysql -u root mysql> UPDATE mysql.user SET Password=PASSWORD('newpwd') -> WHERE User='root'; mysql> FLUSH PRIVILEGES;
-
Don't run the MySQL server as the Unix
root
user. This is very dangerous, because any user with theFILE
privilege will be able to create files asroot
(for example,~root/.bashrc
). To prevent this, @command{mysqld} refuses to run asroot
unless that is specified explicitly using a--user=root
option. @command{mysqld} can be run as an ordinary unprivileged user instead. You can also create a separate Unix account namedmysql
to make everything even more secure. Use the account only for administering MySQL. To start @command{mysqld} as another Unix user, add auser
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=mysql
This causes the server to start as the designated user whether you start it manually or by using @command{mysqld_safe} or @command{mysql.server}. For more details, see section A.3.2 How to Run MySQL as a Normal User. Running @command{mysqld} as a Unix user other thanroot
does not mean that you need to change theroot
username in theuser
table. Usernames for MySQL accounts have nothing to do with usernames for Unix accounts. -
Don't allow the use of symlinks to tables. (This can be disabled with the
--skip-symbolic-links
option.) This is especially important if you run @command{mysqld} asroot
, 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. - Make sure that the only Unix user with read or write privileges in the database directories is the user that @command{mysqld} runs as.
-
Don't grant the
PROCESS
orSUPER
privilege to non-administrative users. The output of @command{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 anUPDATE user SET password=PASSWORD('not_secure')
query. @command{mysqld} reserves an extra connection for users who have theSUPER
privilege (PROCESS
before MySQL 4.0.2), so that a MySQLroot
user can log in and check server activity even if all normal connections are in use. TheSUPER
privilege can be used to terminate client connections, change server operation by changing the value of system variables, and control replication servers. -
Don't grant the
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 @command{mysqld} daemon! To make this a bit safer, files generated withSELECT ... INTO OUTFILE
will not overwrite existing files and are writable by everyone. TheFILE
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 usingLOAD DATA
to load `/etc/passwd' into a table, which then can be displayed withSELECT
. - If you don't trust your DNS, you should use IP numbers rather than hostnames in the grant tables. In any case, you should be very careful about creating grant table entries using hostname values that contain wildcards!
-
If you want to restrict the number of connections allowed to a single account,
you can do so by setting the
max_user_connections
variable in @command{mysqld}. TheGRANT
statement also supports resource control options for limiting the extent of server use allowed to an account.
5.4.3 Startup Options for @command{mysqld} Concerning Security
The following @command{mysqld} options affect security:
--local-infile[={0|1}]
-
If you start the server with
--local-infile=0
, clients cannot useLOCAL
inLOAD DATA
statements. See section 5.4.4 Security Issues withLOAD DATA LOCAL
. --safe-show-database
-
With this option, the
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 now aSHOW DATABASES
privilege that can be used to control access to database names on a per-account basis. See section 14.5.1.2GRANT
andREVOKE
Syntax. --safe-user-create
-
If this is enabled, a user cannot create new users with the
GRANT
statement unless the user has theINSERT
privilege for themysql.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 will ensure that the user can't change any privilege columns directly, but has to use theGRANT
statement to give privileges to other users. --secure-auth
- Disallow authentication for accounts that have old (pre-4.1) passwords. This option is available as of MySQL 4.1.1.
--skip-grant-tables
-
This option causes the server not to use the privilege system at all. This
gives everyone full access to all databases! (You can tell a running
server to start using the grant tables again by executing a @command{mysqladmin
flush-privileges} or @command{mysqladmin reload} command, or by issuing a
FLUSH PRIVILEGES
statement.) --skip-name-resolve
-
Hostnames are not resolved. All
Host
column values in the grant tables must be IP numbers orlocalhost
. --skip-networking
- Don't allow TCP/IP connections over the network. All connections to @command{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
-
With this option, the
SHOW DATABASES
statement is allowed only to users who have theSHOW 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 theSHOW DATABASES
privilege or some privilege for the database.
5.4.4 Security Issues with 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:
-
The transfer of the file from the client host to the server host is initiated
by the MySQL server. In theory, a patched server could be built that would
tell the client program to transfer a file of the server's choosing rather
than the file named by the client in the
LOAD DATA
statement. Such a server could access any file on the client host to which the client user has read access. -
In a Web environment where the clients are connecting from a Web
server, a user could use
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):
-
By default, all MySQL clients and libraries in binary distributions are
compiled with the
--enable-local-infile
option, to be compatible with MySQL 3.23.48 and before. -
If you build MySQL from source but don't use the
--enable-local-infile
option to @command{configure},LOAD DATA LOCAL
cannot be used by any client unless it is written explicitly to invokemysql_options(... MYSQL_OPT_LOCAL_INFILE, 0)
. See section 21.2.3.167mysql_options()
. -
You can disable all
LOAD DATA LOCAL
commands from the server side by starting @command{mysqld} with the--local-infile=0
option. -
For the @command{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 @command{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. -
If you use
LOAD DATA LOCAL
in Perl scripts or other programs that read the[client]
group from option files, you can add thelocal-infile=1
option to that group. However, to keep this from causing problems for programs that do not understandlocal-infile
, specify it using theloose-
prefix:[client] loose-local-infile=1
Theloose-
prefix can be used as of MySQL 4.0.2. -
If
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
5.5 The MySQL Access Privilege System
MySQL has an advanced but non-standard security/privilege system. This section describes how it works.
5.5.1 What the Privilege System Does
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 an anonymous user and
to grant privileges for MySQL-specific functions such as LOAD
DATA INFILE
and administrative operations.
5.5.2 How the Privilege System Works
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. 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 joe
one set
of privileges for connections from office.com
, and a different set
of privileges for connections from elsewhere.com
.
MySQL access control involves two stages:
- Stage 1: The server checks whether you are even allowed to connect.
-
Stage 2: Assuming that you can connect, the server checks each statement you issue
to see whether you have sufficient privileges to perform it. For
example, if you try to select rows from a table in a database or drop a table
from the database, the server verifies that you have the
SELECT
privilege for the table or theDROP
privilege for the database.
If your privileges are changed (either by yourself or someone else) while you are connected, those changes will 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 14.5.1.2 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
| |
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 | |||
ssl_type | |||
ssl_cipher | |||
x509_issuer | |||
x509_subject | |||
max_questions | |||
max_updates | |||
max_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.
The Create_view_priv
and Show_view_priv
columns were added in
MySQL 5.0.1.
During the second stage of access control (request verification), the server
may, if the request involves tables, additionally consult the
tables_priv
and columns_priv
tables that provide finer control
at the table and column levels. The columns in these
tables are shown here:
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.
Each grant table contains scope columns and privilege columns:
-
Scope columns determine the scope of each entry (row) in the tables; that is, the
context in which the entry applies. For example, a
user
table entry withHost
andUser
values of'thomas.loc.gov'
and'bob'
would be used for authenticating connections made to the server from the hostthomas.loc.gov
by a client that specifies a username ofbob
. Similarly, adb
table entry withHost
,User
, andDb
column values of'thomas.loc.gov'
,'bob'
and'reports'
would be used whenbob
connects from the hostthomas.loc.gov
to access thereports
database. Thetables_priv
andcolumns_priv
tables contain scope columns indicating tables or table/column combinations to which each entry applies. - Privilege columns indicate the privileges granted by a table entry; that is, what operations can be performed. The server combines the information in the various grant tables to form a complete description of a user's privileges. The rules used to do this are described in section 5.5.6 Access Control, Stage 2: Request Verification.
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(60)
|
Column_name | CHAR(60)
|
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 disabled
or enabled, with the default being disabled.
In the tables_priv
and columns_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'
|
Briefly, the server uses the grant tables as follows:
-
The
user
table scope columns determine whether to reject or allow incoming connections. For allowed connections, any privileges granted in theuser
table indicate the user's global (superuser) privileges. These privileges apply to all databases on the server. -
The
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. -
The
host
table is used in conjunction with thedb
table when you want a givendb
table entry 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 theHost
value empty in the user'sdb
table entry, then populate thehost
table with an entry for each of those hosts. This mechanism is described more detail in section 5.5.6 Access Control, Stage 2: Request Verification. Note: Thehost
table is not affected by theGRANT
andREVOKE
statements. Most MySQL installations need not use this table at all. -
The
tables_priv
andcolumns_priv
tables are similar to thedb
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.
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 @command{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 @command{mysqladmin flush-privileges} or
@command{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. One way to check
the privileges for a given account is to 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 @command{mysqlaccess} script, which Yves Carlier has
provided for the MySQL distribution. Invoke @command{mysqlaccess} with
the --help
option to find out how it works.
Note that @command{mysqlaccess} checks access using only the user
,
db
, and host
tables. It does not check table or column
privileges specified in the tables_priv
or columns_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.
5.5.3 Privileges Provided by MySQL
Information about account privileges is stored in the user
, db
,
host
, tables_priv
, and columns_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 this manual to refer to the privileges provided by
MySQL are shown in the following table, along with the table 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 14.5.1.2 GRANT
and REVOKE
Syntax.
Privilege | Column | Context |
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 | Create_priv | databases, tables, or indexes |
DROP | Drop_priv | databases or tables |
GRANT | Grant_priv | databases or tables |
REFERENCES | References_priv | databases or tables |
CREATE TEMPORARY TABLES | Create_tmp_table_priv | server administration |
EXECUTE | Execute_priv | server administration |
FILE | File_priv | file access on server host |
LOCK TABLES | Lock_tables_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.
The EXECUTE
and REFERENCES
privileges currently are unused.
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 @command{mysql} client as a simple calculator
to evaluate expressions that make no reference to tables:
mysql> SELECT 1+1; mysql> SELECT PI()*2;
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 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 GRANT
privilege allows you to give to other users those
privileges that you yourself possess.
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 @command{mysqladmin} program or by issuing SQL statements. The following table shows which @command{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 @command{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 14.5.4.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 when they 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 privileges to only those accounts that need them, but you should exercise particular caution in granting administrative privileges:
-
The
GRANT
privilege allows users to give their privileges to other users. Two users with different privileges and with theGRANT
privilege are able to combine privileges. -
The
ALTER
privilege may be used to subvert the privilege system by renaming tables. -
The
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 usingSELECT
to transfer its contents to the client host. -
The
SHUTDOWN
privilege can be abused to deny service to other users entirely by terminating the server. -
The
PROCESS
privilege can be used to view the plain text of currently executing queries, including queries that set or change passwords. -
The
SUPER
privilege can be used to terminate other clients or change how the server operates. -
Privileges granted for the
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 theuser
tablePassword
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:
- You cannot explicitly specify that a given user should be denied access. That is, you cannot explicitly match a user and then refuse the connection.
- You cannot specify that a user has privileges to create or drop tables in a database but not to create or drop the database itself.
5.5.4 Connecting to the MySQL Server
MySQL client programs generally expect you to specify connection parameters when you want to access a MySQL server:
- The name of the host where the MySQL server is running
- Your username
- Your password
For example, the
@command{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 will prompt 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 @command{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:
-
The default hostname is
localhost
. -
The default username is
ODBC
on Windows and your Unix login name on Unix. -
No password is supplied if
-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:
-
You can specify connection parameters in the
[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_pass
Option files are discussed further in section 4.3.2 Using Option Files. -
You can specify some connection parameters using environment variables. The
host can be specified for @command{mysql} using
MYSQL_HOST
. The MySQL username can be specified usingUSER
(this is for Windows and NetWare only). The password can be specified usingMYSQL_PWD
, although this is insecure; see section 5.6.6 Keeping Your Password Secure. For a list of variables, see section E Environment Variables.
5.5.5 Access Control, Stage 1: Connection Verification
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:
- The client host from which you connect
- Your MySQL username
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:
-
A
Host
value may be a hostname or an IP number, or'localhost'
to indicate the local host. -
You can use the wildcard characters `%' and `_' in
Host
column values. These have the same meaning as for pattern-matching operations performed with theLIKE
operator. For example, aHost
value of'%'
matches any hostname, whereas a value of'%.mysql.com'
matches any host in themysql.com
domain. -
As of MySQL 3.23, for
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 [email protected]'192.58.197.0/255.255.255.0';
This allowsdavid
to connect from any client host having an IP numberclient_ip
for which the following condition is true:client_ip & netmask = host_ip
That is, for theGRANT
statement just shown:client_ip & 255.255.255.0 = 192.58.197.0
IP numbers that satisfy this condition and can connect to the MySQL server are those that lie in the range from192.58.197.0
to192.58.197.255
. -
A blank
Host
value in adb
table record means that its privileges should be combined with those in the entry in thehost
table that matches the client hostname. The privileges are combined using an AND (intersection) operation, not OR (union). You can find more information about thehost
table in section 5.5.6 Access Control, Stage 2: Request Verification. A blankHost
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 will never match
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
entry 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 entry 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:
-
Whenever the server reads the
user
table into memory, it sorts the entries. - When a client attempts to connect, the server looks through the entries in sorted order.
- The server uses the first entry that matches the client hostname and username.
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'
entry 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 entry, 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 will be 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 entry containing 'jeffrey'
as the User
column value, but by the entry with no username!
As a result, jeffrey
will be 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 entry
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 13.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.
5.5.6 Access Control, Stage 2: Request Verification
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:
-
The wildcard characters `%' and `_' can be used in the
Host
andDb
columns of either table. These have the same meaning as for pattern-matching operations performed with theLIKE
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 theGRANT
statement. -
A
'%'
Host
value in thedb
table means ``any host.'' A blankHost
value in thedb
table means ``consult thehost
table for further information'' (a process that is described later in this section). -
A
'%'
or blankHost
value in thehost
table means ``any host.'' -
A
'%'
or blankDb
value in either table means ``any database.'' -
A blank
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:
-
The wildcard characters `%' and `_' can be used in the
Host
column of either table. These have the same meaning as for pattern-matching operations performed with theLIKE
operator. -
A
'%'
or blankHost
value in either table means ``any host.'' -
The
Db
,Table_name
, andColumn_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 will 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 entry because that is the only table
that specifies administrative privileges. Access is granted if the entry
allows the requested operation and denied otherwise. For example, if you
want to execute @command{mysqladmin shutdown} but your user
table entry
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 entry. If the entry 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:
-
The server looks in the
db
table for a match on theHost
,Db
, andUser
columns. TheHost
andUser
columns are matched to the connecting user's hostname and MySQL username. TheDb
column is matched to the database that the user wants to access. If there is no entry for theHost
andUser
, access is denied. -
If there is a matching
db
table entry and itsHost
column is not blank, that entry defines the user's database-specific privileges. -
If the matching
db
table entry'sHost
column is blank, it signifies that thehost
table enumerates which hosts should be allowed access to the database. In this case, a further lookup is done in thehost
table to find a match on theHost
andDb
columns. If nohost
table entry 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 thedb
andhost
table entries; that is, the privileges that are'Y'
in both entries. (This way you can grant general privileges in thedb
table entry and then selectively restrict them on a host-by-host basis using thehost
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
entry 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 entry grants one
privilege and the db
table entry 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 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
@command{mysqlaccess}) to make sure that your access privileges are
actually set up the way you think they are.
5.5.7 When Privilege Changes Take Effect
When @command{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:
- Table and column privilege changes take effect with the client's next request.
-
Database privilege changes take effect at the next
USE db_name
statement. - Changes to global privileges and passwords take effect the next time the client connects.
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 @command{mysqladmin
flush-privileges} or @command{mysqladmin reload} command.
If you change the grant tables directly but forget to reload them, your changes will have no effect until you restart the server. This may leave you wondering why your changes don't seem to make any difference!
5.5.8 Causes of Access denied
Errors
If 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.
-
Make sure that the server is running. If it is not running, you cannot connect to it.
For example, if you attempt to connect to the server and see a message such
as one of those following, one cause might be that the server is not running:
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 what port is used, and where the socket is, you can do:shell> netstat -l | grep mysql
-
The grant tables must be properly set up so that the server can use them for
access control. For some distribution types (such as binary distributions
on Windows on RPM distributions on Linux), the installation process
initializes the
mysql
database containing the grant tables. For distributions that do not do this, you should initialize the grant tables manually by running the @command{mysql_install_db} script. For details, see section 2.4.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 @command{mysql_install_db} script. After running this script and starting the server, test the initial privileges by executing this command:shell> mysql -u root test
The server should let you connect without error. -
After a fresh installation, you should connect to the server and set up
your users and their access permissions:
shell> mysql -u root mysql
The server should let you connect because the MySQLroot
user has no password initially. That is also a security risk, so setting the password for theroot
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.4.3 Securing the Initial MySQL Accounts. - If you have updated an existing MySQL installation to a newer version, did you run the @command{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.5.8 Upgrading the Grant Tables.
-
If a client program receives the following error message when it tries
to connect, it means that the server expects passwords in a newer format
than the client is capable of generating:
shell> mysql Client does not support authentication protocol requested by server; consider upgrading MySQL client
For information on how to deal with this, see section 5.5.9 Password Hashing in MySQL 4.1 and section A.2.3Client does not support authentication protocol
. -
If you try to connect as
root
and get the following error, it means that you don't have an entry in theuser
table with aUser
column value of'root'
and that @command{mysqld} cannot resolve the hostname for your client:Access denied for user ''@'unknown' to database mysql
In 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. -
Remember that client programs will use connection parameters specified
in option files or environment variables. If a client program seems to
be sending incorrect default connection parameters when you don't specify
them on the command line, check your environment and any applicable option
files. For example, if you get
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 version
The option files that clients use are listed in section 4.3.2 Using Option Files. Environment variables are listed in section E Environment Variables. -
If you get the following error, it means that you are using an incorrect
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 theroot
password, you can restart @command{mysqld} with--skip-grant-tables
to change the password. See section A.4.1 How to Reset the Root Password. -
If you change a password by using
SET PASSWORD
,INSERT
, orUPDATE
, you must encrypt the password using thePASSWORD()
function. If you do not usePASSWORD()
for these statements, the password will not work. For example, the following statement sets a password, but fails to encrypt it, so the user will not be 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');
ThePASSWORD()
function is unnecessary when you specify a password using theGRANT
statement or the @command{mysqladmin password} command, both of which automatically usePASSWORD()
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 tolocalhost
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 @command{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 auser
table entry on the server host, even though you are running the client program on the same host as the server. -
If you get an
Access denied
error when trying to connect to the database withmysql -u user_name
, you may have a problem with theuser
table. Check this by executingmysql -u root mysql
and issuing this SQL statement:mysql> SELECT * FROM user;
The result should include an entry with theHost
andUser
columns matching your computer's hostname and your MySQL username. -
The
Access denied
error message will tell 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 entry in theuser
table that exactly matches the hostname and username that were given in the error message. For example, if you get an error message that containsusing password: NO
, it means that you tried to log in without an password. -
If the following error occurs when you try to connect from a host other than
the one on which the MySQL server is running, it means that there is no row
in the
user
table with aHost
value that matches the client host:Host ... is not allowed to connect to this MySQL server
You 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 entry with'%'
as theHost
column value in theuser
table and restart @command{mysqld} with the--log
option on the server machine. After trying to connect from the client machine, the information in the MySQL log will indicate how you really did connect. (Then change the'%'
in theuser
table entry 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 theglibc
library than the one you are using. In this case, you should either upgrade your operating system orglibc
, 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. -
If you specify a hostname when trying to connect, but get an error message
where the hostname is not shown or is an IP number,
it means that the MySQL server got an error when trying to resolve the
IP number of the client host to a name:
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 @command{mysqladmin flush-hosts} to reset the internal DNS hostname cache. See section 7.5.6 How MySQL Uses DNS. Some permanent solutions are:- Try to find out what is wrong with your DNS server and fix it.
- Specify IP numbers rather than hostnames in the MySQL grant tables.
-
Put an entry for the client machine name in
/etc/hosts
. -
Start @command{mysqld} with the
--skip-name-resolve
option. -
Start @command{mysqld} with the
--skip-host-cache
option. -
On Unix, if you are running the server and the client on the same machine,
connect to
localhost
. Unix connections tolocalhost
use a Unix socket file rather than TCP/IP. -
On Windows, if you are running the server and the client on the same machine
and the server supports named pipe connections, connect to the hostname
.
(period). Connections to.
use a named pipe rather than TCP/IP.
-
If
mysql -u root test
works butmysql -h your_hostname -u root test
results inAccess denied
(where your_hostname is the actual hostname of the local host), you may not have the correct name for your host in theuser
table. A common problem here is that theHost
value in the user table entry 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 theuser
table, but your DNS tells MySQL that your hostname is'tcx.subnet.se'
, the entry will not work. Try adding an entry to theuser
table that contains the IP number of your host as theHost
column value. (Alternatively, you could add an entry to theuser
table with aHost
value that contains a wildcard; for example,'tcx.%'
. However, use of hostnames ending with `%' is insecure and is not recommended!) -
If
mysql -u user_name test
works butmysql -u user_name other_db_name
does not, you have not granted database access for other_db_name to the given user. -
If
mysql -u user_name
works when executed on the server host, butmysql -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. -
If you can't figure out why you get
Access denied
, remove from theuser
table all entries that haveHost
values containing wildcards (entries that contain `%' or `_'). A very common error is to insert a new entry withHost
='%'
andUser
='some_user'
, thinking that this will allow you to specifylocalhost
to connect from the same machine. The reason that this doesn't work is that the default privileges include an entry withHost
='localhost'
andUser
=''
. Because that entry has aHost
value'localhost'
that is more specific than'%'
, it is used in preference to the new entry when connecting fromlocalhost
! The correct procedure is to insert a second entry withHost
='localhost'
andUser
='some_user'
, or to delete the entry withHost
='localhost'
andUser
=''
. After deleting the entry, remember to issue aFLUSH PRIVILEGES
statement to reload the grant tables. -
If you get the following error, you may have a problem with the
db
orhost
table:Access to database denied
If the entry selected from thedb
table has an empty value in theHost
column, make sure that there are one or more corresponding entries in thehost
table specifying which hosts thedb
table entry applies to. -
If you are able to connect to the MySQL server, but get an
Access denied
message whenever you issue aSELECT ... INTO OUTFILE
orLOAD DATA INFILE
statement, your entry in theuser
table doesn't have theFILE
privilege enabled. -
If you change the grant tables directly (for example, by using
INSERT
,UPDATE
, orDELETE
statements) and your changes seem to be ignored, remember that you must execute aFLUSH PRIVILEGES
statement or a @command{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 theroot
password with anUPDATE
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! - If your privileges seem to have changed in the middle of a session, it may be that a MySQL administrator has changed them. Reloading the grant tables affects new client connections, but it also affects existing connections as indicated in section 5.5.7 When Privilege Changes Take Effect.
-
If you have access problems with a Perl, PHP, Python, or ODBC program, try to
connect to the server with
mysql -u user_name db_name
ormysql -u user_name -pyour_pass db_name
. If you are able to connect using the @command{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 will prompt you for the password.) -
For testing, start the @command{mysqld} server with the
--skip-grant-tables
option. Then you can change the MySQL grant tables and use the @command{mysqlaccess} script to check whether your modifications have the desired effect. When you are satisfied with your changes, execute @command{mysqladmin flush-privileges} to tell the @command{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.) -
If everything else fails, start the @command{mysqld} server with a debugging
option (for example,
--debug=d,general,query
). This will print host and user information about attempted connections, as well as information about each command issued. See section D.1.2 Creating Trace Files. -
If you have any other problems with the MySQL grant tables and
feel you must post the problem to the mailing list, always provide a
dump of the MySQL grant tables. You can dump the tables with
the @command{mysqldump mysql} command. As always, post your problem using
the @command{mysqlbug} script. See section 1.7.1.3 How to Report Bugs or Problems. In some cases, you may need
to restart @command{mysqld} with
--skip-grant-tables
to run @command{mysqldump}.
5.5.9 Password Hashing in MySQL 4.1
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:
-
When a client attempts to connect to the server, there is an initial
authentication step in which the client must present a password that has
a hash value matching the hash value stored in the
user
table for the account that the client wants to use. -
After the client connects, it can (if it has sufficient privileges) set or
change the password hashes for accounts listed in the
user
table. The client can do this by using thePASSWORD()
function to generate a password hash, or by using theGRANT
orSET 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 @command{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:
-
If you perform a new installation of MySQL 4.1, the
Password
column will be made 41 bytes long automatically. -
If you upgrade an older installation to 4.1, you should run the
@command{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 obvious difference is the length (16 bytes versus 41 bytes).
- A second difference is that password hashes in the new format always begin with a `*' character, whereas passwords in the old format never do.
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:
- If the column is short, only short-hash authentication is used.
-
If the column is long, it can hold either short or long hashes, and
the server can use either format:
- Pre-4.1 clients can connect, although because they know only about the old hashing mechanism, they can authenticate only for accounts that have short hashes.
- 4.1 clients can authenticate for accounts that have short or long hashes.
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:
- Pre-4.1 client authenticating for account with short password hash
- 4.1 client authenticating for account with short password hash
- 4.1 client authenticating for account with long password hash
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:
-
The
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 usingPASSWORD()
,GRANT
, orSET PASSWORD
. This is the behavior that occurs if you have upgraded to 4.1 but have not yet run the @command{mysql_fix_privilege_tables} script to widen thePassword
column. -
If the
Password
column is wide, it can store either short or long password hashes. In this case,PASSWORD()
,GRANT
, andSET 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:
- An old client connects to an account that has a short password hash.
-
The client changes its own password. Without
--old-passwords
, this results in the account having a long password hash. - The next time the old client attempts to connect to the account, it cannot, because the account now has a long password hash that requires the new hashing mechanism during authentication. (Once an account has a long password hash in the user table, only 4.1 clients can authenticate for it, because pre-4.1 clients do not understand long hashes.)
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 will 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 will 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:
-
Only short hashes can be stored in the
Password
column. - The server uses only short hashes during client authentication.
-
For connected clients, password hash-generating operations
involving
PASSWORD()
,GRANT
, orSET PASSWORD
use short hashes exclusively. Any change to an account's password results in that account having a short password hash. -
The
--old-passwords
option can be used but is superfluous because with a shortPassword
column, the server will generate only short password hashes anyway.
Scenario 2: Long Password
column; server not started with
--old-passwords
option:
-
Short or long hashes can be stored in the
Password
column. - 4.1 clients can authenticate for accounts that have short or long hashes.
- Pre-4.1 clients can authenticate only for accounts that have short hashes.
-
For connected clients, password hash-generating operations involving
PASSWORD()
,GRANT
, orSET 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:
-
Short or long hashes can be stored in the
Password
column. -
4.1 clients can authenticate for accounts that have short or long
hashes (but note that it is possible to create long hashes only when
the server is started without
--old-passwords
). - Pre-4.1 clients can authenticate only for accounts that have short hashes.
-
For connected clients, password hash-generating operations
involving
PASSWORD()
,GRANT
, orSET 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.
5.5.9.1 Implications of Password Hashing Changes for Application Programs
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 will break. 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()
.
5.5.9.2 Password Hashing in MySQL 4.1.0
Password hashing in MySQL 4.1.0 differs from hashing in 4.1.1 and up. The 4.1.0 differences are:
- Password hashes are 45 bytes long rather than 41 bytes.
-
The
PASSWORD()
function is non-repeatable. That is, with a given argument X, successive calls toPASSWORD(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.
5.6 MySQL User Account Management
This section describes how to set up accounts for clients of your MySQL server. It discusses the following topics:
- The meaning of account names and passwords as used in MySQL and how that compares to names and passwords used by your operating system
- How to set up new accounts and remove existing accounts
- How to change passwords
- Guidelines for using passwords securely
- How to use secure connections with SSL
5.6.1 MySQL Usernames and Passwords
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:
-
Usernames, as used by MySQL for authentication purposes, have nothing to do
with usernames (login names) as used by Windows or Unix. On Unix, most
MySQL clients by default try to log in using the current Unix username as
the MySQL username, but that is for convenience only. The default can be
overridden easily, because client programs allow any username to be
specified with a
-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 will be able to connect successfully to the server. - MySQL usernames can be up to 16 characters long. Operating system usernames might have a different maximum length. For example, Unix usernames typically are limited to eight characters.
- MySQL passwords have nothing to do with passwords for logging in to your operating system. There is no necessary connection between the password you use to log in to a Windows or Unix machine and the password you use to access the MySQL server on that machine.
-
MySQL encrypts passwords using its own algorithm. This encryption is
different from that used during the Unix login process. MySQL password
encryption is the same as that implemented by the
PASSWORD()
SQL function. Unix password encryption is the same as that implemented by theENCRYPT()
SQL function. See the descriptions of thePASSWORD()
andENCRYPT()
functions in section 13.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 themysql
database is captured. (In earlier versions, even though passwords are stored in encrypted form in theuser
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.4.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 14.5.1.2 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 will print a prompt and wait 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.
5.6.2 Adding New User Accounts to MySQL
You can create MySQL accounts in two ways:
-
By using
GRANT
statements - By manipulating the MySQL grant tables directly
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 14.5.1.2 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 @command{mysql} client program to
set up new users. These examples assume that privileges are set up
according to the defaults described in section 2.4.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 @command{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 @command{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:
-
Two of the accounts have a username of
monty
and a password ofsome_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 formonty
to be able to connect from anywhere asmonty
. Without thelocalhost
account, the anonymous-user account forlocalhost
that is created by @command{mysql_install_db} would take precedence whenmonty
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 specificHost
column value than the'monty'@'%'
account and thus comes earlier in theuser
table sort order. (user
table sorting is discussed in section 5.5.5 Access Control, Stage 1: Connection Verification.) -
One account has a username of
admin
and no password. This account can be used only by connecting from the local host. It is granted theRELOAD
andPROCESS