MySQL 5.0 Reference Manual My SQL Refman En.a4

User Manual: MySQL 5.0 Reference Manual Troubleshoot MySQL 5.0 |

Open the PDF directly: View PDF .
Page Count: 2292

Download
Open PDF In Browser	View PDF

MySQL 5.0 Reference Manual

Abstract
This is the MySQL™ Reference Manual. It documents MySQL 5.0 through 5.0.96.
End of Product Lifecycle. Active development for MySQL Database Server version 5.0 has ended. Oracle
offers various support offerings which may be of interest. For details and more information, see the MySQL
section of the Lifetime Support Policy for Oracle Technology Products (http://www.oracle.com/us/support/lifetimesupport/index.html). Please consider upgrading to a recent version.
MySQL 5.0 features.
This manual describes features that are not included in every edition of MySQL 5.0; such
features may not be included in the edition of MySQL 5.0 licensed to you. If you have any questions about the
features included in your edition of MySQL 5.0, refer to your MySQL 5.0 license agreement or contact your Oracle
representative.
For notes detailing the changes in each release, see the MySQL 5.0 Release Notes.
For help with using MySQL, please visit either the MySQL Forums or MySQL Mailing Lists, where you can discuss
your issues with other MySQL users.
For additional documentation on MySQL products, including translations of the documentation into other
languages, and downloadable versions in variety of formats, including HTML and PDF formats, see the MySQL
Documentation Library.
Licensing information.
This product may include third-party software, used under license. If you are using a
Commercial release of MySQL 5.0, see this document for licensing information, including licensing information
relating to third-party software that may be included in this Commercial release. If you are using a Community
release of MySQL 5.0, see this document for licensing information, including licensing information relating to thirdparty software that may be included in this Community release.
Document generated on: 2016-05-11 (revision: 47682)

Table of Contents
Preface and Legal Notices ......................................................................................................... xvii
1 General Information ................................................................................................................... 1
1.1 About This Manual .......................................................................................................... 2
1.2 Typographical and Syntax Conventions ........................................................................... 3
1.3 Overview of the MySQL Database Management System ................................................... 4
1.3.1 What is MySQL? .................................................................................................. 4
1.3.2 The Main Features of MySQL ............................................................................... 6
1.3.3 History of MySQL ................................................................................................. 9
1.4 What Is New in MySQL 5.0 ............................................................................................. 9
1.5 MySQL Development History ......................................................................................... 11
1.6 MySQL Information Sources .......................................................................................... 11
1.6.1 MySQL Mailing Lists ........................................................................................... 12
1.6.2 MySQL Community Support at the MySQL Forums .............................................. 14
1.6.3 MySQL Community Support on Internet Relay Chat (IRC) .................................... 14
1.6.4 MySQL Enterprise .............................................................................................. 14
1.7 How to Report Bugs or Problems .................................................................................. 15
1.8 MySQL Standards Compliance ...................................................................................... 19
1.8.1 MySQL Extensions to Standard SQL ................................................................... 20
1.8.2 MySQL Differences from Standard SQL .............................................................. 23
1.8.3 How MySQL Deals with Constraints .................................................................... 27
1.9 Credits .......................................................................................................................... 31
1.9.1 Contributors to MySQL ....................................................................................... 31
1.9.2 Documenters and translators .............................................................................. 35
1.9.3 Packages that support MySQL ............................................................................ 36
1.9.4 Tools that were used to create MySQL ............................................................... 37
1.9.5 Supporters of MySQL ......................................................................................... 37
2 Installing and Upgrading MySQL .............................................................................................. 39
2.1 MySQL Installation Overview ......................................................................................... 40
2.2 Determining Your Current MySQL Version ..................................................................... 40
2.3 Notes for MySQL Enterprise Server ............................................................................... 41
2.3.1 Enterprise Server Distribution Types ................................................................... 42
2.3.2 Upgrading MySQL Enterprise Server ................................................................... 42
2.4 Notes for MySQL Community Server ............................................................................. 42
2.4.1 Overview of MySQL Community Server Installation .............................................. 42
2.4.2 Choosing Which MySQL Distribution to Install ..................................................... 43
2.5 How to Get MySQL ....................................................................................................... 46
2.6 Verifying Package Integrity Using MD5 Checksums or GnuPG ........................................ 47
2.6.1 Verifying the MD5 Checksum .............................................................................. 47
2.6.2 Signature Checking Using GnuPG ...................................................................... 47
2.6.3 Signature Checking Using Gpg4win for Windows ................................................. 50
2.6.4 Signature Checking Using RPM .......................................................................... 55
2.7 Installation Layouts ....................................................................................................... 56
2.8 Compiler-Specific Build Characteristics .......................................................................... 57
2.9 Standard MySQL Installation from a Binary Distribution ................................................... 58
2.10 Installing MySQL on Microsoft Windows ....................................................................... 58
2.10.1 Choosing An Installation Package ..................................................................... 59
2.10.2 Installing MySQL on Microsoft Windows Using an MSI Package .......................... 60
2.10.3 MySQL Server Instance Configuration Wizard .................................................... 65
2.10.4 Installing MySQL on Microsoft Windows Using a noinstall Zip Archive .................. 77
2.10.5 Troubleshooting a MySQL Installation Under Windows ....................................... 84
2.10.6 Windows Postinstallation Procedures ................................................................ 86
2.10.7 Upgrading MySQL on Windows ........................................................................ 88
2.10.8 Installing MySQL from Source on Windows ....................................................... 89
2.11 Installing MySQL on OS X ........................................................................................... 94
2.12 Installing MySQL on Linux Using RPM Packages ......................................................... 96
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

2.13
2.14
2.15
2.16
2.17

Installing MySQL on Solaris .......................................................................................
Installing MySQL on i5/OS .........................................................................................
Installing MySQL on NetWare ....................................................................................
Installing MySQL on Unix/Linux Using Generic Binaries ...............................................
Installing MySQL from Source ....................................................................................
2.17.1 Installing MySQL Using a Standard Source Distribution ....................................
2.17.2 Installing MySQL Using a Development Source Tree ........................................
2.17.3 MySQL Source-Configuration Options ..............................................................
2.17.4 Dealing with Problems Compiling MySQL ........................................................
2.17.5 Compiling and Linking an Optimized mysqld Server ..........................................
2.18 Postinstallation Setup and Testing .............................................................................
2.18.1 Initializing the Data Directory ...........................................................................
2.18.2 Starting the Server .........................................................................................
2.18.3 Testing the Server ..........................................................................................
2.18.4 Securing the Initial MySQL Accounts ...............................................................
2.18.5 Starting and Stopping MySQL Automatically ....................................................
2.19 Upgrading or Downgrading MySQL ............................................................................
2.19.1 Upgrading MySQL ..........................................................................................
2.19.2 Downgrading MySQL ......................................................................................
2.19.3 Checking Whether Tables or Indexes Must Be Rebuilt ......................................
2.19.4 Rebuilding or Repairing Tables or Indexes .......................................................
2.19.5 Copying MySQL Databases to Another Machine ..............................................
2.20 Operating System-Specific Notes ...............................................................................
2.20.1 Linux Notes ....................................................................................................
2.20.2 OS X Notes ...................................................................................................
2.20.3 Solaris Notes ..................................................................................................
2.20.4 BSD Notes .....................................................................................................
2.20.5 Other Unix Notes ............................................................................................
2.20.6 OS/2 Notes ....................................................................................................
2.21 Environment Variables ...............................................................................................
2.22 Perl Installation Notes ................................................................................................
2.22.1 Installing Perl on Unix .....................................................................................
2.22.2 Installing ActiveState Perl on Windows ............................................................
2.22.3 Problems Using the Perl DBI/DBD Interface .....................................................
3 Tutorial ..................................................................................................................................
3.1 Connecting to and Disconnecting from the Server .........................................................
3.2 Entering Queries .........................................................................................................
3.3 Creating and Using a Database ...................................................................................
3.3.1 Creating and Selecting a Database ...................................................................
3.3.2 Creating a Table ..............................................................................................
3.3.3 Loading Data into a Table ................................................................................
3.3.4 Retrieving Information from a Table ...................................................................
3.4 Getting Information About Databases and Tables .........................................................
3.5 Using mysql in Batch Mode .........................................................................................
3.6 Examples of Common Queries ....................................................................................
3.6.1 The Maximum Value for a Column ....................................................................
3.6.2 The Row Holding the Maximum of a Certain Column ..........................................
3.6.3 Maximum of Column per Group ........................................................................
3.6.4 The Rows Holding the Group-wise Maximum of a Certain Column .......................
3.6.5 Using User-Defined Variables ...........................................................................
3.6.6 Using Foreign Keys ..........................................................................................
3.6.7 Searching on Two Keys ....................................................................................
3.6.8 Calculating Visits Per Day .................................................................................
3.6.9 Using AUTO_INCREMENT ...............................................................................
3.7 Using MySQL with Apache ..........................................................................................
4 MySQL Programs ..................................................................................................................
4.1 Overview of MySQL Programs .....................................................................................
4.2 Using MySQL Programs ..............................................................................................
This
documentation
is for an
older version.
If you're

100
100
104
106
108
109
112
115
123
125
126
127
130
134
136
140
141
141
153
157
159
160
161
161
168
168
172
175
191
191
192
193
194
194
197
197
198
201
202
203
204
206
219
220
221
222
222
222
223
223
224
225
226
226
228
229
230
235

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

4.3

4.4

4.5

4.6

4.7

4.8
This
documentation
is for an
older version.
If you're

4.2.1 Invoking MySQL Programs ...............................................................................
4.2.2 Connecting to the MySQL Server ......................................................................
4.2.3 Specifying Program Options ..............................................................................
4.2.4 Using Options on the Command Line ................................................................
4.2.5 Program Option Modifiers .................................................................................
4.2.6 Using Option Files ............................................................................................
4.2.7 Command-Line Options that Affect Option-File Handling .....................................
4.2.8 Using Options to Set Program Variables ............................................................
4.2.9 Option Defaults, Options Expecting Values, and the = Sign .................................
4.2.10 Setting Environment Variables .........................................................................
MySQL Server and Server-Startup Programs ...............................................................
4.3.1 mysqld — The MySQL Server .........................................................................
4.3.2 mysqld_safe — MySQL Server Startup Script .................................................
4.3.3 mysql.server — MySQL Server Startup Script ...............................................
4.3.4 mysqld_multi — Manage Multiple MySQL Servers .........................................
MySQL Installation-Related Programs ..........................................................................
4.4.1 comp_err — Compile MySQL Error Message File ............................................
4.4.2 make_win_bin_dist — Package MySQL Distribution as Zip Archive ................
4.4.3 make_win_src_distribution — Create Source Distribution for Windows ......
4.4.4 mysqlbug — Generate Bug Report ..................................................................
4.4.5 mysql_fix_privilege_tables — Upgrade MySQL System Tables ...............
4.4.6 mysql_install_db — Initialize MySQL Data Directory ....................................
4.4.7 mysql_secure_installation — Improve MySQL Installation Security ...........
4.4.8 mysql_tzinfo_to_sql — Load the Time Zone Tables ...................................
4.4.9 mysql_upgrade — Check Tables for MySQL Upgrade .....................................
MySQL Client Programs ..............................................................................................
4.5.1 mysql — The MySQL Command-Line Tool .......................................................
4.5.2 mysqladmin — Client for Administering a MySQL Server ..................................
4.5.3 mysqlcheck — A Table Maintenance Program .................................................
4.5.4 mysqldump — A Database Backup Program .....................................................
4.5.5 mysqlimport — A Data Import Program .........................................................
4.5.6 mysqlshow — Display Database, Table, and Column Information ......................
MySQL Administrative and Utility Programs ..................................................................
4.6.1 innochecksum — Offline InnoDB File Checksum Utility ....................................
4.6.2 myisam_ftdump — Display Full-Text Index information .....................................
4.6.3 myisamchk — MyISAM Table-Maintenance Utility .............................................
4.6.4 myisamlog — Display MyISAM Log File Contents ............................................
4.6.5 myisampack — Generate Compressed, Read-Only MyISAM Tables ..................
4.6.6 mysqlaccess — Client for Checking Access Privileges .....................................
4.6.7 mysqlbinlog — Utility for Processing Binary Log Files .....................................
4.6.8 mysqldumpslow — Summarize Slow Query Log Files ......................................
4.6.9 mysqlhotcopy — A Database Backup Program ...............................................
4.6.10 mysqlmanager — The MySQL Instance Manager ...........................................
4.6.11 mysql_convert_table_format — Convert Tables to Use a Given Storage
Engine ......................................................................................................................
4.6.12 mysql_explain_log — Use EXPLAIN on Statements in Query Log ...............
4.6.13 mysql_find_rows — Extract SQL Statements from Files ...............................
4.6.14 mysql_fix_extensions — Normalize Table File Name Extensions ...............
4.6.15 mysql_setpermission — Interactively Set Permissions in Grant Tables ........
4.6.16 mysql_tableinfo — Generate Database Metadata ......................................
4.6.17 mysql_waitpid — Kill Process and Wait for Its Termination ...........................
4.6.18 mysql_zap — Kill Processes That Match a Pattern .........................................
MySQL Program Development Utilities .........................................................................
4.7.1 msql2mysql — Convert mSQL Programs for Use with MySQL ..........................
4.7.2 mysql_config — Display Options for Compiling Clients ...................................
4.7.3 my_print_defaults — Display Options from Option Files ..............................
4.7.4 resolve_stack_dump — Resolve Numeric Stack Trace Dump to Symbols .......
Miscellaneous Programs ..............................................................................................

235
236
239
240
241
242
246
247
248
251
252
252
252
256
258
263
263
264
265
265
266
267
268
269
269
273
273
293
299
305
321
325
329
329
329
331
347
348
354
356
365
366
369
379
380
381
382
382
383
385
385
386
386
386
387
388
389

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

4.8.1 perror — Explain Error Codes ........................................................................
4.8.2 replace — A String-Replacement Utility ..........................................................
4.8.3 resolveip — Resolve Host name to IP Address or Vice Versa .........................
5 MySQL Server Administration .................................................................................................
5.1 The MySQL Server .....................................................................................................
5.1.1 Server Option and Variable Reference ..............................................................
5.1.2 Server Configuration Defaults ...........................................................................
5.1.3 Server Command Options .................................................................................
5.1.4 Server System Variables ..................................................................................
5.1.5 Using System Variables ....................................................................................
5.1.6 Server Status Variables ....................................................................................
5.1.7 Server SQL Modes ...........................................................................................
5.1.8 Server-Side Help ..............................................................................................
5.1.9 Server Response to Signals ..............................................................................
5.1.10 The Server Shutdown Process ........................................................................
5.2 The MySQL Data Directory ..........................................................................................
5.3 The mysql System Database .......................................................................................
5.4 MySQL Server Logs ....................................................................................................
5.4.1 The Error Log ..................................................................................................
5.4.2 The General Query Log ....................................................................................
5.4.3 The Binary Log ................................................................................................
5.4.4 The Slow Query Log ........................................................................................
5.4.5 Server Log Maintenance ...................................................................................
5.5 Running Multiple MySQL Instances on One Machine ....................................................
5.5.1 Setting Up Multiple Data Directories ..................................................................
5.5.2 Running Multiple MySQL Instances on Windows ................................................
5.5.3 Running Multiple MySQL Instances on Unix .......................................................
5.5.4 Using Client Programs in a Multiple-Server Environment ....................................
6 Security .................................................................................................................................
6.1 General Security Issues ..............................................................................................
6.1.1 Security Guidelines ...........................................................................................
6.1.2 Keeping Passwords Secure ..............................................................................
6.1.3 Making MySQL Secure Against Attackers ..........................................................
6.1.4 Security-Related mysqld Options and Variables .................................................
6.1.5 How to Run MySQL as a Normal User ..............................................................
6.1.6 Security Issues with LOAD DATA LOCAL ..........................................................
6.1.7 Client Programming Security Guidelines ............................................................
6.2 The MySQL Access Privilege System ..........................................................................
6.2.1 Privileges Provided by MySQL ..........................................................................
6.2.2 Grant Tables ....................................................................................................
6.2.3 Specifying Account Names ...............................................................................
6.2.4 Access Control, Stage 1: Connection Verification ...............................................
6.2.5 Access Control, Stage 2: Request Verification ...................................................
6.2.6 When Privilege Changes Take Effect ................................................................
6.2.7 Troubleshooting Problems Connecting to MySQL ...............................................
6.3 MySQL User Account Management .............................................................................
6.3.1 User Names and Passwords .............................................................................
6.3.2 Adding User Accounts ......................................................................................
6.3.3 Removing User Accounts ..................................................................................
6.3.4 Setting Account Resource Limits .......................................................................
6.3.5 Assigning Account Passwords ...........................................................................
6.3.6 Using Secure Connections ................................................................................
6.3.7 Creating SSL Certificates and Keys Using openssl .............................................
6.3.8 Connecting to MySQL Remotely from Windows with SSH ...................................
6.3.9 SQL-Based MySQL Account Activity Auditing ....................................................
7 Backup and Recovery ............................................................................................................
7.1 Backup and Recovery Types .......................................................................................
7.2 Database Backup Methods ..........................................................................................
This
documentation
is for an
older version.
If you're

389
390
390
393
393
394
413
414
439
523
532
551
558
558
559
560
561
562
562
563
564
567
568
569
571
572
575
576
577
577
578
579
587
588
589
590
591
592
593
597
601
603
606
608
608
613
613
615
618
618
620
621
629
634
634
637
638
640

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

7.3 Example Backup and Recovery Strategy ......................................................................
7.3.1 Establishing a Backup Policy ............................................................................
7.3.2 Using Backups for Recovery .............................................................................
7.3.3 Backup Strategy Summary ................................................................................
7.4 Using mysqldump for Backups .....................................................................................
7.4.1 Dumping Data in SQL Format with mysqldump ..................................................
7.4.2 Reloading SQL-Format Backups .......................................................................
7.4.3 Dumping Data in Delimited-Text Format with mysqldump ....................................
7.4.4 Reloading Delimited-Text Format Backups .........................................................
7.4.5 mysqldump Tips ...............................................................................................
7.5 Point-in-Time (Incremental) Recovery Using the Binary Log ...........................................
7.5.1 Point-in-Time Recovery Using Event Times .......................................................
7.5.2 Point-in-Time Recovery Using Event Positions ...................................................
7.6 MyISAM Table Maintenance and Crash Recovery ........................................................
7.6.1 Using myisamchk for Crash Recovery ...............................................................
7.6.2 How to Check MyISAM Tables for Errors ...........................................................
7.6.3 How to Repair MyISAM Tables .........................................................................
7.6.4 MyISAM Table Optimization ..............................................................................
7.6.5 Setting Up a MyISAM Table Maintenance Schedule ...........................................
8 Optimization ...........................................................................................................................
8.1 Optimization Overview .................................................................................................
8.2 Optimizing SQL Statements .........................................................................................
8.2.1 Optimizing SELECT Statements ........................................................................
8.2.2 Optimizing DML Statements ..............................................................................
8.2.3 Optimizing Database Privileges .........................................................................
8.2.4 Other Optimization Tips ....................................................................................
8.3 Optimization and Indexes ............................................................................................
8.3.1 How MySQL Uses Indexes ...............................................................................
8.3.2 Using Primary Keys ..........................................................................................
8.3.3 Using Foreign Keys ..........................................................................................
8.3.4 Column Indexes ...............................................................................................
8.3.5 Multiple-Column Indexes ...................................................................................
8.3.6 Verifying Index Usage ......................................................................................
8.3.7 MyISAM Index Statistics Collection ....................................................................
8.3.8 Comparison of B-Tree and Hash Indexes ..........................................................
8.4 Optimizing Database Structure .....................................................................................
8.4.1 Optimizing Data Size ........................................................................................
8.4.2 Optimizing MySQL Data Types .........................................................................
8.4.3 Optimizing for Many Tables ..............................................................................
8.4.4 Internal Temporary Table Use in MySQL ...........................................................
8.5 Optimizing for MyISAM Tables .....................................................................................
8.5.1 Optimizing MyISAM Queries .............................................................................
8.5.2 Bulk Data Loading for MyISAM Tables ..............................................................
8.5.3 Speed of REPAIR TABLE Statements ...............................................................
8.6 Optimizing for InnoDB Tables ......................................................................................
8.6.1 Optimizing Storage Layout for InnoDB Tables ....................................................
8.6.2 Optimizing InnoDB Transaction Management .....................................................
8.6.3 Optimizing InnoDB Redo Logging ......................................................................
8.6.4 Bulk Data Loading for InnoDB Tables ................................................................
8.6.5 Optimizing InnoDB Queries ...............................................................................
8.6.6 Optimizing InnoDB DDL Operations ..................................................................
8.6.7 Optimizing InnoDB Disk I/O ..............................................................................
8.6.8 Optimizing InnoDB for Systems with Many Tables ..............................................
8.7 Optimizing for MEMORY Tables ..................................................................................
8.8 Understanding the Query Execution Plan .....................................................................
8.8.1 Optimizing Queries with EXPLAIN .....................................................................
8.8.2 EXPLAIN Output Format ...................................................................................
8.8.3 EXPLAIN EXTENDED Output Format ................................................................
This
documentation
is for an
older version.
If you're

642
643
645
645
645
646
647
647
649
649
651
652
653
654
654
655
655
658
658
661
662
664
664
698
699
700
700
700
702
702
702
703
704
704
706
707
707
709
711
712
713
713
715
716
717
717
718
719
719
720
720
721
721
721
722
722
722
732

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

8.8.4 Estimating Query Performance ..........................................................................
8.9 Controlling the Query Optimizer ...................................................................................
8.9.1 Controlling Query Plan Evaluation .....................................................................
8.9.2 Index Hints .......................................................................................................
8.10 Buffering and Caching ...............................................................................................
8.10.1 The MyISAM Key Cache .................................................................................
8.10.2 The InnoDB Buffer Pool ..................................................................................
8.10.3 The MySQL Query Cache ...............................................................................
8.11 Optimizing Locking Operations ...................................................................................
8.11.1 Internal Locking Methods ................................................................................
8.11.2 Table Locking Issues ......................................................................................
8.11.3 Concurrent Inserts ..........................................................................................
8.11.4 External Locking .............................................................................................
8.12 Optimizing the MySQL Server ....................................................................................
8.12.1 System Factors and Startup Parameter Tuning ................................................
8.12.2 Tuning Server Parameters ..............................................................................
8.12.3 Optimizing Disk I/O .........................................................................................
8.12.4 Using Symbolic Links ......................................................................................
8.12.5 Optimizing Memory Use ..................................................................................
8.12.6 Optimizing Network Use ..................................................................................
8.13 Measuring Performance (Benchmarking) ....................................................................
8.13.1 Measuring the Speed of Expressions and Functions .........................................
8.13.2 The MySQL Benchmark Suite .........................................................................
8.13.3 Using Your Own Benchmarks .........................................................................
8.14 Examining Thread Information ...................................................................................
8.14.1 Thread Command Values ...............................................................................
8.14.2 General Thread States ....................................................................................
8.14.3 Delayed-Insert Thread States ..........................................................................
8.14.4 Query Cache Thread States ............................................................................
8.14.5 Replication Master Thread States ....................................................................
8.14.6 Replication Slave I/O Thread States ................................................................
8.14.7 Replication Slave SQL Thread States ..............................................................
8.14.8 Replication Slave Connection Thread States ....................................................
8.14.9 MySQL Cluster Thread States .........................................................................
9 Language Structure ................................................................................................................
9.1 Literal Values ..............................................................................................................
9.1.1 String Literals ...................................................................................................
9.1.2 Number Literals ................................................................................................
9.1.3 Date and Time Literals .....................................................................................
9.1.4 Hexadecimal Literals ........................................................................................
9.1.5 Boolean Literals ...............................................................................................
9.1.6 Bit-Field Literals ...............................................................................................
9.1.7 NULL Values ....................................................................................................
9.2 Schema Object Names ................................................................................................
9.2.1 Identifier Qualifiers ............................................................................................
9.2.2 Identifier Case Sensitivity ..................................................................................
9.2.3 Function Name Parsing and Resolution .............................................................
9.3 Keywords and Reserved Words ...................................................................................
9.4 User-Defined Variables ................................................................................................
9.5 Expression Syntax ......................................................................................................
9.6 Comment Syntax .........................................................................................................
10 Globalization ........................................................................................................................
10.1 Character Set Support ...............................................................................................
10.1.1 Character Sets and Collations in General ........................................................
10.1.2 Character Sets and Collations in MySQL .........................................................
10.1.3 Specifying Character Sets and Collations .........................................................
10.1.4 Connection Character Sets and Collations .......................................................
10.1.5 Configuring the Character Set and Collation for Applications .............................
This
documentation
is for an
older version.
If you're

734
734
734
735
736
736
740
741
747
747
749
750
751
752
752
753
754
755
758
761
763
764
764
765
765
766
768
773
774
775
775
776
776
777
779
779
779
782
782
784
784
785
785
785
787
788
790
792
798
801
803
805
805
806
807
808
815
817

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

10.1.6 Character Set for Error Messages ...................................................................
10.1.7 Collation Issues ..............................................................................................
10.1.8 String Repertoire ............................................................................................
10.1.9 Operations Affected by Character Set Support .................................................
10.1.10 Unicode Support ...........................................................................................
10.1.11 UTF-8 for Metadata ......................................................................................
10.1.12 Column Character Set Conversion .................................................................
10.1.13 Character Sets and Collations That MySQL Supports .....................................
10.2 Setting the Error Message Language .........................................................................
10.3 Adding a Character Set .............................................................................................
10.3.1 Character Definition Arrays .............................................................................
10.3.2 String Collating Support for Complex Character Sets ........................................
10.3.3 Multi-Byte Character Support for Complex Character Sets ................................
10.4 Adding a Collation to a Character Set ........................................................................
10.4.1 Collation Implementation Types .......................................................................
10.4.2 Choosing a Collation ID ..................................................................................
10.4.3 Adding a Simple Collation to an 8-Bit Character Set .........................................
10.4.4 Adding a UCA Collation to a Unicode Character Set .........................................
10.5 Character Set Configuration .......................................................................................
10.6 MySQL Server Time Zone Support ............................................................................
10.6.1 Staying Current with Time Zone Changes ........................................................
10.6.2 Time Zone Leap Second Support ....................................................................
10.7 MySQL Server Locale Support ...................................................................................
11 Data Types ..........................................................................................................................
11.1 Data Type Overview ..................................................................................................
11.1.1 Numeric Type Overview ..................................................................................
11.1.2 Date and Time Type Overview ........................................................................
11.1.3 String Type Overview .....................................................................................
11.2 Numeric Types ..........................................................................................................
11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT,
MEDIUMINT, BIGINT ................................................................................................
11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC ..................................
11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE ..........................
11.2.4 Bit-Value Type - BIT .......................................................................................
11.2.5 Numeric Type Attributes ..................................................................................
11.2.6 Out-of-Range and Overflow Handling ..............................................................
11.3 Date and Time Types ................................................................................................
11.3.1 The DATE, DATETIME, and TIMESTAMP Types .............................................
11.3.2 The TIME Type ..............................................................................................
11.3.3 The YEAR Type .............................................................................................
11.3.4 YEAR(2) Limitations and Migrating to YEAR(4) ................................................
11.3.5 Automatic Initialization and Updating for TIMESTAMP ......................................
11.3.6 Fractional Seconds in Time Values .................................................................
11.3.7 Conversion Between Date and Time Types .....................................................
11.3.8 Two-Digit Years in Dates ................................................................................
11.4 String Types .............................................................................................................
11.4.1 The CHAR and VARCHAR Types ...................................................................
11.4.2 The BINARY and VARBINARY Types .............................................................
11.4.3 The BLOB and TEXT Types ...........................................................................
11.4.4 The ENUM Type ............................................................................................
11.4.5 The SET Type ................................................................................................
11.5 Extensions for Spatial Data ........................................................................................
11.5.1 Spatial Data Types .........................................................................................
11.5.2 The OpenGIS Geometry Model .......................................................................
11.5.3 Using Spatial Data ..........................................................................................
11.6 Data Type Default Values ..........................................................................................
11.7 Data Type Storage Requirements ..............................................................................
11.8 Choosing the Right Type for a Column .......................................................................
This
documentation
is for an
older version.
If you're

819
819
826
828
831
832
833
834
845
845
847
848
848
849
850
851
852
853
856
857
859
861
862
865
866
866
869
871
874
875
875
876
876
876
877
879
880
881
882
882
884
887
887
888
888
888
890
892
893
895
897
899
900
905
912
913
917

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

11.9 Using Data Types from Other Database Engines ........................................................ 917
12 Functions and Operators ...................................................................................................... 919
12.1 Function and Operator Reference .............................................................................. 920
12.2 Type Conversion in Expression Evaluation ................................................................. 929
12.3 Operators .................................................................................................................. 930
12.3.1 Operator Precedence ...................................................................................... 931
12.3.2 Comparison Functions and Operators .............................................................. 932
12.3.3 Logical Operators ........................................................................................... 938
12.3.4 Assignment Operators .................................................................................... 940
12.4 Control Flow Functions .............................................................................................. 941
12.5 String Functions ........................................................................................................ 943
12.5.1 String Comparison Functions .......................................................................... 955
12.5.2 Regular Expressions ....................................................................................... 958
12.6 Numeric Functions and Operators .............................................................................. 964
12.6.1 Arithmetic Operators ....................................................................................... 965
12.6.2 Mathematical Functions .................................................................................. 967
12.7 Date and Time Functions .......................................................................................... 975
12.8 What Calendar Is Used By MySQL? .......................................................................... 995
12.9 Full-Text Search Functions ........................................................................................ 996
12.9.1 Natural Language Full-Text Searches .............................................................. 996
12.9.2 Boolean Full-Text Searches ............................................................................ 999
12.9.3 Full-Text Searches with Query Expansion ...................................................... 1002
12.9.4 Full-Text Stopwords ...................................................................................... 1002
12.9.5 Full-Text Restrictions .................................................................................... 1005
12.9.6 Fine-Tuning MySQL Full-Text Search ............................................................ 1006
12.9.7 Adding a Collation for Full-Text Indexing ........................................................ 1008
12.10 Cast Functions and Operators ................................................................................ 1009
12.11 Bit Functions and Operators ................................................................................... 1013
12.12 Encryption and Compression Functions .................................................................. 1014
12.13 Information Functions ............................................................................................. 1020
12.14 Spatial Analysis Functions ..................................................................................... 1028
12.14.1 Spatial Function Reference ......................................................................... 1028
12.14.2 Argument Handling by Spatial Functions ...................................................... 1030
12.14.3 Functions That Create Geometry Values from WKT Values ........................... 1030
12.14.4 Functions That Create Geometry Values from WKB Values ........................... 1031
12.14.5 MySQL-Specific Functions That Create Geometry Values ............................. 1031
12.14.6 Geometry Format Conversion Functions ...................................................... 1032
12.14.7 Geometry Property Functions ...................................................................... 1033
12.14.8 Spatial Operator Functions .......................................................................... 1038
12.14.9 Functions That Test Spatial Relations Between Geometry Objects ................. 1038
12.15 Miscellaneous Functions ........................................................................................ 1040
12.16 GROUP BY (Aggregate) Functions ......................................................................... 1045
12.16.1 GROUP BY (Aggregate) Function Descriptions ............................................. 1045
12.16.2 GROUP BY Modifiers .................................................................................. 1049
12.16.3 MySQL Handling of GROUP BY .................................................................. 1052
12.17 Precision Math ...................................................................................................... 1053
12.17.1 Types of Numeric Values ............................................................................ 1054
12.17.2 DECIMAL Data Type Characteristics ............................................................ 1054
12.17.3 Expression Handling ................................................................................... 1056
12.17.4 Rounding Behavior ..................................................................................... 1057
12.17.5 Precision Math Examples ............................................................................ 1058
13 SQL Statement Syntax ....................................................................................................... 1063
13.1 Data Definition Statements ....................................................................................... 1064
13.1.1 ALTER DATABASE Syntax ........................................................................... 1064
13.1.2 ALTER FUNCTION Syntax ........................................................................... 1064
13.1.3 ALTER PROCEDURE Syntax ....................................................................... 1065
13.1.4 ALTER TABLE Syntax .................................................................................. 1065
13.1.5 ALTER VIEW Syntax .................................................................................... 1073
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

13.2

13.3

13.4

13.5

13.6

13.7

This
documentation
is for an
older version.
If you're

13.1.6 CREATE DATABASE Syntax ........................................................................
13.1.7 CREATE FUNCTION Syntax .........................................................................
13.1.8 CREATE INDEX Syntax ................................................................................
13.1.9 CREATE PROCEDURE and CREATE FUNCTION Syntax ..............................
13.1.10 CREATE TABLE Syntax .............................................................................
13.1.11 CREATE TRIGGER Syntax .........................................................................
13.1.12 CREATE VIEW Syntax ................................................................................
13.1.13 DROP DATABASE Syntax ..........................................................................
13.1.14 DROP FUNCTION Syntax ...........................................................................
13.1.15 DROP INDEX Syntax ..................................................................................
13.1.16 DROP PROCEDURE and DROP FUNCTION Syntax ....................................
13.1.17 DROP TABLE Syntax .................................................................................
13.1.18 DROP TRIGGER Syntax .............................................................................
13.1.19 DROP VIEW Syntax ...................................................................................
13.1.20 RENAME TABLE Syntax .............................................................................
13.1.21 TRUNCATE TABLE Syntax .........................................................................
Data Manipulation Statements ..................................................................................
13.2.1 CALL Syntax ................................................................................................
13.2.2 DELETE Syntax ............................................................................................
13.2.3 DO Syntax ...................................................................................................
13.2.4 HANDLER Syntax .........................................................................................
13.2.5 INSERT Syntax ............................................................................................
13.2.6 LOAD DATA INFILE Syntax ..........................................................................
13.2.7 REPLACE Syntax .........................................................................................
13.2.8 SELECT Syntax ............................................................................................
13.2.9 Subquery Syntax ..........................................................................................
13.2.10 UPDATE Syntax .........................................................................................
MySQL Transactional and Locking Statements .........................................................
13.3.1 START TRANSACTION, COMMIT, and ROLLBACK Syntax ...........................
13.3.2 Statements That Cannot Be Rolled Back .......................................................
13.3.3 Statements That Cause an Implicit Commit ....................................................
13.3.4 SAVEPOINT, ROLLBACK TO SAVEPOINT, and RELEASE SAVEPOINT, and
Syntax ....................................................................................................................
13.3.5 LOCK TABLES and UNLOCK TABLES Syntax ..............................................
13.3.6 SET TRANSACTION Syntax .........................................................................
13.3.7 XA Transactions ...........................................................................................
Replication Statements ............................................................................................
13.4.1 SQL Statements for Controlling Master Servers ..............................................
13.4.2 SQL Statements for Controlling Slave Servers ...............................................
SQL Syntax for Prepared Statements .......................................................................
13.5.1 PREPARE Syntax .........................................................................................
13.5.2 EXECUTE Syntax .........................................................................................
13.5.3 DEALLOCATE PREPARE Syntax ..................................................................
MySQL Compound-Statement Syntax .......................................................................
13.6.1 BEGIN ... END Compound-Statement Syntax .................................................
13.6.2 Statement Label Syntax ................................................................................
13.6.3 DECLARE Syntax .........................................................................................
13.6.4 Variables in Stored Programs ........................................................................
13.6.5 Flow Control Statements ...............................................................................
13.6.6 Cursors ........................................................................................................
13.6.7 Condition Handling ........................................................................................
Database Administration Statements ........................................................................
13.7.1 Account Management Statements .................................................................
13.7.2 Table Maintenance Statements .....................................................................
13.7.3 User-Defined Function Statements ................................................................
13.7.4 SET Syntax ..................................................................................................
13.7.5 SHOW Syntax ..............................................................................................
13.7.6 Other Administrative Statements ....................................................................

1073
1074
1074
1076
1082
1100
1103
1107
1108
1108
1108
1109
1109
1110
1110
1111
1112
1112
1114
1117
1118
1119
1126
1136
1137
1153
1164
1166
1166
1169
1169
1170
1170
1175
1177
1181
1181
1183
1189
1192
1193
1193
1193
1193
1194
1194
1195
1196
1201
1202
1206
1206
1221
1228
1229
1233
1266

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

13.8 MySQL Utility Statements ........................................................................................
13.8.1 DESCRIBE Syntax ........................................................................................
13.8.2 EXPLAIN Syntax ..........................................................................................
13.8.3 HELP Syntax ................................................................................................
13.8.4 USE Syntax ..................................................................................................
14 Storage Engines .................................................................................................................
14.1 The MyISAM Storage Engine ...................................................................................
14.1.1 MyISAM Startup Options ...............................................................................
14.1.2 Space Needed for Keys ................................................................................
14.1.3 MyISAM Table Storage Formats ....................................................................
14.1.4 MyISAM Table Problems ...............................................................................
14.2 The InnoDB Storage Engine ....................................................................................
14.2.1 Configuring InnoDB .......................................................................................
14.2.2 InnoDB Startup Options and System Variables ...............................................
14.2.3 Creating and Using InnoDB Tables ................................................................
14.2.4 Changing the Number or Size of InnoDB Redo Log Files ................................
14.2.5 Resizing the InnoDB System Tablespace .......................................................
14.2.6 Backing Up and Recovering an InnoDB Database ..........................................
14.2.7 Moving an InnoDB Database to Another Machine ...........................................
14.2.8 InnoDB Transaction Model and Locking .........................................................
14.2.9 InnoDB Multi-Versioning ................................................................................
14.2.10 InnoDB Table and Index Structures .............................................................
14.2.11 InnoDB Disk I/O and File Space Management ..............................................
14.2.12 InnoDB Error Handling ................................................................................
14.2.13 InnoDB Troubleshooting ..............................................................................
14.2.14 Limits on InnoDB Tables .............................................................................
14.3 The MERGE Storage Engine ...................................................................................
14.3.1 MERGE Table Advantages and Disadvantages ..............................................
14.3.2 MERGE Table Problems ...............................................................................
14.4 The MEMORY (HEAP) Storage Engine ....................................................................
14.5 The BDB (BerkeleyDB) Storage Engine ....................................................................
14.5.1 Operating Systems Supported by BDB ..........................................................
14.5.2 Installing BDB ...............................................................................................
14.5.3 BDB Startup Options ....................................................................................
14.5.4 Characteristics of BDB Tables .......................................................................
14.5.5 Restrictions on BDB Tables ..........................................................................
14.5.6 Errors That May Occur When Using BDB Tables ............................................
14.6 The EXAMPLE Storage Engine ................................................................................
14.7 The FEDERATED Storage Engine ...........................................................................
14.7.1 Description of the FEDERATED Storage Engine ............................................
14.7.2 How to Use FEDERATED Tables ..................................................................
14.7.3 Limitations of the FEDERATED Storage Engine .............................................
14.8 The ARCHIVE Storage Engine .................................................................................
14.9 The CSV Storage Engine ........................................................................................
14.10 The BLACKHOLE Storage Engine ..........................................................................
15 High Availability and Scalability ...........................................................................................
15.1 Using MySQL within an Amazon EC2 Instance .........................................................
15.1.1 Setting Up MySQL on an EC2 AMI ................................................................
15.1.2 EC2 Instance Limitations ...............................................................................
15.1.3 Deploying a MySQL Database Using EC2 .....................................................
15.2 Using ZFS Replication .............................................................................................
15.2.1 Using ZFS for File System Replication ...........................................................
15.2.2 Configuring MySQL for ZFS Replication .........................................................
15.2.3 Handling MySQL Recovery with ZFS .............................................................
15.3 Using MySQL with memcached ................................................................................
15.3.1 Installing memcached ....................................................................................
15.3.2 Using memcached ........................................................................................
15.3.3 Developing a memcached Application ............................................................
This
documentation
is for an
older version.
If you're

1271
1271
1271
1272
1275
1277
1280
1282
1284
1284
1286
1288
1289
1298
1320
1326
1327
1328
1331
1332
1344
1345
1348
1349
1350
1362
1365
1367
1368
1370
1372
1373
1373
1374
1375
1377
1377
1378
1378
1378
1379
1380
1381
1382
1383
1387
1389
1390
1391
1391
1394
1396
1396
1397
1397
1398
1400
1418

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

15.3.4 Getting memcached Statistics ........................................................................ 1443
15.3.5 memcached FAQ .......................................................................................... 1451
16 Replication ......................................................................................................................... 1455
16.1 Replication Configuration ......................................................................................... 1456
16.1.1 How to Set Up Replication ............................................................................ 1457
16.1.2 Replication and Binary Logging Options and Variables .................................... 1465
16.1.3 Common Replication Administration Tasks ..................................................... 1500
16.2 Replication Implementation ...................................................................................... 1503
16.2.1 Replication Implementation Details ................................................................ 1503
16.2.2 Replication Relay and Status Logs ................................................................ 1505
16.2.3 How Servers Evaluate Replication Filtering Rules ........................................... 1508
16.3 Replication Solutions ............................................................................................... 1513
16.3.1 Using Replication for Backups ....................................................................... 1514
16.3.2 Using Replication with Different Master and Slave Storage Engines ................. 1515
16.3.3 Using Replication for Scale-Out ..................................................................... 1517
16.3.4 Replicating Different Databases to Different Slaves ........................................ 1518
16.3.5 Improving Replication Performance ................................................................ 1519
16.3.6 Switching Masters During Failover ................................................................. 1520
16.3.7 Setting Up Replication to Use Secure Connections ......................................... 1522
16.4 Replication Notes and Tips ...................................................................................... 1523
16.4.1 Replication Features and Issues .................................................................... 1523
16.4.2 Replication Compatibility Between MySQL Versions ....................................... 1535
16.4.3 Upgrading a Replication Setup ...................................................................... 1536
16.4.4 Troubleshooting Replication .......................................................................... 1536
16.4.5 How to Report Replication Bugs or Problems ................................................. 1538
17 MySQL Cluster ................................................................................................................... 1539
17.1 MySQL Cluster Overview ......................................................................................... 1540
17.1.1 MySQL Cluster Core Concepts ...................................................................... 1541
17.1.2 MySQL Cluster Nodes, Node Groups, Replicas, and Partitions ........................ 1544
17.1.3 MySQL Cluster Hardware, Software, and Networking Requirements ................ 1546
17.1.4 What is New in MySQL Cluster ..................................................................... 1547
17.1.5 Known Limitations of MySQL Cluster ............................................................. 1548
17.2 MySQL Cluster Installation and Upgrades ................................................................. 1557
17.2.1 Installing MySQL Cluster on Linux ................................................................. 1559
17.2.2 Initial Configuration of MySQL Cluster ........................................................... 1564
17.2.3 Initial Startup of MySQL Cluster .................................................................... 1566
17.2.4 MySQL Cluster Example with Tables and Data .............................................. 1567
17.2.5 Safe Shutdown and Restart of MySQL Cluster ............................................... 1570
17.2.6 Upgrading and Downgrading MySQL Cluster ................................................. 1571
17.3 MySQL Cluster Configuration ................................................................................... 1573
17.3.1 Quick Test Setup of MySQL Cluster .............................................................. 1573
17.3.2 Overview of MySQL Cluster Configuration Parameters, Options, and Variables . 1575
17.3.3 MySQL Cluster Configuration Files ................................................................ 1595
17.3.4 Using High-Speed Interconnects with MySQL Cluster ..................................... 1645
17.4 MySQL Cluster Programs ........................................................................................ 1647
17.4.1 ndbd — The MySQL Cluster Data Node Daemon .......................................... 1648
17.4.2 ndb_mgmd — The MySQL Cluster Management Server Daemon ..................... 1652
17.4.3 ndb_mgm — The MySQL Cluster Management Client ..................................... 1654
17.4.4 ndb_config — Extract MySQL Cluster Configuration Information .................. 1656
17.4.5 ndb_cpcd — Automate Testing for NDB Development ................................... 1660
17.4.6 ndb_delete_all — Delete All Rows from an NDB Table ............................. 1660
17.4.7 ndb_desc — Describe NDB Tables .............................................................. 1661
17.4.8 ndb_drop_index — Drop Index from an NDB Table .................................... 1663
17.4.9 ndb_drop_table — Drop an NDB Table ..................................................... 1664
17.4.10 ndb_error_reporter — NDB Error-Reporting Utility ................................. 1664
17.4.11 ndb_print_backup_file — Print NDB Backup File Contents ................... 1665
17.4.12 ndb_print_schema_file — Print NDB Schema File Contents .................. 1665
17.4.13 ndb_print_sys_file — Print NDB System File Contents ......................... 1665
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

17.4.14 ndb_restore — Restore a MySQL Cluster Backup ....................................
17.4.15 ndb_select_all — Print Rows from an NDB Table ...................................
17.4.16 ndb_select_count — Print Row Counts for NDB Tables ...........................
17.4.17 ndb_show_tables — Display List of NDB Tables .......................................
17.4.18 ndb_size.pl — NDBCLUSTER Size Requirement Estimator ......................
17.4.19 ndb_waiter — Wait for MySQL Cluster to Reach a Given Status .................
17.4.20 Options Common to MySQL Cluster Programs — Options Common to MySQL
Cluster Programs ....................................................................................................
17.5 Management of MySQL Cluster ...............................................................................
17.5.1 Summary of MySQL Cluster Start Phases ......................................................
17.5.2 Commands in the MySQL Cluster Management Client ....................................
17.5.3 Online Backup of MySQL Cluster ..................................................................
17.5.4 MySQL Server Usage for MySQL Cluster ......................................................
17.5.5 Performing a Rolling Restart of a MySQL Cluster ...........................................
17.5.6 Event Reports Generated in MySQL Cluster ..................................................
17.5.7 MySQL Cluster Log Messages ......................................................................
17.5.8 MySQL Cluster Single User Mode .................................................................
17.5.9 Quick Reference: MySQL Cluster SQL Statements .........................................
17.5.10 MySQL Cluster Security Issues ...................................................................
18 Stored Programs and Views ...............................................................................................
18.1 Defining Stored Programs ........................................................................................
18.2 Using Stored Routines (Procedures and Functions) ...................................................
18.2.1 Stored Routine Syntax ..................................................................................
18.2.2 Stored Routines and MySQL Privileges .........................................................
18.2.3 Stored Routine Metadata ..............................................................................
18.2.4 Stored Procedures, Functions, Triggers, and LAST_INSERT_ID() ....................
18.3 Using Triggers .........................................................................................................
18.3.1 Trigger Syntax and Examples ........................................................................
18.3.2 Trigger Metadata ..........................................................................................
18.4 Using Views ............................................................................................................
18.4.1 View Syntax .................................................................................................
18.4.2 View Processing Algorithms ..........................................................................
18.4.3 Updatable and Insertable Views ....................................................................
18.4.4 The View WITH CHECK OPTION Clause ......................................................
18.4.5 View Metadata ..............................................................................................
18.5 Access Control for Stored Programs and Views ........................................................
18.6 Binary Logging of Stored Programs ..........................................................................
19 INFORMATION_SCHEMA Tables .......................................................................................
19.1 The INFORMATION_SCHEMA CHARACTER_SETS Table .......................................
19.2 The INFORMATION_SCHEMA COLLATIONS Table .................................................
19.3 The INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY
Table ..............................................................................................................................
19.4 The INFORMATION_SCHEMA COLUMNS Table .....................................................
19.5 The INFORMATION_SCHEMA COLUMN_PRIVILEGES Table ..................................
19.6 The INFORMATION_SCHEMA KEY_COLUMN_USAGE Table ..................................
19.7 The INFORMATION_SCHEMA PROFILING Table ....................................................
19.8 The INFORMATION_SCHEMA ROUTINES Table .....................................................
19.9 The INFORMATION_SCHEMA SCHEMATA Table ....................................................
19.10 The INFORMATION_SCHEMA SCHEMA_PRIVILEGES Table .................................
19.11 The INFORMATION_SCHEMA STATISTICS Table .................................................
19.12 The INFORMATION_SCHEMA TABLES Table .......................................................
19.13 The INFORMATION_SCHEMA TABLE_CONSTRAINTS Table ................................
19.14 The INFORMATION_SCHEMA TABLE_PRIVILEGES Table ....................................
19.15 The INFORMATION_SCHEMA TRIGGERS Table ...................................................
19.16 The INFORMATION_SCHEMA USER_PRIVILEGES Table .....................................
19.17 The INFORMATION_SCHEMA VIEWS Table .........................................................
19.18 Extensions to SHOW Statements ...........................................................................
20 Connectors and APIs .........................................................................................................
This
documentation
is for an
older version.
If you're

1666
1671
1674
1675
1676
1677
1679
1682
1683
1685
1685
1689
1690
1692
1700
1715
1716
1717
1725
1725
1726
1727
1728
1728
1729
1729
1730
1733
1733
1734
1734
1736
1737
1738
1738
1739
1749
1751
1751
1752
1752
1753
1754
1755
1756
1757
1757
1757
1758
1759
1760
1760
1762
1762
1763
1767

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

20.1
20.2
20.3
20.4
20.5
20.6

MySQL Connector/ODBC .........................................................................................
MySQL Connector/Net .............................................................................................
MySQL Connector/J ................................................................................................
MySQL Connector/C ................................................................................................
libmysqld, the Embedded MySQL Server Library .......................................................
MySQL C API .........................................................................................................
20.6.1 MySQL C API Implementations .....................................................................
20.6.2 Simultaneous MySQL Server and Connector/C Installations ............................
20.6.3 Example C API Client Programs ....................................................................
20.6.4 Building and Running C API Client Programs .................................................
20.6.5 C API Data Structures ..................................................................................
20.6.6 C API Function Overview ..............................................................................
20.6.7 C API Function Descriptions ..........................................................................
20.6.8 C API Prepared Statements ..........................................................................
20.6.9 C API Prepared Statement Data Structures ....................................................
20.6.10 C API Prepared Statement Function Overview .............................................
20.6.11 C API Prepared Statement Function Descriptions .........................................
20.6.12 C API Threaded Function Descriptions .........................................................
20.6.13 C API Embedded Server Function Descriptions ............................................
20.6.14 Common Questions and Problems When Using the C API ............................
20.6.15 Controlling Automatic Reconnection Behavior ...............................................
20.6.16 C API Support for Multiple Statement Execution ...........................................
20.6.17 C API Prepared Statement Problems ...........................................................
20.6.18 C API Prepared Statement Handling of Date and Time Values .......................
20.6.19 C API Support for Prepared CALL Statements ..............................................
20.7 MySQL PHP API .....................................................................................................
20.8 MySQL Perl API ......................................................................................................
20.9 MySQL Python API .................................................................................................
20.10 MySQL Ruby APIs ................................................................................................
20.10.1 The MySQL/Ruby API .................................................................................
20.10.2 The Ruby/MySQL API .................................................................................
20.11 MySQL Tcl API .....................................................................................................
20.12 MySQL Eiffel Wrapper ...........................................................................................
21 Extending MySQL ..............................................................................................................
21.1 MySQL Internals ......................................................................................................
21.1.1 MySQL Threads ...........................................................................................
21.1.2 The MySQL Test Suite .................................................................................
21.2 Adding New Functions to MySQL .............................................................................
21.2.1 Features of the User-Defined Function Interface .............................................
21.2.2 Adding a New User-Defined Function ............................................................
21.2.3 Adding a New Native Function ......................................................................
21.3 Debugging and Porting MySQL ................................................................................
21.3.1 Debugging a MySQL Server ..........................................................................
21.3.2 Debugging a MySQL Client ...........................................................................
21.3.3 The DBUG Package .....................................................................................
22 MySQL Enterprise Edition ...................................................................................................
22.1 MySQL Enterprise Monitor Overview ........................................................................
22.2 MySQL Enterprise Backup Overview ........................................................................
22.3 MySQL Enterprise Security Overview .......................................................................
22.4 MySQL Enterprise Encryption Overview ...................................................................
22.5 MySQL Enterprise Audit Overview ...........................................................................
22.6 MySQL Enterprise Firewall Overview ........................................................................
22.7 MySQL Enterprise Thread Pool Overview .................................................................
A MySQL 5.0 Frequently Asked Questions ...............................................................................
A.1 MySQL 5.0 FAQ: General .........................................................................................
A.2 MySQL 5.0 FAQ: Storage Engines ............................................................................
A.3 MySQL 5.0 FAQ: Server SQL Mode ..........................................................................
A.4 MySQL 5.0 FAQ: Stored Procedures and Functions ...................................................
This
documentation
is for an
older version.
If you're

1770
1770
1771
1771
1771
1772
1772
1773
1774
1774
1778
1783
1787
1836
1836
1842
1845
1867
1868
1869
1870
1871
1873
1874
1875
1875
1875
1876
1876
1876
1876
1876
1877
1879
1879
1879
1880
1880
1881
1881
1891
1893
1893
1900
1900
1903
1903
1904
1904
1905
1905
1905
1906
1907
1907
1908
1909
1910

This
documentation
is for an
older version.
If you're

MySQL 5.0 Reference Manual

A.5 MySQL 5.0 FAQ: Triggers .........................................................................................
A.6 MySQL 5.0 FAQ: Views ............................................................................................
A.7 MySQL 5.0 FAQ: INFORMATION_SCHEMA ..............................................................
A.8 MySQL 5.0 FAQ: Migration .......................................................................................
A.9 MySQL 5.0 FAQ: Security .........................................................................................
A.10 MySQL 5.0 FAQ: MySQL Cluster .............................................................................
A.11 MySQL 5.0 FAQ: MySQL Chinese, Japanese, and Korean Character Sets .................
A.12 MySQL 5.0 FAQ: Connectors & APIs .......................................................................
A.13 MySQL 5.0 FAQ: Replication ...................................................................................
B Errors, Error Codes, and Common Problems ........................................................................
B.1 Sources of Error Information ......................................................................................
B.2 Types of Error Values ...............................................................................................
B.3 Server Error Codes and Messages ............................................................................
B.4 Client Error Codes and Messages .............................................................................
B.5 Problems and Common Errors ..................................................................................
B.5.1 How to Determine What Is Causing a Problem ................................................
B.5.2 Common Errors When Using MySQL Programs ...............................................
B.5.3 Administration-Related Issues .........................................................................
B.5.4 Query-Related Issues .....................................................................................
B.5.5 Optimizer-Related Issues ................................................................................
B.5.6 Table Definition-Related Issues .......................................................................
B.5.7 Known Issues in MySQL ................................................................................
C Restrictions and Limits .........................................................................................................
C.1 Restrictions on Stored Programs ...............................................................................
C.2 Restrictions on Server-Side Cursors ..........................................................................
C.3 Restrictions on Subqueries ........................................................................................
C.4 Restrictions on Views ................................................................................................
C.5 Restrictions on XA Transactions ................................................................................
C.6 Restrictions on Character Sets ..................................................................................
C.7 Limits in MySQL .......................................................................................................
C.7.1 Limits on Joins ...............................................................................................
C.7.2 Limits on Number of Databases and Tables ....................................................
C.7.3 Limits on Table Size ......................................................................................
C.7.4 Limits on Table Column Count and Row Size ..................................................
C.7.5 Limits Imposed by .frm File Structure ..............................................................
C.7.6 Windows Platform Limitations .........................................................................
General Index .........................................................................................................................
C Function Index .....................................................................................................................
Command Index ......................................................................................................................
Function Index ........................................................................................................................
INFORMATION_SCHEMA Index ..............................................................................................
Join Types Index .....................................................................................................................
Operator Index ........................................................................................................................
Option Index ...........................................................................................................................
Privileges Index .......................................................................................................................
SQL Modes Index ...................................................................................................................
Statement/Syntax Index ...........................................................................................................
Status Variable Index ..............................................................................................................
System Variable Index ............................................................................................................
Transaction Isolation Level Index .............................................................................................

This
documentation
is for an
older version.
If you're

1913
1915
1916
1917
1917
1918
1929
1941
1942
1947
1947
1947
1948
1983
1987
1987
1988
2001
2009
2017
2017
2018
2023
2023
2025
2026
2028
2030
2030
2031
2031
2031
2031
2032
2034
2035
2039
2111
2119
2145
2161
2163
2165
2169
2215
2219
2221
2253
2259
2273

This
documentation
is for an
older version.
If you're

Preface and Legal Notices
This is the Reference Manual for the MySQL Database System, version 5.0, through release 5.0.96.
Differences between minor versions of MySQL 5.0 are noted in the present text with reference to
release numbers (5.0.x). For license information, see the Legal Notices.
This manual is not intended for use with older versions of the MySQL software due to the many
functional and other differences between MySQL 5.0 and previous versions. If you are using an earlier
release of the MySQL software, please refer to the appropriate manual. For example, MySQL 3.23, 4.0,
4.1 Reference Manual covers the 4.1 series of MySQL software releases.
If you are using MySQL 5.1, please refer to the MySQL 5.1 Reference Manual.
Licensing information.
This product may include third-party software, used under license. If you
are using a Commercial release of MySQL 5.0, see this document for licensing information, including
licensing information relating to third-party software that may be included in this Commercial release.
If you are using a Community release of MySQL 5.0, see this document for licensing information,
including licensing information relating to third-party software that may be included in this Community
release.

Legal Notices
Copyright © 1997, 2016, Oracle and/or its affiliates. All rights reserved.
This software and related documentation are provided under a license agreement containing
restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly
permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate,
broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any
form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless
required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be errorfree. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone
licensing it on behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, delivered to U.S.
Government end users are "commercial computer software" pursuant to the applicable Federal
Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication,
disclosure, modification, and adaptation of the programs, including any operating system, integrated
software, any programs installed on the hardware, and/or documentation, shall be subject to license
terms and license restrictions applicable to the programs. No other rights are granted to the U.S.
Government.
This software or hardware is developed for general use in a variety of information management
applications. It is not developed or intended for use in any inherently dangerous applications, including
applications that may create a risk of personal injury. If you use this software or hardware in dangerous
applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and
other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any
damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be
trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC
trademarks are used under license and are trademarks or registered trademarks of SPARC
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Legal Notices

International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or
registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content,
products, and services from third parties. Oracle Corporation and its affiliates are not responsible
for and expressly disclaim all warranties of any kind with respect to third-party content, products,
and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle
Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to
your access to or use of third-party content, products, or services, except as set forth in an applicable
agreement between you and Oracle.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program
website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers that have purchased support have access to electronic support through My Oracle
Support. For information, visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?
ctx=acc&id=trs if you are hearing impaired.
This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the
following terms:
You may create a printed copy of this documentation solely for your own personal use. Conversion
to other formats is allowed as long as the actual content is not altered or edited in any way. You shall
not publish or distribute this documentation in any form or on any media, except if you distribute the
documentation in a manner similar to how Oracle disseminates it (that is, electronically for download
on a Web site with the software) or on a CD-ROM or similar medium, provided however that the
documentation is disseminated together with the software on the same medium. Any other use, such
as any dissemination of printed copies or use of this documentation, in whole or in part, in another
publication, requires the prior written consent from an authorized representative of Oracle. Oracle and/
or its affiliates reserve any and all rights to this documentation not expressly granted above.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 1 General Information
Table of Contents
1.1 About This Manual .................................................................................................................. 2
1.2 Typographical and Syntax Conventions ................................................................................... 3
1.3 Overview of the MySQL Database Management System .......................................................... 4
1.3.1 What is MySQL? .......................................................................................................... 4
1.3.2 The Main Features of MySQL ....................................................................................... 6
1.3.3 History of MySQL ......................................................................................................... 9
1.4 What Is New in MySQL 5.0 ..................................................................................................... 9
1.5 MySQL Development History ................................................................................................. 11
1.6 MySQL Information Sources .................................................................................................. 11
1.6.1 MySQL Mailing Lists .................................................................................................. 12
1.6.2 MySQL Community Support at the MySQL Forums ...................................................... 14
1.6.3 MySQL Community Support on Internet Relay Chat (IRC) ............................................ 14
1.6.4 MySQL Enterprise ...................................................................................................... 14
1.7 How to Report Bugs or Problems .......................................................................................... 15
1.8 MySQL Standards Compliance .............................................................................................. 19
1.8.1 MySQL Extensions to Standard SQL ........................................................................... 20
1.8.2 MySQL Differences from Standard SQL ...................................................................... 23
1.8.3 How MySQL Deals with Constraints ............................................................................ 27
1.9 Credits .................................................................................................................................. 31
1.9.1 Contributors to MySQL ............................................................................................... 31
1.9.2 Documenters and translators ...................................................................................... 35
1.9.3 Packages that support MySQL .................................................................................... 36
1.9.4 Tools that were used to create MySQL ....................................................................... 37
1.9.5 Supporters of MySQL ................................................................................................. 37

End of Product Lifecycle. Active development for MySQL Database Server version 5.0 has ended.
Oracle offers various support offerings which may be of interest. For details and more information,
see the MySQL section of the Lifetime Support Policy for Oracle Technology Products (http://
www.oracle.com/us/support/lifetime-support/index.html). Please consider upgrading to a recent
version.
The MySQL™ 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. Oracle is a registered
trademark of Oracle Corporation and/or its affiliates. MySQL is a trademark of Oracle Corporation and/
or its affiliates, and shall not be used by Customer without Oracle's express written authorization. Other
names may be trademarks of their respective owners.
The MySQL software is Dual Licensed. Users can choose to use the MySQL software as an Open
Source product under the terms of the GNU General Public License (http://www.fsf.org/licenses/) or
can purchase a standard commercial license from Oracle. See http://www.mysql.com/company/legal/
licensing/ for more information on our licensing policies.
The following list describes some sections of particular interest in this manual:
• For a discussion of MySQL Database Server capabilities, see Section 1.3.2, “The Main Features of
MySQL”.
• For an overview of new MySQL features, see Section 1.4, “What Is New in MySQL 5.0”. For
information about the changes in each version, see the Release Notes.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

About This Manual

• For installation instructions, see Chapter 2, Installing and Upgrading MySQL. For information about
upgrading MySQL, see Section 2.19.1, “Upgrading MySQL”.
• For a tutorial introduction to the MySQL Database Server, see Chapter 3, Tutorial.
• For information about configuring and administering MySQL Server, see Chapter 5, MySQL Server
Administration.
• For information about security in MySQL, see Chapter 6, Security.
• For information about setting up replication servers, see Chapter 16, Replication.
• For information about MySQL Enterprise, the commercial MySQL release with advanced features
and management tools, see Chapter 22, MySQL Enterprise Edition.
• For answers to a number of questions that are often asked concerning the MySQL Database Server
and its capabilities, see Appendix A, MySQL 5.0 Frequently Asked Questions.
• For a history of new features and bugfixes, see the Release Notes.

Important
To report problems or bugs, please use the instructions at Section 1.7, “How
to Report Bugs or Problems”. If you find a sensitive security bug in MySQL
Server, please let us know immediately by sending an email message to
. Exception: Support customers should report
all problems, including security bugs, to Oracle Support.

1.1 About This Manual
This is the Reference Manual for the MySQL Database System, version 5.0, through release 5.0.96.
Differences between minor versions of MySQL 5.0 are noted in the present text with reference to
release numbers (5.0.x). For license information, see the Legal Notices.
This manual is not intended for use with older versions of the MySQL software due to the many
functional and other differences between MySQL 5.0 and previous versions. If you are using an earlier
release of the MySQL software, please refer to the appropriate manual. For example, MySQL 3.23, 4.0,
4.1 Reference Manual covers the 4.1 series of MySQL software releases.
If you are using MySQL 5.1, please refer to the MySQL 5.1 Reference Manual.
Because this manual serves as a reference, it does not provide general instruction on SQL or relational
database concepts. It also does not teach you how to use your operating system or command-line
interpreter.
The MySQL Database Software is under constant development, and the Reference Manual is updated
frequently as well. The most recent version of the manual is available online in searchable form at
http://dev.mysql.com/doc/. Other formats also are available there, including HTML, PDF, and Windows
CHM versions.
The Reference Manual source files are written in DocBook XML format. The HTML version and other
formats are produced automatically, primarily using the DocBook XSL stylesheets. For information
about DocBook, see http://docbook.org/
If you have questions about using MySQL, you can ask them using our mailing lists or forums. See
Section 1.6.1, “MySQL Mailing Lists”, and Section 1.6.2, “MySQL Community Support at the MySQL
Forums”. If you have suggestions concerning additions or corrections to the manual itself, please send
them to the http://www.mysql.com/company/contact/.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Typographical and Syntax Conventions

This manual was originally written by David Axmark and Michael “Monty” Widenius. It is maintained by
the MySQL Documentation Team, consisting of Chris Cole, Paul DuBois, Edward Gilmore, Stefan Hinz,
David Moss, Philip Olson, Daniel Price, Daniel So, and Jon Stephens.

1.2 Typographical and Syntax Conventions
This manual uses certain typographical conventions:
• Text in this style is used for SQL statements; database, table, and column names; program
listings and source code; and environment variables. Example: “To reload the grant tables, use the
FLUSH PRIVILEGES statement.”
• Text in this style indicates input that you type in examples.
• Text in this style indicates the names of executable programs and scripts, examples being
mysql (the MySQL command-line client program) and mysqld (the MySQL server executable).
• Text in this style is used for variable input for which you should substitute a value of your
own choosing.
• Text in this style is used for emphasis.
• Text in this style is used in table headings and to convey especially strong emphasis.
• Text in this style is used to indicate a program option that affects how the program is
executed, or that supplies information that is needed for the program to function in a certain way.
Example: “The --host option (short form -h) tells the mysql client program the hostname or IP
address of the MySQL server that it should connect to”.
• File names and directory names are written like this: “The global my.cnf file is located in the /etc
directory.”
• Character sequences are written like this: “To specify a wildcard, use the ‘%’ character.”
When commands are shown that are meant to be executed from within a particular program, the
prompt shown preceding the command indicates which command to use. For example, shell>
indicates a command that you execute from your login shell, root-shell> is similar but should be
executed as root, and mysql> indicates a statement that you execute from the mysql client program:
shell> type a shell command here
root-shell> type a shell command as root here
mysql> type a mysql statement here

In some areas different systems may be distinguished from each other to show that commands should
be executed in two different environments. For example, while working with replication the commands
might be prefixed with master and slave:
master> type a mysql command on the replication master here
slave> type a mysql command on the replication slave here

The “shell” is your command interpreter. On Unix, this is typically a program such as sh, csh, or bash.
On Windows, the equivalent program is command.com or cmd.exe, typically run in a console window.
When you enter a command or statement shown in an example, do not type the prompt shown in the
example.
Database, table, and column names must often be substituted into statements. To indicate that such
substitution is necessary, this manual uses db_name, tbl_name, and col_name. For example, you
might see a statement like this:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Overview of the MySQL Database Management System

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 any lettercase. This manual uses
uppercase.
In syntax descriptions, square brackets (“[” and “]”) 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, SELECT ... INTO OUTFILE is shorthand for the form
of SELECT statement that has an INTO OUTFILE clause following other parts of the 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 the CC environment variable and run the configure command looks like this in Bourne shell
syntax:
shell> CC=gcc ./configure

If you are using csh or tcsh, you must issue commands somewhat differently:
shell> setenv CC gcc
shell> ./configure

1.3 Overview of the MySQL Database Management System
1.3.1 What is MySQL?
MySQL, the most popular Open Source SQL database management system, is developed, distributed,
and supported by Oracle Corporation.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

What is MySQL?

The MySQL Web site (http://www.mysql.com/) provides the latest information about MySQL software.
• 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 databases are relational.
A relational database stores data in separate tables rather than putting all the data in one big
storeroom. The database structures are organized into physical files optimized for speed. The
logical model, with objects such as databases, tables, views, rows, and columns, offers a flexible
programming environment. You set up rules governing the relationships between different data
fields, such as one-to-one, one-to-many, unique, required or optional, and “pointers” between
different tables. The database enforces these rules, so that with a well-designed database, your
application never sees inconsistent, duplicate, orphan, out-of-date, or missing data.
The SQL part of “MySQL” stands for “Structured Query Language”. SQL is the most common
standardized language used to access databases. Depending on your programming environment,
you might enter SQL directly (for example, to generate reports), embed SQL statements into code
written in another language, or use a language-specific API that hides the SQL syntax.
SQL 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 the MySQL Licensing Overview for more information (http://www.mysql.com/company/legal/
licensing/).
• The MySQL Database Server is very fast, reliable, scalable, and easy to use.
If that is what you are looking for, you should give it a try. MySQL Server can run comfortably on a
desktop or laptop, alongside your other applications, web servers, and so on, requiring little or no
attention. If you dedicate an entire machine to MySQL, you can adjust the settings to take advantage
of all the memory, CPU power, and I/O capacity available. MySQL can also scale up to clusters of
machines, networked together.
You can find a performance comparison of MySQL Server with other database managers on our
benchmark page. See Section 8.13.2, “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.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Main Features of MySQL

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 standalone product.
• A large amount of contributed MySQL software is available.
MySQL Server has a practical set of features developed in close cooperation with our users. It is
very likely that your favorite application or language supports the MySQL Database Server.
The official way to pronounce “MySQL” is “My Ess Que Ell” (not “my sequel”), but we do not mind if you
pronounce it as “my sequel” or in some other localized way.

1.3.2 The Main Features of MySQL
This section describes some of the important characteristics of the MySQL Database Software. In most
respects, the roadmap applies to all versions of MySQL. For information about features as they are
introduced into MySQL on a series-specific basis, see the “In a Nutshell” section of the appropriate
Manual:
• MySQL 5.7: What Is New in MySQL 5.7
• MySQL 5.6: What Is New in MySQL 5.6
• MySQL 5.5: What Is New in MySQL 5.5
• MySQL 5.1: What Is New in MySQL 5.1

Internals and Portability
• Written in C and C++.
• Tested with a broad range of different compilers.
• Works on many different platforms. See http://www.mysql.com/support/supportedplatforms/
database.html.
• For portability, uses CMake in MySQL 5.5 and up. Previous series use GNU Automake, Autoconf,
and Libtool.
• Tested with Purify (a commercial memory leakage detector) as well as with Valgrind, a GPL tool
(http://developer.kde.org/~sewardj/).
• Uses multi-layered server design with independent modules.
• Designed to be fully multi-threaded using kernel threads, to easily use multiple CPUs if they are
available.
• Provides transactional and nontransactional storage engines.
• Uses very fast B-tree disk tables (MyISAM) with index compression.
• Designed to make it relatively easy to add other storage engines. This is useful if you want to provide
an SQL interface for an in-house database.
• Uses a very fast thread-based memory allocation system.
• Executes very fast joins using an optimized nested-loop join.
• Implements in-memory hash tables, which are used as temporary tables.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Main Features of MySQL

• Implements SQL functions using a highly optimized class library that should be as fast as possible.
Usually there is no memory allocation at all after query initialization.
• Provides the server as a separate program for use in a client/server networked environment, and 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.

Data Types
• Many data types: signed/unsigned integers 1, 2, 3, 4, and 8 bytes long, FLOAT, DOUBLE, CHAR,
VARCHAR, BINARY, VARBINARY, TEXT, BLOB, DATE, TIME, DATETIME, TIMESTAMP, YEAR, SET,
ENUM, and OpenGIS spatial types. See Chapter 11, Data Types.
• Fixed-length and variable-length string types.

Statements and Functions
• Full operator and function support in the SELECT list and WHERE clause 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 and ORDER BY clauses. Support for group functions (COUNT(),
AVG(), STD(), SUM(), MAX(), MIN(), and GROUP_CONCAT()).
• Support for LEFT OUTER JOIN and RIGHT OUTER JOIN with both standard SQL and ODBC
syntax.
• Support for aliases on tables and columns as required by standard SQL.
• Support for DELETE, INSERT, REPLACE, and UPDATE to return the number of rows that were
changed (affected), or to return the number of rows matched instead by setting a flag when
connecting to the server.
• Support for MySQL-specific SHOW statements that retrieve information about databases, storage
engines, tables, and indexes. Support for the INFORMATION_SCHEMA database, implemented
according to standard SQL.
• An EXPLAIN statement to show how the optimizer resolves a query.
• Independence of function names from table or column names. For example, ABS is a valid column
name. The only restriction is that for a function call, no spaces are permitted between the function
name and the “(” that follows it. See Section 9.3, “Keywords and Reserved Words”.
• You can refer to tables from different databases in the same statement.

Security
• A privilege and password system that is very flexible and secure, and that enables host-based
verification.
• Password security by encryption of all password traffic when you connect to a server.

Scalability and Limits
• Support for large databases. We use MySQL Server with databases that contain 50 million records.
We also know of users who use MySQL Server with 200,000 tables and about 5,000,000,000 rows.
• Support for up to 64 indexes per table. Each index may consist of 1 to 16 columns or parts of
columns. The maximum index width is 767 bytes for InnoDB tables, or 1000 for MyISAM. An index
may use a prefix of a column for CHAR, VARCHAR, BLOB, or TEXT column types.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Main Features of MySQL

Connectivity
• Clients can connect to MySQL Server using several protocols:
• Clients can connect using TCP/IP sockets on any platform.
• On Windows systems, clients can connect using named pipes if the server is started with the
--enable-named-pipe option. Windows servers also support shared-memory connections if
started with the --shared-memory option. Clients can connect through shared memory by using
the --protocol=memory option.
• On Unix systems, clients can connect using Unix domain socket files.
• MySQL client programs can be written in many languages. A client library written in C is available for
clients written in C or C++, or for any language that provides C bindings.
• APIs for C, C++, Eiffel, Java, Perl, PHP, Python, Ruby, and Tcl are available, enabling MySQL
clients to be written in many languages. See Chapter 20, Connectors and APIs.
• 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. Connector/ODBC source is available.
All ODBC 2.5 functions are supported, as are many others. See MySQL Connector/ODBC Developer
Guide.
• 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 MySQL
Connector/J 5.1 Developer Guide.
• MySQL Connector/Net enables developers to easily create .NET applications that require secure,
high-performance data connectivity with MySQL. It implements the required ADO.NET interfaces and
integrates into ADO.NET aware tools. Developers can build applications using their choice of .NET
languages. MySQL Connector/Net is a fully managed ADO.NET driver written in 100% pure C#. See
MySQL Connector/Net Developer Guide.

Localization
• The server can provide error messages to clients in many languages. See Section 10.2, “Setting the
Error Message Language”.
• Full support for several different character sets, including latin1 (cp1252), german, big5, ujis,
several Unicode character sets, and more. For example, the Scandinavian characters “å”, “ä” and “ö”
are permitted in table and column names.
• All data is saved in the chosen character set.
• Sorting and comparisons are done according to the chosen character set and collation (using
latin1 and 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.
• The server time zone can be changed dynamically, and individual clients can specify their own time
zone. See Section 10.6, “MySQL Server Time Zone Support”.

Clients and Tools
• MySQL includes several client and utility programs. These include both command-line programs
such as mysqldump and mysqladmin, and graphical programs such as MySQL Workbench.
• 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 mysqlcheck client. MySQL also
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

History of MySQL

includes myisamchk, a very fast command-line utility for performing these operations on MyISAM
tables. See Chapter 4, MySQL Programs.
• MySQL programs can be invoked with the --help or -? option to obtain online assistance.

1.3.3 History of MySQL
We started out with the intention of using the mSQL database system 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 enable third-party
code that was written for use with mSQL to be ported easily for use with MySQL.
MySQL is named after co-founder Monty Widenius's daughter, My.
The name of the MySQL Dolphin (our logo) is “Sakila,” which was chosen 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
feminine 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.4 What Is New in MySQL 5.0
The following features are implemented in MySQL 5.0:
• Information Schema.
The introduction of the INFORMATION_SCHEMA database in MySQL 5.0
provided a standards-compliant means for accessing the MySQL Server's metadata; that is, data
about the databases (schemas) on the server and the objects which they contain. See Chapter 19,
INFORMATION_SCHEMA Tables.
• Instance Manager.
Can be used to start and stop the MySQL Server, even from a remote host.
See Section 4.6.10, “mysqlmanager — The MySQL Instance Manager”.
• Precision Math.
MySQL 5.0 introduced stricter criteria for acceptance or rejection of data, and
implemented a new library for fixed-point arithmetic. These contributed to a much higher degree of
accuracy for mathematical operations and greater control over invalid values. See Section 12.17,
“Precision Math”.
• Storage Engines.

New storage engines were added and performance of others was improved.

• New storage engines in MySQL 5.0 include ARCHIVE and FEDERATED. See Section 14.8, “The
ARCHIVE Storage Engine”, and Section 14.7, “The FEDERATED Storage Engine”.
• Performance Improvements in the InnoDB Storage Engine:
• New compact storage format which can save up to 20% of the disk space required in previous
MySQL/InnoDB versions.
• Faster recovery from a failed or aborted ALTER TABLE.
• Faster implementation of TRUNCATE TABLE.
(See Section 14.2, “The InnoDB Storage Engine”.)
• Performance Improvements in the NDBCLUSTER Storage Engine:
• Faster handling of queries that use IN and BETWEEN.
• Condition pushdown: In cases involving the comparison of an unindexed column with a
constant, this condition is “pushed down” to the cluster where it is evaluated in all partitions
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

What Is New in MySQL 5.0

simultaneously, eliminating the need to send nonmatching records over the network. This can
make such queries 10 to 100 times faster than in MySQL 4.1 Cluster.
See Section 13.8.2, “EXPLAIN Syntax”, for more information.
(See Chapter 17, MySQL Cluster.)
• Stored Routines.
MySQL 5.0 added support for stored procedures and stored functions. See
Section 18.2, “Using Stored Routines (Procedures and Functions)”.
• Triggers.
• Views.

MySQL 5.0 added limited support for triggers. See Section 18.3, “Using Triggers”.
MySQL 5.0 added support for named, updatable views. See Section 18.4, “Using Views”.

• Cursors.
Elementary support for server-side cursors. For information about using cursors within
stored routines, see Section 13.6.6, “Cursors”. For information about using cursors from within the C
API, see Section 20.6.11.3, “mysql_stmt_attr_set()”.
• Strict Mode and Standard Error Handling.
MySQL 5.0 added a strict mode where by it follows
standard SQL in a number of ways in which it did not previously. Support for standard SQLSTATE
error messages was also implemented. See Section 5.1.7, “Server SQL Modes”.
• VARCHAR Data Type.
The effective maximum length of a VARCHAR column was increased to
65,535 bytes, and stripping of trailing whitespace was eliminated. VARCHAR in MySQL 5.0 is more
efficient than in previous versions, due to the elimination of the old (and nonstandard) removal of
trailing spaces during retrieval. (The actual maximum length of a VARCHAR is determined by the
maximum row size and the character set you use. The maximum effective column length is subject to
a row size of 65,535 bytes, which is shared among all columns.) See Section 11.4, “String Types”.
• BIT Data Type.
A true BIT column type is available that can be used to store numbers in binary
notation. This type is much more efficient for storage and retrieval of Boolean values than the
workarounds required in MySQL in versions previous to 5.0. See Section 11.1.1, “Numeric Type
Overview”.
• Optimizer enhancements.
Several optimizer improvements were made to improve the speed of
certain types of queries and in the handling of certain types. These include:
• MySQL 5.0 introduces a new “greedy” optimizer which can greatly reduce the time required to
arrive at a query execution plan. This is particularly noticeable where several tables are to be
joined and no good join keys can otherwise be found. Without the greedy optimizer, the complexity
of the search for an execution plan is calculated as N!, where N is the number of tables to be
joined. The greedy optimizer reduces this to N!/(D-1)!, where D is the depth of the search.
Although the greedy optimizer does not guarantee the best possible of all execution plans (this
is currently being worked on), it can reduce the time spent arriving at an execution plan for a join
involving a great many tables—30, 40, or more—by a factor of as much as 1,000. This should
eliminate most if not all situations where users thought that the optimizer had hung when trying to
perform joins across many tables.
• Use of the Index Merge method to obtain better optimization of AND and OR relations over different
keys. (Previously, these were optimized only where both relations in the WHERE clause involved
the same key.) This also applies to other one-to-one comparison operators (>, <, and so on),
including = and the IN operator. This means that MySQL can use multiple indexes in retrieving
results for conditions such as WHERE key1 > 4 OR key2 < 7 and even combinations of
conditions such as WHERE (key1 > 4 OR key2 < 7) AND (key3 >= 10 OR key4 = 1).
See Section 8.2.1.4, “Index Merge Optimization”.
• A new equality detector finds and optimizes “hidden” equalities in joins. For example, a WHERE
clause such as
t1.c1=t2.c2 AND t2.c2=t3.c3 AND t1.c1 < 5

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Development History

implies these other conditions
t1.c1=t3.c3 AND t2.c2 < 5 AND t3.c3 < 5

These optimizations can be applied with any combination of AND and OR operators. See
Section 8.2.1.9, “Nested Join Optimization”, and Section 8.2.1.10, “Outer Join Simplification”.
• Optimization of NOT IN and NOT BETWEEN relations, reducing or eliminating table scans for
queries making use of them by mean of range analysis. The performance of MySQL with regard to
these relations now matches its performance with regard to IN and BETWEEN.
• XA Transactions.
Transactions”.

MySQL 5.0 supports XA (distributed) transactions. See Section 13.3.7, “XA

1.5 MySQL Development History
This section describes the general MySQL development history, including major features implemented
in or planned for various MySQL releases. The following sections provide information for each release
series.
The current production release series is MySQL 5.1, which was declared stable for production use as
of MySQL 5.1.30, released in November 2008. The previous production release series was MySQL
5.0, which was declared stable for production use as of MySQL 5.0.15, released in October 2005.
“General Availability status” means that future 5.1 and 5.0 development is limited only to bugfixes. For
the older MySQL 4.1, 4.0, and 3.23 series, only critical bugfixes are made.
Before upgrading from one release series to the next, please see the notes in Section 2.19.1,
“Upgrading MySQL”.
The most requested features and the versions in which they were implemented are summarized in the
following table.
Feature

MySQL Series

Unions

4.0

Subqueries

4.1

R-trees

4.1 (for the MyISAM storage engine)

Stored procedures and functions 5.0
Views

5.0

Cursors

5.0

XA transactions

5.0

Triggers

5.0 and 5.1

Event scheduler

5.1

Partitioning

5.1

Pluggable storage engine API

5.1

Plugin API

5.1

InnoDB Plugin

5.1

Row-based replication

5.1

Server log tables

5.1

1.6 MySQL Information Sources
This section lists sources of additional information that you may find helpful, such as the MySQL
mailing lists and user forums, and Internet Relay Chat.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Mailing Lists

1.6.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 receive all postings to the list as email messages. You
can also send your own questions and answers to the list.
To subscribe to or unsubscribe from any of the mailing lists described in this section, visit http://
lists.mysql.com/. For most of them, you can select the regular version of the list where you get
individual messages, or a digest version where you get one large message per day.
Please do not send messages about subscribing or unsubscribing to any of the mailing lists, because
such messages are distributed automatically to thousands of other users.
Your local site may have many subscribers to a MySQL mailing list. If so, the site may have a local
mailing list, so that messages sent from lists.mysql.com to your site are propagated to the local
list. In such cases, please contact your system administrator to be added to or dropped from the local
MySQL list.
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
The list for announcements of new versions of MySQL and related programs. This is a low-volume
list to which all MySQL users should subscribe.
• mysql
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
The list for people who want to stay informed about issues reported since the last release of MySQL
or who want to be actively involved in the process of bug hunting and fixing. See Section 1.7, “How
to Report Bugs or Problems”.
• internals
The list for people who work on the MySQL code. This is also the forum for discussions on MySQL
development and for posting patches.
• mysqldoc
The list for people who work on the MySQL documentation.
• benchmarks
The list 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, file system, disk system, and so on.
• packagers
The list 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
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Mailing Lists

The list for discussions about the MySQL server and Java. It is mostly used to discuss JDBC drivers
such as MySQL Connector/J.
• win32
The list for all topics concerning the MySQL software on Microsoft operating systems, such as
Windows 9x, Me, NT, 2000, XP, and 2003.
• myodbc
The list for all topics concerning connecting to the MySQL server with ODBC.
• gui-tools
The list for all topics concerning MySQL graphical user interface tools such as MySQL Workbench.
• cluster
The list for discussion of MySQL Cluster.
• dotnet
The list for discussion of the MySQL server and the .NET platform. It is mostly related to MySQL
Connector/Net.
• plusplus
The list for all topics concerning programming with the C++ API for MySQL.
• perl
The list for all topics concerning Perl support for MySQL with DBD::mysql.
If you're unable to get an answer to your questions from a MySQL mailing list or forum, one option is to
purchase support from Oracle. This puts you in direct contact with MySQL developers.
The following MySQL mailing lists are in languages other than English. These lists are not operated by
Oracle.
• 
A French mailing list.
• 
A Korean mailing list. To subscribe, email subscribe mysql your@email.address to this list.
• 
A German mailing list. To subscribe, email subscribe mysql-de your@email.address to this
list. You can find information about this mailing list at http://www.4t2.com/mysql/.
• 
A Portuguese mailing list. To subscribe, email subscribe mysql-br your@email.address to
this list.
• 
A Spanish mailing list. To subscribe, email subscribe mysql your@email.address to this list.

1.6.1.1 Guidelines for Using the Mailing Lists
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Community Support at the MySQL Forums

Please do not post mail messages from your browser with HTML mode turned on. Many users do not
read mail with a browser.
When you answer a question sent to a mailing list, if you consider your answer to have broad interest,
you may want to post it to the 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. Do not feel obliged to quote the entire
original message.
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.6.2 MySQL Community Support at the MySQL Forums
The forums at http://forums.mysql.com are an important community resource. Many forums are
available, grouped into these general categories:
• Migration
• MySQL Usage
• MySQL Connectors
• Programming Languages
• Tools
• 3rd-Party Applications
• Storage Engines
• MySQL Technology
• SQL Standards
• Business

1.6.3 MySQL Community Support on Internet Relay Chat (IRC)
In addition to the various MySQL mailing lists and forums, you can find experienced community people
on Internet Relay Chat (IRC). These are the best networks/channels currently known to us:
freenode (see http://www.freenode.net/ for servers)
• #mysql is primarily for MySQL questions, but other database and general SQL questions are
welcome. Questions about PHP, Perl, or C in combination with MySQL are also common.
• #workbench is primarily for MySQL Workbench related questions and thoughts, and it is also a
good place to meet the MySQL Workbench developers.
If you are looking for IRC client software to connect to an IRC network, take a look at xChat (http://
www.xchat.org/). X-Chat (GPL licensed) is available for Unix as well as for Windows platforms (a free
Windows build of X-Chat is available at http://www.silverex.org/download/).

1.6.4 MySQL Enterprise
Oracle offers technical support in the form of MySQL Enterprise. For organizations that rely on the
MySQL DBMS for business-critical production applications, MySQL Enterprise is a commercial
subscription offering which includes:
• MySQL Enterprise Server
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Report Bugs or Problems

• MySQL Enterprise Monitor
• Monthly Rapid Updates and Quarterly Service Packs
• MySQL Knowledge Base
• 24x7 Technical and Consultative Support
MySQL Enterprise is available in multiple tiers, giving you the flexibility to choose the level of service
that best matches your needs. For more information, see MySQL Enterprise.

1.7 How to Report Bugs or Problems
Before posting a bug report about a problem, please try to verify that it is a bug and that it has not been
reported already:
• 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. In addition, the
release notes accompanying the manual can be particularly useful since it is quite possible that a
newer version contains a solution to your problem. The release notes are available at the location
just given for the manual.
• If you get a parse error for an SQL statement, please check your syntax closely. If you cannot find
something wrong with it, it is 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 doesn't cover
the syntax that you are using, MySQL Server doesn't support your statement.
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.
• For solutions to some common problems, see Section B.5, “Problems and Common Errors”.
• Search the bugs database at http://bugs.mysql.com/ to see whether the bug has been reported and
fixed.
• Search the MySQL mailing list archives at http://lists.mysql.com/. See Section 1.6.1, “MySQL Mailing
Lists”.
• You can also use http://www.mysql.com/search/ to search all the Web pages (including the manual)
that are located at the MySQL Web site.
If you cannot find an answer in the manual, the bugs database, or the mailing list archives, check with
your local MySQL expert. If you still cannot find an answer to your question, please use the following
guidelines for reporting the bug.
The normal way to report bugs is to visit http://bugs.mysql.com/, which is the address for our bugs
database. This database is public and can be browsed and searched by anyone. If you log in to the
system, you can enter new reports.
Bugs posted in the bugs database at http://bugs.mysql.com/ that are corrected for a given release are
noted in the release notes.
If you find a sensitive security bug in MySQL Server, please let us know immediately by sending an
email message to . Exception: Support customers should report all
problems, including security bugs, to Oracle Support at http://support.oracle.com/.
To discuss problems with other users, you can use one of the MySQL mailing lists. Section 1.6.1,
“MySQL Mailing Lists”.
Writing a good bug report takes patience, but doing it right the first time saves time both for us and for
yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix
the bug in the next release. This section helps you write your report correctly so that you do not waste
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Report Bugs or Problems

your time doing things that may not help us much or at all. 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 your test case or by running the shell or Perl script that you include in the bug report.
Any bug that we are able to repeat has a high chance of being fixed in the next MySQL release.
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 21.3, “Debugging and Porting MySQL”.
Remember that it is possible for us to respond to a report 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 do not matter. A good principle to follow is that 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 that you use, and (b) not fully describing the platform on which the MySQL server is
installed (including the platform type and version number). These are highly relevant pieces of
information, and in 99 cases out of 100, the bug report is useless without them. Very often we get
questions like, “Why doesn't this work for me?” Then we find that the feature requested wasn't
implemented in that MySQL version, or that a bug described in a report has been fixed in newer
MySQL versions. Errors often are 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 MySQLrelated. 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 used.
Note that every compiling problem should be regarded as a bug and reported accordingly.
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, it is better that the error message reported exactly
matches the one that the program produces. (Even the lettercase should be observed.) It is best
to copy and paste the entire error message into your report. You should never try to reproduce the
message from memory.
If you have a problem with Connector/ODBC (MyODBC), please try to generate a trace file and send it
with your report. See How to Report Connector/ODBC Problems or Bugs.
If your report includes long query output lines from test cases that you run with the mysql commandline tool, you can make the output more readable by using the --vertical option or the \G statement
terminator. The EXPLAIN SELECT example later in this section demonstrates the use of \G.
Please include the following information in your report:
• The version number of the MySQL distribution you are using (for example, MySQL 5.7.10). You can
find out which version you are running by executing mysqladmin version. The 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.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Report Bugs or Problems

• If you are using a source distribution of the MySQL software, include the name and version number
of the compiler that you used. If you have a binary distribution, include the distribution name.
• 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 mysqld died, you should also report the statement that crashed mysqld. You can usually get this
information by running mysqld with query logging enabled, and then looking in the log after mysqld
crashes. See Section 21.3, “Debugging and Porting MySQL”.
• If a database table is related to the problem, include the output from the SHOW CREATE TABLE
db_name.tbl_name statement in the bug report. This is a very easy way to get the definition of
any table in a database. The information helps us create a situation matching the one that you have
experienced.
• The SQL mode in effect when the problem occurred can be significant, so please report the value
of the sql_mode system variable. For stored procedure, stored function, and trigger objects, the
relevant sql_mode value is the one in effect when the object was created. For a stored procedure
or function, the SHOW CREATE PROCEDURE or SHOW CREATE FUNCTION statement shows the
relevant SQL mode, or you can query INFORMATION_SCHEMA for the information:
SELECT ROUTINE_SCHEMA, ROUTINE_NAME, SQL_MODE
FROM INFORMATION_SCHEMA.ROUTINES;

For triggers, you can use this statement:
SELECT EVENT_OBJECT_SCHEMA, EVENT_OBJECT_TABLE, TRIGGER_NAME, SQL_MODE
FROM INFORMATION_SCHEMA.TRIGGERS;

• For performance-related bugs or problems with SELECT statements, you should always include
the output of EXPLAIN SELECT ..., and at least the number of rows that the SELECT statement
produces. You should also include the output from SHOW CREATE TABLE tbl_name for each
table that is involved. The more information you provide about your situation, the more likely it is that
someone can help you.
The following is an example of a very good bug report. The statements are run using the mysql
command-line tool. Note the use of the \G statement terminator for statements that would otherwise
provide very long output lines that are difficult to read.
mysql> SHOW VARIABLES;
mysql> SHOW COLUMNS FROM ...\G

mysql> EXPLAIN SELECT ...\G

mysql> FLUSH STATUS;
mysql> SELECT ...;

mysql> SHOW STATUS;


• If a bug or problem occurs while running mysqld, try to provide an input script that reproduces the
anomaly. This script should include any necessary source files. The more closely the script can
reproduce your situation, the better. If you can make a reproducible test case, you should upload it to
be attached to the bug report.
If you cannot provide a script, you should at least include the output from mysqladmin variables
extended-status processlist in your report to provide some information on how your system
is performing.
• If you cannot produce a test case with only a few rows, or if the test table is too big to be included in
the bug report (more than 10 rows), you should dump your tables using mysqldump and create a
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Report Bugs or Problems

README file that describes your problem. Create a compressed archive of your files using tar and
gzip or zip. After you initiate a bug report for our bugs database at http://bugs.mysql.com/, click the
Files tab in the bug report for instructions on uploading the archive to the bugs database.
• If you believe that the MySQL server produces a strange result from a statement, include not only the
result, but also your opinion of what the result should be, and an explanation describing the basis for
your opinion.
• When you provide an example of the problem, it is better to use the table names, variable names,
and so forth that exist in your actual situation than to come up with new names. The problem could
be related to the name of a table or variable. 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. If you have data that you do not want to be visible
to others in the bug report, you can upload it using the Files tab as previously described. If the
information is really top secret and you do not want to show it even to us, 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 mysqld server, as well as the options that you use to run
any MySQL client programs. The options to programs such as mysqld and mysql, and to the
configure script, are often key to resolving problems and are very relevant. It is never a bad idea
to include them. If your problem involves a program written in a language such as Perl or PHP,
please include the language processor's version number, as well as the version for any modules
that the program uses. For example, if you have a Perl script that uses the DBI and DBD::mysql
modules, include the version numbers for Perl, DBI, and DBD::mysql.
• If your question is related to the privilege system, please include the output of mysqladmin
reload, and all the error messages you get when trying to connect. When you test your privileges,
you should execute mysqladmin reload version and try to connect with the program that gives
you trouble.
• If you have a patch for a bug, do include it. But do not assume that the patch is all we need, or that
we can use it, if you do not 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 cannot use it.
If we cannot verify the exact purpose of the patch, we will not use it. Test cases help us here. Show
that the patch handles all the situations that may occur. If we find a borderline case (even a rare one)
where the patch will not 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 cannot 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 your data appears corrupt or you get errors when you access a particular table, first check your
tables with CHECK TABLE. If that statement reports any errors:
• The InnoDB crash recovery mechanism handles cleanup when the server is restarted after being
killed, so in typical operation there is no need to “repair” tables. If you encounter an error with
InnoDB tables, restart the server and see whether the problem persists, or whether the error
affected only cached data in memory. If data is corrupted on disk, consider restarting with the
innodb_force_recovery option enabled so that you can dump the affected tables.
• For non-transactional tables, try to repair them with REPAIR TABLE or with myisamchk. See
Chapter 5, MySQL Server Administration.
If you are running Windows, please verify the value of lower_case_table_names using the SHOW
VARIABLES LIKE 'lower_case_table_names' statement. This variable affects how the server
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Standards Compliance

handles lettercase of database and table names. Its effect for a given value should be as described
in Section 9.2.2, “Identifier Case Sensitivity”.
• 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.4.1, “The Error Log”. Please include any
relevant information from this file in your bug report. Normally mysqld should never crash a table
if nothing killed it in the middle of an update. If you can find the cause of mysqld dying, it is much
easier for us to provide you with a fix for the problem. See Section B.5.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.4.2, “Choosing Which
MySQL Distribution to Install”.

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 can find out what they are and how to use them. You
can also find information about functionality missing from MySQL Server, and how to work around
some of the 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,
“SQL:2003” refers to the standard released in 2003, and “SQL:2008” refers to the most recent version
of the standard, released in 2008. We use the phrase “the SQL standard” or “standard SQL” to mean
the current version of the SQL Standard at any time.
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 is an example of this strategy. See Section 13.2.4,
“HANDLER Syntax”.
We continue to support transactional and nontransactional databases to satisfy both mission-critical
24/7 usage and heavy Web or logging usage.
MySQL Server was originally designed to work with medium-sized databases (10-100 million rows,
or about 100MB per table) on small computer systems. Today MySQL Server handles terabytesized 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.
We are not targeting real-time support, although MySQL replication capabilities offer significant
functionality.
MySQL supports ODBC levels 0 to 3.51.
MySQL supports high-availability database clustering using the NDBCLUSTER storage engine. See
Chapter 17, MySQL Cluster.
XML support is to be implemented in a future version of the database server.

Selecting SQL Modes
The MySQL server can operate in different SQL modes, and can apply these modes differently for
different clients, depending on the value of the sql_mode system variable. DBAs can set the global
SQL mode to match site server operating requirements, and each application can set its session SQL
mode to its own requirements.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running MySQL in ANSI Mode

Modes affect the SQL syntax MySQL supports and the data validation checks it performs. This makes
it easier to use MySQL in different environments and to use MySQL together with other database
servers.
For more information on setting the SQL mode, see Section 5.1.7, “Server SQL Modes”.

Running MySQL in ANSI Mode
To run MySQL Server in ANSI mode, start mysqld with the --ansi option. Running the server in
ANSI mode is the same as starting it with the following options:
--transaction-isolation=SERIALIZABLE --sql-mode=ANSI

To achieve the same effect at runtime, execute these two statements:
SET GLOBAL TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SET GLOBAL sql_mode = 'ANSI';

You can see that setting the sql_mode system variable to 'ANSI' enables all SQL mode options that
are relevant for ANSI mode as follows:
mysql> SET GLOBAL sql_mode='ANSI';
mysql> SELECT @@global.sql_mode;
-> 'REAL_AS_FLOAT,PIPES_AS_CONCAT,ANSI_QUOTES,IGNORE_SPACE,ANSI'

Running the server in ANSI mode with --ansi is not quite the same as setting the SQL mode to
'ANSI' because the --ansi option also sets the transaction isolation level.
See Section 5.1.3, “Server Command Options”.

1.8.1 MySQL Extensions to Standard SQL
MySQL Server supports some extensions that you probably won't find in other SQL DBMSs. Be
warned that if you use them, your code won't be portable to other SQL servers. In some cases, you can
write code that includes MySQL extensions, but is still portable, by using comments of the following
form:
/*! MySQL-specific code */

In this case, MySQL Server parses and executes the code within the comment as it would any other
SQL statement, but other SQL servers will ignore the extensions. For example, MySQL Server
recognizes the STRAIGHT_JOIN keyword in the following statement, but other servers will not:
SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...

If you add a version number after the “!” character, the syntax within the comment is executed only if
the MySQL version is greater than or equal to the specified version number. The TEMPORARY keyword
in the following comment is executed only by servers from MySQL 3.23.02 or higher:
CREATE /*!32302 TEMPORARY */ TABLE t (a INT);

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 maps tables
within a database to file names in the database directory. This has a few implications:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Extensions to Standard SQL

•

Database and table names are case sensitive in MySQL Server on operating systems that
have case-sensitive file names (such as most Unix systems). See Section 9.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 storage engine. For example, it is possible to rename a MyISAM table
by renaming the .MYD, .MYI, and .frm files to which the table corresponds. (Nevertheless, it is
preferable to use RENAME TABLE or ALTER TABLE ... RENAME and let the server rename the
files.)
Database and table names cannot contain path name separator characters (“/”, “\”).
• General language syntax
• By default, strings can be enclosed by either “"” or “'”, not just by “'”. (If the ANSI_QUOTES SQL
mode is enabled, strings can be enclosed only by “'” and the server interprets strings enclosed by
“"” as identifiers.)
• “\” is the 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, and REPAIR TABLE statements.
• The CREATE DATABASE, DROP DATABASE, and ALTER DATABASE statements. See
Section 13.1.6, “CREATE DATABASE Syntax”, Section 13.1.13, “DROP DATABASE Syntax”, and
Section 13.1.1, “ALTER DATABASE Syntax”.
• The DO statement.
• EXPLAIN SELECT to obtain a description of how tables are processed by the query optimizer.
• The FLUSH and RESET statements.
• The SET statement. See Section 13.7.4, “SET Syntax”.
• The SHOW statement. See Section 13.7.5, “SHOW Syntax”. The information produced by many of
the MySQL-specific SHOW statements can be obtained in more standard fashion by using SELECT
to query INFORMATION_SCHEMA. See Chapter 19, INFORMATION_SCHEMA Tables.
•

Use of LOAD DATA INFILE. In many cases, this syntax is compatible with Oracle's LOAD DATA
INFILE. See Section 13.2.6, “LOAD DATA INFILE Syntax”.

• Use of RENAME TABLE. See Section 13.1.20, “RENAME TABLE Syntax”.
• Use of REPLACE instead of DELETE plus INSERT. See Section 13.2.7, “REPLACE Syntax”.
• Use of CHANGE col_name, DROP col_name, or DROP INDEX, IGNORE or RENAME in ALTER
TABLE statements. Use of multiple ADD, ALTER, DROP, or CHANGE clauses in an ALTER TABLE
statement. See Section 13.1.4, “ALTER TABLE Syntax”.
• Use of index names, indexes on a prefix of a column, and use of INDEX or KEY in CREATE TABLE
statements. See Section 13.1.10, “CREATE TABLE Syntax”.
• Use of TEMPORARY or IF NOT EXISTS with CREATE TABLE.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Extensions to Standard SQL

• Use of IF EXISTS with DROP TABLE and DROP DATABASE.
• The capability of dropping multiple tables with a single DROP TABLE statement.
• The ORDER BY and LIMIT clauses of the UPDATE and DELETE statements.
• INSERT INTO tbl_name SET col_name = ... syntax.
• The DELAYED clause of the INSERT and REPLACE statements.
• The LOW_PRIORITY clause of the INSERT, REPLACE, DELETE, and UPDATE statements.
• Use of INTO OUTFILE or INTO DUMPFILE in SELECT statements. See Section 13.2.8, “SELECT
Syntax”.
• Options such as STRAIGHT_JOIN or SQL_SMALL_RESULT in SELECT statements.
• You don't need to name all selected columns in the GROUP BY clause. This gives better
performance for some very specific, but quite normal queries. See Section 12.16, “GROUP BY
(Aggregate) Functions”.
• You can specify ASC and DESC with GROUP BY, not just with ORDER BY.
• The ability to set variables in a statement with the := assignment operator. See Section 9.4, “UserDefined Variables”.
• Data types
• The MEDIUMINT, SET, and ENUM data types, and the various BLOB and TEXT data types.
• The AUTO_INCREMENT, BINARY, NULL, UNSIGNED, and ZEROFILL data type attributes.
• Functions and operators
• To make it easier for users who migrate 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, || and OR are synonyms, as are && and AND. Because
of this nice syntax, MySQL Server doesn't support the standard SQL || operator for string
concatenation; use CONCAT() instead. Because CONCAT() takes any number of arguments, it is
easy to convert use of the || operator to MySQL Server.
• Use of COUNT(DISTINCT value_list) where value_list has more than one element.
• String comparisons are case-insensitive by default, with sort ordering determined by the collation
of the current character set, which is latin1 (cp1252 West European) by default. If you don't like
this, you should declare your columns with the BINARY attribute or use the BINARY cast, which
causes comparisons to be done using the underlying character code values rather than a lexical
ordering.
•

The % operator is a synonym for MOD(). That is, N % M is equivalent to MOD(N,M). % is
supported for C programmers and for compatibility with PostgreSQL.

• The =, <>, <=, <, >=, >, <<, >>, <=>, AND, OR, or LIKE operators may be used in expressions in
the output column list (to the left of the FROM) in SELECT statements. For example:
mysql> SELECT col1=1 AND col2=2 FROM my_table;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Differences from Standard SQL

• The LAST_INSERT_ID() function returns the most recent AUTO_INCREMENT value. See
Section 12.13, “Information Functions”.
• LIKE is permitted on numeric values.
• The REGEXP and NOT REGEXP extended regular expression operators.
• CONCAT() or CHAR() with one argument or more than two arguments. (In MySQL Server, these
functions can take a variable number of arguments.)
• The BIT_COUNT(), CASE, ELT(), FROM_DAYS(), FORMAT(), IF(), PASSWORD(), ENCRYPT(),
MD5(), ENCODE(), DECODE(), PERIOD_ADD(), PERIOD_DIFF(), TO_DAYS(), and WEEKDAY()
functions.
• Use of TRIM() to trim substrings. Standard SQL supports removal of single characters only.
• The GROUP BY functions STD(), BIT_OR(), BIT_AND(), BIT_XOR(), and GROUP_CONCAT().
See Section 12.16, “GROUP BY (Aggregate) Functions”.

1.8.2 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. (This is fixed in MySQL
5.0.3). See Section B.5.7, “Known Issues in MySQL”.
• In some cases, CHAR columns are silently converted to VARCHAR columns when you define a table
or alter its structure. (This no longer occurs as of MySQL 5.0.3). See Section 13.1.10.4, “Silent
Column Specification Changes”.
• There are several differences between the MySQL and standard SQL privilege systems. For
example, in MySQL, 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. For more information,
see Section 13.7.1.5, “REVOKE Syntax”.
• The CAST() function does not support cast to REAL or BIGINT. See Section 12.10, “Cast Functions
and Operators”.
• Standard SQL requires that a HAVING clause in a SELECT statement be able to refer to columns in
the GROUP BY clause. This cannot be done before MySQL 5.0.2.

1.8.2.1 SELECT INTO TABLE
MySQL Server doesn't support the SELECT ... INTO TABLE Sybase SQL extension. Instead,
MySQL Server supports the INSERT INTO ... SELECT standard SQL syntax, which is basically the
same thing. See Section 13.2.5.1, “INSERT ... SELECT Syntax”. For example:
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.
You can use SELECT ... INTO with user-defined variables. The same syntax can also be used
inside stored routines using cursors and local variables. See Section 13.2.8.1, “SELECT ... INTO
Syntax”.

1.8.2.2 UPDATE
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Differences from Standard SQL

If you access a column from the table to be updated in an expression, UPDATE uses the current value
of the column. The second assignment in the following statement sets col2 to the current (updated)
col1 value, not the original col1 value. The result is that col1 and col2 have the same value. This
behavior differs from standard SQL.
UPDATE t1 SET col1 = col1 + 1, col2 = col1;

1.8.2.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
Chapter 14, Storage Engines. For information about InnoDB differences from standard SQL with
regard to treatment of transaction errors, see Section 14.2.12, “InnoDB Error Handling”.
The other nontransactional 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.
Because MySQL Server supports 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 tradeoff for transactional versus nontransactional storage engines lies mostly in
performance. Transactional tables have significantly higher memory and disk space requirements, and
more CPU overhead. On the other hand, transactional storage engines such as InnoDB also offer
many significant features. MySQL Server's modular design enables 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
nontransactional MyISAM tables, and how do these features compare with the transactional storage
engines?
• If your applications are written in a way that is dependent on being able to call ROLLBACK rather
than COMMIT in critical situations, transactions are more convenient. Transactions also ensure that
unfinished updates or corrupting activities are not committed to the database; the server is given the
opportunity to do an automatic rollback and your database is saved.
If you use nontransactional tables, MySQL Server in almost all cases enables 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. You can normally fix tables perfectly with no data integrity loss just by using the MySQL log
or even adding one extra log.
• 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 there are no automatic aborts from the server, which is a common problem with
transactional database systems.
• To be safe with MySQL Server, regardless of whether you use transactional tables, you only need
to have backups and have binary logging turned on. When that is true, 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 advantages and disadvantages. Many users and application
developers depend on the ease with which they can code around problems where an abort appears
to be necessary, 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 nontransactional tables can offer on
the order of three to five times the speed of the fastest and most optimally tuned transactional tables.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Differences from Standard SQL

In situations where integrity is of highest importance, MySQL Server offers transaction-level reliability
and integrity even for nontransactional tables. If you lock tables with LOCK TABLES, all updates stall
until integrity checks are made. If you obtain a READ LOCAL lock (as opposed to a write lock) for a
table that enables concurrent inserts at the end of the table, reads are permitted, as are inserts by
other clients. The newly inserted records are not be seen by the client that has the read lock until
it releases the lock. With INSERT DELAYED, you can write inserts that go into a local queue until
the locks are released, without having the client wait for the insert to complete. See Section 8.11.3,
“Concurrent Inserts”, and Section 13.2.5.2, “INSERT DELAYED Syntax”.
“Atomic,” in the sense that we mean it, is nothing magical. It only means that you can be sure that while
each specific update is running, no other user can interfere with it, and there can never be an automatic
rollback (which can happen with transactional tables if you are not very careful). MySQL Server also
guarantees that there are no dirty reads.
Following are some techniques for working with nontransactional 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 employ the following strategy:
1. Use LOCK TABLES to lock all the tables you want to access.
2. Test the conditions that must be true before performing the update.
3. Update if the conditions are satisfied.
4. Use UNLOCK TABLES to release your locks.
This is usually a much faster method than using transactions with possible rollbacks, although not
always. The only situation this solution doesn't handle is when someone kills the threads in the
middle of an update. In that case, all locks are released but some of the updates may not have been
executed.
• 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.
For example, when we are updating customer information, we update only the customer data that
has changed and test only that none of the changed data, or data that depends on the changed data,
has changed compared to the original row. The test for changed data is done with the WHERE clause
in the UPDATE statement. If the record wasn't updated, we give the client a message: “Some of the
data you have changed has been changed by another user.” Then we show the old row versus the
new row in a window so that the user can decide which version of the customer record to use.
This gives us something that is similar to column locking but is actually even better because we only
update some of the columns, using values that are relative to their current values. This means that
typical UPDATE statements look something like these:
UPDATE tablename SET pay_back=pay_back+125;
UPDATE customer
SET
customer_date='current_date',
address='new address',
phone='new phone',
money_owed_to_us=money_owed_to_us-125
WHERE
customer_id=id AND address='old address' AND phone='old phone';

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Differences from Standard SQL

This is very efficient and works even if another client has changed the values in the pay_back or
money_owed_to_us columns.
•

In many cases, users have wanted LOCK TABLES or ROLLBACK for the purpose of managing
unique identifiers. This can be handled much more efficiently without locking or rolling back
by using an AUTO_INCREMENT column and either the LAST_INSERT_ID() SQL function or
the mysql_insert_id() C API function. See Section 12.13, “Information Functions”, and
Section 20.6.7.37, “mysql_insert_id()”.
You can generally code around the need for row-level locking. Some situations really do need it, and
InnoDB tables support row-level locking. Otherwise, with MyISAM tables, you can use a flag column
in the table and do something like the following:
UPDATE tbl_name SET row_flag=1 WHERE id=ID;

MySQL returns 1 for the number of affected rows if the row was found and row_flag wasn't 1 in the
original row. You can think of this as though MySQL Server changed the preceding statement to:
UPDATE tbl_name SET row_flag=1 WHERE id=ID AND row_flag <> 1;

1.8.2.4 Foreign Key Differences
MySQL's implementation of foreign keys differs from the SQL standard in the following key respects:
• If there are several rows in the parent table that have the same referenced key value, InnoDB acts
in foreign key checks as if the other parent rows with the same key value do not exist. For example,
if you have defined a RESTRICT type constraint, and there is a child row with several parent rows,
InnoDB does not permit the deletion of any of those parent rows.
InnoDB performs cascading operations through a depth-first algorithm, based on records in the
indexes corresponding to the foreign key constraints.
• A FOREIGN KEY constraint that references a non-UNIQUE key is not standard SQL but rather an
InnoDB extension.
• If ON UPDATE CASCADE or ON UPDATE SET NULL recurses to update the same table it has
previously updated during the same cascade, it acts like RESTRICT. This means that you cannot
use self-referential ON UPDATE CASCADE or ON UPDATE SET NULL operations. This is to prevent
infinite loops resulting from cascaded updates. A self-referential ON DELETE SET NULL, on the
other hand, is possible, as is a self-referential ON DELETE CASCADE. Cascading operations may not
be nested more than 15 levels deep.
• In an SQL statement that inserts, deletes, or updates many rows, foreign key constraints (like unique
constraints) are checked row-by-row. When performing foreign key checks, InnoDB sets shared rowlevel locks on child or parent records that it must examine. MySQL checks foreign key constraints
immediately; the check is not deferred to transaction commit. According to the SQL standard, the
default behavior should be deferred checking. That is, constraints are only checked after the entire
SQL statement has been processed. This means that it is not possible to delete a row that refers to
itself using a foreign key.
For information about how the InnoDB storage engine handles foreign keys, see Section 14.2.3.4,
“InnoDB and FOREIGN KEY Constraints”.

1.8.2.5 '--' as the Start of a Comment
Standard SQL uses the C syntax /* this is a comment */ for comments, and MySQL Server
supports this syntax as well. MySQL also support extensions to this syntax that enable MySQL-specific
SQL to be embedded in the comment, as described in Section 9.6, “Comment Syntax”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How MySQL Deals with Constraints

Standard SQL uses “--” as a start-comment sequence. MySQL Server uses “#” as the start comment
character. MySQL Server 3.23.3 and up also supports a variant of the “--” comment style. That is,
the “--” start-comment sequence must be followed by a space (or by a control character such as a
newline). The space is required to prevent problems with automatically generated SQL queries that use
constructs such as the following, where we automatically insert the value of the payment for payment:
UPDATE account SET credit=credit-payment

Consider about what happens if payment has a negative value such as -1:
UPDATE account SET credit=credit--1

credit--1 is a legal expression in SQL, but “--” 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 permitting comments to start with
“--” can have serious consequences.
Using our implementation requires a space following the “--” for it to be recognized as a start-comment
sequence in MySQL Server 3.23.3 and newer. Therefore, credit--1 is safe to use.
Another safe feature is that the mysql command-line client ignores 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 script in a text file that contains “--” comments, you should use the replace utility
as follows to convert the comments to use “#” characters before executing the script:
shell> replace " --" " #" < text-file-with-funny-comments.sql \
| mysql db_name

That is safer than executing the script in the usual way:
shell> mysql db_name < text-file-with-funny-comments.sql

You can also edit the script 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

See Section 4.8.2, “replace — A String-Replacement Utility”.

1.8.3 How MySQL Deals with Constraints
MySQL enables you to work both with transactional tables that permit rollback and with
nontransactional tables that do not. Because of this, constraint handling is a bit different in MySQL
than in other DBMSs. We must handle the case when you have inserted or updated a lot of rows in a
nontransactional table for which changes cannot be rolled back when an error occurs.
The basic philosophy is that MySQL Server tries to produce an error for anything that it can detect
while parsing a statement to be executed, and tries to recover from any errors that occur while
executing the statement. We do this in most cases, but not yet for all.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How MySQL Deals with Constraints

The options MySQL has when an error occurs are to stop the statement in the middle or to recover as
well as possible from the problem and continue. By default, the server follows the latter course. This
means, for example, that the server may coerce illegal values to the closest legal values.
Beginning with MySQL 5.0.2, several SQL mode options are available to provide greater control over
handling of bad data values and whether to continue statement execution or abort when errors occur.
Using these options, you can configure MySQL Server to act in a more traditional fashion that is like
other DBMSs that reject improper input. The SQL mode can be set globally at server startup to affect
all clients. Individual clients can set the SQL mode at runtime, which enables each client to select the
behavior most appropriate for its requirements. See Section 5.1.7, “Server SQL Modes”.
The following sections describe how MySQL Server handles different types of constraints.

1.8.3.1 PRIMARY KEY and UNIQUE Index Constraints
Normally, errors occurs for data-change statements (such as INSERT or UPDATE) that would violate
primary-key, unique-key, or foreign-key constraints. If you are using a transactional storage engine
such as InnoDB, MySQL automatically rolls back the statement. If you are using a nontransactional
storage engine, MySQL stops processing the statement at the row for which the error occurred and
leaves any remaining rows unprocessed.
MySQL supports an IGNORE keyword for INSERT, UPDATE, and so forth. If you use it, MySQL ignores
primary-key or unique-key violations and continues processing with the next row. See the section
for the statement that you are using (Section 13.2.5, “INSERT Syntax”, Section 13.2.10, “UPDATE
Syntax”, and so forth).
You can get information about the number of rows actually inserted or updated with the
mysql_info() C API function. You can also use the SHOW WARNINGS statement. See
Section 20.6.7.35, “mysql_info()”, and Section 13.7.5.37, “SHOW WARNINGS Syntax”.
Only InnoDB tables support foreign keys. See Section 14.2.3.4, “InnoDB and FOREIGN KEY
Constraints”.

1.8.3.2 FOREIGN KEY Constraints
Foreign keys let you cross-reference related data across tables, and foreign key constraints help keep
this spread-out data consistent.
MySQL supports ON UPDATE and ON DELETE foreign key references in CREATE TABLE and ALTER
TABLE statements. The available referential actions are RESTRICT (the default), CASCADE, SET NULL,
and NO ACTION.
SET DEFAULT is also supported by the MySQL Server but is currently rejected as invalid by InnoDB.
Since MySQL does not support deferred constraint checking, NO ACTION is treated as RESTRICT. For
the exact syntax supported by MySQL for foreign keys, see Section 13.1.10.3, “Using FOREIGN KEY
Constraints”.
MATCH FULL, MATCH PARTIAL, and MATCH SIMPLE are allowed, but their use should be avoided,
as they cause the MySQL Server to ignore any ON DELETE or ON UPDATE clause used in the same
statement. MATCH options do not have any other effect in MySQL, which in effect enforces MATCH
SIMPLE semantics full-time.
MySQL requires that foreign key columns be indexed; if you create a table with a foreign key constraint
but no index on a given column, an index is created.
You can obtain information about foreign keys from the INFORMATION_SCHEMA.KEY_COLUMN_USAGE
table. An example of a query against this table is shown here:
mysql> SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, CONSTRAINT_NAME

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How MySQL Deals with Constraints

> FROM INFORMATION_SCHEMA.KEY_COLUMN_USAGE
> WHERE REFERENCED_TABLE_SCHEMA IS NOT NULL;
+--------------+---------------+-------------+-----------------+
| TABLE_SCHEMA | TABLE_NAME
| COLUMN_NAME | CONSTRAINT_NAME |
+--------------+---------------+-------------+-----------------+
| fk1
| myuser
| myuser_id
| f
|
| fk1
| product_order | customer_id | f2
|
| fk1
| product_order | product_id | f1
|
+--------------+---------------+-------------+-----------------+
3 rows in set (0.01 sec)

Only InnoDB tables support foreign keys. See Section 14.2.3.4, “InnoDB and FOREIGN KEY
Constraints”, for information specific to foreign key support in InnoDB.

1.8.3.3 Constraints on Invalid Data
Before MySQL 5.0.2, MySQL is forgiving of illegal or improper data values and coerces them to legal
values for data entry. In MySQL 5.0.2 and up, that remains the default behavior, but you can enable
strict SQL mode to select more traditional treatment of bad values such that the server rejects them
and aborts the statement in which they occur. Section 5.1.7, “Server SQL Modes”.
This section describes the default (forgiving) behavior of MySQL, as well as the strict SQL mode and
how it differs.
If you are not using strict mode, then whenever you insert an “incorrect” value into a column, such as
a NULL into a NOT NULL column or a too-large numeric value into a numeric column, MySQL sets the
column to the “best possible value” instead of producing an error: The following rules describe in more
detail how this works:
• If you try to store an out of range value into a numeric column, MySQL Server instead stores zero,
the smallest possible value, or the largest possible value, whichever is closest to the invalid value.
• For strings, MySQL stores either the empty string or as much of the string as can be stored in the
column.
• If you try to store a string that does not start with a number into a numeric column, MySQL Server
stores 0.
• Invalid values for ENUM and SET columns are handled as described in Section 1.8.3.4, “ENUM and
SET Constraints”.
• MySQL permits you to store certain incorrect date values into DATE and DATETIME columns (such
as '2000-02-31' or '2000-02-00'). In this case, when an application has not enabled strict
SQL mode, it up to the application to validate the dates before storing them. 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 “zero” date value '0000-00-00' is stored in the
column instead.
• If you try to store NULL into a column that doesn't take NULL values, an error occurs for singlerow INSERT statements. For multiple-row INSERT statements or for INSERT INTO ... SELECT
statements, MySQL Server stores the implicit default value for the column data type. In general, this
is 0 for numeric types, the empty string ('') for string types, and the “zero” value for date and time
types. Implicit default values are discussed in Section 11.6, “Data Type Default Values”.
• If an INSERT statement specifies no value for a column, MySQL inserts its default value if the
column definition includes an explicit DEFAULT clause. If the definition has no such DEFAULT clause,
MySQL inserts the implicit default value for the column data type.
The reason for using the preceding rules in nonstrict mode is that we can't check these conditions until
the statement has begun executing. We can't just roll back if we encounter a problem after updating
a few rows, because the storage engine may not support rollback. The option of terminating the
statement is not that good; in this case, the update would be “half done,” which is probably the worst
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How MySQL Deals with Constraints

possible scenario. In this case, it is better to “do the best you can” and then continue as if nothing
happened.
In MySQL 5.0.2 and up, you can select stricter treatment of input values by using the
STRICT_TRANS_TABLES or STRICT_ALL_TABLES SQL modes:
SET sql_mode = 'STRICT_TRANS_TABLES';
SET sql_mode = 'STRICT_ALL_TABLES';

STRICT_TRANS_TABLES enables strict mode for transactional storage engines, and also to some
extent for nontransactional engines. It works like this:
• For transactional storage engines, bad data values occurring anywhere in a statement cause the
statement to abort and roll back.
• For nontransactional storage engines, a statement aborts if the error occurs in the first row to be
inserted or updated. (When the error occurs in the first row, the statement can be aborted to leave
the table unchanged, just as for a transactional table.) Errors in rows after the first do not abort the
statement, because the table has already been changed by the first row. Instead, bad data values
are adjusted and result in warnings rather than errors. In other words, with STRICT_TRANS_TABLES,
a wrong value causes MySQL to roll back all updates done so far, if that can be done without
changing the table. But once the table has been changed, further errors result in adjustments and
warnings.
For even stricter checking, enable STRICT_ALL_TABLES. This is the same as
STRICT_TRANS_TABLES except that for nontransactional storage engines, errors abort the statement
even for bad data in rows following the first row. This means that if an error occurs partway through
a multiple-row insert or update for a nontransactional table, a partial update results. Earlier rows are
inserted or updated, but those from the point of the error on are not. To avoid this for nontransactional
tables, either use single-row statements or else use STRICT_TRANS_TABLES if conversion warnings
rather than errors are acceptable. To avoid problems in the first place, do not use MySQL to check
column content. It is safest (and often faster) to let the application ensure that it passes only legal
values to the database.
With either of the strict mode options, you can cause errors to be treated as warnings by using INSERT
IGNORE or UPDATE IGNORE rather than INSERT or UPDATE without IGNORE.

1.8.3.4 ENUM and SET Constraints
ENUM and SET columns provide an efficient way to define columns that can contain only a given set of
values. See Section 11.4.4, “The ENUM Type”, and Section 11.4.5, “The SET Type”. However, before
MySQL 5.0.2, ENUM and SET columns do not provide true constraints on entry of invalid data:
• ENUM columns always have a default value. If you specify no default value, then it is NULL for
columns that can have NULL, otherwise it is the first enumeration value in the column definition.
• 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.
• 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'.
As of MySQL 5.0.2, you can configure the server to use strict SQL mode. See Section 5.1.7, “Server
SQL Modes”. With strict mode enabled, the definition of a ENUM or SET column does act as a constraint
on values entered into the column. An error occurs for values that do not satisfy these conditions:
• 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 as
ENUM('a','b','c'), values such as '', 'd', or 'ax' are illegal and are rejected.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Credits

• A SET value must be the empty string or a value consisting only of the values listed in the column
definition separated by commas. For a column defined as SET('a','b','c'), values such as 'd'
or 'a,b,c,d' are illegal and are rejected.
Errors for invalid values can be suppressed in strict mode if you use INSERT IGNORE or UPDATE
IGNORE. In this case, a warning is generated rather than an error. For ENUM, the value is inserted as
the error member (0). For SET, the value is inserted as given except that any invalid substrings are
deleted. For example, 'a,x,b,y' results in a value of 'a,b'.

1.9 Credits
The following sections list developers, contributors, and supporters that have helped to make MySQL
what it is today.

1.9.1 Contributors to MySQL
Although Oracle Corporation and/or its affiliates own all copyrights in the MySQL server and the
MySQL manual, we wish to recognize those who have made contributions of one kind or another to
the MySQL distribution. Contributors are listed here, in somewhat random order:
• Gianmassimo Vigazzola  or 
The initial port to Win32/NT.
• Per Eric Olsson
For constructive criticism and real testing of the dynamic record format.
• Irena Pancirov 
Win32 port with Borland compiler. mysqlshutdown.exe and mysqlwatch.exe.
• David J. Hughes
For the effort to make a shareware SQL database. At TcX, the predecessor of MySQL AB, we
started with mSQL, but found that it couldn't satisfy our purposes so instead we wrote an SQL
interface to our application builder Unireg. mysqladmin and mysql client are programs that were
largely influenced by their mSQL counterparts. We have put a lot of effort into making the MySQL
syntax a superset of mSQL. Many of the API's ideas are borrowed from mSQL to make it easy to port
free mSQL programs to the MySQL API. The MySQL software doesn't contain any code from mSQL.
Two files in the distribution (client/insert_test.c and client/select_test.c) are based
on the corresponding (noncopyrighted) files in the mSQL distribution, but are modified as examples
showing the changes necessary to convert code from mSQL to MySQL Server. (mSQL is copyrighted
David J. Hughes.)
• Patrick Lynch
For helping us acquire http://www.mysql.com/.
• Fred Lindberg
For setting up qmail to handle the MySQL mailing list and for the incredible help we got in managing
the MySQL mailing lists.
• Igor Romanenko 
mysqldump (previously msqldump, but ported and enhanced by Monty).
• Yuri Dario
For keeping up and extending the MySQL OS/2 port.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Contributors to MySQL

• Tim Bunce
Author of mysqlhotcopy.
• Zarko Mocnik 
Sorting for Slovenian language.
• "TAMITO" 
The _MB character set macros and the ujis and sjis character sets.
• Joshua Chamas 
Base for concurrent insert, extended date syntax, debugging on NT, and answering on the MySQL
mailing list.
• Yves Carlier 
mysqlaccess, a program to show the access rights for a user.
• Rhys Jones  (And GWE Technologies Limited)
For one of the early JDBC drivers.
• Dr Xiaokun Kelvin ZHU 
Further development of one of the early JDBC drivers and other MySQL-related Java tools.
• James Cooper 
For setting up a searchable mailing list archive at his site.
• Rick Mehalick 
For xmysql, a graphical X client for MySQL Server.
• Doug Sisk 
For providing RPM packages of MySQL for Red Hat Linux.
• Diemand Alexander V. 
For providing RPM packages of MySQL for Red Hat Linux-Alpha.
• Antoni Pamies Olive 
For providing RPM versions of a lot of MySQL clients for Intel and SPARC.
• Jay Bloodworth 
For providing RPM versions for MySQL 3.21.
• David Sacerdote 
Ideas for secure checking of DNS host names.
• Wei-Jou Chen 
Some support for Chinese(BIG5) characters.
• Wei He 
A lot of functionality for the Chinese(GBK) character set.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Contributors to MySQL

• Jan Pazdziora 
Czech sorting order.
• Zeev Suraski 
FROM_UNIXTIME() time formatting, ENCRYPT() functions, and bison advisor. Active mailing list
member.
• Luuk de Boer 
Ported (and extended) the benchmark suite to DBI/DBD. Have been of great help with crash-me
and running benchmarks. Some new date functions. The mysql_setpermission script.
• Alexis Mikhailov 
User-defined functions (UDFs); CREATE FUNCTION and DROP FUNCTION.
• Andreas F. Bobak 
The AGGREGATE extension to user-defined functions.
• Ross Wakelin 
Help to set up InstallShield for MySQL-Win32.
• Jethro Wright III 
The libmysql.dll library.
• James Pereria 
Mysqlmanager, a Win32 GUI tool for administering MySQL Servers.
• Curt Sampson 
Porting of MIT-pthreads to NetBSD/Alpha and NetBSD 1.3/i386.
• Martin Ramsch 
Examples in the MySQL Tutorial.
• Steve Harvey
For making mysqlaccess more secure.
• Konark IA-64 Centre of Persistent Systems Private Limited
Help with the Win64 port of the MySQL server.
• Albert Chin-A-Young.
Configure updates for Tru64, large file support and better TCP wrappers support.
• John Birrell
Emulation of pthread_mutex() for OS/2.
• Benjamin Pflugmann
Extended MERGE tables to handle INSERTS. Active member on the MySQL mailing lists.
• Jocelyn Fournier
Excellent spotting and reporting innumerable bugs (especially in the MySQL 4.1 subquery code).

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Contributors to MySQL

• Marc Liyanage
Maintaining the OS X packages and providing invaluable feedback on how to create OS X packages.
• Robert Rutherford
Providing invaluable information and feedback about the QNX port.
• Previous developers of NDB Cluster
Lots of people were involved in various ways summer students, master thesis students, employees.
In total more than 100 people so too many to mention here. Notable name is Ataullah Dabaghi who
up until 1999 contributed around a third of the code base. A special thanks also to developers of
the AXE system which provided much of the architectural foundations for NDB Cluster with blocks,
signals and crash tracing functionality. Also credit should be given to those who believed in the ideas
enough to allocate of their budgets for its development from 1992 to present time.
• Google Inc.
We wish to recognize Google Inc. for contributions to the MySQL distribution: Mark Callaghan's SMP
Performance patches and other patches.
Other contributors, bugfinders, and testers: James H. Thompson, Maurizio Menghini, Wojciech
Tryc, Luca Berra, Zarko Mocnik, Wim Bonis, Elmar Haneke, ,
, , Ted Deppner ,
Mike Simons, Jaakko Hyvatti.
And lots of bug report/patches from the folks on the mailing list.
A big tribute goes to those that help us answer questions on the MySQL mailing lists:
• Daniel Koch 
Irix setup.
• Luuk de Boer 
Benchmark questions.
• Tim Sailer 
DBD::mysql questions.
• Boyd Lynn Gerber 
SCO-related questions.
• Richard Mehalick 
xmysql-related questions and basic installation questions.
• Zeev Suraski 
Apache module configuration questions (log & auth), PHP-related questions, SQL syntax-related
questions and other general questions.
• Francesc Guasch 
General questions.
• Jonathan J Smith 
Questions pertaining to OS-specifics with Linux, SQL syntax, and other things that might need some
work.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Documenters and translators

• David Sklar 
Using MySQL from PHP and Perl.
• Alistair MacDonald 
Is flexible and can handle Linux and perhaps HP-UX.
• John Lyon 
Questions about installing MySQL on Linux systems, using either .rpm files or compiling from
source.
• Lorvid Ltd. 
Simple billing/license/support/copyright issues.
• Patrick Sherrill 
ODBC and VisualC++ interface questions.
• Randy Harmon 
DBD, Linux, some SQL syntax questions.

1.9.2 Documenters and translators
The following people have helped us with writing the MySQL documentation and translating the
documentation or error messages in MySQL.
• Paul DuBois
Ongoing help with making this manual correct and understandable. That includes rewriting Monty's
and David's attempts at English into English as other people know it.
• Kim Aldale
Helped to rewrite Monty's and David's early attempts at English into English.
• Michael J. Miller Jr. 
For the first MySQL manual. And a lot of spelling/language fixes for the FAQ (that turned into the
MySQL manual a long time ago).
• Yan Cailin
First translator of the MySQL Reference Manual into simplified Chinese in early 2000 on which the
Big5 and HK coded versions were based.
• Jay Flaherty 
Big parts of the Perl DBI/DBD section in the manual.
• Paul Southworth , Ray Loyzaga 
Proof-reading of the Reference Manual.
• Therrien Gilbert , Jean-Marc Pouyot 
French error messages.
• Petr Snajdr, 
Czech error messages.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Packages that support MySQL

• Jaroslaw Lewandowski 
Polish error messages.
• Miguel Angel Fernandez Roiz
Spanish error messages.
• Roy-Magne Mo 
Norwegian error messages and testing of MySQL 3.21.xx.
• Timur I. Bakeyev 
Russian error messages.
•  & Filippo Grassilli 
Italian error messages.
• Dirk Munzinger 
German error messages.
• Billik Stefan 
Slovak error messages.
• Stefan Saroiu 
Romanian error messages.
• Peter Feher
Hungarian error messages.
• Roberto M. Serqueira
Portuguese error messages.
• Carsten H. Pedersen
Danish error messages.
• Arjen Lentz
Dutch error messages, completing earlier partial translation (also work on consistency and spelling).

1.9.3 Packages that support MySQL
The following is a list of creators/maintainers of some of the most important API/packages/applications
that a lot of people use with MySQL.
We cannot list every possible package here because the list would then be way to hard to maintain. For
other packages, please refer to the software portal at http://solutions.mysql.com/software/.
• Tim Bunce, Alligator Descartes
For the DBD (Perl) interface.
• Andreas Koenig 
For the Perl interface for MySQL Server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Tools that were used to create MySQL

• Jochen Wiedmann 
For maintaining the Perl DBD::mysql module.
• Eugene Chan 
For porting PHP for MySQL Server.
• Georg Richter
MySQL 4.1 testing and bug hunting. New PHP 5.0 mysqli extension (API) for use with MySQL 4.1
and up.
• Giovanni Maruzzelli 
For porting iODBC (Unix ODBC).
• Xavier Leroy 
The author of LinuxThreads (used by the MySQL Server on Linux).

1.9.4 Tools that were used to create MySQL
The following is a list of some of the tools we have used to create MySQL. We use this to express our
thanks to those that has created them as without these we could not have made MySQL what it is
today.
• Free Software Foundation
From whom we got an excellent compiler (gcc), an excellent debugger (gdb and the libc library
(from which we have borrowed strto.c to get some code working in Linux).
• Free Software Foundation & The XEmacs development team
For a really great editor/environment.
• Julian Seward
Author of valgrind, an excellent memory checker tool that has helped us find a lot of otherwise
hard to find bugs in MySQL.
• Dorothea Lütkehaus and Andreas Zeller
For DDD (The Data Display Debugger) which is an excellent graphical front end to gdb).

1.9.5 Supporters of MySQL
Although Oracle Corporation and/or its affiliates own all copyrights in the MySQL server and
the MySQL manual, we wish to recognize the following companies, which helped us finance the
development of the MySQL server, such as by paying us for developing a new feature or giving us
hardware for development of the MySQL server.
• VA Linux / Andover.net
Funded replication.
• NuSphere
Editing of the MySQL manual.
• Stork Design studio
The MySQL Web site in use between 1998-2000.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Supporters of MySQL

• Intel
Contributed to development on Windows and Linux platforms.
• Compaq
Contributed to Development on Linux/Alpha.
• SWSoft
Development on the embedded mysqld version.
• FutureQuest
The --skip-show-database option.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 2 Installing and Upgrading MySQL
Table of Contents
2.1 MySQL Installation Overview ................................................................................................. 40
2.2 Determining Your Current MySQL Version ............................................................................. 40
2.3 Notes for MySQL Enterprise Server ....................................................................................... 41
2.3.1 Enterprise Server Distribution Types ........................................................................... 42
2.3.2 Upgrading MySQL Enterprise Server ........................................................................... 42
2.4 Notes for MySQL Community Server ..................................................................................... 42
2.4.1 Overview of MySQL Community Server Installation ...................................................... 42
2.4.2 Choosing Which MySQL Distribution to Install ............................................................. 43
2.5 How to Get MySQL ............................................................................................................... 46
2.6 Verifying Package Integrity Using MD5 Checksums or GnuPG ................................................ 47
2.6.1 Verifying the MD5 Checksum ...................................................................................... 47
2.6.2 Signature Checking Using GnuPG .............................................................................. 47
2.6.3 Signature Checking Using Gpg4win for Windows ......................................................... 50
2.6.4 Signature Checking Using RPM .................................................................................. 55
2.7 Installation Layouts ............................................................................................................... 56
2.8 Compiler-Specific Build Characteristics .................................................................................. 57
2.9 Standard MySQL Installation from a Binary Distribution ........................................................... 58
2.10 Installing MySQL on Microsoft Windows ............................................................................... 58
2.10.1 Choosing An Installation Package ............................................................................. 59
2.10.2 Installing MySQL on Microsoft Windows Using an MSI Package ................................. 60
2.10.3 MySQL Server Instance Configuration Wizard ............................................................ 65
2.10.4 Installing MySQL on Microsoft Windows Using a noinstall Zip Archive ......................... 77
2.10.5 Troubleshooting a MySQL Installation Under Windows ............................................... 84
2.10.6 Windows Postinstallation Procedures ........................................................................ 86
2.10.7 Upgrading MySQL on Windows ................................................................................ 88
2.10.8 Installing MySQL from Source on Windows ............................................................... 89
2.11 Installing MySQL on OS X .................................................................................................. 94
2.12 Installing MySQL on Linux Using RPM Packages ................................................................. 96
2.13 Installing MySQL on Solaris ............................................................................................... 100
2.14 Installing MySQL on i5/OS ................................................................................................. 100
2.15 Installing MySQL on NetWare ............................................................................................ 104
2.16 Installing MySQL on Unix/Linux Using Generic Binaries ...................................................... 106
2.17 Installing MySQL from Source ........................................................................................... 108
2.17.1 Installing MySQL Using a Standard Source Distribution ............................................ 109
2.17.2 Installing MySQL Using a Development Source Tree ................................................ 112
2.17.3 MySQL Source-Configuration Options ...................................................................... 115
2.17.4 Dealing with Problems Compiling MySQL ................................................................ 123
2.17.5 Compiling and Linking an Optimized mysqld Server ................................................. 125
2.18 Postinstallation Setup and Testing ..................................................................................... 126
2.18.1 Initializing the Data Directory ................................................................................... 127
2.18.2 Starting the Server ................................................................................................. 130
2.18.3 Testing the Server .................................................................................................. 134
2.18.4 Securing the Initial MySQL Accounts ....................................................................... 136
2.18.5 Starting and Stopping MySQL Automatically ............................................................ 140
2.19 Upgrading or Downgrading MySQL .................................................................................... 141
2.19.1 Upgrading MySQL .................................................................................................. 141
2.19.2 Downgrading MySQL .............................................................................................. 153
2.19.3 Checking Whether Tables or Indexes Must Be Rebuilt .............................................. 157
2.19.4 Rebuilding or Repairing Tables or Indexes ............................................................... 159
2.19.5 Copying MySQL Databases to Another Machine ...................................................... 160
2.20 Operating System-Specific Notes ....................................................................................... 161
2.20.1 Linux Notes ............................................................................................................ 161
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Installation Overview

2.20.2 OS X Notes ...........................................................................................................
2.20.3 Solaris Notes ..........................................................................................................
2.20.4 BSD Notes .............................................................................................................
2.20.5 Other Unix Notes ....................................................................................................
2.20.6 OS/2 Notes ............................................................................................................
2.21 Environment Variables .......................................................................................................
2.22 Perl Installation Notes ........................................................................................................
2.22.1 Installing Perl on Unix .............................................................................................
2.22.2 Installing ActiveState Perl on Windows ....................................................................
2.22.3 Problems Using the Perl DBI/DBD Interface .............................................................

168
168
172
175
191
191
192
193
194
194

End of Product Lifecycle. Active development for MySQL Database Server version 5.0 has ended.
Oracle offers various support offerings which may be of interest. For details and more information,
see the MySQL section of the Lifetime Support Policy for Oracle Technology Products (http://
www.oracle.com/us/support/lifetime-support/index.html). Please consider upgrading to a recent
version.

2.1 MySQL Installation Overview
This chapter describes how to obtain and install MySQL. You can choose to install MySQL Enterprise
or MySQL Community Server:
• MySQL Enterprise is Oracle Corporation's commercial offering for modern enterprise businesses. It
includes MySQL Enterprise Server and the services provided by MySQL Network. To install MySQL
Enterprise, see Section 2.3, “Notes for MySQL Enterprise Server”.
• MySQL Community Server is for users who are comfortable configuring and administering MySQL
by themselves. To install MySQL Community Server, see Section 2.4, “Notes for MySQL Community
Server”.
If you plan to upgrade an existing version of MySQL to a newer version rather than install MySQL for
the first time, see Section 2.19.1, “Upgrading MySQL”, for information about upgrade procedures and
about issues that you should consider before upgrading.
If you are interested in migrating to MySQL from another database system, you may wish to read
Section A.8, “MySQL 5.0 FAQ: Migration”, which contains answers to some common questions
concerning migration issues.

2.2 Determining Your Current MySQL Version
To determine the version and release of your currently installed MySQL installation, there are a number
of options.
• Using a command client (mysql), the server version of the MySQL server to which you are
connected is shown once you are connected. The server version information includes community or
enterprise accordingly.
For example, here is the output from a MySQL Community Server edition installed on Linux:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 5.0.27-standard MySQL Community Edition - Standard (GPL)
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>

This is an example of the output from MySQL Enterprise Server on Windows:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Notes for MySQL Enterprise Server

Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 2
Server version: 5.0.28-enterprise-gpl-nt MySQL Enterprise Server (GPL)
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

• You may also determine the version information using the version variables. Both the version and
version_comment variables contain version information for the server to which you are connected.
Use the SHOW VARIABLES statement to obtain the information you want, as shown in this example:
mysql> SHOW VARIABLES LIKE "%version%";
+-------------------------+------------------------------------------+
| Variable_name
| Value
|
+-------------------------+------------------------------------------+
| protocol_version
| 10
|
| version
| 5.0.27-standard
|
| version_comment
| MySQL Community Edition - Standard (GPL) |
| version_compile_machine | i686
|
| version_compile_os
| pc-linux-gnu
|
+-------------------------+------------------------------------------+
5 rows in set (0.04 sec)

You can also obtain server version information in the mysql client using the SELECT VERSION()
statement. In addition, MySQL Workbench also shows the server version in the Server Status tab.
However, in both of these cases, only the value of version is shown.
• The STATUS command displays the version as well as version comment information. For example:
mysql> STATUS;
-------------./client/mysql

Ver 14.12 Distrib 5.0.29, for pc-linux-gnu (i686) using readline 5.0

Connection id:
Current database:
Current user:
SSL:
Current pager:
Using outfile:
Using delimiter:
Server version:
Protocol version:
Connection:
Server characterset:
Db
characterset:
Client characterset:
Conn. characterset:
UNIX socket:
Uptime:

8
mc@localhost
Not in use
/usr/bin/less
''
;
5.0.27-standard MySQL Community Edition - Standard (GPL)
10
Localhost via UNIX socket
latin1
latin1
latin1
latin1
/tmp/mysql.sock
1 day 3 hours 58 min 43 sec

Threads: 2 Questions: 17
--------------

Slow queries: 0

Opens: 11

Flush tables: 1

Open tables: 6

Queries per s

2.3 Notes for MySQL Enterprise Server
To obtain MySQL Enterprise, visit http://enterprise.mysql.com if you're a customer. Otherwise, visit
http://www.mysql.com/products/enterprise/. The platforms that are officially supported for MySQL
Enterprise are listed at http://www.mysql.com/support/supportedplatforms/enterprise.html.
MySQL Enterprise Server is available for download in the form of Quarterly Service Pack (QSP) or
Monthly Rapid Update (MRU) binary releases.
To install MySQL Enterprise Server, you should use the latest available Quarterly Service Pack (QSP).
This includes an accumulation of the bug fixes provided in all predecessor QSP and MRU releases.
MRU releases are provided on a monthly basis and represent the most current Enterprise Server bug
fixes. Each MRU is an accumulation of the bug fixes included in its predecessor. Customers should
standardize on the latest MRU release only if it includes a needed bug fix.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Enterprise Server Distribution Types

2.3.1 Enterprise Server Distribution Types
Enterprise Server releases will be created for the following packages from the MySQL 5.0 tree:
• mysql-enterprise: Released under a commercial license and includes the following storage
engines: MyISAM, MEMORY, MERGE, InnoDB, ARCHIVE, BLACKHOLE, EXAMPLE, FEDERATED.
• mysql-enterprise-gpl: Same as mysql-enterprise, but released under the GPL.
• mysql-cluster: mysql-enterprise plus MySQL Cluster (NDB).
• mysql-classic: Released under a commercial license, does not include InnoDB.
• mysql-community: Same as mysql-enterprise-gpl, but available for the community, and
released every 6 months.
To satisfy different user requirements, we provide several servers. mysqld is an optimized server
that is a smaller, faster binary. mysqld-debug is compiled with debugging support but is otherwise
configured identically to the nondebug server.
Each of these servers is compiled from the same source distribution, though with different configuration
options. All native MySQL clients can connect to servers from either MySQL version.

2.3.2 Upgrading MySQL Enterprise Server
When upgrading to MySQL Enterprise from Community Server you need only follow the installation
process to install and upgrade the packages to the latest version provided by MySQL Enterprise. You
will also need to install the latest MySQL Enterprise Service Pack and any outstanding MySQL Hot-fix
packs.
Be aware, however, that you must take into account any of the changes when moving between major
releases. You should also check the Release Notes for details on major changes between revisions of
MySQL Enterprise Server.
You should also review the notes and advice contained within Section 2.19.1, “Upgrading MySQL”.

2.4 Notes for MySQL Community Server
2.4.1 Overview of MySQL Community Server Installation
1. Determine whether MySQL runs and is supported on your platform.
Not all platforms are
equally suitable for running MySQL, and not all platforms on which MySQL is known to run are
officially supported by Oracle Corporation.
2. Choose which distribution to install.
Several versions of MySQL are available, and most are
available in multiple distribution formats. You can choose from prepackaged distributions containing
binary (precompiled) programs or source code. When in doubt, use a binary distribution. We
also provide public access to our current source trees for those who want to see our most recent
developments and to help us test new code. To determine which version and type of distribution
you should use, see Section 2.4.2, “Choosing Which MySQL Distribution to Install”.
3. Download the distribution that you want to install.
For download instructions, see
Section 2.5, “How to Get MySQL”. To verify the integrity of the distribution, use the instructions in
Section 2.6, “Verifying Package Integrity Using MD5 Checksums or GnuPG”.
4. Install the distribution.
To install MySQL from a binary distribution, use the instructions
in Section 2.9, “Standard MySQL Installation from a Binary Distribution”. To install MySQL
from a source distribution or from the current development source tree, use the instructions in
Section 2.17, “Installing MySQL from Source”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Choosing Which MySQL Distribution to Install

If you encounter installation difficulties, see Section 2.20, “Operating System-Specific Notes”, for
information on solving problems for particular platforms.
5. Perform any necessary postinstallation setup.
After installing MySQL, read Section 2.18,
“Postinstallation Setup and Testing”, which 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 information in this section applies
whether you install MySQL using a binary or source distribution.
6. Perform setup for running benchmarks (optional).
If you want to use the MySQL benchmark
scripts, Perl support for MySQL must be available. See Section 2.22, “Perl Installation Notes”, for
more information.
The sections immediately following this one contain necessary information about choosing,
downloading, and verifying your distribution. The instructions in later sections of the chapter describe
how to install the distribution that you choose. For binary distributions, see the instructions in
Section 2.9, “Standard MySQL Installation from a Binary Distribution”. To build MySQL from source,
use the instructions in Section 2.17, “Installing MySQL from Source”.

2.4.2 Choosing Which MySQL Distribution to Install
MySQL is available on a number of operating systems and platforms. For information about those
platforms that are officially supported, see http://www.mysql.com/support/supportedplatforms/
database.html on the MySQL Web site.
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.4.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.

Production Releases
• MySQL 5.7: Latest General Availability (Production) release
• MySQL 5.6: Previous General Availability (Production) release
• MySQL 5.5: Older General Availability (Production) release
• MySQL 5.1, 5.0: Older Production releases for which active development has ended
MySQL 4.1, 4.0, and 3.23 are old releases that are no longer supported.
See http://www.mysql.com/about/legal/lifecycle/ for information about support policies and schedules.
For supported platform information, see http://www.mysql.com/support/supportedplatforms/
database.html.
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, use the most recent General Availability series listed in the
preceding descriptions. All MySQL releases, even those from development series, are checked with
the MySQL benchmarks and an extensive test suite before being issued.
If you are running an older system and want to upgrade, but do not want to take the chance of having
a nonseamless upgrade, you should upgrade to the latest version in the same release series you are

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Choosing Which MySQL Distribution to Install

using (where only the last part of the version number is newer than yours). We have tried to fix only
fatal bugs and make only small, relatively “safe” changes to that version.
If you want to use new features not present in the production release series, you can use a version
from a development series. Be aware that development releases are not as stable as production
releases.
We do not use a complete code freeze because this prevents us from making bugfixes and other fixes
that must be done. We may add small things that should not affect anything that currently works in a
production release. Naturally, relevant bugfixes from an earlier series propagate to later series.
If you want to use the very latest sources containing all current patches and bugfixes, you can use one
of our source code repositories (see Section 2.17.2, “Installing MySQL Using a Development Source
Tree”). These are not “releases” as such, but are available as previews of the code on which future
releases are to be based.
The naming scheme in MySQL 5.0 uses release names that consist of three numbers and a suffix; for
example, mysql-5.0.14-rc. The numbers within the release name are interpreted as follows:
• The first number (5) is the major version and describes the file format. All MySQL 5 releases have
the same file format.
• The second number (0) is the release level. Taken together, the major version and release level
constitute the release series number.
• The third number (14) 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 that 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 is for preview purposes only. Known bugs should be documented
in the Release Notes. Most alpha releases implement new commands and extensions. Active
development that may involve major code changes can occur in an alpha release. However, we do
conduct testing before issuing a release.
• beta indicates that the release is appropriate for use with new development. Within beta releases,
the features and compatibility should remain consistent. However, beta releases may contain
numerous and major unaddressed bugs.
No APIs, externally visible structures, or columns for SQL statements will change during future beta,
release candidate, or production releases.
• rc indicates a Release Candidate. Release candidates are believed to be stable, having passed all of
MySQL's internal testing, and with all known fatal runtime bugs fixed. However, the release has not
been in widespread use long enough to know for sure that all bugs have been identified. Only minor
fixes are added. (A release candidate is what formerly was known as a gamma release.)
• If there is no suffix, it indicates that the release is a General Availability (GA) or Production release.
GA releases are stable, having successfully passed through all earlier release stages and are
believed to be reliable, free of serious bugs, and suitable for use in production systems. Only critical
bugfixes are applied to the release.
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.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Choosing Which MySQL Distribution to Install

All releases have been tested at least with these tools:
• An internal test suite.
The mysql-test directory contains an extensive set of test cases.
We run these tests for every server binary. See Section 21.1.2, “The MySQL Test Suite”, for more
information about this test suite.
• The MySQL benchmark suite.
This suite runs a range of common queries. It is also a
test to determine whether the latest batch of optimizations actually made the code faster. See
Section 8.13.2, “The MySQL Benchmark Suite”.
We also perform additional integration and nonfunctional testing of the latest MySQL version in our
internal production environment. Integration testing is done with different connectors, storage engines,
replication modes, backup, partitioning, stored programs, and so forth in various combinations.
Additional nonfunctional testing is done in areas of performance, concurrency, stress, high volume,
upgrade and downgrade.

2.4.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 packages for Linux, DMG packages for OS X, and PKG packages for Solaris. Distributions are
also available in more generic formats such as Zip archives or compressed tar files.
Reasons to choose a binary distribution include the following:
• Binary distributions generally are easier to install than source distributions.
• To satisfy different user requirements, we provide several servers in binary distributions. mysqld
is an optimized server that is a smaller, faster binary. mysqld-debug is compiled with debugging
support.
Each of these servers is compiled from the same source distribution, though with different
configuration options. All native MySQL clients can connect to servers from either MySQL version.
Under some circumstances, you may be better off installing MySQL from a source distribution:
• You want to install MySQL at some explicit location. The standard binary distributions are ready
to run at any installation location, but you might require even more flexibility to place MySQL
components where you want.
• You want to configure mysqld to ensure that features are available that might not be included in the
standard binary distributions. Here is a list of the most common extra options that you may want to
use to ensure feature availability:
• --with-berkeley-db (not available on all platforms)
• --with-libwrap
• --with-named-z-libs (this is done for some of the binaries)
• --with-debug[=full]
For additional information, see Section 2.17.3, “MySQL Source-Configuration Options”.
• You want to configure mysqld without some features that are included in the standard binary
distributions. For example, distributions normally are compiled with support for all character sets. If
you want a smaller MySQL server, you can recompile it with support for only the character sets you
need.
• You want to use the latest sources from one of the Bazaar 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
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Get MySQL

bugfix is committed to the source repository and you can access it there. The bugfix does not appear
in a release until a release actually is issued.
• You want to read (or modify) the C and C++ code that makes up MySQL. For this purpose, you
should get a source distribution, because the source code is always the ultimate manual.
• Source distributions contain more tests and examples than binary distributions.

2.4.2.3 How and When Updates Are Released
MySQL is evolving quite rapidly and we want to share new developments with other MySQL users. We
try to produce a new release whenever we have new and useful features that others also seem to have
a need for.
We also try to help users who request features that are easy to implement. We take note of what our
licensed users want, and we especially take note of what our support customers want and try to help
them in this regard.
No one is required to download a new release. The Release Notes help you determine whether the
new release has something you really want.
We use the following policy when updating MySQL:
• Enterprise Server releases are meant to appear every 18 months, supplemented by quarterly service
packs and monthly rapid updates. Community Server releases are meant to appear 2−3 times per
year.
• 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.
• 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 noncritical but
annoying bugs. The fixes are available in source form immediately from our public Bazaar
repositories, and are included in the next release.
• If by any chance a security vulnerability or critical bug is found in a release, our policy is to fix it in a
new release as soon as possible. (We would like other companies to do this, too!)

2.4.2.4 MySQL Binaries Compiled by Oracle Corporation
Oracle Corporation provides a set of binary distributions of MySQL. In addition to binaries provided in
platform-specific package formats, we offer binary distributions for a number of platforms in the form of
compressed tar files (.tar.gz files). See Section 2.9, “Standard MySQL Installation from a Binary
Distribution”. For Windows distributions, see Section 2.10, “Installing MySQL on Microsoft Windows”.
If you want to compile MySQL from a source distribution, see Section 2.17, “Installing MySQL from
Source”. To compile a debug version of MySQL, see Section 2.17.3, “MySQL Source-Configuration
Options” for options that enable debugging.

2.5 How to Get MySQL
Check our downloads page at http://dev.mysql.com/downloads/ for information about the current
version of MySQL and for downloading instructions. For a complete up-to-date list of MySQL download
mirror sites, see http://dev.mysql.com/downloads/mirrors.html. You can also find information there
about becoming a MySQL mirror site and how to report a bad or out-of-date mirror.
To obtain the latest development source, see Section 2.17.2, “Installing MySQL Using a Development
Source Tree”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Verifying Package Integrity Using MD5 Checksums or GnuPG

2.6 Verifying Package Integrity Using MD5 Checksums or GnuPG
After downloading the MySQL package that suits your needs and before attempting to install it, make
sure that it is intact and has not been tampered with. There are 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.

2.6.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 against the package that you downloaded. The correct MD5 checksum is listed on the
downloads page for each MySQL product, and you will compare it against the MD5 checksum of the
file (product) that you download.
Each operating system and setup offers its own version of tools for checking the MD5 checksum.
Typically the command is named md5sum, or it may be named md5, and some operating systems 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 also download the source code from http://www.gnu.org/software/textutils/.
If you have OpenSSL installed, you can use the command openssl md5 package_name instead.
A Windows implementation of the md5 command line utility is available from http://www.fourmilab.ch/
md5/. winMd5Sum is a graphical MD5 checking tool that can be obtained from http://www.nullriver.com/
index/products/winmd5sum. Our Microsoft Windows examples will assume the name md5.exe.
Linux and Microsoft Windows examples:
shell> md5sum mysql-standard-5.0.96-linux-i686.tar.gz
aaab65abbec64d5e907dcd41b8699945 mysql-standard-5.0.96-linux-i686.tar.gz

shell> md5.exe mysql-installer-community-5.0.96.msi
aaab65abbec64d5e907dcd41b8699945 mysql-installer-community-5.0.96.msi

You should verify that the resulting checksum (the string of hexadecimal digits) matches the one
displayed on the download page immediately below the respective package.
Note
Make sure to verify the checksum of the archive file (for example, the .zip,
.tar.gz, or .msi file) and not of the files that are contained inside of the
archive. In other words, verify the file before extracting its contents.

2.6.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.
We sign MySQL downloadable packages with GnuPG (GNU Privacy Guard). GnuPG is an Open
Source alternative to the well-known Pretty Good Privacy (PGP) by Phil Zimmermann. See http://
www.gnupg.org/ for more information about GnuPG and how to obtain and install it on your system.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using GnuPG

Most Linux distributions ship with GnuPG installed by default. For more information about GnuPG, see
http://www.openpgp.org/.
To verify the signature for a specific package, you first need to obtain a copy of our public GPG build
key, which you can download from http://pgp.mit.edu/. The key that you want to obtain is named
mysql-build@oss.oracle.com. Alternatively, you can cut and paste the key directly from the
following text:
-----BEGIN PGP PUBLIC KEY BLOCK----Version: GnuPG v1.4.9 (SunOS)
mQGiBD4+owwRBAC14GIfUfCyEDSIePvEW3SAFUdJBtoQHH/nJKZyQT7h9bPlUWC3
RODjQReyCITRrdwyrKUGku2FmeVGwn2u2WmDMNABLnpprWPkBdCk96+OmSLN9brZ
fw2vOUgCmYv2hW0hyDHuvYlQA/BThQoADgj8AW6/0Lo7V1W9/8VuHP0gQwCgvzV3
BqOxRznNCRCRxAuAuVztHRcEAJooQK1+iSiunZMYD1WufeXfshc57S/+yeJkegNW
hxwR9pRWVArNYJdDRT+rf2RUe3vpquKNQU/hnEIUHJRQqYHo8gTxvxXNQc7fJYLV
K2HtkrPbP72vwsEKMYhhr0eKCbtLGfls9krjJ6sBgACyP/Vb7hiPwxh6rDZ7ITnE
kYpXBACmWpP8NJTkamEnPCia2ZoOHODANwpUkP43I7jsDmgtobZX9qnrAXw+uNDI
QJEXM6FSbi0LLtZciNlYsafwAPEOMDKpMqAK6IyisNtPvaLd8lH0bPAnWqcyefep
rv0sxxqUEMcM3o7wwgfN83POkDasDbs3pjwPhxvhz6//62zQJ7Q2TXlTUUwgUmVs
ZWFzZSBFbmdpbmVlcmluZyA8bXlzcWwtYnVpbGRAb3NzLm9yYWNsZS5jb20+iGkE
ExECACkCGyMGCwkIBwMCBBUCCAMEFgIDAQIeAQIXgAIZAQUCUwHUZgUJGmbLywAK
CRCMcY07UHLh9V+DAKCjS1gGwgVI/eut+5L+l2v3ybl+ZgCcD7ZoA341HtoroV3U
6xRD09fUgeq0O015U1FMIFBhY2thZ2Ugc2lnbmluZyBrZXkgKHd3dy5teXNxbC5j
b20pIDxidWlsZEBteXNxbC5jb20+iG8EMBECAC8FAk53Pa0oHSBidWlsZEBteXNx
bC5jb20gd2lsbCBzdG9wIHdvcmtpbmcgc29vbgAKCRCMcY07UHLh9bU9AJ9xDK0o
xJFL9vTl9OSZC4lX0K9AzwCcCrS9cnJyz79eaRjL0s2r/CcljdyIZQQTEQIAHQUC
R6yUtAUJDTBYqAULBwoDBAMVAwIDFgIBAheAABIJEIxxjTtQcuH1B2VHUEcAAQGu
kgCffz4GUEjzXkOi71VcwgCxASTgbe0An34LPr1j9fCbrXWXO14msIADfb5piEwE
ExECAAwFAj4+o9EFgwlmALsACgkQSVDhKrJykfIk4QCfWbEeKN+3TRspe+5xKj+k
QJSammIAnjUz0xFWPlVx0f8o38qNG1bq0cU9iEwEExECAAwFAj5CggMFgwliIokA
CgkQtvXNTca6JD+WkQCgiGmnoGjMojynp5ppvMXkyUkfnykAoK79E6h8rwkSDZou
iz7nMRisH8uyiEYEEBECAAYFAj+s468ACgkQr8UjSHiDdA/2lgCg21IhIMMABTYd
p/IBiUsP/JQLiEoAnRzMywEtujQz/E9ono7H1DkebDa4iEYEEBECAAYFAj+0Q3cA
CgkQhZavqzBzTmbGwwCdFqD1frViC7WRt8GKoOS7hzNN32kAnirlbwpnT7a6NOsQ
83nk11a2dePhiEYEEBECAAYFAkNbs+oACgkQi9gubzC5S1x/dACdELKoXQKkwJN0
gZztsM7kjsIgyFMAnRRMbHQ7V39XC90OIpaPjk3a01tgiEYEExECAAYFAkTxMyYA
CgkQ9knE9GCTUwwKcQCgibak/SwhxWH1ijRhgYCo5GtM4vcAnAhtzL57wcw1Kg1X
m7nVGetUqJ7fiEwEEBECAAwFAkGBywEFgwYi2YsACgkQGFnQH2d7oexCjQCcD8sJ
NDc/mS8m8OGDUOx9VMWcnGkAnj1YWOD+Qhxo3mI/Ul9oEAhNkjcfiEwEEBECAAwF
AkGByzQFgwYi2VgACgkQgcL36+ITtpIiIwCdFVNVUB8xe8mFXoPm4d9Z54PTjpMA
niSPA/ZsfJ3oOMLKar4F0QPPrdrGiEwEEBECAAwFAkGBy2IFgwYi2SoACgkQa3Ds
2V3D9HMJqgCbBYzr5GPXOXgP88jKzmdbjweqXeEAnRss4G2G/3qD7uhTL1SPT1SH
jWUXiEwEEBECAAwFAkHQkyQFgwXUEWgACgkQfSXKCsEpp8JiVQCghvWvkPqowsw8
w7WSseTcw1tflvkAni+vLHl/DqIly0LkZYn5jzK1dpvfiEwEEBECAAwFAkIrW7oF
gwV5SNIACgkQ5hukiRXruavzEwCgkzL5QkLSypcw9LGHcFSx1ya0VL4An35nXkum
g6cCJ1NP8r2I4NcZWIrqiEwEEhECAAwFAkAqWToFgwd6S1IACgkQPKEfNJT6+GEm
XACcD+A53A5OGM7w750W11ukq4iZ9ckAnRMvndAqn3YTOxxlLPj2UPZiSgSqiEwE
EhECAAwFAkA9+roFgwdmqdIACgkQ8tdcY+OcZZyy3wCgtDcwlaq20w0cNuXFLLNe
EUaFFTwAni6RHN80moSVAdDTRkzZacJU3M5QiEwEEhECAAwFAkEOCoQFgwaWmggA
CgkQOcor9D1qil/83QCeITZ9wIo7XAMjC6y4ZWUL4m+edZsAoMOhRIRi42fmrNFu
vNZbnMGej81viEwEEhECAAwFAkKApTQFgwUj/1gACgkQBA3AhXyDn6jjJACcD1A4
UtXk84J13JQyoH9+dy24714Aniwlsso/9ndICJOkqs2j5dlHFq6oiEwEExECAAwF
Aj5NTYQFgwlXVwgACgkQLbt2v63UyTMFDACglT5G5NVKf5Mj65bFSlPzb92zk2QA
n1uc2h19/IwwrsbIyK/9POJ+JMP7iEwEExECAAwFAkHXgHYFgwXNJBYACgkQZu/b
yM2C/T4/vACfXe67xiSHB80wkmFZ2krb+oz/gBAAnjR2ucpbaonkQQgnC3GnBqmC
vNaJiEwEExECAAwFAkIYgQ4FgwWMI34ACgkQdsEDHKIxbqGg7gCfQi2HcrHn+yLF
uNlH1oSOh48ZM0oAn3hKV0uIRJphonHaUYiUP1ttWgdBiGUEExECAB0FCwcKAwQD
FQMCAxYCAQIXgAUCS3AvygUJEPPzpwASB2VHUEcAAQEJEIxxjTtQcuH1sNsAniYp
YBGqy/HhMnw3WE8kXahOOR5KAJ4xUmWPGYP4l3hKxyNK9OAUbpDVYIh7BDARAgA7
BQJCdzX1NB0AT29wcy4uLiBzaG91bGQgaGF2ZSBiZWVuIGxvY2FsISBJJ20gKnNv
KiBzdHVwaWQuLi4ACgkQOcor9D1qil/vRwCdFo08f66oKLiuEAqzlf9iDlPozEEA
n2EgvCYLCCHjfGosrkrU3WK5NFVgiI8EMBECAE8FAkVvAL9IHQBTaG91bGQgaGF2
ZSBiZWVuIGEgbG9jYWwgc2lnbmF0dXJlLCBvciBzb21ldGhpbmcgLSBXVEYgd2Fz
IEkgdGhpbmtpbmc/AAoJEDnKK/Q9aopfoPsAn3BVqKOalJeF0xPSvLR90PsRlnmG
AJ44oisY7Tl3NJbPgZal8W32fbqgbIkCIgQQAQIADAUCQYHLhQWDBiLZBwAKCRCq
4+bOZqFEaKgvEACCErnaHGyUYa0wETjj6DLEXsqeOiXad4i9aBQxnD35GUgcFofC
/nCY4XcnCMMEnmdQ9ofUuU3OBJ6BNJIbEusAabgLooebP/3KEaiCIiyhHYU5jarp
ZAh+Zopgs3Oc11mQ1tIaS69iJxrGTLodkAsAJAeEUwTPq9fHFFzC1eGBysoyFWg4
bIjz/zClI+qyTbFA5g6tRoiXTo8ko7QhY2AA5UGEg+83Hdb6akC04Z2QRErxKAqr

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using GnuPG

phHzj8XpjVOsQAdAi/qVKQeNKROlJ+iq6+YesmcWGfzeb87dGNweVFDJIGA0qY27
pTb2lExYjsRFN4Cb13NfodAbMTOxcAWZ7jAPCxAPlHUG++mHMrhQXEToZnBFE4nb
nC7vOBNgWdjUgXcpkUCkop4b17BFpR+k8ZtYLSS8p2LLz4uAeCcSm2/msJxT7rC/
FvoH8428oHincqs2ICo9zO/Ud4HmmO0O+SsZdVKIIjinGyOVWb4OOzkAlnnhEZ3o
6hAHcREIsBgPwEYVTj/9ZdC0AO44Nj9cU7awaqgtrnwwfr/o4V2gl8bLSkltZU27
/29HeuOeFGjlFe0YrDd/aRNsxbyb2O28H4sG1CVZmC5uK1iQBDiSyA7Q0bbdofCW
oQzm5twlpKWnY8Oe0ub9XP5p/sVfck4FceWFHwv+/PC9RzSl33lQ6vM2wIkCIgQT
AQIADAUCQp8KHAWDBQWacAAKCRDYwgoJWiRXzyE+D/9uc7z6fIsalfOYoLN60ajA
bQbI/uRKBFugyZ5RoaItusn9Z2rAtn61WrFhu4uCSJtFN1ny2RERg40f56pTghKr
D+YEt+Nze6+FKQ5AbGIdFsR/2bUk+ZZRSt83e14Lcb6ii/fJfzkoIox9ltkifQxq
Y7Tvk4noKu4oLSc8O1Wsfc/y0B9sYUUCmUfcnq58DEmGie9ovUslmyt5NPnveXxp
5UeaRc5Rqt9tK2B4A+7/cqENrdZJbAMSunt2+2fkYiRunAFPKPBdJBsY1sxeL/A9
aKe0viKEXQdAWqdNZKNCi8rd/oOP99/9lMbFudAbX6nL2DSb1OG2Z7NWEqgIAzjm
pwYYPCKeVz5Q8R+if9/fe5+STY/55OaI33fJ2H3v+U435VjYqbrerWe36xJItcJe
qUzW71fQtXi1CTEl3w2ch7VF5oj/QyjabLnAlHgSlkSi6p7By5C2MnbCHlCfPnIi
nPhFoRcRGPjJe9nFwGs+QblvS/Chzc2WX3s/2SWm4gEUKRX4zsAJ5ocyfa/vkxCk
SxK/erWlCPf/J1T70+i5waXDN/E3enSet/WL7h94pQKpjz8OdGL4JSBHuAVGA+a+
dknqnPF0KMKLhjrgV+L7O84FhbmAP7PXm3xmiMPriXf+el5fZZequQoIagf8rdRH
HhRJxQgI0HNknkaOqs8dtrkCDQQ+PqMdEAgA7+GJfxbMdY4wslPnjH9rF4N2qfWs
EN/lxaZoJYc3a6M02WCnHl6ahT2/tBK2w1QI4YFteR47gCvtgb6O1JHffOo2HfLm
RDRiRjd1DTCHqeyX7CHhcghj/dNRlW2Z0l5QFEcmV9U0Vhp3aFfWC4Ujfs3LU+hk
AWzE7zaD5cH9J7yv/6xuZVw411x0h4UqsTcWMu0iM1BzELqX1DY7LwoPEb/O9Rkb
f4fmLe11EzIaCa4PqARXQZc4dhSinMt6K3X4BrRsKTfozBu74F47D8Ilbf5vSYHb
uE5p/1oIDznkg/p8kW+3FxuWrycciqFTcNz215yyX39LXFnlLzKUb/F5GwADBQf+
Lwqqa8CGrRfsOAJxim63CHfty5mUc5rUSnTslGYEIOCR1BeQauyPZbPDsDD9MZ1Z
aSafanFvwFG6Llx9xkU7tzq+vKLoWkm4u5xf3vn55VjnSd1aQ9eQnUcXiL4cnBGo
TbOWI39EcyzgslzBdC++MPjcQTcA7p6JUVsP6oAB3FQWg54tuUo0Ec8bsM8b3Ev4
2LmuQT5NdKHGwHsXTPtl0klk4bQk4OajHsiy1BMahpT27jWjJlMiJc+IWJ0mghkK
Ht926s/ymfdf5HkdQ1cyvsz5tryVI3Fx78XeSYfQvuuwqp2H139pXGEkg0n6KdUO
etdZWhe70YGNPw1yjWJT1IhUBBgRAgAMBQJOdz3tBQkT+wG4ABIHZUdQRwABAQkQ
jHGNO1By4fUUmwCbBYr2+bBEn/L2BOcnw9Z/QFWuhRMAoKVgCFm5fadQ3Afi+UQl
AcOphrnJ
=443I
-----END PGP PUBLIC KEY BLOCK-----

To import the build key into your personal public GPG keyring, use gpg --import. For example, if
you have saved the key in a file named mysql_pubkey.asc, the import command looks like this:
shell> gpg --import mysql_pubkey.asc
gpg: key 5072E1F5: public key "MySQL Release Engineering
" imported
gpg: Total number processed: 1
gpg:
imported: 1
gpg: no ultimately trusted keys found

You can also download the key from the public keyserver using the public key id, 5072E1F5:
shell> gpg --recv-keys 5072E1F5
gpg: requesting key 5072E1F5 from hkp server keys.gnupg.net
gpg: key 5072E1F5: "MySQL Release Engineering "
1 new user ID
gpg: key 5072E1F5: "MySQL Release Engineering "
53 new signatures
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:
new user IDs: 1
gpg:
new signatures: 53

If you want to import the key into your RPM configuration to validate RPM install packages, you should
be able to import the key directly:
shell> rpm --import mysql_pubkey.asc

If you experience problems or require RPM specific information, see Section 2.6.4, “Signature
Checking Using RPM”.
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
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using Gpg4win for Windows

has the same name as the distribution file with an .asc extension, as shown by the examples in the
following table.
Table 2.1 MySQL Package and Signature Files for Source files
File Type

File Name

Distribution file

mysql-standard-5.0.96-linux-i686.tar.gz

Signature file

mysql-standard-5.0.96-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

If the downloaded package is valid, you will see a "Good signature" similar to:
shell> gpg --verify mysql-standard-5.0.96-linux-i686.tar.gz.asc
gpg: Signature made Tue 01 Feb 2011 02:38:30 AM CST using DSA key ID 5072E1F5
gpg: Good signature from "MySQL Release Engineering "

The Good signature message indicates that the file signature is valid, when compared to the
signature listed on our site. But you might also see warnings, like so:
shell> gpg --verify mysql-standard-5.0.96-linux-i686.tar.gz.asc
gpg: Signature made Wed 23 Jan 2013 02:25:45 AM PST using DSA key ID 5072E1F5
gpg: checking the trustdb
gpg: no ultimately trusted keys found
gpg: Good signature from "MySQL Release Engineering "
gpg: WARNING: This key is not certified with a trusted signature!
gpg:
There is no indication that the signature belongs to the owner.
Primary key fingerprint: A4A9 4068 76FC BD3C 4567 70C8 8C71 8D3B 5072 E1F5

That is normal, as they depend on your setup and configuration. Here are explanations for these
warnings:
• gpg: no ultimately trusted keys found: This means that the specific key is not "ultimately trusted" by
you or your web of trust, which is okay for the purposes of verifying file signatures.
• WARNING: This key is not certified with a trusted signature! There is no indication that the signature
belongs to the owner.: This refers to your level of trust in your belief that you possess our real public
key. This is a personal decision. Ideally, a MySQL developer would hand you the key in person,
but more commonly, you downloaded it. Was the download tampered with? Probably not, but this
decision is up to you. Setting up a web of trust is one method for trusting them.
See the GPG documentation for more information on how to work with public keys.

2.6.3 Signature Checking Using Gpg4win for Windows
The Section 2.6.2, “Signature Checking Using GnuPG” section describes how to verify MySQL
downloads using GPG. That guide also applies to Microsoft Windows, but another option is to use a
GUI tool like Gpg4win. You may use a different tool but our examples are based on Gpg4win, and
utilize its bundled Kleopatra GUI.
Download and install Gpg4win, and then load Kleopatra. The dialog should look similar to:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using Gpg4win for Windows

Figure 2.1 Initial screen after loading Kleopatra

Next, add the MySQL Release Engineering certificate. Do this by clicking File, Lookup Certificates on
Server. Type "Mysql Release Engineering" into the search box and press Search.
Figure 2.2 Finding the MySQL Release Engineering certificate

Select the "MySQL Release Engineering" certificate. The Fingerprint and Key-ID must be "5072E1F5",
or choose Details... to confirm the certificate is valid. Now, import it by clicking Import. An import
dialog will be displayed, choose Okay, and this certificate will now be listed under the Imported
Certificates tab.
Next, configure the trust level for our certificate. Select our certificate, then from the main menu select
Certificates, Change Owner Trust.... We suggest choosing I believe checks are very accurate for
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using Gpg4win for Windows

our certificate, as otherwise you might not be able to verify our signature. Select I believe checks are
very accurate and then press OK.
Figure 2.3 Changing the Trust level

Next, verify the downloaded MySQL package file. This requires files for both the packaged file, and
the signature. The signature file must have the same name as the packaged file but with an appended
.asc extension, as shown by the example in the following table. The signature is linked to on the
downloads page for each MySQL product. You must create the .asc file with this signature.
Table 2.2 MySQL Package and Signature Files for MySQL Installer for Microsoft Windows
File Type

File Name

Distribution file

mysql-installer-community-5.0.96.msi

Signature file

mysql-installer-community-5.0.96.msi.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. Either drag and drop the signature (.asc) file into Kleopatra, or
load the dialog from File, Decrypt/Verify Files..., and then choose either the .msi or .asc file.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using Gpg4win for Windows

Figure 2.4 The Decrypt/Verify Files dialog

Click Decrypt/Verify to check the file. The two most common results will look like the following, and
although the yellow warning looks problematic, the following means that the file check passed with
success. You may now run this installer.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using Gpg4win for Windows

Figure 2.5 The Decrypt/Verify Results: Good

Seeing a red "The signature is bad" error means the file is invalid. Do not execute the MSI file if you
see this error.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Signature Checking Using RPM

Figure 2.6 The Decrypt/Verify Results: Bad

The Section 2.6.2, “Signature Checking Using GnuPG” section explains why you probably don't see a
green Good signature result.

2.6.4 Signature Checking Using RPM
For RPM packages, there is no separate signature. RPM packages have a built-in GPG signature and
MD5 checksum. You can verify a package by running the following command:
shell> rpm --checksig package_name.rpm

Example:
shell> rpm --checksig MySQL-server-5.0.96-0.glibc23.i386.rpm
MySQL-server-5.0.96-0.glibc23.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, RPM maintains a separate keyring because it is a system-wide
application and a user's GPG public keyring is a user-specific file. To import the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installation Layouts

MySQL public key into the RPM keyring, first obtain the key, then use rpm -import to import the key. For example:
shell> gpg --export -a 5072e1f5 > 5072e1f5.asc
shell> rpm --import 5072e1f5.asc

Alternatively, rpm also supports loading the key directly from a URL, and you can use this manual
page:
shell> rpm --import http://dev.mysql.com/doc/refman/5.0/en/checking-gpg-signature.html

If you need to obtain the MySQL public key, see Section 2.6.2, “Signature Checking Using GnuPG”.

2.7 Installation Layouts
This section describes the default layout of the directories created by installing binary or source
distributions provided by Oracle Corporation. A distribution provided by another vendor might use a
layout different from those shown here.
For MySQL 5.0 on Windows, the default installation directory is C:\Program Files\MySQL\MySQL
Server 5.0. (Some Windows users prefer to install in C:\mysql, the directory that formerly was
used as the default. However, the layout of the subdirectories remains the same.) The installation
directory has the following subdirectories:
Table 2.3 MySQL Installation Layout for Windows
Directory

Contents of Directory

bin

Client programs and the mysqld server

data

Log files, databases

examples

Example programs and scripts

include

Include (header) files

lib

Libraries

scripts

Utility scripts

share

Miscellaneous support files, including error messages,
character set files, sample configuration files, SQL for
database installation

Installations created from our Linux RPM distributions result in files under the system directories shown
in the following table.
Table 2.4 MySQL Installation Layout for Linux RPM Packages
Directory

Contents of Directory

/usr/bin

Client programs and scripts

/usr/sbin

The mysqld server

/var/lib/mysql

Log files, databases

/usr/share/info

MySQL manual in Info format

/usr/share/man

Unix man pages

/usr/include/mysql

Include (header) files

/usr/lib/mysql

Libraries

/usr/share/mysql

Miscellaneous support files, including error messages,
character set files, sample configuration files, SQL for
database installation

/usr/share/sql-bench

Benchmarks

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Compiler-Specific Build Characteristics

On Unix, a tar file binary distribution is installed by unpacking it at the installation location you choose
(typically /usr/local/mysql) and creates the following directories in that location:
Table 2.5 MySQL Installation Layout for Generic Unix/Linux Binary Package
Directory

Contents of Directory

bin

Client programs and the mysqld server

data

Log files, databases

docs

MySQL manual in Info format

man

Unix manual pages

include

Include (header) files

lib

Libraries

scripts

mysql_install_db

share/mysql

Miscellaneous support files, including error messages,
character set files, sample configuration files, SQL for
database installation

sql-bench

Benchmarks

By default, when you install MySQL after compiling it from a source distribution, the installation step
installs files under /usr/local. Components are installed in the directories shown in the following
table. To configure particular installation locations, use the options described at Section 2.17.3,
“MySQL Source-Configuration Options”.
Table 2.6 MySQL Layout for Installation from Source
Directory

Contents of Directory

bin

Client programs and scripts

include/mysql

Include (header) files

Docs

MySQL manual in Info format

man

Unix manual pages

lib/mysql

Libraries

libexec

The mysqld server

share/mysql

Miscellaneous support files, including error messages, character
set files, sample configuration files, SQL for database installation

sql-bench

Benchmarks

var

Log files, databases

Within its installation directory, the layout of a source installation differs from that of a binary installation
in the following ways:
• The mysqld server is installed in the libexec directory rather than in the bin directory.
• The data directory is var rather than data.
• mysql_install_db is installed in the bin directory rather than in the scripts directory.
• The header file and library directories are include/mysql and lib/mysql rather than include
and lib.
To create your own binary installation from a compiled source distribution, execute the scripts/
make_binary_distribution script from the top directory of the source distribution.

2.8 Compiler-Specific Build Characteristics
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Standard MySQL Installation from a Binary Distribution

In some cases, the compiler used to build MySQL affects the features available for use. The notes in
this section apply for binary distributions provided by Oracle Corporation or that you compile yourself
from source.
icc (Intel C++ Compiler) Builds
A server built with icc has these characteristics:
• SSL support is not included.

2.9 Standard MySQL Installation from a Binary Distribution
The next several sections cover the installation of MySQL on platforms where we offer packages using
the native packaging format of the respective platform. (This is also known as performing a binary
installation.) However, binary distributions of MySQL are available for many other platforms as well.
See Section 2.16, “Installing MySQL on Unix/Linux Using Generic Binaries”, for generic installation
instructions for these packages that apply to all platforms.
See Section 2.4, “Notes for MySQL Community Server”, for more information on what other binary
distributions are available and how to obtain them.

2.10 Installing MySQL on Microsoft Windows
Important
The MySQL server 5.0 branch is old and not recommended for new
installations. Consider installing the latest stable branch, which today is MySQL
server 5.7.
A native Windows distribution of MySQL has been available since version 3.21 and represents a
sizable percentage of the daily downloads of MySQL. This section describes the process for installing
MySQL on Windows.
Note
If you are upgrading MySQL from an existing installation older than MySQL
4.1.5, you must first perform the procedure described in Section 2.10.7,
“Upgrading MySQL on Windows”.
To run MySQL on Windows, you need the following:
• A Windows operating system such as XP, Vista, and Server 2003. Newer versions of Windows
than these are not supported. Windows 95/98/ME/2000 and versions of Windows older than these
are no longer supported. For supported platform information, see http://www.mysql.com/support/
supportedplatforms/database.html.
A Windows operating system permits you to run the MySQL server as a service. See
Section 2.10.4.7, “Starting MySQL as a Windows Service”.
Generally, you should install MySQL on Windows using an account that has administrator
rights. Otherwise, you may encounter problems with certain operations such as editing the PATH
environment variable or accessing the Service Control Manager.
• TCP/IP protocol support.
• Enough space on the hard drive to unpack, install, and create the databases in accordance with your
requirements (generally a minimum of 200 megabytes is recommended.)
For a list of limitations on the use of MySQL on the Windows platform, see Section C.7.6, “Windows
Platform Limitations”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Choosing An Installation Package

There may also be other requirements, depending on how you plan to use MySQL:
• To connect to the MySQL server using ODBC, you must have a Connector/ODBC driver. See
Chapter 20, Connectors and APIs.
• If you need tables with a size larger than 4GB, install MySQL on an NTFS or newer file system. Do
not forget to use MAX_ROWS and AVG_ROW_LENGTH when you create tables. See Section 13.1.10,
“CREATE TABLE Syntax”.
MySQL for Windows is available in several distribution formats:
• Binary distributions are available that contain a setup program that installs everything you need so
that you can start the server immediately. Another binary distribution format contains an archive
that you simply unpack in the installation location and then configure yourself. For details, see
Section 2.10.1, “Choosing An Installation Package”.
• The source distribution format contains all the code and support files for building the executables
using the Visual Studio compiler system.
Generally speaking, you should use a binary distribution that includes an installer. It is simpler to use
than the others, and you need no additional tools to get MySQL up and running. The installer for the
Windows version of MySQL, combined with a GUI Configuration Wizard, automatically installs MySQL,
creates an option file, starts the server, and secures the default user accounts.
Caution
Virus-scanning software such as Norton/Symantec Anti-Virus on directories
containing MySQL data and temporary tables can cause issues, both in terms
of the performance of MySQL and the virus-scanning software misidentifying
the contents of the files as containing spam. This is due to the fingerprinting
mechanism used by the virus-scanning software, and the way in which MySQL
rapidly updates different files, which may be identified as a potential security
risk.
After installing MySQL Server, it is recommended that you disable virus
scanning on the main directory (datadir) used to store your MySQL table
data. There is usually a system built into the virus scanning software to enable
specific directories to be ignored.
In addition, by default, MySQL creates temporary files in the standard Windows
temporary directory. To prevent the temporary files also being scanned,
configure a separate temporary directory for MySQL temporary files and add
this directory to the virus scanning exclusion list. To do this, add a configuration
option for the tmpdir parameter to your my.ini configuration file. For more
information, see Section 2.10.4.2, “Creating an Option File”.
The following section describes how to install MySQL on Windows using a binary distribution. To
use an installation package that does not include an installer, follow the procedure described in
Section 2.10.4, “Installing MySQL on Microsoft Windows Using a noinstall Zip Archive”. To install using
a source distribution, see Section 2.10.8, “Installing MySQL from Source on Windows”.
MySQL distributions for Windows can be downloaded from http://dev.mysql.com/downloads/. See
Section 2.5, “How to Get MySQL”.

2.10.1 Choosing An Installation Package
For MySQL 5.0, there are multiple installation package formats to choose from when installing MySQL
on Windows.
• The Essentials package.
This package has a file name similar to mysql-essential-5.0.96win32.msi and contains the minimum set of files needed to install MySQL on Windows, including
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using an MSI Package

the Configuration Wizard. This package does not include optional components such as the
embedded server and benchmark suite.
• The Complete package.
This package has a file name similar to mysql-5.0.96-win32.zip
and contains all files needed for a complete Windows installation, including the Configuration Wizard.
This package includes optional components such as the embedded server and benchmark suite.
• The no-install archive.
This package has a file name similar to mysql-noinstall-5.0.96win32.zip and contains all the files found in the Complete install package, with the exception of the
Configuration Wizard. This package does not include an automated installer, and must be manually
installed and configured.
The Essentials package is recommended for most users. It is provided as an .msi file for use with
the Windows Installer. The Complete and Noinstall distributions are packaged as Zip archives. To use
them, you must have a tool that can unpack .zip files.
Your choice of install package affects the installation process you must follow. If you choose to install
either an Essentials or Complete install package, see Section 2.10.2, “Installing MySQL on Microsoft
Windows Using an MSI Package”. If you choose to install a Noinstall archive, see Section 2.10.4,
“Installing MySQL on Microsoft Windows Using a noinstall Zip Archive”.

2.10.2 Installing MySQL on Microsoft Windows Using an MSI Package
New MySQL users can use the MySQL Installation Wizard and MySQL Configuration Wizard to install
MySQL on Windows. These are designed to install and configure MySQL in such a way that new users
can immediately get started using MySQL.
The MySQL Installation Wizard and MySQL Configuration Wizard are available in the Essentials and
Complete install packages. They are recommended for most standard MySQL installations. Exceptions
include users who need to install multiple instances of MySQL on a single server host and advanced
users who want complete control of server configuration.

2.10.2.1 Using the MySQL Installation Wizard
MySQL Installation Wizard is an installer for the MySQL server that uses the latest installer
technologies for Microsoft Windows. The MySQL Installation Wizard, in combination with the MySQL
Configuration Wizard, enables a user to install and configure a MySQL server that is ready for use
immediately after installation.
The MySQL Installation Wizard is the standard installer for all MySQL server distributions, version 4.1.5
and higher. Users of previous versions of MySQL need to shut down and remove their existing MySQL
installations manually before installing MySQL with the MySQL Installation Wizard. See Upgrading
MySQL with the Installation Wizard, for more information on upgrading from a previous version.
The Microsoft Windows Installer (MSI) is the standard for application installations on Windows 2000
and later versions. The MySQL Installation Wizard makes use of this technology to provide a smoother
and more flexible installation process.
The Microsoft Windows Installer Engine was updated with the release of Windows XP; those using a
previous version of Windows can reference this Microsoft Knowledge Base article for information on
upgrading to the latest version of the Windows Installer Engine.
In addition, Microsoft has introduced the WiX (Windows Installer XML) toolkit, which is the first highly
acknowledged Open Source project from Microsoft. We have switched to WiX because it is an Open
Source project and it enables us to handle the complete Windows installation process in a flexible
manner using scripts.
Improving the MySQL Installation Wizard depends on the support and feedback of users. If you find
that the MySQL Installation Wizard is lacking some feature important to you, or if you discover a bug,
please report it in our bugs database using the instructions given in Section 1.7, “How to Report Bugs
or Problems”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using an MSI Package

Downloading and Starting the MySQL Installation Wizard
MySQL installation packages can be downloaded from http://dev.mysql.com/downloads/. If the
package you download is contained within a Zip archive, you need to extract the archive first.
Note
If you are installing on Windows Vista or newer, it is best to open a network port
for MySQL to use before beginning the installation. To do this, first ensure that
you are logged in as an Administrator, then go to the Control Panel and
double-click the Windows Firewall icon. Choose the Allow a program
through Windows Firewall option and click the Add port button. Enter
MySQL into the Name text box and 3306 (or other port of your choice) into
the Port number text box. Also ensure that the TCP protocol radio button
is selected. If you wish, you can also limit access to the MySQL server by
choosing the Change scope button. Confirm your choices by clicking the OK
button. If you do not open a port prior to installation, you cannot configure the
MySQL server immediately after installation. Additionally, when running the
MySQL Installation Wizard on Windows Vista or newer, ensure that you are
logged in as a user with administrative rights.
The process for starting the wizard depends on the contents of the installation package you download.
If there is a setup.exe file present, double-click it to start the installation process. If there is an .msi
file present, double-click it to start the installation process.

Choosing an Installation Type
There are three installation types available: Typical, Complete, and Custom.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using an MSI Package

The Typical installation type installs the MySQL server, the mysql command-line client, and the
command-line utilities. The command-line clients and utilities include mysqldump, myisamchk, and
several other tools to help you manage the MySQL server.
The Complete installation type installs all components included in the installation package. The full
installation package includes components such as the embedded server library, the benchmark suite,
support scripts, and documentation.
The Custom installation type gives you complete control over which packages you wish to install
and the installation path that is used. See The Custom Installation Dialog, for more information on
performing a custom install.
If you choose the Typical or Complete installation types and click the Next button, you advance to
the confirmation screen to verify your choices and begin the installation. If you choose the Custom
installation type and click the Next button, you advance to the custom installation dialog, described in
The Custom Installation Dialog.

The Custom Installation Dialog
If you wish to change the installation path or the specific components that are installed by the MySQL
Installation Wizard, choose the Custom installation type.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using an MSI Package

A tree view on the left side of the custom install dialog lists all available components. Components that
are not installed have a red X icon; components that are installed have a gray icon. To change whether
a component is installed, click that component's icon and choose a new option from the drop-down list
that appears.
You can change the default installation path by clicking the Change... button to the right of the
displayed installation path.
After choosing your installation components and installation path, click the Next button to advance to
the confirmation dialog.

The Confirmation Dialog
Once you choose an installation type and optionally choose your installation components, you advance
to the confirmation dialog. Your installation type and installation path are displayed for you to review.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using an MSI Package

To install MySQL if you are satisfied with your settings, click the Install button. To change your
settings, click the Back button. To exit the MySQL Installation Wizard without installing MySQL, click
the Cancel button.
After installation is complete, you have the option of registering with the MySQL Web site. Registration
gives you access to post in the MySQL forums at forums.mysql.com, along with the ability to report
bugs at bugs.mysql.com and to subscribe to our newsletter. The final screen of the installer provides a
summary of the installation and gives you the option to launch the MySQL Configuration Wizard, which
you can use to create a configuration file, install the MySQL service, and configure security settings.

Changes Made by MySQL Installation Wizard
Once you click the Install button, the MySQL Installation Wizard begins the installation process and
makes certain changes to your system which are described in the sections that follow.
Changes to the Registry
The MySQL Installation Wizard creates one Windows registry key in a typical install situation, located in
HKEY_LOCAL_MACHINE\SOFTWARE\MySQL AB.
The MySQL Installation Wizard creates a key named after the release series of the server that is being
installed, such as MySQL Server 5.0. It contains two string values, Location and Version. The
Location string contains the path to the installation directory. In a default installation it contains C:
\Program Files\MySQL\MySQL Server 5.0\. The Version string contains the release number.
For example, for an installation of MySQL Server 5.0.96, the key contains a value of 5.0.96.
These registry keys are used to help external tools identify the installed location of the MySQL server,
preventing a complete scan of the hard-disk to determine the installation path of the MySQL server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

The registry keys are not required to run the server, and if you install MySQL using the noinstall Zip
archive, the registry keys are not created.
Changes to the Start Menu
The MySQL Installation Wizard creates a new entry in the Windows Start menu under a common
MySQL menu heading named after the release series of MySQL that you have installed. For example,
if you install MySQL 5.0, the MySQL Installation Wizard creates a MySQL Server 5.0 section in the
Start menu.
The following entries are created within the new Start menu section:
• MySQL Command-Line Client: This is a shortcut to the mysql command-line client and is
configured to connect as the root user. The shortcut prompts for a root user password when you
connect.
• MySQL Server Instance Config Wizard: This is a shortcut to the MySQL Configuration Wizard. Use
this shortcut to configure a newly installed server, or to reconfigure an existing server.
• MySQL Documentation: This is a link to the MySQL server documentation that is stored locally
in the MySQL server installation directory. This option is not available when the MySQL server is
installed using the Essentials installation package.
Changes to the File System
The MySQL Installation Wizard by default installs the MySQL 5.0 server to C:\Program
Files\MySQL\MySQL Server 5.0, where Program Files is the default location for applications
in your system, and 5.0 is the major version of your MySQL server. This is the recommended location
for the MySQL server, replacing the former default location C:\mysql.
By default, all MySQL applications are stored in a common directory at C:\Program Files\MySQL,
where Program Files is the default location for applications in your Windows installation. A typical
MySQL installation on a developer machine might look like this:
C:\Program Files\MySQL\MySQL Server 5.0
C:\Program Files\MySQL\MySQL Workbench 5.1 OSS

This approach makes it easier to manage and maintain all MySQL applications installed on a particular
system.

Upgrading MySQL with the Installation Wizard
The MySQL Installation Wizard can perform server upgrades automatically using the upgrade
capabilities of MSI. That means you do not need to remove a previous installation manually before
installing a new release. The installer automatically shuts down and removes the previous MySQL
service before installing the new version.
Automatic upgrades are available only when upgrading between installations that have the same major
and minor version numbers. For example, you can upgrade automatically from MySQL 5.0.5 to MySQL
5.0.6, but not from MySQL 4.1 to MySQL 5.0.
See Section 2.10.7, “Upgrading MySQL on Windows”.

2.10.3 MySQL Server Instance Configuration Wizard
The MySQL Server Instance Configuration Wizard helps automate the process of configuring your
server. It creates a custom MySQL configuration file (my.ini or my.cnf) by asking you a series of
questions and then applying your responses to a template to generate the configuration file that is
tuned to your installation.
The MySQL Server Instance Configuration Wizard is included with the MySQL 5.0 server. The MySQL
Server Instance Configuration Wizard is only available for Windows.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

2.10.3.1 Starting the MySQL Server Instance Configuration Wizard
The MySQL Server Instance Configuration Wizard is normally started as part of the installation
process. You should only need to run the MySQL Server Instance Configuration Wizard again when
you need to change the configuration parameters of your server.
If you chose not to open a port prior to installing MySQL on Windows Vista or newer, you can choose
to use the MySQL Server Configuration Wizard after installation. However, you must open a port in
the Windows Firewall. To do this see the instructions given in Downloading and Starting the MySQL
Installation Wizard. Rather than opening a port, you also have the option of adding MySQL as a
program that bypasses the Windows Firewall. One or the other option is sufficient—you need not do
both. Additionally, when running the MySQL Server Configuration Wizard on Windows Vista or newer,
ensure that you are logged in as a user with administrative rights.

You can launch the MySQL Configuration Wizard by clicking the MySQL Server Instance Config
Wizard entry in the MySQL section of the Windows Start menu.
Alternatively, you can navigate to the bin directory of your MySQL installation and launch the
MySQLInstanceConfig.exe file directly.
The MySQL Server Instance Configuration Wizard places the my.ini file in the installation directory
for the MySQL server. This helps associate configuration files with particular server instances.
To ensure that the MySQL server knows where to look for the my.ini file, an argument similar to this
is passed to the MySQL server as part of the service installation:
--defaults-file="C:\Program Files\MySQL\MySQL Server 5.0\my.ini"

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

Here, C:\Program Files\MySQL\MySQL Server 5.0 is replaced with the installation path to the
MySQL Server. The --defaults-file option instructs the MySQL server to read the specified file
for configuration options when it starts.
Apart from making changes to the my.ini file by running the MySQL Server Instance Configuration
Wizard again, you can modify it by opening it with a text editor and making any necessary changes.
You can also modify the server configuration with the http://www.mysql.com/products/administrator/
utility. For more information about server configuration, see Section 5.1.3, “Server Command Options”.
MySQL clients and utilities such as the mysql and mysqldump command-line clients are not able
to locate the my.ini file located in the server installation directory. To configure the client and
utility applications, create a new my.ini file in the Windows installation directory (for example, C:
\WINDOWS).
Under Windows Server 2003, Windows Server 2000 and Windows XP, MySQL Server Instance
Configuration Wizard will configure MySQL to work as a Windows service. To start and stop MySQL
you use the Services application that is supplied as part of the Windows Administrator Tools.

2.10.3.2 Choosing a Maintenance Option
If the MySQL Server Instance Configuration Wizard detects an existing configuration file, you have
the option of either reconfiguring your existing server, or removing the server instance by deleting the
configuration file and stopping and removing the MySQL service.
To reconfigure an existing server, choose the Re-configure Instance option and click the Next button.
Any existing configuration file is not overwritten, but renamed (within the same directory) using a
timestamp (Windows) or sequential number (Linux). To remove the existing server instance, choose
the Remove Instance option and click the Next button.
If you choose the Remove Instance option, you advance to a confirmation window. Click the Execute
button. The MySQL Server Configuration Wizard stops and removes the MySQL service, and then
deletes the configuration file. The server installation and its data folder are not removed.
If you choose the Re-configure Instance option, you advance to the Configuration Type dialog
where you can choose the type of installation that you wish to configure.

2.10.3.3 Choosing a Configuration Type
When you start the MySQL Server Instance Configuration Wizard for a new MySQL installation,
or choose the Re-configure Instance option for an existing installation, you advance to the
Configuration Type dialog.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

There are two configuration types available: Detailed Configuration and Standard Configuration.
The Standard Configuration option is intended for new users who want to get started with
MySQL quickly without having to make many decisions about server configuration. The Detailed
Configuration option is intended for advanced users who want more fine-grained control over server
configuration.
If you are new to MySQL and need a server configured as a single-user developer machine, the
Standard Configuration should suit your needs. Choosing the Standard Configuration option
causes the MySQL Configuration Wizard to set all configuration options automatically with the
exception of Service Options and Security Options.
The Standard Configuration sets options that may be incompatible with systems where there are
existing MySQL installations. If you have an existing MySQL installation on your system in addition to
the installation you wish to configure, the Detailed Configuration option is recommended.
To complete the Standard Configuration, please refer to the sections on Service Options and
Security Options in Section 2.10.3.10, “The Service Options Dialog”, and Section 2.10.3.11, “The
Security Options Dialog”, respectively.

2.10.3.4 The Server Type Dialog
There are three different server types available to choose from. The server type that you choose affects
the decisions that the MySQL Server Instance Configuration Wizard makes with regard to memory,
disk, and processor usage.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

• Developer Machine: Choose this option for a typical desktop workstation where MySQL is intended
only for personal use. It is assumed that many other desktop applications are running. The MySQL
server is configured to use minimal system resources.
• Server Machine: Choose this option for a server machine where the MySQL server is running
alongside other server applications such as FTP, email, and Web servers. The MySQL server is
configured to use a moderate portion of the system resources.
• Dedicated MySQL Server Machine: Choose this option for a server machine that is intended to run
only the MySQL server. It is assumed that no other applications are running. The MySQL server is
configured to use all available system resources.
Note
By selecting one of the preconfigured configurations, the values and settings
of various options in your my.cnf or my.ini will be altered accordingly. The
default values and options as described in the reference manual may therefore
be different to the options and values that were created during the execution of
the configuration wizard.

2.10.3.5 The Database Usage Dialog
The Database Usage dialog enables you to indicate the storage engines that you expect to use when
creating MySQL tables. The option you choose determines whether the InnoDB storage engine is
available and what percentage of the server resources are available to InnoDB.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

• Multifunctional Database: This option enables both the InnoDB and MyISAM storage engines
and divides resources evenly between the two. This option is recommended for users who use both
storage engines on a regular basis.
• Transactional Database Only: This option enables both the InnoDB and MyISAM storage engines,
but dedicates most server resources to the InnoDB storage engine. This option is recommended for
users who use InnoDB almost exclusively and make only minimal use of MyISAM.
• Non-Transactional Database Only: This option disables the InnoDB storage engine completely
and dedicates all server resources to the MyISAM storage engine. This option is recommended for
users who do not use InnoDB.
The Configuration Wizard uses a template to generate the server configuration file. The Database
Usage dialog sets one of the following option strings:
Multifunctional Database:
MIXED
Transactional Database Only:
INNODB
Non-Transactional Database Only: MYISAM

When these options are processed through the default template (my-template.ini) the result is:
Multifunctional Database:
default-storage-engine=InnoDB
_myisam_pct=50
Transactional Database Only:
default-storage-engine=InnoDB
_myisam_pct=5

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

Non-Transactional Database Only:
default-storage-engine=MyISAM
_myisam_pct=100
skip-innodb

The _myisam_pct value is used to calculate the percentage of resources dedicated to MyISAM. The
remaining resources are allocated to InnoDB.

2.10.3.6 The InnoDB Tablespace Dialog
Some users may want to locate the InnoDB tablespace files in a different location than the MySQL
server data directory. Placing the tablespace files in a separate location can be desirable if your system
has a higher capacity or higher performance storage device available, such as a RAID storage system.

To change the default location for the InnoDB tablespace files, choose a new drive from the drop-down
list of drive letters and choose a new path from the drop-down list of paths. To create a custom path,
click the ... button.
If you are modifying the configuration of an existing server, you must click the Modify button before
you change the path. In this situation you must move the existing tablespace files to the new location
manually before starting the server.

2.10.3.7 The Concurrent Connections Dialog
To prevent the server from running out of resources, it is important to limit the number of concurrent
connections to the MySQL server that can be established. The Concurrent Connections dialog
enables you to choose the expected usage of your server, and sets the limit for concurrent connections
accordingly. It is also possible to set the concurrent connection limit manually.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

• Decision Support (DSS)/OLAP: Choose this option if your server does not require a large number
of concurrent connections. The maximum number of connections is set at 100, with an average of 20
concurrent connections assumed.
• Online Transaction Processing (OLTP): Choose this option if your server requires a large number
of concurrent connections. The maximum number of connections is set at 500.
• Manual Setting: Choose this option to set the maximum number of concurrent connections to the
server manually. Choose the number of concurrent connections from the drop-down box provided,
or enter the maximum number of connections into the drop-down box if the number you desire is not
listed.

2.10.3.8 The Networking and Strict Mode Options Dialog
Use the Networking Options dialog to enable or disable TCP/IP networking and to configure the port
number that is used to connect to the MySQL server.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

TCP/IP networking is enabled by default. To disable TCP/IP networking, uncheck the box next to the
Enable TCP/IP Networking option.
Port 3306 is used by default. To change the port used to access MySQL, choose a new port number
from the drop-down box or type a new port number directly into the drop-down box. If the port number
you choose is in use, you are prompted to confirm your choice of port number.
Set the Server SQL Mode to either enable or disable strict mode. Enabling strict mode (default) makes
MySQL behave more like other database management systems. If you run applications that rely on
MySQL's old “forgiving” behavior, make sure to either adapt those applications or to disable strict
mode. For more information about strict mode, see Section 5.1.7, “Server SQL Modes”.

2.10.3.9 The Character Set Dialog
The MySQL server supports multiple character sets and it is possible to set a default server character
set that is applied to all tables, columns, and databases unless overridden. Use the Character Set
dialog to change the default character set of the MySQL server.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

• Standard Character Set: Choose this option if you want to use latin1 as the default server
character set. latin1 is used for English and many Western European languages.
• Best Support For Multilingualism: Choose this option if you want to use utf8 as the default
server character set. This is a Unicode character set that can store characters from many different
languages.
• Manual Selected Default Character Set / Collation: Choose this option if you want to pick the
server's default character set manually. Choose the desired character set from the provided dropdown list.

2.10.3.10 The Service Options Dialog
On Windows platforms, the MySQL server can be installed as a Windows service. When installed
this way, the MySQL server can be started automatically during system startup, and even restarted
automatically by Windows in the event of a service failure.
The MySQL Server Instance Configuration Wizard installs the MySQL server as a service by default,
using the service name MySQL. If you do not wish to install the service, uncheck the box next to the
Install As Windows Service option. You can change the service name by picking a new service name
from the drop-down box provided or by entering a new service name into the drop-down box.
Note
Service names can include any legal character except forward (/) or backward
(\) slashes, and must be less than 256 characters long.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

Warning
If you are installing multiple versions of MySQL onto the same machine, you
must choose a different service name for each version that you install. If you
do not choose a different service for each installed version then the service
manager information will be inconsistent and this will cause problems when you
try to uninstall a previous version.
If you have already installed multiple versions using the same service name,
you must manually edit the contents of the HKEY_LOCAL_MACHINE\SYSTEM
\CurrentControlSet\Services parameters within the Windows registry to
update the association of the service name with the correct server version.
Typically, when installing multiple versions you create a service name based on
the version information. For example, you might install MySQL 5.x as mysql5,
or specific versions such as MySQL 5.0.56 as mysql50056.
To install the MySQL server as a service but not have it started automatically at startup, uncheck the
box next to the Launch the MySQL Server Automatically option.

2.10.3.11 The Security Options Dialog
It is strongly recommended that you set a root password for your MySQL server, and the MySQL
Server Instance Configuration Wizard requires by default that you do so. If you do not wish to set a
root password, uncheck the box next to the Modify Security Settings option.

To set the root password, enter the desired password into both the New root password and Confirm
boxes. If you are reconfiguring an existing server, you need to enter the existing root password into
the Current root password box.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server Instance Configuration Wizard

To permit root logins from across the network, check the box next to the Enable root access from
remote machines option. This decreases the security of your root account.
To create an anonymous user account, check the box next to the Create An Anonymous Account
option. Creating an anonymous account can decrease server security and cause login and permission
difficulties. For this reason, it is not recommended.

2.10.3.12 The Confirmation Dialog
The final dialog in the MySQL Server Instance Configuration Wizard is the Confirmation Dialog. To
start the configuration process, click the Execute button. To return to a previous dialog, click the Back
button. To exit the MySQL Server Instance Configuration Wizard without configuring the server, click
the Cancel button.

After you click the Execute button, the MySQL Server Instance Configuration Wizard performs a series
of tasks and displays the progress onscreen as the tasks are performed.
The MySQL Server Instance Configuration Wizard first determines configuration file options based on
your choices using a template prepared by MySQL developers and engineers. This template is named
my-template.ini and is located in your server installation directory.
The MySQL Configuration Wizard then writes these options to the corresponding configuration file.
If you chose to create a service for the MySQL server, the MySQL Server Instance Configuration
Wizard creates and starts the service. If you are reconfiguring an existing service, the MySQL Server
Instance Configuration Wizard restarts the service to apply your configuration changes.
If you chose to set a root password, the MySQL Configuration Wizard connects to the server, sets
your new root password, and applies any other security settings you may have selected.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

After the MySQL Server Instance Configuration Wizard has completed its tasks, it displays a summary.
Click the Finish button to exit the MySQL Server Configuration Wizard.

2.10.4 Installing MySQL on Microsoft Windows Using a noinstall Zip
Archive
Users who are installing from the Noinstall package can use the instructions in this section to manually
install MySQL. The process for installing MySQL from a Zip archive is as follows:
1. Extract the archive to the desired install directory
2. Create an option file
3. Choose a MySQL server type
4. Start the MySQL server
5. Secure the default user accounts
This process is described in the sections that follow.

2.10.4.1 Extracting the Install Archive
To install MySQL manually, do the following:
1. If you are upgrading from a previous version please refer to Section 2.10.7, “Upgrading MySQL on
Windows”, before beginning the upgrade process.
2. Make sure that you are logged in as a user with administrator privileges.
3. Choose an installation location. Traditionally, the MySQL server is installed in C:\mysql. The
MySQL Installation Wizard installs MySQL under C:\Program Files\MySQL. If you do not install
MySQL at C:\mysql, you must specify the path to the install directory during startup or in an
option file. See Section 2.10.4.2, “Creating an Option File”.
4. Extract the install archive to the chosen installation location using your preferred Zip archive tool.
Some tools may extract the archive to a folder within your chosen installation location. If this occurs,
you can move the contents of the subfolder into the chosen installation location.

2.10.4.2 Creating an Option File
If you need to specify startup options when you run the server, you can indicate them on the command
line or place them in an option file. For options that are used every time the server starts, you may find
it most convenient to use an option file to specify your MySQL configuration. This is particularly true
under the following circumstances:
• The installation or data directory locations are different from the default locations (C:\Program
Files\MySQL\MySQL Server 5.0 and C:\Program Files\MySQL\MySQL Server
5.0\data).
• You need to tune the server settings.
When the MySQL server starts on Windows, it looks for option files in several locations, such as
the Windows directory, C:\, and the MySQL installation directory (for the full list of locations, see
Section 4.2.6, “Using Option Files”). The Windows directory typically is named something like C:
\WINDOWS. You can determine its exact location from the value of the WINDIR environment variable
using the following command:
shell> echo %WINDIR%

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

MySQL looks for options in each location first in the my.ini file, and then in the my.cnf file. However,
to avoid confusion, it is best if you use only one file. If your PC uses a boot loader where C: is not the
boot drive, your only option is to use the my.ini file. Whichever option file you use, it must be a plain
text file.
You can also make use of the example option files included with your MySQL distribution; see
Section 5.1.2, “Server Configuration Defaults”.
An option file can be created and modified with any text editor, such as Notepad. For example, if
MySQL is installed in E:\mysql and the data directory is in E:\mydata\data, you can create an
option file containing a [mysqld] section to specify values for the basedir and datadir options:
[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 path names are specified in option files using (forward) slashes rather than
backslashes. If you do use backslashes, double them:
[mysqld]
# set basedir to your installation path
basedir=E:\\mysql
# set datadir to the location of your data directory
datadir=E:\\mydata\\data

The rules for use of backslash in option file values are given in Section 4.2.6, “Using Option Files”.
On Windows, the MySQL installer places the data directory directly under the directory where you
install MySQL. If you would like to use a data directory in a different location, you should copy the
entire contents of the data directory to the new location. For example, if MySQL is installed in C:
\Program Files\MySQL\MySQL Server 5.0, the data directory is by default in C:\Program
Files\MySQL\MySQL Server 5.0\data. If you want to use E:\mydata as the data directory
instead, you must do two things:
1. Move the entire data directory and all of its contents from C:\Program Files\MySQL\MySQL
Server 5.0\data to E:\mydata.
2. Use a --datadir option to specify the new data directory location each time you start the server.

2.10.4.3 Selecting a MySQL Server Type
The following table shows the available servers for Windows in MySQL 5.0.
Binary

Description

mysqld-nt

Optimized binary with named-pipe support

mysqld

Optimized binary without named-pipe support

mysqld-debug

Like mysqld-nt, but compiled with full debugging and automatic memory
allocation checking

All of the preceding binaries are optimized for modern Intel processors, but should work on any Intel
i386-class or higher processor.
Each of the servers in a distribution support the same set of storage engines. The SHOW ENGINES
statement displays which engines a given server supports.
All Windows MySQL 5.0 servers have support for symbolic linking of database directories.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

MySQL supports TCP/IP on all Windows platforms. MySQL servers on Windows support named pipes
as indicated in the following list. However, the default is to use TCP/IP regardless of platform. (Named
pipes are slower than TCP/IP in many Windows configurations.)
Use of named pipes is subject to these conditions:
• Named pipes are enabled only if you start the server with the --enable-named-pipe option. It is
necessary to use this option explicitly because some users have experienced problems with shutting
down the MySQL server when named pipes were used.
• Named-pipe connections are permitted only by the mysqld-nt and mysqld-debug servers.
Note
Most of the examples in this manual use mysqld as the server name. If you
choose to use a different server, such as mysqld-nt, make the appropriate
substitutions in the commands that are shown in the examples.

2.10.4.4 Starting the Server for the First Time
This section gives a general overview of starting the MySQL server. The following sections provide
more specific information for starting the MySQL server from the command line or as a Windows
service.
The information here applies primarily if you installed MySQL using the Noinstall version, or if you
wish to configure and test MySQL manually rather than with the GUI tools.
The examples in these sections assume that MySQL is installed under the default location of C:
\Program Files\MySQL\MySQL Server 5.0. Adjust the path names shown in the examples if
you have MySQL installed in a different location.
Clients have two options. They can use TCP/IP, or they can use a named pipe if the server supports
named-pipe connections.
MySQL for Windows also supports shared-memory connections if the server is started with
the --shared-memory option. Clients can connect through shared memory by using the -protocol=MEMORY option.
For information about which server binary to run, see Section 2.10.4.3, “Selecting a MySQL Server
Type”.
Testing is best done from a command prompt in a console window (or “DOS window”). In this way you
can have the server display status messages in the window where they are easy to see. If something is
wrong with your configuration, these messages make it easier for you to identify and fix any problems.
To start the server, enter this command:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --console

For a server that includes InnoDB support, you should see the messages similar to those following as
it starts (the path names and sizes may differ):
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:

This
documentation
is for an
older version.
If you're

The first specified datafile c:\ibdata\ibdata1 did not exist:
a new database to be created!
Setting file c:\ibdata\ibdata1 size to 209715200
Database physically writes the file full: wait...
Log file c:\iblogs\ib_logfile0 did not exist: new to be created
Setting log file c:\iblogs\ib_logfile0 size to 31457280
Log file c:\iblogs\ib_logfile1 did not exist: new to be created

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
InnoDB: Doublewrite buffer not found: creating new
InnoDB: Doublewrite buffer created
InnoDB: creating foreign key constraint system tables
InnoDB: foreign key constraint system tables created
011024 10:58:25 InnoDB: Started

When the server finishes its startup sequence, you should see something like this, which indicates that
the server is ready to service client connections:
mysqld: ready for connections
Version: '5.0.96' socket: ''

port: 3306

The server continues to write to the console any further diagnostic output it produces. You can open a
new console window in which to run client programs.
If you omit the --console option, the server writes diagnostic output to the error log in the data
directory (C:\Program Files\MySQL\MySQL Server 5.0\data by default). The error log is the
file with the .err extension.
Note
The accounts that are listed in the MySQL grant tables initially have no
passwords. After starting the server, you should set up passwords for them
using the instructions in Section 2.18.4, “Securing the Initial MySQL Accounts”.

2.10.4.5 Starting MySQL from the Windows Command Line
The MySQL server can be started manually from the command line. This can be done on any version
of Windows.
To start the mysqld server from the command line, you should start a console window (or “DOS
window”) and enter this command:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld"

The path to mysqld may vary depending on the install location of MySQL on your system.
You can stop the MySQL server by executing this command:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin" -u root shutdown

Note
If the MySQL root user account has a password, you need to invoke
mysqladmin with the -p option and supply the password when prompted.
This command invokes the MySQL administrative utility mysqladmin to connect to the server
and tell it to shut down. The command connects as the MySQL root user, which is the default
administrative account in the MySQL grant system. Note that users in the MySQL grant system are
wholly independent from any login users under Windows.
If mysqld doesn't start, check the error log to see whether the server wrote any messages there to
indicate the cause of the problem. The error log is located in the C:\Program Files\MySQL\MySQL
Server 5.0\data directory. It is the file with a suffix of .err. You can also try to start the server as
mysqld --console; in this case, you may get some useful information on the screen that may help
solve the problem.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

The last option is to start mysqld with the --standalone and --debug options. In this case, mysqld
writes a log file C:\mysqld.trace that should contain the reason why mysqld doesn't start. See
Section 21.3.3, “The DBUG Package”.
Use mysqld --verbose --help to display all the options that mysqld supports.

2.10.4.6 Customizing the PATH for MySQL Tools
To make it easier to invoke MySQL programs, you can add the path name of the MySQL bin directory
to your Windows system PATH environment variable:
• On the Windows desktop, right-click the My Computer icon, and select Properties.
• Next select the Advanced tab from the System Properties menu that appears, and click the
Environment Variables button.
• Under System Variables, select Path, and then click the Edit button. The Edit System Variable
dialogue should appear.
• Place your cursor at the end of the text appearing in the space marked Variable Value. (Use the
End key to ensure that your cursor is positioned at the very end of the text in this space.) Then enter
the complete path name of your MySQL bin directory (for example, C:\Program Files\MySQL
\MySQL Server 5.0\bin)
Note
There must be a semicolon separating this path from any values present in
this field.
Dismiss this dialogue, and each dialogue in turn, by clicking OK until all of the dialogues that were
opened have been dismissed. You should now be able to invoke any MySQL executable program
by typing its name at the DOS prompt from any directory on the system, without having to supply
the path. This includes the servers, the mysql client, and all MySQL command-line utilities such as
mysqladmin and mysqldump.
You should not add the MySQL bin directory to your Windows PATH if you are running multiple
MySQL servers on the same machine.
Warning
You must exercise great care when editing your system PATH by hand;
accidental deletion or modification of any portion of the existing PATH value can
leave you with a malfunctioning or even unusable system.

2.10.4.7 Starting MySQL as a Windows Service
On Windows, the recommended way to run MySQL is to install it as a Windows service, whereby
MySQL starts and stops automatically when Windows starts and stops. A MySQL server installed as
a service can also be controlled from the command line using NET commands, or with the graphical
Services utility. Generally, to install MySQL as a Windows service you should be logged in using an
account that has administrator rights.
The Services utility (the Windows Service Control Manager) can be found in the Windows
Control Panel (under Administrative Tools on Windows 2000, XP, Vista, and Server 2003). To avoid
conflicts, it is advisable to close the Services utility while performing server installation or removal
operations from the command line.

Installing the service
Before installing MySQL as a Windows service, you should first stop the current server if it is running
by using the following command:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin"
-u root shutdown

Note
If the MySQL root user account has a password, you need to invoke
mysqladmin with the -p option and supply the password when prompted.
This command invokes the MySQL administrative utility mysqladmin to connect to the server
and tell it to shut down. The command connects as the MySQL root user, which is the default
administrative account in the MySQL grant system. Note that users in the MySQL grant system are
wholly independent from any login users under Windows.
Install the server as a service using this command:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --install

The service-installation command does not start the server. Instructions for that are given later in this
section.
To make it easier to invoke MySQL programs, you can add the path name of the MySQL bin directory
to your Windows system PATH environment variable:
• On the Windows desktop, right-click the My Computer icon, and select Properties.
• Next select the Advanced tab from the System Properties menu that appears, and click the
Environment Variables button.
• Under System Variables, select Path, and then click the Edit button. The Edit System Variable
dialogue should appear.
• Place your cursor at the end of the text appearing in the space marked Variable Value. (Use the
End key to ensure that your cursor is positioned at the very end of the text in this space.) Then enter
the complete path name of your MySQL bin directory (for example, C:\Program Files\MySQL
\MySQL Server 5.0\bin), Note that there should be a semicolon separating this path from any
values present in this field. Dismiss this dialogue, and each dialogue in turn, by clicking OK until all of
the dialogues that were opened have been dismissed. You should now be able to invoke any MySQL
executable program by typing its name at the DOS prompt from any directory on the system, without
having to supply the path. This includes the servers, the mysql client, and all MySQL command-line
utilities such as mysqladmin and mysqldump.
You should not add the MySQL bin directory to your Windows PATH if you are running multiple
MySQL servers on the same machine.
Warning
You must exercise great care when editing your system PATH by hand;
accidental deletion or modification of any portion of the existing PATH value can
leave you with a malfunctioning or even unusable system.
The following additional arguments can be used when installing the service:
• You can specify a service name immediately following the --install option. The default service
name is MySQL.
• If a service name is given, it can be followed by a single option. By convention, this should be -defaults-file=file_name to specify the name of an option file from which the server should
read options when it starts.
The use of a single option other than --defaults-file is possible but discouraged. -defaults-file is more flexible because it enables you to specify multiple startup options for the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Microsoft Windows Using a noinstall Zip Archive

server by placing them in the named option file. Also, in MySQL 5.0, use of an option different from
--defaults-file is not supported until 5.0.3.
• As of MySQL 5.0.1, you can also specify a --local-service option following the service name.
This causes the server to run using the LocalService Windows account that has limited system
privileges. This account is available only for Windows XP or newer. If both --defaults-file and
--local-service are given following the service name, they can be in any order.
For a MySQL server that is installed as a Windows service, the following rules determine the service
name and option files that the server uses:
• If the service-installation command specifies no service name or the default service name (MySQL)
following the --install option, the server uses the a service name of MySQL and reads options
from the [mysqld] group in the standard option files.
• If the service-installation command specifies a service name other than MySQL following the -install option, the server uses that service name. It reads options from the [mysqld] group
and the group that has the same name as the service in the standard option files. This enables you
to use the [mysqld] group for options that should be used by all MySQL services, and an option
group with the service name for use by the server installed with that service name.
• If the service-installation command specifies a --defaults-file option after the service name,
the server reads options the same way as described in the previous item, except that it reads options
only from the named file and ignores the standard option files.
As a more complex example, consider the following command:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld"
--install MySQL --defaults-file=C:\my-opts.cnf

Here, the default service name (MySQL) is given after the --install option. If no --defaultsfile option had been given, this command would have the effect of causing the server to read the
[mysqld] group from the standard option files. However, because the --defaults-file option is
present, the server reads options from the [mysqld] option group, and only from the named file.
Note
On Windows, if the server is started with the --defaults-file and -install options, --install must be first. Otherwise, mysqld.exe will
attempt to start the MySQL server.
You can also specify options as Start parameters in the Windows Services utility before you start the
MySQL service.

Starting the service
Once a MySQL server has been installed as a service, Windows starts the service automatically
whenever Windows starts. The service also can be started immediately from the Services utility, or
by using a NET START MySQL command. The NET command is not case sensitive.
When run as a service, mysqld has no access to a console window, so no messages can be seen
there. If mysqld does not start, check the error log to see whether the server wrote any messages
there to indicate the cause of the problem. The error log is located in the MySQL data directory (for
example, C:\Program Files\MySQL\MySQL Server 5.0\data). It is the file with a suffix of
.err.
When a MySQL server has been installed as a service, and the service is running, Windows stops the
service automatically when Windows shuts down. The server also can be stopped manually by using
the Services utility, the NET STOP MySQL command, or the mysqladmin shutdown command.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting a MySQL Installation Under Windows

You also have the choice of installing the server as a manual service if you do not wish for the service
to be started automatically during the boot process. To do this, use the --install-manual option
rather than the --install option:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --install-manual

Removing the service
To remove a server that is installed as a service, first stop it if it is running by executing NET STOP
MySQL. Then use the --remove option to remove it:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqld" --remove

If mysqld is not running as a service, you can start it from the command line. For instructions, see
Section 2.10.4.5, “Starting MySQL from the Windows Command Line”.
Please see Section 2.10.5, “Troubleshooting a MySQL Installation Under Windows”, if you encounter
difficulties during installation.
For more information about stopping or removing a MySQL Windows service, see Section 5.5.2.2,
“Starting Multiple MySQL Instances as Windows Services”.

2.10.4.8 Testing The MySQL Installation
You can test whether the MySQL server is working by executing any of the following commands:
shell>
shell>
shell>
shell>

"C:\Program
"C:\Program
"C:\Program
"C:\Program

Files\MySQL\MySQL
Files\MySQL\MySQL
Files\MySQL\MySQL
Files\MySQL\MySQL

Server
Server
Server
Server

5.0\bin\mysqlshow"
5.0\bin\mysqlshow" -u root mysql
5.0\bin\mysqladmin" version status proc
5.0\bin\mysql" test

If mysqld is slow to respond to TCP/IP connections from client programs, there is probably a problem
with your DNS. In this case, start mysqld with the --skip-name-resolve option and use only
localhost and IP addresses in the Host column of the MySQL grant tables. (Be sure that an account
exists that specifies an IP address or you may not be able to connect.)
You can force a MySQL client to use a named-pipe connection rather than TCP/IP by specifying the -pipe or --protocol=PIPE option, or by specifying . (period) as the host name. Use the --socket
option to specify the name of the pipe if you do not want to use the default pipe name.
Note that if you have set a password for the root account, deleted the anonymous account, or created
a new user account, then to connect to the MySQL server you must use the appropriate -u and -p
options with the commands shown previously. See Section 4.2.2, “Connecting to the MySQL Server”.
For more information about mysqlshow, see Section 4.5.6, “mysqlshow — Display Database, Table,
and Column Information”.

2.10.5 Troubleshooting a MySQL Installation Under Windows
When installing and running MySQL for the first time, you may encounter certain errors that prevent the
MySQL server from starting. The purpose of this section is to help you diagnose and correct some of
these errors.
Your first resource when troubleshooting server issues is the error log. The MySQL server uses the
error log to record information relevant to the error that prevents the server from starting. The error log
is located in the data directory specified in your my.ini file. The default data directory location is C:
\Program Files\MySQL\MySQL Server 5.0\data. See Section 5.4.1, “The Error Log”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting a MySQL Installation Under Windows

Another source of information regarding possible errors is the console messages displayed when
the MySQL service is starting. Use the NET START MySQL command from the command line after
installing mysqld as a service to see any error messages regarding the starting of the MySQL server
as a service. See Section 2.10.4.7, “Starting MySQL as a Windows Service”.
The following examples show other common error messages you may encounter when installing
MySQL and starting the server for the first time:
• If the MySQL server cannot find the mysql privileges database or other critical files, you may see
these messages:
System error 1067 has occurred.
Fatal error: Can't open privilege tables: Table 'mysql.host' doesn't exist

These messages often occur when the MySQL base or data directories are installed in different
locations than the default locations (C:\Program Files\MySQL\MySQL Server 5.0 and C:
\Program Files\MySQL\MySQL Server 5.0\data, respectively).
This situation may occur when MySQL is upgraded and installed to a new location, but the
configuration file is not updated to reflect the new location. In addition, there may be old and
new configuration files that conflict. Be sure to delete or rename any old configuration files when
upgrading MySQL.
If you have installed MySQL to a directory other than C:\Program Files\MySQL\MySQL
Server 5.0, you need to ensure that the MySQL server is aware of this through the use of a
configuration (my.ini) file. The my.ini file needs to be located in your Windows directory, typically
C:\WINDOWS. You can determine its exact location from the value of the WINDIR environment
variable by issuing the following command from the command prompt:
shell> echo %WINDIR%

An option file can be created and modified with any text editor, such as Notepad. For example, if
MySQL is installed in E:\mysql and the data directory is D:\MySQLdata, you can create the option
file and set up a [mysqld] section to specify values for the basedir and datadir options:
[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 path names are specified in option files using (forward) slashes rather than
backslashes. If you do use backslashes, double them:
[mysqld]
# set basedir to your installation path
basedir=C:\\Program Files\\MySQL\\MySQL Server 5.0
# set datadir to the location of your data directory
datadir=D:\\MySQLdata

The rules for use of backslash in option file values are given in Section 4.2.6, “Using Option Files”.
If you change the datadir value in your MySQL configuration file, you must move the contents of
the existing MySQL data directory before restarting the MySQL server.
See Section 2.10.4.2, “Creating an Option File”.
• If you reinstall or upgrade MySQL without first stopping and removing the existing MySQL service
and install MySQL using the MySQL Configuration Wizard, you may see this error:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Windows Postinstallation Procedures

Error: Cannot create Windows service for MySql. Error: 0

This occurs when the Configuration Wizard tries to install the service and finds an existing service
with the same name.
One solution to this problem is to choose a service name other than mysql when using the
configuration wizard. This enables the new service to be installed correctly, but leaves the outdated
service in place. Although this is harmless, it is best to remove old services that are no longer in use.
To permanently remove the old mysql service, execute the following command as a user with
administrative privileges, on the command-line:
shell> sc delete mysql
[SC] DeleteService SUCCESS

If the sc utility is not available for your version of Windows, download the delsrv utility from http://
www.microsoft.com/windows2000/techinfo/reskit/tools/existing/delsrv-o.asp and use the delsrv
mysql syntax.

2.10.6 Windows Postinstallation Procedures
On Windows, you need not create the data directory and the grant tables. MySQL Windows
distributions include the grant tables with a set of preinitialized accounts in the mysql database under
the data directory.
Regarding passwords, if you installed MySQL using the Windows Installation Wizard, you may have
already assigned passwords to the accounts. (See Section 2.10.2.1, “Using the MySQL Installation
Wizard”.) Otherwise, use the password-assignment procedure given in Section 2.18.4, “Securing the
Initial MySQL Accounts”.
Before assigning passwords, you might want to try running some client programs to make sure that
you can connect to the server and that it is operating properly. Make sure that the server is running
(see Section 2.10.4.4, “Starting the Server for the First Time”). You can also set up a MySQL service
that runs automatically when Windows starts (see Section 2.10.4.7, “Starting MySQL as a Windows
Service”).
These instructions assume that your current location is the MySQL installation directory and that it has
a bin subdirectory containing the MySQL programs used here. If that is not true, adjust the command
path names accordingly.
If you installed MySQL using the Windows installation Wizard (see Section 2.10.2.1, “Using the MySQL
Installation Wizard”), the default installation directory is C:\Program Files\MySQL\MySQL Server
5.0:
C:\> cd "C:\Program Files\MySQL\MySQL Server 5.0"

A common installation location for installation from a Zip package is C:\mysql:
C:\> cd C:\mysql

Alternatively, add the bin directory to your PATH environment variable setting. That enables your
command interpreter to find MySQL programs properly, so that you can run a program by typing only
its name, not its path name. See Section 2.10.4.6, “Customizing the PATH for MySQL Tools”.
With the server running, issue the following commands to verify that you can retrieve information from
the server. The output should be similar to that shown here.
Use mysqlshow to see what databases exist:
C:\> bin\mysqlshow

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Windows Postinstallation Procedures

+--------------------+
|
Databases
|
+--------------------+
| information_schema |
| mysql
|
| test
|
+--------------------+

The list of installed databases may vary, but will always include the minimum of mysql and
information_schema.
The preceding command (and commands for other MySQL programs such as mysql) may not work if
the correct MySQL account does not exist. For example, the program may fail with an error, or you may
not be able to view all databases. If you installed using the MSI packages and used the MySQL Server
Instance Config Wizard, then the root user will have been created automatically with the password
you supplied. In this case, you should use the -u root and -p options. (You will also need to use the
-u root and -p options if you have already secured the initial MySQL accounts.) With -p, you will be
prompted for the root password. For example:
C:\> bin\mysqlshow -u root -p
Enter password: (enter root password here)
+--------------------+
|
Databases
|
+--------------------+
| information_schema |
| mysql
|
| test
|
+--------------------+

If you specify a database name, mysqlshow displays a list of the tables within the database:
C:\> bin\mysqlshow mysql
Database: mysql
+---------------------------+
|
Tables
|
+---------------------------+
| columns_priv
|
| db
|
| func
|
| help_category
|
| help_keyword
|
| help_relation
|
| help_topic
|
| host
|
| proc
|
| procs_priv
|
| tables_priv
|
| time_zone
|
| time_zone_leap_second
|
| time_zone_name
|
| time_zone_transition
|
| time_zone_transition_type |
| user
|
+---------------------------+

Use the mysql program to select information from a table in the mysql database:
C:\> bin\mysql -e "SELECT User, Host FROM mysql.user" mysql
+------+-----------+
| User | Host
|
+------+-----------+
| root | localhost |
+------+-----------+

For more information about mysql and mysqlshow, see Section 4.5.1, “mysql — The MySQL
Command-Line Tool”, and Section 4.5.6, “mysqlshow — Display Database, Table, and Column
Information”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL on Windows

If you are running a version of Windows that supports services, you can set up the MySQL server
to run automatically when Windows starts. See Section 2.10.4.7, “Starting MySQL as a Windows
Service”.

2.10.7 Upgrading MySQL on Windows
To upgrade MySQL on Windows, follow these steps:
1. Review Section 2.19.1, “Upgrading MySQL”, for additional information on upgrading MySQL that is
not specific to Windows.
2. You should always back up your current MySQL installation before performing an upgrade. See
Section 7.2, “Database Backup Methods”.
3. Download the latest Windows distribution of MySQL from http://dev.mysql.com/downloads/.
4. Before upgrading MySQL, you must stop the server. If the server is installed as a service, stop the
service with the following command from the command prompt:
shell> NET STOP MySQL

If you are not running the MySQL server as a service, use mysqladmin to stop it. For example,
before upgrading from MySQL 4.1 to 5.0, use mysqladmin from MySQL 4.1 as follows:
shell> "C:\Program Files\MySQL\MySQL Server 4.1\bin\mysqladmin" -u root shutdown

Note
If the MySQL root user account has a password, you need to invoke
mysqladmin with the -p option and enter the password when prompted.
5. Before upgrading to MySQL 5.0 from a version previous to 4.1.5, or from a version of MySQL
installed from a Zip archive to a version of MySQL installed with the MySQL Installation Wizard, you
must first manually remove the previous installation and MySQL service (if the server is installed as
a service).
To remove the MySQL service, use the following command:
shell> C:\mysql\bin\mysqld --remove

If you do not remove the existing service, the MySQL Installation Wizard may fail to properly
install the new MySQL service.
6. If you are using the MySQL Installation Wizard, start the wizard as described in Section 2.10.2.1,
“Using the MySQL Installation Wizard”.
7. If you are installing MySQL from a Zip archive, extract the archive. You may either overwrite your
existing MySQL installation (usually located at C:\mysql), or install it into a different directory,
such as C:\mysql5. Overwriting the existing installation is recommended.
8. If you were running MySQL as a Windows service and you had to remove the service earlier in this
procedure, reinstall the service. (See Section 2.10.4.7, “Starting MySQL as a Windows Service”.)
9. Restart the server. For example, use NET START MySQL if you run MySQL as a service, or invoke
mysqld directly otherwise.
10. As Administrator, run mysql_upgrade to check your tables, attempt to repair them if necessary,
and update your grant tables if they have changed so that you can take advantage of any new
capabilities. See Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Installing MySQL from Source on Windows

11. If you encounter errors, see Section 2.10.5, “Troubleshooting a MySQL Installation Under
Windows”.

2.10.8 Installing MySQL from Source on Windows
These instructions describe how to build binaries from source for MySQL 5.0 on Windows. Instructions
are provided for building binaries from a standard source distribution or from the Bazaar tree that
contains the latest development source.
Note
The instructions here are strictly for users who want to test MySQL on Microsoft
Windows from the latest source distribution or from the Bazaar tree. For
production use, we do 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 Oracle
Corporation. Instructions for installing binary distributions are available in
Section 2.10, “Installing MySQL on Microsoft Windows”.
To build MySQL on Windows from source, you must satisfy the following system, compiler, and
resource requirements:
• Windows 2000, Windows XP, or newer version.
Windows Vista is supported when using Visual Studio 2005 provided you have installed the following
updates:
• Microsoft Visual Studio 2005 Professional Edition - ENU Service Pack 1 (KB926601)
• Security Update for Microsoft Visual Studio 2005 Professional Edition - ENU (KB937061)
• Update for Microsoft Visual Studio 2005 Professional Edition - ENU (KB932232)
• To build from the standard source distribution, you will need CMake, which can be downloaded
from http://www.cmake.org. After installing, modify your PATH environment variable to include the
directory where cmake is located.
• Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio 2005 (8.0)
compiler system.
• If you are using Visual C++ 2005 Express Edition, you must also install an appropriate Platform
SDK. More information and links to downloads for various Windows platforms is available from http://
www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb.
• If you are compiling from a Bazaar tree or making changes to the parser, you need bison for
Windows, which can be downloaded from http://gnuwin32.sourceforge.net/packages/bison.htm.
Download the package labeled “Complete package, excluding sources”. After installing the package,
modify your PATH environment variable to include the directory where bison is located.
• Cygwin might be necessary if you want to run the test script or package the compiled binaries and
support files into a Zip archive. (Cygwin is needed only to test or package the distribution, not to build
it.) Cygwin is available from http://cygwin.com.
• 3GB to 5GB of disk space.
There are three solutions available for building from the source code on Windows:
• Build from the standard MySQL source distribution. For this you will need CMake and Visual C++
Express Edition or Visual Studio. Using this method you can select the storage engines that are
included in your build. To use this method, see Section 2.10.8.1, “Building MySQL from the Standard
Source Distribution”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL from Source on Windows

• Build from the MySQL Windows source distribution. The Windows source distribution includes readymade Visual Studio solution files that enable support for all storage engines (except NDB). To build
using using method you only need Visual C++ Express Edition or Visual Studio. To use this method,
see Section 2.10.8.2, “Building MySQL from a Windows Source Distribution”.
• Build directly from the Bazaar source repository. For this you will need CMake, Visual C++ Express
Edition or Visual Studio, and bison. For this method you need to create the distribution on a Unix
system and then copy the generated files to your Windows build environment. To use this method,
see Section 2.10.8.5, “Creating a Windows Source Package from the Bazaar Repository”.
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.6.1, “MySQL Mailing Lists”.

2.10.8.1 Building MySQL from the Standard Source Distribution
You can build MySQL on Windows by using a combination of cmake and Microsoft Visual Studio .NET
2003 (7.1), Microsoft Visual Studio 2005 (8.0) or Microsoft Visual C++ 2005 Express Edition. You must
have the appropriate Microsoft Platform SDK installed.
Note
To compile from the source code using CMake you must use the standard
source distribution (for example, mysql-5.0.96.tar.gz). You build from the
same distribution as used to build MySQL on Unix, Linux and other platforms.
Do not use the Windows Source distributions as they do not contain the
necessary configuration script and other files.
Follow this procedure to build MySQL:
1. If you are installing from a packaged source distribution, create a work directory (for example, C:
\workdir), and unpack the source distribution there using WinZip or another Windows tool that
can read .zip files. This directory is the work directory in the following instructions.
2. If you are installing from a Bazaar tree, the root directory of that tree is the work directory in the
following instructions.
3. Using a command shell, navigate to the work directory and run the following command:
C:\workdir>win\configure.js options

If you have associated the .js file extension with an application such as a text editor, then you may
need to use the following command to force configure.js to be executed as a script:
C:\workdir>cscript win\configure.js options

These options are available for configure.js:
• WITH_INNOBASE_STORAGE_ENGINE: Enable the InnoDB storage engine.
• WITH_PARTITION_STORAGE_ENGINE: Enable user-defined partitioning.
• WITH_ARCHIVE_STORAGE_ENGINE: Enable the ARCHIVE storage engine.
• WITH_BLACKHOLE_STORAGE_ENGINE: Enable the BLACKHOLE storage engine.
• WITH_EXAMPLE_STORAGE_ENGINE: Enable the EXAMPLE storage engine.
• WITH_FEDERATED_STORAGE_ENGINE: Enable the FEDERATED storage engine.
• MYSQL_SERVER_SUFFIX=suffix: Server suffix, default none.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL from Source on Windows

• COMPILATION_COMMENT=comment: Server comment, default "Source distribution".
• MYSQL_TCP_PORT=port: Server port, default 3306.
• DISABLE_GRANT_OPTIONS: Disables the the --bootstrap, --skip-grant-tables, and -init-file options for mysqld. This option is available as of MySQL 5.0.36.
For example (type the command on one line):
C:\workdir>win\configure.js WITH_INNOBASE_STORAGE_ENGINE »
WITH_PARTITION_STORAGE_ENGINE MYSQL_SERVER_SUFFIX=-pro

4. From the work directory, execute the win\build-vs8.bat or win\build-vs71.bat file,
depending on the version of Visual Studio you have installed. The script invokes CMake, which
generates the mysql.sln solution file you will need to build MySQL using Visual Studio..
You can also use win\build-vs8_x64.bat to build the 64-bit version of MySQL. However, you
cannot build the 64-bit version with Visual Studio Express Edition. You must use Visual Studio 2005
(8.0) or higher.
5. From the work directory, open the generated mysql.sln file with Visual Studio and select
the proper configuration using the Configuration menu. The menu provides Debug, Release,
RelwithDebInfo, MinRelInfo options. Then select Solution > Build to build the solution.
The build process will take some time. Please be patient.
Remember the configuration that you use in this step. It is important later when you run the test
script because that script needs to know which configuration you used.
6. You should test you build before installation. See Section 2.10.8.4, “Testing a Windows Source
Build”.
7. To install, use the instructions in Section 2.10.8.3, “Installing MySQL from a Source Build on
Windows”.

2.10.8.2 Building MySQL from a Windows Source Distribution
The Windows source distribution includes the necessary solution file and the vcproj files required
to build each component. Using this method you are not able to select the storage engines that are
included in your build.
Note
VC++ workspace files for MySQL 4.1 and above are compatible with Microsoft
Visual Studio 7.1 and tested by us before each release.
Follow this procedure to build MySQL:
1. Create a work directory (for example, C:\workdir).
2. Unpack the source distribution in the aforementioned directory using WinZip or another Windows
tool that can read .zip files.
3. Start Visual Studio .Net 2003 (7.1).
4. From the File menu, select Open Solution....
5. Open the mysql.sln solution you find in the work directory.
6. From the Build menu, select Configuration Manager....
7. In the Active Solution Configuration pop-up menu, select the configuration to use. You likely
want to use one of nt (normal server), Max nt (more engines and features), or Debug configuration.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL from Source on Windows

8. From the Build menu, select Build Solution.
9. 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.
10. You should test you build before installation. See Section 2.10.8.4, “Testing a Windows Source
Build”.
11. To install, use the instructions in Section 2.10.8.3, “Installing MySQL from a Source Build on
Windows”.

2.10.8.3 Installing MySQL from a Source Build on Windows
When you are satisfied that the program you have built is working correctly, stop the server. Now you
can install the distribution. There are two ways to do this, either by using the supplied installation script
or by copying the files individually by hand.
To use the script method you must have Cygwin installed as the script is a Shell script. To execute
the installation process, run the make_win_bin_dist script in the scripts directory of the MySQL
source distribution (see Section 4.4.2, “make_win_bin_dist — Package MySQL Distribution as Zip
Archive”). This is a shell script, so you must have Cygwin installed if you want to use it. It creates a
Zip archive of the built executables and support files that you can unpack to your desired installation
location.
It is also possible to install MySQL by copying directories and files manually:
1. Create the directories where you want to install MySQL. For example, to install into C:\mysql, use
these commands:
shell>
shell>
shell>
shell>
shell>

mkdir
mkdir
mkdir
mkdir
mkdir

C:\mysql
C:\mysql\bin
C:\mysql\data
C:\mysql\share
C:\mysql\scripts

If you want to compile other clients and link them to MySQL, you should also create several
additional directories:
shell>
shell>
shell>
shell>

mkdir
mkdir
mkdir
mkdir

C:\mysql\include
C:\mysql\lib
C:\mysql\lib\debug
C:\mysql\lib\opt

If you want to benchmark MySQL, create this directory:
shell> mkdir C:\mysql\sql-bench

Benchmarking requires Perl support. See Section 2.22, “Perl Installation Notes”.
2. From the work directory, copy into the C:\mysql directory the following directories:
shell> 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:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL from Source on Windows

C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>
C:\workdir>

copy
copy
copy
copy
copy
copy
copy
copy

lib_debug\mysqlclient.lib C:\mysql\lib\debug
lib_debug\libmysql.* C:\mysql\lib\debug
lib_debug\zlib.* C:\mysql\lib\debug
lib_release\mysqlclient.lib C:\mysql\lib\opt
lib_release\libmysql.* C:\mysql\lib\opt
lib_release\zlib.* C:\mysql\lib\opt
include\*.h C:\mysql\include
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

After installation, set up and start the server in the same way as for binary Windows distributions. See
Section 2.10, “Installing MySQL on Microsoft Windows”.

2.10.8.4 Testing a Windows Source Build
You should test the server that you have built from source before using the distribution.
To test the server you need to run the built mysqld. By default, using the source build examples, the
MySQL base directory and data directory are C:\mysql and C:\mysql\data. If you want to test
your server using the source tree root directory and its data directory as the base directory and data
directory, you need to tell the server their path names. You can either do this on the command line
with the --basedir and --datadir options, or by placing appropriate options in an option file. (See
Section 4.2.6, “Using Option Files”.) If you have an existing data directory elsewhere that you want to
use, you can specify its path name instead.
When the server is running in standalone fashion or as a service based on your configuration, try to
connect to it from the mysql interactive command-line utility.
You can also run the standard test script, mysql-test-run.pl. This script is written in Perl, so you'll
need either Cygwin or ActiveState Perl to run it. You may also need to install the modules required
by the script. To run the test script, change location into the mysql-test directory under the work
directory, set the MTR_VS_CONFIG environment variable to the configuration you selected earlier (or
use the --vs-config option), and invoke mysql-test-run.pl. For example (using Cygwin and the
bash shell):
shell>
shell>
shell>
shell>

cd mysql-test
export MTR_VS_CONFIG=debug
./mysql-test-run.pl --force --timer
./mysql-test-run.pl --force --timer --ps-protocol

2.10.8.5 Creating a Windows Source Package from the Bazaar Repository
To create a Windows source package from the current Bazaar source tree, use the instructions here.
This procedure must be performed on a system running a Unix or Unix-like operating system because
some of the configuration and build steps require tools that work only on Unix. For example, the
following procedure is known to work well on Linux.
1. Copy the Bazaar source tree for MySQL 5.0. For instructions on how to do this, see Section 2.17.2,
“Installing MySQL Using a Development Source Tree”.
2. 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

3. After making sure that the build process completed successfully, run the following utility script from
top-level directory of your source tree:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on OS X

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. See Section 4.4.3,
“make_win_src_distribution — Create Source Distribution for Windows”, for a list of
permissible options.
By default, make_win_src_distribution creates a Zip-format archive with the name
mysql-VERSION-win-src.zip, where VERSION represents the version of your MySQL source
tree.
4. Copy or upload the Windows source package that you have just created to your Windows machine.
To compile it, use the instructions in Section 2.10.8.2, “Building MySQL from a Windows Source
Distribution”.

2.11 Installing MySQL on OS X
You can install MySQL on OS X 10.3.x (“Panther”) or newer using a OS X binary package in DMG
format instead of the binary tarball distribution. Please note that older versions of OS X (for example,
10.1.x or 10.2.x) are not supported by this package.
The package is located inside a disk image (.dmg) file that you first need to mount by double-clicking
its icon in the Finder. It should then mount the image and display its contents.
When installing from the package version, you should also install the MySQL Preference Pane, which
will enable you to control the startup and execution of your MySQL server from System Preferences.
To obtain MySQL, see Section 2.5, “How to Get MySQL”.
Note
Before proceeding with the installation, be sure to shut down all running MySQL
server instances by using either the MySQL Manager Application (on OS X
Server) or mysqladmin shutdown on the command line.
To actually install the MySQL DMG file, double-click the package icon. This launches the OS X
Package Installer, which guides you through the installation of MySQL.
Due to a bug in the 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 OS X MySQL DMG package installs itself into /usr/local/mysql-VERSION and also installs
a symbolic link, /usr/local/mysql, that points to the new location. If a directory named /usr/
local/mysql exists, it is renamed to /usr/local/mysql.bak first. Additionally, the installer
creates the grant tables in the mysql database by executing mysql_install_db.
The installation layout is similar to that of a tar file binary distribution; all MySQL binaries are located
in the directory /usr/local/mysql/bin. The MySQL socket file is created as /tmp/mysql.sock
by default. See Section 2.7, “Installation Layouts”.
MySQL installation requires a OS X user account named mysql. A user account with this name should
exist by default on OS X 10.2 and up.
If you are running OS X Server, a version of MySQL should already be installed. The following table
shows the versions of MySQL that ship with OS X Server versions.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on OS X

OS X Server Version

MySQL Version

10.2-10.2.2

3.23.51

10.2.3-10.2.6

3.23.53

10.3

4.0.14

10.3.2

4.0.16

10.4.0

4.1.10a

This manual section covers the installation of the official MySQL OS X DMG only. Make sure to read
Apple's help information about installing MySQL: Run the “Help View” application, select “OS X Server”
help, do a search for “MySQL,” and read the item entitled “Installing MySQL.”
For preinstalled versions of MySQL on OS X Server, note especially that you should start mysqld with
safe_mysqld instead of mysqld_safe if MySQL is older than version 4.0.
If you previously used Marc Liyanage's MySQL packages for OS X from http://www.entropy.ch, you can
simply follow the update instructions for packages using the binary installation layout as given on his
pages.
If you are upgrading from Marc's 3.23.x versions or from the OS X Server version of MySQL to the
official MySQL DMG, you also need to convert the existing MySQL privilege tables to the current
format, because some new security privileges have been added. See Section 4.4.9, “mysql_upgrade
— Check Tables for MySQL Upgrade”.
If you want MySQL to start automatically during system startup, you also need to install the MySQL
Startup Item. It is part of the OS X installation disk images as a separate installation package. Simply
double-click the MySQLStartupItem.pkg icon and follow the instructions to install it. The Startup Item
need be installed only once. There is no need to install it each time you upgrade the MySQL package
later.
The Startup Item for MySQL is installed into /Library/StartupItems/MySQLCOM. (Before MySQL
4.1.2, the location was /Library/StartupItems/MySQL, but that collided with the MySQL Startup
Item installed by OS X Server.) Startup Item installation adds a variable MYSQLCOM=-YES- to the
system configuration file /etc/hostconfig. If you want to disable the automatic startup of MySQL,
simply change this variable to MYSQLCOM=-NO-.
On OS X Server, the default MySQL installation uses the variable MYSQL in the /etc/hostconfig
file. The MySQL 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 Startup Item. However, it does not
shut down a running MySQL server. You should do that yourself.
After the installation, you can start up MySQL by running the following commands in a terminal window.
You must have administrator privileges to perform this task.
If you have installed the Startup Item, use this command:
shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start
(Enter your password, if necessary)
(Press Control-D or enter "exit" to exit the shell)

If you do not use the Startup Item, enter the following command sequence:
shell>
shell>
(Enter
(Press
shell>
(Press

cd /usr/local/mysql
sudo ./bin/mysqld_safe
your password, if necessary)
Control-Z)
bg
Control-D or enter "exit" to exit the shell)

You should be able to connect to the MySQL server, for example, by running /usr/local/mysql/
bin/mysql.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Linux Using RPM Packages

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.18.4, “Securing the Initial MySQL Accounts”.
You might want to add aliases to your shell's resource file to make it easier to access commonly used
programs such as mysql and mysqladmin from the command line. The syntax for bash is:
alias mysql=/usr/local/mysql/bin/mysql
alias mysqladmin=/usr/local/mysql/bin/mysqladmin

For tcsh, use:
alias mysql /usr/local/mysql/bin/mysql
alias mysqladmin /usr/local/mysql/bin/mysqladmin

Even better, add /usr/local/mysql/bin to your PATH environment variable. You can do this by
modifying the appropriate startup file for your shell. For more information, see Section 4.2.1, “Invoking
MySQL Programs”.
If you are upgrading an existing installation, note that installing a new MySQL DMG does not remove
the directory of an older installation. Unfortunately, the 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.12 Installing MySQL on Linux Using RPM Packages
The recommended way to install MySQL on RPM-based Linux distributions is by using the RPM
packages. The RPMs that we provide to the community should work on all versions of Linux that
support RPM packages and use glibc 2.3. We also provide RPMs with binaries that are statically
linked to a patched version of glibc 2.2, but only for the x86 (32-bit) architecture. To obtain RPM
packages, see Section 2.5, “How to Get MySQL”.
For non-RPM Linux distributions, you can install MySQL using a .tar.gz package. See Section 2.16,
“Installing MySQL on Unix/Linux Using Generic Binaries”.
We do provide some platform-specific RPMs; the difference between a platform-specific RPM and a
generic RPM is that a platform-specific RPM is built on the targeted platform and is linked dynamically
whereas a generic RPM is linked statically with LinuxThreads.
Note
RPM distributions of MySQL are also provided by other vendors. Be aware that
they may differ from those built by us in features, capabilities, and conventions
(including communication setup), and that the instructions in this manual do
not necessarily apply to installing them. The vendor's instructions should be
consulted instead. Because of these differences, RPM packages built by us
check whether such RPMs built by other vendors are installed. If so, the RPM
does not install and produces a message explaining this.
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.20.1.2, “Linux Binary Distribution Notes”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Linux Using RPM Packages

In most cases, you need to install only the MySQL-server and MySQL-client packages to get a
functional MySQL installation. The other packages are not required for a standard installation.
For upgrades, if your installation was originally produced by installing multiple RPM packages, it is
best to upgrade all the packages, not just some. For example, if you previously installed the server and
client RPMs, do not upgrade just the server RPM.
If you get a dependency failure when trying to install MySQL packages (for example, error:
removing these packages would break dependencies: libmysqlclient.so.10 is
needed by ...), you should also install the MySQL-shared-compat package, which includes the
shared libraries for older releases for backward compatibility.
Some Linux distributions still ship with MySQL 3.23 and they usually link applications dynamically to
save disk space. If these shared libraries are in a separate package (for example, MySQL-shared),
it is sufficient to simply leave this package installed and just upgrade the MySQL server and client
packages (which are statically linked and do not depend on the shared libraries). For distributions that
include the shared libraries in the same package as the MySQL server (for example, Red Hat Linux),
you could either install our 3.23 MySQL-shared RPM, or use the MySQL-shared-compat package
instead. (Do not install both.)
The RPM packages shown in the following list are available. The names shown here use a suffix
of .glibc23.i386.rpm, but particular packages can have different suffixes, as described later.
Packages that have community in the names are Community Server builds, available from MySQL
5.0.27 on.
• MySQL-server-VERSION.glibc23.i386.rpm, MySQL-servercommunity-VERSION.glibc23.i386.rpm
The MySQL server. You need this unless you only want to connect to a MySQL server running on
another machine.
• MySQL-client-VERSION.glibc23.i386.rpm, MySQL-clientcommunity-VERSION.glibc23.i386.rpm
The standard MySQL client programs. You probably always want to install this package.
• MySQL-bench-VERSION.glibc23.i386.rpm
Tests and benchmarks. Requires Perl and the DBI and DBD::mysql modules.
• MySQL-devel-VERSION.glibc23.i386.rpm, MySQL-develcommunity-VERSION.glibc23.i386.rpm
The libraries and include files that are needed if to compile other MySQL clients, such as the Perl
modules. Install this RPM if you intend to compile C API applications.
• MySQL-debuginfo-VERSION.glibc23.i386.rpm, MySQL-communitydebuginfo-VERSION.glibc23.i386.rpm
Debugging information. debuginfo RPMs are never needed to use MySQL software; this is true
both for the server and for client programs. However, they contain additional information that might
be needed by a debugger to analyze a crash.
• MySQL-shared-VERSION.glibc23.i386.rpm, MySQL-sharedcommunity-VERSION.glibc23.i386.rpm
The shared libraries (libmysqlclient.so*) that certain languages and applications need to
dynamically load and use MySQL. It contains single-threaded and thread-safe libraries. Install this
RPM if you intend to compile or run C API applications that depend on the shared client library. If you
install this package, do not install the MySQL-shared-compat package.
• MySQL-shared-compat-VERSION.glibc23.i386.rpm
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Linux Using RPM Packages

The shared libraries for older releases, up to the current release. It contains single-threaded and
thread-safe libraries. Install this package instead of MySQL-shared if you have applications installed
that are dynamically linked against older versions of MySQL but you want to upgrade to the current
version without breaking the library dependencies.
• MySQL-clustermanagement-communityVERSION.glibc23.i386.rpm,
MySQL-clusterstorage-communityVERSION.glibc23.i386.rpm, MySQLclustertools-communityVERSION.glibc23.i386.rpm, MySQL-clusterextracommunityVERSION.glibc23.i386.rpm
Packages that contain additional files for MySQL Cluster installations. These are platform-specific
RPMs, in contrast to the platform-independent ndb-xxx RPMs.
Note
The MySQL-clustertools RPM requires a working installation of perl
and the DBI and HTML::Template packages. See Section 2.22, “Perl
Installation Notes”, and Section 17.4.18, “ndb_size.pl — NDBCLUSTER
Size Requirement Estimator”, for more information.
• MySQL-ndb-management-VERSION.glibc23.i386.rpm, MySQL-ndbstorage-VERSION.glibc23.i386.rpm, MySQL-ndb-tools-VERSION.glibc23.i386.rpm,
MySQL-ndb-extra-VERSION.glibc23.i386.rpm
Packages that contain additional files for MySQL Cluster installations. These are platformindependent RPMs, in contrast to the platform-specific clusterxxx-community RPMs.
• MySQL-test-community-VERSION.glibc23.i386.rpm
The MySQL test suite.
• MySQL-VERSION.src.rpm
The source code for all of the previous packages. It can also be used to rebuild the RPMs on other
architectures (for example, SPARC).
The suffix of RPM package names (following the VERSION value) has the following syntax:
[.PLATFORM].CPU.rpm

The PLATFORM and CPU values indicate the type of system for which the package is built. PLATFORM, if
present, indicates the platform, and CPU indicates the processor type or family.
If the PLATFORM value is missing (for example, MySQL-server-VERSION.i386.rpm), the package
is statically linked against a version of glibc 2.2 that has been patched to handle larger numbers of
threads with larger stack sizes than the stock library.
If PLATFORM is present, the package is dynamically linked against glibc 2.3 and the PLATFORM value
indicates whether the package is platform independent or intended for a specific platform, as shown in
the following table.
PLATFORM Value

Intended Use

glibc23

Platform independent, should run on any Linux distribution that supports
glibc 2.3

rhel4, rhel5

Red Hat Enterprise Linux 4 or 5

sles10

SuSE Linux Enterprise Server 10

The CPU value indicates the processor type or family for which the package is built.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Linux Using RPM Packages

CPU Value

Intended Processor Type or Family

i386, i586, i686

Pentium processor or better, 32 bit

x86_64

64-bit x86 processor

ia64

Itanium (IA-64) processor

To see all files in an RPM package (for example, a MySQL-server RPM), run a command like this:
shell> rpm -qpl MySQL-server-VERSION.glibc23.i386.rpm

To perform a standard minimal installation, install the server and client RPMs:
shell> rpm -i MySQL-server-VERSION.glibc23.i386.rpm
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm

To install only the client programs, install just the client RPM:
shell> rpm -i MySQL-client-VERSION.glibc23.i386.rpm

RPM provides a feature to verify the integrity and authenticity of packages before installing them. To
learn more about this feature, see Section 2.6, “Verifying Package Integrity Using MD5 Checksums or
GnuPG”.
The server RPM places data under the /var/lib/mysql directory. The RPM also creates a login
account for a user named mysql (if one does not exist) to use for running the MySQL server, and
creates the appropriate entries in /etc/init.d/ to start the server automatically at boot time. (This
means that if you have performed a previous installation and have made changes to its startup script,
you may want to make a copy of the script so that you do not lose it when you install a newer RPM.)
See Section 2.18.5, “Starting and Stopping MySQL Automatically”, for more information on how
MySQL can be started automatically at system startup.
If the RPM files that you install include MySQL-server, the mysqld server should be up and running
after installation. You should be able to start using MySQL.
If something goes wrong, you can find more information in the binary installation section. See
Section 2.16, “Installing MySQL on Unix/Linux Using Generic Binaries”.
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.18.4, “Securing the Initial MySQL Accounts”.
During RPM installation, a user named mysql and a group named mysql are created on the system.
This is done using the useradd, groupadd, and usermod commands. Those commands require
appropriate administrative privileges, which is ensured for locally managed users and groups (as listed
in the /etc/passwd and /etc/group files) by the RPM installation process being run by root.
If you log in as the mysql user, you may find that MySQL displays “Invalid (old?) table or
database name” errors that mention .mysqlgui, lost+found, .mysqlgui, .bash_history,
.fonts.cache-1, .lesshst, .mysql_history, .profile, .viminfo, and similar files created
by MySQL or operating system utilities. You can safely ignore these error messages or remove the files
or directories that cause them if you do not need them.
For nonlocal user management (LDAP, NIS, and so forth), the administrative tools may require
additional authentication (such as a password), and will fail if the installing user does not provide this
authentication. Even if they fail, the RPM installation will not abort but succeed, and this is intentional.
If they failed, some of the intended transfer of ownership may be missing, and it is recommended that
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Solaris

the system administrator then manually ensures some appropriate user andgroup exists and manually
transfers ownership following the actions in the RPM spec file.

2.13 Installing MySQL on Solaris
To obtain a binary MySQL distribution for Solaris in tarball or PKG format, http://dev.mysql.com/
downloads/mysql/5.0.html.
If you install MySQL using a binary tarball distribution on Solaris, you may run into trouble even before
you get the MySQL distribution unpacked, as the Solaris tar cannot handle long file names. This
means that you may see errors when you try to unpack MySQL.
If this occurs, you must use GNU tar (gtar) to unpack the distribution.
You can install MySQL on Solaris using a binary package in PKG format instead of the binary tarball
distribution. Before installing using the binary PKG format, you should create the mysql user and
group, for example:
groupadd mysql
useradd -g mysql -s /bin/false mysql

Some basic PKG-handling commands follow:
• To add a package:
pkgadd -d package_name.pkg

• To remove a package:
pkgrm package_name

• To get a full list of installed packages:
pkginfo

• To get detailed information for a package:
pkginfo -l package_name

• To list the files belonging to a package:
pkgchk -v package_name

• To get packaging information for an arbitrary file:
pkgchk -l -p file_name

For additional information about installing MySQL on Solaris, see Section 2.20.3, “Solaris Notes”.

2.14 Installing MySQL on i5/OS
The i5/OS POWER MySQL package was created in cooperation with IBM. MySQL works within the
Portable Application Solution Environment (PASE) on the System i series of hardware and will also
provide database services for the Zend Core for i5/OS.
MySQL for i5/OS is provided both as a tar file and as a save file (.savf) package that can be
downloaded and installed directly without any additional installation steps required. To install MySQL
using the tar file, see Section 2.16, “Installing MySQL on Unix/Linux Using Generic Binaries”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on i5/OS

MySQL is only supported on i5/OS V5R4 or later releases. The i5/OS PASE must be installed for
MySQL to operate. You must be able to login as a user in *SECOFR class.
You should the installation notes and tips for i5/OS before starting installation. See i5/OS Installation
Notes.
Before Installation:
Note
The installation package will use an existing configuration if you have previously
installed MySQL (which is identified by looking for the file /etc/my.cnf). The
values for the data directory (DATADIR) and owner of the MySQL files (USRPRF)
specified during the installation will be ignored, and the values determined from
the /etc/my.cnf will be used instead.
If you want to change these parameters during a new install, you should
temporarily rename /etc/my.cnf, install MySQL using the new parameters
you want to use, and then merge your previous /etc/my.cnf configuration
settings with the new /etc/my.cnf file that is created during installation.
• You must have a user profile with PASE with suitable privileges. The user should be within the
*SECOFR class, such as the QSECOFR user ID. You can use the WRKUSRPRF command to check
your user profile.
• For network connections to MySQL, you must have TCP/IP enabled. You should also check the
following:
• Ensure that a name has defined for the system. Run the Configure TCP/IP (CFGTCP) command
and select option 12 (Change TCP/IP domain information) to display this setting. Make sure that a
value is listed in the Host name field.
• Make sure that the system has a loopback entry which represents the localhost or 127.0.0.1.
• Ensure that the IP address of the IBM i machine is mapped correctly to the host name.
To install MySQL on i5/OS, follow these steps:
1. On the System i machine, create a save file that will be used to receive the downloaded installation
save file. The file should be located within the General Purpose Library (QGPL):
CRTSAVF FILE(QGPL/MYSQLINST) TESXT('MySQL Save file')

2. Download the MySQL installation save file in 32-bit (mysql-5.0.82-i5os-power-32bit.savf)
or 64-bit (mysql-5.0.82-i5os-power-64bit.savf) from MySQL Downloads.
3. You need to FTP the downloaded .savf file directly into the QGPL/MYSQLINST file on the System
i server. You can do this through FTP using the following steps after logging in to the System i
machine:
ftp> bin
ftp> cd qgpl
ftp> put mysql-5.0.82-i5os-power.savf mysqlinst

4. Log into the System i server using a user in the *SECOFR class, such as the QSECOFR user ID.
5. You need to restore the installation library stored in the .savf save file:
RSTLIB MYSQLINST DEV(*SAVF) SAVF(QGPL/MYSQLINST) MBROPT(*ALL) ALWOBJDIF(*ALL)

Note
You can ignore the security changes-type message at the bottom of the
installation panel.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on i5/OS

6. Once you have finished restoring the MYSQLINST library, check that all the necessary objects for
installation are on the system by using the Display Library (DSPLIB) command:
DSPLIB LIB(MYSQLINST)

7. You need to execute the installation command, MYSQLINST/INSMYSQL. You can specify three
parameter settings during installation:
• DIR('/QOpenSys/usr/local/mysql') sets the installation location for the MySQL files. The
directory will be created if it does not already exist.
• DATADIR('/QOpenSys/usr/local/mysql/data') sets the location of the directory that
will be used to store the database files and binary logs. The default setting is /QOpenSys/
usr/local/mysql/data. Note that if the installer detects an existing installation (due to the
existence of /etc/my.cnf), then the existing setting will be used instead of the default.
• USRPRF(MYSQL) sets the user profile that will own the files that are installed. The profile will be
created if it does not already exist.
Note
You should choose an appropriate user for using the MySQL server
installation. The user will be used whenever you need to do any
administration on the MySQL server.
Once you have set the appropriate parameters, you can begin the installation.
The installation copies all the necessary files into a directory matching the DIR configuration
value; sets the ownership on those files, sets up the MySQL environment and creates the MySQL
configuration file (in /etc/my.cnf) completing all the steps in a typical binary installation process
automatically. If this is a new installation of MySQL, or if the installer detects that this is a new
version (because the /etc/my.cnf file does not exist), then the initial core MySQL databases will
also be created during installation.
Once the installation has been completed, you will get a notice advising you to set the password for
the root user. For more information, Section 2.18, “Postinstallation Setup and Testing”.
8. Once the installation has completed, you can delete the installation file:
DLTLIB LIB(MYSQLINST)

Upgrading an existing MySQL instance
You need to execute the upgrade command, MYSQLINST/UPGMYSQL.
Note
You cannot use MYSQLINST/UPGMYSQL to upgrade between release series of
MySQL (for example from 5.0 to 5.1). For information and advice on migrating
between release series you can use the advice provided in Section 2.19.1.1,
“Changes Affecting Upgrades to 5.0”.
You must specify 6 parameters to perform an upgrade:
• DIR('/QOpenSys/usr/local/'): Sets the installation location for the MySQL files. The directory
will be created if it does not already exist. This is the directory that the MySQL server will be installed
into, inside a directory with a name matching the version and release. For example, if installing
MySQL 5.0.82 with the DIR set to /QOpenSys/usr/local/ would result in /QOpenSys/usr/
local/mysql-5.0.82-i5os-power64 and a symbolic link to this directory will be created in /
QOpenSys/usr/local/mysql.
• DATADIR('/QOpenSys/mysql/data'): Sets the location of the directory that will be upgraded.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on i5/OS

• USRPRF('MYSQL'): Sets the user profile that will own the files that are installed. The profile will be
created if it does not already exist; if it is created as part of the upgrade process, it will be disabled
initially. You may wish to enable this user profile so that it can be used to start the MySQL server
later. It is best practice to use the one previously created during the first installation.
• MYSQLUSR('root user'): Any user account in the current MySQL server with SUPER privileges.
• PASSWORD('root user password'): The password for the above account. This is necessary as
the upgrade starts the MySQL server to upgrade the tables and the password is need to be able to
shutdown the MySQL server.
• CURINST('path to previous install'): The full path to the installation that is being
upgraded. For example an installation in /QOpenSys/usr/local/ will be /QOpenSys/usr/
local/mysql-5.1.30-i5os-power64. Failure to specify this option may result in corruption of
your existing data files.
For example:

MYSQLINST/UPGMYSQL DIR('/QOpenSys/usr/local/') DATADIR('/QOpenSys/mysql/data') »
USERPRF(MYSQL) MYSQLUSR('root') PASSWORD('root') CURINST('/QOpenSys/usr/local/mysql-5.1.30-i5os-po

You should receive a Program Message indicating UPGRADE SUCCESSFUL! upon completion or an
error message if there is a problem.You can view the upgrade programs progression and the error in
the text file upgrade.log in the installation directory.
To start MySQL:
1. Log into the System i server using the user profile create or specified during installation. By default,
this is MYSQL.
Note
You should start mysqld_safe using a user that in the PASE environment
has the id=0 (the equivalent of the standard Unix root user). If you do
not use a user with this ID then the system will be unable to change the
user when executing mysqld as set using --user option. If this happens,
mysqld may be unable to read the files located within the MySQL data
directory and the execution will fail.
2. Enter the PASE environment using call qp2term.
3. Start the MySQL server by changing to the installation directory and running mysqld_safe,
specifying the user name used to install the server. The installer conveniently installs a symbolic
link to the installation directory (mysql-5.0.42-i5os-power-32bit) as /opt/mysql/mysql:
> cd /opt/mysql/mysql
> bin/mysqld_safe --user=mysql &

You should see a message similar to the following:
Starting mysqld daemon with databases »
from /opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data

If you are having problems starting MySQL server, see Section 2.18.2.1, “Troubleshooting Problems
Starting the MySQL Server”.
To stop MySQL:
1. Log into the System i server using the user profile create or specified during installation. By default,
this is MYSQL.
2. Enter the PASE environment using call qp2term.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on NetWare

3. Stop the MySQL server by changing into the installation directory and running mysqladmin,
specifying the user name used to install the server:
> cd /opt/mysql/mysql
> bin/mysqladmin -u root shutdown

If the session that you started and stopped MySQL are the same, you may get the log output from
mysqld:
STOPPING server from pid file »
/opt/mysql/mysql-enterprise-5.0.42-i5os-power-32bit/data/I5DBX.RCHLAND.IBM.COM.pid
070718 10:34:20 mysqld ended

If the sessions used to start and stop MySQL are different, you will not receive any confirmation of
the shutdown.
Notes and tips
• A problem has been identified with the installation process on DBCS systems. If you are having
problems install MySQL on a DBCS system, you need to change your job's coded character
set identifier (CSSID) to 37 (EBCDIC) before executing the install command, INSMYSQL. To do
this, determine your existing CSSID (using DSPJOB and selecting option 2), execute CHGJOB
CSSID(37), run INSMYSQL to install MySQL and then execute CHGJOB again with your original
CSSID.
• If you want to use the Perl scripts that are included with MySQL, you need to download the iSeries
Tools for Developers (5799-PTL). See http://www-03.ibm.com/servers/enable/site/porting/tools/.

2.15 Installing MySQL on NetWare
Porting MySQL to NetWare was an effort spearheaded by Novell. Novell customers should be pleased
to note that NetWare 6.5 ships with bundled MySQL binaries, complete with an automatic commercial
use license for all servers running that version of NetWare.
MySQL for NetWare is compiled using a combination of Metrowerks CodeWarrior for NetWare and
special cross-compilation versions of the GNU autotools.
The latest binary packages for NetWare can be obtained at http://dev.mysql.com/downloads/. See
Section 2.5, “How to Get MySQL”.
To host MySQL, the NetWare server must meet these requirements:
• The latest Support Pack of NetWare 6.5 must be installed.
• The system must meet Novell's minimum requirements to run the respective version of NetWare.
• MySQL data and the program binaries must be installed on an NSS volume; traditional volumes are
not supported.
To install MySQL for NetWare, use the following procedure:
1. If you are upgrading from a prior installation, stop the MySQL server. This is done from the server
console, using the following command:
SERVER:

mysqladmin -u root shutdown

Note
If the MySQL root user account has a password, you need to invoke
mysqladmin with the -p option and supply the password when prompted.
2. Log on to the target server from a client machine with access to the location where you are
installing MySQL.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on NetWare

3. Extract the binary package Zip file onto the server. Be sure to allow the paths in the Zip file to be
used. It is safe to simply extract the file to SYS:\.
If you are upgrading from a prior installation, you may need to copy the data directory (for example,
SYS:MYSQL\DATA), as well as my.cnf, if you have customized it. You can then delete the old
copy of MySQL.
4. You might want to rename the directory to something more consistent and easy to use. The
examples in this manual use SYS:MYSQL to refer to the installation directory.
Note that MySQL installation on NetWare does not detect if a version of MySQL is already installed
outside the NetWare release. Therefore, if you have installed the latest MySQL version from
the Web (for example, MySQL 4.1 or later) in SYS:\MYSQL, you must rename the folder before
upgrading the NetWare server; otherwise, files in SYS:\MySQL are overwritten by the MySQL
version present in NetWare Support Pack.
5. At the server console, add a search path for the directory containing the MySQL NLMs. For
example:
SERVER:

SEARCH ADD SYS:MYSQL\BIN

6. Initialize the data directory and the grant tables, if necessary, by executing mysql_install_db at
the server console.
7. Start the MySQL server using mysqld_safe at the server console.
8. To finish the installation, you should also add the following commands to autoexec.ncf. For
example, if your MySQL installation is in SYS:MYSQL and you want MySQL to start automatically,
you could add these lines:
#Starts the MySQL 5.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE

If you are running MySQL on NetWare 6.0, we strongly suggest that you use the --skipexternal-locking option on the command line:
#Starts the MySQL 5.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --skip-external-locking

It is also necessary to use CHECK TABLE and REPAIR TABLE instead of myisamchk, because
myisamchk makes use of external locking. External locking is known to have problems on
NetWare 6.0; the problem has been eliminated in NetWare 6.5. Note that the use of MySQL on
Netware 6.0 is not officially supported.
mysqld_safe on NetWare provides a screen presence. When you unload (shut down) the
mysqld_safe NLM, the screen does not go away by default. Instead, it prompts for user input:
**

If you want NetWare to close the screen automatically instead, use the --autoclose option to
mysqld_safe. For example:
#Starts the MySQL 5.0.x database server
SEARCH ADD SYS:MYSQL\BIN
MYSQLD_SAFE --autoclose

The behavior of mysqld_safe on NetWare is described further in Section 4.3.2, “mysqld_safe
— MySQL Server Startup Script”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL on Unix/Linux Using Generic Binaries

9. When installing MySQL, either for the first time or upgrading from a previous version, download and
install the latest and appropriate Perl module and PHP extensions for NetWare:
• Perl: http://forge.novell.com/modules/xfcontent/downloads.php/perl/Modules/
• PHP: http://forge.novell.com/modules/xfcontent/downloads.php/php/Modules/
If there was an existing installation of MySQL on the NetWare server, be sure to check for existing
MySQL startup commands in autoexec.ncf, and edit or delete them as necessary.
Note
The accounts that are listed in the MySQL grant tables initially have no
passwords. After starting the server, you should set up passwords for them
using the instructions in Section 2.18, “Postinstallation Setup and Testing”.

2.16 Installing MySQL on Unix/Linux Using Generic Binaries
Oracle provides a set of binary distributions of MySQL. These include generic binary distributions in the
form of compressed tar files (files with a .tar.gz extension) for a number of platforms, and binaries
in platform-specific package formats for selected platforms.
This section covers the installation of MySQL from a compressed tar file binary distribution. For other
platform-specific package formats, see the other platform-specific sections. For example, for Windows
distributions, see Section 2.10, “Installing MySQL on Microsoft Windows”.
To obtain MySQL, see Section 2.5, “How to Get MySQL”.
MySQL compressed tar file binary distributions have names of the form
mysql-VERSION-OS.tar.gz, where VERSION is a number (for example, 5.0.96), and OS indicates
the type of operating system for which the distribution is intended (for example, pc-linux-i686 or
winx64).
Warning
If you have previously installed MySQL using your operating system native
package management system, such as yum or apt-get, you may experience
problems installing using a native binary. Make sure your previous MySQL
installation has been removed entirely (using your package management
system), and that any additional files, such as old versions of your data files,
have also been removed. You should also check for configuration files such as
/etc/my.cnf or the /etc/mysql directory and delete them.
If you run into problems and need to file a bug report, please use the instructions in Section 1.7, “How
to Report Bugs or Problems”.
To install and use a MySQL binary distribution, the command sequence looks like this:
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
shell>
# Next
shell>
shell>
# Next
shell>

This
documentation
is for an
older version.
If you're

groupadd mysql
useradd -r -g mysql -s /bin/false mysql
cd /usr/local
tar zxvf /path/to/mysql-VERSION-OS.tar.gz
ln -s full-path-to-mysql-VERSION-OS mysql
cd mysql
chown -R mysql .
chgrp -R mysql .
scripts/mysql_install_db --user=mysql
chown -R root .
chown -R mysql data
command is optional
cp support-files/my-medium.cnf /etc/my.cnf
bin/mysqld_safe --user=mysql &
command is optional
cp support-files/mysql.server /etc/init.d/mysql.server

This
documentation
is for an
older version.
If you're

Create a mysql User and Group

Note
This procedure assumes that you have root (administrator) access to your
system. Alternatively, you can prefix each command using the sudo (Linux) or
pfexec (OpenSolaris) command.
Note
The procedure does not assign passwords to MySQL accounts. To do so, use
the instructions in Section 2.18.4, “Securing the Initial MySQL Accounts”.
A more detailed version of the preceding description for installing a binary distribution follows.

Create a mysql User and Group
If your system does not already have a user and group for mysqld to run as, you may need to create
one. The following commands add the mysql group and the mysql user. The syntax for useradd and
groupadd may differ slightly on different versions of Unix, or they may have different names such as
adduser and addgroup.
If your system does not already have a user and group to use for running mysqld, you may need to
create one. The following commands add the mysql group and the mysql user. You might want to
call the user and group something else instead of mysql. If so, substitute the appropriate name in the
following instructions. The syntax for useradd and groupadd may differ slightly on different versions
of Unix, or they may have different names such as adduser and addgroup.
shell> groupadd mysql
shell> useradd -r -g mysql -s /bin/false mysql

Note
Because the user is required only for ownership purposes, not login purposes,
the useradd command uses the -r and -s /bin/false options to create
a user that does not have login permissions to your server host. Omit these
options if your useradd does not support them.

Obtain and Unpack the Distribution
Pick the directory under which you want to unpack the distribution and change location into it. The
example here unpacks the distribution under /usr/local. The instructions, therefore, assume that
you have permission to create files and directories in /usr/local. If that directory is protected, you
must perform the installation as root.
shell> cd /usr/local

Obtain a distribution file using the instructions in Section 2.5, “How to Get MySQL”. For a given release,
binary distributions for all platforms are built from the same MySQL source distribution.
Unpack the distribution, which creates the installation directory. Then create a symbolic link to that
directory. tar can uncompress and unpack the distribution if it has z option support:
shell> tar zxvf /path/to/mysql-VERSION-OS.tar.gz
shell> ln -s full-path-to-mysql-VERSION-OS mysql

The tar command creates a directory named mysql-VERSION-OS. The ln command makes a
symbolic link to that directory. This enables you to refer more easily to the installation directory as /
usr/local/mysql.
To install MySQL from a compressed tar file binary distribution, your system must have GNU gunzip
to uncompress the distribution and a reasonable tar to unpack it. If your tar program supports the z
option, it can both uncompress and unpack the file.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Perform Postinstallation Setup

GNU tar is known to work. The standard tar provided with some operating systems is not able to
unpack the long file names in the MySQL distribution. You should download and install GNU tar, or if
available, use a preinstalled version of GNU tar. Usually this is available as gnutar, gtar, or as tar
within a GNU or Free Software directory, such as /usr/sfw/bin or /usr/local/bin. GNU tar is
available from http://www.gnu.org/software/tar/.
If your tar does not have z option support, use gunzip to unpack the distribution and tar to unpack
it. Replace the preceding tar command with the following alternative command to uncompress and
extract the distribution:
shell> gunzip < /path/to/mysql-VERSION-OS.tar.gz | tar xvf -

Perform Postinstallation Setup
The remainder of the installation process involves setting distribution ownership and access
permissions, initializing the data directory, starting the MySQL server, and setting up the configuration
file. For instructions, see Section 2.18, “Postinstallation Setup and Testing”.

2.17 Installing MySQL from Source
Building MySQL from the source code enables you to customize build parameters, compiler
optimizations, and installation location. For a list of systems on which MySQL is known to run, see
http://www.mysql.com/support/supportedplatforms/database.html.
Before you proceed with an installation from source, check whether we produce a precompiled binary
distribution for your platform and whether it works for you. We put a great deal of effort into ensuring
that our binaries are built with the best possible options for optimal performance. Instructions for
installing binary distributions are available in Section 2.16, “Installing MySQL on Unix/Linux Using
Generic Binaries”.
To obtain a source distribution for MySQL, see Section 2.5, “How to Get MySQL”. MySQL
source distributions are available as compressed tar files, Zip archives, or RPM packages.
Distribution files have names of the form mysql-VERSION.tar.gz, mysql-VERSION.zip, or
mysql-VERSION.rpm, where VERSION is a number like 5.0.96.
To perform a MySQL installation using the source code:
• To build MySQL from source on Unix-like systems, including Linux, commercial Unix, BSD, OS X
and others using a .tar.gz or RPM-based source code distribution, see Section 2.17.1, “Installing
MySQL Using a Standard Source Distribution”.
• To build MySQL from source on Windows (Windows XP or newer required), see Section 2.10.8,
“Installing MySQL from Source on Windows”.
• For information on building from one of our development trees, see Section 2.17.2, “Installing MySQL
Using a Development Source Tree”.
• For information on using the configure command to specify the source build parameters, including
links to platform specific parameters that you might need, see Section 2.17.3, “MySQL SourceConfiguration Options”.
To install MySQL from source, the following system requirements must be satisfied:
• GNU gunzip to uncompress the distribution and a reasonable tar to unpack it (if you use a
.tar.gz distribution), or WinZip or another tool that can read .zip files (if you use a .zip
distribution).
GNU tar is known to work. The standard tar provided with some operating systems is not able to
unpack the long file names in the MySQL distribution. You should download and install GNU tar, or
if available, use a preinstalled version of GNU tar. Usually this is available as gnutar, gtar, or as
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Standard Source Distribution

tar within a GNU or Free Software directory, such as /usr/sfw/bin or /usr/local/bin. GNU
tar is available from http://www.gnu.org/software/tar/.
• A working ANSI C++ compiler. GCC 3.4.6 or later, Sun Studio 10 or later, Visual Studio 2005 or later,
and many current vendor-supplied compilers are known to work.
• A good make program. Although some platforms come with their own make implementations, it is
highly recommended that you use GNU make 3.75 or newer. It may already be available on your
system as gmake. GNU make is available from http://www.gnu.org/software/make/.
• libtool 1.5, available from http://www.gnu.org/software/libtool/. 1.5.24 or later is recommended.
If you are using a version of gcc recent enough to understand the -fno-exceptions option, it is very
important that you use this option. Otherwise, you may compile a binary that crashes randomly. Also
use -felide-constructors and -fno-rtti along with -fno-exceptions. When in doubt, do
the following:
CFLAGS="-O3" CXX=gcc CXXFLAGS="-O3 -felide-constructors \
-fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static

On most systems, this gives you a fast and stable binary.
If you run into problems and need to file a bug report, please use the instructions in Section 1.7, “How
to Report Bugs or Problems”.

2.17.1 Installing MySQL Using a Standard Source Distribution
To install MySQL from source, first configure, build, and install from a source package. Then follow the
same postinstallation setup sequence as for a binary installation.
If you start from a source RPM, use the following command to make a binary RPM that you can install.
If you do not have rpmbuild, use rpm instead.
shell> rpmbuild --rebuild --clean MySQL-VERSION.src.rpm

The result is one or more binary RPM packages that you install as indicated in Section 2.12, “Installing
MySQL on Linux Using RPM Packages”.
The sequence for installation from a compressed tar file source distribution is similar to the process
for installing from a generic binary distribution that is detailed in Section 2.16, “Installing MySQL on
Unix/Linux Using Generic Binaries”. For a MySQL .tar.gz source distribution, the basic installation
command sequence looks like this:
# Preconfiguration setup
shell> groupadd mysql
shell> useradd -g mysql -s /bin/false mysql
# Beginning of source-build specific instructions
shell> tar zxvf mysql-VERSION.tar.gz
shell> cd mysql-VERSION
shell> ./configure --prefix=/usr/local/mysql
shell> make
shell> make install
# End of source-build specific instructions
# Postinstallation setup
shell> cd /usr/local/mysql
shell> chown -R mysql .
shell> chgrp -R mysql .
shell> bin/mysql_install_db --user=mysql
shell> chown -R root .
shell> chown -R mysql var
# Next command is optional
shell> cp support-files/my-medium.cnf /etc/my.cnf
shell> bin/mysqld_safe --user=mysql &

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Standard Source Distribution

# Next command is optional
shell> cp support-files/mysql.server /etc/init.d/mysql.server

Note
This procedure does not set up any passwords for MySQL accounts. After
following the procedure, proceed to Section 2.18, “Postinstallation Setup and
Testing”, for postinstallation setup and testing.
A more detailed version of the preceding description for installing MySQL from a source distribution
follows:
1. Add a login user and group for mysqld to run as:
shell> groupadd mysql
shell> useradd -g mysql -s /bin/false mysql

These commands add the mysql group and the mysql user. The syntax for useradd and
groupadd may differ slightly on different versions of Unix, or they may have different names such
as adduser and addgroup.
You might want to call the user and group something else instead of mysql. If so, substitute the
appropriate name in the following steps.
2. Perform the following steps as the mysql user, except as noted.
3. Pick the directory under which you want to unpack the distribution and change location into it.
4. Obtain a distribution file using the instructions in Section 2.5, “How to Get MySQL”.
5. Unpack the distribution into the current directory. tar can uncompress and unpack the distribution
if it has z option support:
shell> tar zxvf /path/to/mysql-VERSION.tar.gz

This command creates a directory named mysql-VERSION.
If your tar does not have z option support, use gunzip to unpack the distribution and tar to
unpack it:
shell> gunzip < /path/to/mysql-VERSION.tar.gz | tar xvf -

6. 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.
7. Configure the release and compile everything:
shell> ./configure --prefix=/usr/local/mysql
shell> make

When you run configure, you might want to specify other options. For example, if you need
to debug mysqld or a MySQL client, run configure with the --with-debug option, and then
recompile and link your clients with the new client library. See Section 21.3, “Debugging and
Porting MySQL”.
Run ./configure --help for a list of options. Section 2.17.3, “MySQL Source-Configuration
Options”, discusses some of the more useful options.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Standard Source Distribution

If configure fails and you are going to send mail to a MySQL mailing list to ask for assistance,
please include any lines from config.log that you think can help solve the problem. Also include
the last couple of lines of output from configure. To file a bug report, please use the instructions
in Section 1.7, “How to Report Bugs or Problems”.
If the compile fails, see Section 2.17.4, “Dealing with Problems Compiling MySQL”, for help.
8. Install the distribution:
shell> make install

You might need to run this command as root.
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 this command as root.
If you want to configure support for InnoDB tables, you should edit the /etc/my.cnf file,
removing the # character before the option lines that start with innodb_..., and modify the
option values to be what you want. See Section 4.2.6, “Using Option Files”, and Section 14.2.1,
“Configuring InnoDB”.
9. Change location into the installation directory:
shell> cd /usr/local/mysql

10. If you ran the make install command as root, the installed files will be owned by root. Ensure
that the installation is accessible to mysql by executing the following commands as root in the
installation directory:
shell> chown -R mysql .
shell> chgrp -R mysql .

The first command changes the owner attribute of the files to the mysql user. The second changes
the group attribute to the mysql group.
11. If you have not installed MySQL before, you must create the MySQL data directory and initialize the
grant tables:
shell> bin/mysql_install_db --user=mysql

If you run the command as root, include the --user option as shown. If you run the command
while logged in as mysql, you can omit the --user option.
The command should create the data directory and its contents with mysql as the owner.
After using mysql_install_db to create the grant tables for MySQL, you must restart the server
manually. The mysqld_safe command to do this is shown in a later step.
12. Most of the MySQL installation can be owned by root if you like. The exception is that the data
directory must be owned by mysql. To accomplish this, run the following commands as root in the
installation directory:
shell> chown -R root .
shell> chown -R mysql var

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Development Source Tree

13. If the plugin directory is writable by the server, it may be possible for a user to write executable
code to a file in the directory using SELECT ... INTO DUMPFILE. This can be prevented by
making plugin_dir read only to the server or by setting --secure-file-priv to a directory
where SELECT writes can be made safely.
14. If you want MySQL to start automatically when you boot your machine, you can copy supportfiles/mysql.server to the location where your system has its startup files. More information
can be found in the support-files/mysql.server script itself; see also Section 2.18.5,
“Starting and Stopping MySQL Automatically”.
15.

You can set up new accounts using the bin/mysql_setpermission script if you install
the DBI and DBD::mysql Perl modules. See Section 4.6.15, “mysql_setpermission —
Interactively Set Permissions in Grant Tables”. For Perl module installation instructions, see
Section 2.22, “Perl Installation Notes”.

After everything has been installed, test the distribution. To start the MySQL server, use the following
command:
shell> /usr/local/mysql/bin/mysqld_safe --user=mysql &

If you run the command as root, you should use the --user option as shown. The option value is the
name of the login account that you created in the first step to use for running the server. If you run the
mysqld_safe command while logged in as that user, you can omit the --user option.
If the command fails immediately and prints mysqld ended, look for information in the error log (which
by default is the host_name.err file in the data directory).
More information about mysqld_safe is given in Section 4.3.2, “mysqld_safe — MySQL Server
Startup Script”.
To make it more convenient to invoke programs installed in /usr/local/mysql/bin, you can add
that directory to your PATH environment variable setting. That enables you to run a program by typing
only its name, not its entire path name. See Section 4.2.10, “Setting Environment Variables”.
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.18, “Postinstallation Setup and Testing”.

2.17.2 Installing MySQL Using a Development Source Tree
This section discusses how to install MySQL from the latest development source code.
To obtain the source tree, you must have Bazaar installed. The Bazaar VCS Web site has instructions
for downloading and installing Bazaar on different platforms. Bazaar is supported on any platform that
supports Python, and is therefore compatible with any Linux, Unix, Windows, or OS X host.
MySQL development projects are hosted on Launchpad. MySQL projects, including MySQL Server,
MySQL Workbench, and others are available from the Oracle/MySQL Engineering page. For the
repositories related only to MySQL Server, see the MySQL Server page.
To build under Unix/Linux, you must have the following tools installed:
• A good make program. Although some platforms come with their own make implementations, it is
highly recommended that you use GNU make 3.75 or newer. It may already be available on your
system as gmake. GNU make is available from http://www.gnu.org/software/make/.
• autoconf 2.58 (or newer), available from http://www.gnu.org/software/autoconf/.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Development Source Tree

• automake 1.8.1, available from http://www.gnu.org/software/automake/.
• libtool 1.5, available from http://www.gnu.org/software/libtool/. 1.5.24 or later is recommended.
• m4, available from http://www.gnu.org/software/m4/.
• bison, available from http://www.gnu.org/software/bison/. You should use the latest version of
bison where possible. Versions 1.75 and 2.1 are known to work. There have been reported
problems with bison 1.875. If you experience problems, upgrade to a later, rather than earlier,
version.
To build under Windows you must have Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net
2003 (7.1), or Visual Studio 2005 (8.0) compiler system.
Once the necessary tools are installed, create a local branch of the MySQL development tree on your
machine using this procedure:
1. To obtain a copy of the MySQL source code, you must create a new Bazaar branch. If you do not
already have a Bazaar repository directory set up, you must initialize a new directory:
shell> mkdir mysql-server
shell> bzr init-repo --trees mysql-server

This is a one-time operation.
2. Assuming that you have an initialized repository directory, you can branch from the public MySQL
server repositories to create a local source tree. To create a branch of a specific version:
shell> cd mysql-server
shell> bzr branch lp:mysql-server/5.0 mysql-5.0

This is a one-time operation per source tree. You can branch the source trees for several versions
of MySQL under the mysql-server directory.
3. The initial download will take some time to complete, depending on the speed of your connection.
Please be patient. Once you have downloaded the first tree, additional trees should take
significantly less time to download.
4. When building from the Bazaar branch, you may want to create a copy of your active branch so that
you can make configuration and other changes without affecting the original branch contents. You
can achieve this by branching from the original branch:
shell> bzr branch mysql-5.0 mysql-5.0-build

5. To obtain changes made after you have set up the branch initially, update it using the pull option
periodically. Use this command in the top-level directory of the local copy:
shell> bzr pull

You can examine the changeset comments for the tree by using the log option to bzr:
shell> bzr log

You can also browse changesets, comments, and source code online at the Launchpad MySQL
Server page.
If you see diffs (changes) or code that you have a question about, do not hesitate to send email
to the MySQL internals mailing list. See Section 1.6.1, “MySQL Mailing Lists”. If you think you
have a better idea on how to do something, send an email message to the list with a patch.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing MySQL Using a Development Source Tree

After you have the local branch, you can build MySQL server from the source code. On Windows,
the build process is different from Unix/Linux: see Section 2.10.8, “Installing MySQL from Source on
Windows”.
On Unix/Linux, use the autoconf system to create the configure script so that you can configure
the build environment before building. The following example shows the typical commands required to
build MySQL from a source tree.
1. Change location to the top-level directory of the source tree; replace mysql-5.0 with the
appropriate directory name.
shell> cd mysql-5.0

2. Prepare the source tree for configuration.
You must separately configure the BDB and InnoDB storage engines. Run the following commands
from the main source directory:
shell> (cd bdb/dist; sh s_all)
shell> (cd innobase; autoreconf --force --install)

You can omit the previous commands if you do not require BDB or InnoDB support.
Prepare the remainder of the source tree:
shell> autoreconf --force --install

As an alternative to the preceding autoreconf command, you can use BUILD/autorun.sh,
which acts as a shortcut for the following sequence of commands:
shell>
shell>
shell>
shell>
shell>

aclocal; autoheader
libtoolize --automake --force
automake --force --add-missing; autoconf
(cd bdb/dist; sh s_all)
(cd innobase; aclocal; autoheader; autoconf; automake)

If you get some strange errors during this stage, verify that you have the correct version of
libtool installed.
3. Configure the source tree and compile MySQL:
shell> ./configure
shell> make

# Add your favorite options here

For a description of some configure options, see Section 2.17.3, “MySQL Source-Configuration
Options”.
A collection of configuration scripts is located in the BUILD/ subdirectory. For example, 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, or use another script that may be more appropriate. These scripts are
provided on an “as-is” basis. They are not supported and their contents may change from release to
release.
4. When the build is done, run make install. Be careful with this on a production machine; the
installation command may overwrite your live release installation. If you already have MySQL
installed and do not want to overwrite it, run ./configure with values for the --prefix, -with-tcp-port, and --with-unix-socket-path options different from those used by your
production server. For additional information about preventing multiple servers from interfering with
each other, see Section 5.5, “Running Multiple MySQL Instances on One Machine”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

5. Play hard with your new installation. For example, try to make new features crash. Start by running
make test. See Section 21.1.2, “The MySQL Test Suite”.
6. If you have gotten to the make stage, but the distribution does not compile, please enter the
problem into our bugs database using the instructions given in Section 1.7, “How to Report Bugs
or Problems”. If you have installed the latest versions of the required tools, and they crash trying
to process our configuration files, please report that also. However, if you get a command not
found error or a similar problem for required tools, do not report it. Instead, make sure that all the
required tools are installed and that your PATH variable is set correctly so that your shell can find
them.

2.17.3 MySQL Source-Configuration Options
The configure script provides a great deal of control over how you configure a MySQL source
distribution. Typically, you do this using options on the configure command line. For a full list of
options supported by configure, run this command:
shell> ./configure --help

You can also affect configure using certain environment variables. See Section 2.21, “Environment
Variables”.
The following table shows the available configure options.
Table 2.7 MySQL Source-Configuration Option Reference (configure)
Formats

Description

Default

--bindir

User executables

EPREFIX/bin

--build

Configure for building on
BUILD

guessed

--cache-file

Cache test results in FILE

disabled

--config-cache

Alias for `--cachefile=config.cache'

--datadir

Read-only architectureindependent data

--disable-FEATURE

Do not include FEATURE

--disable-communityfeatures

Disable additional features
provided by the community

--disable-dependencytracking

Disable dependency tracking

--disable-grantoptions

Disable GRANT options

--disable-largefile

Omit support for large files

Introduced
Removed

PREFIX/share

5.0.82

5.0.34

--disable-libtool-lock Disable libtool lock
--disable-profiling

Build a version without query
profiling code

--enable-FEATURE

Enable FEATURE

--enable-assembler

Use assembler versions
of some string functions if
available

--enable-dependencytracking

Do not reject slow
dependency extractors

--enable-fast-install

Optimize for fast installation

This
documentation
is for an
older version.
If you're

5.0.37

5.0.45

yes
This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

Formats

Description

Default

--enable-local-infile

Enable LOCAL for LOAD
DATA INFILE

disabled

--enable-shared

Build shared libraries

yes

--enable-static

Build static libraries

yes

--enable-thread-safeclient

Compile the client with
threads

--exec-prefix

Install architecture-dependent
files in EPREFIX

--help

Display help message and
exit

--host

Cross-compile to build
programs to run on HOST

--includedir

C header files

PREFIX/include

--infodir

Info documentation

PREFIX/info

--libdir

Object code libraries

EPREFIX/lib

--libexecdir

Program executables

EPREFIX/
libexec

--localstatedir

Modifiable single-machine
data

PREFIX/var

--mandir

man documentation

PREFIX/man

--no-create

Do not create output files

--oldincludedir

C header files for non-gcc

--prefix

Install architectureindependent files in PREFIX

--program-prefix

Prepend PREFIX to installed
program names

--program-suffix

Append SUFFIX to installed
program names

--program-transformname

run sed PROGRAM on
installed program names

--quiet

Do not print `checking...'
messages

--sbindir

System administrative
executables

EPREFIX/sbin

--sharedstatedir

Modifiable architectureindependent data

PREFIX/com

--srcdir

Find the sources in DIR

configure
directory
or ..

--sysconfdir

Read-only single-machine
data

PREFIX/etc

--target

Configure for building
compilers for TARGET

--version

Display version information
and exit

--with-PACKAGE

Use PACKAGE

This
documentation
is for an
older version.
If you're

Introduced
Removed

/usr/include

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

Formats

Description

Default

Introduced
Removed

--with-archivestorage-engine

Enable the Archive Storage
Engine

no

--with-berkeley-db

Use BerkeleyDB located in
DIR

no

--with-berkeley-dbincludes

Find Berkeley DB headers in
DIR

--with-berkeley-dblibs

Find Berkeley DB libraries in
DIR

--with-big-tables

Support tables with more
than 4 G rows even on 32 bit
platforms

5.0.4

--with-blackholestorage-engine

Enable the Blackhole Storage no
Engine

5.0.4

--with-charset

Default character set

--with-client-ldflags

Extra linking arguments for
clients

--with-collation

Default collation

--with-comment

Comment about compilation
environment

--with-csv-storageengine

Enable the CSV Storage
Engine

--with-darwin-mwcc

Use Metrowerks CodeWarrior
wrappers on OS X/Darwin

--with-embeddedprivilege-control

Build parts to check user's
privileges (only affects
embedded library)

yes
5.0.6

--with-embedded-server Build the embedded server
--with-examplestorage-engine

Enable the Example Storage no
Engine

--with-extra-charsets

Use charsets in addition to
default

--with-gnu-ld

Assume the C compiler uses no
GNU ld

--with-isam

Enable the ISAM table type

--with-lib-ccflags

Extra CC options for libraries

--with-libwrap

Compile in libwrap
(tcp_wrappers) support

--with-low-memory

Try to use less memory to
compile to avoid memory
limitations

--with-machine-type

Set the machine type, like
"powerpc"

--with-max-indexes

Sets the maximum number of 64
indexes per table

--with-mit-threads

Always use included thread
lib

This
documentation
is for an
older version.
If you're

5.0.2

5.0.44

5.0.4

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

Formats

Description

--with-mysqld-ldflags

Extra linking arguments for
mysqld

--with-mysqld-libs

Extra libraries to link with for
mysqld

--with-mysqld-user

What user the mysqld
daemon shall be run as

--with-mysqlfs

Include the corba-based
MySQL file system

--with-mysqlmanager

Build the mysqlmanager
binary

--with-named-curseslibs

Use specified curses libraries

--with-named-threadlibs

Use specified thread libraries

--with-ndb-ccflags

Extra CC options for ndb
compile

--with-ndb-docs

Include the NDB Cluster
ndbapi and mgmapi
documentation

--with-ndb-port

Port for NDB Cluster
management server

--with-ndb-port-base

Port for NDB Cluster
management server

--with-ndb-sci

Provide MySQL with a
custom location of sci library

--with-ndb-shm

Include the NDB Cluster
shared memory transporter

--with-ndb-test

Include the NDB Cluster
ndbapi test programs

--with-ndbcluster

Include the NDB Cluster table no
handler

--with-openssl

Include the OpenSSL support

--with-opensslincludes

Find OpenSSL headers in
DIR

--with-openssl-libs

Find OpenSSL libraries in
DIR

--with-other-libc

Link against libc and other
standard libraries installed
in the specified nonstandard
location

--with-pic

Try to use only PIC/non-PIC
objects

--with-pstack

Use the pstack backtrace
library

--with-pthread

Force use of pthread library

--with-raid

Enable RAID Support

This
documentation
is for an
older version.
If you're

Default

Introduced
Removed

5.0.44

5.0.3
Build if
server is
built

5.0.3

5.0.3

5.0.2

Use both

5.0.3

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

Formats

Description

Default

--with-server-suffix

Append value to the version
string

--with-system-type

Set the system type, like
"sun-solaris10"

--with-tags

Include additional
configurations

--with-tcp-port

Which port to use for MySQL 3306
services

--with-unix-socketpath

Where to put the unix-domain
socket

--with-vio

Include the Virtual IO support

--with-yassl

Include the yaSSL support

--with-zlib-dir

Provide MySQL with
a custom location of
compression library

--without-PACKAGE

Do not use PACKAGE

--without-bench

Skip building of the
benchmark suite

--without-debug

Build a production version
without debugging code

--without-docs

Skip building of the
documentation

--without-extra-tools

Skip building utilities in the
tools directory

--without-geometry

Do not build geometry-related
parts

--without-innodb

Do not include the InnoDB
table handler

--without-libedit

Use system libedit instead of
bundled copy

--without-man

Skip building of the man
pages

--without-ndb-debug

Disable special ndb debug
features

--without-query-cache

Do not build query cache

--without-readline

Use system readline instead
of bundled copy

--without-server

Only build the client

--without-uca

Skip building of the national
Unicode collations

Introduced
Removed

5.0.44
automatic

5.0.2
5.0.6

5.0.48

5.0.3

5.0.3

Some of the configure options available are described here. For options that may be of use if you
have difficulties building MySQL, see Section 2.17.4, “Dealing with Problems Compiling MySQL”.
Many options configure compile-time defaults that can be overridden at server startup. For example,
the --prefix, --with-tcp-port, and with-unix-socket-path options that configure the
default installation base directory location, TCP/IP port number, and Unix socket file can be changed at
server startup with the --basedir, --port, and --socket options for mysqld.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

•

To compile just the MySQL client libraries and client programs and not the server, use the -without-server option:
shell> ./configure --without-server

If you have no C++ compiler, some client programs such as mysql cannot be compiled because
they require C++. In this case, you can remove the code in configure that tests for the C++
compiler and then run ./configure with the --without-server option. The compile step should
still try to build all clients, but you can ignore any warnings about files such as mysql.cc. (If make
stops, try make -k to tell it to continue with the rest of the build even if errors occur.)
•

To build the embedded MySQL library (libmysqld.a), use the --with-embedded-server
option.

•

To place your log files and database directories elsewhere than under /usr/local/var, use a
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.
You can also specify the installation directory and data directory locations at server startup time
by using the --basedir and --datadir options. These can be given on the command line or in
an MySQL option file, although it is more common to use an option file. See Section 4.2.6, “Using
Option Files”.
•

The --with-tcp-port option specifies the port number on which the server listens for TCP/IP
connections. The default is port 3306. To listen on a different port, use a configure command like
this:
shell> ./configure --with-tcp-port=3307

•

On Unix, if you want the MySQL socket file location to be somewhere other than the default
location (normally in the directory /tmp or /var/run), use a configure command like this:
shell> ./configure \
--with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock

The socket file name must be an absolute path name. You can also change the location of
mysql.sock at server startup by using a MySQL option file. See Section B.5.3.6, “How to Protect or
Change the MySQL Unix Socket File”.
•

To compile statically linked programs (for example, to make a binary distribution, to get better
performance, or to work around problems with some Red Hat Linux distributions), run configure
like this:
shell> ./configure --with-client-ldflags=-all-static \
--with-mysqld-ldflags=-all-static

•

If you are using gcc and do not have libg++ or libstdc++ installed, you can tell configure
to use gcc as your C++ compiler:
shell> CC=gcc CXX=gcc ./configure

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

When you use gcc as your C++ compiler, it does not attempt to link in libg++ or libstdc++. This
may be a good thing to do even if you have those libraries installed. Some versions of them have
caused strange problems for MySQL users in the past.
The following list indicates some compilers and environment variable settings that are commonly
used with each one.
• gcc 2.7.2:
CC=gcc CXX=gcc CXXFLAGS="-O3 -felide-constructors"

• gcc 2.95.2:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
-felide-constructors -fno-exceptions -fno-rtti"

In most cases, you can get a reasonably optimized MySQL binary by using the options from the
preceding list and adding the following options to the configure line:
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static

The full configure line would, in other words, be something like the following for all recent gcc
versions:
CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static

The binaries we provide on the MySQL Web site at http://dev.mysql.com/downloads/ are all compiled
with full optimization and should work well for most users. See Section 2.16, “Installing MySQL on
Unix/Linux Using Generic Binaries”.
• If the build fails and produces errors about your compiler or linker not being able to create the shared
library libmysqlclient.so.N (where N is a version number), you can work around this problem
by giving the --disable-shared option to configure. In this case, configure does not build a
shared libmysqlclient.so.N library.
•

By default, MySQL uses the latin1 (cp1252 West European) character set. To change the
default set, use the --with-charset option:
shell> ./configure --with-charset=CHARSET

CHARSET may be one of binary, armscii8, ascii, big5, cp1250, cp1251, cp1256, cp1257,
cp850, cp852, cp866, cp932, dec8, eucjpms, euckr, gb2312, gbk, geostd8, greek, hebrew,
hp8, keybcs2, koi8r, koi8u, latin1, latin2, latin5, latin7, macce, macroman, sjis,
swe7, tis620, ucs2, ujis, utf8. (Additional character sets might be available. Check the output
from ./configure --help for the current list.)
The default collation may also be specified. MySQL uses the latin1_swedish_ci collation by
default. To change this, use the --with-collation option:
shell> ./configure --with-collation=COLLATION

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Source-Configuration Options

To change both the character set and the collation, use both the --with-charset and --withcollation options. The collation must be a legal collation for the character set. (Use the SHOW
COLLATION statement to determine which collations are available for each character set.)
With the configure option --with-extra-charsets=LIST, you can define which additional
character sets should be compiled into the server. LIST is one of the following:
• A list of character set names separated by spaces
• complex to include all character sets that can't be dynamically loaded
• all to include all character sets into the binaries
Clients that want to convert characters between the server and the client should use the SET NAMES
statement. See Section 10.1.4, “Connection Character Sets and Collations”.
•

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 21.3, “Debugging and Porting MySQL”.
As of MySQL 5.0.25, using --with-debug to configure MySQL with debugging support enables
you to use the --debug="d,parser_debug" option when you start the server. This causes the
Bison parser that is used to process SQL statements to dump a parser trace to the server's standard
error output. Typically, this output is written to the error log.
•

If your client programs are using threads, you must compile a thread-safe version of the
MySQL client library with the --enable-thread-safe-client configure option. This creates
a libmysqlclient_r library with which you should link your threaded applications. See
Section 20.6.4.2, “Writing C API Threaded Client Programs”.

•

Some features require that the server be built with compression library support, such as the
COMPRESS() and UNCOMPRESS() functions, and compression of the client/server protocol. The
--with-zlib-dir=no|bundled|DIR option provides control over compression library support.
The value no explicitly disables compression support. bundled causes the zlib library bundled
in the MySQL sources to be used. A DIR path name specifies the directory in which to find the
compression library sources.

•

It is possible to build MySQL with large table support using the --with-big-tables option,
beginning with MySQL 5.0.4.
This option causes the variables that store table row counts to be declared as unsigned long
long rather than unsigned long. This enables tables to hold up to approximately 1.844E
32 2
32
+19 ((2 ) ) rows rather than 2 (~4.295E+09) rows. Previously it was necessary to pass DBIG_TABLES to the compiler manually in order to enable this feature.

•

Run configure with the --disable-grant-options option to cause the --bootstrap, -skip-grant-tables, and --init-file options for mysqld to be disabled. For Windows, the
configure.js script recognizes the DISABLE_GRANT_OPTIONS flag, which has the same effect.
The capability is available as of MySQL 5.0.34.

•

This option allows MySQL Community Server features to be enabled. Additional options may be
required for individual features, such as --enable-profiling to enable statement profiling. This
option was added in MySQL 5.0.82.

•

In MySQL Community Server, this option enables the statement profiling capability exposed by
the SHOW PROFILE and SHOW PROFILES statements. (See Section 13.7.5.29, “SHOW PROFILES
Syntax”.) The option was added in MySQL 5.0.37.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Dealing with Problems Compiling MySQL

• See Section 2.20, “Operating System-Specific Notes”, for options that pertain to particular operating
systems.
• See Section 6.3.6.2, “Building MySQL with Support for Secure Connections”, for options that pertain
to configuring MySQL to support secure (encrypted) connections.

2.17.4 Dealing with Problems Compiling MySQL
All MySQL programs compile cleanly for us with no warnings on Solaris or Linux using gcc. On other
systems, warnings may occur due to differences in system include files. For other problems, check the
following list.
The solution to many problems involves reconfiguring. If you do need to reconfigure, take note of the
following:
• If configure is run after it has previously been run, it may use information that was gathered during
its previous invocation. This information is stored in config.cache. When configure starts up,
it looks for that file and reads its contents if it exists, on the assumption that the information is still
correct. That assumption is invalid when you reconfigure.
• Each time you run configure, you must run make again to recompile. However, you may want
to remove old object files from previous builds first because they were compiled using different
configuration options.
To prevent old configuration information or object files from being used, run these commands before
re-running configure:
shell> rm config.cache
shell> make clean

Alternatively, you can run make distclean.
The following list describes some of the problems that have been found to occur most often when
compiling MySQL:
• If you get errors such as the ones shown here when compiling sql_yacc.cc, you probably have
run out of memory or swap space:
Internal compiler error: program cc1plus got fatal signal 11
Out of virtual memory
Virtual memory exhausted

The problem is that gcc requires a huge amount of memory to compile sql_yacc.cc with inline
functions. Try running configure with the --with-low-memory option:
shell> ./configure --with-low-memory

This option causes -fno-inline to be added to the compile line if you are using gcc and -O0 if
you are using something else. You should try the --with-low-memory option even if you have
so much memory and swap space that you think you can't possibly have run out. This problem has
been observed to occur even on systems with generous hardware configurations, and the --withlow-memory option usually fixes it.
• By default, configure picks c++ as the compiler name and GNU c++ links with -lg++. If you are
using gcc, that behavior can cause problems during configuration such as this:
configure: error: installation or configuration problem:
C++ compiler cannot create executables.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Dealing with Problems Compiling MySQL

You might also observe problems during compilation related to g++, libg++, or libstdc++.
One cause of these problems is that you may not have g++, or you may have g++ but not libg++,
or libstdc++. Take a look at the config.log file. It should contain the exact reason why your C
++ compiler did not work. To work around these problems, you can use gcc as your C++ compiler.
Try setting the environment variable CXX to "gcc -O3". For example:
shell> CXX="gcc -O3" ./configure

This works because gcc compiles C++ source files as well as g++ does, but does not link in libg++
or libstdc++ by default.
Another way to fix these problems is to install g++, libg++, and libstdc++. However, do not use
libg++ or libstdc++ with MySQL because this only increases the binary size of mysqld without
providing any benefits. Some versions of these libraries have also caused strange problems for
MySQL users in the past.
•

To define flags to be used by your C or C++ compilers, specify them using the CFLAGS and
CXXFLAGS environment variables. You can also specify the compiler names this way using CC and
CXX. For example:
shell>
shell>
shell>
shell>
shell>

CC=gcc
CFLAGS=-O3
CXX=gcc
CXXFLAGS=-O3
export CC CFLAGS CXX CXXFLAGS

To see what flags you might need to specify, invoke mysql_config with the --cflags option.
• If you get errors such as those shown here when compiling mysqld, configure did not correctly
detect the type of the last argument to accept(), getsockname(), or getpeername():
cxx: Error: mysqld.cc, line 645: In this statement, the referenced
type of the pointer value ''length'' is ''unsigned long'',
which is not compatible with ''int''.
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);

To fix this, edit the config.h file (which is generated by configure). Look for these lines:
/* Define as the base type of the last arg to accept */
#define SOCKET_SIZE_TYPE XXX

Change XXX to size_t or int, depending on your operating system. (You must do this each time
you run configure because configure regenerates config.h.)
• If your compile fails with errors such as any of the following, you must upgrade your version of make
to GNU make:
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

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Compiling and Linking an Optimized mysqld Server

Solaris and FreeBSD are known to have troublesome make programs.
GNU make 3.75 is known to work.
• The sql_yacc.cc file is generated from sql_yacc.yy. Normally, the build process does not need
to create sql_yacc.cc because MySQL comes with a pregenerated copy. However, if you do need
to re-create it, you might encounter this error:
"sql_yacc.yy", line xxx fatal: default action causes potential...

This is a sign that your version of yacc is deficient. You probably need to install bison (the GNU
version of yacc) and use that instead.
Versions of bison older than 1.75 may report this error:
sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded

The maximum table size is not actually exceeded; the error is caused by bugs in older versions of
bison.
• On Debian Linux 3.0, you need to install gawk instead of the default mawk if you want to compile
MySQL with Berkeley DB support.
• If you get a compilation error on Linux (for example, SuSE Linux 8.1 or Red Hat Linux 7.3) similar to
the following one, you probably do not have g++ installed:
libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
incompatible pointer type
libmysql.c:1329: too few arguments to function `gethostbyname_r'
libmysql.c:1329: warning: assignment makes pointer from integer
without a cast
make[2]: *** [libmysql.lo] Error 1

By default, the configure script attempts to determine the correct number of arguments by using
g++ (the GNU C++ compiler). This test yields incorrect results if g++ is not installed. There are two
ways to work around this problem:
• Make sure that the GNU C++ g++ is installed. On some Linux distributions, the required package
is called gpp; on others, it is named gcc-c++.
• Use gcc as your C++ compiler by setting the CXX environment variable to gcc:
export CXX="gcc"

You must run configure again after making either of those changes.
For information about acquiring or updating tools, see the system requirements in Section 2.17,
“Installing MySQL from Source”.

2.17.5 Compiling and Linking an Optimized mysqld Server
Most of the following tests were performed on Linux with the MySQL benchmarks, but they should give
some indication for other operating systems and workloads.
You obtain the fastest executables when you link with -static.
By using better compiler and compilation options, you can obtain a 10% to 30% speed increase in
applications. This is particularly important if you compile the MySQL server yourself.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Postinstallation Setup and Testing

When we tested both the Cygnus CodeFusion and Fujitsu compilers, neither was sufficiently bug-free
to enable MySQL to be compiled with optimizations enabled.
The standard MySQL binary distributions are compiled with support for all character sets. When you
compile MySQL yourself, you should include support only for the character sets that you are going to
use. This is controlled by the --with-charset option to configure.
Here is a list of some measurements that we have made:
• If you link dynamically (without -static), the result is 13% slower on Linux. Note that you still can
use a dynamically linked MySQL library for your client applications. It is the server that is most critical
for performance.
• For a connection from a client to a server running on the same host, if you connect using TCP/IP
rather than a Unix socket file, performance is 7.5% slower. (On Unix, if you connect to the host name
localhost, MySQL uses a socket file by default.)
• For TCP/IP connections from a client to a server, connecting to a remote server on another host is
8% to 11% slower than connecting to a server on the same host, even for connections faster than
100Mb/s Ethernet.
• When running our benchmark tests using secure connections (all data encrypted with internal SSL
support) performance was 55% slower than with unencrypted connections.
• If you compile with --with-debug=full, most queries are 20% slower. Some queries may take
substantially longer; for example, the MySQL benchmarks run 35% slower. If you use --withdebug (without =full), the speed decrease is only 15%. For a version of mysqld that has been
compiled with --with-debug=full, you can disable memory checking at runtime by starting it with
the --skip-safemalloc option. The execution speed should then be close to that obtained when
configuring with --with-debug.
• On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster than one compiled with gcc
3.2.
• On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster in 32-bit mode than in 64-bit
mode.
• Compiling with gcc 2.95.2 for UltraSPARC with the -mcpu=v8 -Wa,-xarch=v8plusa options
gives 4% better performance.
• Compiling on Linux-x86 using gcc without frame pointers (-fomit-frame-pointer or -fomitframe-pointer -ffixed-ebp) makes mysqld 1% to 4% faster.

2.18 Postinstallation Setup and Testing
This section discusses tasks that you should perform after installing MySQL:
• If necessary, initialize the data directory and create the MySQL grant tables. For some MySQL
installation methods, data directory initialization may be done for you automatically:
• Installation on Windows
• Installation on Linux using a server RPM distribution.
• Installation on OS X using a DMG distribution.
For other platforms and installation types, including installation from generic binary and source
distributions, you must initialize the data directory yourself. For instructions, see Section 2.18.1,
“Initializing the Data Directory”.
• For instructions, see Section 2.18.2, “Starting the Server”, and Section 2.18.3, “Testing the Server”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Initializing the Data Directory

• Assign passwords to any initial accounts in the grant tables, if that was not already done during data
directory initialization. Passwords prevent unauthorized access to the MySQL server. You may also
wish to restrict access to test databases. For instructions, see Section 2.18.4, “Securing the Initial
MySQL Accounts”.
• Optionally, arrange for the server to start and stop automatically when your system starts and stops.
For instructions, see Section 2.18.5, “Starting and Stopping MySQL Automatically”.
• Optionally, populate time zone tables to enable recognition of named time zones. For instructions,
see Section 10.6, “MySQL Server Time Zone Support”.
When you are ready to create additional user accounts, you can find information on the MySQL access
control system and account management in Section 6.2, “The MySQL Access Privilege System”, and
Section 6.3, “MySQL User Account Management”.

2.18.1 Initializing the Data Directory
After installing MySQL, you must initialize the data directory, including the tables in the mysql
system database. For some MySQL installation methods, data directory initialization may be done
automatically, as described in Section 2.18, “Postinstallation Setup and Testing”. For other installation
methods, including installation from generic binary and source distributions, you must initialize the data
directory yourself.
This section describes how to initialize the data directory on Unix and Unix-like systems. (For Windows,
see Section 2.10.6, “Windows Postinstallation Procedures”.) For some suggested commands that you
can use to test whether the server is accessible and working properly, see Section 2.18.3, “Testing the
Server”.
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. For information
about creating the account, see Creating a mysql System User and Group, in Section 2.16, “Installing
MySQL on Unix/Linux Using Generic Binaries”.
1. 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 have changed location to this directory.
You will find several files and subdirectories in the BASEDIR directory. The most important for
installation purposes are the bin and scripts subdirectories, which contain the server as well as
client and utility programs.
For some distribution types, mysqld is installed in the libexec directory.
2. If necessary, ensure that the distribution contents are accessible to mysql. If you installed the
distribution as mysql, no further action is required. If you installed the distribution as root, its
contents will be owned by root. Change its ownership to mysql by executing the following
commands as root in the installation directory. The first command changes the owner attribute of
the files to the mysql user. The second changes the group attribute to the mysql group.
shell> chown -R mysql .
shell> chgrp -R mysql .

3. If necessary, initialize the data directory, including the mysql database containing the initial MySQL
grant tables that determine how users are permitted to connect to the server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Initializing the Data Directory

Typically, data directory initialization need be done only the first time you install MySQL. If you are
upgrading an existing installation, you should run mysql_upgrade instead (see Section 4.4.9,
“mysql_upgrade — Check Tables for MySQL Upgrade”). However, the command that initializes
the data directory does not overwrite any existing privilege tables, so it should be safe to run in any
circumstances.
The exact location of mysql_install_db depends on the layout for your given installation.
To initialize the grant tables, use one of the following commands, depending on whether
mysql_install_db is located in the bin or scripts directory:
shell> bin/mysql_install_db --user=mysql
shell> scripts/mysql_install_db --user=mysql

It is important to make sure that the database directories and files are owned by the mysql login
account so that the server has read and write access to them when you run it later. To ensure this
if you run mysql_install_db as root, include the --user option as shown. Otherwise, you
should execute the program while logged in as mysql, in which case you can omit the --user
option from the command.
The mysql_install_db command creates the server's data directory. Under the data directory, it
creates directories for the mysql database that holds the grant tables and the test database that
you can use to test MySQL. The program also creates privilege table entries for the initial account
or accounts. test_. For a complete listing and description of the grant tables, see Section 6.2,
“The MySQL Access Privilege System”.
It might be necessary to specify other options such as --basedir or --datadir if
mysql_install_db does not identify the correct locations for the installation directory or data
directory. For example:
shell> bin/mysql_install_db --user=mysql \
--basedir=/opt/mysql/mysql \
--datadir=/opt/mysql/mysql/data

If you do not want to have the test database, you can remove it after starting the server, using the
instructions in Section 2.18.4, “Securing the Initial MySQL Accounts”.
If you have trouble with mysql_install_db at this point, see Section 2.18.1.1, “Problems
Running mysql_install_db”.
4. After initializing the data directory, you can establish the final installation ownership settings. To
leave the installation owned by mysql, no action is required here. Otherwise, most of the MySQL
installation can be owned by root if you like. The exception is that the data directory must be
owned by mysql. To accomplish this, run the following commands as root in the installation
directory. For some distribution types, the data directory might be named var rather than data;
adjust the second command accordingly.
shell> chown -R root .
shell> chown -R mysql data

If the plugin directory (the directory named by the plugin_dir system variable) is writable by
the server, it may be possible for a user to write executable code to a file in the directory using
SELECT ... INTO DUMPFILE. This can be prevented by making the plugin directory read only
to the server or by setting the secure_file_priv system variable at server startup to a directory
where SELECT writes can be performed safely.
5. If you installed MySQL using a source distribution, you may want to optionally copy one of the
provided configuration files from the support-files directory into your /etc directory. There
are different sample configuration files for different use cases, server types, and CPU and RAM
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Initializing the Data Directory

configurations. To use one of these standard files, copy it to /etc/my.cnf, or /etc/mysql/
my.cnf and edit and check the configuration before starting your MySQL server for the first time.
You can also create my.cnf yourself and place into it the options the server should use at startup.
See Section 5.1.2, “Server Configuration Defaults”.
If you do not copy one of the standard configuration files or create your own, the MySQL server
starts with its default settings.
6. If you want MySQL to start automatically when you boot your machine, see Section 2.18.5,
“Starting and Stopping MySQL Automatically”.
Data directory initialization creates time zone tables in the mysql database but does not populate
them. To do so, use the instructions in Section 10.6, “MySQL Server Time Zone Support”.

2.18.1.1 Problems Running mysql_install_db
The purpose of the mysql_install_db program is to initialize the data directory, including the tables
in the mysql system database. It does not overwrite existing MySQL privilege tables, and it does not
affect any other data.
To re-create your privilege tables, first stop the mysqld server if it is running. Then rename the
mysql directory under the data directory to save it, and run mysql_install_db. Suppose that
your current directory is the MySQL installation directory and that mysql_install_db is located in
the bin directory and the data directory is named data. To rename the mysql database and re-run
mysql_install_db, use these commands.
shell> mv data/mysql data/mysql.old
shell> bin/mysql_install_db --user=mysql

When you run mysql_install_db, you might encounter the following problems:
• mysql_install_db fails to install the grant tables
You may find that mysql_install_db fails to install the grant tables and terminates after
displaying the following messages:
Starting mysqld daemon with databases from XXXXXX
mysqld ended

In this case, you should examine the error log file very carefully. The log should be located in the
directory XXXXXX named by the error message and should indicate why mysqld did not start. If you
do not understand what happened, include the log when you post a bug report. See Section 1.7,
“How to Report Bugs or Problems”.
• There is a mysqld process running
This indicates that the server is running, in which case the grant tables have probably been created
already. If so, there is no need to run mysql_install_db at all because it needs to be run only
once, when you first install MySQL.
• Installing a second mysqld server does not work when one server is running
This can happen when you have an existing MySQL installation, but want to put a new installation
in a different location. For example, you might have a production installation, but you want to create
a second installation for testing purposes. Generally the problem that occurs when you try to run a
second server is that it tries to use a network interface that is in use by the first server. In this case,
you should see one of the following error messages:
Can't start server: Bind on TCP/IP port:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Starting the Server

Address already in use
Can't start server: Bind on unix socket...

For instructions on setting up multiple servers, see Section 5.5, “Running Multiple MySQL Instances
on One Machine”.
•

You do not have write access to the /tmp directory
If you do not have write access to create temporary files or a Unix socket file in the default location
(the /tmp directory), an error occurs when you run mysql_install_db or the mysqld server.
You can specify different locations for the temporary directory and Unix socket file by executing
these commands prior to starting mysql_install_db or mysqld, where some_tmp_dir is the full
path name to some directory for which you have write permission:
shell> TMPDIR=/some_tmp_dir/
shell> MYSQL_UNIX_PORT=/some_tmp_dir/mysql.sock
shell> export TMPDIR MYSQL_UNIX_PORT

Then you should be able to run mysql_install_db and start the server with these commands:
shell> bin/mysql_install_db --user=mysql
shell> bin/mysqld_safe --user=mysql &

If mysql_install_db is located in the scripts directory, modify the first command to scripts/
mysql_install_db.
See Section B.5.3.6, “How to Protect or Change the MySQL Unix Socket File”, and Section 2.21,
“Environment Variables”.
There are some alternatives to running the mysql_install_db program provided in the MySQL
distribution:
• If you want the initial privileges to be different from the standard defaults, use account-management
statements such as CREATE USER, GRANT, and REVOKE to change the privileges after the grant
tables have been set up. In other words, run mysql_install_db, and then use mysql -u root
mysql to connect to the server as the MySQL root user so that you can issue the necessary
statements. (See Section 13.7.1, “Account Management Statements”.)
To install MySQL on several machines with the same privileges, put the CREATE USER, GRANT,
and REVOKE statements in a file and execute the file as a script using mysql after running
mysql_install_db. For example:
shell> bin/mysql_install_db --user=mysql
shell> bin/mysql -u root < your_script_file

This enables you to avoid issuing the statements manually on each machine.
• It is possible to re-create the grant tables completely after they have previously been created. You
might want to do this if you are just learning how to use CREATE USER, GRANT, and REVOKE and
have made so many modifications after running mysql_install_db that you want to wipe out the
tables and start over.
To re-create the grant tables, stop the server if it is running and remove the mysql database
directory. Then run mysql_install_db again.

2.18.2 Starting the Server
This section describes how start the server on Unix and Unix-like systems. (For Windows, see
Section 2.10.4.4, “Starting the Server for the First Time”.) For some suggested commands that you
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Starting the Server

can use to test whether the server is accessible and working properly, see Section 2.18.3, “Testing the
Server”.
Start the MySQL server like this:
shell> bin/mysqld_safe --user=mysql &

It is important that the MySQL server be run using an unprivileged (non-root) login account. To ensure
this if you run mysqld_safe as root, include the --user option as shown. Otherwise, execute the
program while logged in as mysql, in which case you can omit the --user option from the command.
For further instructions for running MySQL as an unprivileged user, see Section 6.1.5, “How to Run
MySQL as a Normal User”.
If the command fails immediately and prints mysqld ended, look for information in the error log (which
by default is the host_name.err file in the data directory).
If the server is unable to access the data directory it starts or read the grant tables in the mysql
database, it writes a message to its error log. Such problems can occur if you neglected to create the
grant tables by initializing the data directory before proceeding to this step, or if you ran the command
that initializes the data directory without the --user option. Remove the data directory and run the
command with the --user option.
If you have other problems starting the server, see Section 2.18.2.1, “Troubleshooting Problems
Starting the MySQL Server”. For more information about mysqld_safe, see Section 4.3.2,
“mysqld_safe — MySQL Server Startup Script”.
You can set up new accounts using the bin/mysql_setpermission script if you install the DBI
and DBD::mysql Perl modules. See Section 4.6.15, “mysql_setpermission — Interactively
Set Permissions in Grant Tables”. For Perl module installation instructions, see Section 2.22, “Perl
Installation Notes”.
If you would like to use mysqlaccess and have the MySQL distribution in some nonstandard location,
you must change the location where mysqlaccess expects to find the mysql client. Edit the bin/
mysqlaccess script at approximately line 18. Search for a line that looks like this:
$MYSQL

= '/usr/local/bin/mysql';

# path to mysql executable

Change the path to reflect the location where mysql actually is stored on your system. If you do not do
this, a Broken pipe error will occur when you run mysqlaccess.

2.18.2.1 Troubleshooting Problems Starting the MySQL Server
This section provides troubleshooting suggestions for problems starting the server. For additional
suggestions for Windows systems, see Section 2.10.5, “Troubleshooting a MySQL Installation Under
Windows”.
If you have problems starting the server, here are some things to try:
• Check the error log to see why the server does not start.
• Specify any special options needed by the storage engines you are using.
• Make sure that the server knows where to find the data directory.
• Make sure that the server can access the data directory. The ownership and permissions of the data
directory and its contents must be set such that the server can read and modify them.
• Verify that the network interfaces the server wants to use are available.
Some storage engines have options that control their behavior. You can create a my.cnf file and
specify startup options for the engines that you plan to use. If you are going to use storage engines that
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Starting the Server

support transactional tables (InnoDB, BDB, NDB), be sure that you have them configured the way you
want before starting the server:
• If you are using InnoDB tables, see Section 14.2.1, “Configuring InnoDB”.
• If you are using BDB (Berkeley DB) tables, see Section 14.5.3, “BDB Startup Options”.
• If you are using MySQL Cluster, see Section 17.3, “MySQL Cluster Configuration”.
Storage engines will use default option values if you specify none, but it is recommended that you
review the available options and specify explicit values for those for which the defaults are not
appropriate for your installation.
When the mysqld server starts, it changes location to the data directory. This is where it expects to
find databases and where it expects to write log files. The server also writes the pid (process ID) file in
the data directory.
The data directory location is hardwired in when the server is compiled. This is where the server looks
for the data directory by default. If the data directory is located somewhere else on your system, the
server will not work properly. You can determine what the default path settings are by invoking mysqld
with the --verbose and --help options.
If the default locations do not match the MySQL installation layout on your system, you can override
them by specifying options to mysqld or mysqld_safe on the command line or in an option file.
To specify the location of the data directory explicitly, use the --datadir option. However, normally
you can tell mysqld the location of the base directory under which MySQL is installed and it looks for
the data directory there. You can do this with the --basedir option.
To check the effect of specifying path options, invoke mysqld with those options followed by the -verbose and --help options. For example, if you change location into the directory where mysqld
is installed and then run the following command, it shows the effect of starting the server with a base
directory of /usr/local:
shell> ./mysqld --basedir=/usr/local --verbose --help

You can specify other options such as --datadir as well, but --verbose and --help must be the
last options.
Once you determine the path settings you want, start the server without --verbose and --help.
If mysqld is currently running, you can find out what path settings it is using by executing this
command:
shell> mysqladmin variables

Or:
shell> mysqladmin -h host_name variables

host_name is the name of the MySQL server host.
If you get Errcode 13 (which means Permission denied) when starting mysqld, this means that
the privileges of the data directory or its contents do not permit server access. In this case, you change
the permissions for the involved files and directories so that the server has the right to use them. You
can also start the server as root, but this raises security issues and should be avoided.
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:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Starting the Server

shell> ls -la /usr/local/mysql/var

If the data directory or its files or subdirectories are not owned by the login account that you use for
running the server, change their ownership to that account. If the account is named mysql, use these
commands:
shell> chown -R mysql /usr/local/mysql/var
shell> chgrp -R mysql /usr/local/mysql/var

Even with correct ownership, MySQL might fail to start up if there is other security software running
on your system that manages application access to various parts of the file system. In this case,
reconfigure that software to enable mysqld to access the directories it uses during normal operation.
If the server fails to start up correctly, check the error log. Log files are located in the data directory
(typically C:\Program Files\MySQL\MySQL Server 5.0\data on Windows, /usr/local/
mysql/data for a Unix/Linux binary distribution, and /usr/local/var for a Unix/Linux source
distribution). Look in the data directory for files with names of the form host_name.err and
host_name.log, where host_name is the name of your server host. Then examine the last few lines
of these files. You can use tail to display them:
shell> tail host_name.err
shell> tail host_name.log

The error log should contain information that indicates why the server could not start. For example, you
might see something like this in the log:
000729 14:50:10
000729 14:50:10
000729 14:50:10

bdb: Recovery function for LSN 1 27595 failed
bdb: warning: ./test/t1.db: No such file or directory
Can't init databases

This means that you did not start mysqld with the --bdb-no-recover option and Berkeley DB
found something wrong with its own log files when it tried to recover your databases. To be able to
continue, you should move the old Berkeley DB log files from the database directory to some other
place, where you can later examine them. The BDB log files are named in sequence beginning with
log.0000000001, where the number increases over time.
If you are running mysqld with BDB table support and mysqld dumps core at startup, this could be
due to problems with the BDB recovery log. In this case, you can try starting mysqld with --bdb-norecover. If that helps, you should remove all BDB log files from the data directory and try starting
mysqld again without the --bdb-no-recover option.
If either of the following errors occur, it means that some other program (perhaps another mysqld
server) is using the TCP/IP port or Unix socket file that mysqld is trying to use:
Can't start server: Bind on TCP/IP port: Address already in use
Can't start server: Bind on unix socket...

Use ps to determine whether you have another mysqld server running. If so, shut down the server
before starting mysqld again. (If another server is running, and you really want to run multiple servers,
you can find information about how to do so in Section 5.5, “Running Multiple MySQL Instances on
One 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 do not get an error message like telnet: Unable to connect to remote host:
Connection refused, some other program is using the TCP/IP port that mysqld is trying to use.
You will need to track down what program this is and disable it, or else tell mysqld to listen to a
different port with the --port option. In this case, you will also need to specify the port number for
client programs when connecting to the server using TCP/IP.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Testing the Server

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 permit access to the port.
If the server starts but you cannot connect to it, you should make sure that you have an entry in /etc/
hosts that looks like this:
127.0.0.1

localhost

If you cannot get mysqld to start, you can try to make a trace file to find the problem by using the -debug option. See Section 21.3.3, “The DBUG Package”.

2.18.3 Testing the Server
After the data directory is initialized and you have started the server, perform some simple tests to
make sure that it works satisfactorily. This section assumes that your current location is the MySQL
installation directory and that it has a bin subdirectory containing the MySQL programs used here. If
that is not true, adjust the command path names accordingly.
Alternatively, add the bin directory to your PATH environment variable setting. That enables your shell
(command interpreter) to find MySQL programs properly, so that you can run a program by typing only
its name, not its path name. See Section 4.2.10, “Setting Environment Variables”.
Use mysqladmin to verify that the server is running. The following commands provide simple tests to
check whether the server is up and responding to connections:
shell> bin/mysqladmin version
shell> bin/mysqladmin variables

If you cannot connect to the server, specify a -u root option to connect as root. If you have
assigned a password for the root account already, you'll also need to specify -p on the command line
and enter the password when prompted. For example:
shell> bin/mysqladmin -u root -p version
Enter password: (enter root password here)

The output from mysqladmin version varies slightly depending on your platform and version of
MySQL, but should be similar to that shown here:
shell> bin/mysqladmin version
mysqladmin Ver 14.12 Distrib 5.0.96, for pc-linux-gnu on i686
...
Server version
Protocol version
Connection
UNIX socket
Uptime:

5.0.96
10
Localhost via UNIX socket
/var/lib/mysql/mysql.sock
14 days 5 hours 5 min 21 sec

Threads: 1 Questions: 366 Slow queries: 0
Opens: 0 Flush tables: 1 Open tables: 19
Queries per second avg: 0.000

To see what else you can do with mysqladmin, invoke it with the --help option.
Verify that you can shut down the server (include a -p option if the root account has a password
already):
shell> bin/mysqladmin -u root shutdown

Verify that you can start the server again. Do this by using mysqld_safe or by invoking mysqld
directly. For example:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Testing the Server

shell> bin/mysqld_safe --user=mysql &

If mysqld_safe fails, see Section 2.18.2.1, “Troubleshooting Problems Starting the MySQL Server”.
Run some simple tests to verify that you can retrieve information from the server. The output should be
similar to that shown here.
Use mysqlshow to see what databases exist:
shell> bin/mysqlshow
+--------------------+
|
Databases
|
+--------------------+
| information_schema |
| mysql
|
| test
|
+--------------------+

The list of installed databases may vary, but will always include the minimum of mysql and
information_schema.
If you specify a database name, mysqlshow displays a list of the tables within the database:
shell> bin/mysqlshow mysql
Database: mysql
+---------------------------+
|
Tables
|
+---------------------------+
| columns_priv
|
| db
|
| func
|
| help_category
|
| help_keyword
|
| help_relation
|
| help_topic
|
| host
|
| proc
|
| procs_priv
|
| tables_priv
|
| time_zone
|
| time_zone_leap_second
|
| time_zone_name
|
| time_zone_transition
|
| time_zone_transition_type |
| user
|
+---------------------------+

Use the mysql program to select information from a table in the mysql database:
shell> bin/mysql -e "SELECT User, Host FROM mysql.user" mysql
+------+-----------+
| User | Host
|
+------+-----------+
| root | localhost |
+------+-----------+

There is a benchmark suite in the sql-bench directory (under the MySQL installation directory) that
you can use to compare how MySQL performs on different platforms. The benchmark suite is written
in Perl. It requires the Perl DBI module that provides a database-independent interface to the various
databases, and some other additional Perl modules:
DBI
DBD::mysql
Data::Dumper
Data::ShowTable

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Securing the Initial MySQL Accounts

These modules can be obtained from CPAN (http://www.cpan.org/). See also Section 2.22.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 do not have the sql-bench directory, you probably installed MySQL using RPM files other than
the source RPM. (The source RPM includes the sql-bench benchmark directory.) In this case, you
must first install the benchmark suite before you can use it. There are separate benchmark RPM files
named mysql-bench-VERSION.i386.rpm that contain benchmark code and data.
If you have a source distribution, there are also tests in its tests subdirectory that you can run. For
example, to run auto_increment.tst, execute this command from the top-level directory of your
source distribution:
shell> mysql -vvf test < ./tests/auto_increment.tst

The expected result of the test can be found in the ./tests/auto_increment.res file.
At this point, your server is running and you can access it. To tighten security if you have not yet
assigned passwords to the initial account or accounts, follow the instructions in Section 2.18.4,
“Securing the Initial MySQL Accounts”.
For more information about mysql, mysqladmin, and mysqlshow, see Section 4.5.1, “mysql —
The MySQL Command-Line Tool”, Section 4.5.2, “mysqladmin — Client for Administering a MySQL
Server”, and Section 4.5.6, “mysqlshow — Display Database, Table, and Column Information”.

2.18.4 Securing the Initial MySQL Accounts
The MySQL installation process involves initializing the data directory, including the mysql database
containing the grant tables that define MySQL accounts. For details, see Section 2.18, “Postinstallation
Setup and Testing”.
This section describes how to assign passwords to the initial accounts created during the MySQL
installation procedure, if you have not already done so.
The mysql.user grant table defines the initial MySQL user accounts and their access privileges:
• Some accounts have the user name root. These are superuser accounts that have all privileges
and can do anything. If these root accounts have empty passwords, anyone can connect to the
MySQL server as root without a password and be granted all privileges.
• On Windows, root accounts are created that permit connections from the local host only.
Connections can be made by specifying the host name localhost or the IP address
127.0.0.1. If the user selects the Enable root access from remote machines option during
installation, the Windows installer creates another root account that permits connections from any
host.
• On Unix, each root account permits connections from the local host. Connections can be made
by specifying the host name localhost, the IP address 127.0.0.1, or the actual host name or
IP address.
An attempt to connect to the host 127.0.0.1 normally resolves to the localhost account.
However, this fails if the server is run with the --skip-name-resolve option, so the 127.0.0.1
account is useful in that case.
• If accounts for anonymous users were created, these have an empty user name. The anonymous
accounts have no password, so anyone can use them to connect to the MySQL server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Securing the Initial MySQL Accounts

• On Windows, there is one anonymous account that permits connections from the local host.
Connections can be made by specifying a host name of localhost. It has no global privileges.
(Before MySQL 5.0.36, it has all global privileges, just like the root accounts.)
• On Unix, each anonymous account permits connections from the local host. Connections can be
made by specifying a host name of localhost for one of the accounts, or the actual host name
or IP address for the other.
To display which accounts exist in the mysql.user table and check whether their passwords are
empty, use the following statement:
mysql> SELECT User, Host, Password FROM mysql.user;
+------+--------------------+----------+
| User | Host
| Password |
+------+--------------------+----------+
| root | localhost
|
|
| root | myhost.example.com |
|
| root | 127.0.0.1
|
|
|
| localhost
|
|
|
| myhost.example.com |
|
+------+--------------------+----------+

This output indicates that there are several root and anonymous-user accounts, none of which
have passwords. The output might differ on your system, but the presence of accounts with empty
passwords means that your MySQL installation is unprotected until you do something about it:
• Assign a password to each MySQL root account that does not have one.
• To prevent clients from connecting as anonymous users without a password, either assign a
password to each anonymous account or remove the accounts.
In addition, the mysql.db table contains rows that permit all accounts to access the test database
and other databases with names that start with test_. This is true even for accounts that otherwise
have no special privileges such as the default anonymous accounts. This is convenient for testing
but inadvisable on production servers. Administrators who want database access restricted only to
accounts that have permissions granted explicitly for that purpose should remove these mysql.db
table rows.
The following instructions describe how to set up passwords for the initial MySQL accounts, first for
the root accounts, then for the anonymous accounts. The instructions also cover how to remove
anonymous accounts, should you prefer not to permit anonymous access at all, and describe how
to remove permissive access to test databases. Replace new_password in the examples with the
password that you want to use. Replace host_name with the name of the server host. You can
determine this name from the output of the preceding SELECT statement. For the output shown,
host_name is myhost.example.com.
Note
For additional information about setting passwords, see Section 6.3.5,
“Assigning Account Passwords”. If you forget your root password after setting
it, see Section B.5.3.2, “How to Reset the Root Password”.
To set up additional accounts, see Section 6.3.2, “Adding User Accounts”.
You might want to defer setting the passwords until later, to avoid the need to specify them while you
perform additional setup or testing. However, be sure to set them before using your installation for
production purposes.

Assigning root Account Passwords
The root account passwords can be set several ways. The following discussion demonstrates three
methods:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Securing the Initial MySQL Accounts

• Use the SET PASSWORD statement
• Use the UPDATE statement
• Use the mysqladmin command-line client program
To assign passwords using SET PASSWORD, connect to the server as root and issue a SET
PASSWORD statement for each root account listed in the mysql.user table.
For Windows, do this:
shell>
mysql>
mysql>
mysql>

mysql -u root
SET PASSWORD FOR 'root'@'localhost' = PASSWORD('new_password');
SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('new_password');
SET PASSWORD FOR 'root'@'%' = PASSWORD('new_password');

The last statement is unnecessary if the mysql.user table has no root account with a host value of
%.
For Unix, do this:
shell>
mysql>
mysql>
mysql>

mysql -u root
SET PASSWORD FOR 'root'@'localhost' = PASSWORD('new_password');
SET PASSWORD FOR 'root'@'127.0.0.1' = PASSWORD('new_password');
SET PASSWORD FOR 'root'@'host_name' = PASSWORD('new_password');

You can also use a single statement that assigns a password to all root accounts by using UPDATE to
modify the mysql.user table directly. This method works on any platform:
shell> mysql -u root
mysql> UPDATE mysql.user SET Password = PASSWORD('new_password')
->
WHERE User = 'root';
mysql> FLUSH PRIVILEGES;

The FLUSH statement causes the server to reread the grant tables. Without it, the password change
remains unnoticed by the server until you restart it.
To assign passwords to the root accounts using mysqladmin, execute the following commands:
shell> mysqladmin -u root password "new_password"
shell> mysqladmin -u root -h host_name password "new_password"

Those commands apply both to Windows and to Unix. The double quotation marks 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.
The mysqladmin method of setting the root account passwords does not work for the
'root'@'127.0.0.1' account. Use the SET PASSWORD method shown earlier.
After the root passwords have been set, you must supply the appropriate password whenever you
connect as root to the server. For example, to shut down the server with mysqladmin, use this
command:
shell> mysqladmin -u root -p shutdown
Enter password: (enter root password here)

The mysql commands in the following instructions include a -p option based on the assumption that
you have assigned the root account passwords using the preceding instructions and must specify that
password when connecting to the server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Securing the Initial MySQL Accounts

Assigning Anonymous Account Passwords
To assign passwords to the anonymous accounts, connect to the server as root, then use either SET
PASSWORD or UPDATE.
To use SET PASSWORD on Windows, do this:
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('new_password');

To use SET PASSWORD on Unix, do this:
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> SET PASSWORD FOR ''@'localhost' = PASSWORD('new_password');
mysql> SET PASSWORD FOR ''@'host_name' = PASSWORD('new_password');

To set the anonymous-user account passwords with a single UPDATE statement, do this (on any
platform):
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> UPDATE mysql.user SET Password = PASSWORD('new_password')
->
WHERE User = '';
mysql> FLUSH PRIVILEGES;

The FLUSH statement causes the server to reread the grant tables. Without it, the password change
remains unnoticed by the server until you restart it.

Removing Anonymous Accounts
If you prefer to remove any anonymous accounts rather than assigning them passwords, do so as
follows on Windows:
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> DROP USER ''@'localhost';

On Unix, remove the anonymous accounts like this:
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> DROP USER ''@'localhost';
mysql> DROP USER ''@'host_name';

Securing Test Databases
By default, the mysql.db table contains rows that permit access by any user to the test database
and other databases with names that start with test_. (These rows have an empty User column
value, which for access-checking purposes matches any user name.) This means that such databases
can be used even by accounts that otherwise possess no privileges. If you want to remove any-user
access to test databases, do so as follows:
shell> mysql -u root -p
Enter password: (enter root password here)
mysql> DELETE FROM mysql.db WHERE Db LIKE 'test%';
mysql> FLUSH PRIVILEGES;

The FLUSH statement causes the server to reread the grant tables. Without it, the privilege change
remains unnoticed by the server until you restart it.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Starting and Stopping MySQL Automatically

With the preceding change, only users who have global database privileges or privileges granted
explicitly for the test database can use it. However, if you prefer that the database not exist at all,
drop it:
mysql> DROP DATABASE test;

Note
On Windows, you can also perform the process described in this section
using the Configuration Wizard (see Section 2.10.3.11, “The Security
Options Dialog”). On other platforms, the MySQL distribution includes
mysql_secure_installation, a command-line utility that automates much
of the process of securing a MySQL installation.

2.18.5 Starting and Stopping MySQL Automatically
This section discusses methods for starting and stopping the MySQL server.
Generally, you start the mysqld server in one of these ways:
• Invoke mysqld directly. This works on any platform.
• On Windows, you can set up a MySQL service that runs automatically when Windows starts. See
Section 2.10.4.7, “Starting MySQL as a Windows Service”.
• On Unix and Unix-like systems, you can invoke mysqld_safe, which tries to determine the proper
options for mysqld and then runs it with those options. See Section 4.3.2, “mysqld_safe —
MySQL Server Startup Script”.
• On systems that use System V-style run directories (that is, /etc/init.d and run-level specific
directories), invoke mysql.server. This script is used primarily at system startup and shutdown. It
usually is installed under the name mysql. The mysql.server script starts the server by invoking
mysqld_safe. See Section 4.3.3, “mysql.server — MySQL Server Startup Script”.
• On OS X, install a separate MySQL Startup Item package to enable automatic MySQL startup at
system startup. The Startup Item starts the server by invoking mysql.server. For details, see
Section 2.11, “Installing MySQL on OS X”.
The mysqld_safe and mysql.server scripts and the OS X Startup Item can be used to start the
server manually, or automatically at system startup time. mysql.server and the Startup Item also
can be used to stop the server.
The following table shows which option groups the server and startup scripts read from option files.
Table 2.8 MySQL Startup Scripts and Supported Server Option Groups
Script

Option Groups

mysqld

[mysqld], [server], [mysqld-major_version]

mysqld_safe

[mysqld], [server], [mysqld_safe]

mysql.server

[mysqld], [mysql.server], [server]

[mysqld-major_version] means that groups with names like [mysqld-4.1] and
[mysqld-5.0] are read by servers having versions 4.1.x, 5.0.x, and so forth. This feature can be
used to specify options that can be read only by servers within a given release series.
For backward compatibility, mysql.server also reads the [mysql_server] group and
mysqld_safe also reads the [safe_mysqld] group. However, you should update your option files to
use the [mysql.server] and [mysqld_safe] groups instead.
For more information on MySQL configuration files and their structure and contents, see Section 4.2.6,
“Using Option Files”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading or Downgrading MySQL

2.19 Upgrading or Downgrading MySQL
This section describes the steps to upgrade or downgrade a MySQL installation.
Upgrading is a common procedure, as you pick up bug fixes within the same MySQL release series
or significant features between major MySQL releases. You perform this procedure first on some test
systems to make sure everything works smoothly, and then on the production systems.
Downgrading is less common. Typically, you undo an upgrade because of some compatibility or
performance issue that occurs on a production system, and was not uncovered during initial upgrade
verification on the test systems. As with the upgrade procedure, perform and verify the downgrade
procedure on some test systems first, before using it on a production system.

2.19.1 Upgrading MySQL
This section describes how to upgrade to a new MySQL version.
• Supported Upgrade Methods
• Supported Upgrade Paths
• Before You Begin
• Performing an In-place Upgrade
• Performing a Logical Upgrade
• Upgrade Troubleshooting

Supported Upgrade Methods
• In-place Upgrade: Involves shutting down the old MySQL version, replacing the old MySQL binaries
or packages with the new ones, restarting MySQL on the existing data directory, and running
mysql_upgrade.
• Logical Upgrade: Involves exporting existing data from the old MySQL version using mysqldump,
installing the new MySQL version, loading the dump file into the new MySQL version, and running
mysql_upgrade.
Note
MySQL recommends a mysqldump upgrade when upgrading from a previous
release. For example, use this method when upgrading from 4.1 to 5.0.
For in-place and logical upgrade procedures, see Performing an In-place Upgrade, and Performing a
Logical Upgrade.
If you run MySQL Server on Windows, see Section 2.10.7, “Upgrading MySQL on Windows”.

Supported Upgrade Paths
Unless otherwise documented, the following upgrade paths are supported:
• Upgrading from a release series version to a newer release series version is supported. For
example, upgrading from 5.0.95 to 5.0.96 is supported. Skipping release series versions is also
supported. For example, upgrading from 5.0.92 to 5.0.96 is supported.
• Upgrading one release level is supported. For example, upgrading from 4.1 to 5.0 is supported.
Upgrading to the latest release series version is recommended before upgrading to the next release
level. For example, upgrade to the latest 4.1 release before upgrading to 5.0.
• Upgrading more than one release level is supported, but only if you upgrade one release level
at a time. For example, if you currently are running MySQL 4.0 and wish to upgrade to a newer
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

series, upgrade to MySQL 4.1 first before upgrading to MySQL 5.0, and so forth. For information on
upgrading to MySQL 4.1 or earlier releases, see the MySQL 3.23, 4.0, 4.1 Reference Manual.
• Direct upgrades that skip a release level (for example, upgrading directly from MySQL 4.0 to 5.0) are
not recommended or supported.
The following conditions apply to all upgrade paths:
• Upgrades between General Availability (GA) status releases are supported.
• Upgrades between milestone releases (or from a milestone release to a GA release) are not
supported.
• For upgrades between versions of a MySQL release series that has reached GA status, you can
move the MySQL format files and data files between different versions on systems with the same
architecture. This is not necessarily true for upgrades between milestone releases. Use of milestone
releases is at your own risk.

Before You Begin
Before upgrading, review the following information and perform the recommended steps:
• Before upgrading, protect your data by creating a backup of your current databases and log files.
The backup should include the mysql database, which contains the MySQL system tables. See
Section 7.2, “Database Backup Methods”.
• Review the Release Notes which provide information about features that are new in the MySQL
5.0 or differ from those found in earlier MySQL releases. Some of these changes may result in
incompatibilities.
• Review Section 2.19.1.1, “Changes Affecting Upgrades to 5.0”. This section describes changes that
may require action before or after upgrading.
• Check Section 2.19.3, “Checking Whether Tables or Indexes Must Be Rebuilt”, to see whether
changes to table formats or to character sets or collations were made between your current
version of MySQL and the version to which you are upgrading. If such changes have resulted in
an incompatibility between MySQL versions, you will need to upgrade the affected tables using the
instructions in Section 2.19.4, “Rebuilding or Repairing Tables or Indexes”.
• If you use replication, see Section 16.4.3, “Upgrading a Replication Setup”, for information on
upgrading your replication setup.
• If you use XA transactions with InnoDB, run XA RECOVER before upgrading to check for
uncommitted XA transactions. If results are returned, either commit or rollback the XA transactions
by issuing an XA COMMIT or XA ROLLBACK statement.
• If your MySQL installation contains a large amount of data that might take a long time to convert after
an in-place upgrade, you might find it useful to create a “dummy” database instance for assessing
what conversions might be needed and the work involved to perform them. Make a copy of your
MySQL instance that contains a full copy of the mysql database, plus all other databases without
data. Run your upgrade procedure on this dummy instance to see what actions might be needed
so that you can better evaluate the work involved when performing actual data conversion on your
original database instance.
• Rebuilding and reinstalling the Perl DBD::mysql module whenever you install or upgrade to a new
release of MySQL is recommended. The same applies to other MySQL interfaces as well, such as
PHP mysql extensions and the Python MySQLdb module.

Performing an In-place Upgrade
This section describes how to perform an in-place upgrade. Review Before you Begin before
proceeding.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

Note
If you upgrade an installation originally produced by installing multiple RPM
packages, upgrade all the packages, not just some. For example, if you
previously installed the server and client RPMs, do not upgrade just the server
RPM.
To perform an in-place upgrade:
1. Review the changes described in Section 2.19.1.1, “Changes Affecting Upgrades to 5.0” for steps
to be performed before upgrading.
2. If you use InnoDB, configure MySQL to perform a slow shutdown. For example:
shell> bin/mysql -u root -ppassword --execute="set global innodb_fast_shutdown=0"

With a slow shutdown, InnoDB performs a full purge and change buffer merge before shutting
down, which ensures that data files are fully prepared in case of file format differences between
releases.
3. Stop the old MySQL server.
4. Upgrade the MySQL binaries or packages in place (replace the 4.1 binaries with those from 5.0).
5. Start the MySQL 5.0 server using the existing data directory.
6. Run mysql_upgrade. For example:
shell> bin/mysql_upgrade -u root -ppassword

mysql_upgrade examines all tables in all databases for incompatibilities with the current version
of MySQL Server. mysql_upgrade also upgrades the system tables so that you can take
advantage of new privileges or capabilities.
Note
mysql_upgrade does not upgrade the contents of the help tables. For
upgrade instructions, see Section 5.1.8, “Server-Side Help”.

Performing a Logical Upgrade
This section describes how to perform a logical upgrade. Review Before you Begin before proceeding.
To perform a logical upgrade:
1. Review the changes described in Section 2.19.1.1, “Changes Affecting Upgrades to 5.0” for steps
to be performed before upgrading.
2. Export your existing data from the previous MySQL version:
shell> mysqldump --add-drop-table --add-drop-table
-> --all-databases --force > data-for-upgrade.sql

Note
The --all-databases option includes all databases in the dump,
including the mysql database that holds the system tables.
3. Stop the old MySQL server.
4. Install MySQL 5.0.
5. Initialize a new data directory:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

shell> scripts/mysql_install_db --user=mysql --datadir=/path/to/5.0-datadir

6. Start the MySQL 5.0 server using the new data directory.
7. Load the previously created dump file into the new MySQL server. For example:
shell> bin/mysql -u root -ppassword --execute="source data-for-upgrade.sql" --force

8. Run mysql_upgrade. For example:
shell> bin/mysql_upgrade -u root -ppassword

mysql_upgrade examines all tables in all databases for incompatibilities with the current version
of MySQL Server. mysql_upgrade also upgrades the system tables so that you can take
advantage of new privileges or capabilities.
Note
mysql_upgrade does not upgrade the contents of the help tables. For
upgrade instructions, see Section 5.1.8, “Server-Side Help”.
9. If you use InnoDB, configure MySQL to perform a slow shutdown. For example:
shell> bin/mysql -u root -ppassword --execute="set global innodb_fast_shutdown=0"

10. Shut down and restart the MySQL server to ensure a clean shutdown and startup.

Upgrade Troubleshooting
• If problems occur, such as that the new mysqld server does not start or that you cannot connect
without a password, verify that you do not have an old my.cnf file from your previous installation.
You can check this with the --print-defaults option (for example, mysqld --printdefaults). If this command displays anything other than the program name, you have an active
my.cnf file that affects server or client operation.
• If, after an upgrade, you experience problems with compiled 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, 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. Recompilation might also be necessary for
programs compiled against the shared client library if the library major version number has changed
(for example from libmysqlclient.so.15 to libmysqlclient.so.16.
• If you have created a user-defined function (UDF) with a given name and upgrade MySQL to a
version that implements a new built-in function with the same name, the UDF becomes inaccessible.
To correct this, use DROP FUNCTION to drop the UDF, and then use CREATE FUNCTION to
re-create the UDF with a different nonconflicting name. The same is true if the new version of
MySQL implements a built-in function with the same name as an existing stored function. See
Section 9.2.3, “Function Name Parsing and Resolution”, for the rules describing how the server
interprets references to different kinds of functions.

2.19.1.1 Changes Affecting Upgrades to 5.0
Before upgrading to MySQL 5.0, review the changes described in this section to identify upgrade
issues that apply to your current MySQL installation and applications.
Changes marked as either Known issue or Incompatible change are incompatibilities with earlier
versions of MySQL, and may require your attention before you upgrade. Our aim is to avoid these
changes, but occasionally they are necessary to correct problems that would be worse than an
incompatibility between releases. If any upgrade issue applicable to your installation involves an
incompatibility that requires special handling, follow the instructions given in the incompatibility
description. Sometimes this involves dumping and reloading tables, or use of a statement such as
CHECK TABLE or REPAIR TABLE.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

For dump and reload instructions, see Section 2.19.4, “Rebuilding or Repairing Tables or Indexes”. Any
procedure that involves REPAIR TABLE with the USE_FRM option must be done before upgrading. Use
of this statement with a version of MySQL different from the one used to create the table (that is, using
it after upgrading) may damage the table. See Section 13.7.2.6, “REPAIR TABLE Syntax”.
Note
Several visible behaviors have changed between MySQL 4.1 and MySQL 5.0 to
make MySQL more compatible with standard SQL. These changes may affect
your applications.
• System Table Changes
• Server Changes
• SQL Changes
• C API Changes

System Table Changes
• After upgrading a 5.0 installation to 5.0.10 or higher, it is necessary to upgrade your grant tables.
Otherwise, creating stored procedures and functions might not work. The procedure for doing this is
described in Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.

Server Changes
• MySQL 5.0.27 is the last version in MySQL 5.0 for which MySQL-Max binary distributions are
provided, except for RPM distributions. For RPMs, MySQL 5.0.37 is the last release. After these
versions, the features previously included in the mysqld-max server are included in mysqld.
If you previously installed a MySQL-Max distribution that includes a server named mysqld-max,
and then upgrade later to a non-Max version of MySQL, mysqld_safe still attempts to run the old
mysqld-max server. If you perform such an upgrade, you should remove the old mysqld-max
server manually to ensure that mysqld_safe runs the new mysqld server.
• Incompatible change: Character set or collation changes may require table indexes to be rebuilt.
In MySQL 5.0, these occurred in version 5.0.48. For details, see Section 2.19.3, “Checking Whether
Tables or Indexes Must Be Rebuilt”.
• Incompatible change: SHOW CREATE VIEW displays view definitions using an AS alias_name
clause for each column. If a column is created from an expression, the default alias is the expression
text, which can be quite long. As of MySQL 5.0.52, aliases for column names in CREATE VIEW
statements are checked against the maximum column length of 64 characters (not the maximum
alias length of 256 characters). As a result, views created from the output of SHOW CREATE VIEW
fail if any column alias exceeds 64 characters. This can cause problems for replication or loading
dump files. For additional information and workarounds, see Section C.4, “Restrictions on Views”.
• Incompatible change: Beginning with MySQL 5.0.42, when a DATE value is compared with a
DATETIME value, the DATE value is coerced to the DATETIME type by adding the time portion as
00:00:00. Previously, the time portion of the DATETIME value was ignored, or the comparison
could be performed as a string comparison. To mimic the old behavior, use the CAST() function to
cause the comparison operands to be treated as previously. For example:
date_col = CAST(NOW() AS DATE)

• Incompatible change: For ENUM columns that had enumeration values containing commas, the
commas were mapped to 0xff internally. However, this rendered the commas indistinguishable
from true 0xff characters in the values. This no longer occurs. However, the fix requires that you
dump and reload any tables that have ENUM columns containing true 0xff in their values: Dump the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

tables using mysqldump with the current server before upgrading from a version of MySQL 5.0 older
than 5.0.36 to version 5.0.36 or newer.
• Incompatible change. For BINARY columns, the pad value and how it is handled has changed as of
MySQL 5.0.15. The pad value for inserts now is 0x00 rather than space, and there is no stripping of
the pad value for retrievals. For details, see Section 11.4.2, “The BINARY and VARBINARY Types”.
• Incompatible change: As of MySQL 5.0.13, InnoDB rolls back only the last statement on a
transaction timeout. As of MySQL 5.0.32, a new option, --innodb_rollback_on_timeout,
causes InnoDB to abort and roll back the entire transaction if a transaction timeout occurs (the same
behavior as in MySQL 4.1).
• Incompatible change: The namespace for triggers changed in MySQL 5.0.10. Previously, trigger
names had to be unique per table. Now they must be unique within the schema (database). An
implication of this change is that DROP TRIGGER syntax now uses a schema name instead of a table
name (schema name is optional and, if omitted, the current schema will be used).
When upgrading from a version of MySQL 5 older than 5.0.10 to MySQL 5.0.10 or newer, you must
drop all triggers and re-create them or DROP TRIGGER will not work after the upgrade. Here is a
suggested procedure for doing this:
1. Upgrade to MySQL 5.0.10 or later to be able to access trigger information in the
INFORMATION_SCHEMA.TRIGGERS table. (This should work even for pre-5.0.10 triggers.)
2. Dump all trigger definitions using the following SELECT statement:
SELECT CONCAT('CREATE TRIGGER ', t.TRIGGER_SCHEMA, '.', t.TRIGGER_NAME,
' ', t.ACTION_TIMING, ' ', t.EVENT_MANIPULATION, ' ON ',
t.EVENT_OBJECT_SCHEMA, '.', t.EVENT_OBJECT_TABLE,
' FOR EACH ROW ', t.ACTION_STATEMENT, '//' )
INTO OUTFILE '/tmp/triggers.sql'
FROM INFORMATION_SCHEMA.TRIGGERS AS t;

The statement uses INTO OUTFILE, so you must have the FILE privilege. The file will be
created on the server host. Use a different file name if you like. To be 100% safe, inspect the
trigger definitions in the triggers.sql file, and perhaps make a backup of the file.
3. Stop the server and drop all triggers by removing all .TRG files in your database directories.
Change location to your data directory and issue this command:
shell> rm */*.TRG

4. Start the server and re-create all triggers using the triggers.sql file:
mysql> delimiter // ;
mysql> source /tmp/triggers.sql //

5. Use the SHOW TRIGGERS statement to check that all triggers were created successfully.
• Incompatible change: The indexing order for end-space in TEXT columns for InnoDB and MyISAM
tables has changed. Starting from 5.0.3, TEXT indexes are compared as space-padded at the end
(just as MySQL sorts CHAR, VARCHAR and TEXT fields). If you have an index on a TEXT column, you
should run CHECK TABLE on it. If the check reports errors, rebuild the indexes: Dump and reload the
table if it is an InnoDB table, or run OPTIMIZE TABLE or REPAIR TABLE if it is a MyISAM table.
• Incompatible change. As of MySQL 5.0.3, trailing spaces no longer are removed from values
stored in VARCHAR and VARBINARY columns. The maximum lengths for VARCHAR and VARBINARY
columns in MySQL 5.0.3 and later are 65,535 characters and 65,535 bytes, respectively.
When a binary upgrade (file system-level copy of data files) to MySQL 5.0 is performed for a table
with a VARBINARY column, the column is space-padded to the full permissible width of the column.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

This causes values in VARBINARY columns that do not occupy the full width of the column to include
extra trailing spaces after the upgrade, which means that the data in the column is different.
In addition, new rows inserted into a table upgraded in this way will be space padded to the full width
of the column.
This issue can be resolved as follows:
1. For each table containing VARBINARY columns, execute the following statement, where
tbl_name is the name of the table and engine_name is the name of the storage engine
currently used by tbl_name:
ALTER TABLE tbl_name ENGINE=engine_name;

In other words, if the table named mytable uses the MyISAM storage engine, then you would
use this statement:
ALTER TABLE mytable ENGINE=MYISAM;

This rebuilds the table so that it uses the 5.0 VARBINARY format.
2. Then you must remove all trailing spaces from any VARBINARY column values. For each
VARBINARY column varbinary_column, execute the following statement, where tbl_name is
the name of the table containing the VARBINARY column:
UPDATE tbl_name SET varbinary_column = RTRIM(varbinary_column);

This is necessary and safe because trailing spaces are stripped before 5.0.3, meaning that any
trailing spaces are erroneous.
This problem does not occur (and thus these two steps are not required) for tables upgraded using
the recommended procedure of dumping tables prior to the upgrade and reloading them afterward.
Note
If you create a table with new VARCHAR or VARBINARY columns in MySQL
5.0.3 or later, the table will not be usable if you downgrade to a version older
than 5.0.3. Dump the table with mysqldump before downgrading and reload it
after downgrading.
• Incompatible change: The implementation of DECIMAL was changed in MySQL 5.0.3. You
should make your applications aware of this change. For information about this change, and about
possible incompatibilities with old applications, see Section 12.17, “Precision Math”, in particular,
Section 12.17.2, “DECIMAL Data Type Characteristics”.
DECIMAL columns are stored in a more efficient format. To convert a table to use the new DECIMAL
type, you should do an ALTER TABLE on it. (The ALTER TABLE also will change the table's
VARCHAR columns to use the new VARCHAR data type properties, described in a separate item.)
A consequence of the change in handling of the DECIMAL and NUMERIC fixed-point data types is
that the server is more strict to follow standard SQL. For example, a data type of DECIMAL(3,1)
stores a maximum value of 99.9. Before MySQL 5.0.3, the server permitted larger numbers to be
stored. That is, it stored a value such as 100.0 as 100.0. As of MySQL 5.0.3, the server clips 100.0
to the maximum permissible value of 99.9. If you have tables that were created before MySQL 5.0.3
and that contain floating-point data not strictly legal for the data type, you should alter the data types
of those columns. For example:
ALTER TABLE tbl_name MODIFY col_name DECIMAL(4,1);

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

The behavior used by the server for DECIMAL columns in a table depends on the version of MySQL
used to create the table. If your server is from MySQL 5.0.3 or higher, but you have DECIMAL
columns in tables that were created before 5.0.3, the old behavior still applies to those columns. To
convert the tables to the newer DECIMAL format, dump them with mysqldump and reload them.
• Incompatible change: MySQL 5.0.3 and up uses precision math when calculating with DECIMAL
and integer columns (64 decimal digits) and for rounding exact-value numbers. Rounding behavior
is well-defined, not dependent on the implementation of the underlying C library. However, this
might result in incompatibilities for applications that rely on the old behavior. (For example,
inserting .5 into an INT column results in 1 as of MySQL 5.0.3, but might be 0 in older versions.)
For more information about rounding behavior, see Section 12.17.4, “Rounding Behavior”, and
Section 12.17.5, “Precision Math Examples”.
•

Incompatible change: In very old versions of MySQL (prior to 4.1), the TIMESTAMP data type
supported a display width, which was silenty ignored beginning with MySQL 4.1. This is deprecated
in MySQL 5.1, and removed altogether in MySQL 5.5. These changes in behavior can lead to two
problem scenarios when trying to use TIMESTAMP(N) columns with a MySQL 5.5 or later server:
• When importing a dump file (for example, one created using mysqldump) created in a MySQL 5.0
or earlier server into a server from a newer release series, a CREATE TABLE or ALTER TABLE
statement containing TIMESTAMP(N) causes the import to fail with a syntax error.
To fix this problem, edit the dump file in a text editor to replace any instances of TIMESTAMP(N)
with TIMESTAMP prior to importing the file. Be sure to use a plain text editor for this, and not a
word processor; otherwise, the result is almost certain to be unusable for importing into the MySQL
server.
• When trying replicate any CREATE TABLE or ALTER TABLE statement containing
TIMESTAMP(N) from a master MySQL server that supports the TIMESTAMP(N) syntax to a
MySQL 5.5 or newer slave, the statement causes replication to fail. Similarly, when you try to
restore from a binary log written by a server that supports TIMESTAMP(N) to a MySQL 5.5 or
newer server, any CREATE TABLE or ALTER TABLE statement containing TIMESTAMP(N)
causes the backup to fail. This holds true regardless of the logging format used by a MySQL 5.1 or
newer server.
It may be possible to fix such issues using a hex editor, by replacing any width arguments used
with TIMESTAMP, and the parentheses containing them, with space characters (hexadecimal 20).
This can be made to work as long as checksums were not enabled when creating the binary log.
Be sure to use a programmer's binary hex editor and not a regular text editor or word processor
for this; otherwise, the result is almost certain to be a corrupted binary log file. To guard against
accidental corruption of the binary log, you should always work on a copy of the file rather than the
original.
You should try to handle potential issues of these types proactively by updating with ALTER TABLE
any TIMESTAMP(N) columns in your databases so that they use TIMESTAMP instead, before
performing any upgrades.

• Incompatible change: MyISAM and InnoDB tables created with DECIMAL columns in MySQL
5.0.3 to 5.0.5 will appear corrupt after an upgrade to MySQL 5.0.6. (The same incompatibility will
occur for these tables created in MySQL 5.0.6 after a downgrade to MySQL 5.0.3 to 5.0.5.) If you
have such tables, check and repair them with mysql_upgrade after upgrading. See Section 4.4.9,
“mysql_upgrade — Check Tables for MySQL Upgrade”.
• Incompatible change: For user-defined functions, exact-value decimal arguments such as 1.3
or DECIMAL column values were passed as REAL_RESULT values prior to MySQL 5.0.3. As of
5.0.3, they are passed as strings with a type of DECIMAL_RESULT. If you upgrade to 5.0.3 and find
that your UDF now receives string values, use the initialization function to coerce the arguments to
numbers as described in Section 21.2.2.3, “UDF Argument Processing”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

• Incompatible change: As of MySQL 5.0.3, the server by default no longer loads user-defined
functions (UDFs) unless they have at least one auxiliary symbol (for example, an xxx_init
or xxx_deinit symbol) defined in addition to the main function symbol. This behavior can be
overridden with the --allow-suspicious-udfs option. See Section 21.2.2.6, “UDF Security
Precautions”.
• Incompatible change: The update log has been removed in MySQL 5.0. If you had enabled it
previously, enable the binary log instead.
• Incompatible change: Support for the ISAM storage engine has been removed in MySQL 5.0. If
you have any ISAM tables, you should convert them before upgrading. For example, to convert an
ISAM table to use the MyISAM storage engine, use this statement:
ALTER TABLE tbl_name ENGINE = MyISAM;

Use a similar statement for every ISAM table in each of your databases.
• Incompatible change: Support for RAID options in MyISAM tables has been removed in MySQL
5.0. If you have tables that use these options, you should convert them before upgrading. One
way to do this is to dump them with mysqldump, edit the dump file to remove the RAID options
in the CREATE TABLE statements, and reload the dump file. Another possibility is to use CREATE
TABLE new_tbl ... SELECT raid_tbl to create a new table from the RAID table. However,
the CREATE TABLE part of the statement must contain sufficient information to re-create column
attributes as well as indexes, or column attributes may be lost and indexes will not appear in the new
table. See Section 13.1.10, “CREATE TABLE Syntax”.
The .MYD files for RAID tables in a given database are stored under the database directory in
subdirectories that have names consisting of two hex digits in the range from 00 to ff. After
converting all tables that use RAID options, these RAID-related subdirectories still will exist but can
be removed. Verify that they are empty, and then remove them manually. (If they are not empty, this
indicates that there is some RAID table that has not been converted.)
• As of MySQL 5.0.25, the lc_time_names system variable specifies the locale that controls the
language used to display day and month names and abbreviations. This variable affects the output
from the DATE_FORMAT(), DAYNAME() and MONTHNAME() functions. See Section 10.7, “MySQL
Server Locale Support”.
• In MySQL 5.0.6, binary logging of stored routines and triggers was changed. This change has
implications for security, replication, and data recovery, as discussed in Section 18.6, “Binary
Logging of Stored Programs”.
• As of MySQL 5.0.28, mysqld_safe no longer implicitly invokes mysqld-max if it exists. Instead,
it invokes mysqld unless a --mysqld or --mysqld-version option is given to specify another
server explicitly. If you previously relied on the implicit invocation of mysqld-max, you should use an
appropriate option now.

SQL Changes
• Known issue: Prior to MySQL 5.0.46, the parser accepted invalid code in SQL condition handlers,
leading to server crashes or unexpected execution behavior in stored programs. Specifically, the
parser permitted a condition handler to refer to labels for blocks that enclose the handler declaration.
This was incorrect because block label scope does not include the code for handlers declared within
the labeled block.
As of 5.0.46, the parser rejects this invalid construct, but if you upgrade in place (without dumping
and reloading your databases), existing handlers that contain the construct still are invalid even if
they appear to function as you expect and should be rewritten.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

To find affected handlers, use mysqldump to dump all stored procedures and functions, triggers,
and events. Then attempt to reload them into an upgraded server. Handlers that contain illegal label
references will be rejected.
For more information about condition handlers and writing them to avoid invalid jumps, see
Section 13.6.7.2, “DECLARE ... HANDLER Syntax”.
• Known issue: The fix for Bug #23491 introduced a problem with SHOW CREATE VIEW, which is
used by mysqldump. This causes an incompatibility when upgrading from versions affected by that
bug fix (MySQL 5.0.40 through 5.0.43, MySQL 5.1.18 through 5.1.19): If you use mysqldump before
upgrading from an affected version and reload the data after upgrading to a higher version, you must
drop and recreate your views.
• Incompatible change: The parser accepted statements that contained /* ... */ that were not
properly closed with */, such as SELECT 1 /* + 2. As of MySQL 5.0.50, statements that contain
unclosed /*-comments now are rejected with a syntax error.
This fix has the potential to cause incompatibilities. Because of Bug #26302, which caused the
trailing */ to be truncated from comments in views, stored routines, triggers, and events, it is
possible that objects of those types may have been stored with definitions that now will be rejected
as syntactically invalid. Such objects should be dropped and re-created so that their definitions do
not contain truncated comments. If a stored object definition contains only a single statement (does
not use a BEGIN ... END block) and contains a comment within the statement, the comment
should be moved to follow the statement or the object should be rewritten to use a BEGIN ... END
block. For example, this statement:
CREATE PROCEDURE p() SELECT 1 /* my comment */ ;

Can be rewritten in either of these ways:
CREATE PROCEDURE p() SELECT 1; /* my comment */
CREATE PROCEDURE p() BEGIN SELECT 1 /* my comment */ ; END;

• Incompatible change: If you have created a user-defined function (UDF) with a given name and
upgrade MySQL to a version that implements a new built-in function with the same name, the
UDF becomes inaccessible. To correct this, use DROP FUNCTION to drop the UDF, and then use
CREATE FUNCTION to re-create the UDF with a different nonconflicting name. If a new version
of MySQL implements a built-in function with the same name as an existing stored function, you
have two choices: Rename the stored function to use a nonconflicting name, or change calls to the
function so that they use a database qualifier (that is, use db_name.func_name() syntax). See
Section 9.2.3, “Function Name Parsing and Resolution”, for the rules describing how the server
interprets references to different kinds of functions.
• Incompatible change: As of MySQL 5.0.15, the CHAR() function returns a binary string rather than
a string in the connection character set. An optional USING charset_name clause may be used to
produce a result in a specific character set instead. Also, arguments larger than 256 produce multiple
characters. They are no longer interpreted modulo 256 to produce a single character each. These
changes may cause some incompatibilities:
• CHAR(ORD('A')) = 'a' is no longer true:
mysql> SELECT CHAR(ORD('A')) = 'a';
+----------------------+
| CHAR(ORD('A')) = 'a' |
+----------------------+
|
0 |
+----------------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

To perform a case-insensitive comparison, you can produce a result string in a nonbinary
character set by adding a USING clause or converting the result:
mysql> SELECT CHAR(ORD('A') USING latin1) = 'a';
+-----------------------------------+
| CHAR(ORD('A') USING latin1) = 'a' |
+-----------------------------------+
|
1 |
+-----------------------------------+
mysql> SELECT CONVERT(CHAR(ORD('A')) USING latin1) = 'a';
+--------------------------------------------+
| CONVERT(CHAR(ORD('A')) USING latin1) = 'a' |
+--------------------------------------------+
|
1 |
+--------------------------------------------+

• Incompatible change: Beginning with MySQL 5.0.12, natural joins and joins with USING,
including outer join variants, are processed according to the SQL:2003 standard. The changes
include elimination of redundant output columns for NATURAL joins and joins specified with a
USING clause and proper ordering of output columns. The precedence of the comma operator also
now is lower compared to JOIN, LEFT JOIN, and so forth.
These changes make MySQL more compliant with standard SQL. However, they can result in
different output columns for some joins. Also, some queries that appeared to work correctly prior to
5.0.12 must be rewritten to comply with the standard. For details about the scope of the changes
and examples that show what query rewrites are necessary, see Section 13.2.8.2, “JOIN Syntax”.
• CREATE TABLE ... SELECT CHAR(...) produces a VARBINARY column, not a VARCHAR
column. To produce a VARCHAR column, use USING or CONVERT() as just described to convert
the CHAR() result into a nonbinary character set.
• Previously, the following statements inserted the value 0x00410041 ('AA' as a ucs2 string) into
the table:
CREATE TABLE t (ucs2_column CHAR(2) CHARACTER SET ucs2);
INSERT INTO t VALUES (CHAR(0x41,0x41));

As of MySQL 5.0.15, the statements insert a single ucs2 character with value 0x4141.
• Incompatible change: By default, integer subtraction involving an unsigned value should produce
an unsigned result. Tracking of the “unsignedness” of an expression was improved in MySQL 5.0.13.
This means that, in some cases where an unsigned subtraction would have resulted in a signed
integer, it now results in an unsigned integer. One context in which this difference manifests itself is
when a subtraction involving an unsigned operand would be negative.
Suppose that i is a TINYINT UNSIGNED column and has a value of 0. The server evaluates the
following expression using 64-bit unsigned integer arithmetic with the following result:
mysql> SELECT i - 1 FROM t;
+----------------------+
| i - 1
|
+----------------------+
| 18446744073709551615 |
+----------------------+

If the expression is used in an UPDATE t SET i = i - 1 statement, the expression is evaluated
and the result assigned to i according to the usual rules for handling values outside the column
range or 0 to 255. That is, the value is clipped to the nearest endpoint of the range. However, the
result is version-specific:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Upgrading MySQL

• Before MySQL 5.0.13, the expression is evaluated but is treated as the equivalent 64-bit signed
value (−1) for the assignment. The value of −1 is clipped to the nearest endpoint of the column
range, resulting in a value of 0:
mysql> UPDATE t SET i = i - 1; SELECT i FROM t;
+------+
| i
|
+------+
|
0 |
+------+

• As of MySQL 5.0.13, the expression is evaluated and retains its unsigned attribute for the
assignment. The value of 18446744073709551615 is clipped to the nearest endpoint of the
column range, resulting in a value of 255:
mysql> UPDATE t SET i = i - 1; SELECT i FROM t;
+------+
| i
|
+------+
| 255 |
+------+

To get the older behavior, use CAST() to convert the expression result to a signed value:
UPDATE t SET i = CAST(i - 1 AS SIGNED);

Alternatively, set the NO_UNSIGNED_SUBTRACTION SQL mode. However, this will affect all integer
subtractions involving unsigned values.
• Incompatible change: Before MySQL 5.0.12, NOW() and SYSDATE() return the same value (the
time at which the statement in which the function occurs begins executing). As of MySQL 5.0.12,
SYSDATE() returns the time at which it executes, which can differ from the value returned by NOW().
For information about the implications for binary logging, replication, and use of indexes, see the
description for SYSDATE() in Section 12.7, “Date and Time Functions” and for SET TIMESTAMP
in Section 13.7.4, “SET Syntax”. To restore the former behavior for SYSDATE() and cause it to be
an alias for NOW(), start the server with the --sysdate-is-now option (available as of MySQL
5.0.20).
• Incompatible change: Before MySQL 5.0.13, GREATEST(x,NULL) and LEAST(x,NULL) return x
when x is a non-NULL value. As of 5.0.13, both functions return NULL if any argument is NULL, the
same as Oracle. This change can cause problems for applications that rely on the old behavior.
• Incompatible change: Before MySQL 5.0.8, conversion of DATETIME values to numeric form by
adding zero produced a result in YYYYMMDDHHMMSS format. The result of DATETIME+0 is now in
YYYYMMDDHHMMSS.000000 format.
• Incompatible change: In MySQL 5.0.6, the behavior of LOAD DATA INFILE and SELECT ...
INTO OUTFILE has changed when the FIELDS TERMINATED BY and FIELDS ENCLOSED BY
values both are empty. Formerly, a column was read or written using the display width of the column.
For example, INT(4) was read or written using a field with a width of 4. Now columns are read
and written using a field width wide enough to hold all values in the field. However, data files written
before this change was made might not be reloaded correctly with LOAD DATA INFILE for MySQL
5.0.6 and up. This change also affects data files read by mysqlimport and written by mysqldump
--tab, which use LOAD DATA INFILE and SELECT ... INTO OUTFILE. For more information,
see Section 13.2.6, “LOAD DATA INFILE Syntax”.
• Incompatible change: Before MySQL 5.0.2, SHOW STATUS returned global status values. The
default as of 5.0.2 is to return session values, which is incompatible with previous versions. To issue
a SHOW STATUS statement that will retrieve global status values for all versions of MySQL, write it
like this:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Downgrading MySQL

SHOW /*!50002 GLOBAL */ STATUS;

• Incompatible change: User variables are not case sensitive in MySQL 5.0. In MySQL 4.1, SET @x
= 0; SET @X = 1; SELECT @x; created two variables and returned 0. In MySQL 5.0, it creates
one variable and returns 1. Replication setups that rely on the old behavior may be affected by this
change.
• Some keywords may be reserved in MySQL 5.0 that were not reserved in MySQL 4.1. See
Section 9.3, “Keywords and Reserved Words”.
• The LOAD DATA FROM MASTER and LOAD TABLE FROM MASTER statements are deprecated. See
Section 13.4.2.2, “LOAD DATA FROM MASTER Syntax”, for recommended alternatives.
• As of MySQL 5.0.25, TIMESTAMP columns that are NOT NULL now are reported that way by SHOW
COLUMNS and INFORMATION_SCHEMA, rather than as NULL.
• Comparisons made between FLOAT or DOUBLE values that happened to work in MySQL 4.1 may
not do so in 5.0. Values of these types are imprecise in all MySQL versions, and you are strongly
advised to avoid such comparisons as WHERE col_name=some_double, regardless of the MySQL
version you are using. See Section B.5.4.8, “Problems with Floating-Point Values”.
• As of MySQL 5.0.3, BIT is a separate data type, not a synonym for TINYINT(1). See
Section 11.1.1, “Numeric Type Overview”.
• MySQL 5.0.2 adds several SQL modes that enable stricter control over rejecting records that
have invalid or missing values. See Section 5.1.7, “Server SQL Modes”, and Section 1.8.3.3,
“Constraints on Invalid Data”. If you want to enable this control but continue to use MySQL's
capability for storing incorrect dates such as '2004-02-31', you should start the server with -sql_mode="TRADITIONAL,ALLOW_INVALID_DATES".
• As of MySQL 5.0.2, the SCHEMA and SCHEMAS keywords are accepted as synonyms for DATABASE
and DATABASES, respectively. (While “schemata” is grammatically correct and even appears in some
MySQL 5.0 system database and table names, it cannot be used as a keyword.)

C API Changes
• Incompatible change: Because the MySQL 5.0 server has a new implementation of the DECIMAL
data type, a problem may occur if the server is used by older clients that still are linked against
MySQL 4.1 client libraries. If a client uses the binary client/server protocol to execute prepared
statements that generate result sets containing numeric values, an error will be raised: 'Using
unsupported buffer type: 246'
This error occurs because the 4.1 client libraries do not support the new MYSQL_TYPE_NEWDECIMAL
type value added in 5.0. There is no way to disable the new DECIMAL data type on the server side.
You can avoid the problem by relinking the application with the client libraries from MySQL 5.0.
• Incompatible change: The ER_WARN_DATA_TRUNCATED warning symbol was renamed to
WARN_DATA_TRUNCATED in MySQL 5.0.3.
• The reconnect flag in the MYSQL structure is set to 0 by mysql_real_connect(). Only those
client programs which did not explicitly set this flag to 0 or 1 after mysql_real_connect()
experience a change. Having automatic reconnection enabled by default was considered too
dangerous (due to the fact that table locks, temporary tables, user variables, and session variables
are lost after reconnection).

2.19.2 Downgrading MySQL
This section describes how to downgrade to an older MySQL version.
• Supported Downgrade Methods
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Downgrading MySQL

• Supported Downgrade Paths
• Before You Begin
• Performing an In-place Downgrade
• Performing a Logical Downgrade
• Downgrade Troubleshooting

Supported Downgrade Methods
Supported downgrade methods include:
• In-place Downgrade: Involves shutting down the new MySQL version, replacing the new MySQL
binaries or packages with the old ones, and restarting the old MySQL version on the new data files.
In-place downgrades are supported for downgrades between GA versions within the same release
series. For example, in-place downgrades are supported for downgrades from 5.0.96 to 5.0.95.
• Logical Downgrade: Involves using mysqldump to dump all tables from the new MySQL version,
and then loading the dump file into the old MySQL version. Logical downgrades are supported for
downgrades between versions within the same release series and for downgrades between release
levels. For example, logical downgrades are supported for downgrades from 5.0.95 to 5.0.95 and for
downgrades from 5.0 to 4.1.

Supported Downgrade Paths
Unless otherwise documented, the following downgrade paths are supported:
• Downgrading from a release series version to an older release series version is supported using all
downgrade methods. For example, downgrading from 5.0.96 to 5.0.95 is supported. Skipping release
series versions is also supported. For example, downgrading from 5.0.96 to 5.0.92 is supported.
• Downgrading one release level is supported using the logical downgrade method. For example,
downgrading from 5.0 to 4.1 is supported.
• Downgrading more than one release level is supported using the logical downgrade method, but only
if you downgrade one release level at a time.
The following conditions apply to all downgrade paths:
• Downgrades between General Availability (GA) status releases are supported.
• Downgrades between milestone releases (or from a GA release to a milestone release) are not
supported.

Before You Begin
Before downgrading, the following steps are recommended:
• Review the Release Notes for the MySQL version you are downgrading from to ensure that there are
no features or fixes that you really need.
• Review Section 2.19.2.1, “Changes Affecting Downgrades from MySQL 5.0”. This section describes
changes that may require action before or after downgrading.
Note
The downgrade procedures described in the following sections assume
you are downgrading with data files created or modified by the newer
MySQL version. However, if you did not modify your data after upgrading,
downgrading using backups taken before upgrading to the new MySQL
version is recommended. Many of the changes described in Section 2.19.2.1,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Downgrading MySQL

“Changes Affecting Downgrades from MySQL 5.0” that require action before
or after downgrading are not applicable when downgrading using backups
taken before upgrading to the new MySQL version.
• Always back up your current databases and log files before downgrading. The backup should include
the mysql database, which contains the MySQL system tables. See Section 7.2, “Database Backup
Methods”.
• Use of new features, new configuration options, or new configuration option values that are not
supported by a previous release may cause downgrade errors or failures. Before downgrading,
it is recommended that you reverse changes resulting from the use of new features and remove
configuration settings that are not supported by the release you are downgrading to.
• Check Section 2.19.3, “Checking Whether Tables or Indexes Must Be Rebuilt”, to see whether
changes to table formats or to character sets or collations were made between your current version
of MySQL and the version to which you are downgrading. If such changes have resulted in an
incompatibility between MySQL versions, downgrade the affected tables using the instructions in
Section 2.19.4, “Rebuilding or Repairing Tables or Indexes”.
• If you use XA transactions with InnoDB, run XA RECOVER before downgrading to check for
uncommitted XA transactions. If results are returned, either commit or rollback the XA transactions
by issuing an XA COMMIT or XA ROLLBACK statement.

Performing an In-place Downgrade
In-place downgrades are supported for downgrades between GA status releases within the same
release series. Review Before you Begin before proceeding.
To perform an in-place downgrade:
1. Review the changes described in Section 2.19.2.1, “Changes Affecting Downgrades from MySQL
5.0” for steps to be performed before downgrading.
2. If you use InnoDB, configure MySQL to perform a slow shutdown. For example:
shell> bin/mysql -u root -ppassword --execute="set global innodb_fast_shutdown=0"

With a slow shutdown, InnoDB performs a full purge and change buffer merge before shutting
down, which ensures that data files are fully prepared in case of file format differences between
releases.
3. Stop the newer MySQL server.
4. Downgrade the MySQL binaries or packages in-place by replacing the newer binaries or packages
with the older ones.
5. Start the older (downgraded) MySQL server.
6. Run mysql_upgrade. For example:
shell> bin/mysql_upgrade -u root -ppassword

Performing a Logical Downgrade
Logical downgrades are supported for downgrades between releases within the same release series
and for downgrades to the previous release level. Only downgrades between General Availability (GA)
status releases are supported. Review Before you Begin before proceeding.
To perform a logical downgrade:
1. Review the changes described in Section 2.19.2.1, “Changes Affecting Downgrades from MySQL
5.0” for steps to be performed before downgrading.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Downgrading MySQL

2. Dump all databases. For example:
shell> bin/mysqldump --add-drop-table --skip-routines --skip-triggers -u root -ppassword
-> --all-databases --force > all_5_0_databases_dump.sql

3. Stop the newer MySQL server.
4. Initialize the older MySQL instance using an empty data directory. For example:
shell> scripts/mysql_install_db --user=mysql

5. Start the older MySQL server.
6. Load the dump file into the older MySQL server. For example:
shell> bin/mysql -u root -ppassword --execute="source all_5_0_databases_dump.sql" --force

7. Run mysql_upgrade. For example:
shell> bin/mysql_upgrade -u root -ppassword

8. If you use InnoDB, configure MySQL to perform a slow shutdown. For example:
shell> bin/mysql -u root -ppassword --execute="set global innodb_fast_shutdown=0"

9. Shut down and restart the MySQL server to ensure a clean shutdown and startup.

Downgrade Troubleshooting
If you downgrade from one release series to another, there may be incompatibilities in table storage
formats. In this case, use mysqldump to dump your tables before downgrading. After downgrading,
reload the dump file using mysql or mysqlimport to re-create your tables. For examples, see
Section 2.19.5, “Copying MySQL Databases to Another Machine”.
A typical symptom of a downward-incompatible table format change when you downgrade is that you
cannot open tables. In that case, use the following procedure:
1. Stop the older MySQL server that you are downgrading to.
2. Restart the newer MySQL server you are downgrading from.
3. Dump any tables that were inaccessible to the older server by using mysqldump to create a dump
file.
4. Stop the newer MySQL server and restart the older one.
5. Reload the dump file into the older server. Your tables should be accessible.

2.19.2.1 Changes Affecting Downgrades from MySQL 5.0
Before downgrading from MySQL 5.0, review the changes described in this section. Some changes
may require action before or after downgrading.
MySQL 4.1 does not support stored routines or triggers. If your databases contain stored routines or
triggers, prevent them from being dumped when you use mysqldump by using the --skip-routines
and --skip-triggers options. (See Section 4.5.4, “mysqldump — A Database Backup Program”.)
MySQL 4.1 does not support views. If your databases contain views, remove them with DROP VIEW
before using mysqldump. (See Section 13.1.19, “DROP VIEW Syntax”.)
After downgrading from MySQL 5.0, you may see the following information in the mysql.err file:
Incorrect information in file: './mysql/user.frm'

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Checking Whether Tables or Indexes Must Be Rebuilt

In this case, you can do the following:
1. Start MySQL 5.0.4 (or newer).
2. Run mysql_fix_privilege_tables, which will change the mysql.user table to a format that
both MySQL 4.1 and 5.0 can use.
3. Stop the MySQL server.
4. Start MySQL 4.1.
If the preceding procedure fails, you should be able to do the following instead:
1. Start MySQL 5.0.4 (or newer).
2. Run mysqldump --opt --add-drop-table mysql > /tmp/mysql.dump.
3. Stop the MySQL server.
4. Start MySQL 4.1 with the --skip-grant-tables option.
5. Run mysql mysql < /tmp/mysql.dump.
6. Run mysqladmin flush-privileges.

2.19.3 Checking Whether Tables or Indexes Must Be Rebuilt
A binary upgrade or downgrade is one that installs one version of MySQL “in place” over an existing
version, without dumping and reloading tables:
1. Stop the server for the existing version if it is running.
2. Install a different version of MySQL. This is an upgrade if the new version is higher than the original
version, a downgrade if the version is lower.
3. Start the server for the new version.
In many cases, the tables from the previous version of MySQL can be used without problem by the
new version. However, sometimes changes occur that require tables or table indexes to be rebuilt,
as described in this section. If you have tables that are affected by any of the issues described here,
rebuild the tables or indexes as necessary using the instructions given in Section 2.19.4, “Rebuilding or
Repairing Tables or Indexes”.

Table Incompatibilities
After a binary upgrade to MySQL 5.1 from a MySQL 5.0 installation that contains ARCHIVE tables,
accessing those tables causes the server to crash, even if you have run mysql_upgrade or CHECK
TABLE ... FOR UPGRADE. To work around this problem, use mysqldump to dump all ARCHIVE
tables before upgrading, and reload them into MySQL 5.1 after upgrading. The same problem occurs
for binary downgrades from MySQL 5.1 to 5.0.

Index Incompatibilities
If you perform a binary upgrade without dumping and reloading tables, you cannot upgrade directly
from MySQL 4.1 to 5.1 or higher. This occurs due to an incompatible change in the MyISAM table index
format in MySQL 5.0. Upgrade from MySQL 4.1 to 5.0 and repair all MyISAM tables. Then upgrade
from MySQL 5.0 to 5.1 and check and repair your tables.
Modifications to the handling of character sets or collations might change the character sort order,
which causes the ordering of entries in any index that uses an affected character set or collation to be
incorrect. Such changes result in several possible problems:
• Comparison results that differ from previous results
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Checking Whether Tables or Indexes Must Be Rebuilt

• Inability to find some index values due to misordered index entries
• Misordered ORDER BY results
• Tables that CHECK TABLE reports as being in need of repair
The solution to these problems is to rebuild any indexes that use an affected character set or collation,
either by dropping and re-creating the indexes, or by dumping and reloading the entire table. In
some cases, it is possible to alter affected columns to use a different collation. For information about
rebuilding indexes, see Section 2.19.4, “Rebuilding or Repairing Tables or Indexes”.
To check whether a table has indexes that must be rebuilt, consult the following list. It indicates which
versions of MySQL introduced character set or collation changes that require indexes to be rebuilt.
Each entry indicates the version in which the change occurred and the character sets or collations that
the change affects. If the change is associated with a particular bug report, the bug number is given.
The list applies both for binary upgrades and downgrades. For example, Bug #27877 was fixed in
MySQL 5.1.24, so it applies to upgrades from versions older than 5.1.24 to 5.1.24 or newer, and to
downgrades from 5.1.24 or newer to versions older than 5.1.24.
In many cases, you can use CHECK TABLE ... FOR UPGRADE to identify tables for which index
rebuilding is required. It will report this message:
Table upgrade required.
Please do "REPAIR TABLE `tbl_name`" to fix it!

In these cases, you can also use mysqlcheck --check-upgrade or mysql_upgrade, which
execute CHECK TABLE. However, the use of CHECK TABLE applies only after upgrades, not
downgrades. Also, CHECK TABLE is not applicable to all storage engines. For details about which
storage engines CHECK TABLE supports, see Section 13.7.2.3, “CHECK TABLE Syntax”.
These changes cause index rebuilding to be necessary:
• MySQL 5.1.24 (Bug #27877)
Affects indexes that use the utf8_general_ci or ucs2_general_ci collation for columns that
contain 'ß' LATIN SMALL LETTER SHARP S (German). The bug fix corrected an error in the
original collations but introduced an incompatibility such that 'ß' compares equal to characters with
which it previously compared different.
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE as of MySQL 5.1.30 (see
Bug #40053).
A workaround for this issue is implemented as of MySQL 5.1.62, 5.5.21, and 5.6.5. The
workaround involves altering affected columns to use the utf8_general_mysql500_ci and
ucs2_general_mysql500_ci collations, which preserve the original pre-5.1.24 ordering of
utf8_general_ci and ucs2_general_ci.
• MySQL 5.0.48, 5.1.23 (Bug #27562)
Affects indexes that use the ascii_general_ci collation for columns that contain any of these
characters: '`' GRAVE ACCENT, '[' LEFT SQUARE BRACKET, '\' REVERSE SOLIDUS, ']'
RIGHT SQUARE BRACKET, '~' TILDE
Affected tables can be detected by CHECK TABLE ... FOR UPGRADE as of MySQL 5.1.29 (see
Bug #39585).
• MySQL 5.0.48, 5.1.21 (Bug #29461)
Affects indexes for columns that use any of these character sets: eucjpms, euc_kr, gb2312,
latin7, macce, ujis
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Rebuilding or Repairing Tables or Indexes

Affected tables can be detected by CHECK TABLE ... FOR UPGRADE as of MySQL 5.1.29 (see
Bug #39585).

2.19.4 Rebuilding or Repairing Tables or Indexes
This section describes how to rebuild a table. This can be necessitated by changes to MySQL such as
how data types are handled or changes to character set handling. For example, an error in a collation
might have been corrected, necessitating a table rebuild to update the indexes for character columns
that use the collation. (For examples, see Section 2.19.3, “Checking Whether Tables or Indexes Must
Be Rebuilt”.) It might also be that a table repair or upgrade should be done as indicated by a table
check operation such as that performed by CHECK TABLE, mysqlcheck, or mysql_upgrade.
Methods for rebuilding a table include dumping and reloading it, or using ALTER TABLE or REPAIR
TABLE.
Note
If you are rebuilding tables because a different version of MySQL will not handle
them after a binary (in-place) upgrade or downgrade, you must use the dumpand-reload method. Dump the tables before upgrading or downgrading using
your original version of MySQL. Then reload the tables after upgrading or
downgrading.
If you use the dump-and-reload method of rebuilding tables only for the purpose
of rebuilding indexes, you can perform the dump either before or after upgrading
or downgrading. Reloading still must be done afterward.
To rebuild a table by dumping and reloading it, use mysqldump to create a dump file and mysql to
reload the file:
shell> mysqldump db_name t1 > dump.sql
shell> mysql db_name < dump.sql

To rebuild all the tables in a single database, specify the database name without any following table
name:
shell> mysqldump db_name > dump.sql
shell> mysql db_name < dump.sql

To rebuild all tables in all databases, use the --all-databases option:
shell> mysqldump --all-databases > dump.sql
shell> mysql < dump.sql

To rebuild a table with ALTER TABLE, use a “null” alteration; that is, an ALTER TABLE statement that
“changes” the table to use the storage engine that it already has. For example, if t1 is a MyISAM table,
use this statement:
mysql> ALTER TABLE t1 ENGINE = MyISAM;

If you are not sure which storage engine to specify in the ALTER TABLE statement, use SHOW CREATE
TABLE to display the table definition.
If you must rebuild a table because a table checking operation indicates that the table is corrupt or
needs an upgrade, you can use REPAIR TABLE if that statement supports the table's storage engine.
For example, to repair a MyISAM table, use this statement:
mysql> REPAIR TABLE t1;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Copying MySQL Databases to Another Machine

For storage engines such as InnoDB that REPAIR TABLE does not support, use mysqldump to create
a dump file and mysql to reload the file, as described earlier.
For specifics about which storage engines REPAIR TABLE supports, see Section 13.7.2.6, “REPAIR
TABLE Syntax”.
mysqlcheck --repair provides command-line access to the REPAIR TABLE statement. This can
be a more convenient means of repairing tables because you can use the --databases or --alldatabases option to repair all tables in specific databases or all databases, respectively:
shell> mysqlcheck --repair --databases db_name ...
shell> mysqlcheck --repair --all-databases

For incompatibilities introduced in MySQL 5.1.24 by the fix for Bug #27877 that corrected the
utf8_general_ci and ucs2_general_ci collations, a workaround is implemented as of MySQL
5.1.62, 5.5.21, and 5.6.5. Upgrade to one of those versions, then convert each affected table using
one of the following methods. In each case, the workaround altering affected columns to use the
utf8_general_mysql500_ci and ucs2_general_mysql500_ci collations, which preserve the
original pre-5.1.24 ordering of utf8_general_ci and ucs2_general_ci.
• To convert an affected table after a binary upgrade that leaves the table files in place, alter the table
to use the new collation. Suppose that the table t1 contains one or more problematic utf8 columns.
To convert the table at the table level, use a statement like this:
ALTER TABLE t1
CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_mysql500_ci;

To apply the change on a column-specific basis, use a statement like this (be sure to repeat the
column definition as originally specified except for the COLLATE clause):
ALTER TABLE t1
MODIFY c1 CHAR(N) CHARACTER SET utf8 COLLATE utf8_general_mysql500_ci;

• To upgrade the table using a dump and reload procedure, dump the table using mysqldump, modify
the CREATE TABLE statement in the dump file to use the new collation, and reload the table.
After making the appropriate changes, CHECK TABLE should report no error.

2.19.5 Copying MySQL Databases to Another Machine
You can copy the .frm, .MYI, and .MYD files for MyISAM tables between different architectures
that support the same floating-point format. (MySQL takes care of any byte-swapping issues.) See
Section 14.1, “The MyISAM Storage Engine”.
In cases where you need to transfer databases between different architectures, you can use
mysqldump to create a file containing SQL statements. You can then transfer the file to the other
machine and feed it as input to the mysql client.
Use mysqldump --help to see what options are available.
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 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 these
commands:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Operating System-Specific Notes

shell> mysqladmin create db_name
shell> mysqldump -h 'other_hostname' --compress db_name | mysql db_name

You can also store the dump in a file, transfer the file to the target machine, and then load the file
into the database there. For example, you can dump a database to a compressed file on the source
machine like this:
shell> mysqldump --quick db_name | gzip > db_name.gz

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.gz | mysql db_name

You can also use mysqldump and mysqlimport to transfer the database. For large tables, this is
much faster than simply using mysqldump. In the following commands, DUMPDIR represents the full
path name of the directory you use to store the output from mysqldump.
First, create the directory for the output files and dump the database:
shell> mkdir DUMPDIR
shell> mysqldump --tab=DUMPDIR db_name

Then transfer the files in the DUMPDIR directory to some corresponding directory on the target machine
and load the files into MySQL there:
shell> mysqladmin create db_name
shell> cat DUMPDIR/*.sql | mysql db_name
shell> mysqlimport db_name DUMPDIR/*.txt

# create database
# create tables in database
# load data into tables

Do not forget to copy the mysql database because that is where the grant tables are stored. You
might have to run commands as the MySQL root user on the new machine until you have the mysql
database in place.
After you import the mysql database on the new machine, execute mysqladmin flushprivileges so that the server reloads the grant table information.

2.20 Operating System-Specific Notes
2.20.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 postinstallation issues. The remaining subsections discuss problems that
occur with Linux on specific platforms.
Note that most of these problems occur on older versions of Linux. If you are running a recent version,
you may see none of them.

2.20.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
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Linux Notes

you are using this kernel, you should upgrade to 2.2.19 (or newer) or to a 2.4
kernel. If you have a multiple-CPU box, you should seriously consider using 2.4
because it gives you a significant speed boost. Your system should be more
stable.
When using LinuxThreads, you should see a minimum of three mysqld processes running. These are
in fact threads. There is one thread for the LinuxThreads manager, one thread to handle connections,
and one thread to handle alarms and signals.

2.20.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% to
5%). However, one problem with a statically linked program is that you can't use user-defined functions
(UDFs). If you are going to write or use UDFs (this is something for C or C++ programmers only), you
must compile MySQL yourself using dynamic linking.
A known issue with binary distributions is that on older Linux systems that use libc (such as Red
Hat 4.x or Slackware), you get some (nonfatal) issues with host name resolution. If your system uses
libc rather than glibc2, you probably will encounter some difficulties with host name resolution
and getpwnam(). This happens because glibc (unfortunately) depends on some external libraries
to implement host name resolution and getpwent(), even when compiled with -static. These
problems manifest themselves in two ways:
• You may see the following error message when you run mysql_install_db:
Sorry, the host 'xxxx' could not be looked up

You can deal with this by executing mysql_install_db --force, which does not execute the
resolveip test in mysql_install_db. The downside is that you cannot use host names in the
grant tables: except for localhost, you must use IP addresses instead. If you are using an old
version of MySQL that does not support --force, you must manually remove the resolveip test
in mysql_install_db using a text editor.
• You also may see the following error when you try to run mysqld with the --user option:
getpwnam: No such file or directory

To work around this problem, start mysqld by using the su command rather than by specifying the
--user option. This causes the system itself to change the user ID of the mysqld process so that
mysqld need not do so.
Another solution, which solves both problems, is not to use a binary distribution. Obtain a MySQL
source distribution (in RPM or .tar.gz format) and install that instead.
On some Linux 2.2 versions, you may get the error Resource temporarily unavailable when
clients make a great many new connections to a mysqld server over TCP/IP. The problem is that
Linux has a delay between the time that you close a TCP/IP socket and the time that the system
actually frees it. There is room for only a finite number of TCP/IP slots, so you encounter the resourceunavailable error if clients attempt too many new TCP/IP connections over a short period of time. For
example, you may see the error when you run the MySQL test-connect benchmark over TCP/IP.
We have inquired about this problem a few times on different Linux mailing lists but have never been
able to find a suitable resolution. The only known “fix” is for clients to use persistent connections,
or, if you are running the database server and clients on the same machine, to use Unix socket file
connections rather than TCP/IP connections.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Linux Notes

2.20.1.3 Linux Source Distribution Notes
The following notes regarding glibc apply only to the situation when you build MySQL yourself. If you
are running Linux on an x86 machine, in most cases it is much better for you to use our binary. We link
our binaries against the best patched version of glibc we can find and with the best compiler options,
in an attempt to make it suitable for a high-load server. For a typical user, even for setups with a lot of
concurrent connections or tables exceeding the 2GB limit, our binary is the best choice in most cases.
After reading the following text, if you are in doubt about what to do, try our binary first to determine
whether it meets your needs. If you discover that it is not good enough, you may want to try your own
build. In that case, we would appreciate a note about it so that we can build a better binary next time.
MySQL uses LinuxThreads on Linux. If you are using an old Linux version that doesn't have glibc2,
you must install LinuxThreads before trying to compile MySQL. You can obtain LinuxThreads from
http://dev.mysql.com/downloads/os-linux.html.
Note that glibc versions before and including version 2.1.1 have a fatal bug in
pthread_mutex_timedwait() handling, which is used when INSERT DELAYED statements are
issued. Do not use INSERT DELAYED before upgrading glibc.
Note that Linux kernel and the LinuxThread library can by default handle a maximum of 1,024 threads.
If you plan to have more than 1,000 concurrent connections, you need to make some changes to
LinuxThreads, as follows:
• Increase PTHREAD_THREADS_MAX in sysdeps/unix/sysv/linux/bits/local_lim.h to 4096
and decrease STACK_SIZE in linuxthreads/internals.h to 256KB. The paths are relative to
the root of glibc. (Note that MySQL is not stable with 600 to 1000 connections if STACK_SIZE is
the default of 2MB.)
• Recompile LinuxThreads to produce a new libpthread.a library, and relink MySQL against it.
There is another issue that greatly hurts MySQL performance, especially on SMP systems. The mutex
implementation in LinuxThreads in glibc 2.1 is very poor for programs with many threads that hold
the mutex only for a short time. This produces a paradoxical result: If you link MySQL against an
unmodified LinuxThreads, removing processors from an SMP actually improves MySQL performance
in many cases. We have made a patch available for glibc 2.1.3 to correct this behavior (http://
dev.mysql.com/Downloads/Linux/linuxthreads-2.1-patch).
With glibc 2.2.2, MySQL uses the adaptive mutex, which is much better than even the patched
one in glibc 2.1.3. Be warned, however, that under some conditions, the current mutex code in
glibc 2.2.2 overspins, which hurts MySQL performance. The likelihood that this condition occurs
can be reduced by re-nicing the mysqld process to the highest priority. We have also been able
to correct the overspin behavior with a patch, available at http://dev.mysql.com/Downloads/Linux/
linuxthreads-2.2.2.patch. It combines the correction of overspin, maximum number of threads, and
stack spacing all in one. You need to apply it in the linuxthreads directory with patch -p0  cat /proc/sys/fs/file-max
shell> cat /proc/sys/fs/dquot-max
shell> cat /proc/sys/fs/super-max

If you have more than 16MB of memory, you should add something like the following to your init scripts
(for example, /etc/init.d/boot.local on SuSE Linux):
echo 65536 > /proc/sys/fs/file-max
echo 8192 > /proc/sys/fs/dquot-max
echo 1024 > /proc/sys/fs/super-max

You can also run the echo commands from the command line as root, but these settings are lost the
next time your computer restarts.
Alternatively, you can set these parameters on startup by using the sysctl tool, which is used by
many Linux distributions (including SuSE Linux 8.0 and later). Put the following values into a file named
/etc/sysctl.conf:
# Increase some values for MySQL
fs.file-max = 65536
fs.dquot-max = 8192
fs.super-max = 1024

You should also add the following to /etc/my.cnf:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Linux Notes

[mysqld_safe]
open-files-limit=8192

This should enable a server limit of 8,192 for the combined number of connections and open files.
The STACK_SIZE constant in LinuxThreads controls the spacing of thread stacks in the address
space. It needs to be large enough so that there is plenty of room for each individual thread
stack, but small enough to keep the stack of some threads from running into the global mysqld
data. Unfortunately, as we have experimentally discovered, the Linux implementation of mmap()
successfully unmaps a mapped region if you ask it to map out an address currently in use, zeroing
out the data on the entire page instead of returning an error. So, the safety of mysqld or any other
threaded application depends on the “gentlemanly” behavior of the code that creates threads. The
user must take measures to make sure that the number of running threads at any given time is
sufficiently low for thread stacks to stay away from the global heap. With mysqld, you should enforce
this behavior by setting a reasonable value for the max_connections variable.
If you build MySQL yourself, you can patch LinuxThreads for better stack use. See Section 2.20.1.3,
“Linux Source Distribution Notes”. If you do not want to patch LinuxThreads, you should set
max_connections to a value no higher than 500. It should be even less if you have a large key
buffer, large heap tables, or some other things that make mysqld allocate a lot of memory, or if you
are running a 2.2 kernel with a 2GB patch. If you are using our binary or RPM version, you can safely
set max_connections at 1500, assuming no large key buffer or heap tables with lots of data. The
more you reduce STACK_SIZE in LinuxThreads the more threads you can safely create. Values
between 128KB and 256KB are recommended.
If you use a lot of concurrent connections, you may suffer from a “feature” in the 2.2 kernel that
attempts to prevent fork bomb attacks by penalizing a process for forking or cloning a child. This
causes MySQL not to scale well as you increase the number of concurrent clients. On single-CPU
systems, we have seen this manifest as very slow thread creation; it may take a long time to connect
to MySQL (as long as one minute), and it may take just as long to shut it down. On multiple-CPU
systems, we have observed a gradual drop in query speed as the number of clients increases. In
the process of trying to find a solution, we have received a kernel patch from one of our users who
claimed it helped for his site. This patch is available at http://dev.mysql.com/Downloads/Patches/linuxfork.patch. We have done rather extensive testing of this patch on both development and production
systems. It has significantly improved MySQL performance without causing any problems and is
recommended for users who still run high-load servers on 2.2 kernels.
This issue has been fixed in the 2.4 kernel, so if you are not satisfied with the current performance
of your system, rather than patching your 2.2 kernel, it might be easier to upgrade to 2.4. On SMP
systems, upgrading also gives you a nice SMP boost in addition to fixing the fairness bug.
We have tested MySQL on the 2.4 kernel on a two-CPU machine and found MySQL scales much
better. There was virtually no slowdown on query throughput all the way up to 1,000 clients, and the
MySQL scaling factor (computed as the ratio of maximum throughput to the throughput for one client)
was 180%. We have observed similar results on a four-CPU system: Virtually no slowdown as the
number of clients was increased up to 1,000, and a 300% scaling factor. Based on these results, for a
high-load SMP server using a 2.2 kernel, it is definitely recommended to upgrade to the 2.4 kernel at
this point.
We have discovered that it is essential to run the mysqld process with the highest possible priority
on the 2.4 kernel to achieve maximum performance. This can be done by adding a renice -20 $$
command to mysqld_safe. In our testing on a four-CPU machine, increasing the priority resulted in a
60% throughput increase with 400 clients.
If you see a dead mysqld server process with ps, this usually means that you have found a bug in
MySQL or you have a corrupted table. See Section B.5.3.3, “What to Do If MySQL Keeps Crashing”.
To get a core dump on Linux if mysqld dies with a SIGSEGV signal, you can start mysqld with the -core-file option. Note that you also probably need to raise the core file size by adding ulimit This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Linux Notes

c 1000000 to mysqld_safe or starting mysqld_safe with --core-file-size=1000000. See
Section 4.3.2, “mysqld_safe — MySQL Server Startup Script”.

2.20.1.5 Linux x86 Notes
MySQL requires libc 5.4.12 or newer. It is known to work with libc 5.4.46. glibc 2.0.6 and later
should also work. There have been some problems with the glibc RPMs from Red Hat, so if you have
problems, check whether there are any updates. The glibc 2.0.7-19 and 2.0.7-29 RPMs are known to
work.
If you are using Red Hat 8.0 or a new glibc 2.2.x library, you may see mysqld die in
gethostbyaddr(). This happens because the new glibc library requires a stack size greater than
128KB for this call. To fix the problem, start mysqld with the --thread-stack=192K option. This
stack size is the default on MySQL 4.0.10 and above, so you should not see the problem.
If you are using gcc 3.0 and above to compile MySQL, you must install the libstdc+
+v3 library before compiling MySQL; if you do not do this, you get an error about a missing
__cxa_pure_virtual symbol during linking.
On some older Linux distributions, configure may produce an error like this:
Syntax error in sched.h. Change _P to __P in the
/usr/include/sched.h file.
See the Installation chapter in the Reference Manual.

Just do what the error message says. Add an extra underscore to the _P macro name that has only
one underscore, and then try again.
You may get some warnings when compiling. Those shown here can be ignored:
mysqld.cc -o objs-thread/mysqld.o
mysqld.cc: In function `void init_signals()':
mysqld.cc:315: warning: assignment of negative value `-1' to
`long unsigned int'
mysqld.cc: In function `void * signal_hand(void *)':
mysqld.cc:346: warning: assignment of negative value `-1' to
`long unsigned int'

If mysqld always dumps core when it starts, the problem may be that you have an old /lib/libc.a.
Try renaming it, and then remove sql/mysqld and do a new make install and try again. This
problem has been reported on some Slackware installations.
If you get the following error when linking mysqld, it means that your libg++.a is not installed
correctly:
/usr/lib/libc.a(putc.o): In function `_IO_putc':
putc.o(.text+0x0): multiple definition of `_IO_putc'

You can avoid using libg++.a by running configure like this:
shell> CXX=gcc ./configure

2.20.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.20.1.7 Linux Alpha Notes
We have tested MySQL 5.0 on Alpha with our benchmarks and test suite, and it appears to work well.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Linux Notes

We currently build the MySQL binary packages on SuSE Linux 7.0 for AXP, kernel 2.4.4-SMP,
Compaq C compiler (V6.2-505) and Compaq C++ compiler (V6.3-006) on a Compaq DS20 machine
with an Alpha EV6 processor.
You can find the preceding compilers at http://www.support.compaq.com/alpha-tools/. By using these
compilers rather than gcc, we get about 9% to 14% better MySQL performance.
For MySQL on Alpha, we use the -arch generic flag to our compile options, which ensures that
the binary runs on all Alpha processors. We also compile statically to avoid library problems. The
configure command looks like this:
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

Some known problems when running MySQL on Linux-Alpha:
• Debugging threaded applications like MySQL does not work with gdb 4.18. You should use gdb
5.1 instead.
• If you try linking mysqld statically when using gcc, the resulting image dumps core at startup time.
In other words, do not use --with-mysqld-ldflags=-all-static with gcc.

2.20.1.8 Linux PowerPC Notes
MySQL should work on MkLinux with the newest glibc package (tested with glibc 2.0.7).

2.20.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 gcc 2.95.2 or newer).

2.20.1.10 Linux IA-64 Notes
To get MySQL to compile on Linux IA-64, we use the following configure command for building with
gcc 2.96:
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 20.6.4.1, “Building C API Client Programs”.

2.20.1.11 SELinux Notes
RHEL4 comes with SELinux, which supports tighter access control for processes. If SELinux is enabled
(SELINUX in /etc/selinux/config is set to enforcing, SELINUXTYPE is set to either targeted
or strict), you might encounter problems installing Oracle Corporation RPM packages.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

OS X Notes

Red Hat has an update that solves this. It involves an update of the “security policy” specification
to handle the install structure of the RPMs provided by Oracle Corporation. For further information,
see https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=167551 and http://rhn.redhat.com/errata/
RHBA-2006-0049.html.

2.20.2 OS X Notes
On OS X, tar cannot handle long file names. If you need to unpack a .tar.gz distribution, use
gnutar instead.

2.20.2.1 OS X 10.x (Darwin)
MySQL should work without major problems on OS X 10.x (Darwin).
Known issues:
• If you have problems with performance under heavy load, try using the --skip-threadpriority option to mysqld. This runs all threads with the same priority. On OS X, this gives better
performance, at least until Apple fixes its thread scheduler.
• The connection times (wait_timeout, interactive_timeout and net_read_timeout) values
are not honored.
This is probably a signal handling problem in the thread library where the signal doesn't break a
pending read and we hope that a future update to the thread libraries will fix this.
Our binary for OS X is compiled on Darwin 6.3 with the following configure line:
CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc \
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --disable-shared

See Section 2.11, “Installing MySQL on OS X”.

2.20.2.2 OS X Server 1.2 (Rhapsody)
For current versions of 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 OS X.
For older versions (OS X Server 1.2, a.k.a. Rhapsody), you must first install a pthread package before
trying to configure MySQL.
See Section 2.11, “Installing MySQL on OS X”.

2.20.3 Solaris Notes
For information about installing MySQL on Solaris using PKG distributions, see Section 2.13, “Installing
MySQL on Solaris”.
On Solaris, you may run into trouble even before you get the MySQL distribution unpacked, as the
Solaris tar cannot handle long file names. This means that you may see errors when you try to
unpack MySQL.
If this occurs, you must use GNU tar (gtar) to unpack the distribution.
If you get the following error from configure, it means that you have something wrong with your
compiler installation:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Solaris Notes

checking for restartable system calls... configure: error can not
run test programs while cross compiling

In this case, you should upgrade your compiler to a newer version. You may also be able to solve this
problem by inserting the following row into the config.cache file:
ac_cv_sys_restartable_syscalls=${ac_cv_sys_restartable_syscalls='no'}

If you are using Solaris on a SPARC, the recommended compiler is gcc 2.95.2 or 3.2. You can find this
at http://gcc.gnu.org/. Note that gcc 2.8.1 does not work reliably on SPARC.
The recommended configure line when using gcc 2.95.2 is:
CC=gcc CFLAGS="-O3" \
CXX=gcc CXXFLAGS="-O3 -felide-constructors -fno-exceptions -fno-rtti" \
./configure --prefix=/usr/local/mysql --with-low-memory \
--enable-assembler

If you have an UltraSPARC system, you can get 4% better performance by adding -mcpu=v8 -Wa,xarch=v8plusa to the CFLAGS and CXXFLAGS environment variables.
If you have Sun's Forte 5.0 (or newer) compiler, you can run configure like this:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
CXX=CC CXXFLAGS="-noex -mt" \
./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit binary with Sun's Forte compiler, use the following configuration options:
CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit Solaris binary using gcc, add -m64 to CFLAGS and CXXFLAGS and remove -enable-assembler from the configure line.
In the MySQL benchmarks, we obtained a 4% speed increase on UltraSPARC when using Forte 5.0 in
32-bit mode, as compared to using gcc 3.2 with the -mcpu flag.
If you create a 64-bit mysqld binary, it is 4% slower than the 32-bit binary, but can handle more
threads and memory.
When using Solaris 10 for x86_64, you should mount any file systems on which you intend to store
InnoDB files with the forcedirectio option. (By default mounting is done without this option.)
Failing to do so will cause a significant drop in performance when using the InnoDB storage engine on
this platform.
If you get a problem with fdatasync or sched_yield, you can fix this by adding LIBS=-lrt to the
configure line
For compilers older than WorkShop 5.3, you might have to edit the configure script. Change this
line:
#if !defined(__STDC__) || __STDC__ != 1

To this:
#if !defined(__STDC__)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Solaris Notes

If you turn on __STDC__ with the -Xc option, the Sun compiler can't compile with the Solaris
pthread.h header file. This is a Sun bug (broken compiler or broken include file).
If mysqld issues the following error message when you run it, you have tried to compile MySQL with
the Sun compiler without enabling the -mt multi-thread option:
libc internal error: _rmutex_unlock: rmutex not held

Add -mt to CFLAGS and CXXFLAGS and recompile.
If you are using the SFW version of gcc (which comes with Solaris 8), you must add /opt/sfw/lib
to the environment variable LD_LIBRARY_PATH before running configure.
If you are using the gcc available from sunfreeware.com, you may have many problems. To avoid
this, you should recompile gcc and GNU binutils on the machine where you are running them.
If you get the following error when compiling MySQL with gcc, it means that your gcc is not configured
for your version of Solaris:
shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ...
./thr_alarm.c: In function `signal_hand':
./thr_alarm.c:556: too many arguments to function `sigwait'

The proper thing to do in this case is to get the newest version of gcc and compile it with your current
gcc compiler. At least for Solaris 2.5, almost all binary versions of gcc have old, unusable include files
that break all programs that use threads, and possibly other programs as well.
Solaris does not provide static versions of all system libraries (libpthreads and libdl), so you
cannot compile MySQL with --static. If you try to do so, you get one of the following errors:
ld: fatal: library -ldl: not found
undefined reference to `dlopen'
cannot find -lrt

If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory

This problem can be avoided by one of the following methods:
• Link clients with the -Wl,r/full/path/to/libmysqlclient.so flag rather than with -Lpath).
• Copy libmysqclient.so to /usr/lib.
•

Add the path name of the directory where libmysqlclient.so is located to the LD_RUN_PATH
environment variable before running your client.

If you have problems with configure trying to link with -lz when you do not have zlib installed, you
have two options:
• If you want to be able to use the compressed communication protocol, you need to get and install
zlib from ftp.gnu.org.
• Run configure with the --with-named-z-libs=no option when building MySQL.
If you are using gcc and have problems with loading user-defined functions (UDFs) into MySQL, try
adding -lgcc to the link line for the UDF.
If you would like MySQL to start automatically, you can copy support-files/mysql.server to /
etc/init.d and create a symbolic link to it named /etc/rc3.d/S99mysql.server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Solaris Notes

If too many processes try to connect very rapidly to mysqld, you should see this error in the MySQL
log:
Error in accept: Protocol error

You might try starting the server with the --back_log=50 option as a workaround for this. (Use -O
back_log=50 before MySQL 4.)
To configure the generation of core files on Solaris you should use the coreadm command. Because of
the security implications of generating a core on a setuid() application, by default, Solaris does not
support core files on setuid() programs. However, you can modify this behavior using coreadm. If
you enable setuid() core files for the current user, they will be generated using the mode 600 and
owned by the superuser.

2.20.3.1 Solaris 2.7/2.8 Notes
Normally, you can use a Solaris 2.6 binary on Solaris 2.7 and 2.8. Most of the Solaris 2.6 issues also
apply for Solaris 2.7 and 2.8.
MySQL should be able to detect new versions of Solaris automatically and enable workarounds for the
following problems.
Solaris 2.7 / 2.8 has some bugs in the include files. You may see the following error when you use gcc:
/usr/include/widec.h:42: warning: `getwc' redefined
/usr/include/wchar.h:326: warning: this is the location of the previous
definition

If this occurs, you can fix the problem by copying /usr/include/widec.h to .../lib/gcc-lib/
os/gcc-version/include and changing line 41 from this:
#if

!defined(lint) && !defined(__lint)

To this:
#if

!defined(lint) && !defined(__lint) && !defined(getwc)

Alternatively, you can edit /usr/include/widec.h directly. Either way, after you make the fix, you
should remove config.cache and run configure again.
If you get the following errors when you run make, it is because configure didn't detect the
curses.h file (probably because of the error in /usr/include/widec.h):
In file included from mysql.cc:50:
/usr/include/term.h:1060: syntax error before `,'
/usr/include/term.h:1081: syntax error before `;'

The solution to this problem is to do one of the following:
1. Configure with CFLAGS=-DHAVE_CURSES_H CXXFLAGS=-DHAVE_CURSES_H ./configure.
2. Edit /usr/include/widec.h as indicated in the preceding discussion and re-run configure.
3. Remove the #define HAVE_TERM line from the config.h file and run make again.
If your linker cannot find -lz when linking client programs, the problem is probably that your libz.so
file is installed in /usr/local/lib. You can fix this problem by one of the following methods:
• Add /usr/local/lib to LD_LIBRARY_PATH.
• Add a link to libz.so from /lib.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

BSD Notes

• If you are using Solaris 8, you can install the optional zlib from your Solaris 8 CD distribution.
• Run configure with the --with-named-z-libs=no option when building MySQL.

2.20.3.2 Solaris x86 Notes
On Solaris 8 on x86, mysqld dumps core if you remove the debug symbols using strip.
If you are using gcc on Solaris x86 and you experience problems with core dumps under load, you
should use the following configure command:
CC=gcc CFLAGS="-O3 -fomit-frame-pointer -DHAVE_CURSES_H" \
CXX=gcc \
CXXFLAGS="-O3 -fomit-frame-pointer -felide-constructors \
-fno-exceptions -fno-rtti -DHAVE_CURSES_H" \
./configure --prefix=/usr/local/mysql

This avoids problems with the libstdc++ library and with C++ exceptions.
If this doesn't help, you should compile a debug version and run it with a trace file or under gdb. See
Section 21.3, “Debugging and Porting MySQL”.

2.20.4 BSD Notes
This section provides information about using MySQL on variants of BSD Unix.

2.20.4.1 FreeBSD Notes
FreeBSD 4.x or newer is recommended for running MySQL, because the thread package is much more
integrated. To get a secure and stable system, you should use only FreeBSD kernels that are marked
-RELEASE.
The easiest (and preferred) way to install MySQL is to use the mysql-server and mysql-client
ports available at http://www.freebsd.org/. Using these ports gives you the following benefits:
• A working MySQL with all optimizations enabled that are known to work on your version of FreeBSD.
• Automatic configuration and build.
• Startup scripts installed in /usr/local/etc/rc.d.
• The ability to use pkg_info -L to see which files are installed.
• The ability to use pkg_delete to remove MySQL if you no longer want it on your machine.
It is recommended you use MIT-pthreads on FreeBSD 2.x, and native threads on FreeBSD 3 and up.
It is possible to run with native threads on some late 2.2.x versions, but you may encounter problems
shutting down mysqld.
Unfortunately, certain function calls on FreeBSD are not yet fully thread-safe. Most notably, this
includes the gethostbyname() function, which is used by MySQL to convert host names into IP
addresses. Under certain circumstances, the mysqld process suddenly causes 100% CPU load and
is unresponsive. If you encounter this problem, try to start MySQL using the --skip-name-resolve
option.
Alternatively, you can link MySQL on FreeBSD 4.x against the LinuxThreads library, which avoids a
few of the problems that the native FreeBSD thread implementation has. For a very good comparison
of LinuxThreads versus native threads, see Jeremy Zawodny's article FreeBSD or Linux for your
MySQL Server? at http://jeremy.zawodny.com/blog/archives/000697.html.
Known problem when using LinuxThreads on FreeBSD is:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

BSD Notes

• The connection times (wait_timeout, interactive_timeout and net_read_timeout) values
are not honored. The symptom is that persistent connections can hang for a very long time without
getting closed down and that a 'kill' for a thread will not take affect until the thread does it a new
command
This is probably a signal handling problem in the thread library where the signal doesn't break a
pending read. This is supposed to be fixed in FreeBSD 5.0
The MySQL build process requires GNU make (gmake) to work. If GNU make is not available, you
must install it first before compiling MySQL.
The recommended way to compile and install MySQL on FreeBSD with gcc (2.95.2 and up) is:
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 &

Be sure that your name resolver setup is correct. Otherwise, you may experience resolver delays or
failures when connecting to mysqld. Also make sure that the localhost entry in the /etc/hosts
file is correct. The file should start with a line similar to this:
127.0.0.1

localhost localhost.your.domain

FreeBSD is known to have a very low default file handle limit. See Section B.5.2.18, “File Not Found
and Similar Errors”. Start the server by using the --open-files-limit option for mysqld_safe,
or raise the limits for the mysqld user in /etc/login.conf and rebuild it with cap_mkdb /etc/
login.conf. Also be sure that you set the appropriate class for this user in the password file if you
are not using the default (use chpass mysqld-user-name). See Section 4.3.2, “mysqld_safe —
MySQL Server Startup Script”.
FreeBSD limits the size of a process to 512MB, even if you have much more RAM available on the
system. So you may get an error such as this:
Out of memory (Needed 16391 bytes)

In current versions of FreeBSD (at least 4.x and greater), you may increase this limit by adding the
following entries to the /boot/loader.conf file and rebooting the machine (these are not settings
that can be changed at run time with the sysctl command):
kern.maxdsiz="1073741824" # 1GB
kern.dfldsiz="1073741824" # 1GB
kern.maxssiz="134217728" # 128MB

For older versions of FreeBSD, you must recompile your kernel to change the maximum data segment
size for a process. In this case, you should look at the MAXDSIZ option in the LINT config file for more
information.
If you get problems with the current date in MySQL, setting the TZ variable should help. See
Section 2.21, “Environment Variables”.

2.20.4.2 NetBSD Notes
To compile on NetBSD, you need GNU make. Otherwise, the build process fails when make tries to run
lint on C++ files.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

BSD Notes

2.20.4.3 OpenBSD 2.5 Notes
On OpenBSD 2.5, you can compile MySQL with native threads with the following options:
CFLAGS=-pthread CXXFLAGS=-pthread ./configure --with-mit-threads=no

2.20.4.4 BSD/OS Version 2.x Notes
If you get the following error when compiling MySQL, your ulimit value for virtual memory is too low:
item_func.h: In method
`Item_func_ge::Item_func_ge(const Item_func_ge &)':
item_func.h:28: virtual memory exhausted
make[2]: *** [item_func.o] Error 1

Try using ulimit -v 80000 and run make again. If this doesn't work and you are using bash, try
switching to csh or sh; some BSDI users have reported problems with bash and ulimit.
If you are using gcc, you may also use have to use the --with-low-memory flag for configure to
be able to compile sql_yacc.cc.
If you get problems with the current date in MySQL, setting the TZ variable should help. See
Section 2.21, “Environment Variables”.

2.20.4.5 BSD/OS Version 3.x Notes
Upgrade to BSD/OS 3.1. If that is not possible, install BSDIpatch M300-038.
Use the following command when configuring MySQL:
env CXX=shlicc++ CC=shlicc2 \
./configure \
--prefix=/usr/local/mysql \
--localstatedir=/var/mysql \
--without-perl \
--with-unix-socket-path=/var/mysql/mysql.sock

The following is also known to work:
env CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure \
--prefix=/usr/local/mysql \
--with-unix-socket-path=/var/mysql/mysql.sock

You can change the directory locations if you wish, or just use the defaults by not specifying any
locations.
If you have problems with performance under heavy load, try using the --skip-thread-priority
option to mysqld. This runs all threads with the same priority. On BSDI 3.1, this gives better
performance, at least until BSDI fixes its thread scheduler.
If you get the error virtual memory exhausted while compiling, you should try using ulimit v 80000 and running make again. If this doesn't work and you are using bash, try switching to csh or
sh; some BSDI users have reported problems with bash and ulimit.

2.20.4.6 BSD/OS Version 4.x Notes
BSDI 4.x has some thread-related bugs. If you want to use MySQL on this, you should install all threadrelated patches. At least M400-023 should be installed.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

On some BSDI 4.x systems, you may get problems with shared libraries. The symptom is that you can't
execute any client programs, for example, mysqladmin. In this case, you need to reconfigure not to
use shared libraries with the --disable-shared option to configure.
Some customers have had problems on BSDI 4.0.1 that the mysqld binary after a while can't open
tables. This occurs because some library/system-related bug causes mysqld to change current
directory without having asked for that to happen.
The fix is to either upgrade MySQL to at least version 3.23.34 or, after running configure, remove
the line #define HAVE_REALPATH from config.h before running make.
Note that this means that you can't symbolically link a database directories to another database
directory or symbolic link a table to another database on BSDI. (Making a symbolic link to another disk
is okay).

2.20.5 Other Unix Notes
2.20.5.1 HP-UX Version 10.20 Notes
If you install MySQL using a binary tarball distribution on HP-UX, you may run into trouble even before
you get the MySQL distribution unpacked, as the HP-UX tar cannot handle long file names. This
means that you may see errors when you try to unpack MySQL.
If this occurs, you must use GNU tar (gtar) to unpack the distribution.
There are a couple of small problems when compiling MySQL on HP-UX. Use gcc instead of the HPUX native compiler, because gcc produces better code.
Use gcc 2.95 on HP-UX. Do not use high optimization flags (such as -O6) because they may not be
safe on HP-UX.
The following configure line should work with gcc 2.95:
CFLAGS="-I/opt/dce/include -fpic" \
CXXFLAGS="-I/opt/dce/include -felide-constructors -fno-exceptions \
-fno-rtti" \
CXX=gcc \
./configure --with-pthread \
--with-named-thread-libs='-ldce' \
--prefix=/usr/local/mysql --disable-shared

The following configure line should work with gcc 3.1:
CFLAGS="-DHPUX -I/opt/dce/include -O3 -fPIC" CXX=gcc \
CXXFLAGS="-DHPUX -I/opt/dce/include -felide-constructors \
-fno-exceptions -fno-rtti -O3 -fPIC" \
./configure --prefix=/usr/local/mysql \
--with-extra-charsets=complex --enable-thread-safe-client \
--enable-local-infile --with-pthread \
--with-named-thread-libs=-ldce --with-lib-ccflags=-fPIC
--disable-shared

2.20.5.2 HP-UX Version 11.x Notes
If you install MySQL using a binary tarball distribution on HP-UX, you may run into trouble even before
you get the MySQL distribution unpacked, as the HP-UX tar cannot handle long file names. This
means that you may see errors when you try to unpack MySQL.
If this occurs, you must use GNU tar (gtar) to unpack the distribution.
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:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

PHKL_22840 Streams cumulative
PHNE_22397 ARPA cumulative

This solves the problem of getting EWOULDBLOCK from recv() and EBADF from accept() in
threaded applications.
If you are using gcc 2.95.1 on an unpatched HP-UX 11.x system, you may get the following error:
In file included from /usr/include/unistd.h:11,
from ../include/global.h:125,
from mysql_priv.h:15,
from item.cc:19:
/usr/include/sys/unistd.h:184: declaration of C function ...
/usr/include/sys/pthread.h:440: previous declaration ...
In file included from item.h:306,
from mysql_priv.h:158,
from item.cc:19:

The problem is that HP-UX does not define pthreads_atfork() consistently. It has conflicting
prototypes in /usr/include/sys/unistd.h:184 and /usr/include/sys/pthread.h:440.
One solution is to copy /usr/include/sys/unistd.h into mysql/include and edit unistd.h
and change it to match the definition in pthread.h. Look for this line:
extern int pthread_atfork(void (*prepare)(), void (*parent)(),
void (*child)());

Change it to look like this:
extern int pthread_atfork(void (*prepare)(void), void (*parent)(void),
void (*child)(void));

After making the change, the following configure line should work:
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 HP-UX compiler, you can use the following command (which has been tested with cc
B.11.11.04):
CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
--with-extra-character-set=complex

You can ignore any errors of the following type:
aCC: warning 901: unknown option: `-3': use +help for online
documentation

If you get the following error from configure, verify that you do not have the path to the K&R compiler
before the path to the HP-UX C and C++ compiler:
checking for cc option to accept ANSI C... no
configure: error: MySQL requires an ANSI C compiler (and a C++ compiler).
Try gcc. See the Installation chapter in the Reference Manual.

Another reason for not being able to compile is that you didn't define the +DD64 flags as just described.
Another possibility for HP-UX 11 is to use the MySQL binaries provided at http://dev.mysql.com/
downloads/, which we have built and tested ourselves. We have also received reports that the HP-UX
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

10.20 binaries supplied by MySQL can be run successfully on HP-UX 11. If you encounter problems,
you should be sure to check your HP-UX patch level.

2.20.5.3 IBM-AIX notes
Automatic detection of xlC is missing from Autoconf, so a number of variables need to be set before
running configure. The following example uses the IBM compiler:
export
export
export
export
export
export

CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
CFLAGS="-I /usr/local/include"
LDFLAGS="-L /usr/local/lib"
CPPFLAGS=$CFLAGS
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://wwwfrec.bull.com/.
If you change the -O3 to -O2 in the preceding configure line, you must also remove the -qstrict
option. This is a limitation in the IBM C compiler.
If you are using gcc to compile MySQL, you must use the -fno-exceptions flag, because the
exception handling in gcc is not thread-safe! There are also some known problems with IBM's
assembler that may cause it to generate bad code when used with gcc.
Use the following configure line with 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 do not know if the -fnoexceptions is required with gcc 2.95, but because MySQL doesn't use exceptions and the option
generates faster code, you should always use it with 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 do not know what your CPU is, execute a uname -m command. It produces a string that looks
like 000514676700, with a format of xxyyyyyymmss where xx and ss are always 00, yyyyyy is a
unique system ID and mm is the ID of the CPU Planar. A chart of these values can be found at http://
www16.boulder.ibm.com/pseries/en_US/cmds/aixcmds5/uname.htm.
This gives you a machine type and a machine model you can use to determine what type of CPU you
have.
If you have problems with threads on AIX 5.3, you should upgrade AIX 5.3 to technology level 7
(5300-07).
If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an
OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring as
follows:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
-DDONT_USE_THR_ALARM" \
./configure --prefix=/usr/local/mysql --with-debug \
--with-low-memory

This doesn't affect the performance of MySQL, but has the side effect that you can't kill clients that are
“sleeping” on a connection with mysqladmin kill or mysqladmin shutdown. Instead, the client
dies when it issues its next command.
On some versions of AIX, linking with libbind.a makes getservbyname() dump core. This is an
AIX bug and should be reported to IBM.
For AIX 4.2.1 and gcc, you have to make the following changes.
After configuring, edit config.h and include/my_config.h and change the line that says this:
#define HAVE_SNPRINTF 1

to this:
#undef HAVE_SNPRINTF

And finally, in mysqld.cc, you need to add a prototype for initgroups().
#ifdef _AIX41
extern "C" int initgroups(const char *,int);
#endif

For 32-bit binaries, if you need to allocate a lot of memory to the mysqld process, it is not enough
to just use ulimit -d unlimited. You may also have to modify mysqld_safe to add a line
something like this:
export LDR_CNTRL='MAXDATA=0x80000000'

You can find more information about using a lot of memory at http://publib16.boulder.ibm.com/pseries/
en_US/aixprggd/genprogc/lrg_prg_support.htm.
Users of AIX 4.3 should use gmake instead of the make utility included with AIX.
As of AIX 4.1, the C compiler has been unbundled from AIX as a separate product. gcc 3.3.2 can be
obtained here: ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/gcc/
The steps for compiling MySQL on AIX with gcc 3.3.2 are similar to those for using gcc 2.95 (in
particular, the need to edit config.h and my_config.h after running configure). However, before
running configure, you should also patch the curses.h file as follows:
/opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/curses.h.ORIG
Mon Dec 26 02:17:28 2005
--- /opt/freeware/lib/gcc-lib/powerpc-ibm-aix5.2.0.0/3.3.2/include/curses.h
Mon Dec 26 02:40:13 2005
***************
*** 2023,2029 ****

#endif /* _AIX32_CURSES */
! #if defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus) || defined
(__STRICT_ANSI__)
extern int delwin (WINDOW *);
extern int endwin (void);
extern int getcurx (WINDOW *);
--- 2023,2029 ----

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

#endif /* _AIX32_CURSES */
! #if 0 && (defined(__USE_FIXED_PROTOTYPES__) || defined(__cplusplus)
|| defined
(__STRICT_ANSI__))
extern int delwin (WINDOW *);
extern int endwin (void);
extern int getcurx (WINDOW *);

2.20.5.4 SunOS 4 Notes
On SunOS 4, MIT-pthreads is needed to compile MySQL. This in turn means you need GNU make.
Some SunOS 4 systems have problems with dynamic libraries and libtool. You can use the
following configure line to avoid this problem:
./configure --disable-shared --with-mysqld-ldflags=-all-static

When compiling readline, you may get warnings about duplicate defines. These can be ignored.
When compiling mysqld, there are some implicit declaration of function warnings. These
can be ignored.

2.20.5.5 Alpha-DEC-UNIX Notes (Tru64)
If you are using egcs 1.1.2 on Digital Unix, you should upgrade to gcc 2.95.2, because egcs on DEC
has some serious bugs!
When compiling threaded programs under Digital Unix, the documentation recommends using the pthread option for cc and cxx and the -lmach -lexc libraries (in addition to -lpthread). You
should run configure something like this:
CC="cc -pthread" CXX="cxx -pthread -O" \
./configure --with-named-thread-libs="-lpthread -lmach -lexc -lc"

When compiling mysqld, you may see a couple of warnings like this:
mysqld.cc: In function void handle_connections()':
mysqld.cc:626: passing long unsigned int *' as argument 3 of
accept(int,sockadddr *, int *)'

You can safely ignore these warnings. They occur because configure can detect only errors, not
warnings.
If you start the server directly from the command line, you may have problems with it dying when you
log out. (When you log out, your outstanding processes receive a SIGHUP signal.) If so, try starting the
server like this:
nohup mysqld [options] &

nohup causes the command following it to ignore any SIGHUP signal sent from the terminal.
Alternatively, start the server by running mysqld_safe, which invokes mysqld using nohup for you.
See Section 4.3.2, “mysqld_safe — MySQL Server Startup Script”.
If you get a problem when compiling mysys/get_opt.c, just remove the #define _NO_PROTO line
from the start of that file.
If you are using Compaq's CC compiler, the following configure line should work:
CC="cc -pthread"
CFLAGS="-O4 -ansi_alias -ansi_args -fast -inline speed \

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

-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/local/mysql \
--with-low-memory \
--enable-large-files \
--enable-shared=yes \
--with-named-thread-libs="-lpthread -lmach -lexc -lc"
gnumake

If you get a problem with libtool when compiling with shared libraries as just shown, when linking
mysql, you should be able to get around this by issuing these commands:
cd mysql
/bin/sh ../libtool --mode=link cxx -pthread -O3 -DDBUG_OFF \
-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all \ -arch host -DUNDEF_HAVE_GETHOSTBYNAME_R \
-o mysql mysql.o readline.o sql_string.o completion_hash.o \
../readline/libreadline.a -lcurses \
../libmysql/.libs/libmysqlclient.so -lm
cd ..
gnumake
gnumake install
scripts/mysql_install_db

2.20.5.6 Alpha-DEC-OSF/1 Notes
If you have problems compiling and have DEC CC and gcc installed, try running configure like this:
CC=cc CFLAGS=-O CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql

If you get problems with the c_asm.h file, you can create and use a 'dummy' c_asm.h file with:
touch include/c_asm.h
CC=gcc CFLAGS=-I./include \
CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql

Note that the following problems with the ld program can be fixed by downloading the latest DEC
(Compaq) patch kit from: http://ftp.support.compaq.com/public/unix/.
On OSF/1 V4.0D and compiler "DEC C V5.6-071 on Digital Unix V4.0 (Rev. 878)," the compiler had
some strange behavior (undefined asm symbols). /bin/ld also appears to be broken (problems with
_exit undefined errors occurring while linking mysqld). On this system, we have managed to
compile MySQL with the following configure line, after replacing /bin/ld with the version from OSF
4.0C:
CC=gcc CXX=gcc CXXFLAGS=-O3 ./configure --prefix=/usr/local/mysql

With the Digital compiler "C++ V6.1-029," the following should work:
CC=cc -pthread
CFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host
CXX=cxx -pthread
CXXFLAGS=-O4 -ansi_alias -ansi_args -fast -inline speed \
-speculate all -arch host -noexceptions -nortti
export CC CFLAGS CXX CXXFLAGS
./configure --prefix=/usr/mysql/mysql \
--with-mysqld-ldflags=-all-static --disable-shared \

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

--with-named-thread-libs="-lmach -lexc -lc"

In some versions of OSF/1, the alloca() function is broken. Fix this by removing the line in
config.h that defines 'HAVE_ALLOCA'.
The alloca() function also may have an incorrect prototype in /usr/include/alloca.h. This
warning resulting from this can be ignored.
configure uses the following thread libraries automatically: --with-named-thread-libs="lpthread -lmach -lexc -lc".
When using gcc, you can also try running configure like this:
CFLAGS=-D_PTHREAD_USE_D4 CXX=gcc CXXFLAGS=-O3 ./configure ...

If you have problems with signals (MySQL dies unexpectedly under high load), you may have found
an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring
with:
CFLAGS=-DDONT_USE_THR_ALARM \
CXXFLAGS=-DDONT_USE_THR_ALARM \
./configure ...

This does not affect the performance of MySQL, but has the side effect that you can't kill clients that
are “sleeping” on a connection with mysqladmin kill or mysqladmin shutdown. Instead, the
client dies when it issues its next command.
With gcc 2.95.2, you may encounter the following compile error:
sql_acl.cc:1456: Internal compiler error in `scan_region',
at except.c:2566
Please submit a full bug report.

To fix this, you should change to the sql directory and do a cut-and-paste of the last gcc line, but
change -O3 to -O0 (or add -O0 immediately after gcc if you do not have any -O option on your
compile line). After this is done, you can just change back to the top-level directory and run make
again.

2.20.5.7 SGI Irix Notes
Note
As of MySQL 5.0, we do not provide binaries for Irix any more.
If you are using Irix 6.5.3 or newer, mysqld is able to create threads only if you run it as a user that
has CAP_SCHED_MGT privileges (such as root) or give the mysqld server this privilege with the
following shell command:
chcap "CAP_SCHED_MGT+epi" /opt/mysql/libexec/mysqld

You may have to undefine some symbols in config.h after running configure and before
compiling.
In some Irix implementations, the alloca() function is broken. If the mysqld server dies on
some SELECT statements, remove the lines from config.h that define HAVE_ALLOC and
HAVE_ALLOCA_H. If mysqladmin create doesn't work, remove the line from config.h that defines
HAVE_READDIR_R. You may have to remove the HAVE_TERM_H line as well.
SGI recommends that you install all the patches on this page as a set: http://support.sgi.com/surfzone/
patches/patchset/6.2_indigo.rps.html
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

At the very minimum, you should install the latest kernel rollup, the latest rld rollup, and the latest
libc rollup.
You definitely need all the POSIX patches on this page, for pthreads support:
http://support.sgi.com/surfzone/patches/patchset/6.2_posix.rps.html
If you get the something like the following error when compiling mysql.cc:
"/usr/include/curses.h", line 82: error(1084):
invalid combination of type

Type the following in the top-level directory of your MySQL source tree:
extra/replace bool curses_bool < /usr/include/curses.h > include/curses.h
make

There have also been reports of scheduling problems. If only one thread is running, performance is
slow. Avoid this by starting another client. This may lead to a two-to-tenfold increase in execution
speed thereafter for the other thread. This is a poorly understood problem with Irix threads; you may
have to improvise to find solutions until this can be fixed.
If you are compiling with gcc, you can use the following configure command:
CC=gcc CXX=gcc CXXFLAGS=-O3 \
./configure --prefix=/usr/local/mysql --enable-thread-safe-client \
--with-named-thread-libs=-lpthread

On Irix 6.5.11 with native Irix C and C++ compilers ver. 7.3.1.2, the following is reported to work
CC=cc CXX=CC CFLAGS='-O3 -n32 -TARG:platform=IP22 -I/usr/local/include \
-L/usr/local/lib' CXXFLAGS='-O3 -n32 -TARG:platform=IP22 \
-I/usr/local/include -L/usr/local/lib' \
./configure --prefix=/usr/local/mysql --with-innodb --with-berkeley-db \
--with-libwrap=/usr/local \
--with-named-curses-libs=/usr/local/lib/libncurses.a

2.20.5.8 SCO UNIX and OpenServer 5.0.x 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 progress on a port to sco3.2v4.2. Open Server 5.0.8 (Legend) has native
threads and permits files greater than 2GB. The current maximum file size is 2GB.
We have been able to compile MySQL with the following configure command on OpenServer with
gcc 2.95.3.
CC=gcc CFLAGS="-D_FILE_OFFSET_BITS=64 -O3" \
CXX=gcc CXXFLAGS="-D_FILE_OFFSET_BITS=64 -O3" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-innodb \
--with-openssl --with-vio --with-extra-charsets=complex

gcc is available at ftp://ftp.sco.com/pub/openserver5/opensrc/gnutools-5.0.7Kj.
This development system requires the OpenServer Execution Environment Supplement oss646B on
OpenServer 5.0.6 and oss656B and the OpenSource libraries found in gwxlibs. All OpenSource tools
are in the opensrc directory. They are available at ftp://ftp.sco.com/pub/openserver5/opensrc/.
Use the latest production release of MySQL.
SCO provides operating system patches at ftp://ftp.sco.com/pub/openserver5 for OpenServer 5.0.[0-6]
and ftp://ftp.sco.com/pub/openserverv5/507 for OpenServer 5.0.7.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

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 OpenServer 5.0.x system is 2GB.
The total memory which can 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.
1. Log in as root.
2. Enable the SUDS driver by editing the /etc/conf/sdevice.d/suds file. Change the N in the
second field to a Y.
3. Use mkdev aio or the Hardware/Kernel Manager to enable support for asynchronous I/O and
relink the kernel. To enable 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.
4. Many applications use setuid binaries so that you need to specify only a single user. See the
documentation provided with the application to determine whether this is the case for your
application.
After you complete this process, reboot the system to create a new kernel incorporating these changes.
By default, the entries in /etc/conf/cf.d/mtune are set as follows:
Value
Default
----------NBUF
0
NHBUF
0
NMPBUF
0
MAX_INODE
0
MAX_FILE
0
CTBUFSIZE
128
MAX_PROC
0
MAX_REGION
0
NCLIST
170
MAXUP
100
NOFILES
110
NHINODE
128
NAUTOUP
10
NGROUPS
8
BDFLUSHR
30
MAX_FLCKREC
0
PUTBUFSZ
8000
MAXSLICE
100
ULIMIT
4194303
* Streams Parameters
NSTREAM
64
NSTRPUSH
9
NMUXLINK
192
STRMSGSZ
16384
STRCTLSZ
1024
STRMAXBLK
524288
NSTRPAGES
500
STRSPLITFRAC
80
NLOG
3
NUMSP
64

This
documentation
is for an
older version.
If you're

Min
--24
32
12
100
100
0
50
500
120
15
60
64
0
0
1
50
2000
25
2048

Max
--450000
524288
512
64000
64000
256
16000
160000
16640
16000
11000
8192
60
128
300
16000
20000
100
4194303

1
9
1
4096
1024
4096
0
50
3
1

32768
9
4096
524288
1024
524288
8000
100
3
256

This
documentation
is for an
older version.
If you're

Other Unix Notes

NUMTIM
16
NUMTRW
16
* Semaphore Parameters
SEMMAP
10
SEMMNI
10
SEMMNS
60
SEMMNU
30
SEMMSL
25
SEMOPM
10
SEMUME
10
SEMVMX
32767
SEMAEM
16384
* Shared Memory Parameters
SHMMAX
524288
SHMMIN
1
SHMMNI
100
FILE
0
NMOUNT
0
NPROC
0
NREGION
0

1
1

8192
8192

10
10
60
10
25
10
10
32767
16384

8192
8192
8192
8192
150
1024
25
32767
16384

131072
1
100
100
4
50
500

2147483647
1
2000
64000
256
16000
160000

Set these values as follows:
• NOFILES should be 4096 or 2048.
• MAXUP should be 2048.
To make changes to the kernel, use the idtune name parameter command. idtune modifies the
/etc/conf/cf.d/stune file for you. For example, to change SEMMS to 200, execute this command
as root:
# /etc/conf/bin/idtune SEMMNS 200

Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6

To tune the system, the proper parameter values to use depend on the number of users accessing the
application or database and size the of the database (that is, the used buffer pool). The following kernel
parameters can be set with idtune:
• SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters
have an influence on the MySQL database engine to create user buffer pools.
• NOFILES and MAXUP should be set to at least 2048.
• MAXPROC should be set to at least 3000/4000 (depends on number of users) or more.
• The following formulas are recommended to calculate values for SEMMSL, SEMMNS, and SEMMNU:
SEMMSL = 13

13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system

Set SEMMNS to the value of SEMMSL multiplied by the number of database servers (maximum) that
you are running on the system at one time.
SEMMNU = SEMMNS

Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

You need to at least install the SCO OpenServer Linker and Application Development Libraries or the
OpenServer Development System to use gcc. You cannot use the GCC Dev system without installing
one of these.
You should get the FSU Pthreads package and install it first. This can be found at http://
moss.csc.ncsu.edu/~mueller/ftp/pub/PART/pthreads.tar.gz. You can also get a precompiled package
from ftp://ftp.zenez.com/pub/zenez/prgms/FSU-threads-3.14.tar.gz.
FSU Pthreads can be compiled with SCO Unix 4.2 with tcpip, or using OpenServer 3.0 or Open
Desktop 3.0 (OS 3.0 ODT 3.0) with the SCO Development System installed using a good port of GCC
2.5.x. For ODT or OS 3.0, you need a good port of GCC 2.5.x. There are a lot of problems without a
good port. The port for this product requires the SCO Unix Development system. Without it, you are
missing the libraries and the linker that is needed. You also need SCO-3.2v4.2-includes.tar.gz.
This file contains the changes to the SCO Development include files that are needed to get MySQL to
build. You need to replace the existing system include files with these modified header files. They can
be obtained from ftp://ftp.zenez.com/pub/zenez/prgms/SCO-3.2v4.2-includes.tar.gz.
To build FSU Pthreads on your system, all you should need to do is run GNU make. The Makefile in
FSU-threads-3.14.tar.gz is set up to make FSU-threads.
You can run ./configure in the threads/src directory and select the SCO OpenServer option.
This command copies Makefile.SCO5 to Makefile. Then run make.
To install in the default /usr/include directory, log in as root, and then cd to the thread/src
directory and run make install.
Remember that you must use GNU make to build MySQL.
Note
If you do not start mysqld_safe as root, you should get only the default 110
open files per process. mysqld writes a note about this in the log file.
With SCO 3.2V4.2, you should use FSU Pthreads version 3.14 or newer. The following configure
command should work:
CFLAGS="-D_XOPEN_XPG4" CXX=gcc CXXFLAGS="-D_XOPEN_XPG4" \
./configure \
--prefix=/usr/local/mysql \
--with-named-thread-libs="-lgthreads -lsocket -lgen -lgthreads" \
--with-named-curses-libs="-lcurses"

You may have 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 mysqld with -lgthreads -lsocket
-lgthreads.
• The SCO development libraries are re-entrant in FSU Pthreads. SCO claims that its library functions
are re-entrant, so they must be re-entrant with FSU Pthreads. FSU Pthreads on OpenServer tries to
use the SCO scheme to make re-entrant libraries.
• FSU Pthreads (at least the version at ftp://ftp.zenez.com) comes linked with GNU malloc.
If you encounter problems with memory usage, make sure that gmalloc.o is included in
libgthreads.a and libgthreads.so.
• In FSU Pthreads, the following system calls are pthreads-aware: read(), write(), getmsg(),
connect(), accept(), select(), and wait().
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

• The CSSA-2001-SCO.35.2 (the patch is listed in custom as erg711905-dscr_remap security patch
(version 2.0.0)) breaks FSU threads and makes mysqld unstable. You have to remove this one if
you want to run mysqld on an OpenServer 5.0.6 machine.
• If you use SCO OpenServer 5, you may need to recompile FSU pthreads with -DDRAFT7 in CFLAGS.
Otherwise, InnoDB may hang at a mysqld startup.
• 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 is probably a good idea to install these patches before trying to compile/use MySQL.
Beginning with Legend/OpenServer 6.0.0, there are native threads and no 2GB file size limit.

2.20.5.9 SCO OpenServer 6.0.x Notes
OpenServer 6 includes these key improvements:
• Larger file support up to 1 TB
• Multiprocessor support increased from 4 to 32 processors
• Increased memory support up to 64GB
• Extending the power of UnixWare into OpenServer 6
• Dramatic performance improvement
OpenServer 6.0.0 commands are organized as follows:
• /bin is for commands that behave exactly the same as on OpenServer 5.0.x.
• /u95/bin is for commands that have better standards conformance, for example Large File System
(LFS) support.
• /udk/bin is for commands that behave the same as on UnixWare 7.1.4. The default is for the LFS
support.
The following is a guide to setting PATH on OpenServer 6. If the user wants the traditional OpenServer
5.0.x then PATH should be /bin first. If the user wants LFS support, the path should be /u95/bin:/
bin. If the user wants UnixWare 7 support first, the path would be /udk/bin:/u95/bin:/bin:.
Use the latest production release of MySQL. Should you choose to use an older release of MySQL on
OpenServer 6.0.x, you must use a version of MySQL at least as recent as 3.22.13 to get fixes for some
portability and OS problems.
MySQL distribution files with names of the following form are tar archives of media are tar archives
of media images suitable for installation with the SCO Software Manager (/etc/custom) on SCO
OpenServer 6:
mysql-PRODUCT-5.0.96-sco-osr6-i686.VOLS.tar

A distribution where PRODUCT is pro-cert is the Commercially licensed MySQL Pro Certified server.
A distribution where PRODUCT is pro-gpl-cert is the MySQL Pro Certified server licensed under the
terms of the General Public License (GPL).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

Select whichever distribution you wish to install and, after download, extract the tar archive into an
empty directory. For example:
shell> mkdir /tmp/mysql-pro
shell> cd /tmp/mysql-pro
shell> tar xf /tmp/mysql-pro-cert-5.0.96-sco-osr6-i686.VOLS.tar

Prior to installation, back up your data in accordance with the procedures outlined in Section 2.19.1,
“Upgrading MySQL”.
Remove any previously installed pkgadd version of MySQL:
shell> pkginfo mysql 2>&1 > /dev/null && pkgrm mysql

Install MySQL Pro from media images using the SCO Software Manager:
shell> /etc/custom -p SCO:MySQL -i -z /tmp/mysql-pro

Alternatively, the SCO Software Manager can be displayed graphically by clicking the Software
Manager icon on the desktop, selecting Software -> Install New, selecting the host, selecting
Media Images for the Media Device, and entering /tmp/mysql-pro as the Image Directory.
After installation, run mkdev mysql as the root user to configure your newly installed MySQL Pro
Certified server.
Note
The installation procedure for VOLS packages does not create the mysql
user and group that the package uses by default. You should either create the
mysql user and group, or else select a different user and group using an option
in mkdev mysql.
If you wish to configure your MySQL Pro server to interface with the Apache Web server using
PHP, download and install the PHP update from SCO at ftp://ftp.sco.com/pub/updates/OpenServer/
SCOSA-2006.17/.
We have been able to compile MySQL with the following configure command on OpenServer 6.0.x:
CC=cc CFLAGS="-D_FILE_OFFSET_BITS=64 -O3" \
CXX=CC CXXFLAGS="-D_FILE_OFFSET_BITS=64 -O3" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-berkeley-db \
--with-extra-charsets=complex \
--build=i686-unknown-sysv5SCO_SV6.0.0

If you use gcc, you must use gcc 2.95.3 or newer.
CC=gcc CXX=g++ ... ./configure ...

The version of Berkeley DB that comes with either UnixWare 7.1.4 or OpenServer 6.0.0 is not
used when building MySQL. MySQL instead uses its own version of Berkeley DB. The configure
command needs to build both a static and a dynamic library in src_directory/bdb/build_unix/,
but it does not with MySQL's own BDB version. The workaround is as follows.
1. Configure as normal for MySQL.
2. cd bdb/build_unix/
3. cp -p Makefile Makefile.sav
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

4. Use same options and run ../dist/configure.
5. Run gmake.
6. cp -p Makefile.sav Makefile
7. Change location to the top source directory and run gmake.
This enables both the shared and dynamic libraries to be made and work.
SCO provides OpenServer 6 operating system patches at ftp://ftp.sco.com/pub/openserver6.
SCO provides information about security fixes at ftp://ftp.sco.com/pub/security/OpenServer.
By default, the maximum file size on a OpenServer 6.0.0 system is 1TB. Some operating system
utilities have a limitation of 2GB. The maximum possible file size on UnixWare 7 is 1TB with VXFS or
HTFS.
OpenServer 6 can be configured for large file support (file sizes greater than 2GB) by tuning the UNIX
kernel.
By default, the entries in /etc/conf/cf.d/mtune are set as follows:
Value
----SVMMLIM
HVMMLIM

Default
------0x9000000
0x9000000

Min
--0x1000000
0x1000000

Max
--0x7FFFFFFF
0x7FFFFFFF

To make changes to the kernel, use the idtune name parameter command. idtune modifies the
/etc/conf/cf.d/stune file for you. To set the kernel values, execute the following commands as
root:
#
#
#
#
#
#

/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune

SDATLIM
HDATLIM
SVMMLIM
HVMMLIM
SFNOLIM
HFNOLIM

0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
2048
2048

Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6

To tune the system, the proper parameter values to use depend on the number of users accessing the
application or database and size the of the database (that is, the used buffer pool). The following kernel
parameters can be set with idtune:
• SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters
have an influence on the MySQL database engine to create user buffer pools.
• SFNOLIM and HFNOLIM should be at maximum 2048.
• NPROC should be set to at least 3000/4000 (depends on number of users).
• The following formulas are recommended to calculate values for SEMMSL, SEMMNS, and SEMMNU:
SEMMSL = 13

13 is what has been found to be the best for both Progress and MySQL.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

SEMMNS = SEMMSL * number of db servers to be run on the system

Set SEMMNS to the value of SEMMSL multiplied by the number of database servers (maximum) that
you are running on the system at one time.
SEMMNU = SEMMNS

Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.

2.20.5.10 SCO UnixWare 7.1.x and OpenUNIX 8.0.0 Notes
Use the latest production release of MySQL. Should you choose to use an older release of MySQL on
UnixWare 7.1.x, you must use a version of MySQL at least as recent as 3.22.13 to get fixes for some
portability and OS problems.
We have been able to compile MySQL with the following configure command on UnixWare 7.1.x:
CC="cc" CFLAGS="-I/usr/local/include" \
CXX="CC" CXXFLAGS="-I/usr/local/include" \
./configure --prefix=/usr/local/mysql \
--enable-thread-safe-client --with-berkeley-db=./bdb \
--with-innodb --with-openssl --with-extra-charsets=complex

If you want to use gcc, you must use gcc 2.95.3 or newer.
CC=gcc CXX=g++ ... ./configure ...

The version of Berkeley DB that comes with either UnixWare 7.1.4 or OpenServer 6.0.0 is not
used when building MySQL. MySQL instead uses its own version of Berkeley DB. The configure
command needs to build both a static and a dynamic library in src_directory/bdb/build_unix/,
but it does not with MySQL's own BDB version. The workaround is as follows.
1. Configure as normal for MySQL.
2. cd bdb/build_unix/
3. cp -p Makefile Makefile.sav
4. Use same options and run ../dist/configure.
5. Run gmake.
6. cp -p Makefile.sav Makefile
7. Change to top source directory and run gmake.
This enables both the shared and dynamic libraries to be made and work.
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.
The UnixWare 7 file size limit is 1 TB with VXFS. Some OS utilities have a limitation of 2GB.
On UnixWare 7.1.4 you do not need to do anything to get large file support, but to enable large file
support on prior versions of UnixWare 7.1.x, run fsadm.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Unix Notes

#
#
#
#
#
#

fsadm -Fvxfs -o largefiles /
fsadm /
* Note
ulimit unlimited
/etc/conf/bin/idtune SFSZLIM 0x7FFFFFFF
/etc/conf/bin/idtune HFSZLIM 0x7FFFFFFF
/etc/conf/bin/idbuild -B

** Note
** Note

* 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 as follows:
Value
----SVMMLIM
HVMMLIM

Default
------0x9000000
0x9000000

Min
--0x1000000
0x1000000

Max
--0x7FFFFFFF
0x7FFFFFFF

To make changes to the kernel, use the idtune name parameter command. idtune modifies the
/etc/conf/cf.d/stune file for you. To set the kernel values, execute the following commands as
root:
#
#
#
#
#
#

/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune
/etc/conf/bin/idtune

SDATLIM
HDATLIM
SVMMLIM
HVMMLIM
SFNOLIM
HFNOLIM

0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
2048
2048

Then rebuild and reboot the kernel by issuing this command:
# /etc/conf/bin/idbuild -B && init 6

To tune the system, the proper parameter values to use depend on the number of users accessing the
application or database and size the of the database (that is, the used buffer pool). The following kernel
parameters can be set with idtune:
• SHMMAX (recommended setting: 128MB) and SHMSEG (recommended setting: 15). These parameters
have an influence on the MySQL database engine to create user buffer pools.
• SFNOLIM and HFNOLIM should be at maximum 2048.
• NPROC should be set to at least 3000/4000 (depends on number of users).
• The following formulas are recommended to calculate values for SEMMSL, SEMMNS, and SEMMNU:
SEMMSL = 13

13 is what has been found to be the best for both Progress and MySQL.
SEMMNS = SEMMSL * number of db servers to be run on the system

Set SEMMNS to the value of SEMMSL multiplied by the number of database servers (maximum) that
you are running on the system at one time.
SEMMNU = SEMMNS

Set the value of SEMMNU to equal the value of SEMMNS. You could probably set this to 75% of
SEMMNS, but this is a conservative estimate.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

OS/2 Notes

2.20.6 OS/2 Notes
Note
We no longer test builds on OS/2. The notes in this section are provided for
your information but may not work on your system.
MySQL uses quite a few open files. Because of this, you should add something like the following to
your CONFIG.SYS file:
SET EMXOPT=-c -n -h1024

If you do not do this, you may encounter the following error:
File 'xxxx' not found (Errcode: 24)

When using MySQL with OS/2 Warp 3, FixPack 29 or above is required. With OS/2 Warp 4, FixPack
4 or above is required. This is a requirement of the Pthreads library. MySQL must be installed on a
partition with a type that supports long file names, such as HPFS, FAT32, and so on.
The INSTALL.CMD script must be run from OS/2's own CMD.EXE and may not work with replacement
shells such as 4OS2.EXE.
The scripts/mysql-install-db script has been renamed. It is called install.cmd and is a
REXX script, which sets up the default MySQL security settings and creates the WorkPlace Shell icons
for MySQL.
Dynamic module support is compiled in but not fully tested. Dynamic modules should be compiled
using the Pthreads runtime library.
gcc -Zdll -Zmt -Zcrtdll=pthrdrtl -I../include -I../regex -I.. \
-o example udf_example.c -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 safemysqld.cmd script puts this directory in the BEGINLIBPATH environment
variable. When using UDF modules, specified extensions are ignored---it is
assumed to be .udf. For example, in Unix, the shared module might be named
example.so and you would load a function from it like this:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example.so';

In OS/2, the module would be named example.udf, but you would not specify the module extension:
mysql> CREATE FUNCTION metaphon RETURNS STRING SONAME 'example';

2.21 Environment Variables
This section lists environment variables that are used directly or indirectly by MySQL. Most of these
can also be found in other places in this manual.
Note that any options on the command line take precedence over values specified in option files
and environment variables, and values in option files take precedence over values in environment
variables. In many cases, it is preferable to use an option file instead of environment variables to
modify the behavior of MySQL. See Section 4.2.6, “Using Option Files”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Perl Installation Notes

Variable

Description

CXX

The name of your C++ compiler (for running configure).

CC

The name of your C compiler (for running configure).

CFLAGS

Flags for your C compiler (for running configure).

CXXFLAGS

Flags for your C++ compiler (for running configure).

DBI_USER

The default user name for Perl DBI.

DBI_TRACE

Trace options for Perl DBI.

HOME

The default path for the mysql history file is $HOME/.mysql_history.

LD_RUN_PATH

Used to specify the location of libmysqlclient.so.

MYSQL_DEBUG

Debug trace options when debugging.

MYSQL_GROUP_SUFFIX Option group suffix value (like specifying --defaults-group-suffix).
MYSQL_HISTFILE

The path to the mysql history file. If this variable is set, its value overrides
the default for $HOME/.mysql_history.

MYSQL_HOME

The path to the directory in which the server-specific my.cnf file resides (as
of MySQL 5.0.3).

MYSQL_HOST

The default host name used by the mysql command-line client.

MYSQL_PS1

The command prompt to use in the mysql command-line client.

MYSQL_PWD

The default password when connecting to mysqld. Using this is insecure.
See Section 6.1.2.1, “End-User Guidelines for Password Security”.

MYSQL_TCP_PORT

The default TCP/IP port number.

MYSQL_UNIX_PORT

The default Unix socket file name; used for connections to localhost.

PATH

Used by the shell to find MySQL programs.

TMPDIR

The directory in which temporary files are created.

TZ

This should be set to your local time zone. See Section B.5.3.7, “Time Zone
Problems”.

UMASK

The user-file creation mode when creating files. See note following table.

UMASK_DIR

The user-directory creation mode when creating directories. See note
following table.

USER

The default user name on Windows and NetWare when connecting to
mysqld.

For information about the mysql history file, see Section 4.5.1.3, “mysql Logging”.
The default UMASK and UMASK_DIR values are 0660 and 0700, respectively. MySQL assumes that the
value for UMASK or UMASK_DIR is in octal if it starts with a zero. For example, setting UMASK=0600 is
equivalent to UMASK=384 because 0600 octal is 384 decimal.
The UMASK and UMASK_DIR variables, despite their names, are used as modes, not masks:
• If UMASK is set, mysqld uses ($UMASK | 0600) as the mode for file creation, so that newly
created files have a mode in the range from 0600 to 0666 (all values octal).
• If UMASK_DIR is set, mysqld uses ($UMASK_DIR | 0700) as the base mode for directory
creation, which then is AND-ed with ~(~$UMASK & 0666), so that newly created directories have
a mode in the range from 0700 to 0777 (all values octal). The AND operation may remove read and
write permissions from the directory mode, but not execute permissions.

2.22 Perl Installation Notes
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing Perl on Unix

The Perl DBI module provides a generic interface for database access. You can write a DBI script
that works with many different database engines without change. To use DBI, you must install the DBI
module, as well as a DataBase Driver (DBD) module for each type of database server you want to
access. For MySQL, this driver is the DBD::mysql module.
Perl, and the DBD::MySQL module for DBI must be installed if you want to run the MySQL benchmark
scripts; see Section 8.13.2, “The MySQL Benchmark Suite”. They are also required for the MySQL
Cluster ndb_size.pl utility; see Section 17.4.18, “ndb_size.pl — NDBCLUSTER Size
Requirement Estimator”.
Note
Perl support is not included with MySQL distributions. You can obtain the
necessary modules from http://search.cpan.org for Unix, or by using the
ActiveState ppm program on Windows. The following sections describe how to
do this.
The DBI/DBD interface requires Perl 5.6.0, and 5.6.1 or later is preferred. DBI does not work if you
have an older version of Perl. You should use DBD::mysql 4.009 or higher. Although earlier versions
are available, they do not support the full functionality of MySQL 5.0.

2.22.1 Installing Perl on Unix
MySQL Perl support requires that you have installed MySQL client programming support (libraries and
header files). Most installation methods install the necessary files. If you install MySQL from RPM files
on Linux, be sure to install the developer RPM as well. The client programs are in the client RPM, but
client programming support is in the developer RPM.
The files you need for Perl support 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 attempt to connect to the local
MySQL server using the default user name and password. (The default user name is your login name
on Unix, and ODBC on Windows. The default password is “no password.”) If you cannot connect to
the server with those values (for example, if your account has a password), the tests fail. You can use
force install DBD::mysql to ignore the failed tests.
DBI requires the Data::Dumper module. It may be installed; if not, you should install it before
installing DBI.
It is also possible to download the module distributions in the form of compressed tar archives and
build the modules manually. For example, to unpack and build a DBI distribution, use a procedure such
as this:
1. Unpack the distribution into the current directory:
shell> gunzip < DBI-VERSION.tar.gz | tar xvf -

This command creates a directory named DBI-VERSION.
2. Change location into the top-level directory of the unpacked distribution:
shell> cd DBI-VERSION

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Installing ActiveState Perl on Windows

3. Build the distribution and compile everything:
shell>
shell>
shell>
shell>

perl Makefile.PL
make
make test
make install

The make test command is important because it verifies that the module is working. Note that when
you run that command during the DBD::mysql installation to exercise the interface code, the MySQL
server must be running or the test fails.
It is a good idea to rebuild and reinstall the DBD::mysql distribution whenever you install a new
release of MySQL. This ensures that the latest versions of the MySQL client libraries are installed
correctly.
If you do not 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.22.2 Installing ActiveState Perl on Windows
On Windows, you should do the following to install the MySQL DBD module with ActiveState Perl:
1. Get ActiveState Perl from http://www.activestate.com/Products/ActivePerl/ and install it.
2. Open a console window.
3. If necessary, set the HTTP_proxy variable. For example, you might try a setting like this:
C:\> set HTTP_proxy=my.proxy.com:3128

4. Start the PPM program:
C:\> C:\perl\bin\ppm.pl

5. If you have not previously done so, install DBI:
ppm> install DBI

6. If this succeeds, run the following command:
ppm> install DBD-mysql

This procedure should work with ActiveState Perl 5.6 or newer.
If you cannot get the procedure to work, you should install the ODBC driver instead and connect to the
MySQL server through ODBC:
use DBI;
$dbh= DBI->connect("DBI:ODBC:$dsn",$user,$password) ||
die "Got error $DBI::errstr when connecting to $dsn\n";

2.22.3 Problems Using the Perl DBI/DBD Interface
If Perl reports that it cannot find the ../mysql/mysql.so module, the problem is probably that Perl
cannot locate the libmysqlclient.so shared library. You should be able to fix this problem by one
of the following methods:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Problems Using the Perl DBI/DBD Interface

• Compile the DBD::mysql distribution with perl Makefile.PL -static -config rather than
perl Makefile.PL.
• Copy libmysqlclient.so to the directory where your other shared libraries are located (probably
/usr/lib or /lib).
• Modify the -L options used to compile DBD::mysql to reflect the actual location of
libmysqlclient.so.
• On Linux, you can add the path name of the directory where libmysqlclient.so is located to the
/etc/ld.so.conf file.
•

Add the path name of the directory where libmysqlclient.so is located to the LD_RUN_PATH
environment variable. Some systems use LD_LIBRARY_PATH instead.

Note that you may also need to modify the -L options if there are other libraries that the linker fails to
find. For example, if the linker cannot find libc because it is in /lib and the link command specifies L/usr/lib, change the -L option to -L/lib or add -L/lib to the existing link command.
If you get the following errors from DBD::mysql, you are probably using gcc (or using an old binary
compiled with gcc):
/usr/bin/perl: can't resolve symbol '__moddi3'
/usr/bin/perl: can't resolve symbol '__divdi3'

Add -L/usr/lib/gcc-lib/... -lgcc to the link command when the mysql.so library gets built
(check the output from make for mysql.so when you compile the Perl client). The -L option should
specify the path name of the directory where libgcc.a is located on your system.
Another cause of this problem may be that Perl and MySQL are not both compiled with gcc. In this
case, you can solve the mismatch by compiling both with gcc.
You may see the following error from DBD::mysql when you run the tests:
t/00base............install_driver(mysql) failed:
Can't load '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol:
uncompress at /usr/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.

This means that you need to include the -lz compression library on the link line. That can be done by
changing the following line in the file lib/DBD/mysql/Install.pm:
$sysliblist .= " -lm";

Change that line to:
$sysliblist .= " -lm -lz";

After this, you must run make realclean and then proceed with the installation from the beginning.
If you want to install DBI on SCO, you have to edit the Makefile in DBI-xxx and each subdirectory.
Note that the following assumes gcc 2.95.2 or newer:
OLD:
CC = cc
CCCDLFLAGS = -KPIC -W1,-Bexport
CCDLFLAGS = -wl,-Bexport

NEW:
CC = gcc
CCCDLFLAGS = -fpic
CCDLFLAGS =

LD = ld
LDDLFLAGS = -G -L/usr/local/lib

LD = gcc -G -fpic
LDDLFLAGS = -L/usr/local/lib

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Problems Using the Perl DBI/DBD Interface

LDFLAGS = -belf -L/usr/local/lib

LDFLAGS = -L/usr/local/lib

LD = ld
OPTIMISE = -Od

LD = gcc -G -fpic
OPTIMISE = -O1

OLD:
CCCFLAGS = -belf -dy -w0 -U M_XENIX -DPERL_SCO5 -I/usr/local/include
NEW:
CCFLAGS = -U M_XENIX -DPERL_SCO5 -I/usr/local/include

These changes are necessary because the Perl dynaloader does not load the DBI modules if they
were compiled with icc or cc.
If you want to use the Perl module on a system that does not support dynamic linking (such as SCO),
you can generate a static version of Perl that includes DBI and DBD::mysql. The way this works is
that you generate a version of Perl with the DBI code linked in and install it on top of your current Perl.
Then you use that to build a version of Perl that additionally has the DBD code linked in, and install that.
On SCO, you must have the following environment variables set:
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>
shell>
shell>
shell>

perl Makefile.PL -static -config
make
make install
make perl

Then, you must install the new Perl. The output of make perl indicates the exact make command you
need to execute to perform the installation. On SCO, this is make -f Makefile.aperl inst_perl
MAP_TARGET=perl.
Next, use the just-created Perl to create another Perl that also includes a statically linked DBD::mysql
by running these commands in the directory where your DBD::mysql distribution is located:
shell>
shell>
shell>
shell>

perl Makefile.PL -static -config
make
make install
make perl

Finally, you should install this new Perl. Again, the output of make perl indicates the command to
use.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 3 Tutorial
Table of Contents
3.1 Connecting to and Disconnecting from the Server .................................................................
3.2 Entering Queries .................................................................................................................
3.3 Creating and Using a Database ...........................................................................................
3.3.1 Creating and Selecting a Database ...........................................................................
3.3.2 Creating a Table ......................................................................................................
3.3.3 Loading Data into a Table ........................................................................................
3.3.4 Retrieving Information from a Table ...........................................................................
3.4 Getting Information About Databases and Tables .................................................................
3.5 Using mysql in Batch Mode .................................................................................................
3.6 Examples of Common Queries ............................................................................................
3.6.1 The Maximum Value for a Column ............................................................................
3.6.2 The Row Holding the Maximum of a Certain Column .................................................
3.6.3 Maximum of Column per Group ................................................................................
3.6.4 The Rows Holding the Group-wise Maximum of a Certain Column ..............................
3.6.5 Using User-Defined Variables ...................................................................................
3.6.6 Using Foreign Keys ..................................................................................................
3.6.7 Searching on Two Keys ............................................................................................
3.6.8 Calculating Visits Per Day ........................................................................................
3.6.9 Using AUTO_INCREMENT .......................................................................................
3.7 Using MySQL with Apache ..................................................................................................

197
198
201
202
203
204
206
219
220
221
222
222
222
223
223
224
225
226
226
228

This chapter provides a tutorial introduction to MySQL by showing how to use the mysql client
program to create and use a simple database. mysql (sometimes referred to as the “terminal monitor”
or just “monitor”) is an interactive program that enables you to connect to a MySQL server, run
queries, and view the results. mysql may also be used in batch mode: you place your queries in a file
beforehand, then tell mysql to execute the contents of the file. Both ways of using mysql are covered
here.
To see a list of options provided by mysql, invoke it with the --help option:
shell> mysql --help

This chapter assumes that mysql is installed on your machine and that a MySQL server is available
to which you can connect. If this is not true, contact your MySQL administrator. (If you are the
administrator, you need to consult the relevant portions of this manual, such as Chapter 5, MySQL
Server Administration.)
This chapter describes the entire process of setting up and using a database. If you are interested only
in accessing an existing database, you may want to skip over the sections that describe how to create
the database and the tables it contains.
Because this chapter is tutorial in nature, many details are necessarily omitted. Consult the relevant
sections of the manual for more information on the topics covered here.

3.1 Connecting to and Disconnecting from the Server
To connect to the server, you will usually need to provide a MySQL user name when you invoke mysql
and, most likely, a password. If the server runs on a machine other than the one where you log in,
you will also need to specify a host name. Contact your administrator to find out what connection
parameters you should use to connect (that is, what host, user name, and password to use). Once you
know the proper parameters, you should be able to connect like this:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Entering Queries

shell> mysql -h host -u user -p
Enter password: ********

host and user represent the host name where your MySQL server is running and the user name of
your MySQL account. Substitute appropriate values for your setup. The ******** represents your
password; enter it when mysql displays the Enter password: prompt.
If that works, you should see some introductory information followed by a mysql> prompt:
shell> mysql -h host -u user -p
Enter password: ********
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 25338 to server version: 5.0.96-standard
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql>

The mysql> prompt tells you that mysql is ready for you to enter SQL statements.
If you are logging in on the same machine that MySQL is running on, you can omit the host, and simply
use the following:
shell> mysql -u user -p

If, when you attempt to log in, you get an error message such as ERROR 2002 (HY000): Can't
connect to local MySQL server through socket '/tmp/mysql.sock' (2), it means
that the MySQL server daemon (Unix) or service (Windows) is not running. Consult the administrator
or see the section of Chapter 2, Installing and Upgrading MySQL that is appropriate to your operating
system.
For help with other problems often encountered when trying to log in, see Section B.5.2, “Common
Errors When Using MySQL Programs”.
Some MySQL installations permit users to connect as the anonymous (unnamed) user to the server
running on the local host. If this is the case on your machine, you should be able to connect to that
server by invoking mysql without any options:
shell> mysql

After you have connected successfully, you can disconnect any time by typing QUIT (or \q) at the
mysql> prompt:
mysql> QUIT
Bye

On Unix, you can also disconnect by pressing Control+D.
Most examples in the following sections assume that you are connected to the server. They indicate
this by the mysql> prompt.

3.2 Entering Queries
Make sure that you are connected to the server, as discussed in the previous section. Doing so does
not in itself select any database to work with, but that is okay. At this point, it is 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 queries, using several
queries you can try out to familiarize yourself with how mysql works.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Entering Queries

Here is a simple query 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 |
+----------------+--------------+
| 5.0.7-beta-Max | 2005-07-11
|
+----------------+--------------+
1 row in set (0.01 sec)
mysql>

This query illustrates several things about mysql:
• A query 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 query, 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 query.
• mysql displays query output in tabular form (rows and columns). The first row contains labels for
the columns. The rows following are the query results. Normally, column labels are the names of the
columns you fetch from database tables. If you're retrieving the value of an expression rather than a
table column (as in the example just shown), mysql labels the column using the expression itself.
• mysql shows how many rows were returned and how long the query took to execute, which gives
you a rough idea of server performance. These values are imprecise because they represent wall
clock time (not CPU or machine time), and because they are affected by factors such as server load
and network latency. (For brevity, the “rows in set” line is sometimes 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 is another query. It demonstrates that you can use mysql as a simple calculator:
mysql> SELECT SIN(PI()/4), (4+1)*5;
+------------------+---------+
| SIN(PI()/4)
| (4+1)*5 |
+------------------+---------+
| 0.70710678118655 |
25 |
+------------------+---------+
1 row in set (0.02 sec)

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()
|
+----------------+
| 5.0.7-beta-Max |
+----------------+
1 row in set (0.00 sec)
+---------------------+
| NOW()
|
+---------------------+
| 2005-07-11 17:59:36 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Entering Queries

+---------------------+
1 row in set (0.00 sec)

A query need not be given all on a single line, so lengthy queries that require several lines are not a
problem. mysql determines where your statement ends by looking for the terminating semicolon, not
by looking for the end of the input line. (In other words, mysql accepts free-format input: it collects
input lines but does not execute them until it sees the semicolon.)
Here is a simple multiple-line statement:
mysql> SELECT
-> USER()
-> ,
-> CURRENT_DATE;
+---------------+--------------+
| USER()
| CURRENT_DATE |
+---------------+--------------+
| jon@localhost | 2005-07-11
|
+---------------+--------------+

In this example, notice how the prompt changes from mysql> to -> after you enter the first line of a
multiple-line query. This is how mysql indicates that it has not yet seen a complete statement and is
waiting for the rest. The prompt is your friend, because it provides valuable feedback. If you use that
feedback, you can always be aware of what mysql is waiting for.
If you decide you do not want to execute a query that you are in the process of entering, cancel it by
typing \c:
mysql> SELECT
-> USER()
-> \c
mysql>

Here, too, notice the prompt. It switches back to mysql> after you type \c, providing feedback to
indicate that mysql is ready for a new query.
The following table shows each of the prompts you may see and summarizes what they mean about
the state that mysql is in.
Prompt

Meaning

mysql>

Ready for new query

->

Waiting for next line of multiple-line query

'>

Waiting for next line, waiting for completion of a string that began with a single quote (“'”)

">

Waiting for next line, waiting for completion of a string that began with a double quote (“"”)

`>

Waiting for next line, waiting for completion of an identifier that began with a backtick (“`”)

/*>

Waiting for next line, waiting for completion of a comment that began with /*

In the MySQL 5.0 series, the /*> prompt was implemented in MySQL 5.0.6.
Multiple-line statements commonly occur by accident when you intend to issue a query on a single line,
but forget the terminating semicolon. In this case, mysql waits for more input:
mysql> SELECT USER()
->

If this happens to you (you think you've entered a statement but the only response is a -> prompt),
most likely mysql is waiting for the semicolon. If you don't notice what the prompt is telling you, you
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating and Using a Database

might sit there for a while before realizing what you need to do. Enter a semicolon to complete the
statement, and mysql executes it:
mysql> SELECT USER()
-> ;
+---------------+
| USER()
|
+---------------+
| jon@localhost |
+---------------+

The '> and "> prompts occur during string collection (another way of saying that MySQL is waiting for
completion of a string). In MySQL, you can write strings surrounded by either “'” or “"” characters (for
example, 'hello' or "goodbye"), and mysql lets you enter strings that span multiple lines. When
you see a '> or "> prompt, it means that you have 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. This
often indicates that you have inadvertently left out a quote character. For example:
mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
'>

If you enter this SELECT statement, then press Enter and wait for the result, nothing happens. Instead
of wondering why this query takes so long, notice the clue provided by the '> prompt. It tells you that
mysql expects to see the rest of an unterminated string. (Do you see the error in the statement? The
string 'Smith is missing the second single quotation mark.)
At this point, what do you do? The simplest thing is to cancel the query. However, you cannot just type
\c in this case, because mysql interprets it as part of the string that it is collecting. Instead, enter the
closing quote character (so mysql knows you've finished the string), then type \c:
mysql> SELECT * FROM my_table WHERE name = 'Smith AND age < 30;
'> '\c
mysql>

The prompt changes back to mysql>, indicating that mysql is ready for a new query.
The `> prompt is similar to the '> and "> prompts, but indicates that you have begun but not
completed a backtick-quoted identifier.
It is important to know what the '>, ">, and `> prompts signify, because if you mistakenly enter
an unterminated string, any further lines you type appear to be ignored by mysql—including a line
containing QUIT. This can be quite confusing, especially if you do not know that you need to supply the
terminating quote before you can cancel the current query.

3.3 Creating and Using a Database
Once you know how to enter SQL statements, you are ready to access a database.
Suppose that you have several pets in your home (your menagerie) and you would 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 perform the following
operations:
• Create a database
• Create a table
• Load data into the table
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating and Selecting a Database

• Retrieve data from the table in various ways
• Use multiple tables
The menagerie database is simple (deliberately), but it is not difficult to think of real-world situations
in which a similar type of database might be used. For example, a database like this could be used by
a farmer to keep track of livestock, or by a veterinarian to keep track of patient records. A menagerie
distribution containing some of the queries and sample data used in the following sections can be
obtained from the MySQL Web site. It is available in both compressed tar file and Zip formats at http://
dev.mysql.com/doc/.
Use the SHOW statement to find out what databases currently exist on the server:
mysql> SHOW DATABASES;
+----------+
| Database |
+----------+
| mysql
|
| test
|
| tmp
|
+----------+

The mysql database describes user access privileges. The test database often is available as a
workspace for users to try things out.
The list of databases displayed by the statement may be different on your machine; SHOW DATABASES
does not show databases that you have no privileges for if you do not have the SHOW DATABASES
privilege. See Section 13.7.5.11, “SHOW DATABASES Syntax”.
If the test database exists, try to access it:
mysql> USE test
Database changed

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 statement like this:
mysql> GRANT ALL ON menagerie.* TO 'your_mysql_name'@'your_client_host';

where your_mysql_name is the MySQL user name 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. However, for a variety of
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating a Table

reasons, the recommended best practice is always to use the same lettercase that was used when the
database was created.)
Note
If you get an error such as ERROR 1044 (42000): Access denied
for user 'micah'@'localhost' to database 'menagerie' when
attempting to create a database, this means that your user account does not
have the necessary privileges to do so. Discuss this with the administrator or
see Section 6.2, “The MySQL Access Privilege System”.
Creating a database does not select it for use; you must do that explicitly. To make menagerie the
current database, use this statement:
mysql> USE menagerie
Database changed

Your database needs to be created only once, but you must select it for use each time you begin a
mysql session. You can do this by issuing a USE statement as shown in the example. Alternatively,
you can select the database on the command line when you invoke mysql. Just specify its name after
any connection parameters that you might need to provide. For example:
shell> mysql -h host -u user -p menagerie
Enter password: ********

Important
menagerie in the command just shown is not your password. 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.
Note
You can see at any time which database is currently selected using SELECT
DATABASE().

3.3.2 Creating a Table
Creating the database is the easy part, but at this point it is empty, as SHOW TABLES tells you:
mysql> SHOW TABLES;
Empty set (0.00 sec)

The harder part is deciding what the structure of your database should be: what tables you need and
what columns should be in each of them.
You 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 is 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 is better
to store a fixed value such as date of birth. Then, whenever you need age, you can calculate it as
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Loading Data into a Table

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 need to send out birthday greetings in
the current week or month, 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: name, owner, species, sex, birth, and death.
Use a CREATE TABLE statement to specify the layout of your table:
mysql> CREATE TABLE pet (name VARCHAR(20), owner VARCHAR(20),
-> species VARCHAR(20), sex CHAR(1), birth DATE, death DATE);

VARCHAR is a good choice for the name, owner, and species columns because the column values
vary in length. The lengths in those column definitions need not all be the same, and need not be 20.
You can normally pick any length from 1 to 65535, whatever seems most reasonable to you.
Note
Prior to MySQL 5.0.3, the upper limit was 255.) 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 is simplest to use the single characters 'm' and 'f'.
The use of the DATE data type for the birth and death columns is a fairly obvious choice.
Once you have created a table, SHOW TABLES should produce some output:
mysql> SHOW TABLES;
+---------------------+
| Tables in menagerie |
+---------------------+
| pet
|
+---------------------+

To verify that your table was created the way you expected, use a DESCRIBE statement:
mysql> DESCRIBE pet;
+---------+-------------+------+-----+---------+-------+
| Field
| Type
| Null | Key | Default | Extra |
+---------+-------------+------+-----+---------+-------+
| name
| varchar(20) | YES |
| NULL
|
|
| owner
| varchar(20) | YES |
| NULL
|
|
| species | varchar(20) | YES |
| NULL
|
|
| sex
| char(1)
| YES |
| NULL
|
|
| birth
| date
| YES |
| NULL
|
|
| death
| date
| YES |
| NULL
|
|
+---------+-------------+------+-----+---------+-------+

You can use DESCRIBE any time, for example, if you forget the names of the columns in your table or
what types they have.
For more information about MySQL data types, see Chapter 11, Data Types.

3.3.3 Loading Data into a Table
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

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

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

Chirpy

Gwen

bird

f

1998-09-11

Whistler

Gwen

bird

Slim

Benny

snake

death

1995-07-29

1997-12-09
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):
Whistler

Gwen

bird

\N

1997-12-09

\N

To load the text file pet.txt into the pet table, use this statement:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet;

If you created the file on Windows with an editor that uses \r\n as a line terminator, you should use
this statement instead:
mysql> LOAD DATA LOCAL INFILE '/path/pet.txt' INTO TABLE pet
-> LINES TERMINATED BY '\r\n';

(On an Apple machine running OS X, you would likely want to use LINES TERMINATED BY '\r'.)
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 6.1.6, “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:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

mysql> INSERT INTO pet
-> VALUES ('Puffball','Diane','hamster','f','1999-03-30',NULL);

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 is present, conditions_to_satisfy specifies one or more 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 data set. 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 at least two ways to fix this:
• Edit the file pet.txt to correct the error, then empty the table and reload it using DELETE and LOAD
DATA:
mysql> DELETE FROM pet;
mysql> LOAD DATA LOCAL INFILE 'pet.txt' INTO TABLE pet;

However, if you do this, you must also re-enter the record for Puffball.
• Fix only the erroneous record with an UPDATE statement:
mysql> UPDATE pet SET birth = '1989-08-31' WHERE name = 'Bowser';

The UPDATE changes only the record in question and does not require you to reload the table.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a 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 as 1989, not 1979.
String comparisons normally are case-insensitive, so you can specify the name as 'bowser',
'BOWSER', and so forth. The query result is the same.
You can specify conditions on any column, not just name. For example, if you want to know which
animals were born during or 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 is 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 |
+-------+--------+---------+------+------------+-------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 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 do not want to see entire rows from your table, just name the columns in which you are
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 |
+--------+

Notice that the query simply retrieves the owner column 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
|
+--------+---------+------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 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 is often easier to examine query output when the rows are sorted in some meaningful way. To
sort a result, use an ORDER BY clause.
Here are animal birthdays, sorted by date:
mysql> SELECT name, birth FROM pet ORDER BY birth;
+----------+------------+
| name
| birth
|
+----------+------------+
| Buffy
| 1989-05-13 |
| Bowser
| 1989-08-31 |
| Fang
| 1990-08-27 |
| Fluffy
| 1993-02-04 |
| Claws
| 1994-03-17 |
| Slim
| 1996-04-29 |
| Whistler | 1997-12-09 |
| Chirpy
| 1998-09-11 |
| Puffball | 1999-03-30 |
+----------+------------+

On character type columns, sorting—like all other comparison operations—is normally performed in a
case-insensitive fashion. This means that the order is undefined for columns that are identical except
for their case. You can force a case-sensitive sort for a column by using BINARY like so: 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 different 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 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 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 |
+----------+---------+------------+

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, use the TIMESTAMPDIFF() function. Its
arguments are the unit in which you want the result expressed, and the two date for which to take the
difference. The following query shows, for each pet, the birth date, the current date, and the age in
years. An alias (age) is used to make the final output column label more meaningful.
mysql> SELECT name, birth, CURDATE(),
-> TIMESTAMPDIFF(YEAR,birth,CURDATE()) 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 |
+----------+------------+------------+------+

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(),
-> TIMESTAMPDIFF(YEAR,birth,CURDATE()) 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(),
-> TIMESTAMPDIFF(YEAR,birth,CURDATE()) AS age
-> FROM pet ORDER BY age;
+----------+------------+------------+------+
| name
| birth
| CURDATE() | age |
+----------+------------+------------+------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 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,
-> TIMESTAMPDIFF(YEAR,birth,death) 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 functions for extracting parts of dates, 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 also simple. Suppose that the current month is
April. Then the month value is 4 and you can 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 cannot merely 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 write the query so that it works no matter what the current month is, so that you do not have to
use the number for a particular month. DATE_ADD() enables you to add a time interval to a given date.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

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 the month value to 0 if it is currently 12:
mysql> SELECT name, birth FROM pet
-> WHERE MONTH(birth) = MOD(MONTH(CURDATE()), 12) + 1;

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 “a missing
unknown value” and it is treated somewhat differently from other values.
To test for NULL, use the IS NULL and IS NOT NULL operators, as shown here:
mysql> SELECT 1 IS NULL, 1 IS NOT NULL;
+-----------+---------------+
| 1 IS NULL | 1 IS NOT NULL |
+-----------+---------------+
|
0 |
1 |
+-----------+---------------+

You cannot use arithmetic comparison operators such as =, <, or <> to test for NULL. 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 |
+----------+-----------+----------+----------+

Because the result of any arithmetic comparison with NULL is also NULL, you cannot obtain any
meaningful results from such comparisons.
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.
A common error when working with NULL is to assume that it is not possible to insert a zero or an
empty string into a column defined as NOT NULL, but this is not the case. These are in fact values,
whereas NULL means “not having a value.” You can test this easily enough by using IS [NOT] NULL
as shown:
mysql> SELECT 0 IS NULL, 0 IS NOT NULL, '' IS NULL, '' IS NOT NULL;
+-----------+---------------+------------+----------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 0 IS NULL | 0 IS NOT NULL | '' IS NULL | '' IS NOT NULL |
+-----------+---------------+------------+----------------+
|
0 |
1 |
0 |
1 |
+-----------+---------------+------------+----------------+

Thus it is entirely possible to insert a zero or empty string into a NOT NULL column, as these are in fact
NOT NULL. See Section B.5.4.3, “Problems with NULL Values”.

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 enables you to use “_” to match any single character and “%” to match an
arbitrary number of characters (including zero characters). In MySQL, SQL patterns are caseinsensitive by default. Some examples are shown here. 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).
The following list describes some characteristics of extended regular expressions:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

• “.” 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 succeeds if the pattern matches anywhere in the value being tested. (This
differs from a LIKE pattern match, which succeeds only if the pattern matches the entire value.)
• To 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 |
+--------+--------+---------+------+------------+------------+

If you really want to force a REGEXP comparison to be case sensitive, use the BINARY keyword to
make one of the strings a binary string. This query matches only lowercase “b” at the beginning of a
name:
mysql> SELECT * FROM pet WHERE name REGEXP BINARY '^b';

To find names ending with “fy”, use “$” to match the end of the name:
mysql> SELECT * FROM pet WHERE name REGEXP 'fy$';
+--------+--------+---------+------+------------+-------+
| name
| owner | species | sex | birth
| death |
+--------+--------+---------+------+------------+-------+
| Fluffy | Harold | cat
| f
| 1993-02-04 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+--------+--------+---------+------+------------+-------+

To find names containing a “w”, use this query:
mysql> SELECT * FROM pet WHERE name REGEXP 'w';
+----------+-------+---------+------+------------+------------+
| name
| owner | species | sex | birth
| death
|
+----------+-------+---------+------+------------+------------+
| Claws
| Gwen | cat
| m
| 1994-03-17 | NULL
|
| Bowser
| Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL
|
+----------+-------+---------+------+------------+------------+

Because a regular expression pattern matches if it occurs anywhere in the value, it is not necessary in
the previous query to put a wildcard on either side of the pattern to get it to match the entire value like it
would be if you used an SQL pattern.
To find names containing exactly five characters, use “^” and “$” to match the beginning and end of the
name, and five instances of “.” in between:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

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 |
+-------+--------+---------+------+------------+-------+

Section 12.5.2, “Regular Expressions”, provides more information about the syntax for regular
expressions.

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 |
+--------+----------+

The preceding query uses GROUP BY to group all records for each owner. The use of COUNT()
in conjunction with GROUP BY is useful for characterizing your data under various groupings. 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 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

| 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 animals whose sex is known:
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 |
+---------+------+----------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

If you name columns to select in addition to the COUNT() value, a GROUP BY clause should be present
that names those same columns. Otherwise, the following occurs:
• If the ONLY_FULL_GROUP_BY SQL mode is enabled, an error occurs:
mysql> SET sql_mode = 'ONLY_FULL_GROUP_BY';
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT owner, COUNT(*) FROM pet;
ERROR 1140 (42000): Mixing of GROUP columns (MIN(),MAX(),COUNT()...)
with no GROUP columns is illegal if there is no GROUP BY clause

• If ONLY_FULL_GROUP_BY is not enabled, the query is processed by treating all rows as a single
group, but the value selected for each named column is indeterminate. The server is free to select
the value from any row:
mysql> SET sql_mode = '';
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT owner, COUNT(*) FROM pet;
+--------+----------+
| owner | COUNT(*) |
+--------+----------+
| Harold |
8 |
+--------+----------+
1 row in set (0.00 sec)

See also Section 12.16.3, “MySQL Handling of GROUP BY”.

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 following information:
• The pet name so that you know which animal each event pertains to.
• A date so that 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 is easiest to load the initial records by creating a tab-delimited text file
containing the following 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

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Retrieving Information from a Table

name

date

type

remark

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 have learned from the queries that you have 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) remark
-> FROM pet INNER JOIN event
->
ON pet.name = event.name
-> WHERE event.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 joins 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 uses ON clause to match up records in the two tables based on the name values.
The query uses an INNER JOIN to combine the tables. An INNER JOIN permits rows from either
table to appear in the result if and only if both tables meet the conditions specified in the ON clause.
In this example, the ON clause specifies that the name column in the pet table must match the name
column in the event table. If a name appears in one table but not the other, the row will not appear
in the result because the condition in the ON clause fails.
• 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 INNER JOIN pet AS p2
->
ON p1.species = p2.species AND p1.sex = 'f' AND p2.sex = 'm';
+--------+------+--------+------+---------+
| name
| sex | name
| sex | species |
+--------+------+--------+------+---------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Getting Information About Databases and Tables

| 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 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 previously seen SHOW DATABASES, which lists the databases managed by the server. To
find out which database is currently selected, use the DATABASE() function:
mysql> SELECT DATABASE();
+------------+
| DATABASE() |
+------------+
| menagerie |
+------------+

If you have not yet selected any database, the result is NULL.
To find out what tables the default database contains (for example, when you are not sure about the
name of a table), use this statement:
mysql> SHOW TABLES;
+---------------------+
| Tables_in_menagerie |
+---------------------+
| event
|
| pet
|
+---------------------+

The name of the column in the output produced by this statement is always Tables_in_db_name,
where db_name is the name of the database. See Section 13.7.5.34, “SHOW TABLES Syntax”, for
more information.
If you want to find out about the structure of a table, the DESCRIBE statement 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. Extra displays special information about columns: If a column was created
with the AUTO_INCREMENT option, the value will be auto_increment rather than empty.
DESC is a short form of DESCRIBE. See Section 13.8.1, “DESCRIBE Syntax”, for more information.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using mysql in Batch Mode

You can obtain the CREATE TABLE statement necessary to create an existing table using the SHOW
CREATE TABLE statement. See Section 13.7.5.9, “SHOW CREATE TABLE Syntax”.
If you have indexes on a table, SHOW INDEX FROM tbl_name produces information about them. See
Section 13.7.5.18, “SHOW INDEX Syntax”, for more about this statement.

3.5 Using mysql in Batch Mode
In the previous sections, you used mysql interactively to enter statements and view the results. You
can also run mysql in batch mode. To do this, put the statements you want to run in a file, then tell
mysql to read its input from the file:
shell> mysql < batch-file

If you are running mysql under Windows and have some special characters in the file that cause
problems, you can do this:
C:\> mysql -e "source batch-file"

If you need to specify connection parameters on the command line, the command might look like this:
shell> mysql -h host -u user -p < batch-file
Enter password: ********

When you use mysql this way, you are creating a script file, then executing the script.
If you want the script to continue even if some of the statements in it produce errors, you should use
the --force command-line option.
Why use a script? Here are a few reasons:
• If you run a query repeatedly (say, every day or every week), making it a script enables 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
statements or multiple-statement sequences. If you make a mistake, you don't have to retype
everything. Just edit your script to correct the error, then tell 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 that they can also run the statements.
• Some situations do not allow for interactive use, for example, when you run a query from a cron job.
In this case, you must use batch mode.
The default output format is different (more concise) when you run mysql in batch mode than when
you use it interactively. For example, the output of SELECT DISTINCT species FROM pet looks
like this when mysql is run interactively:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Examples of Common Queries

+---------+
| 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 statements that are executed, use mysql -v.
You can also use scripts from the mysql prompt by using the source command or \. command:
mysql> source filename;
mysql> \. filename

See Section 4.5.1.5, “Executing SQL Statements from a Text File”, for more information.

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 mysql and select a database:
shell> mysql your-database-name

(In most MySQL installations, you can use the database named test).
You can create and populate the example table with these statements:
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));
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:
SELECT * FROM shop;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0001 | A
| 3.45 |
|
0001 | B
| 3.99 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Maximum Value for a Column

|
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 is 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
Task: Find the number, dealer, and price of the most expensive article.
This is easily done with a subquery:
SELECT article, dealer, price
FROM
shop
WHERE price=(SELECT MAX(price) FROM shop);
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0004 | D
| 19.95 |
+---------+--------+-------+

Other solutions are to use a LEFT JOIN or to sort all rows descending by price and get only the first
row using the MySQL-specific LIMIT clause:
SELECT s1.article, s1.dealer, s1.price
FROM shop s1
LEFT JOIN shop s2 ON s1.price < s2.price
WHERE s2.article IS NULL;
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
Task: Find the highest price per article.
SELECT article, MAX(price) AS price
FROM
shop
GROUP BY article;
+---------+-------+
| article | price |
+---------+-------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Rows Holding the Group-wise Maximum of a Certain Column

|
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 Column
Task: For each article, find the dealer or dealers with the most expensive price.
This problem can be solved with a subquery like this one:
SELECT article, dealer, price
FROM
shop s1
WHERE price=(SELECT MAX(s2.price)
FROM shop s2
WHERE s1.article = s2.article);
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
0001 | B
| 3.99 |
|
0002 | A
| 10.99 |
|
0003 | C
| 1.69 |
|
0004 | D
| 19.95 |
+---------+--------+-------+

The preceding example uses a correlated subquery, which can be inefficient (see Section 13.2.9.7,
“Correlated Subqueries”). Other possibilities for solving the problem are to use an uncorrelated
subquery in the FROM clause or a LEFT JOIN.
Uncorrelated subquery:
SELECT s1.article, dealer, s1.price
FROM shop s1
JOIN (
SELECT article, MAX(price) AS price
FROM shop
GROUP BY article) AS s2
ON s1.article = s2.article AND s1.price = s2.price;

LEFT JOIN:
SELECT s1.article, s1.dealer, s1.price
FROM shop s1
LEFT JOIN shop s2 ON s1.article = s2.article AND s1.price < s2.price
WHERE s2.article IS NULL;

The LEFT JOIN works on the basis that when s1.price is at its maximum value, there is no
s2.price with a greater value and the s2 rows values will be NULL. See Section 13.2.8.2, “JOIN
Syntax”.

3.6.5 Using User-Defined Variables
You can employ MySQL user variables to remember results without having to store them in temporary
variables in the client. (See Section 9.4, “User-Defined Variables”.)
For example, to find the articles with the highest and lowest price you can do this:
mysql> SELECT @min_price:=MIN(price),@max_price:=MAX(price) FROM shop;
mysql> SELECT * FROM shop WHERE price=@min_price OR price=@max_price;
+---------+--------+-------+
| article | dealer | price |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Foreign Keys

+---------+--------+-------+
|
0003 | D
| 1.25 |
|
0004 | D
| 19.95 |
+---------+--------+-------+

Note
It is also possible to store the name of a database object such as a table or a
column in a user variable and then to use this variable in an SQL statement;
however, this requires the use of a prepared statement. See Section 13.5, “SQL
Syntax for Prepared Statements”, for more information.

3.6.6 Using Foreign Keys
In MySQL, InnoDB tables support checking of foreign key constraints. See Section 14.2, “The InnoDB
Storage Engine”, and Section 1.8.2.4, “Foreign Key Differences”.
A foreign key constraint is not required merely to join two tables. For storage engines other than
InnoDB, it is possible when defining a column to use a REFERENCES tbl_name(col_name) clause,
which has no actual effect, and serves only as a memo or comment to you that the column which
you are currently defining is intended to refer to a column in another table. It is extremely important to
realize when using this syntax that:
• MySQL does not perform any sort of CHECK to make sure that col_name actually exists in
tbl_name (or even that tbl_name itself exists).
• MySQL does not perform any sort of action on tbl_name such as deleting rows in response to
actions taken on rows in the table which you are defining; in other words, this syntax induces no
ON DELETE or ON UPDATE behavior whatsoever. (Although you can write an ON DELETE or ON
UPDATE clause as part of the REFERENCES clause, it is also ignored.)
• This syntax creates a column; it does not create any sort of index or key.
You can use a column so created as a join column, as shown here:
CREATE TABLE person (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
name CHAR(60) NOT NULL,
PRIMARY KEY (id)
);
CREATE TABLE shirt (
id SMALLINT UNSIGNED NOT NULL AUTO_INCREMENT,
style ENUM('t-shirt', 'polo', 'dress') NOT NULL,
color ENUM('red', 'blue', 'orange', 'white', 'black') NOT NULL,
owner SMALLINT UNSIGNED NOT NULL REFERENCES person(id),
PRIMARY KEY (id)
);
INSERT INTO person VALUES (NULL, 'Antonio Paz');
SELECT @last := LAST_INSERT_ID();
INSERT
(NULL,
(NULL,
(NULL,

INTO shirt VALUES
'polo', 'blue', @last),
'dress', 'white', @last),
't-shirt', 'blue', @last);

INSERT INTO person VALUES (NULL, 'Lilliana Angelovska');
SELECT @last := LAST_INSERT_ID();
INSERT
(NULL,
(NULL,
(NULL,

This
documentation
is for an
older version.
If you're

INTO shirt VALUES
'dress', 'orange', @last),
'polo', 'red', @last),
'dress', 'blue', @last),

This
documentation
is for an
older version.
If you're

Searching on Two Keys

(NULL, 't-shirt', 'white', @last);
SELECT * FROM person;
+----+---------------------+
| id | name
|
+----+---------------------+
| 1 | Antonio Paz
|
| 2 | Lilliana Angelovska |
+----+---------------------+
SELECT * FROM shirt;
+----+---------+--------+-------+
| id | style
| color | owner |
+----+---------+--------+-------+
| 1 | polo
| blue
|
1 |
| 2 | dress
| white |
1 |
| 3 | t-shirt | blue
|
1 |
| 4 | dress
| orange |
2 |
| 5 | polo
| red
|
2 |
| 6 | dress
| blue
|
2 |
| 7 | t-shirt | white |
2 |
+----+---------+--------+-------+

SELECT s.* FROM person p INNER JOIN shirt s
ON s.owner = p.id
WHERE p.name LIKE 'Lilliana%'
AND s.color <> 'white';
+----+-------+--------+-------+
| id | style | color | owner |
+----+-------+--------+-------+
| 4 | dress | orange |
2 |
| 5 | polo | red
|
2 |
| 6 | dress | blue
|
2 |
+----+-------+--------+-------+

When used in this fashion, the REFERENCES clause is not displayed in the output of SHOW CREATE
TABLE or DESCRIBE:
SHOW CREATE TABLE shirt\G
*************************** 1. row ***************************
Table: shirt
Create Table: CREATE TABLE `shirt` (
`id` smallint(5) unsigned NOT NULL auto_increment,
`style` enum('t-shirt','polo','dress') NOT NULL,
`color` enum('red','blue','orange','white','black') NOT NULL,
`owner` smallint(5) unsigned NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1

The use of REFERENCES in this way as a comment or “reminder” in a column definition works with both
MyISAM and BerkeleyDB tables.

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 8.2.1.4, “Index Merge Optimization”.
You can also solve the problem efficiently by using a UNION that combines the output of two separate
SELECT statements. See Section 13.2.8.3, “UNION Syntax”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Calculating Visits Per Day

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';

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< ALTER TABLE tbl AUTO_INCREMENT = 100;

More information about AUTO_INCREMENT is available here:
• How to assign the AUTO_INCREMENT attribute to a column: Section 13.1.10, “CREATE TABLE
Syntax”, and Section 13.1.4, “ALTER TABLE Syntax”.
• How AUTO_INCREMENT behaves depending on the NO_AUTO_VALUE_ON_ZERO SQL mode:
Section 5.1.7, “Server SQL Modes”.
• How to use the LAST_INSERT_ID() function to find the row that contains the most recent
AUTO_INCREMENT value: Section 12.13, “Information Functions”.
• Setting the AUTO_INCREMENT value to be used: Section 5.1.4, “Server System Variables”.
• AUTO_INCREMENT and replication: Section 16.4.1.1, “Replication and AUTO_INCREMENT”.
• Server-system variables related to AUTO_INCREMENT (auto_increment_increment and
auto_increment_offset) that can be used for replication: Section 5.1.4, “Server System
Variables”.
• AUTO_INCREMENT and InnoDB tables: Section 14.2.3.3, “AUTO_INCREMENT Handling in InnoDB”.

3.7 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.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 4 MySQL Programs
Table of Contents
4.1 Overview of MySQL Programs .............................................................................................
4.2 Using MySQL Programs ......................................................................................................
4.2.1 Invoking MySQL Programs .......................................................................................
4.2.2 Connecting to the MySQL Server ..............................................................................
4.2.3 Specifying Program Options ......................................................................................
4.2.4 Using Options on the Command Line ........................................................................
4.2.5 Program Option Modifiers .........................................................................................
4.2.6 Using Option Files ....................................................................................................
4.2.7 Command-Line Options that Affect Option-File Handling .............................................
4.2.8 Using Options to Set Program Variables ....................................................................
4.2.9 Option Defaults, Options Expecting Values, and the = Sign ........................................
4.2.10 Setting Environment Variables .................................................................................
4.3 MySQL Server and Server-Startup Programs .......................................................................
4.3.1 mysqld — The MySQL Server .................................................................................
4.3.2 mysqld_safe — MySQL Server Startup Script .........................................................
4.3.3 mysql.server — MySQL Server Startup Script .......................................................
4.3.4 mysqld_multi — Manage Multiple MySQL Servers .................................................
4.4 MySQL Installation-Related Programs ..................................................................................
4.4.1 comp_err — Compile MySQL Error Message File ....................................................
4.4.2 make_win_bin_dist — Package MySQL Distribution as Zip Archive ........................
4.4.3 make_win_src_distribution — Create Source Distribution for Windows ..............
4.4.4 mysqlbug — Generate Bug Report ..........................................................................
4.4.5 mysql_fix_privilege_tables — Upgrade MySQL System Tables .......................
4.4.6 mysql_install_db — Initialize MySQL Data Directory ............................................
4.4.7 mysql_secure_installation — Improve MySQL Installation Security ...................
4.4.8 mysql_tzinfo_to_sql — Load the Time Zone Tables ...........................................
4.4.9 mysql_upgrade — Check Tables for MySQL Upgrade .............................................
4.5 MySQL Client Programs ......................................................................................................
4.5.1 mysql — The MySQL Command-Line Tool ...............................................................
4.5.2 mysqladmin — Client for Administering a MySQL Server ..........................................
4.5.3 mysqlcheck — A Table Maintenance Program ........................................................
4.5.4 mysqldump — A Database Backup Program ............................................................
4.5.5 mysqlimport — A Data Import Program .................................................................
4.5.6 mysqlshow — Display Database, Table, and Column Information ..............................
4.6 MySQL Administrative and Utility Programs ..........................................................................
4.6.1 innochecksum — Offline InnoDB File Checksum Utility ............................................
4.6.2 myisam_ftdump — Display Full-Text Index information .............................................
4.6.3 myisamchk — MyISAM Table-Maintenance Utility .....................................................
4.6.4 myisamlog — Display MyISAM Log File Contents ....................................................
4.6.5 myisampack — Generate Compressed, Read-Only MyISAM Tables ..........................
4.6.6 mysqlaccess — Client for Checking Access Privileges .............................................
4.6.7 mysqlbinlog — Utility for Processing Binary Log Files ............................................
4.6.8 mysqldumpslow — Summarize Slow Query Log Files ..............................................
4.6.9 mysqlhotcopy — A Database Backup Program .......................................................
4.6.10 mysqlmanager — The MySQL Instance Manager ...................................................
4.6.11 mysql_convert_table_format — Convert Tables to Use a Given Storage
Engine ..............................................................................................................................
4.6.12 mysql_explain_log — Use EXPLAIN on Statements in Query Log .......................
4.6.13 mysql_find_rows — Extract SQL Statements from Files .......................................
4.6.14 mysql_fix_extensions — Normalize Table File Name Extensions .......................
4.6.15 mysql_setpermission — Interactively Set Permissions in Grant Tables ................
4.6.16 mysql_tableinfo — Generate Database Metadata ..............................................
This
documentation
is for an
older version.
If you're

230
235
235
236
239
240
241
242
246
247
248
251
252
252
252
256
258
263
263
264
265
265
266
267
268
269
269
273
273
293
299
305
321
325
329
329
329
331
347
348
354
356
365
366
369
379
380
381
382
382
383

This
documentation
is for an
older version.
If you're

Overview of MySQL Programs

4.6.17 mysql_waitpid — Kill Process and Wait for Its Termination ...................................
4.6.18 mysql_zap — Kill Processes That Match a Pattern .................................................
4.7 MySQL Program Development Utilities .................................................................................
4.7.1 msql2mysql — Convert mSQL Programs for Use with MySQL ..................................
4.7.2 mysql_config — Display Options for Compiling Clients ...........................................
4.7.3 my_print_defaults — Display Options from Option Files ......................................
4.7.4 resolve_stack_dump — Resolve Numeric Stack Trace Dump to Symbols ...............
4.8 Miscellaneous Programs ......................................................................................................
4.8.1 perror — Explain Error Codes ................................................................................
4.8.2 replace — A String-Replacement Utility ..................................................................
4.8.3 resolveip — Resolve Host name to IP Address or Vice Versa .................................

385
385
386
386
386
387
388
389
389
390
390

This chapter provides a brief overview of the MySQL command-line programs provided by Oracle
Corporation. It also discusses the general syntax for specifying options when you run these programs.
Most programs have options that are specific to their own operation, but the option syntax is similar for
all of them. Finally, the chapter provides more detailed descriptions of individual programs, including
which options they recognize.

4.1 Overview of MySQL Programs
There are many different programs in a MySQL installation. This section provides a brief overview of
them. Later sections provide a more detailed description of each one, with the exception of MySQL
Cluster programs. Each program's description indicates its invocation syntax and the options that it
supports. Chapter 17, MySQL Cluster, describes programs specific to MySQL Cluster.
Most MySQL distributions include all of these programs, except for those programs that are platformspecific. (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 client programs, and
so forth. If you appear to be missing one or more programs, see Chapter 2, Installing and Upgrading
MySQL, for information on types of distributions and what they contain. It may be that you have a
distribution that does not include all programs and you need to install an additional package.
Each MySQL program takes many different options. Most programs provide a --help option that you
can use to get a description of the program's different options. For example, try mysql --help.
You can override default option values for MySQL programs by specifying options on the command
line or in an option file. See Section 4.2, “Using MySQL Programs”, for general information on invoking
programs and specifying program options.
The MySQL server, mysqld, is the main program that does most of the work in a MySQL installation.
The server is accompanied by several related scripts that assist you in starting and stopping the server:
• mysqld
The SQL daemon (that is, the MySQL server). To use client programs, mysqld must be running,
because clients gain access to databases by connecting to the server. See Section 4.3.1, “mysqld
— The MySQL Server”.
• mysqld_safe
A server startup script. mysqld_safe attempts to start mysqld. See Section 4.3.2, “mysqld_safe
— MySQL Server Startup Script”.
• mysql.server
A server startup script. This script is used on systems that use System V-style run directories
containing scripts that start system services for particular run levels. It invokes mysqld_safe to start
the MySQL server. See Section 4.3.3, “mysql.server — MySQL Server Startup Script”.
• mysqld_multi
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Overview of MySQL Programs

A server startup script that can start or stop multiple servers installed on the system. See
Section 4.3.4, “mysqld_multi — Manage Multiple MySQL Servers”. As of MySQL 5.0.3 (Unix-like
systems) or 5.0.13 (Windows), an alternative to mysqld_multi is mysqlmanager, the MySQL
Instance Manager. See Section 4.6.10, “mysqlmanager — The MySQL Instance Manager”.
There are several programs that perform setup operations during MySQL installation or upgrading:
• comp_err
This program is used during the MySQL build/installation process. It compiles error message files
from the error source files. See Section 4.4.1, “comp_err — Compile MySQL Error Message File”.
• 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.
• make_win_bin_dist
This program is used on Windows. It packages a MySQL distribution for installation after the
source distribution has been built. See Section 4.4.2, “make_win_bin_dist — Package MySQL
Distribution as Zip Archive”.
• mysql_fix_privilege_tables
This program is used after a MySQL upgrade operation. It updates the grant tables with
any changes that have been made in newer versions of MySQL. See Section 4.4.5,
“mysql_fix_privilege_tables — Upgrade MySQL System Tables”.
Note: As of MySQL 5.0.19, this program has been superseded by mysql_upgrade and should no
longer be used.
• mysql_install_db
This program initializes the MySQL data directory, creates the mysql database, and initializes its
grant tables with default privileges. It is usually executed only once, when first installing MySQL
on a system. See Section 4.4.6, “mysql_install_db — Initialize MySQL Data Directory”, and
Section 2.18, “Postinstallation Setup and Testing”.
• mysql_secure_installation
This program enables you to improve the security of your MySQL installation. See Section 4.4.7,
“mysql_secure_installation — Improve MySQL Installation Security”.
• mysql_tzinfo_to_sql
This program loads the time zone tables in the mysql database using the contents of the
host system zoneinfo database (the set of files describing time zones). See Section 4.4.8,
“mysql_tzinfo_to_sql — Load the Time Zone Tables”.
• mysql_upgrade
This program is used after a MySQL upgrade operation. It checks tables for incompatibilities and
repairs them if necessary, and updates the grant tables with any changes that have been made
in newer versions of MySQL. See Section 4.4.9, “mysql_upgrade — Check Tables for MySQL
Upgrade”.
• make_win_src_distribution
This program is used on Unix or Unix-like systems to create a MySQL source distribution that can be
compiled on Windows. See Section 2.10.8.5, “Creating a Windows Source Package from the Bazaar

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Overview of MySQL Programs

Repository”, and Section 4.4.3, “make_win_src_distribution — Create Source Distribution for
Windows”.
MySQL client programs:
• mysql
The command-line tool for interactively entering SQL statements or executing them from a file in
batch mode. See Section 4.5.1, “mysql — The MySQL Command-Line Tool”.
• mysqladmin
A client that performs administrative operations, such as creating or dropping databases, reloading
the grant tables, flushing tables to disk, and reopening log files. mysqladmin can also be used to
retrieve version, process, and status information from the server. See Section 4.5.2, “mysqladmin
— Client for Administering a MySQL Server”.
• mysqlcheck
A table-maintenance client that checks, repairs, analyzes, and optimizes tables. See Section 4.5.3,
“mysqlcheck — A Table Maintenance Program”.
• mysqldump
A client that dumps a MySQL database into a file as SQL, text, or XML. See Section 4.5.4,
“mysqldump — A Database Backup Program”.
• mysqlimport
A client that imports text files into their respective tables using LOAD DATA INFILE. See
Section 4.5.5, “mysqlimport — A Data Import Program”.
• mysqlshow
A client that displays information about databases, tables, columns, and indexes. See Section 4.5.6,
“mysqlshow — Display Database, Table, and Column Information”.
MySQL administrative and utility programs:
• innochecksum
An offline InnoDB offline file checksum utility. See Section 4.6.1, “innochecksum — Offline InnoDB
File Checksum Utility”.
• myisam_ftdump
A utility that displays information about full-text indexes in MyISAM tables. See Section 4.6.2,
“myisam_ftdump — Display Full-Text Index information”.
• myisamchk
A utility to describe, check, optimize, and repair MyISAM tables. See Section 4.6.3, “myisamchk —
MyISAM Table-Maintenance Utility”.
• myisamlog
A utility that processes the contents of a MyISAM log file. See Section 4.6.4, “myisamlog — Display
MyISAM Log File Contents”.
• myisampack
A utility that compresses MyISAM tables to produce smaller read-only tables. See Section 4.6.5,
“myisampack — Generate Compressed, Read-Only MyISAM Tables”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Overview of MySQL Programs

• mysqlaccess
A script that checks the access privileges for a host name, user name, and database combination.
See Section 4.6.6, “mysqlaccess — Client for Checking Access Privileges”.
• mysqlbinlog
A utility for reading statements from a binary log. The log of executed statements contained in the
binary log files can be used to help recover from a crash. See Section 4.6.7, “mysqlbinlog —
Utility for Processing Binary Log Files”.
• mysqldumpslow
A utility to read and summarize the contents of a slow query log. See Section 4.6.8,
“mysqldumpslow — Summarize Slow Query Log Files”.
• mysqlhotcopy
A utility that quickly makes backups of MyISAM tables while the server is running. See Section 4.6.9,
“mysqlhotcopy — A Database Backup Program”.
• mysqlmanager
The MySQL Instance Manager, a program for monitoring and managing MySQL servers. See
Section 4.6.10, “mysqlmanager — The MySQL Instance Manager”.
Important
MySQL Instance Manager has been deprecated and is removed in MySQL
5.5.
• mysql_convert_table_format
A utility that converts tables in a database to use a given storage engine. See Section 4.6.11,
“mysql_convert_table_format — Convert Tables to Use a Given Storage Engine”.
• mysql_explain_log
A utility that analyzes queries in the MySQL query log using EXPLAIN See Section 4.6.12,
“mysql_explain_log — Use EXPLAIN on Statements in Query Log”.
• mysql_find_rows
A utility that reads files containing SQL statements (such as update logs) and extracts statements
that match a given regular expression. See Section 4.6.13, “mysql_find_rows — Extract SQL
Statements from Files”.
• mysql_fix_extensions
A utility that converts the extensions for MyISAM table files to lowercase. This can be useful
after transferring the files from a system with case-insensitive file names to a system with casesensitive file names. See Section 4.6.14, “mysql_fix_extensions — Normalize Table File Name
Extensions”.
• mysql_setpermission
A utility for interactively setting permissions in the MySQL grant tables. See Section 4.6.15,
“mysql_setpermission — Interactively Set Permissions in Grant Tables”.
• mysql_tableinfo
A utility that generates database metadata. Section 4.6.16, “mysql_tableinfo — Generate
Database Metadata”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Overview of MySQL Programs

• mysql_waitpid
A utility that kills the process with a given process ID. See Section 4.6.17, “mysql_waitpid — Kill
Process and Wait for Its Termination”.
• mysql_zap
A utility that kills processes that match a pattern. See Section 4.6.18, “mysql_zap — Kill Processes
That Match a Pattern”.
MySQL program-development utilities:
• msql2mysql
A shell script that converts mSQL programs to MySQL. It doesn't handle every case, but it gives a
good start when converting. See Section 4.7.1, “msql2mysql — Convert mSQL Programs for Use
with MySQL”.
• mysql_config
A shell script that produces the option values needed when compiling MySQL programs. See
Section 4.7.2, “mysql_config — Display Options for Compiling Clients”.
• my_print_defaults
A utility that shows which options are present in option groups of option files. See Section 4.7.3,
“my_print_defaults — Display Options from Option Files”.
• resolve_stack_dump
A utility program that resolves a numeric stack trace dump to symbols. See Section 4.7.4,
“resolve_stack_dump — Resolve Numeric Stack Trace Dump to Symbols”.
Miscellaneous utilities:
• perror
A utility that displays the meaning of system or MySQL error codes. See Section 4.8.1, “perror —
Explain Error Codes”.
• replace
A utility program that performs string replacement in the input text. See Section 4.8.2, “replace — A
String-Replacement Utility”.
• resolveip
A utility program that resolves a host name to an IP address or vice versa. See Section 4.8.3,
“resolveip — Resolve Host name to IP Address or Vice Versa”.
Oracle Corporation also provides the MySQL Workbench GUI tool, which is used to administer MySQL
servers and databases, to create, execute, and evaluate queries, and to migrate schemas and data
from other relational database management systems for use with MySQL. Additional GUI tools include
MySQL Notifier and MySQL for Excel.
MySQL client programs that communicate with the server using the MySQL client/server library use the
following environment variables.
Environment Variable

Meaning

MYSQL_UNIX_PORT

The default Unix socket file; used for connections to localhost

MYSQL_TCP_PORT

The default port number; used for TCP/IP connections

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using MySQL Programs

Environment Variable

Meaning

MYSQL_PWD

The default password

MYSQL_DEBUG

Debug trace options when debugging

TMPDIR

The directory where temporary tables and files are created

For a full list of environment variables used by MySQL programs, see Section 2.21, “Environment
Variables”.
Use of MYSQL_PWD is insecure. See Section 6.1.2.1, “End-User Guidelines for Password Security”.

4.2 Using MySQL Programs
4.2.1 Invoking MySQL Programs
To invoke a MySQL program from the command line (that is, from your shell or command prompt),
enter the program name followed by any options or other arguments needed to instruct the program
what you want it to do. The following commands show some sample program invocations. “shell>”
represents the prompt for your command interpreter; it is not part of what you type. The particular
prompt you see depends on your command interpreter. Typical prompts are $ for sh or bash, % for
csh or tcsh, and C:\> for the Windows command.com or cmd.exe command interpreters.
shell>
shell>
shell>
shell>

mysql --user=root test
mysqladmin extended-status variables
mysqlshow --help
mysqldump -u root personnel

Arguments that begin with a single or double dash (“-”, “--”) specify program options. Options typically
indicate the type of connection a program should make to the server or affect its operational mode.
Option syntax is described in Section 4.2.3, “Specifying Program Options”.
Nonoption arguments (arguments with no leading dash) provide additional information to the program.
For example, the mysql program interprets the first nonoption argument as a database name, so the
command mysql --user=root test indicates that you want to use the test database.
Later sections that describe individual programs indicate which options a program supports and
describe the meaning of any additional nonoption arguments.
Some options are common to a number of programs. The most frequently used of these are the -host (or -h), --user (or -u), and --password (or -p) options that specify connection parameters.
They indicate the host where the MySQL server is running, and the user name and password of your
MySQL account. All MySQL client programs understand these options; they enable you to specify
which server to connect to and the account to use on that server. Other connection options are --port
(or -P) to specify a TCP/IP port number and --socket (or -S) to specify a Unix socket file on Unix (or
named pipe name on Windows). For more information on options that specify connection options, see
Section 4.2.2, “Connecting to the MySQL Server”.
You may find it necessary to invoke MySQL programs using the path name 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 path name of the bin directory to your PATH environment
variable setting. That enables you to run a program by typing only its name, not its entire path name.
For example, if mysql is installed in /usr/local/mysql/bin, you can run the program by invoking it
as mysql, and it is not necessary to invoke it as /usr/local/mysql/bin/mysql.
Consult the documentation for your command interpreter for instructions on setting your PATH variable.
The syntax for setting environment variables is interpreter-specific. (Some information is given in
Section 4.2.10, “Setting Environment Variables”.) After modifying your PATH setting, open a new
console window on Windows or log in again on Unix so that the setting goes into effect.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connecting to the MySQL Server

4.2.2 Connecting to the MySQL Server
This section describes how to establish a connection to the MySQL server. For additional information if
you are unable to connect, see Section 6.2.7, “Troubleshooting Problems Connecting to MySQL”.
For a client program to be able to connect to the MySQL server, it must use the proper connection
parameters, such as the name of the host where the server is running and the user name and
password of your MySQL account. Each connection parameter has a default value, but you can
override them as necessary using program options specified either on the command line or in an option
file.
The examples here use the mysql client program, but the principles apply to other clients such as
mysqldump, mysqladmin, or mysqlshow.
This command invokes mysql without specifying any connection parameters explicitly:
shell> mysql

Because there are no parameter options, the default values apply:
• The default host name is localhost. On Unix, this has a special meaning, as described later.
• The default user name is ODBC on Windows or your Unix login name on Unix.
• No password is sent if neither -p nor --password is given.
• For mysql, the first nonoption argument is taken as the name of the default database. If there is no
such option, mysql does not select a default database.
To specify the host name and user name explicitly, as well as a password, supply appropriate options
on the command line:
shell> mysql --host=localhost --user=myname --password=mypass mydb
shell> mysql -h localhost -u myname -pmypass mydb

For password options, the password value is optional:
• If you use a -p or --password option and specify the password value, there must be no space
between -p or --password= and the password following it.
• If you use a -p or --password option but do not specify the password value, the client program
prompts you to enter the password. The password is not displayed as you enter it. This is more
secure than giving the password on the command line. Other users on your system may be able to
see a password specified on the command line by executing a command such as ps auxw. See
Section 6.1.2.1, “End-User Guidelines for Password Security”.
As just mentioned, including the password value on the command line can be a security risk. To avoid
this problem, specify the --password or -p option without any following password value:
shell> mysql --host=localhost --user=myname --password mydb
shell> mysql -h localhost -u myname -p mydb

When the password option has no password value, the client program prints a prompt and waits for
you to enter the password. (In these examples, mydb is not interpreted as a password because it is
separated from the preceding password option by a space.)
On some systems, the library routine 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 does not 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.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connecting to the MySQL Server

On Unix, MySQL programs treat the host name localhost specially, in a way that is likely different
from what you expect compared to other network-based programs. For connections to localhost,
MySQL programs attempt to connect to the local server by using a Unix socket file. This occurs even
if a --port or -P option is given to specify a port number. To ensure that the client makes a TCP/IP
connection to the local server, use --host or -h to specify a host name value of 127.0.0.1, or the
IP address or name of the local server. You can also specify the connection protocol explicitly, even for
localhost, by using the --protocol=TCP option. For example:
shell> mysql --host=127.0.0.1
shell> mysql --protocol=TCP

The --protocol option enables you to establish a particular type of connection even when the other
options would normally default to some other protocol.
On Windows, you can force a MySQL client to use a named-pipe connection by specifying the --pipe
or --protocol=PIPE option, or by specifying . (period) as the host name. If named-pipe connections
are not enabled, an error occurs. Use the --socket option to specify the name of the pipe if you do
not want to use the default pipe name.
Connections to remote servers always use TCP/IP. This command connects to the server running on
remote.example.com using the default port number (3306):
shell> mysql --host=remote.example.com

To specify a port number explicitly, use the --port or -P option:
shell> mysql --host=remote.example.com --port=13306

You can specify a port number for connections to a local server, too. However, as indicated previously,
connections to localhost on Unix will use a socket file by default. You will need to force a TCP/IP
connection as already described or any option that specifies a port number will be ignored.
For this command, the program uses a socket file on Unix and the --port option is ignored:
shell> mysql --port=13306 --host=localhost

To cause the port number to be used, invoke the program in either of these ways:
shell> mysql --port=13306 --host=127.0.0.1
shell> mysql --port=13306 --protocol=TCP

The following list summarizes the options that can be used to control how client programs connect to
the server:
• --host=host_name, -h host_name
The host where the server is running. The default value is localhost.
• --password[=pass_val], -p[pass_val]
The password of the MySQL account. As described earlier, the password value is optional, but if
given, there must be no space between -p or --password= and the password following it. The
default is to send no password.
• --pipe, -W
On Windows, connect to the server using a named pipe. The server must be started with the -enable-named-pipe option to enable named-pipe connections.
• --port=port_num, -P port_num
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connecting to the MySQL Server

The port number to use for the connection, for connections made using TCP/IP. The default port
number is 3306.
• --protocol={TCP|SOCKET|PIPE|MEMORY}
This option explicitly specifies a protocol to use for connecting to the server. It is useful when the
other connection parameters normally would cause a protocol to be used other than the one you
want. For example, connections on Unix to localhost are made using a Unix socket file by default:
shell> mysql --host=localhost

To force a TCP/IP connection to be used instead, specify a --protocol option:
shell> mysql --host=localhost --protocol=TCP

The following table shows the permissible --protocol option values and indicates the platforms on
which each value may be used. The values are not case sensitive.
--protocol
Value

Connection Protocol

Permissible Operating
Systems

TCP

TCP/IP connection to local or remote server

All

SOCKET

Unix socket file connection to local server

Unix only

PIPE

Named-pipe connection to local or remote server Windows only

MEMORY

Shared-memory connection to local server

Windows only

• --shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.
• --socket=file_name, -S file_name
On Unix, the name of the Unix socket file to use, for connections made using a named pipe to a local
server. The default Unix socket file name is /tmp/mysql.sock.
On Windows, the name of the named pipe to use, for connections to a local server. The default
Windows pipe name is MySQL. The pipe name is not case sensitive.
The server must be started with the --enable-named-pipe option to enable named-pipe
connections.
• --ssl*
Options that begin with --ssl are used for establishing a secure connection to the server using
SSL, if the server is configured with SSL support. For details, see Section 6.3.6.5, “Command
Options for Secure Connections”.
• --user=user_name, -u user_name
The user name of the MySQL account you want to use. The default user name is ODBC on Windows
or your Unix login name on Unix.
It is possible to 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:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Program Options

• 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

Section 4.2.6, “Using Option Files”, discusses option files further.
•

You can specify some connection parameters using environment variables. The host can be
specified for mysql using MYSQL_HOST. The MySQL user name can be specified using USER (this
is for Windows and NetWare only). The password can be specified using MYSQL_PWD, although this
is insecure; see Section 6.1.2.1, “End-User Guidelines for Password Security”. For a list of variables,
see Section 2.21, “Environment Variables”.

4.2.3 Specifying Program Options
There are several ways to specify options for MySQL programs:
• List the options on the command line following the program name. This is common for options that
apply to a specific invocation of the program.
• List the options 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.
• List the options in environment variables (see Section 4.2.10, “Setting Environment Variables”).
This method is useful for options that you want to apply each time the program runs. In practice,
option files are used more commonly for this purpose, but Section 5.5.3, “Running Multiple MySQL
Instances 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 the server and for client programs.
Options are processed in order, so if an option is specified multiple times, the last occurrence takes
precedence. The following command causes mysql to connect to the server running on localhost:
shell> mysql -h example.com -h localhost

If conflicting or related options are given, later options take precedence over earlier options. The
following command runs mysql in “no column names” mode:
shell> mysql --column-names --skip-column-names

MySQL programs determine which options are given first by examining environment variables, then by
reading option files, and then by checking the command line. 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 default option
values for a program in an option file. That enables you to avoid typing them each time you run the
program while enabling you to override the defaults if necessary by using command-line options.
An option can be specified by writing it in full or as any unambiguous prefix. For example, the -compress option can be given to mysqldump as --compr, but not as --comp because the latter is
ambiguous:
shell> mysqldump --comp
mysqldump: ambiguous option '--comp' (compatible, compress)

Be aware that the use of option prefixes can cause problems in the event that new options are
implemented for a program. A prefix that is unambiguous now might become ambiguous in the future.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Options on the Command Line

4.2.4 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 is a short form or
long form of the option name. Many options have both short and long forms. For example, -? and -help are the short and long forms of the option that instructs a MySQL program to display its 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 prompts you for the password. The password option also may be given in short form as ppass_val or as -p. However, for the short form, if the password value is given, it must follow the
option letter with no intervening space. The reason for this is that if a space follows the option letter,
the program has no way to tell whether a following argument is supposed to be the password value
or some other kind of argument. Consequently, the following two commands have two completely
different meanings:
shell> mysql -ptest
shell> mysql -p test

The first command instructs mysql to use a password value of test, but specifies no default
database. The second instructs mysql to prompt for the password value and to use test as the
default database.
• Within option names, dash (“-”) and underscore (“_”) may be used interchangeably. For example, -skip-grant-tables and --skip_grant_tables are equivalent. (However, the leading dashes
cannot be given as underscores.)
• For options that take a numeric value, the value can be given with a suffix of K, M, or G (either
2
3
uppercase or lowercase) to indicate a multiplier of 1024, 1024 or 1024 . For example, the following
command tells mysqladmin to ping the server 1024 times, sleeping 10 seconds between each ping:
mysql> mysqladmin --count=1K --sleep=10 ping

Option values that contain spaces must be quoted when given on the command line. For example, the
--execute (or -e) option can be used with mysql to pass SQL statements to the server. When this
option is used, mysql executes the statements in the option value and exits. The statements must be
enclosed by quotation marks. For example, you can use the following command to obtain a list of user
accounts:
mysql> mysql -u root -p --execute="SELECT User, Host FROM mysql.user"
Enter password: ******
+------+-----------+
| User | Host
|
+------+-----------+
|
| gigan
|
| root | gigan
|

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Program Option Modifiers

|
| localhost |
| jon | localhost |
| root | localhost |
+------+-----------+
shell>

Note
The long form (--execute) is followed by an equals sign (=).
If you wish to use quoted values within a statement, you will either need to escape the inner quotation
marks, or use a different type of quotation marks within the statement from those used to quote the
statement itself. The capabilities of your command processor dictate your choices for whether you can
use single or double quotation marks and the syntax for escaping quote characters. For example, if
your command processor supports quoting with single or double quotation marks, you can use double
quotation marks around the statement, and single quotation marks for any quoted values within the
statement.
Multiple SQL statements may be passed in the option value on the command line, separated by
semicolons:
shell> mysql -u root -p -e "SELECT VERSION();SELECT NOW()"
Enter password: ******
+------------------+
| VERSION()
|
+------------------+
| 5.0.97-debug-log |
+------------------+
+---------------------+
| NOW()
|
+---------------------+
| 2015-11-05 20:03:51 |
+---------------------+

The --execute or -e option may also be used to pass commands in an analogous fashion to the
ndb_mgm management client for MySQL Cluster. See Section 17.2.5, “Safe Shutdown and Restart of
MySQL Cluster”, for an example.

4.2.5 Program Option Modifiers
Some options are “boolean” and control behavior that can be turned on or off. For example, the mysql
client supports a --column-names option that determines whether or not to display a row of column
names at the beginning of query results. By default, this option is enabled. However, you may want
to disable it in some instances, such as when sending the output of mysql into another program that
expects to see only data and not an initial header line.
To disable column names, you can specify the option using any of these forms:
--disable-column-names
--skip-column-names
--column-names=0

The --disable and --skip prefixes and the =0 suffix all have the same effect: They turn the option
off.
The “enabled” form of the option may be specified in any of these ways:
--column-names
--enable-column-names
--column-names=1

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Option Files

If an option is prefixed by --loose, a program does not exit with an error if it does not recognize the
option, but instead issues only a warning:
shell> mysql --loose-no-such-option
mysql: WARNING: unknown option '--loose-no-such-option'

The --loose prefix can be useful when you run programs from multiple installations of MySQL on the
same machine and 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 recognize the option process it normally, and versions that do not recognize it issue a warning and
ignore it.
The --maximum prefix is available for mysqld only and permits a limit to be placed on how large client
programs can set session system variables. To do this, use a --maximum prefix with the variable
name. For example, --maximum-max_heap_table_size=32M prevents any client from making the
heap table size limit larger than 32M.
The --maximum prefix is intended for use with system variables that have a session value. If applied
to a system variable that has only a global value, an error occurs. For example, with --maximumquery_cache_size=4M, the server produces this error:
Maximum value of 'query_cache_size' cannot be set

4.2.6 Using Option Files
Most 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. For the MySQL server, MySQL provides a
number of preconfigured option files.
To determine whether a program reads option files, invoke it with the --help option. (For mysqld, use
--verbose and --help.) If the program reads option files, the help message indicates which files it
looks for and which option groups it recognizes.
Note
Option files used with MySQL Cluster programs are covered in Section 17.3,
“MySQL Cluster Configuration”.
On Windows, MySQL programs read startup options from the following files, in the specified order (top
files are read first, later files take precedence).
File Name

Purpose

%WINDIR%\my.ini,
%WINDIR%\my.cnf

Global options

C:\my.ini, C:\my.cnf

Global options

INSTALLDIR\my.ini,
INSTALLDIR\my.cnf

Global options

defaults-extra-file

The file specified with --defaults-extra-file=file_name, if any

In table items, %WINDIR% represents the location of your Windows directory. This is commonly C:
\WINDOWS. You can determine its exact location from the value of the WINDIR environment variable
using the following command:
C:\> echo %WINDIR%

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Option Files

INSTALLDIR represents the MySQL installation directory. This is typically C:\PROGRAMDIR\MySQL
\MySQL 5.0 Server where PROGRAMDIR represents the programs directory (usually Program
Files on English-language versions of Windows), when MySQL 5.0 has been installed using the
installation and configuration wizards. See Section 2.10.3.1, “Starting the MySQL Server Instance
Configuration Wizard”.
On Unix, Linux and OS X, MySQL programs read startup options from the following files, in the
specified order (top files are read first, later files take precedence).
File Name

Purpose

/etc/my.cnf

Global options

SYSCONFDIR/my.cnf

Global options

$MYSQL_HOME/my.cnf

Server-specific options

defaults-extra-file

The file specified with --defaults-extra-file=file_name, if any

~/.my.cnf

User-specific options

In table items, ~ represents the current user's home directory (the value of $HOME).
SYSCONFDIR represents the directory specified with the --sysconfdir option to configure
when MySQL was built. By default, this is the etc directory located under the compiled-in installation
directory. This location is used as of MySQL 5.0.21. (From 5.0.21 to 5.0.53, it was read last, after
~/.my.cnf.)
MYSQL_HOME is an environment variable containing the path to the directory in which the serverspecific my.cnf file resides. (This was DATADIR prior to MySQL version 5.0.3.)
If MYSQL_HOME is not set and you start the server using the mysqld_safe program, mysqld_safe
attempts to set MYSQL_HOME as follows:
• Let BASEDIR and DATADIR represent the path names of the MySQL base directory and data
directory, respectively.
• If there is a my.cnf file in DATADIR but not in BASEDIR, mysqld_safe sets MYSQL_HOME to
DATADIR.
• Otherwise, if MYSQL_HOME is not set and there is no my.cnf file in DATADIR, mysqld_safe sets
MYSQL_HOME to BASEDIR.
In MySQL 5.0, use of DATADIR as the location for my.cnf is deprecated.
Typically, DATADIR is /usr/local/mysql/data for a binary installation or /usr/local/var for
a source installation. This is the data directory location that was specified at configuration time, not
the one specified with the --datadir option when mysqld starts. Use of --datadir at runtime has
no effect on where the server looks for option files, because it looks for them before processing any
options.
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 instances of a given option are found, the last instance takes precedence. There is one
exception: For mysqld, the first instance of the --user option is used as a security precaution, to
prevent a user specified in an option file from being overridden on the command line.
Note
On Unix platforms, MySQL ignores configuration files that are world-writable.
This is intentional as a security measure.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Option Files

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 (see Section 4.2.4,
“Using Options on the Command Line”). However, in an option file, you omit the leading two dashes
from the option name and you specify only one option per line. For example, --quick and -host=localhost on the command line should be specified as quick and host=localhost on
separate lines 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. Nonempty lines can take any of the following forms:
• #comment, ;comment
Comment lines start with “#” or “;”. 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
option-setting lines apply to the named group until the end of the option file or another group line is
given. Option group names are not case sensitive.
• 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. You can optionally
enclose the value within single quotation marks or double quotation marks, which is useful if the
value contains a “#” comment character.
Leading and trailing spaces are automatically deleted from option names and values.
You can use the escape sequences “\b”, “\t”, “\n”, “\r”, “\\”, and “\s” in option values to represent
the backspace, tab, newline, carriage return, backslash, and space characters. The escaping rules in
option files are:
• If a backslash is followed by a valid escape sequence character, the sequence is converted to the
character represented by the sequence. For example, “\s” is converted to a space.
• If a backslash is not followed by a valid escape sequence character, it remains unchanged. For
example, “\S” is retained as is.
The preceding rules mean that a literal backslash can be given as “\\”, or as “\” if it is not followed by
a valid escape sequence character.
The rules for escape sequences in option files differ slightly from the rules for escape sequences in
string literals in SQL statements. In the latter context, if “x” is not a valid escape sequence character,
“\x” becomes “x” rather than “\x”. See Section 9.1.1, “String Literals”.
The escaping rules for option file values are especially pertinent for Windows path names, which use
“\” as a path name separator. A separator in a Windows path name must be written as “\\” if it is
followed by an escape sequence character. It can be written as “\\” or “\” if it is not. Alternatively, “/”
may be used in Windows path names and will be treated as “\”. Suppose that you want to specify a
base directory of C:\Program Files\MySQL\MySQL Server 5.0 in an option file. This can be
done several ways. Some examples:
basedir="C:\Program Files\MySQL\MySQL Server 5.0"
basedir="C:\\Program Files\\MySQL\\MySQL Server 5.0"

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Option Files

basedir="C:/Program Files/MySQL/MySQL Server 5.0"
basedir=C:\\Program\sFiles\\MySQL\\MySQL\sServer\s5.0

If an option group name is the same as a program name, options in the group apply specifically to
that program. For example, the [mysqld] and [mysql] groups apply to the mysqld server and the
mysql client program, respectively.
The [client] option group is read by all client programs (but not by mysqld). This enables you to
specify options that apply to all clients. For example, [client] is the perfect group to use to specify
the password that you use to connect to the server. (But make sure that the option file is readable and
writable only by yourself, so that other people cannot find out your password.) Be sure not to put an
option in the [client] group unless it is recognized by all client programs that you use. Programs
that do not understand the option quit after displaying an error message if you try to run them.
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.
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
connect_timeout=2
[mysqlhotcopy]
interactive-timeout

If you want to create option groups that should be read by mysqld servers from a specific MySQL
release series only, you can do this by using groups with names of [mysqld-4.1], [mysqld-5.0],
and so forth. The following group indicates that the sql_mode setting should be used only by MySQL
servers with 5.0.x version numbers:
[mysqld-5.0]
sql_mode=TRADITIONAL

Beginning with MySQL 5.0.4, it is possible to use !include directives in option files to include other
option files and !includedir to search specific directories for option files. For example, to include the
/home/mydir/myopt.cnf file, use the following directive:
!include /home/mydir/myopt.cnf

To search the /home/mydir directory and read option files found there, use this directive:
!includedir /home/mydir

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Command-Line Options that Affect Option-File Handling

There is no guarantee about the order in which the option files in the directory will be read.
Note
Any files to be found and included using the !includedir directive on Unix
operating systems must have file names ending in .cnf. On Windows, this
directive checks for files with the .ini or .cnf extension.
Write the contents of an included option file like any other option file. That is, it should contain groups of
options, each preceded by a [group] line that indicates the program to which the options apply.
While an included file is being processed, only those options in groups that the current program is
looking for are used. Other groups are ignored. Suppose that a my.cnf file contains this line:
!include /home/mydir/myopt.cnf

And suppose that /home/mydir/myopt.cnf looks like this:
[mysqladmin]
force
[mysqld]
key_buffer_size=16M

If my.cnf is processed by mysqld, only the [mysqld] group in /home/mydir/myopt.cnf is used.
If the file is processed by mysqladmin, only the [mysqladmin] group is used. If the file is processed
by any other program, no options in /home/mydir/myopt.cnf are used.
The !includedir directive is processed similarly except that all option files in the named directory
are read.

4.2.7 Command-Line Options that Affect Option-File Handling
Most MySQL programs that support option files handle the following options. Because these options
affect option-file handling, they must be given on the command line and not in an option file. To work
properly, each of these options must be given before other options, with these exceptions:
• --print-defaults may be used immediately after --defaults-file or --defaults-extrafile.
• On Windows, if the server is started with the --defaults-file and --install options, -install must be first. See Section 2.10.4.7, “Starting MySQL as a Windows Service”.
When specifying file names, avoid the use of the “~” shell metacharacter because it might not be
interpreted as you expect.
• --defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. (For
information about the order in which option files are used, see Section 4.2.6, “Using Option
Files”.) As of MySQL 5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.
• --defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.
• --defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str.
For example, the mysql client normally reads the [client] and [mysql] groups. If the -This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Options to Set Program Variables

defaults-group-suffix=_other option is given, mysql also reads the [client_other] and
[mysql_other] groups. This option was added in MySQL 5.0.10.
• --no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.
• --print-defaults
Print the program name and all options that it gets from option files.

4.2.8 Using Options to Set Program Variables
Many MySQL programs have internal variables that can be set at runtime using the SET statement.
See Section 13.7.4, “SET Syntax”, and Section 5.1.5, “Using System Variables”.
Most of these program variables also can be set at server startup by using the same syntax that
applies to specifying program options. For example, mysql has a max_allowed_packet variable that
controls the maximum size of its communication buffer. To set the max_allowed_packet variable for
mysql to a value of 16MB, use either of the following commands:
shell> mysql --max_allowed_packet=16777216
shell> mysql --max_allowed_packet=16M

The first command specifies the value in bytes. The second specifies the value in megabytes. For
variables that take a numeric value, the value can be given with a suffix of K, M, or G (either uppercase
2
3
or lowercase) to indicate a multiplier of 1024, 1024 or 1024 . (For example, when used to set
max_allowed_packet, the suffixes indicate units of kilobytes, megabytes, or gigabytes.)
In an option file, variable settings are 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. The following option groups are
equivalent. Both set the size of the server's key buffer to 512MB:
[mysqld]
key_buffer_size=512M
[mysqld]
key-buffer-size=512M

A variable can be specified by writing it in full or as any unambiguous prefix. For example, the
max_allowed_packet variable can be set for mysql as --max_a, but not as --max because the
latter is ambiguous:
shell> mysql --max=1000000
mysql: ambiguous option '--max=1000000' (max_allowed_packet, max_join_size)

Be aware that the use of variable prefixes can cause problems in the event that new variables are
implemented for a program. A prefix that is unambiguous now might become ambiguous in the future.
Suffixes for specifying a value multiplier can be used when setting a variable at server startup, but not
to set the value with SET at runtime. On the other hand, with SET you can assign a variable's value
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Option Defaults, Options Expecting Values, and the = Sign

using an expression, which is not true when you set a variable at server startup. For example, the first
of the following lines is legal at server startup, but the second is not:
shell> mysql --max_allowed_packet=16M
shell> mysql --max_allowed_packet=16*1024*1024

Conversely, the second of the following lines is legal at runtime, but the first is not:
mysql> SET GLOBAL max_allowed_packet=16M;
mysql> SET GLOBAL max_allowed_packet=16*1024*1024;

Note
Before MySQL 4.0.2, the only syntax for setting program variables was --setvariable=option=value (or set-variable=option=value in option
files). Underscores cannot be given as dashes, and the variable name must
be specified in full. This syntax still is recognized, but is now deprecated and is
removed in MySQL 5.5.

4.2.9 Option Defaults, Options Expecting Values, and the = Sign
By convention, long forms of options that assign a value are written with an equals (=) sign, like this:
shell> mysql --host=tonfisk --user=jon

For options that require a value (that is, not having a default value), the equal sign is not required, and
so the following is also valid:
shell> mysql --host tonfisk --user jon

In both cases, the mysql client attempts to connect to a MySQL server running on the host named
“tonfisk” using an account with the user name “jon”.
Due to this behavior, problems can occasionally arise when no value is provided for an option that
expects one. Consider the following example, where a user connects to a MySQL server running on
host tonfisk as user jon:
shell> mysql --host 85.224.35.45 --user jon
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.0.96 Source distribution
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> SELECT CURRENT_USER();
+----------------+
| CURRENT_USER() |
+----------------+
| jon@%
|
+----------------+
1 row in set (0.00 sec)

Omitting the required value for one of these option yields an error, such as the one shown here:
shell> mysql --host 85.224.35.45 --user
mysql: option '--user' requires an argument

In this case, mysql was unable to find a value following the --user option because nothing came
after it on the command line. However, if you omit the value for an option that is not the last option to
be used, you obtain a different error that you may not be expecting:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Option Defaults, Options Expecting Values, and the = Sign

shell> mysql --host --user jon
ERROR 2005 (HY000): Unknown MySQL server host '--user' (1)

Because mysql assumes that any string following --host on the command line is a host name, -host --user is interpreted as --host=--user, and the client attempts to connect to a MySQL
server running on a host named “--user”.
Options having default values always require an equal sign when assigning a value; failing to do
so causes an error. For example, the MySQL server --log-error option has the default value
host_name.err, where host_name is the name of the host on which MySQL is running. Assume
that you are running MySQL on a computer whose host name is “tonfisk”, and consider the following
invocation of mysqld_safe:
shell> mysqld_safe &
[1] 11699
shell> 080112 12:53:40 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
080112 12:53:40 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
shell>

After shutting down the server, restart it as follows:
shell> mysqld_safe --log-error &
[1] 11699
shell> 080112 12:53:40 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
080112 12:53:40 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
shell>

The result is the same, since --log-error is not followed by anything else on the command line,
and it supplies its own default value. (The & character tells the operating system to run MySQL in the
background; it is ignored by MySQL itself.) Now suppose that you wish to log errors to a file named
my-errors.err. You might try starting the server with --log-error my-errors, but this does not
have the intended effect, as shown here:
shell> mysqld_safe --log-error my-errors &
[1] 31357
shell> 080111 22:53:31 mysqld_safe Logging to '/usr/local/mysql/var/tonfisk.err'.
080111 22:53:32 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
080111 22:53:34 mysqld_safe mysqld from pid file /usr/local/mysql/var/tonfisk.pid ended
[1]+

Done

./mysqld_safe --log-error my-errors

The server attempted to start using /usr/local/mysql/var/tonfisk.err as the error log, but
then shut down. Examining the last few lines of this file shows the reason:
shell> tail /usr/local/mysql/var/tonfisk.err
080111 22:53:32 InnoDB: Started; log sequence number 0 46409
/usr/local/mysql/libexec/mysqld: Too many arguments (first extra is 'my-errors').
Use --verbose --help to get a list of available options
080111 22:53:32 [ERROR] Aborting
080111 22:53:32 InnoDB: Starting shutdown...
080111 22:53:34 InnoDB: Shutdown completed; log sequence number 0 46409
080111 22:53:34 [Note] /usr/local/mysql/libexec/mysqld: Shutdown complete
080111 22:53:34 mysqld_safe mysqld from pid file /usr/local/mysql/var/tonfisk.pid ended

Because the --log-error option supplies a default value, you must use an equal sign to assign a
different value to it, as shown here:
shell> mysqld_safe --log-error=my-errors &
[1] 31437
shell> 080111 22:54:15 mysqld_safe Logging to '/usr/local/mysql/var/my-errors.err'.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Option Defaults, Options Expecting Values, and the = Sign

080111 22:54:15 mysqld_safe Starting mysqld daemon with databases from /usr/local/mysql/var
shell>

Now the server has been started successfully, and is logging errors to the file /usr/local/mysql/
var/my-errors.err.
Similar issues can arise when specifying option values in option files. For example, consider a my.cnf
file that contains the following:
[mysql]
host
user

When the mysql client reads this file, these entries are parsed as --host --user or --host=-user, with the result shown here:
shell> mysql
ERROR 2005 (HY000): Unknown MySQL server host '--user' (1)

However, in option files, an equal sign is not assumed. Suppose the my.cnf file is as shown here:
[mysql]
user jon

Trying to start mysql in this case causes a different error:
shell> mysql
mysql: unknown option '--user jon'

A similar error would occur if you were to write host tonfisk in the option file rather than
host=tonfisk. Instead, you must use the equals sign:
[mysql]
user=jon

Now the login attempt succeeds:
shell> mysql
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 5
Server version: 5.0.96 Source distribution
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> SELECT USER();
+---------------+
| USER()
|
+---------------+
| jon@localhost |
+---------------+
1 row in set (0.00 sec)

This is not the same behavior as with the command line, where the equals sign is not required:
shell> mysql --user jon --host tonfisk
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 6
Server version: 5.0.96 Source distribution

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Setting Environment Variables

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> SELECT USER();
+---------------+
| USER()
|
+---------------+
| jon@tonfisk
|
+---------------+
1 row in set (0.00 sec)

4.2.10 Setting Environment Variables
Environment variables can be set at the command prompt to affect the current invocation of your
command processor, or set permanently to affect future invocations. To set a variable permanently,
you can set it in a startup file or by using the interface provided by your system for this purpose.
Consult the documentation for your command interpreter for specific details. Section 2.21,
“Environment Variables”, lists all environment variables that affect MySQL program operation.
To specify a value for an environment variable, use the syntax appropriate for your command
processor. For example, on Windows or NetWare, you can set the USER variable to specify your
MySQL account name. To do so, use this syntax:
SET USER=your_name

The syntax on Unix depends on your shell. Suppose that you want to specify the TCP/IP port number
using the MYSQL_TCP_PORT variable. Typical syntax (such as for sh, bash, zsh, and so on) is as
follows:
MYSQL_TCP_PORT=3306
export MYSQL_TCP_PORT

The first command sets the variable, and the export command exports the variable to the shell
environment so that its value becomes accessible to MySQL and other processes.
For csh and tcsh, use setenv to make the shell variable available to the environment:
setenv MYSQL_TCP_PORT 3306

The commands to set environment variables can be executed at your command prompt to take effect
immediately, but the settings persist only until you log out. To have the settings take effect each time
you log in, use the interface provided by your system or place the appropriate command or commands
in a startup file that your command interpreter reads each time it starts.
On Windows, you can set environment variables using the System Control Panel (under Advanced).
On Unix, typical shell startup files are .bashrc or .bash_profile for bash, or .tcshrc for tcsh.
Suppose that your MySQL programs are installed in /usr/local/mysql/bin and that you want to
make it easy to invoke these programs. To do this, set the value of the PATH environment variable to
include that directory. For example, if your shell is bash, add the following line to your .bashrc file:
PATH=${PATH}:/usr/local/mysql/bin

bash uses different startup files for login and nonlogin shells, so you might want to add the setting to
.bashrc for login shells and to .bash_profile for nonlogin shells to make sure that PATH is set
regardless.
If your shell is tcsh, add the following line to your .tcshrc file:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Server and Server-Startup Programs

setenv PATH ${PATH}:/usr/local/mysql/bin

If the appropriate startup file does not exist in your home directory, create it with a text editor.
After modifying your PATH setting, open a new console window on Windows or log in again on Unix so
that the setting goes into effect.

4.3 MySQL Server and Server-Startup Programs
This section describes mysqld, the MySQL server, and several programs that are used to start the
server.

4.3.1 mysqld — The MySQL Server
mysqld, also known as MySQL Server, is the main program that does most of the work in a MySQL
installation. MySQL Server manages access to the MySQL data directory that contains databases and
tables. The data directory is also the default location for other information such as log files and status
files.
When MySQL server starts, it listens for network connections from client programs and manages
access to databases on behalf of those clients.
The mysqld program has many options that can be specified at startup. For a complete list of options,
run this command:
shell> mysqld --verbose --help

MySQL Server also has a set of system variables that affect its operation as it runs. System variables
can be set at server startup, and many of them can be changed at runtime to effect dynamic server
reconfiguration. MySQL Server also has a set of status variables that provide information about its
operation. You can monitor these status variables to access runtime performance characteristics.
For a full description of MySQL Server command options, system variables, and status variables, see
Section 5.1, “The MySQL Server”. For information about installing MySQL and setting up the initial
configuration, see Chapter 2, Installing and Upgrading MySQL.

4.3.2 mysqld_safe — MySQL Server Startup Script
mysqld_safe is the recommended way to start a mysqld server on Unix and NetWare.
mysqld_safe adds some safety features such as restarting the server when an error occurs and
logging runtime information to an error log file. NetWare-specific behaviors are listed later in this
section.
Note
To preserve backward compatibility with older versions of MySQL, MySQL
binary distributions still include safe_mysqld as a symbolic link to
mysqld_safe. However, you should not rely on this because it is removed as
of MySQL 5.1.
By default, mysqld_safe before MySQL 5.0.27 tries to start an executable named mysqld-max if it
exists, and mysqld otherwise. Be aware of the implications of this behavior:
• On Linux, the MySQL-Max RPM relies on this mysqld_safe behavior. The RPM installs an
executable named mysqld-max, which causes mysqld_safe to automatically use that executable
rather than mysqld from that point on.
• If you install a MySQL-Max distribution that includes a server named mysqld-max, and then
upgrade later to a non-Max version of MySQL, mysqld_safe will still attempt to run the old
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_safe — MySQL Server Startup Script

mysqld-max server. If you perform such an upgrade, you should manually remove the old mysqldmax server to ensure that mysqld_safe runs the new mysqld server.
To override the default behavior and specify explicitly the name of the server you want to run, specify
a --mysqld or --mysqld-version option to mysqld_safe. You can also use --ledir to indicate
the directory where mysqld_safe should look for the server.
Many of the options to mysqld_safe are the same as the options to mysqld. See Section 5.1.3,
“Server Command Options”.
Options unknown to mysqld_safe are passed to mysqld if they are specified on the command line,
but ignored if they are specified in the [mysqld_safe] group of an option file. See Section 4.2.6,
“Using Option Files”.
mysqld_safe reads all options from the [mysqld], [server], and [mysqld_safe] sections in
option files. For example, if you specify a [mysqld] section like this, mysqld_safe will find and use
the --log-error option:
[mysqld]
log-error=error.log

For backward compatibility, mysqld_safe also reads [safe_mysqld] sections, but to be current you
should rename such sections to [mysqld_safe].
mysqld_safe supports the following options. It also reads option files and supports the options for
processing them described at Section 4.2.7, “Command-Line Options that Affect Option-File Handling”.
Table 4.1 mysqld_safe Options
Format

Description

--autoclose

On NetWare, mysqld_safe provides a screen presence

--basedir

Path to MySQL installation directory

--core-file-size

Size of core file that mysqld should be able to create

--datadir

Path to data directory

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--help

Display help message and exit

--ledir

Path to directory where server is located

--log-error

Write error log to named file

--mysqld

Name of server program to start (in ledir directory)

--mysqld-version

Suffix for server program name

--nice

Use nice program to set server scheduling priority

--no-defaults

Read no option files

--open-files-limit

Number of files that mysqld should be able to open

--pid-file

Path name of process ID file

--port

Port number on which to listen for TCP/IP connections

--skip-kill-mysqld

Do not try to kill stray mysqld processes

--socket

Socket file on which to listen for Unix socket connections

--timezone

Set TZ time zone environment variable to named value

--user

Run mysqld as user having name user_name or numeric
user ID user_id

•

Introduced

5.0.3

--help

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_safe — MySQL Server Startup Script

Display a help message and exit. (Added in MySQL 5.0.3)
•

--autoclose
(NetWare only) On NetWare, mysqld_safe provides a screen presence. When you unload (shut
down) the mysqld_safe NLM, the screen does not by default go away. Instead, it prompts for user
input:
**

If you want NetWare to close the screen automatically instead, use the --autoclose option to
mysqld_safe.
•

--basedir=dir_name
The path to the MySQL installation directory.

•

--core-file-size=size
The size of the core file that mysqld should be able to create. The option value is passed to ulimit
-c.

•

--datadir=dir_name
The path to the data directory.

•

--defaults-extra-file=file_name
The name of an option file to be read in addition to the usual option files. This must be the first
option on the command line if it is used. As of MySQL 5.0.6, if the file does not exist or is otherwise
inaccessible, the server will exit with an error.

•

--defaults-file=file_name
The name of an option file to be read instead of the usual option files. This must be the first option on
the command line if it is used.

•

--ledir=dir_name
If mysqld_safe cannot find the server, use this option to indicate the path name to the directory
where the server is located.

•

--log-error=file_name
Write the error log to the given file. See Section 5.4.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. If mysqld_safe cannot find the server, use the --ledir option to indicate the path
name to the directory where the server is located.

•

--mysqld-version=suffix
This option is similar to the --mysqld option, but you specify only the suffix for the server
program name. The base name is assumed to be mysqld. For example, if you use --mysqldversion=debug, mysqld_safe starts the mysqld-debug program in the ledir directory. If the
argument to --mysqld-version is empty, mysqld_safe uses mysqld in the ledir directory.

•

--nice=priority

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_safe — MySQL Server Startup Script

Use the nice program to set the server's scheduling priority to the given value.
•

--no-defaults
Do not read any option files. This must be the first option on the command line if it is used.

•

--open-files-limit=count
The number of files that mysqld should be able to open. The option value is passed to ulimit -n.
Note
You must start mysqld_safe as root for this to function properly.

•

--pid-file=file_name
The path name of the process ID file.

•

--port=port_num
The port number that the server should use when listening for TCP/IP connections. The port number
must be 1024 or higher unless the server is started by the root system user.

•

--skip-kill-mysqld
Do not try to kill stray mysqld processes at startup. This option works only on Linux.

•

--socket=path
The Unix socket file that the server should use when listening for local connections.

•

--timezone=timezone
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 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.)

If you execute mysqld_safe with the --defaults-file or --defaults-extra-file option to
name an option file, the option must be the first one given on the command line or the option file will not
be used. For example, this command will not use the named option file:
mysql> mysqld_safe --port=port_num --defaults-file=file_name

Instead, use the following command:
mysql> mysqld_safe --defaults-file=file_name --port=port_num

The mysqld_safe script is written so that it normally can start a server that was installed from either
a source or a binary distribution of MySQL, even though these types of distributions typically install the
server in slightly different locations. (See Section 2.7, “Installation Layouts”.) mysqld_safe expects
one of the following conditions to be true:
• The server and databases can be found relative to the working directory (the directory from which
mysqld_safe is invoked). For binary distributions, mysqld_safe looks under its working directory
for bin and data directories. For source distributions, it looks for libexec and var directories. This
condition should be met if you execute mysqld_safe from your MySQL installation directory (for
example, /usr/local/mysql for a binary distribution).

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql.server — MySQL Server Startup Script

• If the server and databases cannot be found relative to the working directory, mysqld_safe
attempts to locate them by absolute path names. Typical locations are /usr/local/libexec
and /usr/local/var. The actual locations are determined from the values configured into the
distribution at the time it was built. They should be correct if MySQL is installed in the location
specified at configuration time.
Because mysqld_safe tries to find the server and databases relative to its own working directory,
you can install a binary distribution of MySQL anywhere, as long as you run mysqld_safe from the
MySQL installation directory:
shell> cd mysql_installation_directory
shell> bin/mysqld_safe &

If mysqld_safe fails, even when invoked from the MySQL installation directory, specify the --ledir
and --datadir options to indicate the directories in which the server and databases are located on
your system.
Normally, you should not edit the mysqld_safe script. Instead, configure mysqld_safe by using
command-line options or options in the [mysqld_safe] section of a my.cnf option file. In rare cases,
it might be necessary to edit mysqld_safe to get it to start the server properly. However, if you do
this, your modified version of mysqld_safe might be overwritten if you upgrade MySQL in the future,
so you should make a copy of your edited version that you can reinstall.
On NetWare, mysqld_safe is a NetWare Loadable Module (NLM) that is ported from the original Unix
shell script. It starts the server as follows:
1. Runs a number of system and option checks.
2. Runs a check on MyISAM tables.
3. Provides a screen presence for the MySQL server.
4. Starts mysqld, monitors it, and restarts it if it terminates in error.
5. Sends error messages from mysqld to the host_name.err file in the data directory.
6. Sends mysqld_safe screen output to the host_name.safe file in the data directory.

4.3.3 mysql.server — MySQL Server Startup Script
MySQL distributions on Unix include a script named mysql.server, which starts the server using
mysqld_safe. 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 OS X Startup Item for MySQL.
To start or stop the server manually using the mysql.server script, invoke it with start or stop
arguments:
shell> mysql.server start
shell> mysql.server stop

Before mysql.server starts the server, it changes location to the MySQL installation directory, and
then invokes mysqld_safe. To run the server 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 must edit mysql.server if you've installed a binary distribution of MySQL in a nonstandard
location. Modify it to change location into the proper directory before it runs mysqld_safe. If you do
this, your modified version of mysql.server may be overwritten if you upgrade MySQL in the future,
so you should make a copy of your edited version that you can reinstall.)
mysql.server stop stops the server by sending a signal to it. You can also stop the server
manually by executing mysqladmin shutdown.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql.server — MySQL Server Startup Script

To start and stop MySQL automatically on your server, you must add start and stop commands to the
appropriate places in your /etc/rc* files.
If you use the Linux server RPM package (MySQL-server-VERSION.rpm), the mysql.server script
is installed in the /etc/init.d directory with the name mysql. You need not install it manually. See
Section 2.12, “Installing MySQL on Linux Using RPM Packages”, for more information on the Linux
RPM packages.
Some vendors provide RPM packages that install a startup script under a different name such as
mysqld.
If you install MySQL from a source distribution or using a binary distribution format that does not install
mysql.server automatically, you can install it manually. The script can be found in the supportfiles directory under the MySQL installation directory or in a MySQL source tree. Copy it to the /
etc/init.d directory with the name mysql, and then make it executable:
shell> cp mysql.server /etc/init.d/mysql
shell> chmod +x /etc/init.d/mysql

Note
Older Red Hat systems use the /etc/rc.d/init.d directory rather than /
etc/init.d. Adjust the preceding commands accordingly. Alternatively, first
create /etc/init.d as a symbolic link that points to /etc/rc.d/init.d:
shell> cd /etc
shell> ln -s rc.d/init.d .

After installing the script, the commands needed to activate it to run at system startup depend on your
operating system. On Linux, you can use chkconfig:
shell> chkconfig --add mysql

On some Linux systems, the following command also seems to be necessary to fully enable the mysql
script:
shell> chkconfig --level 345 mysql on

On FreeBSD, startup scripts generally should go in /usr/local/etc/rc.d/. The rc(8) manual
page states that scripts in this directory are executed only if their base name matches the *.sh shell
file name 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,
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.
mysql.server reads options from the [mysql.server] and [mysqld] sections of option files. For
backward compatibility, it also reads [mysql_server] sections, but to be current you should rename
such sections to [mysql.server].
You can add options for mysql.server in a global /etc/my.cnf file. A typical /etc/my.cnf file
might look like this:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_multi — Manage Multiple MySQL Servers

[mysqld]
datadir=/usr/local/mysql/var
socket=/var/tmp/mysql.sock
port=3306
user=mysql
[mysql.server]
basedir=/usr/local/mysql

The mysql.server script supports the following options. If specified, they must be placed in an
option file, not on the command line. mysql.server supports only start and stop as command-line
arguments.
Table 4.2 mysql.server Options
Format

Description

--basedir

Path to MySQL installation directory

--datadir

Path to MySQL data directory

--pid-file

File in which server should write its process ID

--service-startup-timeout

How long to wait for server startup

5.0.40

--use-manager

Use Instance Manager to start server

5.0.4

--use-mysqld_safe

Use mysqld_safe to start server

5.0.4

--user

Run server using this login user name

5.0.4

•

Introduced

--basedir=dir_name
The path to the MySQL installation directory.

•

--datadir=dir_name
The path to the MySQL data directory.

•

--pid-file=file_name
The path name of the file in which the server should write its process ID.

•

--service-startup-timeout=seconds
How long in seconds to wait for confirmation of server startup. If the server does not start within this
time, mysql.server exits with an error. The default value is 900. A value of 0 means not to wait at
all for startup. Negative values mean to wait forever (no timeout). This option was added in MySQL
5.0.40. Before that, a value of 900 is always used.

•

--use-mysqld_safe
Use mysqld_safe to start the server. This is the default. This option was added in MySQL 5.0.4.

•

--use-manager
Use Instance Manager to start the server. This option was added in MySQL 5.0.4.

•

--user=user_name
The login user name to use for running mysqld. This option was added in MySQL 5.0.4.

4.3.4 mysqld_multi — Manage Multiple MySQL Servers
mysqld_multi is designed to manage several mysqld processes that listen for connections
on different Unix socket files and TCP/IP ports. It can start or stop servers, or report their current
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_multi — Manage Multiple MySQL Servers

status. The MySQL Instance Manager is an alternative means of managing multiple servers (see
Section 4.6.10, “mysqlmanager — The MySQL Instance Manager”).
mysqld_multi searches for groups named [mysqldN] in my.cnf (or in the file named by the
--config-file option). N can be any positive integer. This number is referred to in the following
discussion as the option group number, or GNR. Group numbers distinguish option groups from one
another and are used as arguments to mysqld_multi to specify which servers you want to start,
stop, or obtain a status report for. Options listed in these groups are the same that you would use in the
[mysqld] group used for starting mysqld. (See, for example, Section 2.18.5, “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.5, “Running
Multiple MySQL Instances on One Machine”.
To invoke mysqld_multi, use the following syntax:
shell> mysqld_multi [options] {start|stop|report} [GNR[,GNR] ...]

start, stop, and report indicate which operation to perform. You can perform the designated
operation for a single server or multiple servers, depending on the GNR list that follows the option name.
If there is no list, mysqld_multi performs the operation for all servers in the option file.
Each GNR value represents an option group number or range of group numbers. The value should be
the number at the end of the group name in the option file. For example, the GNR for a group named
[mysqld17] is 17. To specify a range of numbers, separate the first and last numbers by a dash. The
GNR value 10-13 represents groups [mysqld10] through [mysqld13]. Multiple groups or group
ranges can be specified on the command line, separated by commas. There must be no whitespace
characters (spaces or tabs) in the GNR list; anything after a whitespace character is ignored.
This command starts a single server using option group [mysqld17]:
shell> mysqld_multi start 17

This command stops several servers, using option groups [mysqld8] 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

As of MySQL 5.0.42, mysqld_multi searches for option files as follows:
•

With --no-defaults, no option files are read.

•

With --defaults-file=file_name, only the named file is read.

•

Otherwise, option files in the standard list of locations are read, including any file named by the -defaults-extra-file=file_name option, if one is given. (If the option is given multiple times,
the last value is used.)

Before MySQL 5.0.42, the preceding options are not recognized. Files in the standard locations are
read, and any file named by the --config-file=file_name option, if one is given. A file named by
--config-file is read only for [mysqldN] option groups, not the [mysqld_multi] group.
Option files read are searched for [mysqld_multi] and [mysqldN] option groups. The
[mysqld_multi] group can be used for options to mysqld_multi itself. [mysqldN] groups can be
used for options passed to specific mysqld instances.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_multi — Manage Multiple MySQL Servers

As of MySQL 5.0.82, the [mysqld] or [mysqld_safe] groups can be used for common options read
by all instances of mysqld or mysqld_safe. You can specify a --defaults-file=file_name
option to use a different configuration file for that instance, in which case the [mysqld] or
[mysqld_safe] groups from that file will be used for that instance. Before MySQL 5.0.82, some
versions of mysqld_multi pass the --no-defaults options to instances, so these techniques are
inapplicable.
mysqld_multi supports the following options.
•

--help
Display a help message and exit.

•

--config-file=file_name
As of MySQL 5.0.42, this option is deprecated. If given, it is treated the same way as --defaultsextra-file, described earlier. --config-file is removed in MySQL 5.5.
Before MySQL 5.0.42, this option specifies the name of an extra option file. It affects where
mysqld_multi looks for [mysqldN] option groups. Without this option, all options are read from
the usual my.cnf file. The option does not affect where mysqld_multi reads its own options,
which are always taken from the [mysqld_multi] group in the usual my.cnf file.

•

--example
Display a sample option file.

•

--log=file_name
Specify the name of the log file. If the file exists, log output is appended to it.

•

--mysqladmin=prog_name
The mysqladmin binary to be used to stop servers.

•

--mysqld=prog_name
The mysqld binary to be used. Note that you can specify mysqld_safe as the value for this option
also. If you use mysqld_safe to start the server, you can include the mysqld or ledir options
in the corresponding [mysqldN] option group. These options indicate the name of the server that
mysqld_safe should start and the path name of the directory where the server is located. (See the
descriptions for these options in Section 4.3.2, “mysqld_safe — MySQL Server Startup Script”.)
Example:
[mysqld38]
mysqld = mysqld-debug
ledir = /opt/local/mysql/libexec

•

--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 mysqladmin. Note that the password
value is not optional for this option, unlike for other MySQL programs.

•

--silent
Silent mode; disable warnings.

•

--tcp-ip

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_multi — Manage Multiple MySQL Servers

Connect to each MySQL server through 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 through the TCP/IP port.) By
default, connections are made using the Unix socket file. This option affects stop and report
operations.
•

--user=user_name
The user name of the MySQL account to use when invoking mysqladmin.

•

--verbose
Be more verbose.

•

--version
Display version information and exit.

Some notes about mysqld_multi:
• Most important: Before using mysqld_multi be sure that you understand the meanings of the
options that are passed to the mysqld servers and why you would want to have separate mysqld
processes. Beware of the dangers of using multiple mysqld servers with the same data directory.
Use separate data directories, unless you know what you are doing. Starting multiple servers with
the same data directory does not give you extra performance in a threaded system. See Section 5.5,
“Running Multiple MySQL Instances on One Machine”.
•

Important
Make sure that the data directory for each server is fully accessible to the
Unix account that the specific mysqld process is started as. Do not use
the Unix root account for this, unless you know what you are doing. See
Section 6.1.5, “How to Run MySQL as a Normal User”.

• Make sure that the MySQL account used for stopping the mysqld servers (with the mysqladmin
program) has the same user name and password for each server. Also, make sure that the account
has the SHUTDOWN privilege. If the servers that you want to manage have different user names or
passwords for the administrative accounts, you might want to create an account on each server that
has the same user name and password. For example, you might set up a common multi_admin
account by executing the following commands for each server:
shell> mysql -u root -S /tmp/mysql.sock -p
Enter password:
mysql> CREATE USER 'multi_admin'@'localhost' IDENTIFIED BY 'multipass';
mysql> GRANT SHUTDOWN ON *.* TO 'multi_admin'@'localhost';

See Section 6.2, “The MySQL Access Privilege System”. You have to do this for each mysqld
server. Change the connection parameters appropriately when connecting to each one. Note that
the host name part of the account name must permit you to connect as multi_admin from the host
where you want to run mysqld_multi.
• The Unix socket file and the TCP/IP port number must be different for every mysqld. (Alternatively, if
the host has multiple network addresses, you can use --bind-address to cause different servers
to listen to different interfaces.)
• The --pid-file option is very important if you are using mysqld_safe to start mysqld (for
example, --mysqld=mysqld_safe) Every mysqld should have its own process ID file. The
advantage of using mysqld_safe instead of mysqld is that mysqld_safe monitors its mysqld
process and restarts it if the process terminates due to a signal sent using kill -9 or for other
reasons, such as a segmentation fault. Please note that the mysqld_safe script might require
that you start it from a certain place. This means that you might have to change location to a

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqld_multi — Manage Multiple MySQL Servers

certain directory before running mysqld_multi. If you have problems starting, please see the
mysqld_safe script. Check especially the lines:
---------------------------------------------------------------MY_PWD=`pwd`
# Check if we are starting this relative (for the binary release)
if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
-x ./bin/mysqld
----------------------------------------------------------------

The test performed by these lines should be successful, or you might encounter problems. See
Section 4.3.2, “mysqld_safe — MySQL Server Startup Script”.
• You might want to use the --user option for mysqld, but to do this you need to run the
mysqld_multi script as the Unix superuser (root). Having the option in the option file doesn't
matter; you just get a warning if you are not the superuser and the mysqld processes are started
under your own Unix account.
The following example shows how you might set up an option file for use with mysqld_multi. The
order in which the mysqld programs are started or stopped depends on the order in which they appear
in the option file. Group numbers need not form an unbroken sequence. The first and fifth [mysqldN]
groups were intentionally omitted from the example to illustrate that you can have “gaps” in the option
file. This gives you more flexibility.
# This is an example of a my.cnf file for mysqld_multi.
# Usually this file is located in home dir ~/.my.cnf or /etc/my.cnf
[mysqld_multi]
mysqld
= /usr/local/mysql/bin/mysqld_safe
mysqladmin = /usr/local/mysql/bin/mysqladmin
user
= multi_admin
password
= my_password
[mysqld2]
socket
port
pid-file
datadir
language
user

=
=
=
=
=
=

/tmp/mysql.sock2
3307
/usr/local/mysql/data2/hostname.pid2
/usr/local/mysql/data2
/usr/local/mysql/share/mysql/english
unix_user1

[mysqld3]
mysqld
ledir
mysqladmin
socket
port
pid-file
datadir
language
user

=
=
=
=
=
=
=
=
=

/path/to/mysqld_safe
/path/to/mysqld-binary/
/path/to/mysqladmin
/tmp/mysql.sock3
3308
/usr/local/mysql/data3/hostname.pid3
/usr/local/mysql/data3
/usr/local/mysql/share/mysql/swedish
unix_user2

[mysqld4]
socket
port
pid-file
datadir
language
user

=
=
=
=
=
=

/tmp/mysql.sock4
3309
/usr/local/mysql/data4/hostname.pid4
/usr/local/mysql/data4
/usr/local/mysql/share/mysql/estonia
unix_user3

[mysqld6]
socket
port
pid-file
datadir
language
user

=
=
=
=
=
=

/tmp/mysql.sock6
3311
/usr/local/mysql/data6/hostname.pid6
/usr/local/mysql/data6
/usr/local/mysql/share/mysql/japanese
unix_user4

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Installation-Related Programs

See Section 4.2.6, “Using Option Files”.

4.4 MySQL Installation-Related Programs
The programs in this section are used when installing or upgrading MySQL.

4.4.1 comp_err — Compile MySQL Error Message File
comp_err creates the errmsg.sys file that is used by mysqld to determine the error messages
to display for different error codes. comp_err normally is run automatically when MySQL is built. It
compiles the errmsg.sys file from the text file located at sql/share/errmsg.txt in MySQL source
distributions.
comp_err also generates mysqld_error.h, mysqld_ername.h, and sql_state.h header files.
For more information about how error messages are defined, see the MySQL Internals Manual.
Invoke comp_err like this:
shell> comp_err [options]

comp_err supports the following options.
•

--help, -?
Display a help message and exit.

•

--charset=dir_name, -C dir_name
The character set directory. The default is ../sql/share/charsets.

•

--debug=debug_options, -# debug_options
Write a debugging log. A typical debug_options string is d:t:O,file_name. The default is
d:t:O,/tmp/comp_err.trace.

•

--debug-info, -T
Print some debugging information when the program exits.

•

--header_file=file_name, -H file_name
The name of the error header file. The default is mysqld_error.h.

•

--in_file=file_name, -F file_name
The name of the input file. The default is ../sql/share/errmsg.txt.

•

--name_file=file_name, -N file_name
The name of the error name file. The default is mysqld_ername.h.

•

--out_dir=dir_name, -D dir_name
The name of the output base directory. The default is ../sql/share/.

•

--out_file=file_name, -O file_name
The name of the output file. The default is errmsg.sys.

•

--statefile=file_name, -S file_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

make_win_bin_dist — Package MySQL Distribution as Zip Archive

The name for the SQLSTATE header file. The default is sql_state.h.
•

--version, -V
Display version information and exit.

4.4.2 make_win_bin_dist — Package MySQL Distribution as Zip Archive
This script is used on Windows after building a MySQL distribution from source to create executable
programs. It packages the binaries and support files into a Zip archive that can be unpacked at the
location where you want to install MySQL.
make_win_bin_dist is a shell script, so you must have Cygwin installed to use it.
This program's use is subject to change. Currently, you invoke it as follows from the root directory of
your source distribution:
shell> make_win_bin_dist [options] package_basename [copy_def ...]

The package_basename argument provides the base name for the resulting Zip archive. This name
will be the name of the directory that results from unpacking the archive.
Because you might want to include files of directories from other builds, you can instruct
this script to copy them in for you, using copy_def arguments, which have the form
relative_dest_name=source_name.
Example:
bin/mysqld-max.exe=../my-max-build/sql/release/mysqld.exe

If you specify a directory, the entire directory will be copied.
make_win_bin_dist supports the following options.
•

--debug
Pack the debug binaries and produce an error if they were not built.

•

--embedded
Pack the embedded server and produce an error if it was not built. The default is to pack it if it was
built.

•

--exe-suffix=suffix
Add a suffix to the base name of the mysql binary. For example, a suffix of -abc produces a binary
named mysqld-abc.exe.

•

--no-debug
Do not pack the debug binaries even if they were built.

•

--no-embedded
Do not pack the embedded server even if it was built.

•

--only-debug
Use this option when the target for this build was Debug, and you just want to replace the normal
binaries with debug versions (that is, do not use separate debug directories).

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

make_win_src_distribution — Create Source Distribution for Windows

4.4.3 make_win_src_distribution — Create Source Distribution for
Windows
make_win_src_distribution creates a Windows source package to be used on Windows
systems. It is used after you configure and build the source distribution on a Unix or Unix-like system
so that you have a server binary to work with. (See the instructions at Section 2.10.8.5, “Creating a
Windows Source Package from the Bazaar Repository”.)
Invoke make_win_src_distribution like this from the top-level directory of a MySQL source
distribution:
shell> make_win_src_distribution [options]

make_win_src_distribution understands the following options:
•

--help
Display a help message and exit.

•

--debug
Print information about script operations; do not create a package.

•

--dirname
Directory name to copy files (intermediate).

•

--silent
Do not print verbose list of files processed.

•

--suffix
The suffix name for the package.

•

--tar
Create a .tar.gz package instead of a .zip package.
By default, make_win_src_distribution creates a Zip-format archive with the name
mysql-VERSION-win-src.zip, where VERSION represents the version of your MySQL source
tree.

•

--tmp
Specify the temporary location.

4.4.4 mysqlbug — Generate Bug Report
This program enables you to generate a bug report and send it to Oracle Corporation. It is a shell script
and runs on Unix.
The normal way to report bugs is to visit http://bugs.mysql.com/, which is the address for our bugs
database. This database is public and can be browsed and searched by anyone. If you log in to the
system, you can enter new reports. If you have no Web access, you can generate a bug report by
using the mysqlbug script.
mysqlbug 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. mysqlbug can be found
in the scripts directory (source distribution) and in the bin directory under your MySQL installation
directory (binary distribution).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_fix_privilege_tables — Upgrade MySQL System Tables

Invoke mysqlbug without arguments:
shell> mysqlbug

The script will place you in an editor with a copy of the report to be sent. Edit the lines near the
beginning that indicate the nature of the problem. Then write the file to save your changes, quit the
editor, and mysqlbug will send the report by email.

4.4.5 mysql_fix_privilege_tables — Upgrade MySQL System Tables
Some releases of MySQL introduce changes to the structure of the system tables in the mysql
database to add new privileges or support new features. When you update to a new version of MySQL,
update your system tables as well to make sure that their structure is up to date. Otherwise, there
might be capabilities that you cannot take advantage of.
mysql_fix_privilege_tables is an older script that previously was used to uprade the system
tables in the mysql database after a MySQL upgrade.
Note
As of MySQL 5.0.19, mysql_fix_privilege_tables is superseded
by mysql_upgrade, which should be used instead. See Section 4.4.9,
“mysql_upgrade — Check Tables for MySQL Upgrade”.
Before running mysql_fix_privilege_tables, make a backup of your mysql database.
On Unix or Unix-like systems, update the system tables by running the
mysql_fix_privilege_tables script:
shell> mysql_fix_privilege_tables

You must run this script while the server is running. It attempts to connect to the server running on the
local host as root. If your root account requires a password, indicate the password on the command
line like this:
shell> mysql_fix_privilege_tables --password=root_password

The mysql_fix_privilege_tables script performs any actions necessary to convert your system
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 so that any changes made to the system tables
take effect.
On Windows systems, MySQL distributions include a mysql_fix_privilege_tables.sql SQL
script that you can run using the mysql client. For example, if your MySQL installation is located at C:
\Program Files\MySQL\MySQL Server 5.0, the commands look like this:
C:\> cd "C:\Program Files\MySQL\MySQL Server 5.0"
C:\> bin\mysql -u root -p mysql
mysql> SOURCE share/mysql_fix_privilege_tables.sql

Note
Prior to version 5.0.38, this script is found in the scripts directory.
The mysql command will prompt you for the root password; enter it when prompted.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_install_db — Initialize MySQL Data Directory

If your installation is located in some other directory, adjust the path names appropriately.
As with the Unix procedure, you might see some Duplicate column name warnings as mysql
processes the statements in the mysql_fix_privilege_tables.sql script; you can ignore them.
After running the script, stop the server and restart it.

4.4.6 mysql_install_db — Initialize MySQL Data Directory
mysql_install_db initializes the MySQL data directory and creates the system tables that it
contains, if they do not exist. mysql_install_db is a shell script and is available only on Unix
platforms.
To invoke mysql_install_db, use the following syntax:
shell> mysql_install_db [options]

Because the MySQL server, mysqld, must access the data directory when it runs later, you
should either run mysql_install_db from the same system account that will be used for running
mysqld, or run it as root and specify the --user option to indicate the user name that mysqld
will run as. It might be necessary to specify other options such as --basedir or --datadir if
mysql_install_db does not use the correct locations for the installation directory or data directory.
For example:
shell> bin/mysql_install_db --user=mysql \
--basedir=/opt/mysql/mysql \
--datadir=/opt/mysql/mysql/data

mysql_install_db needs to invoke mysqld with the --bootstrap and --skip-grant-tables
options. If MySQL was configured with the --disable-grant-options configuration option, -bootstrap and --skip-grant-tables will be disabled (see Section 2.17.3, “MySQL SourceConfiguration Options”). To handle this, set the MYSQLD_BOOTSTRAP environment variable to the full
path name of a server that has all options enabled. mysql_install_db will use that server.
mysql_install_db supports the following options, which can be specified on the command line or in
the [mysql_install_db] group of an option file. (Options that are common to mysqld can also be
specified in the [mysqld] group.) Other options are passed to mysqld. For information about option
files used by MySQL programs, see Section 4.2.6, “Using Option Files”. mysql_install_db also
supports the options for processing option files described at Section 4.2.7, “Command-Line Options
that Affect Option-File Handling”.
•

--help
Display a help message and exit.

•

--basedir=dir_name
The path to the MySQL installation directory.

•

--builddir=dir_name
For use with --srcdir and out-of-source builds. Set this to the location of the directory where the
built files reside.

•

--cross-bootstrap
For internal use. This option is used for building system tables on one host intended for another.

•

--datadir=dir_name
The path to the MySQL data directory.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_secure_installation — Improve MySQL Installation Security

• --defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. If the file
does not exist or is otherwise inaccessible, an error occurs. file_name is interpreted relative to the
current directory if given as a relative path name rather than a full path name.
• --defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is interpreted relative to the current directory if given as a relative path name rather than
a full path name.
•

--force
Cause mysql_install_db to run even if DNS does not work. Grant table entries normally created
using host names will use IP addresses instead.

•

--ldata=dir_name
A synonym for --datadir.

• --no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.
•

--rpm
For internal use. This option is used during the MySQL installation process for install operations
performed using RPM packages.

•

--skip-name-resolve
Use IP addresses rather than host names when creating grant table entries. This option can be
useful if your DNS does not work.

•

--srcdir=dir_name
For internal use. This option specifies the directory under which mysql_install_db looks for
support files such as the error message file and the file for populating the help tables. This option
was added in MySQL 5.0.32.

•

--user=user_name
The system (login) user name to use for running mysqld. Files and directories created by mysqld
will be owned by this user. You must be the system root user to use this option. By default, mysqld
runs using your current login name and files and directories that it creates will be owned by you.

•

--verbose
Verbose mode. Print more information about what the program does.

•

--windows
For internal use. This option is used for creating Windows distributions.

4.4.7 mysql_secure_installation — Improve MySQL Installation
Security
This program enables you to improve the security of your MySQL installation in the following ways:
• You can set a password for root accounts.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_tzinfo_to_sql — Load the Time Zone Tables

• You can remove root accounts that are accessible from outside the local host.
• You can remove anonymous-user accounts.
• You can remove the test database (which by default can be accessed by all users, even
anonymous users), and privileges that permit anyone to access databases with names that start with
test_.
mysql_secure_installation helps you implement security recommendations similar to those
described at Section 2.18.4, “Securing the Initial MySQL Accounts”.
Invoke mysql_secure_installation without arguments:
shell> mysql_secure_installation

When executed, the script prompts you to determine which actions to perform.
mysql_secure_installation is not available on Windows.

4.4.8 mysql_tzinfo_to_sql — Load the Time Zone Tables
The mysql_tzinfo_to_sql program loads the time zone tables in the mysql database. It is used
on systems that have a zoneinfo database (the set of files describing time zones). Examples of such
systems are Linux, FreeBSD, Solaris, and OS X. One likely location for these files is the /usr/share/
zoneinfo directory (/usr/share/lib/zoneinfo on Solaris). If your system does not have a
zoneinfo database, you can use the downloadable package described in Section 10.6, “MySQL Server
Time Zone Support”.
mysql_tzinfo_to_sql can be invoked several ways:
shell> mysql_tzinfo_to_sql tz_dir
shell> mysql_tzinfo_to_sql tz_file tz_name
shell> mysql_tzinfo_to_sql --leap tz_file

For the first invocation syntax, pass the zoneinfo directory path name to mysql_tzinfo_to_sql and
send the output into the mysql program. For example:
shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

mysql_tzinfo_to_sql reads your system's time zone files and generates SQL statements from
them. mysql processes those statements to load the time zone tables.
The second syntax causes mysql_tzinfo_to_sql to load a single time zone file tz_file that
corresponds to a time zone name tz_name:
shell> mysql_tzinfo_to_sql tz_file tz_name | mysql -u root mysql

If your time zone needs to account for leap seconds, invoke mysql_tzinfo_to_sql using the third
syntax, which initializes the leap second information. tz_file is the name of your time zone file:
shell> mysql_tzinfo_to_sql --leap tz_file | mysql -u root mysql

After running mysql_tzinfo_to_sql, it is best to restart the server so that it does not continue to
use any previously cached time zone data.

4.4.9 mysql_upgrade — Check Tables for MySQL Upgrade
mysql_upgrade examines all tables in all databases for incompatibilities with the current version of
MySQL Server. mysql_upgrade also upgrades the system tables so that you can take advantage of
new privileges or capabilities that might have been added.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_upgrade — Check Tables for MySQL Upgrade

If mysql_upgrade finds that a table has a possible incompatibility, it performs a table check and,
if problems are found, attempts a table repair. If the table cannot be repaired, see Section 2.19.4,
“Rebuilding or Repairing Tables or Indexes” for manual table repair strategies.
You should execute mysql_upgrade each time you upgrade MySQL. It supersedes the older
mysql_fix_privilege_tables script, which should no longer be used.
If you install MySQL from RPM packages on Linux, you must install the server and client RPMs.
mysql_upgrade is included in the server RPM but requires the client RPM because the latter includes
mysqlcheck. (See Section 2.12, “Installing MySQL on Linux Using RPM Packages”.)
Caution
You should always back up your current MySQL installation before performing
an upgrade. See Section 7.2, “Database Backup Methods”.
Some upgrade incompatibilities may require special handling before
you upgrade your MySQL installation and run mysql_upgrade. See
Section 2.19.1, “Upgrading MySQL”, for instructions on determining whether
any such incompatibilities apply to your installation and how to handle them.
To use mysql_upgrade, make sure that the server is running. Then invoke it like this:
shell> mysql_upgrade [options]

After running mysql_upgrade, stop the server and restart it so that any changes made to the system
tables take effect.
If you have multiple MySQL server instances running, invoke mysql_upgrade with connection
parameters appropriate for connecting to the desired server. For example, with servers running on the
local host on parts 3306 through 3308, upgrade each of them by connecting to the appropriate port:
shell> mysql_upgrade --protocol=tcp -P 3306 [other_options]
shell> mysql_upgrade --protocol=tcp -P 3307 [other_options]
shell> mysql_upgrade --protocol=tcp -P 3308 [other_options]

For local host connections on Unix, the --protocol=tcp option forces a connection using TCP/IP
rather than the Unix socket file.
mysql_upgrade executes the following commands to check and repair tables and to upgrade the
system tables:
mysqlcheck --no-defaults --check-upgrade --all-databases --auto-repair
mysql < fix_priv_tables

Notes about the preceding commands:
• Because mysql_upgrade invokes mysqlcheck with the --all-databases option, it processes
all tables in all databases, which might take a long time to complete. Each table is locked and
therefore unavailable to other sessions while it is being processed. Check and repair operations can
be time-consuming, particularly for large tables.
• For details about what checks the --check-upgrade option entails, see the description of the FOR
UPGRADE option of the CHECK TABLE statement (see Section 13.7.2.3, “CHECK TABLE Syntax”).
• fix_priv_tables represents a script generated internally by mysql_upgrade that contains SQL
statements to upgrade the tables in the mysql database.
All checked and repaired tables are marked with the current MySQL version number. This ensures that
next time you run mysql_upgrade with the same version of the server, it can tell whether there is any
need to check or repair the table again.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_upgrade — Check Tables for MySQL Upgrade

mysql_upgrade also saves the MySQL version number in a file named mysql_upgrade_info in
the data directory. This is used to quickly check whether all tables have been checked for this release
so that table-checking can be skipped. To ignore this file and perform the check regardless, use the -force option.
In MySQL 5.0.19, mysql_upgrade was added as a shell script and worked only for Unix systems. As
of MySQL 5.0.23, mysql_upgrade is an executable binary and is available on all systems.
mysql_upgrade does not upgrade the contents of the help tables. For upgrade instructions, see
Section 5.1.8, “Server-Side Help”.
mysql_upgrade supports the following options, which can be specified on the command line or in
the [mysql_upgrade] and [client] groups of an option file. Unrecognized options are passed to
mysqlcheck. For information about option files, see Section 4.2.6, “Using Option Files”.
•

--help
Display a short help message and exit.

•

--basedir=dir_name
The path to the MySQL installation directory. This option is accepted for backward compatibility but
ignored.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.
This option was added in MySQL 5.0.30.

•

--compress
Compress all information sent between the client and the server if both support compression. This
option was added in MySQL 5.0.30.

•

--datadir=dir_name
The path to the data directory. This option is accepted for backward compatibility but ignored.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:O,/tmp/mysql_upgrade.trace.

•

--debug-info, -T
Print some debugging information when the program exits.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”.
This option was added in MySQL 5.0.30.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_upgrade — Check Tables for MySQL Upgrade

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str.
For example, mysql_upgrade normally reads the [client] and [mysql_upgrade] groups.
If the --defaults-group-suffix=_other option is given, mysql_upgrade also reads the
[client_other] and [mysql_upgrade_other] groups.

•

--force
Ignore the mysql_upgrade_info file and force execution even if mysql_upgrade has already
been executed for the current version of MySQL.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host. This option was added in MySQL 5.0.30.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysql_upgrade prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections. This option was added in MySQL 5.0.30.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections. This option was added in MySQL 5.0.30.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Client Programs

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”. These options were added in MySQL 5.0.30.

•

--tmpdir=dir_name, -t dir_name
The path name of the directory to use for creating temporary files. This option was added in MySQL
5.0.62.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server. The default user name is root.

•

--verbose
Verbose mode. Print more information about what the program does.

4.5 MySQL Client Programs
This section describes client programs that connect to the MySQL server.

4.5.1 mysql — The MySQL Command-Line Tool
mysql is a simple SQL shell with input line editing capabilities. It supports interactive and
noninteractive use. When used interactively, query results are presented in an ASCII-table format.
When used noninteractively (for example, as a filter), the result is presented in tab-separated format.
The output format can be changed using command options.
If you have problems due to insufficient memory for large result sets, use the --quick option.
This forces mysql to retrieve results from the server a row at a time rather than retrieving the
entire result set and buffering it in memory before displaying it. This is done by returning the
result set using the mysql_use_result() C API function in the client/server library rather than
mysql_store_result().
Using mysql is very easy. Invoke it from the prompt of your command interpreter as follows:
shell> mysql db_name

Or:
shell> mysql --user=user_name --password=your_password db_name

Then type an SQL statement, end it with “;”, \g, or \G and press Enter.
As of MySQL 5.0.25, typing Control+C causes mysql to attempt to kill the current statement. If this
cannot be done, or Control+C is typed again before the statement is killed, mysql exits. Previously,
Control+C caused mysql to exit in all cases.
You can execute SQL statements in a script file (batch file) like this:
shell> mysql db_name < script.sql > output.tab

On Unix, the mysql client logs statements executed interactively to a history file. See Section 4.5.1.3,
“mysql Logging”.

4.5.1.1 mysql Options
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

mysql supports the following options, which can be specified on the command line or in the [mysql]
and [client] groups of an option file. For information about option files used by MySQL programs,
see Section 4.2.6, “Using Option Files”.
Table 4.3 mysql Options
Format

Description

--auto-rehash

Enable automatic rehashing

--batch

Do not use history file

--character-sets-dir

Directory where character sets are installed

--column-names

Write column names in results

--comments

Whether to retain or strip comments in statements sent to 5.0.52
the server

--compress

Compress all information sent between client and server

--connect_timeout

Number of seconds before connection timeout

--database

The database to use

--debug

Write debugging log; supported only if MySQL was built
with debugging support

--debug-info

Print debugging information, memory, and CPU statistics
when program exits

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--delimiter

Set the statement delimiter

--execute

Execute the statement and quit

--force

Continue even if an SQL error occurs

--help

Display help message and exit

--host

Connect to MySQL server on given host

--html

Produce HTML output

--ignore-spaces

Ignore spaces after function names

--line-numbers

Write line numbers for errors

--local-infile

Enable or disable for LOCAL capability for LOAD DATA
INFILE

--max_allowed_packet

Maximum packet length to send to or receive from server

--max_join_size

The automatic limit for rows in a join when using --safeupdates

--named-commands

Enable named mysql commands

--net_buffer_length

Buffer size for TCP/IP and socket communication

--no-auto-rehash

Disable automatic rehashing

--no-beep

Do not beep when errors occur

--no-defaults

Read no option files

--no-named-commands

Disable named mysql commands

--no-pager

Deprecated form of --skip-pager

--no-tee

Do not copy output to a file

This
documentation
is for an
older version.
If you're

Introduced

5.0.10

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Format

Description

--one-database

Ignore statements except those for the default database
named on the command line

--pager

Use the given command for paging query output

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--prompt

Set the prompt to the specified format

--protocol

Connection protocol to use

--quick

Do not cache each query result

--raw

Write column values without escape conversion

--reconnect

If the connection to the server is lost, automatically try to
reconnect

--i-am-a-dummy, --safeupdates

Allow only UPDATE and DELETE statements that
specify key values

--secure-auth

Do not send passwords to server in old (pre-4.1) format

--select_limit

The automatic limit for SELECT statements when using
--safe-updates

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--show-warnings

Show warnings after each statement if there are any

--sigint-ignore

Ignore SIGINT signals (typically the result of typing
Control+C)

--silent

Silent mode

--skip-auto-rehash

Disable automatic rehashing

--skip-column-names

Do not write column names in results

--skip-line-numbers

Skip line numbers for errors

--skip-named-commands

Disable named mysql commands

--skip-pager

Disable paging

--skip-reconnect

Disable reconnecting

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--table

Display output in tabular format

--tee

Append a copy of output to named file

--unbuffered

Flush the buffer after each query

This
documentation
is for an
older version.
If you're

Introduced

5.0.6

5.0.23

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Format

Description

--user

MySQL user name to use when connecting to server

--verbose

Verbose mode

--version

Display version information and exit

--vertical

Print query output rows vertically (one line per column
value)

--wait

If the connection cannot be established, wait and retry
instead of aborting

--xml

Produce XML output

•

Introduced

--help, -?
Display a help message and exit.

•

--auto-rehash
Enable automatic rehashing. This option is on by default, which enables database, table, and column
name completion. Use --disable-auto-rehash to disable rehashing. That causes mysql to start
faster, but you must issue the rehash command if you want to use name completion.
To complete a name, enter the first part and press Tab. If the name is unambiguous, mysql
completes it. Otherwise, you can press Tab again to see the possible names that begin with what
you have typed so far. Completion does not occur if there is no default database.

•

--batch, -B
Print results using tab as the column separator, with each row on a new line. With this option, mysql
does not use the history file.
Batch mode results in nontabular output format and escaping of special characters. Escaping may be
disabled by using raw mode; see the description for the --raw option.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--column-names
Write column names in results.

•

--comments, -c
Whether to preserve comments in statements sent to the server. The default is --skip-comments
(discard comments), enable with --comments (preserve comments). This option was added in
MySQL 5.0.52.

•

--compress, -C
Compress all information sent between the client and the server if both support compression.

•

--database=db_name, -D db_name
The database to use. This is useful primarily in an option file.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o,/tmp/mysql.trace.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

This option is available only if MySQL was built using --with-debug. MySQL release binaries are
not built using this option.
•

--debug-info, -T
Print some debugging information when the program exits.

•

--default-character-set=charset_name
Use charset_name as the default character set for the client and connection.
A common issue that can occur when the operating system uses utf8 or another multibyte
character set is that output from the mysql client is formatted incorrectly, due to the fact that the
MySQL client uses the latin1 character set by default. You can usually fix such issues by using
this option to force the client to use the system character set instead.
See Section 10.5, “Character Set Configuration”, for more information.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str. For
example, mysql normally reads the [client] and [mysql] groups. If the --defaults-groupsuffix=_other option is given, mysql also reads the [client_other] and [mysql_other]
groups. This option was added in MySQL 5.0.10.

•

--delimiter=str
Set the statement delimiter. The default is the semicolon character (“;”).

•

--disable-named-commands
Disable named commands. Use the \* form only, or use named commands only at the beginning
of a line ending with a semicolon (“;”). mysql starts with this option enabled by default. However,
even with this option, long-format commands still work from the first line. See Section 4.5.1.2, “mysql
Commands”.

•

--execute=statement, -e statement
Execute the statement and quit. The default output format is like that produced with --batch. See
Section 4.2.4, “Using Options on the Command Line”, for some examples. With this option, mysql
does not use the history file.

•

--force, -f
Continue even if an SQL error occurs.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--html, -H

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Produce HTML output.
•

--ignore-spaces, -i
Ignore spaces after function names. The effect of this is described in the discussion for the
IGNORE_SPACE SQL mode (see Section 5.1.7, “Server SQL Modes”).

•

--line-numbers
Write line numbers for errors. Disable this with --skip-line-numbers.

•

--local-infile[={0|1}]
Enable or disable LOCAL capability for LOAD DATA INFILE. With no value, the option enables
LOCAL. The option may be given as --local-infile=0 or --local-infile=1 to explicitly
disable or enable LOCAL. Enabling LOCAL has no effect if the server does not also support it.

•

--named-commands, -G
Enable named mysql commands. Long-format commands are permitted, not just short-format
commands. For example, quit and \q both are recognized. Use --skip-named-commands to
disable named commands. See Section 4.5.1.2, “mysql Commands”.

•

--no-auto-rehash, -A
This has the same effect as --skip-auto-rehash. See the description for --auto-rehash.

•

--no-beep, -b
Do not beep when errors occur.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--no-named-commands, -g
Deprecated, use --disable-named-commands instead. --no-named-commands is removed in
MySQL 5.5.

•

--no-pager
Deprecated form of --skip-pager. See the --pager option. --no-pager is removed in MySQL
5.5.

•

--no-tee
Deprecated form of --skip-tee. See the --tee option. --no-tee is removed in MySQL 5.5.

•

--one-database, -o
Ignore statements except those that occur while the default database is the one named on the
command line. This option is rudimentary and should be used with care. Statement filtering is based
only on USE statements.
Initially, mysql executes statements in the input because specifying a database db_name on the
command line is equivalent to inserting USE db_name at the beginning of the input. Then, for each
USE statement encountered, mysql accepts or rejects following statements depending on whether
the database named is the one on the command line. The content of the statements is immaterial.
Suppose that mysql is invoked to process this set of statements:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

DELETE FROM db2.t2;
USE db2;
DROP TABLE db1.t1;
CREATE TABLE db1.t1 (i INT);
USE db1;
INSERT INTO t1 (i) VALUES(1);
CREATE TABLE db2.t1 (j INT);

If the command line is mysql --force --one-database db1, mysql handles the input as
follows:
• The DELETE statement is executed because the default database is db1, even though the
statement names a table in a different database.
• The DROP TABLE and CREATE TABLE statements are not executed because the default database
is not db1, even though the statements name a table in db1.
• The INSERT and CREATE TABLE statements are executed because the default database is db1,
even though the CREATE TABLE statement names a table in a different database.
•

--pager[=command]
Use the given command for paging query output. If the command is omitted, the default pager is the
value of your PAGER environment variable. Valid pagers are less, more, cat [> filename],
and so forth. This option works only on Unix and only in interactive mode. To disable paging, use -skip-pager. Section 4.5.1.2, “mysql Commands”, discusses output paging further.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysql prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--prompt=format_str
Set the prompt to the specified format. The default is mysql>. The special sequences that the
prompt can contain are described in Section 4.5.1.2, “mysql Commands”.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--quick, -q

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Do not cache each query result, print each row as it is received. This may slow down the server if the
output is suspended. With this option, mysql does not use the history file.
•

--raw, -r
For tabular output, the “boxing” around columns enables one column value to be distinguished from
another. For nontabular output (such as is produced in batch mode or when the --batch or -silent option is given), special characters are escaped in the output so they can be identified
easily. Newline, tab, NUL, and backslash are written as \n, \t, \0, and \\. The --raw option
disables this character escaping.
The following example demonstrates tabular versus nontabular output and the use of raw mode to
disable escaping:
% mysql
mysql> SELECT CHAR(92);
+----------+
| CHAR(92) |
+----------+
| \
|
+----------+
% mysql -s
mysql> SELECT CHAR(92);
CHAR(92)
\\
% mysql -s -r
mysql> SELECT CHAR(92);
CHAR(92)
\

•

--reconnect
If the connection to the server is lost, automatically try to reconnect. A single reconnect attempt
is made each time the connection is lost. To suppress reconnection behavior, use --skipreconnect.

•

--safe-updates, --i-am-a-dummy, -U
Permit only those UPDATE and DELETE statements that specify which rows to modify by using key
values. If you have set this option in an option file, you can override it by using --safe-updates on
the command line. See Section 4.5.1.6, “mysql Tips”, for more information about this option.

•

--secure-auth
Do not send passwords to the server in old (pre-4.1) format. This prevents connections except for
servers that use the newer password format.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

•

--show-warnings
Cause warnings to be shown after each statement if there are any. This option applies to interactive
and batch mode. This option was added in MySQL 5.0.6.

•

--sigint-ignore

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Ignore SIGINT signals (typically the result of typing Control+C).
•

--silent, -s
Silent mode. Produce less output. This option can be given multiple times to produce less and less
output.
This option results in nontabular output format and escaping of special characters. Escaping may be
disabled by using raw mode; see the description for the --raw option.

•

--skip-column-names, -N
Do not write column names in results.

•

--skip-line-numbers, -L
Do not write line numbers for errors. Useful when you want to compare result files that include error
messages.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--table, -t
Display output in table format. This is the default for interactive use, but can be used to produce table
output in batch mode.

•

--tee=file_name
Append a copy of output to the given file. This option works only in interactive mode. Section 4.5.1.2,
“mysql Commands”, discusses tee files further.

•

--unbuffered, -n
Flush the buffer after each query.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Produce more output about what the program does. This option can be given
multiple times to produce more and more output. (For example, -v -v -v produces table output
format even in batch mode.)

•

--version, -V
Display version information and exit.

•

--vertical, -E
Print query output rows vertically (one line per column value). Without this option, you can specify
vertical output for individual statements by terminating them with \G.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

•

--wait, -w
If the connection cannot be established, wait and retry instead of aborting.

•

--xml, -X
Produce XML output.
Note
Prior to MySQL 5.0.26, there was no differentiation in the output when
using this option between columns containing the NULL value and columns
containing the string literal 'NULL'; both were represented as
NULL

Beginning with MySQL 5.0.26, the output when --xml is used with mysql matches that of
mysqldump --xml. See Section 4.5.4, “mysqldump — A Database Backup Program” for details.
Beginning with MySQL 5.0.40, the XML output also uses an XML namespace, as shown here:
shell> mysql --xml -uroot -e "SHOW VARIABLES LIKE 'version%'"


version
5.0.40-debug


version_comment
Source distribution


version_compile_machine
i686


version_compile_os
suse-linux-gnu



(See Bug #25946.)
You can also set the following variables by using --var_name=value. The --set-variable format
is deprecated.
•

connect_timeout
The number of seconds before connection timeout. (Default value is 0.)

• max_allowed_packet
The maximum size of the buffer for client/server communication. The default is 16MB, the maximum
is 1GB.
• max_join_size
The automatic limit for rows in a join when using --safe-updates. (Default value is 1,000,000.)
• net_buffer_length

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

The buffer size for TCP/IP and socket communication. (Default value is 16KB.)
• select_limit
The automatic limit for SELECT statements when using --safe-updates. (Default value is 1,000.)
It is also possible to set variables by using --var_name=value. The --set-variable format is
deprecated.

4.5.1.2 mysql Commands
mysql sends each SQL statement that you issue to the server to be executed. There is also a set of
commands that mysql itself interprets. For a list of these commands, type help or \h at the mysql>
prompt:
mysql> help
List of all MySQL commands:
Note that all text commands must be first on line and end with ';'
?
(\?) Synonym for `help'.
clear
(\c) Clear command.
connect
(\r) Reconnect to the server. Optional arguments are db and host.
delimiter (\d) Set statement delimiter.
edit
(\e) Edit command with $EDITOR.
ego
(\G) Send command to mysql server, display result vertically.
exit
(\q) Exit mysql. Same as quit.
go
(\g) Send command to mysql server.
help
(\h) Display this help.
nopager
(\n) Disable pager, print to stdout.
notee
(\t) Don't write into outfile.
pager
(\P) Set PAGER [to_pager]. Print the query results via PAGER.
print
(\p) Print current command.
prompt
(\R) Change your mysql prompt.
quit
(\q) Quit mysql.
rehash
(\#) Rebuild completion hash.
source
(\.) Execute an SQL script file. Takes a file name as an argument.
status
(\s) Get status information from the server.
system
(\!) Execute a system shell command.
tee
(\T) Set outfile [to_outfile]. Append everything into given
outfile.
use
(\u) Use another database. Takes database name as argument.
charset
(\C) Switch to another charset. Might be needed for processing
binlog with multi-byte charsets.
warnings (\W) Show warnings after every statement.
nowarning (\w) Don't show warnings after every statement.
For server side help, type 'help contents'

Each command has both a long and short form. The long form is not case sensitive; the short form is.
The long form can be followed by an optional semicolon terminator, but the short form should not.
The use of short-form commands within multiple-line /* ... */ comments is not supported.
•

help [arg], \h [arg], \? [arg], ? [arg]
Display a help message listing the available mysql commands.
If you provide an argument to the help command, mysql uses it as a search string to access
server-side help from the contents of the MySQL Reference Manual. For more information, see
Section 4.5.1.4, “mysql Server-Side Help”.

•

charset charset_name, \C charset_name
Change the default character set and issue a SET NAMES statement. This enables the character set
to remain synchronized on the client and server if mysql is run with auto-reconnect enabled (which

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

is not recommended), because the specified character set is used for reconnects. This command
was added in MySQL 5.0.19.
•

clear, \c
Clear the current input. Use this if you change your mind about executing the statement that you are
entering.

•

connect [db_name host_name]], \r [db_name host_name]]
Reconnect to the server. The optional database name and host name arguments may be given to
specify the default database or the host where the server is running. If omitted, the current values are
used.

•

delimiter str, \d str
Change the string that mysql interprets as the separator between SQL statements. The default is
the semicolon character (“;”).
The delimiter string can be specified as an unquoted or quoted argument on the delimiter
command line. Quoting can be done with either single quote ('), double quote ("), or backtick (`)
characters. To include a quote within a quoted string, either quote the string with a different quote
character or escape the quote with a backslash (“\”) character. Backslash should be avoided outside
of quoted strings because it is the escape character for MySQL. For an unquoted argument, the
delimiter is read up to the first space or end of line. For a quoted argument, the delimiter is read up to
the matching quote on the line.
mysql interprets instances of the delimiter string as a statement delimiter anywhere it occurs, except
within quoted strings. Be careful about defining a delimiter that might occur within other words. For
example, if you define the delimiter as X, you will be unable to use the word INDEX in statements.
mysql interprets this as INDE followed by the delimiter X.
When the delimiter recognized by mysql is set to something other than the default of “;”, instances
of that character are sent to the server without interpretation. However, the server itself still interprets
“;” as a statement delimiter and processes statements accordingly. This behavior on the server side
comes into play for multiple-statement execution (see Section 20.6.16, “C API Support for Multiple
Statement Execution”), and for parsing the body of stored procedures and functions and triggers (see
Section 18.1, “Defining Stored Programs”).

•

edit, \e
Edit the current input statement. mysql checks the values of the EDITOR and VISUAL environment
variables to determine which editor to use. The default editor is vi if neither variable is set.
The edit command works only in Unix.

•

ego, \G
Send the current statement to the server to be executed and display the result using vertical format.
Be careful about defining a delimiter that might occur within other words. For example, if you define
the delimiter as X, you will be unable to use the word INDEX in statements.

•

exit, \q
Exit mysql.

•

go, \g
Send the current statement to the server to be executed.

•

nopager, \n

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Disable output paging. See the description for pager.
The nopager command works only in Unix.
•

notee, \t
Disable output copying to the tee file. See the description for tee.

•

nowarning, \w
Disable display of warnings after each statement. This command was added in MySQL 5.0.6.

•

pager [command], \P [command]
Enable output paging. By using the --pager option when you invoke mysql, it is possible to
browse or search query results in interactive mode with Unix programs such as less, more, or any
other similar program. If you specify no value for the option, mysql checks the value of the PAGER
environment variable and sets the pager to that. Pager functionality works only in interactive mode.
Output paging can be enabled interactively with the pager command and disabled with nopager.
The command takes an optional argument; if given, the paging program is set to that. With no
argument, the pager is set to the pager that was set on the command line, or stdout if no pager
was specified.
Output paging works only in Unix because it uses the popen() function, which does not exist on
Windows. For Windows, the tee option can be used instead to save query output, although it is not
as convenient as pager for browsing output in some situations.

•

print, \p
Print the current input statement without executing it.

•

prompt [str], \R [str]
Reconfigure the mysql prompt to the given string. The special character sequences that can be
used in the prompt are described later in this section.
If you specify the prompt command with no argument, mysql resets the prompt to the default of
mysql>.

•

quit, \q
Exit mysql.

•

rehash, \#
Rebuild the completion hash that enables database, table, and column name completion while you
are entering statements. (See the description for the --auto-rehash option.)

•

source file_name, \. file_name
Read the named file and executes the statements contained therein. On Windows, you can specify
path name separators as / or \\.

•

status, \s
Provide status information about the connection and the server you are using. If you are running in
--safe-updates mode, status also prints the values for the mysql variables that affect your
queries.

• system command, \! command
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Execute the given command using your default command interpreter.
The system command works only in Unix.
•

tee [file_name], \T [file_name]
By using the --tee option when you invoke mysql, you can log statements and their output. All the
data displayed on the screen is appended into a given file. This can be very useful for debugging
purposes also. mysql flushes results to the file after each statement, just before it prints its next
prompt. Tee functionality works only in interactive mode.
You can enable this feature interactively with the tee command. Without a parameter, the previous
file is used. The tee file can be disabled with the notee command. Executing tee again re-enables
logging.

•

use db_name, \u db_name
Use db_name as the default database.

•

warnings, \W
Enable display of warnings after each statement (if there are any). This command was added in
MySQL 5.0.6.

Here are a few tips about the pager command:
• You can use it to write to a file and the results go only to the file:
mysql> pager cat > /tmp/log.txt

You can also pass any options for the program that you want to use as your pager:
mysql> pager less -n -i -S

• In the preceding example, note the -S option. You may find it very useful for browsing wide query
results. Sometimes a very wide result set is difficult to read on the screen. The -S option to less
can make the result set much more readable because you can scroll it horizontally using the leftarrow and right-arrow keys. You can also use -S interactively within less to switch the horizontalbrowse mode on and off. For more information, read the less manual page:
shell> man less

• The -F and -X options may be used with less to cause it to exit if output fits on one screen, which
is convenient when no scrolling is necessary:
mysql> pager less -n -i -S -F -X

• You can specify very complex pager commands for handling query output:
mysql> pager cat | tee /dr1/tmp/res.txt \
| tee /dr2/tmp/res2.txt | less -n -i -S

In this example, the command would send query results to two files in two different directories on two
different file systems mounted on /dr1 and /dr2, yet still display the results onscreen using less.
You can also combine the tee and pager functions. Have a tee file enabled and pager set to less,
and you are able to browse the results using the less program and still have everything appended
into a file the same time. The difference between the Unix tee used with the pager command and
the mysql built-in tee command is that the built-in tee works even if you do not have the Unix tee

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

available. The built-in tee also logs everything that is printed on the screen, whereas the Unix tee
used with pager does not log quite that much. Additionally, tee file logging can be turned on and
off interactively from within mysql. This is useful when you want to log some queries to a file, but not
others.
The prompt command reconfigures the default mysql> prompt. The string for defining the prompt can
contain the following special sequences.
Option

Description

\c

A counter that increments for each statement you issue

\D

The full current date

\d

The default database

\h

The server host

\l

The current delimiter (new in 5.0.25)

\m

Minutes of the current time

\n

A newline character

\O

The current month in three-letter format (Jan, Feb, …)

\o

The current month in numeric format

\P

am/pm

\p

The current TCP/IP port or socket file

\R

The current time, in 24-hour military time (0–23)

\r

The current time, standard 12-hour time (1–12)

\S

Semicolon

\s

Seconds of the current time

\t

A tab character

\U

Your full user_name@host_name account name

\u

Your user name

\v

The server version

\w

The current day of the week in three-letter format (Mon, Tue, …)

\Y

The current year, four digits

\y

The current year, two digits

\_

A space

\

A space (a space follows the backslash)

\'

Single quote

\"

Double quote

\\

A literal “\” backslash character

\x

x, for any “x” not listed above

You can set the prompt in several ways:
• Use an environment variable. You can set the MYSQL_PS1 environment variable to a prompt string.
For example:
shell> export MYSQL_PS1="(\u@\h) [\d]> "

• Use a command-line option. You can set the --prompt option on the command line to mysql. For
example:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

shell> mysql --prompt="(\u@\h) [\d]> "
(user@host) [database]>

• Use an option file. You can set the prompt option in the [mysql] group of any MySQL option file,
such as /etc/my.cnf or the .my.cnf file in your home directory. For example:
[mysql]
prompt=(\\u@\\h) [\\d]>\\_

In this example, note that the backslashes are doubled. If you set the prompt using the prompt
option in an option file, it is advisable to double the backslashes when using the special prompt
options. There is some overlap in the set of permissible prompt options and the set of special escape
sequences that are recognized in option files. (The rules for escape sequences in option files are
listed in Section 4.2.6, “Using Option Files”.) The overlap may cause you problems if you use single
backslashes. For example, \s is interpreted as a space rather than as the current seconds value.
The following example shows how to define a prompt within an option file to include the current time
in HH:MM:SS> format:
[mysql]
prompt="\\r:\\m:\\s> "

• Set the prompt interactively. You can change your prompt interactively by using the prompt (or \R)
command. For example:
mysql> prompt (\u@\h) [\d]>\_
PROMPT set to '(\u@\h) [\d]>\_'
(user@host) [database]>
(user@host) [database]> prompt
Returning to default PROMPT of mysql>
mysql>

4.5.1.3 mysql Logging
On Unix, the mysql client logs statements executed interactively to a history file. By default, this file
is named .mysql_history in your home directory. To specify a different file, set the value of the
MYSQL_HISTFILE environment variable.

How Logging Occurs
Statement logging occurs as follows:
• Statements are logged only when executed interactively. Statements are noninteractive, for example,
when read from a file or a pipe. It is also possible to suppress statement logging by using the -batch or --execute option.
• mysql logs each nonempty statement line individually.
• If a statement spans multiple lines (not including the terminating delimiter), mysql concatenates the
lines to form the complete statement, maps newlines to spaces, and logs the result, plus a delimiter.
Consequently, an input statement that spans multiple lines can be logged twice. Consider this input:
mysql>
->
->
->
->

SELECT
'Today is'
,
CURDATE()
;

In this case, mysql logs the “SELECT”, “'Today is'”, “,”, “CURDATE()”, and “;” lines as it reads them.
It also logs the complete statement, after mapping SELECT\n'Today is'\n,\nCURDATE() to
SELECT 'Today is' , CURDATE(), plus a delimiter. Thus, these lines appear in logged output:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

SELECT
'Today is'
,
CURDATE()
;
SELECT 'Today is' , CURDATE();

Controlling the History File
The .mysql_history file should be protected with a restrictive access mode because sensitive
information might be written to it, such as the text of SQL statements that contain passwords. See
Section 6.1.2.1, “End-User Guidelines for Password Security”.
If you do not want to maintain a history file, first remove .mysql_history if it exists. Then use either
of the following techniques to prevent it from being created again:
• Set the MYSQL_HISTFILE environment variable to /dev/null. To cause this setting to take effect
each time you log in, put it in one of your shell's startup files.
• Create .mysql_history as a symbolic link to /dev/null; this need be done only once:
shell> ln -s /dev/null $HOME/.mysql_history

4.5.1.4 mysql Server-Side Help
mysql> help search_string

If you provide an argument to the help command, mysql uses it as a search string to access serverside help from the contents of the MySQL Reference Manual. The proper operation of this command
requires that the help tables in the mysql database be initialized with help topic information (see
Section 5.1.8, “Server-Side Help”).
If there is no match for the search string, the search fails:
mysql> help me
Nothing found
Please try to run 'help contents' for a list of all accessible topics

Use help contents to see a list of the help categories:
mysql> help contents
You asked for help about help category: "Contents"
For more information, type 'help ', where  is one of the
following categories:
Account Management
Administration
Data Definition
Data Manipulation
Data Types
Functions
Functions and Modifiers for Use with GROUP BY
Geographic Features
Language Structure
Storage Engines
Stored Routines
Table Maintenance
Transactions
Triggers

If the search string matches multiple items, mysql shows a list of matching topics:
mysql> help logs
Many help items for your request exist.
To make a more specific request, please type 'help ',

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

where  is one of the following topics:
SHOW
SHOW BINARY LOGS
SHOW ENGINE
SHOW LOGS

Use a topic as the search string to see the help entry for that topic:
mysql> help show binary logs
Name: 'SHOW BINARY LOGS'
Description:
Syntax:
SHOW BINARY LOGS
SHOW MASTER LOGS
Lists the binary log files on the server. This statement is used as
part of the procedure described in [purge-binary-logs], that shows how
to determine which logs can be purged.
mysql> SHOW BINARY LOGS;
+---------------+-----------+
| Log_name
| File_size |
+---------------+-----------+
| binlog.000015 |
724935 |
| binlog.000016 |
733481 |
+---------------+-----------+

The search string can contain the wildcard characters “%” and “_”. These have the same meaning as
for pattern-matching operations performed with the LIKE operator. For example, HELP rep% returns a
list of topics that begin with rep:
mysql> HELP rep%
Many help items for your request exist.
To make a more specific request, please type 'help ',
where  is one of the following
topics:
REPAIR TABLE
REPEAT FUNCTION
REPEAT LOOP
REPLACE
REPLACE FUNCTION

4.5.1.5 Executing SQL Statements from a Text File
The mysql client typically is used interactively, like this:
shell> mysql db_name

However, it is also possible to put your SQL statements in a file and then tell mysql to read its input
from that file. To do so, create a text file text_file that contains the statements you wish to execute.
Then invoke mysql as shown here:
shell> mysql db_name < text_file

If you place a USE db_name statement as the first statement in the file, it is unnecessary to specify the
database name on the command line:
shell> mysql < text_file

If you are already running mysql, you can execute an SQL script file using the source command or
\. command:
mysql> source file_name
mysql> \. file_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

Sometimes you may want your script to display progress information to the user. For this you can insert
statements like this:
SELECT '' AS ' ';

The statement shown outputs .
You can also invoke mysql with the --verbose option, which causes each statement to be displayed
before the result that it produces.
As of MySQL 5.0.54, mysql ignores Unicode byte order mark (BOM) characters at the beginning of
input files. Previously, it read them and sent them to the server, resulting in a syntax error. Presence
of a BOM does not cause mysql to change its default character set. To do that, invoke mysql with an
option such as --default-character-set=utf8.
For more information about batch mode, see Section 3.5, “Using mysql in Batch Mode”.

4.5.1.6 mysql Tips
This section describes some techniques that can help you use mysql more effectively.

Input-Line Editing
mysql supports input-line editing, which enables you to modify the current input line in place or recall
previous input lines. For example, the left-arrow and right-arrow keys move horizontally within the
current input line, and the up-arrow and down-arrow keys move up and down through the set of
previously entered lines. Backspace deletes the character before the cursor and typing new characters
enters them at the cursor position. To enter the line, press Enter.
On Windows, the editing key sequences are the same as supported for command editing in console
windows. On Unix, the key sequences depend on the input library used to build mysql (for example,
the libedit or readline library).
Documentation for the libedit and readline libraries is available online. To change the set of key
sequences permitted by a given input library, define key bindings in the library startup file. This is a file
in your home directory: .editrc for libedit and .inputrc for readline.
For example, in libedit, Control+W deletes everything before the current cursor position and
Control+U deletes the entire line. In readline, Control+W deletes the word before the cursor and
Control+U deletes everything before the current cursor position. If mysql was built using libedit, a
user who prefers the readline behavior for these two keys can put the following lines in the .editrc
file (creating the file if necessary):
bind "^W" ed-delete-prev-word
bind "^U" vi-kill-line-prev

To see the current set of key bindings, temporarily put a line that says only bind at the end of
.editrc. mysql will show the bindings when it starts.

Displaying Query Results Vertically
Some query results are much more readable when displayed vertically, instead of in the usual
horizontal table format. Queries can be displayed vertically by terminating the query with \G instead of
a semicolon. For example, longer text values that include newlines often are much easier to read with
vertical output:
mysql> SELECT * FROM mails WHERE LENGTH(txt) < 300 LIMIT 300,1\G
*************************** 1. row ***************************
msg_nro: 3068
date: 2000-03-01 23:29:50
time_zone: +0200
mail_from: Monty

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql — The MySQL Command-Line Tool

reply:
mail_to:
sbj:
txt:

monty@no.spam.com
"Thimble Smith" 
UTF-8
>>>>> "Thimble" == Thimble Smith writes:

Thimble> Hi. I think this is a good idea. Is anyone familiar
Thimble> with UTF-8 or Unicode? Otherwise, I'll put this on my
Thimble> TODO list and see what happens.
Yes, please do that.
Regards,
Monty
file: inbox-jani-1
hash: 190402944
1 row in set (0.09 sec)

Using the --safe-updates Option
For beginners, a useful startup option is --safe-updates (or --i-am-a-dummy, which has
the same effect). It is helpful for cases when you might have issued a DELETE FROM tbl_name
statement but forgotten the WHERE clause. Normally, such a statement deletes all rows from the table.
With --safe-updates, you can delete rows only by specifying the key values that identify them. This
helps prevent accidents.
When you use the --safe-updates option, mysql issues the following statement when it connects
to the MySQL server:
SET sql_safe_updates=1, sql_select_limit=1000, sql_max_join_size=1000000;

See Section 5.1.4, “Server System Variables”.
The SET statement has the following effects:
• You are not permitted to execute an UPDATE or DELETE statement unless you specify a key
constraint in the WHERE clause or provide a LIMIT clause (or both). For example:
UPDATE tbl_name SET not_key_column=val WHERE key_column=val;
UPDATE tbl_name SET not_key_column=val LIMIT 1;

• The server limits all large SELECT results to 1,000 rows unless the statement includes a LIMIT
clause.
• The server aborts multiple-table SELECT statements that probably need to examine more than
1,000,000 row combinations.
To specify limits different from 1,000 and 1,000,000, you can override the defaults by using the -select_limit and --max_join_size options:
shell> mysql --safe-updates --select_limit=500 --max_join_size=10000

Disabling mysql Auto-Reconnect
If the mysql client loses its connection to the server while sending a statement, it immediately and
automatically tries to reconnect once to the server and send the statement again. However, even if
mysql succeeds in reconnecting, your first connection has ended and all your previous session objects
and settings are lost: temporary tables, the autocommit mode, and user-defined and session variables.
Also, any current transaction rolls back. This behavior may be dangerous for you, as in the following
example where the server was shut down and restarted between the first and second statements
without you knowing it:
mysql> SET @a=1;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

Query OK, 0 rows affected (0.05 sec)
mysql> INSERT INTO t VALUES(@a);
ERROR 2006: MySQL server has gone away
No connection. Trying to reconnect...
Connection id:
1
Current database: test
Query OK, 1 row affected (1.30 sec)
mysql> SELECT * FROM t;
+------+
| a
|
+------+
| NULL |
+------+
1 row in set (0.05 sec)

The @a user variable has been lost with the connection, and after the reconnection it is undefined. If it
is important to have mysql terminate with an error if the connection has been lost, you can start the
mysql client with the --skip-reconnect option.
For more information about auto-reconnect and its effect on state information when a reconnection
occurs, see Section 20.6.15, “Controlling Automatic Reconnection Behavior”.

4.5.2 mysqladmin — Client for Administering a MySQL Server
mysqladmin is a client for performing administrative operations. You can use it to check the server's
configuration and current status, to create and drop databases, and more.
Invoke mysqladmin like this:
shell> mysqladmin [options] command [command-arg] [command [command-arg]] ...

mysqladmin supports the following commands. Some of the commands take an argument following
the command name.
• create db_name
Create a new database named db_name.
• debug
Tell the server to write debug information to the error log. Format and content of this information is
subject to change.
• drop db_name
Delete the database named db_name and all its tables.
• extended-status
Display the server status variables and their values.
• flush-hosts
Flush all information in the host cache.
• flush-logs
Flush all logs.
• flush-privileges
Reload the grant tables (same as reload).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

• flush-status
Clear status variables.
• flush-tables
Flush all tables.
• flush-threads
Flush the thread cache.
• kill id,id,...
Kill server threads. If multiple thread ID values are given, there must be no spaces in the list.
• old-password new_password
This is like the password command but stores the password using the old (pre-4.1) passwordhashing format. (See Section 6.1.2.4, “Password Hashing in MySQL”.)
• password new_password
Set a new password. This changes the password to new_password for the account that you use
with mysqladmin for connecting to the server. Thus, the next time you invoke mysqladmin (or any
other client program) using the same account, you will need to specify the new password.
If the new_password value contains spaces or other characters that are special to your command
interpreter, you need to enclose it within quotation marks. On Windows, be sure to use double
quotation marks rather than single quotation marks; single quotation marks are not stripped from the
password, but rather are interpreted as part of the password. For example:
shell> mysqladmin password "my new password"

Caution
Do not use this command used if the server was started with the --skipgrant-tables option. No password change will be applied. This is true
even if you precede the password command with flush-privileges
on the same command line to re-enable the grant tables because the flush
operation occurs after you connect. However, you can use mysqladmin
flush-privileges to re-enable the grant table and then use a separate
mysqladmin password command to change the password.
• ping
Check whether the server is available. The return status from mysqladmin is 0 if the server is
running, 1 if it is not. This is 0 even in case of an error such as Access denied, because this
means that the server is running but refused the connection, which is different from the server not
running.
• processlist
Show a list of active server threads. This is like the output of the SHOW PROCESSLIST statement.
If the --verbose option is given, the output is like that of SHOW FULL PROCESSLIST. (See
Section 13.7.5.27, “SHOW PROCESSLIST Syntax”.)
• reload
Reload the grant tables.
• refresh

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

Flush all tables and close and open log files.
• shutdown
Stop the server.
• start-slave
Start replication on a slave server.
• status
Display a short server status message.
• stop-slave
Stop replication on a slave server.
• variables
Display the server system variables and their values.
• version
Display version information from the server.
All commands can be shortened to any unique prefix. For example:
shell> mysqladmin proc stat
+----+-------+-----------+----+---------+------+-------+------------------+
| Id | User | Host
| db | Command | Time | State | Info
|
+----+-------+-----------+----+---------+------+-------+------------------+
| 51 | monty | localhost |
| Query
| 0
|
| show processlist |
+----+-------+-----------+----+---------+------+-------+------------------+
Uptime: 1473624 Threads: 1 Questions: 39487
Slow queries: 0 Opens: 541 Flush tables: 1
Open tables: 19 Queries per second avg: 0.0268

The mysqladmin status command result displays the following values:
• Uptime
The number of seconds the MySQL server has been running.
• Threads
The number of active threads (clients).
• Questions
The number of questions (queries) from clients since the server was started.
• Slow queries
The number of queries that have taken more than long_query_time seconds. See Section 5.4.4,
“The Slow Query Log”.
• Opens
The number of tables the server has opened.
•

Flush tables

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

The number of flush-*, refresh, and reload commands the server has executed.
• Open tables
The number of tables that currently are open.
• Memory in use
The amount of memory allocated directly by mysqld. This value is displayed only when MySQL has
been compiled with --with-debug=full.
• Maximum memory used
The maximum amount of memory allocated directly by mysqld. This value is displayed only when
MySQL has been compiled with --with-debug=full.
If you execute mysqladmin shutdown when connecting to a local server using a Unix socket file,
mysqladmin waits until the server's process ID file has been removed, to ensure that the server has
stopped properly.
mysqladmin supports the following options, which can be specified on the command line or in the
[mysqladmin] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.4 mysqladmin Options
Format

Description

--compress

Compress all information sent between client and server

--connect_timeout

Number of seconds before connection timeout

--count

Number of iterations to make for repeated command
execution

--debug

Write debugging log

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--force

Continue even if an SQL error occurs

--help

Display help message and exit

--host

Connect to MySQL server on given host

--no-defaults

Read no option files

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--protocol

Connection protocol to use

--relative

Show the difference between the current and previous
values when used with the --sleep option

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--shutdown_timeout

The maximum number of seconds to wait for server
shutdown

--silent

Silent mode

This
documentation
is for an
older version.
If you're

Introduced

5.0.10

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

Format

Description

--sleep

Execute commands repeatedly, sleeping for delay
seconds in between

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--user

MySQL user name to use when connecting to server

--verbose

Verbose mode

--version

Display version information and exit

--vertical

Print query output rows vertically (one line per column
value)

--wait

If the connection cannot be established, wait and retry
instead of aborting

•

Introduced

5.0.23

--help, -?
Display a help message and exit.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--compress, -C
Compress all information sent between the client and the server if both support compression.

•

--count=N, -c N
The number of iterations to make for repeated command execution if the --sleep option is given.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o,/tmp/mysqladmin.trace.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqladmin — Client for Administering a MySQL Server

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of
str. For example, mysqladmin normally reads the [client] and [mysqladmin] groups.
If the --defaults-group-suffix=_other option is given, mysqladmin also reads the
[client_other] and [mysqladmin_other] groups. This option was added in MySQL 5.0.10.

•

--force, -f
Do not ask for confirmation for the drop db_name command. With multiple commands, continue
even if an error occurs.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqladmin prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--relative, -r
Show the difference between the current and previous values when used with the --sleep option.
This option works only with the extended-status command.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

•

--silent, -s
Exit silently if a connection to the server cannot be established.

•

--sleep=delay, -i delay
Execute commands repeatedly, sleeping for delay seconds in between. The --count option
determines the number of iterations. If --count is not given, mysqladmin executes commands
indefinitely until interrupted.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Print more information about what the program does.

•

--version, -V
Display version information and exit.

•

--vertical, -E
Print output vertically. This is similar to --relative, but prints output vertically.

•

--wait[=count], -w[count]
If the connection cannot be established, wait and retry instead of aborting. If a count value is given,
it indicates the number of times to retry. The default is one time.

You can also set the following variables by using --var_name=value The --set-variable format
is deprecated. syntax:
•

connect_timeout
The maximum number of seconds before connection timeout. The default value is 43200 (12 hours).

•

shutdown_timeout
The maximum number of seconds to wait for server shutdown. The default value is 3600 (1 hour).

It is also possible to set variables by using --var_name=value. The --set-variable format is
deprecated.

4.5.3 mysqlcheck — A Table Maintenance Program
The mysqlcheck client performs table maintenance: It checks, repairs, optimizes, or analyzes tables.
Each table is locked and therefore unavailable to other sessions while it is being processed,
although for check operations, the table is locked with a READ lock only (see Section 13.3.5, “LOCK
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

TABLES and UNLOCK TABLES Syntax”, for more information about READ and WRITE locks).
Table maintenance operations can be time-consuming, particularly for large tables. If you use the
--databases or --all-databases option to process all tables in one or more databases, an
invocation of mysqlcheck might take a long time. (This is also true for mysql_upgrade because that
program invokes mysqlcheck to check all tables and repair them if necessary.)
mysqlcheck is similar in function to myisamchk, but works differently. The main operational
difference is that mysqlcheck must be used when the mysqld server is running, whereas
myisamchk should be used when it is not. The benefit of using mysqlcheck is that you do not have to
stop the server to perform table maintenance.
mysqlcheck uses the SQL statements CHECK TABLE, REPAIR TABLE, ANALYZE TABLE, and
OPTIMIZE TABLE in a convenient way for the user. It determines which statements to use for the
operation you want to perform, and then sends the statements to the server to be executed. For details
about which storage engines each statement works with, see the descriptions for those statements in
Section 13.7.2, “Table Maintenance Statements”.
The MyISAM storage engine supports all four maintenance operations, so mysqlcheck can be
used to perform any of them on MyISAM tables. Other storage engines do not necessarily support all
operations. In such cases, an error message is displayed. For example, if test.t is a MEMORY table,
an attempt to check it produces this result:
shell> mysqlcheck test t
test.t
note
: The storage engine for the table doesn't support check

If mysqlcheck is unable to repair a table, see Section 2.19.4, “Rebuilding or Repairing Tables or
Indexes” for manual table repair strategies. This will be the case, for example, for InnoDB tables,
which can be checked with CHECK TABLE, but not repaired with REPAIR TABLE.
Caution
It is best to make a backup of a table before performing a table repair operation;
under some circumstances the operation might cause data loss. Possible
causes include but are not limited to file system errors.
There are three general ways to invoke mysqlcheck:
shell> mysqlcheck [options] db_name [tbl_name ...]
shell> mysqlcheck [options] --databases db_name ...
shell> mysqlcheck [options] --all-databases

If you do not name any tables following db_name or if you use the --databases or --alldatabases option, entire databases are checked.
mysqlcheck has a special feature compared to other client programs. The default behavior of
checking tables (--check) can be changed by renaming the binary. If you want to have a tool that
repairs tables by default, you should just make a copy of mysqlcheck named mysqlrepair, or make
a symbolic link to mysqlcheck named mysqlrepair. If you invoke mysqlrepair, it repairs tables.
The names shown in the following table can be used to change mysqlcheck default behavior.
Command

Meaning

mysqlrepair

The default option is --repair

mysqlanalyze

The default option is --analyze

mysqloptimize

The default option is --optimize

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

mysqlcheck supports the following options, which can be specified on the command line or in the
[mysqlcheck] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.5 mysqlcheck Options
Format

Description

--all-databases

Check all tables in all databases

--all-in-1

Execute a single statement for each database that
names all the tables from that database

--analyze

Analyze the tables

--auto-repair

If a checked table is corrupted, automatically fix it

--character-sets-dir

Directory where character sets are installed

--check

Check the tables for errors

--check-only-changed

Check only tables that have changed since the last check

--check-upgrade

Invoke CHECK TABLE with the FOR UPGRADE option

--compress

Compress all information sent between client and server

--databases

Interpret all arguments as database names

--debug

Write debugging log

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--extended

Check and repair tables

--fast

Check only tables that have not been closed properly

--force

Continue even if an SQL error occurs

--help

Display help message and exit

--host

Connect to MySQL server on given host

--medium-check

Do a check that is faster than an --extended operation

--no-defaults

Read no option files

--optimize

Optimize the tables

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--protocol

Connection protocol to use

--quick

The fastest method of checking

--repair

Perform a repair that can fix almost anything except
unique keys that are not unique

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--silent

Silent mode

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

This
documentation
is for an
older version.
If you're

Introduced

5.0.19

5.0.10

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

Format

Description

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--tables

Overrides the --databases or -B option

--use-frm

For repair operations on MyISAM tables

--user

MySQL user name to use when connecting to server

--verbose

Verbose mode

--version

Display version information and exit

•

Introduced

5.0.23

--help, -?
Display a help message and exit.

•

--all-databases, -A
Check all tables in all databases. This is the same as using the --databases option and naming all
the databases on the command line.

•

--all-in-1, -1
Instead of issuing a statement for each table, execute a single statement for each database that
names all the tables from that database to be processed.

•

--analyze, -a
Analyze the tables.

•

--auto-repair
If a checked table is corrupted, automatically fix it. Any necessary repairs are done after all tables
have been checked.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--check, -c
Check the tables for errors. This is the default operation.

•

--check-only-changed, -C
Check only tables that have changed since the last check or that have not been closed properly.

•

--check-upgrade, -g
Invoke CHECK TABLE with the FOR UPGRADE option to check tables for incompatibilities with the
current version of the server. This option was added in MySQL 5.0.19.

•

--compress
Compress all information sent between the client and the server if both support compression.

•

--databases, -B

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

Process all tables in the named databases. Normally, mysqlcheck treats the first name argument
on the command line as a database name and any following names as table names. With this option,
it treats all name arguments as database names.
•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of
str. For example, mysqlcheck normally reads the [client] and [mysqlcheck] groups.
If the --defaults-group-suffix=_other option is given, mysqlcheck also reads the
[client_other] and [mysqlcheck_other] groups. This option was added in MySQL 5.0.10.

•

--extended, -e
If you are using this option to check tables, it ensures that they are 100% consistent but takes a long
time.
If you are using this option to repair tables, it runs an extended repair that may not only take a long
time to execute, but may produce a lot of garbage rows also!

•

--fast, -F
Check only tables that have not been closed properly.

•

--force, -f
Continue even if an SQL error occurs.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--medium-check, -m
Do a check that is faster than an --extended operation. This finds only 99.99% of all errors, which
should be good enough in most cases.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--optimize, -o

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlcheck — A Table Maintenance Program

Optimize the tables.
•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqlcheck prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--quick, -q
If you are using this option to check tables, it prevents the check from scanning the rows to check for
incorrect links. This is the fastest check method.
If you are using this option to repair tables, it tries to repair only the index tree. This is the fastest
repair method.

•

--repair, -r
Perform a repair that can fix almost anything except unique keys that are not unique.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

•

--silent, -s
Silent mode. Print only error messages.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

• --ssl*
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.
•

--tables
Override the --databases or -B option. All name arguments following the option are regarded as
table names.

•

--use-frm
For repair operations on MyISAM tables, get the table structure from the .frm file so that the table
can be repaired even if the .MYI header is corrupted.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Print information about the various stages of program operation.

•

--version, -V
Display version information and exit.

4.5.4 mysqldump — A Database Backup Program
The mysqldump client is a backup program originally written by Igor Romanenko. It can be used
to dump a database or a collection of databases for backup or transfer to another SQL server (not
necessarily a MySQL server). The dump typically contains SQL statements to create the table,
populate it, or both. However, mysqldump can also be used to generate files in CSV, other delimited
text, or XML format.
mysqldump requires at least the SELECT privilege for dumped tables, SHOW VIEW for dumped views,
SUPER for dumped triggers, and LOCK TABLES if the --single-transaction option is not used.
Certain options might require other privileges as noted in the option descriptions.
To reload a dump file, you must have the privileges required to execute the statements that it contains,
such as the appropriate CREATE privileges for objects created by those statements.
If you are doing a backup on the server and your tables all are MyISAM tables, consider using
the mysqlhotcopy instead because it can accomplish faster backups and faster restores. See
Section 4.6.9, “mysqlhotcopy — A Database Backup Program”.
There are three general ways to invoke mysqldump:
shell> mysqldump [options] db_name [tbl_name ...]
shell> mysqldump [options] --databases db_name ...
shell> mysqldump [options] --all-databases

If you do not name any tables following db_name or if you use the --databases or --alldatabases option, entire databases are dumped.
mysqldump does not dump the INFORMATION_SCHEMA database. If you name that database explicitly
on the command line, mysqldump silently ignores it.
To see a list of the options your version of mysqldump supports, execute mysqldump --help.
Some mysqldump options are shorthand for groups of other options:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

• Use of --opt is the same as specifying --add-drop-table, --add-locks, --createoptions, --disable-keys, --extended-insert, --lock-tables, --quick, and --setcharset. All of the options that --opt stands for also are on by default because --opt is on by
default.
• Use of --compact is the same as specifying --skip-add-drop-table, --skip-add-locks,
--skip-comments, --skip-disable-keys, and --skip-set-charset options.
To reverse the effect of a group option, uses its --skip-xxx form (--skip-opt or --skipcompact). It is also possible to select only part of the effect of a group option by following it with
options that enable or disable specific features. Here are some examples:
• To select the effect of --opt except for some features, use the --skip option for each feature. To
disable extended inserts and memory buffering, use --opt --skip-extended-insert --skipquick. (Actually, --skip-extended-insert --skip-quick is sufficient because --opt is on
by default.)
• To reverse --opt for all features except index disabling and table locking, use --skip-opt -disable-keys --lock-tables.
When you selectively enable or disable the effect of a group option, order is important because options
are processed first to last. For example, --disable-keys --lock-tables --skip-opt would not
have the intended effect; it is the same as --skip-opt by itself.
mysqldump can retrieve and dump table contents row by row, or it can retrieve the entire content from
a table and buffer it in memory before dumping it. Buffering in memory can be a problem if you are
dumping large tables. To dump tables row by row, use the --quick option (or --opt, which enables
--quick). The --opt option (and hence --quick) is enabled by default, so to enable memory
buffering, use --skip-quick.
If you are using a recent version of mysqldump to generate a dump to be reloaded into a very old
MySQL server, you should not use the --opt or --extended-insert option. Use --skip-opt
instead.
Before MySQL 4.1.2, out-of-range numeric values such as -inf and inf, as well as NaN (not-anumber) values are dumped by mysqldump as NULL. You can see this using the following sample
table:
mysql> CREATE
mysql> INSERT
mysql> INSERT
mysql> SELECT
+------+
| f
|
+------+
| inf |
| -inf |
+------+

TABLE t (f DOUBLE);
INTO t VALUES(1e+111111111111111111111);
INTO t VALUES(-1e111111111111111111111);
f FROM t;

For this table, mysqldump produces the following data output:
--- Dumping data for table `t`
-INSERT INTO t VALUES (NULL);
INSERT INTO t VALUES (NULL);

The significance of this behavior is that if you dump and restore the table, the new table has contents
that differ from the original contents. This problem is fixed as of MySQL 4.1.2; you cannot insert inf in
the table, so this mysqldump behavior is only relevant when you deal with old servers.
For additional information about mysqldump, see Section 7.4, “Using mysqldump for Backups”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

mysqldump supports the following options, which can be specified on the command line or in the
[mysqldump] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.6 mysqldump Options
Format

Description

--add-drop-database

Add DROP DATABASE statement before each CREATE
DATABASE statement

--add-drop-table

Add DROP TABLE statement before each CREATE
TABLE statement

--add-locks

Surround each table dump with LOCK TABLES and
UNLOCK TABLES statements

--all-databases

Dump all tables in all databases

--allow-keywords

Allow creation of column names that are keywords

--character-sets-dir

Directory where character sets are installed

--comments

Add comments to dump file

--compact

Produce more compact output

--compatible

Produce output that is more compatible with other
database systems or with older MySQL servers

--complete-insert

Use complete INSERT statements that include column
names

--compress

Compress all information sent between client and server

--create-options

Include all MySQL-specific table options in CREATE
TABLE statements

--databases

Interpret all name arguments as database names

--debug

Write debugging log

--debug-info

Print debugging information, memory, and CPU statistics 5.0.32
when program exits

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--delayed-insert

Write INSERT DELAYED statements rather than
INSERT statements

--delete-master-logs

On a master replication server, delete the binary logs
after performing the dump operation

--disable-keys

For each table, surround INSERT statements with
statements to disable and enable keys

--dump-date

Include dump date as "Dump completed on" comment if
--comments is given

--extended-insert

Use multiple-row INSERT syntax

--fields-enclosed-by

This option is used with the --tab option and has the
same meaning as the corresponding clause for LOAD
DATA INFILE

--fields-escaped-by

This option is used with the --tab option and has the
same meaning as the corresponding clause for LOAD
DATA INFILE

This
documentation
is for an
older version.
If you're

Introduced

5.0.10

5.0.52

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

Format

Description

--fields-optionally-enclosed-by

This option is used with the --tab option and has the
same meaning as the corresponding clause for LOAD
DATA INFILE

--fields-terminated-by

This option is used with the --tab option and has the
same meaning as the corresponding clause for LOAD
DATA INFILE

--first-slave

Deprecated; use --lock-all-tables instead

--flush-logs

Flush MySQL server log files before starting dump

--flush-privileges

Emit a FLUSH PRIVILEGES statement after dumping
mysql database

--force

Continue even if an SQL error occurs during a table
dump

--help

Display help message and exit

--hex-blob

Dump binary columns using hexadecimal notation

--host

Host to connect to (IP address or hostname)

--ignore-table

Do not dump given table

--insert-ignore

Write INSERT IGNORE rather than INSERT statements

--lines-terminated-by

This option is used with the --tab option and has the
same meaning as the corresponding clause for LOAD
DATA INFILE

--lock-all-tables

Lock all tables across all databases

--lock-tables

Lock all tables before dumping them

--log-error

Append warnings and errors to named file

--master-data

Write the binary log file name and position to the output

--max_allowed_packet

Maximum packet length to send to or receive from server

--net_buffer_length

Buffer size for TCP/IP and socket communication

--no-autocommit

Enclose the INSERT statements for each dumped table
within SET autocommit = 0 and COMMIT statements

--no-create-db

Do not write CREATE DATABASE statements

--no-create-info

Do not write CREATE TABLE statements that re-create
each dumped table

--no-data

Do not dump table contents

--no-defaults

Read no option files

--no-set-names

Same as --skip-set-charset

--opt

Shorthand for --add-drop-table --add-locks --createoptions --disable-keys --extended-insert --lock-tables -quick --set-charset.

--order-by-primary

Dump each table's rows sorted by its primary key, or by
its first unique index

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--protocol

Connection protocol to use

This
documentation
is for an
older version.
If you're

Introduced

5.0.42

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

Format

Description

--quick

Retrieve rows for a table from the server a row at a time

--quote-names

Quote identifiers within backtick characters

--result-file

Direct output to a given file

--routines

Dump stored routines (procedures and functions) from
dumped databases

--set-charset

Add SET NAMES default_character_set to output

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--single-transaction

Issue a BEGIN SQL statement before dumping data from
server

--skip-add-drop-table

Do not add a DROP TABLE statement before each
CREATE TABLE statement

--skip-add-locks

Do not add locks

--skip-comments

Do not add comments to dump file

--skip-compact

Do not produce more compact output

--skip-disable-keys

Do not disable keys

--skip-extended-insert

Turn off extended-insert

--skip-opt

Turn off options set by --opt

--skip-quick

Do not retrieve rows for a table from the server a row at a
time

--skip-quote-names

Do not quote identifiers

--skip-set-charset

Do not write SET NAMES statement

--skip-triggers

Do not dump triggers

5.0.11

--skip-tz-utc

Turn off tz-utc

5.0.15

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--tab

Produce tab-separated data files

--tables

Override --databases or -B option

--triggers

Dump triggers for each dumped table

--tz-utc

Add SET TIME_ZONE='+00:00' to dump file

--user

MySQL user name to use when connecting to server

--verbose

Verbose mode

--version

Display version information and exit

--where

Dump only rows selected by given WHERE condition

--xml

Produce XML output

This
documentation
is for an
older version.
If you're

Introduced

5.0.13

5.0.23

5.0.15

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

•

--help, -?
Display a help message and exit.

•

--add-drop-database
Write a DROP DATABASE statement before each CREATE DATABASE statement. This option is
typically used in conjunction with the --all-databases or --databases option because no
CREATE DATABASE statements are written unless one of those options is specified.

•

--add-drop-table
Write a DROP TABLE statement before each CREATE TABLE statement.

•

--add-locks
Surround each table dump with LOCK TABLES and UNLOCK TABLES statements. This results in
faster inserts when the dump file is reloaded. See Section 8.2.2.1, “Speed of INSERT Statements”.

•

--all-databases, -A
Dump all tables in all databases. This is the same as using the --databases option and naming all
the databases on the command line.

•

--allow-keywords
Permit creation of column names that are keywords. This works by prefixing each column name with
the table name.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--comments, -i
Write additional information in the dump file such as program version, server version, and host. This
option is enabled by default. To suppress this additional information, use --skip-comments.

•

--compact
Produce more compact output. This option enables the --skip-add-drop-table, --skip-addlocks, --skip-comments, --skip-disable-keys, and --skip-set-charset options.
Note
Prior to MySQL 5.0.48, this option did not create valid SQL if the database
dump contained views. The recreation of views requires the creation and
removal of temporary tables and this option suppressed the removal of those
temporary tables. As a workaround, use --compact with the --add-droptable option and then manually adjust the dump file.

•

--compatible=name
Produce output that is more compatible with other database systems or with older MySQL servers.
The value of name can be ansi, mysql323, mysql40, postgresql, oracle, mssql, db2, maxdb,
no_key_options, no_table_options, or no_field_options. To use several values, separate
them by commas. These values have the same meaning as the corresponding options for setting the
server SQL mode. See Section 5.1.7, “Server SQL Modes”.
This option does not guarantee compatibility with other servers. It only enables those SQL mode
values that are currently available for making dump output more compatible. For example, -compatible=oracle does not map data types to Oracle types or use Oracle comment syntax.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

This option requires a server version of 4.1.0 or higher. With older servers, it does nothing.
•

--complete-insert, -c
Use complete INSERT statements that include column names.

•

--compress, -C
Compress all information sent between the client and the server if both support compression.

•

--create-options
Include all MySQL-specific table options in the CREATE TABLE statements.

•

--databases, -B
Dump several databases. Normally, mysqldump treats the first name argument on the command
line as a database name and following names as table names. With this option, it treats all name
arguments as database names. CREATE DATABASE and USE statements are included in the output
before each new database.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default value is
d:t:o,/tmp/mysqldump.trace.

•

--debug-info
Print debugging information and memory and CPU usage statistics when the program exits. This
option was added in MySQL 5.0.32.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”. If
no character set is specified, mysqldump uses utf8.
This option has no effect for output data files produced by using the --tab option. See the
description for that option.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str.
For example, mysqldump normally reads the [client] and [mysqldump] groups. If the -defaults-group-suffix=_other option is given, mysqldump also reads the [client_other]
and [mysqldump_other] groups. This option was added in MySQL 5.0.10.

•

--delayed-insert
Write INSERT DELAYED statements rather than INSERT statements.

•

--delete-master-logs

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

On a master replication server, delete the binary logs by sending a PURGE BINARY LOGS statement
to the server after performing the dump operation. This option automatically enables --masterdata.
•

--disable-keys, -K
For each table, surround the INSERT statements with /*!40000 ALTER TABLE tbl_name
DISABLE KEYS */; and /*!40000 ALTER TABLE tbl_name ENABLE KEYS */; statements.
This makes loading the dump file faster because the indexes are created after all rows are inserted.
This option is effective only for nonunique indexes of MyISAM tables. It has no effect for other tables.

•

--dump-date
If the --comments option is given, mysqldump produces a comment at the end of the dump of the
following form:
-- Dump completed on DATE

However, the date causes dump files taken at different times to appear to be different, even if the
data are otherwise identical. --dump-date and --skip-dump-date control whether the date is
added to the comment. The default is --dump-date (include the date in the comment). --skipdump-date suppresses date printing. This option was added in MySQL 5.0.52.
•

--extended-insert, -e
Write INSERT statements using multiple-row syntax that includes several VALUES lists. This results
in a smaller dump file and speeds up inserts when the file is reloaded.

•

--fields-terminated-by=..., --fields-enclosed-by=..., --fieldsoptionally-enclosed-by=..., --fields-escaped-by=...
These options are used with the --tab option and have the same meaning as the corresponding
FIELDS clauses for LOAD DATA INFILE. See Section 13.2.6, “LOAD DATA INFILE Syntax”.

•

--first-slave
Deprecated. Use --lock-all-tables instead. --first-slave is removed in MySQL 5.5.

•

--flush-logs, -F
Flush the MySQL server log files before starting the dump. This option requires the RELOAD
privilege. If you use this option in combination with the --all-databases option, the logs are
flushed for each database dumped. The exception is when using --lock-all-tables or -master-data: In this case, the logs are flushed only once, corresponding to the moment that all
tables are locked. If you want your dump and the log flush to happen at exactly the same moment,
you should use --flush-logs together with either --lock-all-tables or --master-data.

•

--flush-privileges
Add a FLUSH PRIVILEGES statement to the dump output after dumping the mysql database. This
option should be used any time the dump contains the mysql database and any other database that
depends on the data in the mysql database for proper restoration. This option was added in MySQL
5.0.26.

•

--force, -f
Continue even if an SQL error occurs during a table dump.
One use for this option is to cause mysqldump to continue executing even when it encounters a
view that has become invalid because the definition refers to a table that has been dropped. Without
--force, mysqldump exits with an error message. With --force, mysqldump prints the error

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

message, but it also writes an SQL comment containing the view definition to the dump output and
continues executing.
•

--host=host_name, -h host_name
Dump data from the MySQL server on the given host. The default host is localhost.

•

--hex-blob
Dump binary columns using hexadecimal notation (for example, 'abc' becomes 0x616263).
The affected data types are BINARY, VARBINARY, and the BLOB types. As of MySQL 5.0.13, BIT
columns are affected as well.

•

--ignore-table=db_name.tbl_name
Do not dump the given table, which must be specified using both the database and table names. To
ignore multiple tables, use this option multiple times. This option also can be used to ignore views.

•

--insert-ignore
Write INSERT IGNORE statements rather than INSERT statements.

•

--lines-terminated-by=...
This option is used with the --tab option and has the same meaning as the corresponding LINES
clause for LOAD DATA INFILE. See Section 13.2.6, “LOAD DATA INFILE Syntax”.

•

--lock-all-tables, -x
Lock all tables across all databases. This is achieved by acquiring a global read lock for the duration
of the whole dump. This option automatically turns off --single-transaction and --locktables.

•

--lock-tables, -l
For each dumped database, lock all tables to be dumped before dumping them. The tables are
locked with READ LOCAL to permit concurrent inserts in the case of MyISAM tables. For transactional
tables such as InnoDB and BDB, --single-transaction is a much better option than --locktables because it does not need to lock the tables at all.
Because --lock-tables locks tables for each database separately, this option does not guarantee
that the tables in the dump file are logically consistent between databases. Tables in different
databases may be dumped in completely different states.

•

--log-error=file_name
Log warnings and errors by appending them to the named file. The default is to do no logging. This
option was added in MySQL 5.0.42.

•

--master-data[=value]
Use this option to dump a master replication server to produce a dump file that can be used to set
up another server as a slave of the master. It causes the dump output to include a CHANGE MASTER
TO statement that indicates the binary log coordinates (file name and position) of the dumped server.
These are the master server coordinates from which the slave should start replicating after you load
the dump file into the slave.
If the option value is 2, the CHANGE MASTER TO statement is written as an SQL comment, and
thus is informative only; it has no effect when the dump file is reloaded. If the option value is 1, the
statement is not written as a comment and takes effect when the dump file is reloaded. If no option
value is specified, the default value is 1.
This option requires the RELOAD privilege and the binary log must be enabled.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

The --master-data option automatically turns off --lock-tables. It also turns on --lockall-tables, unless --single-transaction also is specified, in which case, a global read lock
is acquired only for a short time at the beginning of the dump (see the description for --singletransaction). In all cases, any action on logs happens at the exact moment of the dump.
It is also possible to set up a slave by dumping an existing slave of the master. To do this, use the
following procedure on the existing slave:
1. Stop the slave's SQL thread and get its current status:
mysql> STOP SLAVE SQL_THREAD;
mysql> SHOW SLAVE STATUS;

2. From the output of the SHOW SLAVE STATUS statement, the binary log coordinates of
the master server from which the new slave should start replicating are the values of the
Relay_Master_Log_File and Exec_Master_Log_Pos fields. Denote those values as
file_name and file_pos.
3. Dump the slave server:
shell> mysqldump --master-data=2 --all-databases > dumpfile

Using --master-data=2 works only if binary logging has been enabled on the slave.
Otherwise, mysqldump fails with the error Binlogging on server not active. In this case
you must handle any locking issues in another manner, using one or more of --add-locks,
--lock-tables, --lock-all-tables, or --single-transaction, as required by your
application and environment.
4. Restart the slave:
mysql> START SLAVE;

5. On the new slave, load the dump file:
shell> mysql < dumpfile

6. On the new slave, set the replication coordinates to those of the master server obtained earlier:
mysql> CHANGE MASTER TO
-> MASTER_LOG_FILE = 'file_name', MASTER_LOG_POS = file_pos;

The CHANGE MASTER TO statement might also need other parameters, such as MASTER_HOST
to point the slave to the correct master server host. Add any such parameters as necessary.
•

--no-autocommit
Enclose the INSERT statements for each dumped table within SET autocommit = 0 and COMMIT
statements.

•

--no-create-db, -n
Suppress the CREATE DATABASE statements that are otherwise included in the output if the -databases or --all-databases option is given.

•

--no-create-info, -t
Do not write CREATE TABLE statements that create each dumped table.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

•

--no-data, -d
Do not write any table row information (that is, do not dump table contents). This is useful if you want
to dump only the CREATE TABLE statement for the table (for example, to create an empty copy of
the table by loading the dump file).

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--no-set-names, -N
This has the same effect as --skip-set-charset.

•

--opt
This option is shorthand. It is the same as specifying --add-drop-table --add-locks -create-options --disable-keys --extended-insert --lock-tables --quick --setcharset. It should give you a fast dump operation and produce a dump file that can be reloaded
into a MySQL server quickly.
The --opt option is enabled by default. Use --skip-opt to disable it. See the discussion at
the beginning of this section for information about selectively enabling or disabling a subset of the
options affected by --opt.

•

--order-by-primary
Dump each table's rows sorted by its primary key, or by its first unique index, if such an index exists.
This is useful when dumping a MyISAM table to be loaded into an InnoDB table, but will make the
dump operation take considerably longer.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqldump prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--quick, -q

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

This option is useful for dumping large tables. It forces mysqldump to retrieve rows for a table from
the server a row at a time rather than retrieving the entire row set and buffering it in memory before
writing it out.
•

--quote-names, -Q
Quote identifiers (such as database, table, and column names) within “`” characters. If the
ANSI_QUOTES SQL mode is enabled, identifiers are quoted within “"” characters. This option is
enabled by default. It can be disabled with --skip-quote-names, but this option should be given
after any option such as --compatible that may enable --quote-names.

•

--result-file=file_name, -r file_name
Direct output to the named file. The result file is created and its previous contents overwritten, even if
an error occurs while generating the dump.
This option should be used on Windows to prevent newline “\n” characters from being converted to
“\r\n” carriage return/newline sequences.

•

--routines, -R
Include stored routines (procedures and functions) for the dumped databases in the output. Use of
this option requires the SELECT privilege for the mysql.proc table.
The output generated by using --routines contains CREATE PROCEDURE and CREATE
FUNCTION statements to create the routines. However, these statements do not include attributes
such as the routine creation and modification timestamps, so when the routines are reloaded, they
are created with timestamps equal to the reload time.
If you require routines to be created with their original timestamp attributes, do not use --routines.
Instead, dump and reload the contents of the mysql.proc table directly, using a MySQL account
that has appropriate privileges for the mysql database.
This option was added in MySQL 5.0.13. Before that, stored routines are not dumped. Routine
DEFINER values are not dumped until MySQL 5.0.20. This means that before 5.0.20, when routines
are reloaded, they will be created with the definer set to the reloading user. If you require routines
to be re-created with their original definer, dump and load the contents of the mysql.proc table
directly as described earlier.

•

--set-charset
Write SET NAMES default_character_set to the output. This option is enabled by default. To
suppress the SET NAMES statement, use --skip-set-charset.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

•

--single-transaction
This option sets the transaction isolation mode to REPEATABLE READ and sends a START
TRANSACTION SQL statement to the server before dumping data. It is useful only with transactional
tables such as InnoDB and BDB, because then it dumps the consistent state of the database at the
time when START TRANSACTION was issued without blocking any applications.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

When using this option, you should keep in mind that only InnoDB tables are dumped in a consistent
state. For example, any MyISAM or MEMORY tables dumped while using this option may still change
state.
While a --single-transaction dump is in process, to ensure a valid dump file (correct table
contents and binary log coordinates), no other connection should use the following statements:
ALTER TABLE, CREATE TABLE, DROP TABLE, RENAME TABLE, TRUNCATE TABLE. A consistent
read is not isolated from those statements, so use of them on a table to be dumped can cause the
SELECT that is performed by mysqldump to retrieve the table contents to obtain incorrect contents
or fail.
The --single-transaction option and the --lock-tables option are mutually exclusive
because LOCK TABLES causes any pending transactions to be committed implicitly.
This option is not supported for MySQL Cluster tables; the results cannot be guaranteed to be
consistent due to the fact that the NDBCLUSTER storage engine supports only the READ_COMMITTED
transaction isolation level. You should always use NDB backup and restore instead.
To dump large tables, combine the --single-transaction option with the --quick option.
•

--skip-comments
See the description for the --comments option.

•

--skip-opt
See the description for the --opt option.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--tab=dir_name, -T dir_name
Produce tab-separated text-format data files. For each dumped table, mysqldump creates a
tbl_name.sql file that contains the CREATE TABLE statement that creates the table, and the
server writes a tbl_name.txt file that contains its data. The option value is the directory in which to
write the files.
Note
This option should be used only when mysqldump is run on the same
machine as the mysqld server. Because the server creates files *.txt file
in the directory that you specify, the directory must be writable by the server
and the MySQL account that you use must have the FILE privilege. Because
mysqldump creates *.sql in the same directory, it must be writable by your
system login account.
By default, the .txt data files are formatted using tab characters between column values and a
newline at the end of each line. The format can be specified explicitly using the --fields-xxx and
--lines-terminated-by options.
Column values are dumped using the binary character set and the --default-characterset option is ignored. In effect, there is no character set conversion. If a table contains columns

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

in several character sets, the output data file will as well and you may not be able to reload the file
correctly.
•

--tables
Override the --databases or -B option. mysqldump regards all name arguments following the
option as table names.

•

--triggers
Include triggers for each dumped table in the output. This option is enabled by default; disable it with
--skip-triggers. This option was added in MySQL 5.0.11. Before that, triggers are not dumped.

•

--tz-utc
This option enables TIMESTAMP columns to be dumped and reloaded between servers
in different time zones. mysqldump sets its connection time zone to UTC and adds SET
TIME_ZONE='+00:00' to the dump file. Without this option, TIMESTAMP columns are dumped and
reloaded in the time zones local to the source and destination servers, which can cause the values
to change if the servers are in different time zones. --tz-utc also protects against changes due
to daylight saving time. --tz-utc is enabled by default. To disable it, use --skip-tz-utc. This
option was added in MySQL 5.0.15.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Print more information about what the program does.

•

--version, -V
Display version information and exit.

•

--where='where_condition', -w 'where_condition'
Dump only rows selected by the given WHERE condition. Quotes around the condition are mandatory
if it contains spaces or other characters that are special to your command interpreter.
Examples:
--where="user='jimf'"
-w"userid>1"
-w"userid<1"

•

--xml, -X
Write dump output as well-formed XML.
NULL, 'NULL', and Empty Values: For a column named column_name, the NULL value, an empty
string, and the string value 'NULL' are distinguished from one another in the output generated by
this option as follows.
Value:

XML Representation:

NULL (unknown value)



'' (empty string)



'NULL' (string value)

NULL

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

Beginning with MySQL 5.0.26, the output from the mysql client when run using the --xml option
also follows the preceding rules. (See Section 4.5.1.1, “mysql Options”.)
Beginning with MySQL 5.0.40, XML output from mysqldump includes the XML namespace, as
shown here:
shell> mysqldump --xml -u root world City














1
Kabul
AFG
Kabol
1780000

...

4079
Rafah
PSE
Rafah
92020





You can also set the following variables by using --var_name=value syntax:
• max_allowed_packet
The maximum size of the buffer for client/server communication. The default is 24MB, the maximum
is 1GB.
• net_buffer_length
The initial size of the buffer for client/server communication. When creating multiple-row INSERT
statements (as with the --extended-insert or --opt option), mysqldump creates rows up
to net_buffer_length bytes long. If you increase this variable, ensure that the MySQL server
net_buffer_length system variable has a value at least this large.
It is also possible to set variables by using --var_name=value. The --set-variable format is
deprecated.
A common use of mysqldump is for making a backup of an entire database:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump — A Database Backup Program

shell> mysqldump db_name > backup-file.sql

You can load the dump file back into the server like this:
shell> mysql db_name < backup-file.sql

Or like this:
shell> mysql -e "source /path-to-backup/backup-file.sql" db_name

mysqldump is also very useful for populating databases by copying data from one MySQL server to
another:
shell> mysqldump --opt db_name | mysql --host=remote_host -C db_name

It is possible to dump several databases with one command:
shell> mysqldump --databases db_name1 [db_name2 ...] > my_databases.sql

To dump all databases, use the --all-databases option:
shell> mysqldump --all-databases > all_databases.sql

For InnoDB tables, mysqldump provides a way of making an online backup:
shell> mysqldump --all-databases --master-data --single-transaction > all_databases.sql

This backup acquires a global read lock on all tables (using FLUSH TABLES WITH READ LOCK) at
the beginning of the dump. As soon as this lock has been acquired, the binary log coordinates are read
and the lock is released. If long updating statements are running when the FLUSH statement is issued,
the MySQL server may get stalled until those statements finish. After that, the dump becomes lock free
and does not disturb reads and writes on the tables. If the update statements that the MySQL server
receives are short (in terms of execution time), the initial lock period should not be noticeable, even
with many updates.
For point-in-time recovery (also known as “roll-forward,” when you need to restore an old backup
and replay the changes that happened since that backup), it is often useful to rotate the binary log
(see Section 5.4.3, “The Binary Log”) or at least know the binary log coordinates to which the dump
corresponds:
shell> mysqldump --all-databases --master-data=2 > all_databases.sql

Or:
shell> mysqldump --all-databases --flush-logs --master-data=2
> all_databases.sql

The --master-data and --single-transaction options can be used simultaneously, which
provides a convenient way to make an online backup suitable for use prior to point-in-time recovery if
tables are stored using the InnoDB storage engine.
For more information on making backups, see Section 7.2, “Database Backup Methods”, and
Section 7.3, “Example Backup and Recovery Strategy”.
If you encounter problems backing up views, please read the section that covers restrictions on views
which describes a workaround for backing up views when this fails due to insufficient privileges. See
Section C.4, “Restrictions on Views”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlimport — A Data Import Program

4.5.5 mysqlimport — A Data Import Program
The mysqlimport client provides a command-line interface to the LOAD DATA INFILE SQL
statement. Most options to mysqlimport correspond directly to clauses of LOAD DATA INFILE
syntax. See Section 13.2.6, “LOAD DATA INFILE Syntax”.
Invoke mysqlimport like this:
shell> mysqlimport [options] db_name textfile1 [textfile2 ...]

For each text file named on the command line, mysqlimport strips any extension from the file name
and uses the result to determine the name of the table into which to import the file's contents. For
example, files named patient.txt, patient.text, and patient all would be imported into a table
named patient.
mysqlimport supports the following options, which can be specified on the command line or in the
[mysqlimport] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.7 mysqlimport Options
Format

Description

--columns

This option takes a comma-separated list of column
names as its value

--compress

Compress all information sent between client and server

--debug

Write debugging log

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--delete

Empty the table before importing the text file

--fields-enclosed-by

This option has the same meaning as the corresponding
clause for LOAD DATA INFILE

--fields-escaped-by

This option has the same meaning as the corresponding
clause for LOAD DATA INFILE

--fields-optionally-enclosed-by

This option has the same meaning as the corresponding
clause for LOAD DATA INFILE

--fields-terminated-by

This option has the same meaning as the corresponding
clause for LOAD DATA INFILE

--force

Continue even if an SQL error occurs

--help

Display help message and exit

--host

Connect to MySQL server on given host

--ignore

See the description for the --replace option

--ignore-lines

Ignore the first N lines of the data file

--lines-terminated-by

This option has the same meaning as the corresponding
clause for LOAD DATA INFILE

--local

Read input files locally from the client host

--lock-tables

Lock all tables for writing before processing any text files

--low-priority

Use LOW_PRIORITY when loading the table.

--no-defaults

Read no option files

This
documentation
is for an
older version.
If you're

Introduced

5.0.10

This
documentation
is for an
older version.
If you're

mysqlimport — A Data Import Program

Format

Description

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--protocol

Connection protocol to use

--replace

The --replace and --ignore options control handling of
input rows that duplicate existing rows on unique key
values

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--silent

Produce output only when errors occur

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--user

MySQL user name to use when connecting to server

--verbose

Verbose mode

--version

Display version information and exit

•

Introduced

5.0.23

--help, -?
Display a help message and exit.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--columns=column_list, -c column_list
This option takes a comma-separated list of column names as its value. The order of the column
names indicates how to match data file columns with table columns.

•

--compress, -C
Compress all information sent between the client and the server if both support compression.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”.

•

--defaults-extra-file=file_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlimport — A Data Import Program

Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.
•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of
str. For example, mysqlimport normally reads the [client] and [mysqlimport] groups.
If the --defaults-group-suffix=_other option is given, mysqlimport also reads the
[client_other] and [mysqlimport_other] groups. This option was added in MySQL 5.0.10.

•

--delete, -D
Empty the table before importing the text file.

•

--fields-terminated-by=..., --fields-enclosed-by=..., --fieldsoptionally-enclosed-by=..., --fields-escaped-by=...
These options have the same meaning as the corresponding clauses for LOAD DATA INFILE. See
Section 13.2.6, “LOAD DATA INFILE Syntax”.

•

--force, -f
Ignore errors. For example, if a table for a text file does not exist, continue processing any remaining
files. Without --force, mysqlimport exits if a table does not exist.

•

--host=host_name, -h host_name
Import data to the MySQL server on the given host. The default host is localhost.

•

--ignore, -i
See the description for the --replace option.

•

--ignore-lines=N
Ignore the first N lines of the data file.

•

--lines-terminated-by=...
This option has the same meaning as the corresponding clause for LOAD DATA INFILE. For
example, to import Windows files that have lines terminated with carriage return/linefeed pairs, use
--lines-terminated-by="\r\n". (You might have to double the backslashes, depending on
the escaping conventions of your command interpreter.) See Section 13.2.6, “LOAD DATA INFILE
Syntax”.

•

--local, -L
Read input files locally from the client host.

•

--lock-tables, -l
Lock all tables for writing before processing any text files. This ensures that all tables are
synchronized on the server.

• --low-priority
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlimport — A Data Import Program

Use LOW_PRIORITY when loading the table. This affects only storage engines that use only tablelevel locking (such as MyISAM, MEMORY, and MERGE).
•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqlimport prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--replace, -r
The --replace and --ignore options control handling of input rows that duplicate existing rows
on unique key values. If you specify --replace, new rows replace existing rows that have the same
unique key value. If you specify --ignore, input rows that duplicate an existing row on a unique key
value are skipped. If you do not specify either option, an error occurs when a duplicate key value is
found, and the rest of the text file is ignored.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

•

--silent, -s
Silent mode. Produce output only when errors occur.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlshow — Display Database, Table, and Column Information

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Print more information about what the program does.

•

--version, -V
Display version information and exit.
Some options, such as --opt, automatically enable --lock-tables. If you want to override this,
use --skip-lock-tables at the end of the option list.

Here is a sample session that demonstrates use of mysqlimport:
shell> mysql -e 'CREATE TABLE imptest(id INT, n VARCHAR(30))' test
shell> ed
a
100
Max Sydow
101
Count Dracula
.
w imptest.txt
32
q
shell> od -c imptest.txt
0000000
1
0
0 \t
M
a
x
S
y
d
o
w \n
1
0000020
1 \t
C
o
u
n
t
D
r
a
c
u
l
a
0000040
shell> mysqlimport --local test imptest.txt
test.imptest: Records: 2 Deleted: 0 Skipped: 0 Warnings: 0
shell> mysql -e 'SELECT * FROM imptest' test
+------+---------------+
| id
| n
|
+------+---------------+
| 100 | Max Sydow
|
| 101 | Count Dracula |
+------+---------------+

0
\n

4.5.6 mysqlshow — Display Database, Table, and Column Information
The mysqlshow client can be used to quickly see which databases exist, their tables, or a table's
columns or indexes.
mysqlshow provides a command-line interface to several SQL SHOW statements. See Section 13.7.5,
“SHOW Syntax”. The same information can be obtained by using those statements directly. For
example, you can issue them from the mysql client program.
Invoke mysqlshow like this:
shell> mysqlshow [options] [db_name [tbl_name [col_name]]]

• If no database is given, a list of database names is shown.
• If no table is given, all matching tables in the database are shown.
• If no column is given, all matching columns and column types in the table are shown.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlshow — Display Database, Table, and Column Information

The output displays only the names of those databases, tables, or columns for which you have some
privileges.
If the last argument contains shell or SQL wildcard characters (“*”, “?”, “%”, or “_”), only those names
that are matched by the wildcard are shown. If a database name contains any underscores, those
should be escaped with a backslash (some Unix shells require two) to get a list of the proper tables
or columns. “*” and “?” characters are converted into SQL “%” and “_” wildcard characters. This might
cause some confusion when you try to display the columns for a table with a “_” in the name, because
in this case, mysqlshow shows you only the table names that match the pattern. This is easily fixed by
adding an extra “%” last on the command line as a separate argument.
mysqlshow supports the following options, which can be specified on the command line or in the
[mysqlshow] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.8 mysqlshow Options
Format

Description

--compress

Compress all information sent between client and server

--count

Show the number of rows per table

--debug

Write debugging log

--default-character-set

Specify default character set

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--help

Display help message and exit

--host

Connect to MySQL server on given host

--keys

Show table indexes

--no-defaults

Read no option files

--password

Password to use when connecting to server

--pipe

On Windows, connect to server using named pipe

--port

TCP/IP port number to use for connection

--print-defaults

Print default options

--protocol

Connection protocol to use

--shared-memory-base-name

The name of shared memory to use for shared-memory
connections

--show-table-type

Show a column indicating the table type

--socket

For connections to localhost, the Unix socket file to use

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

--ssl-cert

Path of file that contains X509 certificate in PEM format

--ssl-cipher

List of permitted ciphers to use for connection encryption

--ssl-key

Path of file that contains X509 key in PEM format

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

--status

Display extra information about each table

--user

MySQL user name to use when connecting to server

This
documentation
is for an
older version.
If you're

Introduced
5.0.6

5.0.10

5.0.4

5.0.23

This
documentation
is for an
older version.
If you're

mysqlshow — Display Database, Table, and Column Information

Format

Description

--verbose

Verbose mode

--version

Display version information and exit

•

Introduced

--help, -?
Display a help message and exit.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--compress, -C
Compress all information sent between the client and the server if both support compression.

•

--count
Show the number of rows per table. This can be slow for non-MyISAM tables. This option was added
in MySQL 5.0.6.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o.

•

--default-character-set=charset_name
Use charset_name as the default character set. See Section 10.5, “Character Set Configuration”.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str.
For example, mysqlshow normally reads the [client] and [mysqlshow] groups. If the -defaults-group-suffix=_other option is given, mysqlshow also reads the [client_other]
and [mysqlshow_other] groups. This option was added in MySQL 5.0.10.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--keys, -k
Show table indexes.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--password[=password], -p[password]

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlshow — Display Database, Table, and Column Information

The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqlshow prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.
•

--pipe, -W
On Windows, connect to the server using a named pipe. This option applies only if the server
supports named-pipe connections.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--shared-memory-base-name=name
On Windows, the shared-memory name to use, for connections made using shared memory to a
local server. The default value is MYSQL. The shared-memory name is case sensitive.
The server must be started with the --shared-memory option to enable shared-memory
connections.

•

--show-table-type, -t
Show a column indicating the table type, as in SHOW FULL TABLES. The type is BASE TABLE or
VIEW. This option was added in MySQL 5.0.4.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--ssl*
Options that begin with --ssl specify whether to connect to the server using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--status, -i
Display extra information about each table.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

•

--verbose, -v
Verbose mode. Print more information about what the program does. This option can be used
multiple times to increase the amount of information.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Administrative and Utility Programs

•

--version, -V
Display version information and exit.

4.6 MySQL Administrative and Utility Programs
This section describes administrative programs and programs that perform miscellaneous utility
operations.

4.6.1 innochecksum — Offline InnoDB File Checksum Utility
innochecksum prints checksums for InnoDB files. This tool reads an InnoDB tablespace file,
calculates the checksum for each page, compares the calculated checksum to the stored checksum,
and reports mismatches, which indicate damaged pages. It was originally developed to speed up
verifying the integrity of tablespace files after power outages but can also be used after file copies.
Because checksum mismatches will cause InnoDB to deliberately shut down a running server, it can
be preferable to use this tool rather than waiting for a server in production usage to encounter the
damaged pages.
innochecksum cannot be used on tablespace files that the server already has open. For such files,
you should use CHECK TABLE to check tables within the tablespace.
If checksum mismatches are found, you would normally restore the tablespace from backup or start the
server and attempt to use mysqldump to make a backup of the tables within the tablespace.
Invoke innochecksum like this:
shell> innochecksum [options] file_name

innochecksum supports the following options. For options that refer to page numbers, the numbers
are zero-based.
• -c
Print a count of the number of pages in the file.
• -d
Debug mode; prints checksums for each page.
• -e num
End at this page number.
• -p num
Check only this page number.
• -s num
Start at this page number.
• -v
Verbose mode; print a progress indicator every five seconds.

4.6.2 myisam_ftdump — Display Full-Text Index information
myisam_ftdump displays information about FULLTEXT indexes in MyISAM tables. It reads the
MyISAM index file directly, so it must be run on the server host where the table is located. Before using
myisam_ftdump, be sure to issue a FLUSH TABLES statement first if the server is running.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisam_ftdump — Display Full-Text Index information

myisam_ftdump scans and dumps the entire index, which is not particularly fast. On the other hand,
the distribution of words changes infrequently, so it need not be run often.
Invoke myisam_ftdump like this:
shell> myisam_ftdump [options] tbl_name index_num

The tbl_name argument should be the name of a MyISAM table. You can also specify a table by
naming its index file (the file with the .MYI suffix). If you do not invoke myisam_ftdump in the
directory where the table files are located, the table or index file name must be preceded by the path
name to the table's database directory. Index numbers begin with 0.
Example: Suppose that the test database contains a table named mytexttable that has the
following definition:
CREATE TABLE mytexttable
(
id
INT NOT NULL,
txt TEXT NOT NULL,
PRIMARY KEY (id),
FULLTEXT (txt)
) ENGINE=MyISAM;

The index on id is index 0 and the FULLTEXT index on txt is index 1. If your working directory is the
test database directory, invoke myisam_ftdump as follows:
shell> myisam_ftdump mytexttable 1

If the path name to the test database directory is /usr/local/mysql/data/test, you can
also specify the table name argument using that path name. This is useful if you do not invoke
myisam_ftdump in the database directory:
shell> myisam_ftdump /usr/local/mysql/data/test/mytexttable 1

You can use myisam_ftdump to generate a list of index entries in order of frequency of occurrence
like this:
shell> myisam_ftdump -c mytexttable 1 | sort -r

myisam_ftdump supports the following options:
•

--help, -h -?
Display a help message and exit.

•

--count, -c
Calculate per-word statistics (counts and global weights).

•

--dump, -d
Dump the index, including data offsets and word weights.

•

--length, -l
Report the length distribution.

•

--stats, -s
Report global index statistics. This is the default operation if no other operation is specified.

•

--verbose, -v

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Verbose mode. Print more output about what the program does.

4.6.3 myisamchk — MyISAM Table-Maintenance Utility
The myisamchk utility gets information about your database tables or checks, repairs, or optimizes
them. myisamchk works with MyISAM tables (tables that have .MYD and .MYI files for storing data
and indexes).
You can also use the CHECK TABLE and REPAIR TABLE statements to check and repair MyISAM
tables. See Section 13.7.2.3, “CHECK TABLE Syntax”, and Section 13.7.2.6, “REPAIR TABLE
Syntax”.
Caution
It is best to make a backup of a table before performing a table repair operation;
under some circumstances the operation might cause data loss. Possible
causes include but are not limited to file system errors.
Invoke myisamchk like this:
shell> myisamchk [options] tbl_name ...

The options specify what you want myisamchk to do. They are described in the following sections.
You can also get a list of options by invoking myisamchk --help.
With no options, myisamchk simply checks your table as the default operation. To get more
information or to tell myisamchk to take corrective action, specify options as described in the following
discussion.
tbl_name is the database table you want to check or repair. If you run myisamchk somewhere
other than in the database directory, you must specify the path to the database directory, because
myisamchk has no idea where the database is located. In fact, myisamchk does not actually care
whether the files you are working on are located in a database directory. You can copy the files that
correspond to a database table into some other location and perform recovery operations on them
there.
You can name several tables on the myisamchk command line if you wish. You can also specify a
table by naming its index file (the file with the .MYI suffix). This enables you to specify all tables in a
directory by using the pattern *.MYI. For example, if you are in a database directory, you can check all
the MyISAM tables in that directory like this:
shell> myisamchk *.MYI

If you are not in the database directory, you can check all the tables there by specifying the path to the
directory:
shell> myisamchk /path/to/database_dir/*.MYI

You can even check all tables in all databases by specifying a wildcard with the path to the MySQL
data directory:
shell> myisamchk /path/to/datadir/*/*.MYI

The recommended way to quickly check all MyISAM tables is:
shell> myisamchk --silent --fast /path/to/datadir/*/*.MYI

If you want to check all MyISAM tables and repair any that are corrupted, you can use the following
command:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

shell> myisamchk --silent --force --fast --update-state \
--key_buffer_size=64M --sort_buffer_size=64M \
--read_buffer_size=1M --write_buffer_size=1M \
/path/to/datadir/*/*.MYI

This command assumes that you have more than 64MB free. For more information about memory
allocation with myisamchk, see Section 4.6.3.6, “myisamchk Memory Usage”.
For additional information about using myisamchk, see Section 7.6, “MyISAM Table Maintenance and
Crash Recovery”.
Important
You must ensure that no other program is using the tables while you are
running myisamchk. The most effective means of doing so is to shut down the
MySQL server while running myisamchk, or to lock all tables that myisamchk
is being used on.
Otherwise, when you run myisamchk, it may display the following error
message:
warning: clients are using or haven't closed the table properly

This means that you are trying to check a table that has been updated by
another program (such as the mysqld server) that hasn't yet closed the file or
that has died without closing the file properly, which can sometimes lead to the
corruption of one or more MyISAM tables.
If mysqld is running, you must force it to flush any table modifications that are
still buffered in memory by using FLUSH TABLES. You should then ensure that
no one is using the tables while you are running myisamchk
However, the easiest way to avoid this problem is to use CHECK TABLE instead
of myisamchk to check tables. See Section 13.7.2.3, “CHECK TABLE Syntax”.
myisamchk supports the following options, which can be specified on the command line or in the
[myisamchk] group of an option file. For information about option files used by MySQL programs, see
Section 4.2.6, “Using Option Files”.
Table 4.9 myisamchk Options
Format

Description

--analyze

Analyze the distribution of key values

--backup

Make a backup of the .MYD file as file_nametime.BAK

--block-search

Find the record that a block at the given offset
belongs to

--check

Check the table for errors

--check-only-changed

Check only tables that have changed since the last
check

--correct-checksum

Correct the checksum information for the table

--data-file-length

Maximum length of the data file (when re-creating
data file when it is full)

--debug

Write debugging log

--decode_bits

Decode_bits

This
documentation
is for an
older version.
If you're

IntroducedRemoved

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Format

Description

--defaults-extra-file

Read named option file in addition to usual option
files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--description

Print some descriptive information about the table

--extend-check

Do very thorough table check or repair that tries to
recover every possible row from the data file

--fast

Check only tables that haven't been closed
properly

--force

Do a repair operation automatically if myisamchk
finds any errors in the table

--force

Overwrite old temporary files. For use with the -r or
-o option

--ft_max_word_len

Maximum word length for FULLTEXT indexes

--ft_min_word_len

Minimum word length for FULLTEXT indexes

--ft_stopword_file

Use stopwords from this file instead of built-in list

--HELP

Display help message and exit

--help

Display help message and exit

--information

Print informational statistics about the table that is
checked

--key_buffer_size

Size of buffer used for index blocks for MyISAM
tables

--keys-used

A bit-value that indicates which indexes to update

--max-record-length

Skip rows larger than the given length if
myisamchk cannot allocate memory to hold them

--medium-check

Do a check that is faster than an --extend-check
operation

--myisam_block_size

Block size to be used for MyISAM index pages

--no-defaults

Read no option files

--parallel-recover

Uses the same technique as -r and -n, but creates
all the keys in parallel, using different threads
(beta)

--print-defaults

Print default options

--quick

Achieve a faster repair by not modifying the data
file.

--read_buffer_size

Each thread that does a sequential scan allocates
a buffer of this size for each table it scans

--read-only

Do not mark the table as checked

--recover

Do a repair that can fix almost any problem except
unique keys that aren't unique

--safe-recover

Do a repair using an old recovery method that
reads through all rows in order and updates all
index trees based on the rows found

--set-auto-increment

Force AUTO_INCREMENT numbering for new
records to start at the given value

This
documentation
is for an
older version.
If you're

IntroducedRemoved

5.0.10

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Format

Description

--set-character-set

Change the character set used by the table
indexes

--set-collation

Specify the collation to use for sorting table
indexes

--silent

Silent mode

--sort_buffer_size

The buffer that is allocated when sorting the index
when doing a REPAIR or when creating indexes
with CREATE INDEX or ALTER TABLE

--sort-index

Sort the index tree blocks in high-low order

--sort_key_blocks

sort_key_blocks

--sort-records

Sort records according to a particular index

--sort-recover

Force myisamchk to use sorting to resolve the
keys even if the temporary files would be very
large

--stats_method

Specifies how MyISAM index statistics collection
code should treat NULLs

--tmpdir

Path of the directory to be used for storing
temporary files

--unpack

Unpack a table that was packed with myisampack

--update-state

Store information in the .MYI file to indicate when
the table was checked and whether the table
crashed

--verbose

Verbose mode

--version

Display version information and exit

--write_buffer_size

Write buffer size

IntroducedRemoved
5.0.3
5.0.3

4.6.3.1 myisamchk General Options
The options described in this section can be used for any type of table maintenance operation
performed by myisamchk. The sections following this one describe options that pertain only to specific
operations, such as table checking or repairing.
•

--help, -?
Display a help message and exit. Options are grouped by type of operation.

•

--HELP, -H
Display a help message and exit. Options are presented in a single list.

•

--debug=debug_options, -# debug_options
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o,/tmp/myisamchk.trace.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.
•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of str.
For example, myisamchk normally reads the [myisamchk] group. If the --defaults-groupsuffix=_other option is given, myisamchk also reads the [myisamchk_other] group. This
option was added in MySQL 5.0.10.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--silent, -s
Silent mode. Write output only when errors occur. You can use -s twice (-ss) to make myisamchk
very silent.

•

--verbose, -v
Verbose mode. Print more information about what the program does. This can be used with -d and e. Use -v multiple times (-vv, -vvv) for even more output.

•

--version, -V
Display version information and exit.

•

--wait, -w
Instead of terminating with an error if the table is locked, wait until the table is unlocked before
continuing. If you are running mysqld with external locking disabled, the table can be locked only by
another myisamchk command.

You can also set the following variables by using --var_name=value syntax:
Variable

Default Value

decode_bits

9

ft_max_word_len

version-dependent

ft_min_word_len

4

ft_stopword_file

built-in list

key_buffer_size

523264

myisam_block_size

1024

read_buffer_size

262136

sort_buffer_size

2097144

sort_key_blocks

16

stats_method

nulls_unequal

write_buffer_size

262136

It is also possible to set variables by using --set-variable=var_name=value or -O
var_name=value syntax. However, this syntax is deprecated as of MySQL 4.0.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

The possible myisamchk variables and their default values can be examined with myisamchk -help:
sort_buffer_size is used when the keys are repaired by sorting keys, which is the normal case
when you use --recover.
key_buffer_size is used when you are checking the table with --extend-check or when the keys
are repaired by inserting keys row by row into the table (like when doing normal inserts). Repairing
through the key buffer is used in the following cases:
• You use --safe-recover.
• The temporary files needed to sort the keys would be more than twice as big as when creating the
key file directly. This is often the case when you have large key values for CHAR, VARCHAR, or TEXT
columns, because the sort operation needs to store the complete key values as it proceeds. If you
have lots of temporary space and you can force myisamchk to repair by sorting, you can use the -sort-recover option.
Repairing through the key buffer takes much less disk space than using sorting, but is also much
slower.
If you want a faster repair, set the key_buffer_size and sort_buffer_size variables to about
25% of your available memory. You can set both variables to large values, because only one of them is
used at a time.
myisam_block_size is the size used for index blocks.
stats_method influences how NULL values are treated for index statistics collection when the
--analyze option is given. It acts like the myisam_stats_method system variable. For more
information, see the description of myisam_stats_method in Section 5.1.4, “Server System
Variables”, and Section 8.3.7, “MyISAM Index Statistics Collection”. The stats_method method
was added in MySQL 5.0.14. For older versions, the statistics collection method is equivalent to
nulls_equal.
ft_min_word_len and ft_max_word_len indicate the minimum and maximum word length for
FULLTEXT indexes. ft_stopword_file names the stopword file. These need to be set under the
following circumstances.
If you use myisamchk to perform an operation that modifies table indexes (such as repair or analyze),
the FULLTEXT indexes are rebuilt using the default full-text parameter values for minimum and
maximum word length and the stopword file unless you specify otherwise. This can result in queries
failing.
The problem occurs because these parameters are known only by the server. They are not stored in
MyISAM index files. To avoid the problem if you have modified the minimum or maximum word length
or the stopword file in the server, specify the same ft_min_word_len, ft_max_word_len, and
ft_stopword_file values to myisamchk that you use for mysqld. For example, if you have set the
minimum word length to 3, you can repair a table with myisamchk like this:
shell> myisamchk --recover --ft_min_word_len=3 tbl_name.MYI

To ensure that myisamchk and the server use the same values for full-text parameters, you can place
each one in both the [mysqld] and [myisamchk] sections of an option file:
[mysqld]
ft_min_word_len=3
[myisamchk]
ft_min_word_len=3

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

An alternative to using myisamchk is to use the REPAIR TABLE, ANALYZE TABLE, OPTIMIZE
TABLE, or ALTER TABLE. These statements are performed by the server, which knows the proper fulltext parameter values to use.

4.6.3.2 myisamchk Check Options
myisamchk supports the following options for table checking operations:
•

--check, -c
Check the table for errors. This is the default operation if you specify no option that selects an
operation type explicitly.

•

--check-only-changed, -C
Check only tables that have changed since the last check.

•

--extend-check, -e
Check the table very thoroughly. This is quite slow if the table has many indexes. This option should
only be used in extreme cases. Normally, myisamchk or myisamchk --medium-check should be
able to determine whether there are any errors in the table.
If you are using --extend-check and have plenty of memory, setting the key_buffer_size
variable to a large value helps the repair operation run faster.
See also the description of this option under table repair options.
For a description of the output format, see Section 4.6.3.5, “Obtaining Table Information with
myisamchk”.

•

--fast, -F
Check only tables that haven't been closed properly.

•

--force, -f
Do a repair operation automatically if myisamchk finds any errors in the table. The repair type is the
same as that specified with the --recover or -r option.

•

--information, -i
Print informational statistics about the table that is checked.

•

--medium-check, -m
Do a check that is faster than an --extend-check operation. This finds only 99.99% of all errors,
which should be good enough in most cases.

•

--read-only, -T
Do not mark the table as checked. This is useful if you use myisamchk to check a table that is in use
by some other application that does not use locking, such as mysqld when run with external locking
disabled.

•

--update-state, -U
Store information in the .MYI file to indicate when the table was checked and whether the table
crashed. This should be used to get full benefit of the --check-only-changed option, but you
shouldn't use this option if the mysqld server is using the table and you are running it with external
locking disabled.

4.6.3.3 myisamchk Repair Options

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

myisamchk supports the following options for table repair operations (operations performed when an
option such as --recover or --safe-recover is given):
•

--backup, -B
Make a backup of the .MYD file as file_name-time.BAK

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--correct-checksum
Correct the checksum information for the table.

•

--data-file-length=len, -D len
The maximum length of the data file (when re-creating data file when it is “full”).

•

--extend-check, -e
Do a repair that tries to recover every possible row from the data file. Normally, this also finds a lot of
garbage rows. Do not use this option unless you are desperate.
See also the description of this option under table checking options.
For a description of the output format, see Section 4.6.3.5, “Obtaining Table Information with
myisamchk”.

•

--force, -f
Overwrite old intermediate files (files with names like tbl_name.TMD) instead of aborting.

•

--keys-used=val, -k val
For myisamchk, the option value is a bit-value that indicates which indexes to update. Each binary
bit of the option value corresponds to a table index, where the first index is bit 0. An option value of 0
disables updates to all indexes, which can be used to get faster inserts. Deactivated indexes can be
reactivated by using myisamchk -r.

•

--no-symlinks, -l
Do not follow symbolic links. Normally myisamchk repairs the table that a symlink points to. This
option does not exist as of MySQL 4.0 because versions from 4.0 on do not remove symlinks during
repair operations.

•

--max-record-length=len
Skip rows larger than the given length if myisamchk cannot allocate memory to hold them.

•

--parallel-recover, -p
Use the same technique as -r and -n, but create all the keys in parallel, using different threads.
This is beta-quality code. Use at your own risk!

•

--quick, -q
Achieve a faster repair by modifying only the index file, not the data file. You can specify this option
twice to force myisamchk to modify the original data file in case of duplicate keys.

•

--recover, -r
Do a repair that can fix almost any problem except unique keys that are not unique (which is an
extremely unlikely error with MyISAM tables). If you want to recover a table, this is the option to try

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

first. You should try --safe-recover only if myisamchk reports that the table cannot be recovered
using --recover. (In the unlikely case that --recover fails, the data file remains intact.)
If you have lots of memory, you should increase the value of sort_buffer_size.
•

--safe-recover, -o
Do a repair using an old recovery method that reads through all rows in order and updates all index
trees based on the rows found. This is an order of magnitude slower than --recover, but can
handle a couple of very unlikely cases that --recover cannot. This recovery method also uses
much less disk space than --recover. Normally, you should repair first using --recover, and
then with --safe-recover only if --recover fails.
If you have lots of memory, you should increase the value of key_buffer_size.

•

--set-character-set=name
Change the character set used by the table indexes. This option was replaced by --setcollation in MySQL 5.0.3.

•

--set-collation=name
Specify the collation to use for sorting table indexes. The character set name is implied by the first
part of the collation name. This option was added in MySQL 5.0.3.

•

--sort-recover, -n
Force myisamchk to use sorting to resolve the keys even if the temporary files would be very large.

•

--tmpdir=dir_name, -t dir_name
The path of the directory to be used for storing temporary files. If this is not set, myisamchk uses
the value of the TMPDIR environment variable. --tmpdir can be set to a list of directory paths that
are used successively in round-robin fashion for creating temporary files. The separator character
between directory names is the colon (“:”) on Unix and the semicolon (“;”) on Windows, NetWare,
and OS/2.

•

--unpack, -u
Unpack a table that was packed with myisampack.

4.6.3.4 Other myisamchk Options
myisamchk supports the following options for actions other than table checks and repairs:
•

--analyze, -a
Analyze the distribution of key values. This improves join performance by enabling the join
optimizer to better choose the order in which to join the tables and which indexes it should use. To
obtain information about the key distribution, use a myisamchk --description --verbose
tbl_name command or the SHOW INDEX FROM tbl_name statement.

•

--block-search=offset, -b offset
Find the record that a block at the given offset belongs to.

•

--description, -d
Print some descriptive information about the table. Specifying the --verbose option once or twice
produces additional information. See Section 4.6.3.5, “Obtaining Table Information with myisamchk”.

•

--set-auto-increment[=value], -A[value]

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Force AUTO_INCREMENT numbering for new records to start at the given value (or higher, if
there are existing records with AUTO_INCREMENT values this large). If value is not specified,
AUTO_INCREMENT numbers for new records begin with the largest value currently in the table, plus
one.
•

--sort-index, -S
Sort the index tree blocks in high-low order. This optimizes seeks and makes table scans that use
indexes faster.

•

--sort-records=N, -R N
Sort records according to a particular index. This makes your data much more localized and may
speed up range-based SELECT and ORDER BY operations that use this index. (The first time you
use this option to sort a table, it may be very slow.) To determine a table's index numbers, use SHOW
INDEX, which displays a table's indexes in the same order that myisamchk sees them. Indexes are
numbered beginning with 1.
If keys are not packed (PACK_KEYS=0), they have the same length, so when myisamchk sorts and
moves records, it just overwrites record offsets in the index. If keys are packed (PACK_KEYS=1),
myisamchk must unpack key blocks first, then re-create indexes and pack the key blocks again. (In
this case, re-creating indexes is faster than updating offsets for each index.)

4.6.3.5 Obtaining Table Information with myisamchk
To obtain a description of a MyISAM table or statistics about it, use the commands shown here. The
output from these commands is explained later in this section.
• myisamchk -d tbl_name
Runs myisamchk in “describe mode” to produce a description of your table. If you start the MySQL
server with external locking disabled, myisamchk may report an error for a table that is updated
while it runs. However, because myisamchk does not change the table in describe mode, there is no
risk of destroying data.
• myisamchk -dv tbl_name
Adding -v runs myisamchk in verbose mode so that it produces more information about the table.
Adding -v a second time produces even more information.
• myisamchk -eis tbl_name
Shows only the most important information from a table. This operation is slow because it must read
the entire table.
• myisamchk -eiv tbl_name
This is like -eis, but tells you what is being done.
The tbl_name argument can be either the name of a MyISAM table or the name of its index file, as
described in Section 4.6.3, “myisamchk — MyISAM Table-Maintenance Utility”. Multiple tbl_name
arguments can be given.
Suppose that a table named person has the following structure. (The MAX_ROWS table option is
included so that in the example output from myisamchk shown later, some values are smaller and fit
the output format more easily.)
CREATE TABLE person
(
id
INT NOT NULL AUTO_INCREMENT,

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
birth
DATE,
death
DATE,
PRIMARY KEY (id),
INDEX (last_name, first_name),
INDEX (birth)
) MAX_ROWS = 1000000;

Suppose also that the table has these data and index file sizes:
-rw-rw----rw-rw----

1 mysql
1 mysql

mysql
mysql

9347072 Aug 19 11:47 person.MYD
6066176 Aug 19 11:47 person.MYI

Example of myisamchk -dvv output:
MyISAM file:
person
Record format:
Packed
Character set:
latin1_swedish_ci (8)
File-version:
1
Creation time:
2009-08-19 16:47:41
Recover time:
2009-08-19 16:47:56
Status:
checked,analyzed,optimized keys
Auto increment key:
1 Last value:
306688
Data records:
306688 Deleted blocks:
0
Datafile parts:
306688 Deleted data:
0
Datafile pointer (bytes):
4 Keyfile pointer (bytes):
3
Datafile length:
9347072 Keyfile length:
6066176
Max datafile length:
4294967294 Max keyfile length:
17179868159
Recordlength:
54
table description:
Key Start Len Index
1
2
4
unique
2
6
20 multip.
27
20
3
48
3
multip.
Field
1
2
3
4
5
6

Start
1
2
6
27
48
51

Type
long
varchar prefix
varchar
uint24 NULL

Length Nullpos Nullbit
1
4
21
21
3
1
1
3
1
2

Rec/key
1
512
512
306688

Root
99328
3563520

Blocksize
1024
1024

6065152

1024

Type
no zeros
varchar
varchar
no zeros
no zeros

Explanations for the types of information myisamchk produces are given here. “Keyfile” refers to the
index file. “Record” and “row” are synonymous, as are “field” and “column.”
The initial part of the table description contains these values:
• MyISAM file
Name of the MyISAM (index) file.
• Record format
The format used to store table rows. The preceding examples use Fixed length. Other possible
values are Compressed and Packed. (Packed corresponds to what SHOW TABLE STATUS reports
as Dynamic.)
• Chararacter set
The table default character set.
• File-version
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

Version of MyISAM format. Always 1.
• Creation time
When the data file was created.
• Recover time
When the index/data file was last reconstructed.
• Status
Table status flags. Possible values are crashed, open, changed, analyzed, optimized keys,
and sorted index pages.
• Auto increment key, Last value
The key number associated the table's AUTO_INCREMENT column, and the most recently generated
value for this column. These fields do not appear if there is no such column.
• Data records
The number of rows in the table.
• Deleted blocks
How many deleted blocks still have reserved space. You can optimize your table to minimize this
space. See Section 7.6.4, “MyISAM Table Optimization”.
• Datafile parts
For dynamic-row format, this indicates how many data blocks there are. For an optimized table
without fragmented rows, this is the same as Data records.
• Deleted data
How many bytes of unreclaimed deleted data there are. You can optimize your table to minimize this
space. See Section 7.6.4, “MyISAM Table Optimization”.
• Datafile pointer
The size of the data file pointer, in bytes. It is usually 2, 3, 4, or 5 bytes. Most tables manage with
2 bytes, but this cannot be controlled from MySQL yet. For fixed tables, this is a row address. For
dynamic tables, this is a byte address.
• Keyfile pointer
The size of the index file pointer, in bytes. It is usually 1, 2, or 3 bytes. Most tables manage with 2
bytes, but this is calculated automatically by MySQL. It is always a block address.
• Max datafile length
How long the table data file can become, in bytes.
• Max keyfile length
How long the table index file can become, in bytes.
• Recordlength
How much space each row takes, in bytes.
The table description part of the output includes a list of all keys in the table. For each key,
myisamchk displays some low-level information:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

• Key
This key's number. This value is shown only for the first column of the key. If this value is missing,
the line corresponds to the second or later column of a multiple-column key. For the table shown in
the example, there are two table description lines for the second index. This indicates that it is
a multiple-part index with two parts.
• Start
Where in the row this portion of the index starts.
• Len
How long this portion of the index is. For packed numbers, this should always be the full length of the
column. For strings, it may be shorter than the full length of the indexed column, because you can
index a prefix of a string column. The total length of a multiple-part key is the sum of the Len values
for all key parts.
• Index
Whether a key value can exist multiple times in the index. Possible values are unique or multip.
(multiple).
• Type
What data type this portion of the index has. This is a MyISAM data type with the possible values
packed, stripped, or empty.
• Root
Address of the root index block.
• Blocksize
The size of each index block. By default this is 1024, but the value may be changed at compile time
when MySQL is built from source.
• Rec/key
This is a statistical value used by the optimizer. It tells how many rows there are per value for this
index. A unique index always has a value of 1. This may be updated after a table is loaded (or
greatly changed) with myisamchk -a. If this is not updated at all, a default value of 30 is given.
The last part of the output provides information about each column:
• Field
The column number.
• Start
The byte position of the column within table rows.
• Length
The length of the column in bytes.
• Nullpos, Nullbit
For columns that can be NULL, MyISAM stores NULL values as a flag in a byte. Depending on
how many nullable columns there are, there can be one or more bytes used for this purpose. The
Nullpos and Nullbit values, if nonempty, indicate which byte and bit contains that flag indicating
whether the column is NULL.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

The position and number of bytes used to store NULL flags is shown in the line for field 1. This is why
there are six Field lines for the person table even though it has only five columns.
• Type
The data type. The value may contain any of the following descriptors:
• constant
All rows have the same value.
• no endspace
Do not store endspace.
• no endspace, not_always
Do not store endspace and do not do endspace compression for all values.
• no endspace, no empty
Do not store endspace. Do not store empty values.
• table-lookup
The column was converted to an ENUM.
• zerofill(N)
The most significant N bytes in the value are always 0 and are not stored.
• no zeros
Do not store zeros.
• always zero
Zero values are stored using one bit.
• Huff tree
The number of the Huffman tree associated with the column.
• Bits
The number of bits used in the Huffman tree.
The Huff tree and Bits fields are displayed if the table has been compressed with myisampack.
See Section 4.6.5, “myisampack — Generate Compressed, Read-Only MyISAM Tables”, for an
example of this information.
Example of myisamchk -eiv output:
Checking MyISAM file: person
Data records: 306688
Deleted blocks:
- check file-size
- check record delete-chain
No recordlinks
- check key delete-chain
block_size 1024:
- check index reference
- check data record references index: 1
Key: 1: Keyblocks used: 98% Packed:

This
documentation
is for an
older version.
If you're

0

0%

Max levels:

3

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

- check data record
Key: 2: Keyblocks
- check data record
Key: 3: Keyblocks
Total:
Keyblocks

references index: 2
used: 99% Packed:
references index: 3
used: 98% Packed:
used: 98% Packed:

97%

Max levels:

3

-14%
89%

Max levels:

3

- check records and index references
*** LOTS OF ROW NUMBERS DELETED ***
Records:
Recordspace used:
Record blocks:
Record data:
Lost space:

306688
97%
306688
7934464
256512

M.recordlength:
Empty space:
Delete blocks:
Deleted data:
Linkdata:

25 Packed:
2% Blocks/Record:
0
0
1156096

83%
1.00

User time 43.08, System time 1.68
Maximum resident set size 0, Integral resident set size 0
Non-physical pagefaults 0, Physical pagefaults 0, Swaps 0
Blocks in 0 out 7, Messages in 0 out 0, Signals 0
Voluntary context switches 0, Involuntary context switches 0
Maximum memory usage: 1046926 bytes (1023k)

myisamchk -eiv output includes the following information:
• Data records
The number of rows in the table.
• Deleted blocks
How many deleted blocks still have reserved space. You can optimize your table to minimize this
space. See Section 7.6.4, “MyISAM Table Optimization”.
• Key
The key number.
• Keyblocks used
What percentage of the keyblocks are used. When a table has just been reorganized with
myisamchk, the values are very high (very near theoretical maximum).
• Packed
MySQL tries to pack key values that have a common suffix. This can only be used for indexes on
CHAR and VARCHAR columns. For long indexed strings that have similar leftmost parts, this can
significantly reduce the space used. In the preceding example, the second key is 40 bytes long and a
97% reduction in space is achieved.
• Max levels
How deep the B-tree for this key is. Large tables with long key values get high values.
• Records
How many rows are in the table.
• M.recordlength
The average row length. This is the exact row length for tables with fixed-length rows, because all
rows have the same length.
• Packed
MySQL strips spaces from the end of strings. The Packed value indicates the percentage of savings
achieved by doing this.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamchk — MyISAM Table-Maintenance Utility

• Recordspace used
What percentage of the data file is used.
• Empty space
What percentage of the data file is unused.
• Blocks/Record
Average number of blocks per row (that is, how many links a fragmented row is composed of). This
is always 1.0 for fixed-format tables. This value should stay as close to 1.0 as possible. If it gets too
large, you can reorganize the table. See Section 7.6.4, “MyISAM Table Optimization”.
• Recordblocks
How many blocks (links) are used. For fixed-format tables, this is the same as the number of rows.
• Deleteblocks
How many blocks (links) are deleted.
• Recorddata
How many bytes in the data file are used.
• Deleted data
How many bytes in the data file are deleted (unused).
• Lost space
If a row is updated to a shorter length, some space is lost. This is the sum of all such losses, in
bytes.
• Linkdata
When the dynamic table format is used, row fragments are linked with pointers (4 to 7 bytes each).
Linkdata is the sum of the amount of storage used by all such pointers.

4.6.3.6 myisamchk Memory Usage
Memory allocation is important when you run myisamchk. myisamchk uses no more memory than
its memory-related variables are set to. If you are going to use myisamchk on very large tables, you
should first decide how much memory you want it to use. The default is to use only about 3MB to
perform repairs. By using larger values, you can get myisamchk to operate faster. For example, if you
have more than 512MB RAM available, you could use options such as these (in addition to any other
options you might specify):
shell> myisamchk --sort_buffer_size=256M \
--key_buffer_size=512M \
--read_buffer_size=64M \
--write_buffer_size=64M ...

Using --sort_buffer_size=16M is probably enough for most cases.
Be aware that myisamchk uses temporary files in TMPDIR. If TMPDIR points to a memory file system,
out of memory errors can easily occur. If this happens, run myisamchk with the --tmpdir=dir_name
option to specify a directory located on a file system that has more space.
When performing repair operations, myisamchk also needs a lot of disk space:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisamlog — Display MyISAM Log File Contents

• Twice the size of the data file (the original file and a copy). This space is not needed if you do a
repair with --quick; in this case, only the index file is re-created. This space must be available on
the same file system as the original data file, as the copy is created in the same directory as the
original.
• Space for the new index file that replaces the old one. The old index file is truncated at the start of
the repair operation, so you usually ignore this space. This space must be available on the same file
system as the original data file.
• When using --recover or --sort-recover (but not when using --safe-recover), you need
space on disk for sorting. This space is allocated in the temporary directory (specified by TMPDIR or
--tmpdir=dir_name). The following formula yields the amount of space required:
(largest_key + row_pointer_length) * number_of_rows * 2

You can check the length of the keys and the row_pointer_length with myisamchk dv tbl_name (see Section 4.6.3.5, “Obtaining Table Information with myisamchk”). The
row_pointer_length and number_of_rows values are the Datafile pointer and Data
records values in the table description. To determine the largest_key value, check the Key
lines in the table description. The Len column indicates the number of bytes for each key part. For a
multiple-column index, the key size is the sum of the Len values for all key parts.
If you have a problem with disk space during repair, you can try --safe-recover instead of -recover.

4.6.4 myisamlog — Display MyISAM Log File Contents
myisamlog processes the contents of a MyISAM log file. To create such a file, start the server with a
--log-isam=log_file option.
Invoke myisamlog like this:
shell> myisamlog [options] [file_name [tbl_name] ...]

The default operation is update (-u). If a recovery is done (-r), all writes and possibly updates
and deletes are done and errors are only counted. The default log file name is myisam.log if no
log_file argument is given. If tables are named on the command line, only those tables are updated.
myisamlog supports the following options:
• -?, -I
Display a help message and exit.
• -c N
Execute only N commands.
• -f N
Specify the maximum number of open files.
• -i
Display extra information before exiting.
• -o offset
Specify the starting offset.
• -p N
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

Remove N components from path.
• -r
Perform a recovery operation.
• -R record_pos_file record_pos
Specify record position file and record position.
• -u
Perform an update operation.
• -v
Verbose mode. Print more output about what the program does. This option can be given multiple
times to produce more and more output.
• -w write_file
Specify the write file.
• -V
Display version information.

4.6.5 myisampack — Generate Compressed, Read-Only MyISAM Tables
The myisampack utility compresses MyISAM tables. myisampack works by compressing each column
in the table separately. Usually, myisampack packs the data file 40% to 70%.
When the table is used later, the server reads into memory the information needed to decompress
columns. This results in much better performance when accessing individual rows, because you only
have to uncompress exactly one row.
MySQL uses mmap() when possible to perform memory mapping on compressed tables. If mmap()
does not work, MySQL falls back to normal read/write file operations.
Please note the following:
• If the mysqld server was invoked with external locking disabled, it is not a good idea to invoke
myisampack if the table might be updated by the server during the packing process. It is safest to
compress tables with the server stopped.
• After packing a table, it becomes read only. This is generally intended (such as when accessing
packed tables on a CD).
Invoke myisampack like this:
shell> myisampack [options] file_name ...

Each file name argument should be the name of an index (.MYI) file. If you are not in the database
directory, you should specify the path name to the file. It is permissible to omit the .MYI extension.
After you compress a table with myisampack, use myisamchk -rq to rebuild its indexes.
Section 4.6.3, “myisamchk — MyISAM Table-Maintenance Utility”.
myisampack supports the following options. It also reads option files and supports the options for
processing them described at Section 4.2.7, “Command-Line Options that Affect Option-File Handling”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

•

--help, -?
Display a help message and exit.

•

--backup, -b
Make a backup of each table's data file using the name tbl_name.OLD.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o.

•

--force, -f
Produce a packed table even if it becomes larger than the original or if the intermediate file from
an earlier invocation of myisampack exists. (myisampack creates an intermediate file named
tbl_name.TMD in the database directory while it compresses the table. If you kill myisampack,
the .TMD file might not be deleted.) Normally, myisampack exits with an error if it finds that
tbl_name.TMD exists. With --force, myisampack packs the table anyway.

•

--join=big_tbl_name, -j big_tbl_name
Join all tables named on the command line into a single packed table big_tbl_name. All tables that
are to be combined must have identical structure (same column names and types, same indexes,
and so forth).
big_tbl_name must not exist prior to the join operation. All source tables named on the command
line to be merged into big_tbl_name must exist. The source tables are read for the join
operation but not modified. The join operation does not create a .frm file for big_tbl_name,
so after the join operation finishes, copy the .frm file from one of the source tables and name it
big_tbl_name.frm.

•

--silent, -s
Silent mode. Write output only when errors occur.

•

--test, -t
Do not actually pack the table, just test packing it.

•

--tmpdir=dir_name, -T dir_name
Use the named directory as the location where myisampack creates temporary files.

•

--verbose, -v
Verbose mode. Write information about the progress of the packing operation and its result.

•

--version, -V
Display version information and exit.

•

--wait, -w
Wait and retry if the table is in use. If the mysqld server was invoked with external locking disabled,
it is not a good idea to invoke myisampack if the table might be updated by the server during the
packing process.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

The following sequence of commands illustrates a typical table compression session:
shell> ls -l
-rw-rw-r--rw-rw-r--rw-rw-r--

station.*
1 monty
1 monty
1 monty

my
my
my

994128 Apr 17 19:00 station.MYD
53248 Apr 17 19:00 station.MYI
5767 Apr 17 19:00 station.frm

shell> myisamchk -dvv station
MyISAM file:
station
Isam-version: 2
Creation time: 1996-03-13 10:08:58
Recover time: 1997-02-02 3:06:43
Data records:
1192 Deleted blocks:
0
Datafile parts:
1192 Deleted data:
0
Datafile pointer (bytes):
2 Keyfile pointer (bytes):
2
Max datafile length:
54657023 Max keyfile length:
33554431
Recordlength:
834
Record format: Fixed length
table description:
Key Start Len Index
Type
1
2
4
unique unsigned long
2
32
30 multip. text
Field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

This
documentation
is for an
older version.
If you're

Start
1
2
6
10
11
31
32
62
97
132
167
171
187
222
226
242
262
282
302
332
336
340
341
349
357
365
367
369
373
377
378
380
388
392
396
400
404
405
409
413
417
421
425
429
449

Root
1024
10240

Blocksize
1024
1024

Rec/key
1
1

Length Type
1
4
4
1
20
1
30
35
35
35
4
16
35
4
16
20
20
20
30
4
4
1
8
8
8
2
2
4
4
1
2
8
4
4
4
4
1
4
4
4
4
4
4
20
30

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

46
47
48
49
50
51
52
53
54
55
56
57

479
480
481
560
639
718
797
805
806
807
827
831

1
1
79
79
79
79
8
1
1
20
4
4

shell> myisampack station.MYI
Compressing station.MYI: (1192 records)
- Calculating statistics
normal:
20 empty-space:
16 empty-zero:
12
pre-space:
0 end-space:
12 table-lookups:
5
Original trees: 57 After join: 17
- Compressing file
87.14%
Remember to run myisamchk -rq on compressed tables

empty-fill:
zero:

11
7

shell> myisamchk -rq station
- check record delete-chain
- recovering (with sort) MyISAM-table 'station'
Data records: 1192
- Fixing index 1
- Fixing index 2
shell> mysqladmin -uroot flush-tables
shell> ls -l
-rw-rw-r--rw-rw-r--rw-rw-r--

station.*
1 monty
1 monty
1 monty

my
my
my

127874 Apr 17 19:00 station.MYD
55296 Apr 17 19:04 station.MYI
5767 Apr 17 19:00 station.frm

shell> myisamchk -dvv station
MyISAM file:
station
Isam-version: 2
Creation time: 1996-03-13 10:08:58
Recover time: 1997-04-17 19:04:26
Data records:
1192 Deleted blocks:
0
Datafile parts:
1192 Deleted data:
0
Datafile pointer (bytes):
3 Keyfile pointer (bytes):
1
Max datafile length:
16777215 Max keyfile length:
131071
Recordlength:
834
Record format: Compressed
table description:
Key Start Len Index
Type
1
2
4
unique unsigned long
2
32
30 multip. text
Field
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

This
documentation
is for an
older version.
If you're

Start
1
2
6
10
11
31
32
62
97
132
167
171
187
222
226

Length
1
4
4
1
20
1
30
35
35
35
4
16
35
4
16

Root
10240
54272

Type
constant
zerofill(1)
no zeros, zerofill(1)
table-lookup
no endspace,
no endspace,
no empty
no endspace,
zerofill(1)
no endspace,
no endspace,
zerofill(1)
no endspace,

not_always
not_always, no
not_always, no
not_always, no
not_always, no
not_always, no

Blocksize
1024
1024
Huff tree
1
2
2
3
4
3
5
empty
6
7
empty
6
2
empty
5
empty
6
2
empty
5

Rec/key
1
1
Bits
0
9
9
9
0
9
9
9
9
9
9
9
9
9
9

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

242
262
282
302
332
336
340
341
349
357
365
367
369
373
377
378
380
388
392
396
400
404
405
409
413
417
421
425
429
449
479
480
481
560
639
718
797
805
806
807
827
831

20
20
20
30
4
4
1
8
8
8
2
2
4
4
1
2
8
4
4
4
4
1
4
4
4
4
4
4
20
30
1
1
79
79
79
79
8
1
1
20
4
4

no endspace,
no endspace,
no endspace,
no endspace,
always zero
always zero

not_always
no empty
no empty
no empty

table-lookup
table-lookup
always zero
no zeros, zerofill(1)
no zeros, zerofill(1)
table-lookup
no zeros, zerofill(1)
no zeros
always zero
table-lookup
no zeros, zerofill(1)
no zeros, zerofill(1)
no zeros
always zero
no zeros
always zero
no zeros
always zero
no empty
no empty

no
no
no
no
no

endspace, no empty
empty
empty
endspace
empty

no empty
no zeros, zerofill(2)
no zeros, zerofill(1)

8
8
5
6
2
2
3
9
10
2
2
2
2
11
3
2
2
2
12
13
2
2
2
2
2
2
2
2
3
3
14
14
15
2
2
16
2
17
3
3
2
2

9
9
9
9
9
9
9
0
0
9
9
9
9
0
9
9
9
9
0
9
9
9
9
9
9
9
9
9
9
9
4
4
9
9
9
9
9
1
9
9
9
9

myisampack displays the following kinds of information:
• normal
The number of columns for which no extra packing is used.
• empty-space
The number of columns containing values that are only spaces. These occupy one bit.
• empty-zero
The number of columns containing values that are only binary zeros. These occupy one bit.
• empty-fill
The number of integer columns that do not occupy the full byte range of their type. These are
changed to a smaller type. For example, a BIGINT column (eight bytes) can be stored as a
TINYINT column (one byte) if all its values are in the range from -128 to 127.
• pre-space
The number of decimal columns that are stored with leading spaces. In this case, each value
contains a count for the number of leading spaces.
• end-space
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

myisampack — Generate Compressed, Read-Only MyISAM Tables

The number of columns that have a lot of trailing spaces. In this case, each value contains a count
for the number of trailing spaces.
• table-lookup
The column had only a small number of different values, which were converted to an ENUM before
Huffman compression.
• zero
The number of columns for which all values are zero.
• Original trees
The initial number of Huffman trees.
• After join
The number of distinct Huffman trees left after joining trees to save some header space.
After a table has been compressed, the Field lines displayed by myisamchk -dvv include additional
information about each column:
• Type
The data type. The value may contain any of the following descriptors:
• constant
All rows have the same value.
• no endspace
Do not store endspace.
• no endspace, not_always
Do not store endspace and do not do endspace compression for all values.
• no endspace, no empty
Do not store endspace. Do not store empty values.
• table-lookup
The column was converted to an ENUM.
• zerofill(N)
The most significant N bytes in the value are always 0 and are not stored.
• no zeros
Do not store zeros.
• always zero
Zero values are stored using one bit.
• Huff tree
The number of the Huffman tree associated with the column.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlaccess — Client for Checking Access Privileges

• Bits
The number of bits used in the Huffman tree.
After you run myisampack, use myisamchk to re-create any indexes. At this time, you can also sort
the index blocks and create statistics needed for the MySQL optimizer to work more efficiently:
shell> myisamchk -rq --sort-index --analyze tbl_name.MYI

After you have installed the packed table into the MySQL database directory, you should execute
mysqladmin flush-tables to force mysqld to start using the new table.
To unpack a packed table, use the --unpack option to myisamchk.

4.6.6 mysqlaccess — Client for Checking Access Privileges
mysqlaccess is a diagnostic tool that Yves Carlier has provided for the MySQL distribution. It checks
the access privileges for a host name, user name, and database combination. Note that mysqlaccess
checks access using only the user, db, and host tables. It does not check table, column, or routine
privileges specified in the tables_priv, columns_priv, or procs_priv tables.
Invoke mysqlaccess like this:
shell> mysqlaccess [host_name [user_name [db_name]]] [options]

mysqlaccess supports the following options.
Table 4.10 mysqlaccess Options
Format

Description

--brief

Generate reports in single-line tabular format

--commit

Copy the new access privileges from the temporary tables to the
original grant tables

--copy

Reload the temporary grant tables from original ones

--db

Specify the database name

--debug

Specify the debug level

--help

Display help message and exit

--host

Connect to MySQL server on given host

--howto

Display some examples that show how to use mysqlaccess

--old_server

Assume that the server is an old MySQL server (prior to MySQL
3.21)

--password

Password to use when connecting to server

--plan

Display suggestions and ideas for future releases

--preview

Show the privilege differences after making changes to the
temporary grant tables

--relnotes

Display release notes

--rhost

Connect to MySQL server on given host

--rollback

Undo the most recent changes to the temporary grant tables.

--spassword

Password to use when connecting to server as the superuser

--superuser

Specify the user name for connecting as the superuser

--table

Generate reports in table format

--user

MySQL user name to use when connecting to server

--version

Display version information and exit

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlaccess — Client for Checking Access Privileges

•

--help, -?
Display a help message and exit.

•

--brief, -b
Generate reports in single-line tabular format.

•

--commit
Copy the new access privileges from the temporary tables to the original grant tables. The grant
tables must be flushed for the new privileges to take effect. (For example, execute a mysqladmin
reload command.)

•

--copy
Reload the temporary grant tables from original ones.

•

--db=db_name, -d db_name
Specify the database name.

•

--debug=N
Specify the debug level. N can be an integer from 0 to 3.

•

--host=host_name, -h host_name
The host name to use in the access privileges.

•

--howto
Display some examples that show how to use mysqlaccess.

•

--old_server
Assume that the server is an old MySQL server (before MySQL 3.21) that does not yet know how to
handle full WHERE clauses.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you omit the password value following the
--password or -p option on the command line, mysqlaccess prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”.

•

--plan
Display suggestions and ideas for future releases.

•

--preview
Show the privilege differences after making changes to the temporary grant tables.

•

--relnotes
Display the release notes.

•

--rhost=host_name, -H host_name
Connect to the MySQL server on the given host.

•

--rollback

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

Undo the most recent changes to the temporary grant tables.
•

--spassword[=password], -P[password]
The password to use when connecting to the server as the superuser. If you omit the password
value following the --spassword or -p option on the command line, mysqlaccess prompts for
one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”.

•

--superuser=user_name, -U user_name
Specify the user name for connecting as the superuser.

•

--table, -t
Generate reports in table format.

•

--user=user_name, -u user_name
The user name to use in the access privileges.

•

--version, -v
Display version information and exit.

If your MySQL distribution is installed in some nonstandard location, you must change the location
where mysqlaccess expects to find the mysql client. Edit the mysqlaccess script at approximately
line 18. Search for a line that looks like this:
$MYSQL

= '/usr/local/bin/mysql';

# path to mysql executable

Change the path to reflect the location where mysql actually is stored on your system. If you do not do
this, a Broken pipe error will occur when you run mysqlaccess.

4.6.7 mysqlbinlog — Utility for Processing Binary Log Files
The server's binary log consists of files containing “events” that describe modifications to database
contents. The server writes these files in binary format. To display their contents in text format, use the
mysqlbinlog utility. You can also use mysqlbinlog to display the contents of relay log files written
by a slave server in a replication setup because relay logs have the same format as binary logs. The
binary log and relay log are discussed further in Section 5.4.3, “The Binary Log”, and Section 16.2.2,
“Replication Relay and Status Logs”.
Invoke mysqlbinlog like this:
shell> mysqlbinlog [options] log_file ...

For example, to display the contents of the binary log file named binlog.000003, use this command:
shell> mysqlbinlog binlog.0000003

The output includes events contained in binlog.000003. Event information includes the SQL
statement, the ID of the server on which it was executed, the timestamp when the statement was
executed, how much time it took, and so forth.
Events are preceded by header comments that provide additional information. For example:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

# at 141
#100309 9:28:36 server id 123 end_log_pos 245
Query thread_id=3350 exec_time=11 error_code=0

In the first line, the number following at indicates the file offset, or starting position, of the event in the
binary log file.
The second line starts with a date and time indicating when the statement started on the server where
the event originated. For replication, this timestamp is propagated to slave servers. server id is
the server_id value of the server where the event originated. end_log_pos indicates where the
next event starts (that is, it is the end position of the current event + 1). thread_id indicates which
thread executed the event. exec_time is the time spent executing the event, on a master server. On
a slave, it is the difference of the end execution time on the slave minus the beginning execution time
on the master. The difference serves as an indicator of how much replication lags behind the master.
error_code indicates the result from executing the event. Zero means that no error occurred.
Note
When using event groups, the file offsets of events may be grouped together
and the comments of events may be grouped together. Do not mistake these
grouped events for blank file offsets.
The output from mysqlbinlog can be re-executed (for example, by using it as input to mysql) to redo
the statements in the log. This is useful for recovery operations after a server crash. For other usage
examples, see the discussion later in this section and in Section 7.5, “Point-in-Time (Incremental)
Recovery Using the Binary Log”.
Normally, you use mysqlbinlog to read binary log files directly and apply them to the local MySQL
server. It is also possible to read binary logs from a remote server by using the --read-fromremote-server option. To read remote binary logs, the connection parameter options can be given
to indicate how to connect to the server. These options are --host, --password, --port, -protocol, --socket, and --user; they are ignored except when you also use the --read-fromremote-server option.
When running mysqlbinlog against a large binary log, be careful that the filesystem has enough
space for the resulting files. To configure the directory that mysqlbinlog uses for temporary files, use
the TMPDIR environment variable.
mysqlbinlog supports the following options, which can be specified on the command line or in the
[mysqlbinlog] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.11 mysqlbinlog Options
Format

Description

--character-sets-dir

Directory where character sets are installed

--database

List entries for just this database

--debug

Write debugging log

--defaults-extra-file

Read named option file in addition to usual option files

--defaults-file

Read only named option file

--defaults-group-suffix

Option group suffix value

--disable-log-bin

Disable binary logging

--force-read

If mysqlbinlog reads a binary log event that it does not
recognize, it prints a warning

--help

Display help message and exit

--hexdump

Display a hex dump of the log in comments

--host

Connect to MySQL server on given host

This
documentation
is for an
older version.
If you're

Introduced

5.0.10

5.0.16

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

Format

Description

--local-load

Prepare local temporary files for LOAD DATA INFILE in
the specified directory

--no-defaults

Read no option files

--offset

Skip the first N entries in the log

--password

Password to use when connecting to server

--port

TCP/IP port number to use for connection

--position

Deprecated. Use --start-position

--print-defaults

Print default options

--protocol

Connection protocol to use

--read-from-remote-server

Read binary log from MySQL server rather than local log
file

--result-file

Direct output to named file

--set-charset

Add a SET NAMES charset_name statement to the
output

--short-form

Display only the statements contained in the log

--socket

For connections to localhost, the Unix socket file to use

--start-datetime

Read binary log from first event with timestamp equal to
or later than datetime argument

--start-position

Read binary log from first event with position equal to or
greater than argument

--stop-datetime

Stop reading binary log at first event with timestamp
equal to or greater than datetime argument

--stop-position

Stop reading binary log at first event with position equal
to or greater than argument

--to-last-log

Do not stop at the end of requested binary log from a
MySQL server, but rather continue printing to end of last
binary log

--user

MySQL user name to use when connecting to server

--version

Display version information and exit

•

Introduced

5.0.23

--help, -?
Display a help message and exit.

•

--character-sets-dir=dir_name
The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.

•

--database=db_name, -d db_name
This option causes mysqlbinlog to output entries from the binary log (local log only) that occur
while db_name is been selected as the default database by USE.
The --database option for mysqlbinlog is similar to the --binlog-do-db option for mysqld,
but can be used to specify only one database. If --database is given multiple times, only the last
instance is used.
The --database option works as follows:
• While db_name is the default database, statements are output whether they modify tables in
db_name or a different database.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

• Unless db_name is selected as the default database, statements are not output, even if they
modify tables in db_name.
• There is an exception for CREATE DATABASE, ALTER DATABASE, and DROP DATABASE. The
database being created, altered, or dropped is considered to be the default database when
determining whether to output the statement.
Suppose that the binary log contains these statements:
INSERT INTO
INSERT INTO
USE test;
INSERT INTO
INSERT INTO
INSERT INTO
USE db2;
INSERT INTO
INSERT INTO
INSERT INTO

test.t1 (i) VALUES(100);
db2.t2 (j) VALUES(200);
test.t1 (i) VALUES(101);
t1 (i)
VALUES(102);
db2.t2 (j) VALUES(201);
test.t1 (i) VALUES(103);
db2.t2 (j) VALUES(202);
t2 (j)
VALUES(203);

mysqlbinlog --database=test does not output the first two INSERT statements because there
is no default database. It outputs the three INSERT statements following USE test, but not the
three INSERT statements following USE db2.
mysqlbinlog --database=db2 does not output the first two INSERT statements because there
is no default database. It does not output the three INSERT statements following USE test, but
does output the three INSERT statements following USE db2.
•

--debug[=debug_options], -# [debug_options]
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o,/tmp/mysqlbinlog.trace.

•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of
str. For example, mysqlbinlog normally reads the [client] and [mysqlbinlog] groups.
If the --defaults-group-suffix=_other option is given, mysqlbinlog also reads the
[client_other] and [mysqlbinlog_other] groups. This option was added in MySQL 5.0.10.

•

--disable-log-bin, -D
Disable binary logging. This is useful for avoiding an endless loop if you use the --to-lastlog option and are sending the output to the same MySQL server. This option also is useful when
restoring after a crash to avoid duplication of the statements you have logged.
This option requires that you have the SUPER privilege. It causes mysqlbinlog to include a SET
sql_log_bin = 0 statement in its output to disable binary logging of the remaining output. The
SET statement is ineffective unless you have the SUPER privilege.

•

--force-read, -f

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

With this option, if mysqlbinlog reads a binary log event that it does not recognize, it prints a
warning, ignores the event, and continues. Without this option, mysqlbinlog stops if it reads such
an event.
•

--hexdump, -H
Display a hex dump of the log in comments. The hex output can be helpful for replication debugging.
Hex dump format is discussed later in this section. This option was added in MySQL 5.0.16.

•

--host=host_name, -h host_name
Get the binary log from the MySQL server on the given host.

•

--local-load=dir_name, -l dir_name
Prepare local temporary files for LOAD DATA INFILE in the specified directory.
Important
These temporary files are not automatically removed by mysqlbinlog or
any other MySQL program.

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--offset=N, -o N
Skip the first N entries in the log.

•

--password[=password], -p[password]
The password to use when connecting to the server. If you use the short option form (-p), you
cannot have a space between the option and the password. If you omit the password value
following the --password or -p option on the command line, mysqlbinlog prompts for one.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--port=port_num, -P port_num
The TCP/IP port number to use for connecting to a remote server.

•

--position=N
Deprecated. Use --start-position instead. --position is removed in MySQL 5.5.

•

--print-defaults
Print the program name and all options that it gets from option files.

•

--protocol={TCP|SOCKET|PIPE|MEMORY}
The connection protocol to use for connecting to the server. It is useful when the other connection
parameters normally would cause a protocol to be used other than the one you want. For details on
the permissible values, see Section 4.2.2, “Connecting to the MySQL Server”.

•

--read-from-remote-server, -R

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

Read the binary log from a MySQL server rather than reading a local log file. Any connection
parameter options are ignored unless this option is given as well. These options are --host, -password, --port, --protocol, --socket, and --user.
This option requires that the remote server be running. It works only for binary log files on the remote
server, not relay log files.
•

--result-file=name, -r name
Direct output to the given file.

•

--set-charset=charset_name
Add a SET NAMES charset_name statement to the output to specify the character set to be used
for processing log files. This option was added in MySQL 5.0.23.

•

--short-form, -s
Display only the statements contained in the log, without any extra information. This is for testing
only, and should not be used in production systems.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--start-datetime=datetime
Start reading the binary log at the first event having a timestamp equal to or later than the datetime
argument. The datetime value is relative to the local time zone on the machine where you run
mysqlbinlog. The value should be in a format accepted for the DATETIME or TIMESTAMP data
types. For example:
shell> mysqlbinlog --start-datetime="2005-12-25 11:25:56" binlog.000003

This option is useful for point-in-time recovery. See Section 7.3, “Example Backup and Recovery
Strategy”.
•

--start-position=N, -j N
Start reading the binary log at the first event having a position equal to or greater than N. This option
applies to the first log file named on the command line.
This option is useful for point-in-time recovery. See Section 7.3, “Example Backup and Recovery
Strategy”.

•

--stop-datetime=datetime
Stop reading the binary log at the first event having a timestamp equal to or later than the datetime
argument. This option is useful for point-in-time recovery. See the description of the --startdatetime option for information about the datetime value.
This option is useful for point-in-time recovery. See Section 7.3, “Example Backup and Recovery
Strategy”.

•

--stop-position=N
Stop reading the binary log at the first event having a position equal to or greater than N. This option
applies to the last log file named on the command line.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

This option is useful for point-in-time recovery. See Section 7.3, “Example Backup and Recovery
Strategy”.
•

--to-last-log, -t
Do not stop at the end of the requested binary log from a MySQL server, but rather continue printing
until the end of the last binary log. If you send the output to the same MySQL server, this may lead to
an endless loop. This option requires --read-from-remote-server.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to a remote server.

•

--version, -V
Display version information and exit.
In MySQL 5.0, the version number shown for mysqlbinlog is always 3.2.

You can also set the following variable by using --var_name=value syntax:
• open_files_limit
Specify the number of open file descriptors to reserve.
It is also possible to set variables by using --set-variable=var_name=value or -O
var_name=value syntax. This syntax is deprecated.
You can pipe the output of mysqlbinlog into the mysql client to execute the events contained in
the binary log. This technique is used to recover from a crash when you have an old backup (see
Section 7.5, “Point-in-Time (Incremental) Recovery Using the Binary Log”). For example:
shell> mysqlbinlog binlog.000001 | mysql -u root -p

Or:
shell> mysqlbinlog binlog.[0-9]* | mysql -u root -p

You can also redirect the output of mysqlbinlog to a text file instead, if you need to modify the
statement log first (for example, to remove statements that you do not want to execute for some
reason). After editing the file, execute the statements that it contains by using it as input to the mysql
program:
shell> mysqlbinlog binlog.000001 > tmpfile
shell> ... edit tmpfile ...
shell> mysql -u root -p < tmpfile

When mysqlbinlog is invoked with the --start-position option, it displays only those events
with an offset in the binary log greater than or equal to a given position (the given position must match
the start of one event). It also has options to stop and start when it sees an event with a given date and
time. This enables you to perform point-in-time recovery using the --stop-datetime option (to be
able to say, for example, “roll forward my databases to how they were today at 10:30 a.m.”).
If you have more than one binary log to execute on the MySQL server, the safe method is to process
them all using a single connection to the server. Here is an example that demonstrates what may be
unsafe:
shell> mysqlbinlog binlog.000001 | mysql -u root -p # DANGER!!

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

shell> mysqlbinlog binlog.000002 | mysql -u root -p # DANGER!!

Processing binary logs this way using multiple connections to the server causes problems if the first log
file contains a CREATE TEMPORARY TABLE statement and the second log contains a statement that
uses the temporary table. When the first mysql process terminates, the server drops the temporary
table. When the second mysql process attempts to use the table, the server reports “unknown table.”
To avoid problems like this, use a single mysql process to execute the contents of all binary logs that
you want to process. Here is one way to do so:
shell> mysqlbinlog binlog.000001 binlog.000002 | mysql -u root -p

Another approach is to write all the logs to a single file and then process the file:
shell> mysqlbinlog binlog.000001 > /tmp/statements.sql
shell> mysqlbinlog binlog.000002 >> /tmp/statements.sql
shell> mysql -u root -p -e "source /tmp/statements.sql"

mysqlbinlog can produce output that reproduces a LOAD DATA INFILE operation without the
original data file. mysqlbinlog copies the data to a temporary file and writes a LOAD DATA LOCAL
INFILE statement that refers to the file. The default location of the directory where these files are
written is system-specific. To specify a directory explicitly, use the --local-load option.
Because mysqlbinlog converts LOAD DATA INFILE statements to LOAD DATA LOCAL INFILE
statements (that is, it adds LOCAL), both the client and the server that you use to process the
statements must be configured with the LOCAL capability enabled. See Section 6.1.6, “Security Issues
with LOAD DATA LOCAL”.
Warning
The temporary files created for LOAD DATA LOCAL statements are not
automatically deleted because they are needed until you actually execute those
statements. You should delete the temporary files yourself after you no longer
need the statement log. The files can be found in the temporary file directory
and have names like original_file_name-#-#.
The --hexdump option produces a hex dump of the log contents:
shell> mysqlbinlog --hexdump master-bin.000001

The hex output consists of comment lines beginning with #, so the output might look like this for the
preceding command:
/*!40019 SET @@session.max_insert_delayed_threads=0*/;
/*!50003 SET @OLD_COMPLETION_TYPE=@@COMPLETION_TYPE,COMPLETION_TYPE=0*/;
# at 4
#051024 17:24:13 server id 1 end_log_pos 98
# Position Timestamp
Type
Master ID
Size
Master Pos
Flags
# 00000004 9d fc 5c 43
0f
01 00 00 00
5e 00 00 00
62 00 00 00
00 00
# 00000017 04 00 35 2e 30 2e 31 35 2d 64 65 62 75 67 2d 6c |..5.0.15.debug.l|
# 00000027 6f 67 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |og..............|
# 00000037 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................|
# 00000047 00 00 00 00 9d fc 5c 43 13 38 0d 00 08 00 12 00 |.......C.8......|
# 00000057 04 04 04 04 12 00 00 4b 00 04 1a
|.......K...|
#
Start: binlog v 4, server v 5.0.15-debug-log created 051024 17:24:13
#
at startup
ROLLBACK;

Hex dump output currently contains the following elements. This format is subject to change.
• Position: The byte position within the log file.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlbinlog — Utility for Processing Binary Log Files

• Timestamp: The event timestamp. In the example shown, '9d fc 5c 43' is the representation of
'051024 17:24:13' in hexadecimal.
• Type: The event type code. In the example shown, '0f' indicates a
FORMAT_DESCRIPTION_EVENT. The following table lists the possible type codes.
TypeName

Meaning

00

UNKNOWN_EVENT

This event should never be present in the log.

01

START_EVENT_V3 This indicates the start of a log file written by MySQL 4 or earlier.

02

QUERY_EVENT

The most common type of events. These contain statements executed on
the master.

03

STOP_EVENT

Indicates that master has stopped.

04

ROTATE_EVENT

Written when the master switches to a new log file.

05

INTVAR_EVENT

Used for AUTO_INCREMENT values or when the LAST_INSERT_ID()
function is used in the statement.

06

LOAD_EVENT

Used for LOAD DATA INFILE in MySQL 3.23.

07

SLAVE_EVENT

Reserved for future use.

08

CREATE_FILE_EVENT
Used for LOAD DATA INFILE statements. This indicates the start of
execution of such a statement. A temporary file is created on the slave.
Used in MySQL 4 only.

09

APPEND_BLOCK_EVENT
Contains data for use in a LOAD DATA INFILE statement. The data is
stored in the temporary file on the slave.

0a

EXEC_LOAD_EVENTUsed for LOAD DATA INFILE statements. The contents of the temporary
file is stored in the table on the slave. Used in MySQL 4 only.

0b

DELETE_FILE_EVENT
Rollback of a LOAD DATA INFILE statement. The temporary file should
be deleted on the slave.

0c

NEW_LOAD_EVENT Used for LOAD DATA INFILE in MySQL 4 and earlier.

0d

RAND_EVENT

0e

USER_VAR_EVENT Used to replicate user variables.

0f

FORMAT_DESCRIPTION_EVENT
This indicates the start of a log file written by MySQL 5 or later.

10

XID_EVENT

11

BEGIN_LOAD_QUERY_EVENT
Used for LOAD DATA INFILE statements in MySQL 5 and later.

12

EXECUTE_LOAD_QUERY_EVENT
Used for LOAD DATA INFILE statements in MySQL 5 and later.

13

TABLE_MAP_EVENTReserved for future use.

14

WRITE_ROWS_EVENT
Reserved for future use.

15

UPDATE_ROWS_EVENT
Reserved for future use.

16

DELETE_ROWS_EVENT
Reserved for future use.

Used to send information about random values if the RAND() function is
used in the statement.

Event indicating commit of an XA transaction.

• Master ID: The server ID of the master that created the event.
• Size: The size in bytes of the event.
• Master Pos: The position of the next event in the original master log file.
• Flags: 16 flags. The following flags are used. The others are reserved for future use.
Flag Name
01

This
documentation
is for an
older version.
If you're

Meaning

LOG_EVENT_BINLOG_IN_USE_F
Log file correctly closed. (Used only in FORMAT_DESCRIPTION_EVENT.)
If this flag is set (if the flags are, for example, '01 00') in a
This
documentation
is for an
older version.
If you're

mysqldumpslow — Summarize Slow Query Log Files

Flag Name

Meaning
FORMAT_DESCRIPTION_EVENT, the log file has not been properly closed.
Most probably this is because of a master crash (for example, due to
power failure).

02

Reserved for future use.

04

LOG_EVENT_THREAD_SPECIFIC_F
Set if the event is dependent on the connection it was executed in (for
example, '04 00'), for example, if the event uses temporary tables.

08

LOG_EVENT_SUPPRESS_USE_F
Set in some circumstances when the event is not dependent on the default
database.

4.6.8 mysqldumpslow — Summarize Slow Query Log Files
The MySQL slow query log contains information about queries that take a long time to execute (see
Section 5.4.4, “The Slow Query Log”). mysqldumpslow parses MySQL slow query log files and prints
a summary of their contents.
Normally, mysqldumpslow groups queries that are similar except for the particular values of number
and string data values. It “abstracts” these values to N and 'S' when displaying summary output. The
-a and -n options can be used to modify value abstracting behavior.
Invoke mysqldumpslow like this:
shell> mysqldumpslow [options] [log_file ...]

mysqldumpslow supports the following options.
Table 4.12 mysqldumpslow Options
Format

Description

-a

Do not abstract all numbers to N and strings to S

-n

Abstract numbers with at least the specified digits

--debug

Write debugging information

-g

Only consider statements that match the pattern

--help

Display help message and exit

-h

Host name of the server in the log file name

-i

Name of the server instance

-l

Do not subtract lock time from total time

-r

Reverse the sort order

-s

How to sort output

-t

Display only first num queries

--verbose

Verbose mode

•

--help
Display a help message and exit.

• -a
Do not abstract all numbers to N and strings to 'S'.
•

--debug, -d
Run in debug mode.

• -g pattern
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlhotcopy — A Database Backup Program

Consider only queries that match the (grep-style) pattern.
• -h host_name
Host name of MySQL server for *-slow.log file name. The value can contain a wildcard. The
default is * (match all).
• -i name
Name of server instance (if using mysql.server startup script).
• -l
Do not subtract lock time from total time.
• -n N
Abstract numbers with at least N digits within names.
• -r
Reverse the sort order.
• -s sort_type
How to sort the output. The value of sort_type should be chosen from the following list:
• t, at: Sort by query time or average query time
• l, al: Sort by lock time or average lock time
• r, ar: Sort by rows sent or average rows sent
• c: Sort by count
By default, mysqldumpslow sorts by average query time (equivalent to -s at).
• -t N
Display only the first N queries in the output.
•

--verbose, -v
Verbose mode. Print more information about what the program does.

Example of usage:
shell> mysqldumpslow
Reading mysql slow query log from /usr/local/mysql/data/mysqld51-apple-slow.log
Count: 1 Time=4.32s (4s) Lock=0.00s (0s) Rows=0.0 (0), root[root]@localhost
insert into t2 select * from t1
Count: 3 Time=2.53s (7s) Lock=0.00s (0s)
insert into t2 select * from t1 limit N

Rows=0.0 (0), root[root]@localhost

Count: 3 Time=2.13s (6s) Lock=0.00s (0s)
insert into t1 select * from t1

Rows=0.0 (0), root[root]@localhost

4.6.9 mysqlhotcopy — A Database Backup Program
mysqlhotcopy is a Perl script that was originally written and contributed by Tim Bunce. It uses FLUSH
TABLES, LOCK TABLES, and cp or scp to make a database backup. It is a fast way to make a backup

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlhotcopy — A Database Backup Program

of the database or single tables, but it can be run only on the same machine where the database
directories are located. mysqlhotcopy works only for backing up MyISAM and ARCHIVE tables. It
runs on Unix and NetWare.
To use mysqlhotcopy, you must have read access to the files for the tables that you are backing up,
the SELECT privilege for those tables, the RELOAD privilege (to be able to execute FLUSH TABLES),
and the LOCK TABLES privilege (to be able to lock the tables).
shell> mysqlhotcopy db_name [/path/to/new_directory]

shell> mysqlhotcopy db_name_1 ... db_name_n /path/to/new_directory

Back up tables in the given database that match a regular expression:
shell> mysqlhotcopy db_name./regex/

The regular expression for the table name can be negated by prefixing it with a tilde (“~”):
shell> mysqlhotcopy db_name./~regex/

mysqlhotcopy supports the following options, which can be specified on the command line or in the
[mysqlhotcopy] and [client] groups of an option file. For information about option files used by
MySQL programs, see Section 4.2.6, “Using Option Files”.
Table 4.13 mysqlhotcopy Options
Format

Description

--addtodest

Do not rename target directory (if it exists); merely add files to it

--allowold

Do not abort if a target exists; rename it by adding an _old suffix

--checkpoint

Insert checkpoint entries

--chroot

Base directory of the chroot jail in which mysqld operates

--debug

Write debugging log

--dryrun

Report actions without performing them

--flushlog

Flush logs after all tables are locked

--help

Display help message and exit

--host

Connect to MySQL server on given host

--keepold

Do not delete previous (renamed) target when done

--method

The method for copying files

--noindices

Do not include full index files in the backup

--password

Password to use when connecting to server

--port

TCP/IP port number to use for connection

--quiet

Be silent except for errors

--regexp

Copy all databases with names that match the given regular
expression

--resetmaster

Reset the binary log after locking all the tables

--resetslave

Reset the master.info file after locking all the tables

--socket

For connections to localhost, the Unix socket file to use

--tmpdir

The temporary directory

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlhotcopy — A Database Backup Program

Format

Description

--user

MySQL user name to use when connecting to server

•

--help, -?
Display a help message and exit.

•

--addtodest
Do not rename target directory (if it exists); merely add files to it.

•

--allowold
Do not abort if a target exists; rename it by adding an _old suffix.

•

--checkpoint=db_name.tbl_name
Insert checkpoint entries into the specified database db_name and table tbl_name.

•

--chroot=dir_name
Base directory of the chroot jail in which mysqld operates. The dir_name value should match that
of the --chroot option given to mysqld.

•

--debug
Enable debug output.

•

--dryrun, -n
Report actions without performing them.

•

--flushlog
Flush logs after all tables are locked.

•

--host=host_name, -h host_name
The host name of the local host to use for making a TCP/IP connection to the local server. By
default, the connection is made to localhost using a Unix socket file.

•

--keepold
Do not delete previous (renamed) target when done.

•

--method=command
The method for copying files (cp or scp). The default is cp.

•

--noindices
Do not include full index files for MyISAM tables in the backup. This makes the backup smaller and
faster. The indexes for reloaded tables can be reconstructed later with myisamchk -rq.

•

--password=password, -ppassword
The password to use when connecting to the server. The password value is not optional for this
option, unlike for other MySQL programs.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

•

--port=port_num, -P port_num
The TCP/IP port number to use when connecting to the local server.

•

--quiet, -q
Be silent except for errors.

•

--record_log_pos=db_name.tbl_name
Record master and slave status in the specified database db_name and table tbl_name.

•

--regexp=expr
Copy all databases with names that match the given regular expression.

•

--resetmaster
Reset the binary log after locking all the tables.

•

--resetslave
Reset the master.info file after locking all the tables.

•

--socket=path, -S path
The Unix socket file to use for connections to localhost.

•

--suffix=str
The suffix to use for names of copied databases.

•

--tmpdir=dir_name
The temporary directory. The default is /tmp.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

Use perldoc for additional mysqlhotcopy documentation, including information about the structure
of the tables needed for the --checkpoint and --record_log_pos options:
shell> perldoc mysqlhotcopy

4.6.10 mysqlmanager — The MySQL Instance Manager
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
mysqlmanager is the MySQL Instance Manager (IM). This program monitors and manages MySQL
Database Server instances. MySQL Instance Manager is available for Unix-like operating systems, and
also on Windows as of MySQL 5.0.13. It runs as a daemon that listens on a TCP/IP port. On Unix, it
also listens on a Unix socket file.
MySQL Instance Manager is included in MySQL distributions from version 5.0.3, and can be used
in place of the mysqld_safe script to start and stop one or more instances of MySQL Server.
Because Instance Manager can manage multiple server instances, it can also be used in place of the
mysqld_multi script. Instance Manager offers these capabilities:
• Instance Manager can start and stop instances, and report on the status of instances.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

• Server instances can be treated as guarded or unguarded:
• When Instance Manager starts, it starts each guarded instance. If the instance crashes, Instance
Manager detects this and restarts it. When Instance Manager stops, it stops the instance.
• A nonguarded instance is not started when Instance Manager starts or monitored by it. If the
instance crashes after being started, Instance Manager does not restart it. When Instance
Manager exits, it does not stop the instance if it is running.
Instances are guarded by default. An instance can be designated as nonguarded by including the
nonguarded option in the configuration file.
• Instance Manager provides an interactive interface for configuring instances, so that the need to edit
the configuration file manually is reduced or eliminated.
• Instance Manager provides remote instance management. That is, it runs on the host where you
want to control MySQL Server instances, but you can connect to it from a remote host to perform
instance-management operations.
The following sections describe MySQL Instance Manager operation in more detail.

4.6.10.1 MySQL Instance Manager Command Options
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
The MySQL Instance Manager supports a number of command options. For a brief listing, invoke
mysqlmanager with the --help option. Options may be given on the command line or in the Instance
Manager configuration file. On Windows, the standard configuration file is my.ini in the directory
where Instance Manager is installed. On Unix, the standard file is /etc/my.cnf. To specify a different
configuration file, start Instance Manager with the --defaults-file option.
mysqlmanager supports the following options. It also reads option files and supports the options for
processing them described at Section 4.2.7, “Command-Line Options that Affect Option-File Handling”.
•

--help, -?
Display a help message and exit.

•

--angel-pid-file=file_name
The file in which the angel process records its process ID when mysqlmanager runs in
daemon mode (that is, when the --run-as-service option is given). The default file name is
mysqlmanager.angel.pid.
If the --angel-pid-file option is not given, the default angel PID file has the same name as
the PID file except that any PID file extension is replaced with an extension of .angel.pid. (For
example, mysqlmanager.pid becomes mysqlmanager.angel.pid.)
This option was added in MySQL 5.0.23.

•

--bind-address=IP
The IP address to bind to.

•

--default-mysqld-path=file_name
The path name of the MySQL Server binary. This path name is used for all server instance sections
in the configuration file for which no mysqld-path option is present. The default value of this

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

option is the compiled-in path name, which depends on how the MySQL distribution was configured.
Example: --default-mysqld-path=/usr/sbin/mysqld
•

--defaults-file=file_name
Read Instance Manager and MySQL Server settings from the given file. All configuration changes
made by the Instance Manager will be written to this file. This must be the first option on the
command line if it is used, and the file must exist.
If this option is not given, Instance Manager uses its standard configuration file. On Windows, the
standard file is my.ini in the directory where Instance Manager is installed. On Unix, the standard
file is /etc/my.cnf.

•

--install
On Windows, install Instance Manager as a Windows service. The service name is MySQL
Manager. This option was added in MySQL 5.0.11.

•

--log=file_name
The path to the Instance Manager log file. This option has no effect unless the --run-as-service
option is also given. If the file name specified for the option is a relative name, the log file is created
under the directory from which Instance Manager is started. To ensure that the file is created in a
specific directory, specify it as a full path name.
If --run-as-service is given without --log, the log file is mysqlmanager.log in the data
directory.
If --run-as-service is not given, log messages go to the standard output. To capture log output,
you can redirect Instance Manager output to a file:
mysqlmanager > im.log

•

--monitoring-interval=seconds
The interval in seconds for monitoring server instances. The default value is 20 seconds.
Instance Manager tries to connect to each monitored (guarded) instance using the nonexisting
MySQL_Instance_Manager user account to check whether it is available/not hanging. If the result
of the connection attempt indicates that the instance is unavailable, Instance Manager performs
several attempts to restart the instance.
Normally, the MySQL_Instance_Manager account does not exist, so the connection attempts by
Instance Manager cause the monitored instance to produce messages in its general query log similar
to the following:
Access denied for user 'MySQL_Instance_M'@'localhost' (using password: YES)

The nonguarded option in the appropriate server instance section disables monitoring for a
particular instance. If the instance dies after being started, Instance Manager will not restart it.
Instance Manager tries to connect to a nonguarded instance only when you request the instance's
status (for example, with the SHOW INSTANCES status.
See Section 4.6.10.5, “MySQL Server Instance Status Monitoring”, for more information.
•

--passwd, -P
Prepare an entry for the password file, print it to the standard output, and exit. You can redirect
the output from Instance Manager to a file to save the entry in the file. See also Section 4.6.10.4,
“Instance Manager User and Password Management”. This

•

--password-file=file_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

The name of the file where the Instance Manager looks for users and passwords. On Windows, the
default is mysqlmanager.passwd in the directory where Instance Manager is installed. On Unix,
the default file is /etc/mysqlmanager.passwd. See also Section 4.6.10.4, “Instance Manager
User and Password Management”.
•

--pid-file=file_name
The process ID file to use. On Windows, the default file is mysqlmanager.pid in the directory
where Instance Manager is installed. On Unix, the default is mysqlmanager.pid in the data
directory.

•

--port=port_num
The port number to use when listening for TCP/IP connections from clients. The default port number
(assigned by IANA) is 2273.

•

--print-defaults
Print the current defaults and exit. This must be the first option on the command line if it is used.

•

--remove
On Windows, removes Instance Manager as a Windows service. This assumes that Instance
Manager has been run with --install previously. This option was added in MySQL 5.0.11.

•

--run-as-service
On Unix, daemonize and start an angel process. The angel process monitors Instance Manager and
restarts it if it crashes. (The angel process itself is simple and unlikely to crash.)

•

--socket=path
On Unix, the socket file to use for incoming connections. The default file is named /tmp/
mysqlmanager.sock. This option has no meaning on Windows.

•

--standalone
This option is used on Windows to run Instance Manager in standalone mode. You should specify it
when you start Instance Manager from the command line. This option was added in MySQL 5.0.13.

•

--user=user_name
On Unix, the user name of the system account to use for starting and running mysqlmanager. This
option generates a warning and has no effect unless you start mysqlmanager as root (so that
it can change its effective user ID), or as the named user. It is recommended that you configure
mysqlmanager to run using the same account used to run the mysqld server. (“User” in this
context refers to a system login account, not a MySQL user listed in the grant tables.)

•

--version, -V
Display version information and exit.

•

--wait-timeout=N
The number of seconds to wait for activity on an incoming connection before closing it. The default is
28800 seconds (8 hours).
This option was added in MySQL 5.0.19. Before that, the timeout is 30 seconds and cannot be
changed.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

4.6.10.2 MySQL Instance Manager Configuration Files
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
Instance Manager uses its standard configuration file unless it is started with a --defaults-file
option that specifies a different file. On Windows, the standard file is my.ini in the directory where
Instance Manager is installed. On Unix, the standard file is /etc/my.cnf. (Prior to MySQL 5.0.10, the
MySQL Instance Manager read the same configuration files as the MySQL Server, including /etc/
my.cnf, ~/.my.cnf, and so forth.)
Instance Manager reads options for itself from the [manager] section of the configuration file, and
options for server instances from [mysqld] or [mysqldN] sections. The [manager] section
contains any of the options listed in Section 4.6.10.1, “MySQL Instance Manager Command Options”,
except for those specified as having to be given as the first option on the command line. Here is a
sample [manager] section:
# MySQL Instance Manager options section
[manager]
default-mysqld-path = /usr/local/mysql/libexec/mysqld
socket=/tmp/manager.sock
pid-file=/tmp/manager.pid
password-file = /home/cps/.mysqlmanager.passwd
monitoring-interval = 2
port = 1999
bind-address = 192.168.1.5

Each [mysqld] or [mysqldN] instance section specifies options given by Instance Manager to
a server instance at startup. These are mainly common MySQL Server options (see Section 5.1.3,
“Server Command Options”). In addition, a [mysqldN] section can contain the options in the following
list, which are specific to Instance Manager. These options are interpreted by Instance Manager itself; it
does not pass them to the server when it attempts to start that server.
Warning
The Instance Manager-specific options must not be used in a [mysqld]
section. If a server is started without using Instance Manager, it will not
recognize these options and will fail to start properly.
• mysqld-path = file_name
The path name of the mysqld server binary to use for the server instance.
• nonguarded
This option disables Instance Manager monitoring functionality for the server instance. By default,
an instance is guarded: At Instance Manager start time, it starts the instance. It also monitors
the instance status and attempts to restart it if it fails. At Instance Manager exit time, it stops the
instance. None of these things happen for nonguarded instances.
• shutdown-delay = seconds
The number of seconds Instance Manager should wait for the server instance to shut down. The
default value is 35 seconds. After the delay expires, Instance Manager assumes that the instance is
hanging and attempts to terminate it. If you use InnoDB with large tables, you should increase this
value.
Here are some sample instance sections:
[mysqld1]

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

mysqld-path=/usr/local/mysql/libexec/mysqld
socket=/tmp/mysql.sock
port=3307
server_id=1
skip-stack-trace
core-file
skip-bdb
log-bin
log-error
log=mylog
log-slow-queries
[mysqld2]
nonguarded
port=3308
server_id=2
mysqld-path= /home/cps/mysql/trees/mysql-5.0/sql/mysqld
socket
= /tmp/mysql.sock5
pid-file
= /tmp/hostname.pid5
datadir= /home/cps/mysql_data/data_dir1
language=/home/cps/mysql/trees/mysql-5.0/sql/share/english
log-bin
log=/tmp/fordel.log

4.6.10.3 Starting the MySQL Server with MySQL Instance Manager
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
This section discusses how Instance Manager starts server instances when it starts. However, before
you start Instance Manager, you should set up a password file for it. Otherwise, you will not be able to
connect to Instance Manager to control it after it starts. For details about creating Instance Manager
accounts, see Section 4.6.10.4, “Instance Manager User and Password Management”.
On Unix, the mysqld MySQL database server normally is started with the mysql.server
script, which usually resides in the /etc/init.d/ directory. In MySQL 5.0.3, this script invokes
mysqlmanager (the MySQL Instance Manager binary) to start MySQL. (In prior versions of MySQL
the mysqld_safe script is used for this purpose.) Starting from MySQL 5.0.4, the behavior of the
startup script was changed again to incorporate both setup schemes. In version 5.0.4, the startup script
uses the old scheme (invoking mysqld_safe) by default, but one can set the use_mysqld_safe
variable in the script to 0 (zero) to use the MySQL Instance Manager to start a server.
Starting with MySQL 5.0.19, you can use Instance Manager if you modify the my.cnf configuration file
by adding use-manager to the [mysql.server] section:
[mysql.server]
use-manager

When Instance Manager starts, it reads its configuration file if it exists to find server instance sections
and prepare a list of instances. Instance sections have names of the form [mysqld] or [mysqldN],
where N is an unsigned integer (for example, [mysqld1], [mysqld2], and so forth).
After preparing the list of instances, Instance Manager starts the guarded instances in the list. If there
are no instances, Instance Manager creates an instance named mysqld and attempts to start it
with default (compiled-in) configuration values. This means that the Instance Manager cannot find
the mysqld program if it is not installed in the default location. (Section 2.7, “Installation Layouts”,
describes default locations for components of MySQL distributions.) If you have installed the MySQL
server in a nonstandard location, you should create the Instance Manager configuration file.
Instance Manager also stops all guarded server instances when it shuts down.
The permissible options for [mysqldN] server instance sections are described in Section 4.6.10.2,
“MySQL Instance Manager Configuration Files”. In these sections, you can use a special mysqldThis
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

path=path-to-mysqld-binary option that is recognized only by Instance Manager. Use this option
to let Instance Manager know where the mysqld binary resides. If there are multiple instances, it may
also be necessary to set other options such as datadir and port, to ensure that each instance has
a different data directory and TCP/IP port number. Section 5.5, “Running Multiple MySQL Instances
on One Machine”, discusses the configuration values that must differ for each instance when you run
multiple instance on the same machine.
Warning
The [mysqld] instance section, if it exists, must not contain any Instance
Manager-specific options.
The typical Unix startup/shutdown cycle for a MySQL server with the MySQL Instance Manager
enabled is as follows:
1. The /etc/init.d/mysql script starts MySQL Instance Manager.
2. Instance Manager starts the guarded server instances and monitors them.
3. If a server instance fails, Instance Manager restarts it.
4. If Instance Manager is shut down (for example, with the /etc/init.d/mysql stop command), it
shuts down all server instances.

4.6.10.4 Instance Manager User and Password Management
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
The Instance Manager stores its user information in a password file. On Windows, the default is
mysqlmanager.passwd in the directory where Instance Manager is installed. On Unix, the default
file is /etc/mysqlmanager.passwd. To specify a different location for the password file, use the -password-file option.
If the password file does not exist or contains no password entries, you cannot connect to the Instance
Manager.
Note
Any Instance Manager process that is running to monitor server instances does
not notice changes to the password file. You must stop it and restart it after
making password entry changes.
Entries in the password file have the following format, where the two fields are the account user name
and encrypted password, separated by a colon:
petr:*35110DC9B4D8140F5DE667E28C72DD2597B5C848

Instance Manager password encryption is the same as that used by MySQL Server. It is a one-way
operation; no means are provided for decrypting encrypted passwords.
Instance Manager accounts differ somewhat from MySQL Server accounts:
• MySQL Server accounts are associated with a host name, user name, and password (see
Section 6.3.1, “User Names and Passwords”).
• Instance Manager accounts are associated with a user name and password only.
This means that a client can connect to Instance Manager with a given user name from any host. To
limit connections so that clients can connect only from the local host, start Instance Manager with the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

--bind-address=127.0.0.1 option so that it listens only to the local network interface. Remote
clients will not be able to connect. Local clients can connect like this:
shell> mysql -h 127.0.0.1 -P 2273

To generate a new entry, invoke Instance Manager with the --passwd option and append the output
to the /etc/mysqlmanager.passwd file. Here is an example:
shell> mysqlmanager --passwd >> /etc/mysqlmanager.passwd
Creating record for new user.
Enter user name: mike
Enter password: mikepass
Re-type password: mikepass

At the prompts, enter the user name and password for the new Instance Manager user. You must enter
the password twice. It does not echo to the screen, so double entry guards against entering a different
password than you intend (if the two passwords do not match, no entry is generated).
The preceding command causes the following line to be added to /etc/mysqlmanager.passwd:
mike:*BBF1F551DD9DD96A01E66EC7DDC073911BAD17BA

Use of the --passwd option fails if mysqlmanager is invoked directly from an IBM 5250 terminal. To
work around this, use a command like the following from the command line to generate the password
entry:
shell> mysql -B --skip-column-name \
-e 'SELECT CONCAT("user_name",":",PASSWORD("pass_val"));'

The output from the command can be used an entry in the /etc/mysqlmanager.passwd file.

4.6.10.5 MySQL Server Instance Status Monitoring
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
To monitor the status of each guarded server instance, the MySQL Instance Manager attempts to
connect to the instance at regular intervals using the MySQL_Instance_Manager@localhost user
account with a password of check_connection.
You are not required to create this account for MySQL Server; in fact, it is expected that it will not exist.
Instance Manager can tell that a server is operational if the server accepts the connection attempt but
refuses access for the account by returning a login error. However, these failed connection attempts
are logged by the server to its general query log (see Section 5.4.2, “The General Query Log”).
Instance Manager also attempts a connection to nonguarded server instances when you use the
SHOW INSTANCES or SHOW INSTANCE STATUS command. This is the only status monitoring done for
nonguarded instances.
Instance Manager knows if a server instance fails at startup because it receives a status from the
attempt. For an instance that starts but later crashes, Instance Manager receives a signal because it is
the parent process of the instance.

4.6.10.6 Connecting to MySQL Instance Manager
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

After you set up a password file for the MySQL Instance Manager and Instance Manager is running,
you can connect to it. The MySQL client/server protocol is used to communicate with the Instance
Manager. For example, you can connect to it using the standard mysql client program:
shell> mysql --port=2273 --host=im.example.org --user=mysql --password

Instance Manager supports the version of the MySQL client/server protocol used by the client tools and
libraries distributed with MySQL 4.1 or later, so other programs that use the MySQL C API also can
connect to it.

4.6.10.7 MySQL Instance Manager Commands
Important
MySQL Instance Manager is been deprecated in MySQL 5.1 and is removed in
MySQL 5.5.
After you connect to MySQL Instance Manager, you can issue commands. The following general
principles apply to Instance Manager command execution:
• Commands that take an instance name fail if the name is not a valid instance name.
• Commands that take an instance name fail if the instance does not exist.
• Instance Manager maintains information about instance configuration in an internal (in-memory)
cache. Initially, this information comes from the configuration file if it exists, but some commands
change the configuration of an instance. Commands that modify the configuration file fail if the file
does not exist or is not accessible to Instance Manager.
• On Windows, the standard file is my.ini in the directory where Instance Manager is installed. On
Unix, the standard configuration file is /etc/my.cnf. To specify a different configuration file, start
Instance Manager with the --defaults-file option.
• If a [mysqld] instance section exists in the configuration file, it must not contain any Instance
Manager-specific options (see Section 4.6.10.2, “MySQL Instance Manager Configuration Files”).
Therefore, you must not add any of these options if you change the configuration for an instance
named mysqld.
The following list describes the commands that Instance Manager accepts, with examples.
• START INSTANCE instance_name
This command attempts to start an offline instance. The command is asynchronous; it does not wait
for the instance to start.
mysql> START INSTANCE mysqld4;
Query OK, 0 rows affected (0,00 sec)

• STOP INSTANCE instance_name
This command attempts to stop an instance. The command is synchronous; it waits for the instance
to stop.
mysql> STOP INSTANCE mysqld4;
Query OK, 0 rows affected (0,00 sec)

• SHOW INSTANCES
Shows the names and status of all loaded instances.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqlmanager — The MySQL Instance Manager

mysql> SHOW INSTANCES;
+---------------+---------+
| instance_name | status |
+---------------+---------+
| mysqld3
| offline |
| mysqld4
| online |
| mysqld2
| offline |
+---------------+---------+

• SHOW INSTANCE STATUS instance_name
Shows status and version information for an instance.
mysql> SHOW INSTANCE STATUS mysqld3;
+---------------+--------+---------+
| instance_name | status | version |
+---------------+--------+---------+
| mysqld3
| online | unknown |
+---------------+--------+---------+

• SHOW INSTANCE OPTIONS instance_name
Shows the options used by an instance.
mysql> SHOW INSTANCE OPTIONS mysqld3;
+---------------+---------------------------------------------------+
| option_name
| value
|
+---------------+---------------------------------------------------+
| instance_name | mysqld3
|
| mysqld-path
| /home/cps/mysql/trees/mysql-4.1/sql/mysqld
|
| port
| 3309
|
| socket
| /tmp/mysql.sock3
|
| pid-file
| hostname.pid3
|
| datadir
| /home/cps/mysql_data/data_dir1/
|
| language
| /home/cps/mysql/trees/mysql-4.1/sql/share/english |
+---------------+---------------------------------------------------+

• SHOW instance_name LOG FILES
The command lists all log files used by the instance. The result set contains the path to the log file
and the log file size. If no log file path is specified in the instance section of the configuration file (for
example, log=/var/mysql.log), the Instance Manager tries to guess its placement. If Instance
Manager is unable to guess the log file placement you should specify the log file location explicitly by
using a log option in the appropriate instance section of the configuration file.
mysql> SHOW mysqld LOG FILES;
+-------------+------------------------------------+----------+
| Logfile
| Path
| Filesize |
+-------------+------------------------------------+----------+
| ERROR LOG
| /home/cps/var/mysql/owlet.err
| 9186
|
| GENERAL LOG | /home/cps/var/mysql/owlet.log
| 471503
|
| SLOW LOG
| /home/cps/var/mysql/owlet-slow.log | 4463
|
+-------------+------------------------------------+----------+

Log options are described in Section 5.1.3, “Server Command Options”.
• SHOW instance_name LOG {ERROR | SLOW | GENERAL} size[,offset_from_end]
This command retrieves a portion of the specified log file. Because most users are interested in
the latest log messages, the size parameter defines the number of bytes to retrieve from the end
of the log. To retrieve data from the middle of the log file, specify the optional offset_from_end
parameter. The following example retrieves 21 bytes of data, starting 23 bytes before the end of the
log file and ending 2 bytes before the end:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_convert_table_format — Convert Tables to Use a Given Storage Engine

mysql> SHOW mysqld LOG GENERAL 21, 2;
+---------------------+
| Log
|
+---------------------+
| using password: YES |
+---------------------+

• SET instance_name.option_name[=option_value]
This command edits the specified instance's configuration section to change or add instance options.
The option is added to the section is it is not already present. Otherwise, the new setting replaces the
existing one.
mysql> SET mysqld2.port=3322;
Query OK, 0 rows affected (0.00 sec)

Changes made to the configuration file do not take effect until the MySQL server is restarted. In
addition, these changes are not stored in the instance manager's local cache of instance settings
until a FLUSH INSTANCES command is executed.
• UNSET instance_name.option_name
This command removes an option from an instance's configuration section.
mysql> UNSET mysqld2.port;
Query OK, 0 rows affected (0.00 sec)

Changes made to the configuration file do not take effect until the MySQL server is restarted. In
addition, these changes are not stored in the instance manager's local cache of instance settings
until a FLUSH INSTANCES command is executed.
• FLUSH INSTANCES
This command forces Instance Manager reread the configuration file and to refresh internal
structures. This command should be performed after editing the configuration file. The command
does not restart instances.
mysql> FLUSH INSTANCES;
Query OK, 0 rows affected (0.04 sec)

FLUSH INSTANCES is deprecated and will be removed in a future MySQL release.

4.6.11 mysql_convert_table_format — Convert Tables to Use a Given
Storage Engine
mysql_convert_table_format converts the tables in a database to use a particular storage engine
(MyISAM by default). mysql_convert_table_format is written in Perl and requires that the DBI
and DBD::mysql Perl modules be installed (see Section 2.22, “Perl Installation Notes”).
Invoke mysql_convert_table_format like this:
shell> mysql_convert_table_format [options]db_name

The db_name argument indicates the database containing the tables to be converted.
mysql_convert_table_format supports the options described in the following list.
•

--help
Display a help message and exit.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_explain_log — Use EXPLAIN on Statements in Query Log

•

--force
Continue even if errors occur.

•

--host=host_name
Connect to the MySQL server on the given host.

•

--password=password
The password to use when connecting to the server. Note that the password value is not optional for
this option, unlike for other MySQL programs.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--port=port_num
The TCP/IP port number to use for the connection.

•

--socket=path
For connections to localhost, the Unix socket file to use.

•

--type=engine_name
Specify the storage engine that the tables should be converted to use. The default is MyISAM if this
option is not given.

•

--user=user_name
The MySQL user name to use when connecting to the server.

•

--verbose
Verbose mode. Print more information about what the program does.

•

--version
Display version information and exit.

4.6.12 mysql_explain_log — Use EXPLAIN on Statements in Query Log
mysql_explain_log reads its standard input for query log contents. It uses EXPLAIN to analyze
SELECT statements found in the input. UPDATE statements are rewritten to SELECT statements and
also analyzed with EXPLAIN. mysql_explain_log then displays a summary of its results.
The results may assist you in determining which queries result in table scans and where it would be
beneficial to add indexes to your tables.
Invoke mysql_explain_log like this, where log_file contains all or part of a MySQL query log:
shell> mysql_explain_log [options] < log_file

mysql_explain_log understands the following options:
•

--help, -?
Display a help message and exit.

•

--date=YYMMDD, -d YYMMDD

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_find_rows — Extract SQL Statements from Files

Select entries from the log only for the given date.
•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--password=password, -p password
The password to use when connecting to the server.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”.

•

--printerror=1, -e 1
Enable error output.

•

--socket=path, -S path
For connections to localhost, the Unix socket file to use, or, on Windows, the name of the named
pipe to use.

•

--user=user_name, -u user_name
The MySQL user name to use when connecting to the server.

4.6.13 mysql_find_rows — Extract SQL Statements from Files
mysql_find_rows reads files containing SQL statements and extracts statements that match a given
regular expression or that contain USE db_name or SET statements. The utility was written for use
with update log files (as used prior to MySQL 5.0) and as such expects statements to be terminated
with semicolon (;) characters. It may be useful with other files that contain SQL statements as long as
statements are terminated with semicolons.
Invoke mysql_find_rows like this:
shell> mysql_find_rows [options] [file_name ...]

Each file_name argument should be the name of file containing SQL statements. If no file names are
given, mysql_find_rows reads the standard input.
Examples:
mysql_find_rows --regexp=problem_table --rows=20 < update.log
mysql_find_rows --regexp=problem_table update-log.1 update-log.2

mysql_find_rows supports the following options:
•

--help, --Information
Display a help message and exit.

•

--regexp=pattern
Display queries that match the pattern.

•

--rows=N
Quit after displaying N queries.

•

--skip-use-db

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_fix_extensions — Normalize Table File Name Extensions

Do not include USE db_name statements in the output.
•

--start_row=N
Start output from this row.

4.6.14 mysql_fix_extensions — Normalize Table File Name Extensions
mysql_fix_extensions converts the extensions for MyISAM (or ISAM) table files to their canonical
forms. It looks for files with extensions matching any lettercase variant of .frm, .myd, .myi, .isd,
and .ism and renames them to have extensions of .frm, .MYD, .MYI, .ISD, and .ISM, respectively.
This can be useful after transferring the files from a system with case-insensitive file names (such as
Windows) to a system with case-sensitive file names.
Invoke mysql_fix_extensions like this, where data_dir is the path name to the MySQL data
directory.
shell> mysql_fix_extensions data_dir

4.6.15 mysql_setpermission — Interactively Set Permissions in Grant
Tables
mysql_setpermission is a Perl script that was originally written and contributed by Luuk de Boer.
It interactively sets permissions in the MySQL grant tables. mysql_setpermission is written in
Perl and requires that the DBI and DBD::mysql Perl modules be installed (see Section 2.22, “Perl
Installation Notes”).
Invoke mysql_setpermission like this:
shell> mysql_setpermission [options]

options should be either --help to display the help message, or options that indicate how to
connect to the MySQL server. The account used when you connect determines which permissions you
have when attempting to modify existing permissions in the grant tables.
mysql_setpermissions also reads options from the [client] and [perl] groups in the
.my.cnf file in your home directory, if the file exists.
mysql_setpermission supports the following options:
•

--help
Display a help message and exit.

•

--host=host_name
Connect to the MySQL server on the given host.

•

--password=password
The password to use when connecting to the server. Note that the password value is not optional for
this option, unlike for other MySQL programs.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”. You can use an option file to avoid giving the
password on the command line.

•

--port=port_num

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_tableinfo — Generate Database Metadata

The TCP/IP port number to use for the connection.
•

--socket=path
For connections to localhost, the Unix socket file to use.

•

--user=user_name
The MySQL user name to use when connecting to the server.

4.6.16 mysql_tableinfo — Generate Database Metadata
mysql_tableinfo creates tables and populates them with database metadata. It uses SHOW
DATABASES, SHOW TABLES, SHOW TABLE STATUS, SHOW COLUMNS, and SHOW INDEX to obtain the
metadata.
In MySQL 5.0 and up, the INFORMATION_SCHEMA database contains the same kind of
information in the SCHEMATA, TABLES, COLUMNS, and STATISTICS tables. See Chapter 19,
INFORMATION_SCHEMA Tables.
Invoke mysql_tableinfo like this:
shell> mysql_tableinfo [options] db_name [db_like [tbl_like]]

The db_name argument indicates which database mysql_tableinfo should use as the location for
the metadata tables. The database will be created if it does not exist. The tables will be named db, tbl
(or tbl_status), col, and idx.
If the db_like or tbl_like arguments are given, they are used as patterns and metadata is
generated only for databases or tables that match the patterns. These arguments default to % if not
given.
Examples:
mysql_tableinfo info
mysql_tableinfo info world
mysql_tableinfo info mydb tmp%

Each of the commands stores information into tables in the info database. The first stores information
for all databases and tables. The second stores information for all tables in the world database. The
third stores information for tables in the mydb database that have names matching the pattern tmp%.
mysql_tableinfo supports the following options:
Table 4.14 mysql_tableinfo Options
Format

Description

--clear

Before populating each metadata table, drop it if it exists

--clear-only

Similar to --clear, but exits after dropping the metadata tables to
be populated.

--col

Generate column metadata into the col table

--help

Display help message and exit

--host

Connect to MySQL server on given host

--idx

Generate index metadata into the idx table

--password

Password to use when connecting to server -- not optional

--port

TCP/IP port number to use for connection

--prefix

Add prefix_str at the beginning of each metadata table name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_tableinfo — Generate Database Metadata

Format

Description

--quiet

Be silent except for errors

--socket

For connections to localhost, the Unix socket file to use

--tbl-status

Use SHOW TABLE STATUS instead of SHOW TABLES

--user

The mysql_tableinfo user name to use when connecting to server

•

--help
Display a help message and exit.

•

--clear
Before populating each metadata table, drop it if it exists.

•

--clear-only
Similar to --clear, but exits after dropping the metadata tables to be populated.

•

--col
Generate column metadata into the col table.

•

--host=host_name, -h host_name
Connect to the MySQL server on the given host.

•

--idx
Generate index metadata into the idx table.

•

--password=password, -ppassword
The password to use when connecting to the server. Note that the password value is not optional
for this option, unlike for other MySQL programs. You can use an option file to avoid giving the
password on the command line.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1,
“End-User Guidelines for Password Security”.

•

--port=port_num, -P port_num
The TCP/IP port number to use for the connection.

•

--prefix=prefix_str
Add prefix_str at the beginning of each metadata table name.

•

--quiet, -q
Be silent except for errors.

•

--socket=path, -S path
The Unix socket file to use for the connection.

•

--tbl-status
Use SHOW TABLE STATUS instead of SHOW TABLES. This provides more complete information, but
is slower.

•

--user=user_name, -u user_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysql_waitpid — Kill Process and Wait for Its Termination

The MySQL user name to use when connecting to the server.

4.6.17 mysql_waitpid — Kill Process and Wait for Its Termination
mysql_waitpid signals a process to terminate and waits for the process to exit. It uses the kill()
system call and Unix signals, so it runs on Unix and Unix-like systems.
Invoke mysql_waitpid like this:
shell> mysql_waitpid [options] pid wait_time

mysql_waitpid sends signal 0 to the process identified by pid and waits up to wait_time seconds
for the process to terminate. pid and wait_time must be positive integers.
If process termination occurs within the wait time or the process does not exist, mysql_waitpid
returns 0. Otherwise, it returns 1.
If the kill() system call cannot handle signal 0, mysql_waitpid() uses signal 1 instead.
mysql_waitpid supports the following options:
•

--help, -?, -I
Display a help message and exit.

•

--verbose, -v
Verbose mode. Display a warning if signal 0 could not be used and signal 1 is used instead.

•

--version, -V
Display version information and exit.

4.6.18 mysql_zap — Kill Processes That Match a Pattern
mysql_zap kills processes that match a pattern. It uses the ps command and Unix signals, so it runs
on Unix and Unix-like systems.
Invoke mysql_zap like this:
shell> mysql_zap [-signal] [-?Ift] pattern

A process matches if its output line from the ps command contains the pattern. By default, mysql_zap
asks for confirmation for each process. Respond y to kill the process, or q to exit mysql_zap. For any
other response, mysql_zap does not attempt to kill the process.
If the -signal option is given, it specifies the name or number of the signal to send to each process.
Otherwise, mysql_zap tries first with TERM (signal 15) and then with KILL (signal 9).
mysql_zap supports the following additional options:
• --help, -?, -I
Display a help message and exit.
• -f
Force mode. mysql_zap attempts to kill each process without confirmation.
• -t

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Program Development Utilities

Test mode. Display information about each process but do not kill it.

4.7 MySQL Program Development Utilities
This section describes some utilities that you may find useful when developing MySQL programs.
In shell scripts, you can use the my_print_defaults program to parse option files and see
what options would be used by a given program. The following example shows the output that
my_print_defaults might produce when asked to show the options found in the [client] and
[mysql] groups:
shell> my_print_defaults client mysql
--port=3306
--socket=/tmp/mysql.sock
--no-auto-rehash

Note for developers: Option file handling is implemented in the C client library simply by processing
all options in the appropriate group or groups before any command-line arguments. This works well
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 that 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. For details, see the
documentation for your preferred interface.

4.7.1 msql2mysql — Convert mSQL Programs for Use with MySQL
Initially, the MySQL C API was developed to be very similar to that for the mSQL database system.
Because of this, mSQL programs often can be converted relatively easily for use with MySQL by
changing the names of the C API functions.
The msql2mysql utility performs the conversion of mSQL C API function calls to their MySQL
equivalents. msql2mysql converts the input file in place, so make a copy of the original before
converting it. For example, use msql2mysql like this:
shell> cp client-prog.c client-prog.c.orig
shell> msql2mysql client-prog.c
client-prog.c converted

Then examine client-prog.c and make any post-conversion revisions that may be necessary.
msql2mysql uses the replace utility to make the function name substitutions. See Section 4.8.2,
“replace — A String-Replacement Utility”.

4.7.2 mysql_config — Display Options for Compiling Clients
mysql_config provides you with useful information for compiling your MySQL client and connecting it
to MySQL. It is a shell script, so it is available only on Unix and Unix-like systems.
mysql_config supports the following options.
•

--cflags
Compiler flags to find include files and critical compiler flags and defines used when compiling the
libmysqlclient library. The options returned are tied to the specific compiler that was used when
the library was created and might clash with the settings for your own compiler. Use --include for
more portable options that contain only include paths.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

my_print_defaults — Display Options from Option Files

•

--include
Compiler options to find MySQL include files.

•

--libmysqld-libs, --embedded
Libraries and options required to link with the MySQL embedded server.

•

--libs
Libraries and options required to link with the MySQL client library.

•

--libs_r
Libraries and options required to link with the thread-safe MySQL client library.

•

--port
The default TCP/IP port number, defined when configuring MySQL.

•

--socket
The default Unix socket file, defined when configuring MySQL.

•

--version
Version number for the MySQL distribution.

If you invoke mysql_config with no options, it displays a list of all options that it supports, and their
values:
shell> mysql_config
Usage: /usr/local/mysql/bin/mysql_config [options]
Options:
--cflags
[-I/usr/local/mysql/include/mysql -mcpu=pentiumpro]
--include
[-I/usr/local/mysql/include/mysql]
--libs
[-L/usr/local/mysql/lib/mysql -lmysqlclient -lz
-lz -lcrypt -lnsl -lm]
--libs_r
[-L/usr/local/mysql/lib/mysql -lmysqlclient_r
-lz -lpthread -lcrypt -lnsl -lm -lpthread]
--socket
[/tmp/mysql.sock]
--port
[3306]
--version
[5.0.96]
--libmysqld-libs [-L/usr/local/mysql/lib/mysql -lmysqld
-lz -lpthread -lcrypt -lnsl -lm -lpthread -lrt]

You can use mysql_config within a command line using backticks to include the output that it
produces for particular options. For example, to compile and link a MySQL client program, use
mysql_config as follows:
gcc -c `mysql_config --cflags` progname.c
gcc -o progname progname.o `mysql_config --libs`

4.7.3 my_print_defaults — Display Options from Option Files
my_print_defaults displays the options that are present in option groups of option files. The output
indicates what options will be used by programs that read the specified option groups. For example, the
mysqlcheck program reads the [mysqlcheck] and [client] option groups. To see what options
are present in those groups in the standard option files, invoke my_print_defaults like this:
shell> my_print_defaults mysqlcheck client
--user=myusername
--password=secret

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

resolve_stack_dump — Resolve Numeric Stack Trace Dump to Symbols

--host=localhost

The output consists of options, one per line, in the form that they would be specified on the command
line.
my_print_defaults supports the following options.
•

--help, -?
Display a help message and exit.

•

--config-file=file_name, --defaults-file=file_name, -c file_name
Read only the given option file.

•

--debug=debug_options, -# debug_options
Write a debugging log. A typical debug_options string is d:t:o,file_name. The default is
d:t:o,/tmp/my_print_defaults.trace.

•

--defaults-extra-file=file_name, --extra-file=file_name, -e file_name
Read this option file after the global option file but (on Unix) before the user option file.

•

--defaults-group-suffix=suffix, -g suffix
In addition to the groups named on the command line, read groups that have the given suffix.

•

--no-defaults, -n
Return an empty string.

•

--verbose, -v
Verbose mode. Print more information about what the program does.

•

--version, -V
Display version information and exit.

4.7.4 resolve_stack_dump — Resolve Numeric Stack Trace Dump to
Symbols
resolve_stack_dump resolves a numeric stack dump to symbols.
Invoke resolve_stack_dump like this:
shell> resolve_stack_dump [options] symbols_file [numeric_dump_file]

The symbols file should include the output from the nm --numeric-sort mysqld command. The
numeric dump file should contain a numeric stack track from mysqld. If no numeric dump file is named
on the command line, the stack trace is read from the standard input.
resolve_stack_dump supports the following options.
•

--help, -h
Display a help message and exit.

•

--numeric-dump-file=file_name, -n file_name
Read the stack trace from the given file.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Miscellaneous Programs

•

--symbols-file=file_name, -s file_name
Use the given symbols file.

•

--version, -V
Display version information and exit.

For more information, see Section 21.3.1.5, “Using a Stack Trace”.

4.8 Miscellaneous Programs
4.8.1 perror — Explain Error Codes
For most system errors, MySQL displays, in addition to an internal text message, the system error code
in one of the following styles:
message ... (errno: #)
message ... (Errcode: #)

You can find out what the error code means by examining the documentation for your system or by
using the perror utility.
perror prints a description for a system error code or for a storage engine (table handler) error code.
Invoke perror like this:
shell> perror [options] errorcode ...

Example:
shell> perror 13 64
OS error code 13: Permission denied
OS error code 64: Machine is not on the network

To obtain the error message for a MySQL Cluster error code, invoke perror with the --ndb option:
shell> perror --ndb errorcode

The meaning of system error messages may be dependent on your operating system. A given error
code may mean different things on different operating systems.
perror supports the following options.
•

--help, --info, -I, -?
Display a help message and exit.

•

--ndb
Print the error message for a MySQL Cluster error code.

•

--silent, -s
Silent mode. Print only the error message.

•

--verbose, -v
Verbose mode. Print error code and message. This is the default behavior.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

replace — A String-Replacement Utility

•

--version, -V
Display version information and exit.

4.8.2 replace — A String-Replacement Utility
The replace utility program changes strings in place in files or on the standard input.
Invoke replace in one of the following ways:
shell> replace from to [from to] ... -- file_name [file_name] ...
shell> replace from to [from to] ... < file_name

from represents a string to look for and to represents its replacement. There can be one or more pairs
of strings.
Use the -- option to indicate where the string-replacement list ends and the file names begin. In this
case, any file named on the command line is modified in place, so you may want to make a copy of
the original before converting it. replace prints a message indicating which of the input files it actually
modifies.
If the -- option is not given, replace reads the standard input and writes to the standard output.
replace uses a finite state machine to match longer strings first. It can be used to swap strings. For
example, the following command swaps a and b in the given files, file1 and file2:
shell> replace a b b a -- file1 file2 ...

The replace program is used by msql2mysql. See Section 4.7.1, “msql2mysql — Convert mSQL
Programs for Use with MySQL”.
replace supports the following options.
• -?, -I
Display a help message and exit.
• -#debug_options
Enable debugging.
• -s
Silent mode. Print less information what the program does.
• -v
Verbose mode. Print more information about what the program does.
• -V
Display version information and exit.

4.8.3 resolveip — Resolve Host name to IP Address or Vice Versa
The resolveip utility resolves host names to IP addresses and vice versa.
Invoke resolveip like this:
shell> resolveip [options] {host_name|ip-addr} ...

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

resolveip — Resolve Host name to IP Address or Vice Versa

resolveip supports the following options.
•

--help, --info, -?, -I
Display a help message and exit.

•

--silent, -s
Silent mode. Produce less output.

•

--version, -V
Display version information and exit.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 5 MySQL Server Administration
Table of Contents
5.1 The MySQL Server .............................................................................................................
5.1.1 Server Option and Variable Reference ......................................................................
5.1.2 Server Configuration Defaults ...................................................................................
5.1.3 Server Command Options .........................................................................................
5.1.4 Server System Variables ..........................................................................................
5.1.5 Using System Variables ............................................................................................
5.1.6 Server Status Variables ............................................................................................
5.1.7 Server SQL Modes ...................................................................................................
5.1.8 Server-Side Help ......................................................................................................
5.1.9 Server Response to Signals ......................................................................................
5.1.10 The Server Shutdown Process ................................................................................
5.2 The MySQL Data Directory ..................................................................................................
5.3 The mysql System Database ...............................................................................................
5.4 MySQL Server Logs ............................................................................................................
5.4.1 The Error Log ..........................................................................................................
5.4.2 The General Query Log ............................................................................................
5.4.3 The Binary Log ........................................................................................................
5.4.4 The Slow Query Log ................................................................................................
5.4.5 Server Log Maintenance ...........................................................................................
5.5 Running Multiple MySQL Instances on One Machine ............................................................
5.5.1 Setting Up Multiple Data Directories ..........................................................................
5.5.2 Running Multiple MySQL Instances on Windows ........................................................
5.5.3 Running Multiple MySQL Instances on Unix ..............................................................
5.5.4 Using Client Programs in a Multiple-Server Environment ............................................

393
394
413
414
439
523
532
551
558
558
559
560
561
562
562
563
564
567
568
569
571
572
575
576

End of Product Lifecycle. Active development for MySQL Database Server version 5.0 has ended.
Oracle offers various support offerings which may be of interest. For details and more information,
see the MySQL section of the Lifetime Support Policy for Oracle Technology Products (http://
www.oracle.com/us/support/lifetime-support/index.html). Please consider upgrading to a recent
version.
MySQL Server (mysqld) is the main program that does most of the work in a MySQL installation. This
chapter provides an overview of MySQL Server and covers general server administration:
• Server configuration
• The data directory, particularly the mysql system database
• The server log files
• Management of multiple servers on a single machine
For additional information on administrative topics, see also:
• Chapter 6, Security
• Chapter 7, Backup and Recovery
• Chapter 16, Replication

5.1 The MySQL Server
mysqld is the MySQL server. The following discussion covers these MySQL server configuration
topics:
• Startup options that the server supports
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

• Server system variables
• Server status variables
• How to set the server SQL mode
• The server shutdown process
Note
Not all storage engines are supported by all MySQL server binaries and
configurations. To find out how to determine which storage engines your
MySQL server installation supports, see Section 13.7.5.13, “SHOW ENGINES
Syntax”.

5.1.1 Server Option and Variable Reference
The following table provides a list of all the command line options, server and status variables
applicable within mysqld.
The table lists command-line options (Cmd-line), options valid in configuration files (Option file), server
system variables (System Var), and status variables (Status var) in one unified list, with notification
of where each option/variable is valid. If a server option set on the command line or in an option file
differs from the name of the corresponding server system or status variable, the variable name is noted
immediately below the corresponding option. For status variables, the scope of the variable is shown
(Scope) as either global, session, or both. Please see the corresponding sections for details on setting
and using the options and variables. Where appropriate, a direct link to further information on the item
as available.
For a version of this table that is specific to MySQL Cluster, see Section 17.3.2.5, “MySQL Cluster
mysqld Option and Variable Reference”.
Table 5.1 Option/Variable Summary
Name

Cmd-Line

Option File

abort-slaveevent-count

Yes

Yes

System Var Status Var

Var Scope

Dynamic

Aborted_clients

Yes

Global

No

Aborted_connects

Yes

Global

No

allow-suspicious- Yes
udfs

Yes

ansi

Yes

Yes

auto_increment_increment

Yes

Both

Yes

auto_increment_offset

Yes

Both

Yes

autocommit

Yes

Session

Yes

automatic_sp_privileges

Yes

Global

Yes

back_log

Yes

Global

No

Yes

Global

No

Yes

Global

No

Global

No

Yes

Global

No

Yes

Global

No

Yes

Global

No

Global

No

basedir

Yes

Yes

bdb_cache_size
bdb-home

Yes

Yes

- Variable:
bdb_home
bdb-lock-detect

Yes

Yes

bdb_log_buffer_size
bdb-logdir
This
documentation
is for an
older version.
If you're

Yes

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

- Variable:
bdb_logdir

Yes

Global

No

bdb_max_lock

Yes

Global

No

Global

No

Global

No

Global

No

Global

No

Session

Yes

Session

Yes

Global

No

Global

Yes

Global

No

Both

Yes

bdb-no-recover

Yes

Yes

bdb-no-sync

Yes

Yes

bdb-shared-data Yes

Yes

- Variable:
bdb_shared_data
bdb-tmpdir

Yes
Yes

Yes

- Variable:
bdb_tmpdir
big-tables

Yes
Yes

Yes

- Variable:
big_tables
bind-address

Yes
Yes

Yes

Binlog_cache_disk_use

Yes

binlog_cache_sizeYes

Yes

Yes

Binlog_cache_use

Yes

binlog-do-db

Yes

Yes

binlog-ignore-db

Yes

Yes

bootstrap

Yes

Yes

bulk_insert_buffer_size
Yes

Yes

Yes

Bytes_received

Yes

Both

No

Bytes_sent

Yes

Both

No

Yes

Both

Yes

Yes

Both

Yes

Yes

Both

Yes

Both

Yes

character_set_client
character-setYes
client-handshake

Yes

character_set_connection
a

character_set_database
character-setfilesystem

Yes

Yes

- Variable:
character_set_filesystem

Yes

Both

Yes

character_set_results

Yes

Both

Yes

Both

Yes

character-setserver

Yes

Yes

- Variable:
character_set_server

Yes

Both

Yes

character_set_system

Yes

Global

No

Global

No

Yes

Global

No

Yes

Both

Yes

character-sets-dir Yes

Yes

- Variable:
character_sets_dir
chroot

Yes

collation_connection
This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

b

collation_database
collation-server

Yes

- Variable:
collation_server

System Var Status Var

Var Scope

Dynamic

Yes

Both

Yes

Both

Yes

Both

Yes

Yes
Yes

Com_admin_commands

Yes

Both

No

Com_alter_db

Yes

Both

No

Com_alter_event

Yes

Both

No

Com_alter_table

Yes

Both

No

Com_analyze

Yes

Both

No

Com_backup_table

Yes

Both

No

Com_begin

Yes

Both

No

Com_call_procedure

Yes

Both

No

Com_change_db

Yes

Both

No

Com_change_master

Yes

Both

No

Com_check

Yes

Both

No

Com_checksum

Yes

Both

No

Com_commit

Yes

Both

No

Com_create_db

Yes

Both

No

Com_create_event

Yes

Both

No

Com_create_function

Yes

Both

No

Com_create_index

Yes

Both

No

Com_create_table

Yes

Both

No

Com_create_user

Yes

Both

No

Com_dealloc_sql

Yes

Both

No

Com_delete

Yes

Both

No

Com_delete_multi

Yes

Both

No

Com_do

Yes

Both

No

Com_drop_db

Yes

Both

No

Com_drop_event

Yes

Both

No

Com_drop_function

Yes

Both

No

Com_drop_index

Yes

Both

No

Com_drop_table

Yes

Both

No

Com_drop_user

Yes

Both

No

Com_execute_sql

Yes

Both

No

Com_flush

Yes

Both

No

Com_grant

Yes

Both

No

Com_ha_close

Yes

Both

No

Com_ha_open

Yes

Both

No

Com_ha_read

Yes

Both

No

Com_help

Yes

Both

No

Com_insert

Yes

Both

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Com_insert_select

Yes

Both

No

Com_kill

Yes

Both

No

Com_load

Yes

Both

No

Com_lock_tables

Yes

Both

No

Com_optimize

Yes

Both

No

Com_preload_keys

Yes

Both

No

Com_prepare_sql

Yes

Both

No

Com_purge

Yes

Both

No

Com_purge_before_date

Yes

Both

No

Com_rename_table

Yes

Both

No

Com_repair

Yes

Both

No

Com_replace

Yes

Both

No

Com_replace_select

Yes

Both

No

Com_reset

Yes

Both

No

Com_restore_table

Yes

Both

No

Com_revoke

Yes

Both

No

Com_revoke_all

Yes

Both

No

Com_rollback

Yes

Both

No

Com_savepoint

Yes

Both

No

Com_select

Yes

Both

No

Com_set_option

Yes

Both

No

Com_show_binlog_events

Yes

Both

No

Com_show_binlogs

Yes

Both

No

Com_show_charsets

Yes

Both

No

Com_show_collations

Yes

Both

No

Com_show_column_types

Yes

Both

No

Com_show_create_db

Yes

Both

No

Com_show_create_event

Yes

Both

No

Com_show_create_table

Yes

Both

No

Com_show_databases

Yes

Both

No

Com_show_engine_logs

Yes

Both

No

Com_show_engine_mutex

Yes

Both

No

Com_show_engine_status

Yes

Both

No

Com_show_errors

Yes

Both

No

Com_show_events

Yes

Both

No

Com_show_fields

Yes

Both

No

Com_show_grants

Yes

Both

No

Com_show_innodb_status

Yes

Both

No

Com_show_keys

Yes

Both

No

Com_show_logs

Yes

Both

No

Com_show_master_status

Yes

Both

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Com_show_ndb_status

Yes

Both

No

Com_show_new_master

Yes

Both

No

Com_show_open_tables

Yes

Both

No

Com_show_plugins

Yes

Both

No

Com_show_privileges

Yes

Both

No

Com_show_processlist

Yes

Both

No

Com_show_slave_hosts

Yes

Both

No

Com_show_slave_status

Yes

Both

No

Com_show_status

Yes

Both

No

Com_show_storage_engines

Yes

Both

No

Com_show_tables

Yes

Both

No

Com_show_triggers

Yes

Both

No

Com_show_variables

Yes

Both

No

Com_show_warnings

Yes

Both

No

Com_slave_start

Yes

Both

No

Com_slave_stop

Yes

Both

No

Com_stmt_close

Yes

Both

No

Com_stmt_execute

Yes

Both

No

Com_stmt_fetch

Yes

Both

No

Com_stmt_prepare

Yes

Both

No

Com_stmt_reset

Yes

Both

No

Com_stmt_send_long_data

Yes

Both

No

Com_truncate

Yes

Both

No

Com_unlock_tables

Yes

Both

No

Com_update

Yes

Both

No

Com_update_multi

Yes

Both

No

Com_xa_commit

Yes

Both

No

Com_xa_end

Yes

Both

No

Com_xa_prepare

Yes

Both

No

Com_xa_recover

Yes

Both

No

Com_xa_rollback

Yes

Both

No

Com_xa_start

Yes

Both

No

Both

Yes

Session

No

completion_type

Yes

Yes

Yes

Compression

Yes

concurrent_insert Yes

Yes

Yes

Global

Yes

connect_timeout Yes

Yes

Yes

Global

Yes

Yes

Global

No

Created_tmp_disk_tables

Yes

Both

No

Created_tmp_files

Yes

Global

No

Connections
console

Yes

Yes

core-file

Yes

Yes

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Both

No

Yes

Global

No

date_format

Yes

Both

No

datetime_format

Yes

Both

No

Yes

Both

Yes

Yes

Both

Yes

Yes

Both

Yes

Global

Yes

Global

Yes

Global

No

Global

Yes

Global

No

Created_tmp_tables
datadir

debug

Yes

Yes
Yes

Yes

Yes

default-character- Yes
set

Yes

default-storageengine

Yes

Yes

default-table-type Yes

Yes

default-time-zone Yes

Yes

default_week_format
Yes

Yes

defaults-extra-file Yes
defaults-file

Yes

defaults-groupsuffix

Yes

delay-key-write

Yes

Yes

- Variable:
delay_key_write

Yes

Delayed_errors

Yes

delayed_insert_limit
Yes

Yes

Yes

Delayed_insert_threads

Yes

delayed_insert_timeout
Yes

Yes

Yes

Global

Yes

delayed_queue_size
Yes

Yes

Yes

Global

Yes

Global

No

Both

Yes

Both

Yes

Delayed_writes
des-key-file

Yes
Yes

Yes

disconnect-slave- Yes
event-count

Yes

div_precision_increment
Yes

Yes

enable-locking

Yes

Yes

enable-namedpipe

Yes

Yes

Yes

Yes

engine-condition- Yes
pushdown

Yes

Yes

- Variable:
named_pipe
enable-pstack

- Variable:
engine_condition_pushdown

Yes

Both

Yes

error_count

Yes

Session

No

Yes

Global

Yes

exit-info

Yes

Yes

expire_logs_days Yes

Yes

external-locking

Yes

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Yes

Yes

Global

Yes

Global

No

Yes

Global

Yes

Yes

Session

Yes

- Variable:
skip_external_locking
flush

Yes

Flush_commands
flush_time

Yes
Yes

Yes

foreign_key_checks
ft_boolean_syntax Yes

Yes

Yes

Global

Yes

ft_max_word_len Yes

Yes

Yes

Global

No

ft_min_word_len Yes

Yes

Yes

Global

No

ft_query_expansion_limit
Yes

Yes

Yes

Global

No

ft_stopword_file

Yes

Yes

Yes

Global

No

gdb

Yes

Yes
Yes

Both

Yes

group_concat_max_len
Yes

Yes

Handler_commit

Yes

Both

No

Handler_delete

Yes

Both

No

Handler_discover

Yes

Both

No

Handler_prepare

Yes

Both

No

Handler_read_first

Yes

Both

No

Handler_read_key

Yes

Both

No

Handler_read_next

Yes

Both

No

Handler_read_prev

Yes

Both

No

Handler_read_rnd

Yes

Both

No

Handler_read_rnd_next

Yes

Both

No

Handler_rollback

Yes

Both

No

Handler_savepoint

Yes

Both

No

Handler_savepoint_rollback

Yes

Both

No

Handler_update

Yes

Both

No

Handler_write

Yes

Both

No

have_archive

Yes

Global

No

have_bdb

Yes

Global

No

have_blackhole_engine

Yes

Global

No

have_community_features

Yes

Global

No

have_compress

Yes

Global

No

have_crypt

Yes

Global

No

have_csv

Yes

Global

No

have_example_engine

Yes

Global

No

have_federated_engine

Yes

Global

No

have_geometry

Yes

Global

No

have_innodb

Yes

Global

No

have_isam

Yes

Global

No

have_merge_engine

Yes

Global

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

System Var Status Var

Var Scope

Dynamic

have_ndbcluster

Yes

Global

No

have_openssl

Yes

Global

No

have_profiling

Yes

Global

No

have_query_cache

Yes

Global

No

have_raid

Yes

Global

No

have_rtree_keys

Yes

Global

No

have_ssl

Yes

Global

No

have_symlink

Yes

Global

No

hostname

Yes

Global

No

identity

Yes

Session

Yes

Yes

Global

Yes

Global

No

Yes

Global

No

Yes

Global

Yes

Yes

Yes

Global

No

innodb_additional_mem_pool_size
Yes
Yes

Yes

Global

No

innodb_autoextend_increment
Yes

Yes

Yes

Global

Yes

innodb_buffer_pool_awe_mem_mb
Yes
Yes

Yes

Global

No

help

Cmd-Line

Yes

Option File

Yes

init_connect

Yes

Yes

init-file

Yes

Yes

- Variable:
init_file
init-rpl-role

Yes

Yes

init_slave

Yes

Yes

innodb

Yes

Yes

innodb_adaptive_hash_index
Yes

Innodb_buffer_pool_pages_data

Yes

Global

No

Innodb_buffer_pool_pages_dirty

Yes

Global

No

Innodb_buffer_pool_pages_flushed

Yes

Global

No

Innodb_buffer_pool_pages_free

Yes

Global

No

Innodb_buffer_pool_pages_latched

Yes

Global

No

Innodb_buffer_pool_pages_misc

Yes

Global

No

Innodb_buffer_pool_pages_total

Yes

Global

No

Innodb_buffer_pool_read_ahead_rnd

Yes

Global

No

Innodb_buffer_pool_read_ahead_seq

Yes

Global

No

Innodb_buffer_pool_read_requests

Yes

Global

No

Innodb_buffer_pool_reads

Yes

Global

No

Global

No

innodb_buffer_pool_size
Yes

Yes

Yes

Innodb_buffer_pool_wait_free

Yes

Global

No

Innodb_buffer_pool_write_requests

Yes

Global

No

innodb_checksumsYes

Yes

Yes

Global

No

innodb_commit_concurrency
Yes

Yes

Yes

Global

Yes

innodb_concurrency_tickets
Yes

Yes

Yes

Global

Yes

innodb_data_file_path
Yes

Yes

Yes

Global

No

Global

No

Innodb_data_fsyncs

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

innodb_data_home_dir
Yes

Option File

System Var Status Var

Var Scope

Dynamic

Yes

Yes

Global

No

Innodb_data_pending_fsyncs

Yes

Global

No

Innodb_data_pending_reads

Yes

Global

No

Innodb_data_pending_writes

Yes

Global

No

Innodb_data_read

Yes

Global

No

Innodb_data_reads

Yes

Global

No

Innodb_data_writes

Yes

Global

No

Innodb_data_written

Yes

Global

No

Innodb_dblwr_pages_written

Yes

Global

No

Innodb_dblwr_writes

Yes

Global

No

innodb_doublewriteYes

Yes

Yes

Global

No

innodb_fast_shutdown
Yes

Yes

Yes

Global

Yes

innodb_file_io_threads
Yes

Yes

Yes

Global

No

innodb_file_per_table
Yes

Yes

Yes

Global

No

innodb_flush_log_at_trx_commit
Yes
Yes

Yes

Global

Yes

innodb_flush_method
Yes

Yes

Yes

Global

No

innodb_force_recovery
Yes

Yes

Yes

Global

No

innodb_lock_wait_timeout
Yes

Yes

Yes

Global

No

innodb_locks_unsafe_for_binlog
Yes
Yes

Yes

Global

No

innodb_log_arch_dir
Yes

Yes

Yes

Global

No

innodb_log_archiveYes

Yes

Yes

Global

No

innodb_log_buffer_size
Yes

Yes

Yes

Global

No

innodb_log_file_size
Yes

Yes

Yes

Global

No

innodb_log_files_in_group
Yes

Yes

Yes

Global

No

innodb_log_group_home_dir
Yes

Yes

Yes

Global

No

Innodb_log_waits

Yes

Global

No

Innodb_log_write_requests

Yes

Global

No

Innodb_log_writes

Yes

Global

No

innodb_max_dirty_pages_pct
Yes

Yes

Yes

Global

Yes

innodb_max_purge_lag
Yes

Yes

Yes

Global

Yes

innodb_mirrored_log_groups
Yes

Yes

Yes

Global

No

innodb_open_files Yes

Yes

Yes

Global

No

Innodb_os_log_fsyncs

Yes

Global

No

Innodb_os_log_pending_fsyncs

Yes

Global

No

Innodb_os_log_pending_writes

Yes

Global

No

Innodb_os_log_written

Yes

Global

No

Innodb_page_size

Yes

Global

No

Innodb_pages_created

Yes

Global

No

Innodb_pages_read

Yes

Global

No

Innodb_pages_written

Yes

Global

No

Global

No

innodb_rollback_on_timeout
Yes
This
documentation
is for an
older version.
If you're

Yes

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Innodb_row_lock_current_waits

Yes

Global

No

Innodb_row_lock_time

Yes

Global

No

Innodb_row_lock_time_avg

Yes

Global

No

Innodb_row_lock_time_max

Yes

Global

No

Innodb_row_lock_waits

Yes

Global

No

Innodb_rows_deleted

Yes

Global

No

Innodb_rows_inserted

Yes

Global

No

Innodb_rows_read

Yes

Global

No

Innodb_rows_updated

Yes

Global

No

innodb-safebinlog

Yes

Yes

innodb-status-file Yes

Yes

innodb_support_xaYes

Yes

Yes

Both

Yes

innodb_sync_spin_loops
Yes

Yes

Yes

Global

Yes

innodb_table_locksYes

Yes

Yes

Both

Yes

innodb_thread_concurrency
Yes

Yes

Yes

Global

Yes

innodb_thread_sleep_delay
Yes

Yes

Yes

Global

Yes

innodb_use_legacy_cardinality_algorithm
Yes
Yes

Yes

Global

Yes

insert_id

Yes

Session

Yes

install

Yes

install-manual

Yes

interactive_timeoutYes

Yes

Yes

Both

Yes

join_buffer_size

Yes

Yes

Yes

Both

Yes

keep_files_on_create
Yes

Yes

Yes

Both

Yes

Key_blocks_not_flushed

Yes

Global

No

Key_blocks_unused

Yes

Global

No

Key_blocks_used

Yes

Global

No

key_buffer_size

Yes

Yes

Yes

Global

Yes

key_cache_age_threshold
Yes

Yes

Yes

Global

Yes

key_cache_block_size
Yes

Yes

Yes

Global

Yes

key_cache_division_limit
Yes

Yes

Yes

Global

Yes

Key_read_requests

Yes

Global

No

Key_reads

Yes

Global

No

Key_write_requests

Yes

Global

No

Key_writes

Yes

Global

No

Yes

Global

No

large_files_support

Yes

Global

No

large_page_size

Yes

Global

No

Global

No

Global

No

language

large-pages
- Variable:
large_pages

This
documentation
is for an
older version.
If you're

Yes

Yes

Yes

Yes
Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

last_insert_id

System Var Status Var

Var Scope

Dynamic

Yes

Session

Yes

Session

No

Last_query_cost

Yes

lc_time_names

Yes

Both

Yes

license

Yes

Global

No

local_infile

Yes

Global

Yes

Yes

Global

No

local-service

Yes

locked_in_memory
log

Yes

Yes

Yes

Global

No

log-bin

Yes

Yes

Yes

Global

No

Yes

Global

No

Global

Yes

Global

Yes

Global

Yes

Global

Yes

Global

No

Global

No

Global

Yes

Global

Yes

Global

No

Yes

Global

No

Yes

Global

No

Global

No

Global

No

Both

Yes

Yes

Both

Yes

Yes

Both

Yes

log_bin
log-bin-index

Yes

Yes

log-bin-trustYes
function-creators

Yes

- Variable:
log_bin_trust_function_creators
log-bin-trustroutine-creators

Yes

Yes
Yes

- Variable:
log_bin_trust_routine_creators
log-error

Yes

Yes
Yes

- Variable:
log_error

Yes

log-isam

Yes

Yes

log-queries-notusing-indexes

Yes

Yes

- Variable:
log_queries_not_using_indexes

Yes

log-short-format

Yes

Yes

log-slaveupdates

Yes

Yes

- Variable:
log_slave_updates
log_slave_updatesYes

Yes

log-slow-adminstatements

Yes

Yes

log-slow-queries

Yes

Yes

- Variable:
log_slow_queries

Yes

log-tc

Yes

Yes

log-tc-size

Yes

Yes

log-warnings

Yes

Yes

- Variable:
log_warnings
long_query_time Yes

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

low-priorityupdates

Yes

Yes

System Var Status Var

Var Scope

Dynamic

Both

Yes

- Variable:
low_priority_updates

Yes

Both

Yes

lower_case_file_system

Yes

Global

No

Yes

Global

No

lower_case_table_names
Yes

Yes

master-connectretry

Yes

Yes

master-host

Yes

Yes

master-info-file

Yes

Yes

master-password Yes

Yes

master-port

Yes

Yes

master-retrycount

Yes

Yes

master-ssl

Yes

Yes

master-ssl-ca

Yes

Yes

master-sslcapath

Yes

Yes

master-ssl-cert

Yes

Yes

master-ssl-cipher Yes

Yes

master-ssl-key

Yes

Yes

master-user

Yes

Yes

max_allowed_packet
Yes

Yes

Yes

Both

Yes

max_binlog_cache_size
Yes

Yes

Yes

Global

Yes

max-binlogdump-events

Yes

Yes

max_binlog_size Yes

Yes

Yes

Global

Yes

max_connect_errors
Yes

Yes

Yes

Global

Yes

max_connections Yes

Yes

Yes

Global

Yes

max_delayed_threads
Yes

Yes

Yes

Both

Yes

max_error_count Yes

Yes

Yes

Both

Yes

max_heap_table_size
Yes

Yes

Yes

Both

Yes

Yes

Both

Yes

Yes

Yes

Both

Yes

max_length_for_sort_data
Yes

Yes

Yes

Both

Yes

max_prepared_stmt_count
Yes

Yes

Yes

Global

Yes

max_relay_log_size
Yes

Yes

Yes

Global

Yes

max_seeks_for_key
Yes

Yes

Yes

Both

Yes

max_sort_length Yes

Yes

Yes

Both

Yes

max_sp_recursion_depth
Yes

Yes

Yes

Both

Yes

Yes

Both

Yes

Global

No

max_insert_delayed_threads
max_join_size

Yes

max_tmp_tables
Max_used_connections

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

max_user_connections
Yes

Yes

Yes

Varies

Yes

max_write_lock_count
Yes

Yes

Yes

Global

Yes

memlock

Yes

Yes

Both

Yes

Yes

Yes

Global

Yes

myisam_max_extra_sort_file_size
Yes
Yes

Yes

Global

No

myisam_max_sort_file_size
Yes

Yes

Yes

Global

Yes

myisam_mmap_size
Yes

Yes

Yes

Global

No

myisam-recover

Yes

Yes

Global

No

Yes

- Variable:
locked_in_memory
merge

Yes

Yes

multi_range_countYes

Yes

myisam-blocksize

Yes

Yes

myisam_data_pointer_size
Yes

Yes

- Variable:
myisam_recover_options
myisam_recover_options
myisam_repair_threads
Yes

Yes

Yes

Both

Yes

myisam_sort_buffer_size
Yes

Yes

Yes

Both

Yes

myisam_stats_method
Yes

Yes

Yes

Both

Yes

named_pipe

Yes

Global

No

ndb_autoincrement_prefetch_sz
Yes
Yes

Yes

Both

Yes

ndb_cache_check_time
Yes

Yes

Global

Yes

Yes

Ndb_cluster_node_id

Yes

Both

No

Ndb_config_from_host

Yes

Both

No

Ndb_config_from_port

Yes

Both

No

ndbconnectstring

Yes

Yes

ndb_force_send

Yes

Yes

Yes

Both

Yes

ndb_index_stat_cache_entries
Yes
Yes

Yes

Both

Yes

ndb_index_stat_enable
Yes

Yes

Yes

Both

Yes

ndb_index_stat_update_freq
Yes

Yes

Yes

Both

Yes

ndb-mgmd-host

Yes

Yes

ndb-nodeid

Yes

Yes

Global

No

Yes

Global

No

Yes

Both

Yes

Yes

Both

Yes

ndb_optimized_node_selection
Yes
Yes

Yes

ndb_report_thresh_binlog_epoch_slip
Yes
Yes
ndb_report_thresh_binlog_mem_usage
Yes
Yes
ndb_use_exact_count
ndb_use_transactions
Yes

Yes

ndbcluster

Yes

Yes

- Variable:
have_ndbcluster

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

net_buffer_length Yes

Yes

Yes

Both

Yes

net_read_timeout Yes

Yes

Yes

Both

Yes

net_retry_count

Yes

Yes

Yes

Both

Yes

net_write_timeout Yes

Yes

Yes

Both

Yes

new

Yes

Yes

Yes

Both

Yes

no-defaults

Yes
Global

No

Both

Yes

Global

No

Global

No

Global

No

Not_flushed_delayed_rows

Yes

old_passwords

Yes

old-style-userlimits

Yes

Yes

one-thread

Yes

Yes

Open_files
open-files-limit

Yes
Yes

Yes

- Variable:
open_files_limit

Yes

Open_streams

Yes

Global

No

Open_tables

Yes

Both

No

Opened_tables

Yes

Both

No

optimizer_prune_level
Yes

Yes

Yes

Both

Yes

optimizer_search_depth
Yes

Yes

Yes

Both

Yes

pid-file

Yes

Global

No

Yes

Global

No

Yes

- Variable:
pid_file
plugin_dir

Yes

Yes

Yes

Global

No

port

Yes

Yes

Yes

Global

No

port-opentimeout

Yes

Yes

preload_buffer_sizeYes

Yes

Yes

Both

Yes

Global

No

Yes

Global

No

Yes

Session

Yes

Yes

Both

Yes

protocol_version

Yes

Global

No

pseudo_thread_id

Yes

Session

Yes

Prepared_stmt_count

Yes

prepared_stmt_count
print-defaults

Yes

profiling
profiling_history_size
Yes

Yes

Qcache_free_blocks

Yes

Global

No

Qcache_free_memory

Yes

Global

No

Qcache_hits

Yes

Global

No

Qcache_inserts

Yes

Global

No

Qcache_lowmem_prunes

Yes

Global

No

Qcache_not_cached

Yes

Global

No

Qcache_queries_in_cache

Yes

Global

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Qcache_total_blocks

Yes

Global

No

Queries

Yes

Both

No

query_alloc_block_size
Yes

Yes

Yes

Both

Yes

query_cache_limit Yes

Yes

Yes

Global

Yes

query_cache_min_res_unit
Yes

Yes

Yes

Global

Yes

query_cache_size Yes

Yes

Yes

Global

Yes

query_cache_type Yes

Yes

Yes

Both

Yes

query_cache_wlock_invalidate
Yes
Yes

Yes

Both

Yes

query_prealloc_size
Yes

Yes

Both

Yes

Both

No

Yes

Questions

Yes

rand_seed1

Yes

Session

Yes

rand_seed2

Yes

Session

Yes

range_alloc_block_size
Yes

Yes

Yes

Both

Yes

read_buffer_size Yes

Yes

Yes

Both

Yes

read_only

Yes

Yes

Yes

Global

Yes

read_rnd_buffer_size
Yes

Yes

Yes

Both

Yes

relay-log

Yes

Global

No

Global

No

Global

No

Yes

Global

No

Yes

Global

No

Yes

- Variable:
relay_log
relay-log-index

Yes
Yes

Yes

- Variable:
relay_log_index
relay_log_index

Yes

Yes

relay-log-info-file Yes

Yes

- Variable:
relay_log_info_file
relay_log_info_file Yes

Yes

Yes

Global

No

relay_log_purge

Yes

Yes

Yes

Global

Yes

relay_log_space_limit
Yes

Yes

Yes

Global

No

remove

Yes

replicate-do-db

Yes

Yes

replicate-do-table Yes

Yes

replicate-ignoredb

Yes

Yes

replicate-ignoretable

Yes

Yes

replicate-rewrite- Yes
db

Yes

replicate-sameserver-id

Yes

Yes

replicate-wild-do- Yes
table

Yes

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

replicate-wildignore-table

Yes

Yes

report-host

Yes

Yes

report-password

Yes

Yes

report-port

Yes

Yes

report-user

Yes

Yes

rpl_recovery_rank

System Var Status Var

Var Scope

Dynamic

Yes

Global

Yes

Global

No

Global

Yes

Global

Yes

Global

No

Global

No

Rpl_status

Yes

safe-mode

Yes

Yes

safe-showdatabase

Yes

Yes

safe-user-create

Yes

Yes

safemalloc-mem- Yes
limit

Yes

secure-auth

Yes

Yes

- Variable:
secure_auth
secure-file-priv

Yes
Yes

Yes

- Variable:
secure_file_priv

Yes

Select_full_join

Yes

Both

No

Select_full_range_join

Yes

Both

No

Select_range

Yes

Both

No

Select_range_check

Yes

Both

No

Select_scan

Yes

Both

No

Global

Yes

Yes

Global

Yes

server-id

Yes

Yes

- Variable:
server_id
set-variable

Yes

Yes

shared_memory

Yes

Yes

Yes

Global

No

shared_memory_base_name
Yes

Yes

Yes

Global

No

show-slave-auth- Yes
info

Yes

skip-bdb

Yes

Yes

skip-characterset-clienthandshake

Yes

Yes

skip-concurrentinsert

Yes

Yes

skip_external_locking
Yes

Yes

Yes

Global

No

skip-grant-tables Yes

Yes

skip-host-cache

Yes

- Variable:
concurrent_insert

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

skip-locking

Yes

Yes

skip-merge

Yes

Yes

skip-nameresolve

Yes

Yes

skip-ndbcluster

Yes

Yes

skip-networking

Yes

Yes

- Variable:
skip_networking

System Var Status Var

Var Scope

Dynamic

Global

No

Global

No

Global

No

Yes

Global

No

Yes

Global

No

Yes

Global

Yes

Global

No

Global

No

Global

Yes

Global

Yes

Yes

skip-new

Yes

Yes

skip-safemalloc

Yes

Yes

skip-showdatabase

Yes

Yes

- Variable:
skip_show_database
skip-slave-start

Yes

Yes

skip-ssl

Yes

Yes

skip-stack-trace

Yes

Yes

skip-symboliclinks

Yes

skip-symlink

Yes

Yes

skip-sync-bdblogs

Yes

Yes

skip-threadpriority

Yes

Yes

slave_compressed_protocol
Yes

Yes

slave-load-tmpdir Yes

Yes

- Variable:
slave_load_tmpdir

Yes

slave-net-timeout Yes

Yes

- Variable:
slave_net_timeout

Yes

Slave_open_temp_tables

Yes

Global

No

Slave_retried_transactions

Yes

Global

No

Slave_running

Yes

Global

No

Global

No

Yes

Global

No

Yes

Global

Yes

Both

No

Global

Yes

Both

No

slave-skip-errors Yes

Yes

- Variable:
slave_skip_errors
slave_transaction_retries
Yes

Yes

Slow_launch_threads
slow_launch_time Yes

Yes
Yes

Yes

Slow_queries

Yes

socket

Yes

Yes

Yes

Global

No

sort_buffer_size

Yes

Yes

Yes

Both

Yes

Both

No

Sort_merge_passes
This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Sort_range

Yes

Both

No

Sort_rows

Yes

Both

No

Sort_scan

Yes

Both

No

sporadic-binlogdump-fail

Yes

Yes

sql_auto_is_null

Yes

Session

Yes

sql_big_selects

Yes

Session

Yes

sql_big_tables

Yes

Session

Yes

sql_buffer_result

Yes

Session

Yes

sql_log_bin

Yes

Session

Yes

sql_log_off

Yes

Session

Yes

sql_log_update

Yes

Session

Yes

sql_low_priority_updates

Yes

Both

Yes

sql_max_join_size

Yes

Both

Yes

Both

Yes

sql-mode

Yes

Yes

- Variable:
sql_mode

Yes

Both

Yes

sql_notes

Yes

Session

Yes

sql_quote_show_create

Yes

Session

Yes

sql_safe_updates

Yes

Session

Yes

sql_select_limit

Yes

Both

Yes

sql_slave_skip_counter

Yes

Global

Yes

sql_warnings

Yes

Session

Yes

ssl

Yes

Yes

Ssl_accept_renegotiates

Yes

Global

No

Ssl_accepts

Yes

Global

No

Global

No

Global

No

Global

No

Global

No

Global

No

Global

No

Global

No

Both

No

Global

No

Global

No

ssl-ca

Yes

Yes

- Variable: ssl_ca

Yes

Ssl_callback_cache_hits
ssl-capath

Yes

Yes
Yes

- Variable:
ssl_capath
ssl-cert

Yes
Yes

Yes

- Variable:
ssl_cert

Yes

Ssl_cipher
ssl-cipher

Yes
Yes

- Variable:
ssl_cipher

Yes
Yes

Ssl_cipher_list

Yes

Both

No

Ssl_client_connects

Yes

Global

No

Ssl_connect_renegotiates

Yes

Global

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Option and Variable Reference

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Ssl_ctx_verify_depth

Yes

Global

No

Ssl_ctx_verify_mode

Yes

Global

No

Ssl_default_timeout

Yes

Both

No

Ssl_finished_accepts

Yes

Global

No

Ssl_finished_connects

Yes

Global

No

Global

No

Global

No

ssl-key

Yes

Yes

- Variable:
ssl_key

Yes

Ssl_session_cache_hits

Yes

Global

No

Ssl_session_cache_misses

Yes

Global

No

Ssl_session_cache_mode

Yes

Global

No

Ssl_session_cache_overflows

Yes

Global

No

Ssl_session_cache_size

Yes

Global

No

Ssl_session_cache_timeouts

Yes

Global

No

Ssl_sessions_reused

Yes

Both

No

Ssl_used_session_cache_entries

Yes

Global

No

Ssl_verify_depth

Yes

Both

No

Ssl_verify_mode

Yes

Both

No

Ssl_version

Yes

Both

No

Yes

Both

Yes

standalone

Yes

Yes

storage_engine
symbolic-links

Yes

Yes

sync-bdb-logs

Yes

Yes

Yes

Global

No

sync_binlog

Yes

Yes

Yes

Global

Yes

sync_frm

Yes

Yes

Yes

Global

Yes

sysdate-is-now

Yes

Yes
Yes

Global

No

Yes

Yes

Global

Yes

Yes

Yes

Global

Yes

system_time_zone
table_cache

Yes

table_lock_wait_timeout
Yes
Table_locks_immediate

Yes

Global

No

Table_locks_waited

Yes

Global

No

Both

Yes

table_type
tc-heuristicrecover

Yes
Yes

Yes

Tc_log_max_pages_used

Yes

Global

No

Tc_log_page_size

Yes

Global

No

Tc_log_page_waits

Yes

Global

No

temp-pool

Yes

Yes

thread_cache_sizeYes

Yes

Yes

Global

Yes

thread_concurrency
Yes

Yes

Yes

Global

No

thread_stack

Yes

Yes

Global

No

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server Configuration Defaults

Name

Cmd-Line

Option File

System Var Status Var

Var Scope

Dynamic

Threads_cached

Yes

Global

No

Threads_connected

Yes

Global

No

Threads_created

Yes

Global

No

Threads_running

Yes

Global

No

time_format

Yes

Both

No

time_zone

Yes

Both

Yes

Yes

Global

Yes

Yes

Session

Yes

timed_mutexes

Yes

Yes

timestamp
tmp_table_size

Yes

Yes

Yes

Both

Yes

tmpdir

Yes

Yes

Yes

Global

No

transaction_alloc_block_size
Yes

Yes

Yes

Both

Yes

transactionisolation

Yes

Yes

Both

Yes

tx_isolation

Yes

Both

Yes

unique_checks

Yes

Session

Yes

Yes

Both

Yes

Yes

- Variable:
tx_isolation
transaction_prealloc_size
Yes

updatable_views_with_limit
Yes

Yes

Yes

Uptime

Yes

Global

No

Uptime_since_flush_status

Yes

Global

No

user

Yes

Yes

verbose

Yes

Yes

version

Yes

Global

No

version_comment

Yes

Global

No

version_compile_machine

Yes

Global

No

version_compile_os

Yes

Global

No

Yes

Both

Yes

Yes

Session

No

wait_timeout

Yes

Yes

warning_count
warnings

Yes

Yes

a

This option is dynamic, but only the server should set this information. You should not set the value of this variable manually.
b
This option is dynamic, but only the server should set this information. You should not set the value of this variable manually.

5.1.2 Server Configuration Defaults
The MySQL server has many operating parameters, which you can change at server startup using
command-line options or configuration files (option files). It is also possible to change many parameters
at runtime. For general instructions on setting parameters at startup or runtime, see Section 5.1.3,
“Server Command Options”, and Section 5.1.4, “Server System Variables”.
MySQL provides a number of preconfigured option files that can be used as a basis for tuning the
MySQL server. Look for files named my-small.cnf, my-medium.cnf, my-large.cnf, and myhuge.cnf, which are sample option files for small, medium, large, and very large systems. On
Windows, the extension is .ini rather than .cnf.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

Note
On Windows, the .ini or .cnf option file extension might not be displayed.
For a binary distribution, look for the sample files in or under your installation directory. If you have a
source distribution, look in the support-files directory. To use a sample file as a base configuration
file, rename a copy of it and place the copy in the appropriate location. Regarding names and
appropriate location, see the general information provided in Section 4.2.6, “Using Option Files”. That
section also describes option file format and syntax.

5.1.3 Server Command Options
When you start the mysqld server, you can specify program options using any of the methods
described in Section 4.2.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.2.6, “Using Option Files”. That section also describes option file format and
syntax.
mysqld reads options from the [mysqld] and [server] groups. mysqld_safe reads options from
the [mysqld], [server], [mysqld_safe], and [safe_mysqld] groups. mysql.server reads
options from the [mysqld] and [mysql.server] groups.
An embedded MySQL server usually reads options from the [server], [embedded], and
[xxxxx_SERVER] groups, where xxxxx is the name of the application into which the server is
embedded.
mysqld accepts many command options. For a brief summary, execute mysqld --help. To see the
full list, use mysqld --verbose --help.
The following list shows some of the most common server options. Additional options are described in
other sections:
• Options that affect security: See Section 6.1.4, “Security-Related mysqld Options and Variables”.
• SSL-related options: See Section 6.3.6.5, “Command Options for Secure Connections”.
• Binary log control options: See Section 16.1.2.4, “Binary Log Options and Variables”.
• Replication-related options: See Section 16.1.2, “Replication and Binary Logging Options and
Variables”.
• Options specific to particular storage engines: See Section 14.1.1, “MyISAM Startup Options”,
Section 14.5.3, “BDB Startup Options”, Section 14.2.2, “InnoDB Startup Options and System
Variables”, and mysqld Command Options for MySQL Cluster.
Some options control the size of buffers or caches. For a given buffer, the server might need to allocate
internal data structures. These structures typically are allocated from the total memory allocated to
the buffer, and the amount of space required might be platform dependent. This means that when you
assign a value to an option that controls a buffer size, the amount of space actually available might
differ from the value assigned. In some cases, the amount might be less than the value assigned. It is
also possible that the server will adjust a value upward. For example, if you assign a value of 0 to an
option for which the minimal value is 1024, the server will set the value to 1024.
Values for buffer sizes, lengths, and stack sizes are given in bytes unless otherwise specified.
Some options take file name values. Unless otherwise specified, the default file location is the data
directory if the value is a relative path name. To specify the location explicitly, use an absolute path
name. Suppose that the data directory is /var/mysql/data. If a file-valued option is given as a
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

relative path name, it will be located under /var/mysql/data. If the value is an absolute path name,
its location is as given by the path name.
You can also set the values of server system variables at server startup by using variable names as
options. To assign a value to a server system variable, use 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.
When you assign a value to a variable, MySQL might automatically correct the value to stay within a
given range, or adjust the value to the closest permissible value if only certain values are permitted.
If you want to restrict the maximum value to which a variable can be set at runtime with SET, you can
define this by using the --maximum-var_name=value command-line option.
It is also possible to set variables by using --set-variable=var_name=value or -O
var_name=value syntax. This syntax is deprecated.
You can change the values of most system variables for a running server with the SET statement. See
Section 13.7.4, “SET Syntax”.
Section 5.1.4, “Server System Variables”, provides a full description for all variables, and additional
information for setting them at server startup and runtime. Section 8.12.2, “Tuning Server Parameters”,
includes information on optimizing the server by tuning system variables.
•

--help, -?
Command-Line Format

--help

Display a short help message and exit. Use both the --verbose and --help options to see the full
message.
•

--allow-suspicious-udfs
Introduced

5.0.3

Command-Line Format

--allow-suspicious-udfs

Permitted Values

Type

boolean

Default FALSE
This option controls whether user-defined functions that have only an xxx symbol for the main
function can be loaded. By default, the option is off and only UDFs that have at least one auxiliary
symbol can be loaded; this prevents attempts at loading functions from shared object files other than
those containing legitimate UDFs. This option was added in version 5.0.3. See Section 21.2.2.6,
“UDF Security Precautions”.
•

--ansi
Command-Line Format

--ansi

Use standard (ANSI) SQL syntax instead of MySQL syntax. For more precise control over the server
SQL mode, use the --sql-mode option instead. See Section 1.8, “MySQL Standards Compliance”,
and Section 5.1.7, “Server SQL Modes”.
•

--basedir=dir_name, -b dir_name
Command-Line Format

--basedir=dir_name

System Variable

Name

This
documentation
is for an
older version.
If you're

basedir

Variable Global
Scope

This
documentation
is for an
older version.
If you're

Server Command Options

DynamicNo
Variable
Permitted Values

Type

directory name

The path to the MySQL installation directory. All paths are usually resolved relative to this directory.
•

--big-tables
Command-Line Format

--big-tables

System Variable

Name

big_tables

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
Enable 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=addr
Command-Line Format

--bind-address=addr

Permitted Values

Type

string

Default 0.0.0.0
The MySQL server listens on a single network socket for TCP/IP connections. This socket is bound
to a single address, but it is possible for an address to map onto multiple network interfaces. The
default address is 0.0.0.0. To specify an address explicitly, use the --bind-address=addr
option at server startup, where addr is an IPv4 address or a host name. If addr is a host name, the
server resolves the name to an IPv4 address and binds to that address.
The server treats different types of addresses as follows:
• If the address is 0.0.0.0, the server accepts TCP/IP connections on all server host IPv4
interfaces.
• If the address is a “regular” IPv4 address (such as 127.0.0.1), the server accepts TCP/IP
connections only for that particular IPv4 address.
If you intend to bind the server to a specific address, be sure that the mysql.user grant table
contains an account with administrative privileges that you can use connect to that address.
Otherwise, you will not be able to shut down the server. For example, if you bind to 0.0.0.0,
you can connect to the server using all existing accounts. But if you bind to 127.0.0.1,
the server accepts connections only on that address. In this case, first make sure that the
'root'@'127.0.0.1' account is present in the mysql.user table so that you can still connect to
the server to shut it down.
•

--bootstrap
Command-Line Format

--bootstrap

This option is used by the mysql_install_db program to create the MySQL privilege tables
without having to start a full MySQL server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

This option is unavailable if MySQL was configured with the --disable-grant-options option.
See Section 2.17.3, “MySQL Source-Configuration Options”.
•

--character-sets-dir=dir_name

Command-Line Format

--character-sets-dir=dir_name

System Variable

Name

character_sets_dir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The directory where character sets are installed. See Section 10.5, “Character Set Configuration”.
•

--character-set-client-handshake

Command-Line Format

--character-set-client-handshake

Permitted Values

Type

boolean

Default TRUE
Do not ignore character set information sent by the client. To ignore client information and use the
default server character set, use --skip-character-set-client-handshake; this makes
MySQL behave like MySQL 4.0.
•

--character-set-filesystem=charset_name

Introduced

5.0.19

Command-Line Format

--character-set-filesystem=name

System Variable

Name

character_set_filesystem

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

Default binary
The file system character set. This option sets the character_set_filesystem system variable.
It was added in MySQL 5.0.19.
•

--character-set-server=charset_name, -C charset_name

Command-Line Format

--character-set-server

System Variable

Name

character_set_server

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

string

Default latin1

This
documentation
is for an
older version.
If you're

Server Command Options

Use charset_name as the default server character set. See Section 10.5, “Character Set
Configuration”. If you use this option to specify a nondefault character set, you should also use -collation-server to specify the collation.
•

--chroot=dir_name, -r dir_name
Command-Line Format

--chroot=dir_name

Permitted Values

Type

directory name

Put the mysqld server in a closed environment during startup by using the chroot() system call.
This is a recommended security measure. Use of this option somewhat limits LOAD DATA INFILE
and SELECT ... INTO OUTFILE.
•

--collation-server=collation_name
Command-Line Format

--collation-server

System Variable

Name

collation_server

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

Default latin1_swedish_ci
Use collation_name as the default server collation. See Section 10.5, “Character Set
Configuration”.
•

--console
Command-Line Format

--console

Platform Specific

Windows

(Windows only.) Write error log messages to stderr and stdout. mysqld does not close the
console window if this option is used.
If both --log-error and --console are specified, whichever option is given last takes
precedence.
•

--core-file
Command-Line Format

--core-file

Permitted Values

Type

boolean

Default OFF
Write a core file if mysqld dies. The name and location of the core file is system dependent. On
Linux, a core file named core.pid is written to the current working directory of the process, which
for mysqld is the data directory. pid represents the process ID of the server process. On OS
X, a core file named core.pid is written to the /cores directory. On Solaris, use the coreadm
command to specify where to write the core file and how to name it.
For some systems, to get a core file you must also specify the --core-file-size option to
mysqld_safe. See Section 4.3.2, “mysqld_safe — MySQL Server Startup Script”. On some
systems, such as Solaris, you do not get a core file if you are also using the --user option. There
might be additional restrictions or limitations. For example, it might be necessary to execute ulimit
-c unlimited before starting the server. Consult your system documentation.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

•

--datadir=dir_name, -h dir_name

Command-Line Format

--datadir=dir_name

System Variable

Name

datadir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The path to the data directory.
•

--debug[=debug_options], -# [debug_options]

Command-Line Format

--debug[=debug_options]

System Variable

Name

debug

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (Unix)

Type

string

Default d:t:i:o,/tmp/mysqld.trace
Permitted Values
(Windows)

Type

string

Default d:t:i:O,\mysqld.trace

If MySQL is configured with --with-debug, you can use this option to get a trace file of what
mysqld is doing. A typical debug_options string is d:t:o,file_name. The default is
d:t:i:o,/tmp/mysqld.trace on Unix and d:t:i:O,\mysqld.trace on Windows.
As of MySQL 5.0.25, using --with-debug to configure MySQL with debugging support enables
you to use the --debug="d,parser_debug" option when you start the server. This causes the
Bison parser that is used to process SQL statements to dump a parser trace to the server's standard
error output. Typically, this output is written to the error log.
For more information, see Section 21.3.3, “The DBUG Package”.
•

--default-character-set=charset_name

Deprecated

5.0.0

Command-Line Format

--default-character-set=name

Permitted Values

Type

string

Use charset_name as the default character set. This option is deprecated in favor of -character-set-server. See Section 10.5, “Character Set Configuration”. --defaultcharacter-set is removed in MySQL 5.5.
•

--default-collation=collation_name

Deprecated

4.1.3

Command-Line Format

--default-collation=name

Permitted Values
This
documentation
is for an
older version.
If you're

Type

string

This
documentation
is for an
older version.
If you're

Server Command Options

Use collation_name as the default collation. This option is deprecated in favor of --collationserver. See Section 10.5, “Character Set Configuration”. --default-collation is removed in
MySQL 5.5.
•

--default-storage-engine=type
Command-Line Format

--default-storage-engine=name

System Variable

Name

storage_engine

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

enumeration

Default MyISAM
Set the default storage engine (table type) for tables. See Chapter 14, Storage Engines.
•

--default-table-type=type
Deprecated

5.0.0, by default-storage-engine

Command-Line Format

--default-table-type=name

Permitted Values

Type

string

This option is a deprecated synonym for --default-storage-engine.
•

--default-time-zone=timezone
Command-Line Format

--default-time-zone=name

Permitted Values

Type

string

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 is the same as the system time zone (given by the value of
the system_time_zone system variable.
•

--defaults-extra-file=file_name
Read this option file after the global option file but (on Unix) before the user option file. As of MySQL
5.0.6, if the file does not exist or is otherwise inaccessible, an error occurs. file_name is the full
path name to the file.

•

--defaults-file=file_name
Use only the given option file. If the file does not exist or is otherwise inaccessible, an error occurs.
file_name is the full path name to the file.

•

--defaults-group-suffix=str
Read not only the usual option groups, but also groups with the usual names and a suffix of
str. For example, mysqld normally reads the [mysqld] group. If the --defaults-groupsuffix=_other option is given, mysqld also reads the [mysqld_other] group. This option was
added in MySQL 5.0.10.

•

--delay-key-write[={OFF|ON|ALL}]
Command-Line Format

--delay-key-write[=name]

System Variable

Name

This
documentation
is for an
older version.
If you're

delay_key_write

This
documentation
is for an
older version.
If you're

Server Command Options

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

enumeration

Default ON
Valid
ON
Values OFF
ALL
Specify how to use delayed key writes. Delayed key writing causes key buffers not to be flushed
between writes for MyISAM tables. OFF disables delayed key writes. ON enables delayed key writes
for those tables that were created with the DELAY_KEY_WRITE option. ALL delays key writes for
all MyISAM tables. See Section 8.12.2, “Tuning Server Parameters”, and Section 14.1.1, “MyISAM
Startup Options”.
Note
If you set this variable to ALL, you should not use MyISAM tables from within
another program (such as another MySQL server or myisamchk) when the
tables are in use. Doing so leads to index corruption.
•

--des-key-file=file_name
Command-Line Format

--des-key-file=file_name

Read the default DES keys from this file. These keys are used by the DES_ENCRYPT() and
DES_DECRYPT() functions.
• --enable-locking
This option is deprecated. Use --external-locking instead.
•

--enable-named-pipe
Command-Line Format

--enable-named-pipe

Platform Specific

Windows

Enable support for named pipes. This option can be used only with the mysqld-nt and mysqlddebug servers that support named-pipe connections.
•

--enable-pstack
Command-Line Format

--enable-pstack

Permitted Values

Type

boolean

Default FALSE
Print a symbolic stack trace on failure. This capability is available only on Intel Linux systems, and
only if MySQL was configured with the --with-pstack option.
• --engine-condition-pushdown={ON|OFF}
Introduced

5.0.3

Command-Line Format

--engine-condition-pushdown

System Variable

Name

This
documentation
is for an
older version.
If you're

engine_condition_pushdown

This
documentation
is for an
older version.
If you're

Server Command Options

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (>=
5.0.3)

Type

boolean

Default OFF

Sets the engine_condition_pushdown system variable. For more information, see
Section 8.2.1.5, “Engine Condition Pushdown Optimization”.
This variable was added in MySQL 5.0.3.
•

--exit-info[=flags], -T [flags]

Command-Line Format

--exit-info[=flags]

Permitted Values

Type

integer

This is a bit mask of different flags that you can use for debugging the mysqld server. Do not use
this option unless you know exactly what it does!
•

--external-locking

Command-Line Format

--external-locking

Permitted Values

Type

boolean

Default FALSE
Enable external locking (system locking), which is disabled by default. If you use this option on a
system on which lockd does not fully work (such as Linux), it is easy for mysqld to deadlock. This
option previously was named --enable-locking.
To disable external locking explicitly, use --skip-external-locking.
External locking affects only MyISAM table access. For more information, including conditions under
which it can and cannot be used, see Section 8.11.4, “External Locking”.
•

--flush

Command-Line Format

--flush

System Variable

Name

flush

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
Flush (synchronize) 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
synchronizing to disk. See Section B.5.3.3, “What to Do If MySQL Keeps Crashing”.
•

--gdb

This
Command-Line Format
documentation
Permitted Values
is for an
older version.
If you're

--gdb
Type

boolean

This
documentation
is for an
older version.
If you're

Server Command Options

Default FALSE
Install an interrupt handler for SIGINT (needed to stop mysqld with ^C to set breakpoints) and
disable stack tracing and core file handling. See Section 21.3, “Debugging and Porting MySQL”.
•

--init-file=file_name

Command-Line Format

--init-file=file_name

System Variable

Name

init_file

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

Read SQL statements from this file at startup. Each statement must be on a single line and should
not include comments.
This option is unavailable if MySQL was configured with the --disable-grant-options option.
See Section 2.17.3, “MySQL Source-Configuration Options”.
•

--innodb-safe-binlog

Deprecated

5.0.3

Removed

5.0.3

Command-Line Format

--innodb-safe-binlog

Permitted Values

Type

boolean

If this option is given, then after a crash recovery by InnoDB, mysqld truncates the binary log after
the last not-rolled-back transaction in the log. The option also causes InnoDB to print an error if the
binary log is smaller or shorter than it should be. See Section 5.4.3, “The Binary Log”. This option
was removed in MySQL 5.0.3, having been made obsolete by the introduction of XA transaction
support.
• --innodb-xxx
Set an option for the InnoDB storage engine. The InnoDB options are listed in Section 14.2.2,
“InnoDB Startup Options and System Variables”.
•

--install [service_name]

Command-Line Format

--install [service_name]

Platform Specific

Windows

(Windows only) Install the server as a Windows service that starts automatically during Windows
startup. The default service name is MySQL if no service_name value is given. For more
information, see Section 2.10.4.7, “Starting MySQL as a Windows Service”.
Note
If the server is started with the --defaults-file and --install options,
--install must be first.
• --install-manual [service_name]
This
documentation
is for an
Command-Line Format --install-manual [service_name]
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

Platform Specific

Windows

(Windows only) Install the server as a Windows service that must be started manually. It does not
start automatically during Windows startup. The default service name is MySQL if no service_name
value is given. For more information, see Section 2.10.4.7, “Starting MySQL as a Windows Service”.
Note
If the server is started with the --defaults-file and --install-manual
options, --install-manual must be first.
•

--language=lang_name, -L lang_name

Command-Line Format

--language=name

System Variable

Name

language

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

Default /usr/local/mysql/share/mysql/english/
The language to use for error messages. lang_name can be given as the language name or as the
full path name to the directory where the language files are installed. See Section 10.2, “Setting the
Error Message Language”.
•

--large-pages

Introduced

5.0.3

Command-Line Format

--large-pages

System Variable

Name

large_pages

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Linux

Permitted Values (Linux) Type

boolean

Default FALSE
Some hardware/operating system architectures support memory pages greater than the default
(usually 4KB). The actual implementation of this support depends on the underlying hardware and
operating system. Applications that perform a lot of memory accesses may obtain performance
improvements by using large pages due to reduced Translation Lookaside Buffer (TLB) misses.
MySQL supports only the Linux implementation of large page support (which is called HugeTLB in
Linux). See Section 8.12.5.2, “Enabling Large Page Support”.
--large-pages is disabled by default. It was added in MySQL 5.0.3.
•

--local-service

Command-Line Format
This
documentation
is for an
older version.
If you're

--local-service
This
documentation
is for an
older version.
If you're

Server Command Options

(Windows only) A --local-service option following the service name causes the server to run
using the LocalService Windows account that has limited system privileges. This account is
available only for Windows XP or newer. If both --defaults-file and --local-service are
given following the service name, they can be in any order. See Section 2.10.4.7, “Starting MySQL
as a Windows Service”.
•

--log[=file_name], -l [file_name]

Command-Line Format

--log[=file_name]

System Variable

Name

log

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

Log connections and SQL statements received from clients to this file. See Section 5.4.2, “The
General Query Log”. If you omit the file name, MySQL uses host_name.log as the file name.
•

--log-error[=file_name]

Command-Line Format

--log-error[=file_name]

System Variable

Name

log_error

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

Log errors and startup messages to this file. See Section 5.4.1, “The Error Log”. If you omit the
file name, MySQL uses host_name.err. If the file name has no extension, the server adds an
extension of .err.
•

--log-isam[=file_name]

Command-Line Format

--log-isam[=file_name]

Permitted Values

Type

file name

Log all MyISAM changes to this file (used only when debugging MyISAM).
•

--log-long-format

Deprecated

4.1.0

Command-Line Format

--log-long-format

Log extra information to the update log, binary update log, and slow query log, if they have been
activated. For example, the user name and timestamp are logged for all queries. This option is
deprecated, as it now represents the default logging behavior. (See the description for --logshort-format.) 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-long-format is removed
in MySQL 5.5.
• --log-queries-not-using-indexes
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

Command-Line Format

--log-queries-not-using-indexes

System Variable (>=
5.0.23)

Name

log_queries_not_using_indexes

Variable Global
Scope
DynamicYes
Variable

Permitted Values

Type

boolean

Default OFF
If you are using this option with the slow query log enabled, queries that are expected to retrieve all
rows are logged. See Section 5.4.4, “The Slow Query Log”. This option does not necessarily mean
that no index is used. For example, a query that uses a full index scan uses an index but would be
logged because the index would not limit the number of rows.
•

--log-short-format
Command-Line Format

--log-short-format

Permitted Values

Type

boolean

Default FALSE
Originally intended to log less information to the update log and slow query log, if they have been
activated. However, this option is not operational.
•

--log-slow-admin-statements
Command-Line Format

--log-slow-admin-statements

Permitted Values

Type

boolean

Default OFF
Include slow administrative statements in the statements written to the slow query log. Administrative
statements include ALTER TABLE, ANALYZE TABLE, CHECK TABLE, CREATE INDEX, DROP
INDEX, OPTIMIZE TABLE, and REPAIR TABLE.
•

--log-slow-queries[=file_name]
Command-Line Format

--log-slow-queries[=name]

System Variable

Name

log_slow_queries

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

boolean

Log all queries that have taken more than long_query_time seconds to execute to this file. See
Section 5.4.4, “The Slow Query Log”. See the descriptions of the --log-long-format and -log-short-format options for details.
•

--log-tc=file_name
Introduced

5.0.3

Command-Line Format

--log-tc=file_name

Permitted Values

Type

This
documentation
is for an
older version.
If you're

file name

This
documentation
is for an
older version.
If you're

Server Command Options

Default tc.log
The name of the memory-mapped transaction coordinator log file (for XA transactions that affect
multiple storage engines when the binary log is disabled). The default name is tc.log. The file is
created under the data directory if not given as a full path name. This option is unused. Added in
MySQL 5.0.3.
•

--log-tc-size=size

Introduced

5.0.3

Command-Line Format

--log-tc-size=#

Permitted Values (32-bit Type
integer
platforms)
Default 24576
Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 24576
Max
Value

18446744073709547520

The size in bytes of the memory-mapped transaction coordinator log. The default size is 24KB.
Added in MySQL 5.0.3.
•

--log-warnings[=level], -W [level]

Command-Line Format

--log-warnings[=#]

System Variable

Name

log_warnings

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1
Min
Value

0

Max
Value

18446744073709547520

Print out warnings such as Aborted connection... to the error log. This option is enabled (1)
by default. To disable it, use --log-warnings=0. Specifying the option without a level value
increments the current value by 1. Enabling this option by setting it greater than 0 is recommended,
for example, if you use replication (you get more information about what is happening, such
as messages about network failures and reconnections). If the value is greater than 1, aborted
connections are written to the error log. See Section B.5.2.11, “Communication Errors and Aborted
Connections”.
This

This
documentation
is for an
older version.
If you're

documentation
is for an
older version.
If you're

Server Command Options

If a slave server was started with --log-warnings enabled, the slave prints messages to the error
log to provide information about its status, such as the binary log and relay log coordinates where it
starts its job, when it is switching to another relay log, when it reconnects after a disconnect, and so
forth.
•

--low-priority-updates

Command-Line Format

--low-priority-updates

System Variable

Name

low_priority_updates

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default FALSE
Give table-modifying operations (INSERT, REPLACE, DELETE, UPDATE) lower priority than selects.
This can also be done using {INSERT | REPLACE | DELETE | UPDATE} LOW_PRIORITY ...
to lower the priority of only one query, or by SET LOW_PRIORITY_UPDATES=1 to change the priority
in one thread. This affects only storage engines that use only table-level locking (MyISAM, MEMORY,
MERGE). See Section 8.11.2, “Table Locking Issues”.
•

--memlock

Command-Line Format

--memlock

Permitted Values

Type

boolean

Default FALSE
Lock the mysqld process in memory. This option might help if you have a problem where the
operating system is causing mysqld to swap to disk.
--memlock works on systems that support the mlockall() system call; this includes Solaris,
most Linux distributions that use a 2.4 or newer kernel, and perhaps other Unix systems. On Linux
systems, you can tell whether or not mlockall() (and thus this option) is supported by checking to
see whether or not it is defined in the system mman.h file, like this:
shell> grep mlockall /usr/include/sys/mman.h

If mlockall() is supported, you should see in the output of the previous command something like
the following:
extern int mlockall (int __flags) __THROW;

Important
Use of this option may require you to run the server as root, which, for
reasons of security, is normally not a good idea. See Section 6.1.5, “How to
Run MySQL as a Normal User”.
On Linux and perhaps other systems, you can avoid the need to run the
server as root by changing the limits.conf file. See the notes regarding
the memlock limit in Section 8.12.5.2, “Enabling Large Page Support”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

You must not try to use this option on a system that does not support the
mlockall() system call; if you do so, mysqld will very likely crash as soon
as you try to start it.
•

--myisam-block-size=N

Command-Line Format

--myisam-block-size=#

Permitted Values

Type

integer

Default 1024
Min
Value

1024

Max
Value

16384

The block size to be used for MyISAM index pages.
•

--myisam-recover[=option[,option]...]]

Command-Line Format

--myisam-recover[=name]

Permitted Values

Type

enumeration

Default OFF
Valid
OFF
Values DEFAULT
BACKUP
FORCE
QUICK
Set the MyISAM storage engine recovery mode. The option value is any combination of the values
of DEFAULT, BACKUP, FORCE, or QUICK. If you specify multiple values, separate them by commas.
Specifying the option with no argument is the same as specifying DEFAULT, and specifying with an
explicit value of "" disables recovery (same as not giving the option). If recovery is enabled, each
time mysqld opens a MyISAM table, it checks whether the table is marked as crashed or was not
closed properly. (The last option works only if you are running with external locking disabled.) If this
is the case, mysqld runs a check on the table. If the table was corrupted, mysqld attempts to repair
it.
The following options affect how the repair works.

Option

Description

DEFAULT

Recovery without backup, forcing, or quick checking.

BACKUP

If the data file was changed during recovery, save a backup of the
tbl_name.MYD file as tbl_name-datetime.BAK.

FORCE

Run recovery even if we would lose more than one row from the .MYD file.

QUICK

Do not check the rows in the table if there are not any delete blocks.

Before the server automatically repairs a table, it writes a note about the repair to the error log. If you
want to be able to recover from most problems without user intervention, you should use the options
BACKUP,FORCE. This forces a repair of a table even if some rows would be deleted, but it keeps the
old data file as a backup so that you can later examine what happened.
See Section 14.1.1, “MyISAM Startup Options”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

•

--no-defaults
Do not read any option files. If program startup fails due to reading unknown options from an option
file, --no-defaults can be used to prevent them from being read.

•

--old-style-user-limits

Introduced

5.0.3

Command-Line Format

--old-style-user-limits

Permitted Values

Type

boolean

Default FALSE
Enable old-style user limits. (Before MySQL 5.0.3, account resource limits were counted separately
for each host from which a user connected rather than per account row in the user table.) See
Section 6.3.4, “Setting Account Resource Limits”. This option was added in MySQL 5.0.3.
•

--one-thread

Command-Line Format

--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 21.3, “Debugging and Porting MySQL”.
•

--open-files-limit=count

Command-Line Format

--open-files-limit=#

System Variable

Name

open_files_limit

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

platform dependent

Changes the number of file descriptors available to mysqld. You should try increasing the value
of this option if mysqld gives you the error Too many open files. mysqld uses the option
value to reserve descriptors with setrlimit(). Internally, the maximum value for this option is the
maximum unsigned integer value, but the actual maximum is platform dependent. If the requested
number of file descriptors cannot be allocated, mysqld writes a warning to the error log.
mysqld may attempt to allocate more than the requested number of descriptors (if they are
available), using the values of max_connections and table_cache to estimate whether more
descriptors will be needed.
On Unix, the value cannot be set less than ulimit -n.
•

--pid-file=file_name

Command-Line Format
This
documentation
System Variable
is for an
older version.
If you're

--pid-file=file_name
Name

pid_file

This
documentation
is for an
older version.
If you're

Server Command Options

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The path name of the process ID file. The server creates the file in the data directory unless an
absolute path name is given to specify a different directory. This file is used by other programs such
as mysqld_safe to determine the server's process ID.
•

--port=port_num, -P port_num
Command-Line Format

--port=#

System Variable

Name

port

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 3306
Min
Value

0

Max
Value

65535

The port number to use when listening for TCP/IP connections. On Unix and Unix-like systems, the
port number must be 1024 or higher unless the server is started by the root system user.
•

--port-open-timeout=num
Introduced

5.0.19

Command-Line Format

--port-open-timeout=#

Permitted Values

Type

integer

Default 0
On some systems, when the server is stopped, the TCP/IP port might not become available
immediately. If the server is restarted quickly afterward, its attempt to reopen the port can fail. This
option indicates how many seconds the server should wait for the TCP/IP port to become free if it
cannot be opened. The default is not to wait. This option was added in MySQL 5.0.19.
•

--print-defaults
Print the program name and all options that it gets from option files.

•

--remove [service_name]
Command-Line Format

--remove [service_name]

Platform Specific

Windows

(Windows only) Remove a MySQL Windows service. The default service name is MySQL if no
service_name value is given. For more information, see Section 2.10.4.7, “Starting MySQL as a
Windows Service”.
•

--safe-mode

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

Command-Line Format

--safe-mode

Skip some optimization stages. This option is deprecated and is removed in MySQL 5.6.
•

--safe-show-database

Deprecated

4.0.2

Command-Line Format

--safe-show-database

Permitted Values

Type

boolean

This option is deprecated and does not do anything because there is a SHOW DATABASES privilege
that can be used to control access to database names on a per-account basis. See Section 6.2.1,
“Privileges Provided by MySQL”. --safe-show-database is removed in MySQL 5.5.
•

--safe-user-create

Command-Line Format

--safe-user-create

Permitted Values

Type

boolean

Default FALSE
If this option is enabled, a user cannot create new MySQL users by using the GRANT statement
unless the user has the INSERT privilege for the mysql.user table or any column in the table. If
you want a user to have the ability to create new users that have those privileges that the user has
the right to grant, you should grant the user the following privilege:
GRANT INSERT(user) ON mysql.user TO 'user_name'@'host_name';

This ensures that the user cannot change any privilege columns directly, but has to use the GRANT
statement to give privileges to other users.
•

--secure-auth

Command-Line Format

--secure-auth

System Variable

Name

secure_auth

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
This option causes the server to block connections by clients that attempt to use accounts that have
passwords stored in the old (pre-4.1) format. Use it to prevent all use of passwords employing the old
format (and hence insecure communication over the network).
Server startup fails with an error if this option is enabled and the privilege tables are in pre-4.1
format. See Section B.5.2.4, “Client does not support authentication protocol”.
The mysql client also has a --secure-auth option, which prevents connections to a server if the
server requires a password in old format for the client account.
•

--secure-file-priv=dir_name

This
documentation
Introduced
is for an
older version.
If you're

5.0.38

This
documentation
is for an
older version.
If you're

Server Command Options

Command-Line Format

--secure-file-priv=dir_name

System Variable

Name

secure_file_priv

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

Default empty
Valid
empty
Values dirname
This option limits the effect of the LOAD DATA and SELECT ... INTO OUTFILE statements and
the LOAD_FILE() function to work only with files in the specified directory.
This option was added in MySQL 5.0.38.
•

--shared-memory

Command-Line Format

--shared_memory[={0,1}]

System Variable

Name

shared_memory

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Windows

Permitted Values

Type

boolean

Default FALSE
Enable shared-memory connections by local clients. This option is available only on Windows.
•

--shared-memory-base-name=name

Command-Line Format

--shared_memory_base_name=name

System Variable

Name

shared_memory_base_name

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Windows

Permitted Values

Type

string

Default MYSQL
The name of shared memory to use for shared-memory connections. This option is available only on
Windows. The default name is MYSQL. The name is case sensitive.
•

--skip-bdb
Disable the BDB storage engine. This saves memory and might speed up some operations. Do not
use this option if you require BDB tables.

• --skip-concurrent-insert
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

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.) See Section 8.11.3, “Concurrent Inserts”.
•

--skip-grant-tables
This option causes the server to start without using the privilege system at all, which gives anyone
with access to the server unrestricted access to all databases. You can cause a running server to
start using the grant tables again by executing mysqladmin flush-privileges or mysqladmin
reload command from a system shell, or by issuing a MySQL FLUSH PRIVILEGES statement after
connecting to the server. This option also suppresses loading of user-defined functions (UDFs).
FLUSH PRIVILEGES might be executed implicitly by other actions performed after startup. For
example, mysql_upgrade flushes the privileges during the upgrade procedure.
This option is unavailable if MySQL was configured with the --disable-grant-options option.
See Section 2.17.3, “MySQL Source-Configuration Options”.

•

--skip-host-cache
Disable use of the internal host cache for faster name-to-IP resolution. In this case, the server
performs a DNS lookup every time a client connects. See Section 8.12.6.2, “DNS Lookup
Optimization and the Host Cache”.

•

--skip-innodb
Disable the InnoDB storage engine. In this case, the server will not start if the default storage engine
is set to InnoDB. Use --default-storage-engine to set the default to some other engine if
necessary.

•

--skip-merge
Disable the MERGE storage engine. This option was added in MySQL 5.0.24. It can be used if the
following behavior is undesirable: If a user has access to MyISAM table t, that user can create a
MERGE table m that accesses t. However, if the user's privileges on t are subsequently revoked, the
user can continue to access t by doing so through m.

•

--skip-name-resolve
Do not resolve host names when checking client connections. Use only IP addresses. If you use
this option, all Host column values in the grant tables must be IP addresses or localhost. See
Section 8.12.6.2, “DNS Lookup Optimization and the Host Cache”.
Depending on the network configuration of your system and the Host values for your accounts,
clients may need to connect using an explicit --host option, such as --host=localhost or -host=127.0.0.1.

•

--skip-networking
Do not listen for TCP/IP connections at all. All interaction with mysqld must be made using
named pipes or shared memory (on Windows) or Unix socket files (on Unix). This option is highly
recommended for systems where only local clients are permitted. See Section 8.12.6.2, “DNS
Lookup Optimization and the Host Cache”.

•

--ssl*
Options that begin with --ssl specify whether to permit clients to connect using SSL and indicate
where to find SSL keys and certificates. See Section 6.3.6.5, “Command Options for Secure
Connections”.

•

--standalone

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

Command-Line Format

--standalone

Platform Specific

Windows

Instructs the MySQL server not to run as a service.
•

--symbolic-links, --skip-symbolic-links

Command-Line Format

--symbolic-links

Enable or disable symbolic link support. This option has different effects on Windows and Unix:
• On Windows, enabling symbolic links enables you to establish a symbolic link to a database
directory by creating a db_name.sym file that contains the path to the real directory. See
Section 8.12.4.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 the INDEX DIRECTORY or DATA DIRECTORY options of the CREATE
TABLE statement. If you delete or rename the table, the files that its symbolic links point to also are
deleted or renamed. See Section 8.12.4.2, “Using Symbolic Links for MyISAM Tables on Unix”.
•

--skip-safemalloc

Command-Line Format

--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 do not need it by using the --skip-safemalloc option.
•

--skip-show-database

Command-Line Format

--skip-show-database

System Variable

Name

skip_show_database

Variable Global
Scope
DynamicNo
Variable
This option sets the skip_show_database system variable that controls who is permitted to use
the SHOW DATABASES statement. See Section 5.1.4, “Server System Variables”.
•

--skip-stack-trace

Command-Line Format

--skip-stack-trace

Do not write stack traces. This option is useful when you are running mysqld under a debugger. On
some systems, you also must use this option to get a core file. See Section 21.3, “Debugging and
Porting MySQL”.
•

--skip-thread-priority

Command-Line Format

--skip-thread-priority

Disable using thread priorities for faster response time.
This
This
mysqld makes a large number of invalid calls to thread scheduling routines on Linux. These
calls do
documentation
documentation
not affect performance noticeably but may be a source of “noise” for debugging tools. For example,
is for an
is for an
older version.
older version.
If you're
If you're

Server Command Options

they can overwhelm other information of more interest in kernel logs. To avoid these calls, start the
server with the --skip-thread-priority option.
•

--socket=path
Command-Line Format

--socket={file_name|pipe_name}

System Variable

Name

socket

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

Default /tmp/mysql.sock
On Unix, this option specifies the Unix socket file to use when listening for local connections. The
default value is /tmp/mysql.sock. If this option is given, the server creates the file in the data
directory unless an absolute path name is given to specify a different directory. On Windows, the
option specifies the pipe name to use when listening for local connections that use a named pipe.
The default value is MySQL (not case sensitive).
•

--sql-mode=value[,value[,value...]]
Command-Line Format

--sql-mode=name

System Variable

Name

sql_mode

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

set

Default ''
Valid
ALLOW_INVALID_DATES
Values ANSI_QUOTES
ERROR_FOR_DIVISION_BY_ZERO
HIGH_NOT_PRECEDENCE
IGNORE_SPACE
NO_AUTO_CREATE_USER
NO_AUTO_VALUE_ON_ZERO
NO_BACKSLASH_ESCAPES
NO_DIR_IN_CREATE
NO_ENGINE_SUBSTITUTION
NO_FIELD_OPTIONS
NO_KEY_OPTIONS
NO_TABLE_OPTIONS
NO_UNSIGNED_SUBTRACTION
NO_ZERO_DATE
NO_ZERO_IN_DATE
ONLY_FULL_GROUP_BY
PAD_CHAR_TO_FULL_LENGTH

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Command Options

PIPES_AS_CONCAT
REAL_AS_FLOAT
STRICT_ALL_TABLES
STRICT_TRANS_TABLES
Set the SQL mode. See Section 5.1.7, “Server SQL Modes”.
Note
MySQL installation programs may configure the SQL mode during the
installation process. If the SQL mode differs from the default or from what you
expect, check for a setting in an option file that the server reads at startup.
•

--sysdate-is-now
Introduced

5.0.20

Command-Line Format

--sysdate-is-now

Permitted Values

Type

boolean

Default FALSE
As of MySQL 5.0.12, SYSDATE() by default returns the time at which it executes, not the time at
which the statement in which it occurs begins executing. This differs from the behavior of NOW().
This option causes SYSDATE() to be an alias for NOW(). For information about the implications for
binary logging and replication, see the description for SYSDATE() in Section 12.7, “Date and Time
Functions” and for SET TIMESTAMP in Section 5.1.4, “Server System Variables”.
This option was added in MySQL 5.0.20.
•

--tc-heuristic-recover={COMMIT|ROLLBACK}
Introduced

5.0.3

Command-Line Format

--tc-heuristic-recover=name

Permitted Values

Type

enumeration

Default COMMIT
Valid
COMMIT
Values ROLLBACK
The type of decision to use in the heuristic recovery process. This option is unused. Added in MySQL
5.0.3.
•

--temp-pool
Command-Line Format

--temp-pool

Permitted Values

Type

boolean

Default TRUE
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 is being allocated to the directory entry cache rather than to the disk cache.
•

--transaction-isolation=level
Command-Line Format

This
documentation
is for an
older version.
If you're

--transaction-isolation=name
This
documentation
is for an
older version.
If you're

Server Command Options

Permitted Values

Type

enumeration

Default REPEATABLE-READ
Valid
READ-UNCOMMITTED
Values READ-COMMITTED
REPEATABLE-READ
SERIALIZABLE
Sets the default transaction isolation level. The level value can be READ-UNCOMMITTED, READCOMMITTED, REPEATABLE-READ, or SERIALIZABLE. See Section 13.3.6, “SET TRANSACTION
Syntax”.
The default transaction isolation level can also be set at runtime using the SET TRANSACTION
statement or by setting the tx_isolation system variable.
•

--tmpdir=dir_name, -t dir_name

Command-Line Format

--tmpdir=dir_name

System Variable

Name

tmpdir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

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. 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 file
system or to a directory that is cleared when the server host restarts. For more information about the
storage location of temporary files, see Section B.5.3.5, “Where MySQL Stores Temporary Files”. A
replication slave needs some of its temporary files to survive a machine restart so that it can replicate
temporary tables or LOAD DATA INFILE operations. If files in the temporary file directory are lost
when the server restarts, replication fails.
•

--user={user_name|user_id}, -u {user_name|user_id}

Command-Line Format

--user=name

Permitted Values

Type

string

Run the mysqld server as the user having the name user_name or the numeric user ID user_id.
(“User” in this context refers to a system login account, not a MySQL user listed in the grant tables.)
This option is mandatory when starting mysqld as root. The server changes its user ID during its
startup sequence, causing it to run as that particular user rather than as root. See Section 6.1.1,
“Security Guidelines”.
To avoid a possible security hole where a user adds a --user=root option to a my.cnf file
(thus causing the server to run as root), mysqld uses only the first --user option specified
and produces a warning if there are multiple --user options. Options in /etc/my.cnf and
$MYSQL_HOME/my.cnf are processed before command-line options, so it is recommended that you
put a --user option in /etc/my.cnf and specify a value other than root. The option in /etc/
my.cnf is found before any other --user options, which ensures that the server runs as a user
other than root, and that a warning results if any other --user option is found.
This

This
documentation
is for an
older version.
If you're

documentation
is for an
older version.
If you're

Server System Variables

•

--verbose, -v
Use this option with the --help option for detailed help.

•

--version, -V
System Variable

Name

version

Variable Global
Scope
DynamicNo
Variable
Display version information and exit.
An attempt to connect to the host 127.0.0.1 normally resolves to the localhost account.
However, this fails if the server is run with the --skip-name-resolve option, so make sure that an
account exists that can accept a connection. For example, to be able to connect as root using -host=127.0.0.1 or --host=::1, create these accounts:
CREATE USER 'root'@'127.0.0.1' IDENTIFIED BY 'root-password';
CREATE USER 'root'@'::1' IDENTIFIED BY 'root-password';

5.1.4 Server System Variables
The MySQL server maintains many system variables that indicate how it is configured. Each system
variable has a default value. System variables can be set at server startup using options on the
command line or in an option file. Most of them can be changed dynamically while the server is running
by means of the SET statement, which enables you to modify operation of the server without having to
stop and restart it. You can refer to system variable values in expressions.
There are several ways to see the names and values of system variables:
• To see the values that a server will use based on its compiled-in defaults and any option files that it
reads, use this command:
mysqld --verbose --help

• To see the values that a server will use based on its compiled-in defaults, ignoring the settings in any
option files, use this command:
mysqld --no-defaults --verbose --help

• To see the current values used by a running server, use the SHOW VARIABLES statement.
This section provides a description of each system variable. Variables with no version indicated are
present in all MySQL 5.0 releases.
The following table lists all available system variables.
Table 5.2 System Variable Summary
Name

System Var

Var Scope

Dynamic

auto_increment_increment

Yes

Both

Yes

auto_increment_offset

Yes

Both

Yes

autocommit

Yes

Session

Yes

automatic_sp_privileges

Yes

Global

Yes

back_log

Yes

Global

No

This
documentation
is for an
older version.
If you're

Cmd-Line

Option File

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

System Var

Var Scope

Dynamic

basedir

Yes

Yes

Yes

Global

No

Yes

Global

No

bdb_cache_size
bdb-home

Yes

Yes

- Variable:
bdb_home
bdb-lock-detect

Yes

Yes

bdb_log_buffer_size
bdb-logdir

Yes

No
Yes

Global

No

Yes

Global

No

Yes

Global

No

Yes

No

- Variable:
bdb_logdir

Yes

Global

No

bdb_max_lock

Yes

Global

No

bdb-shared-data

Yes

Yes

- Variable:
bdb_shared_data

No
Yes

bdb-tmpdir

Yes

Yes

- Variable:
bdb_tmpdir
Yes

binlog_cache_size

Global

Yes

- Variable:
big_tables

No
No

Yes

big-tables

Global

No
Yes

Yes

Session

Yes

Yes

Yes

Yes

Global

Yes

bulk_insert_buffer_size
Yes

Yes

Yes

Both

Yes

Yes

Both

Yes

Yes

Both

Yes

Yes

Both

Yes

character_set_client
character_set_connection
a

character_set_database
character-setfilesystem

Yes

Yes

Yes

- Variable:
character_set_filesystem

Yes

Both

Yes

character_set_results

Yes

Both

Yes

character-set-server Yes

Yes

Yes

- Variable:
character_set_server

Yes

Both

Yes

character_set_system

Yes

Global

No

character-sets-dir

Yes

Yes

- Variable:
character_sets_dir
collation_connection
b

collation_database
collation-server

Yes

No
Yes

Global

No

Yes

Both

Yes

Yes

Both

Yes

Yes

- Variable:
collation_server

Yes
Yes

Both

Yes

completion_type

Yes

Yes

Yes

Both

Yes

concurrent_insert

Yes

Yes

Yes

Global

Yes

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

System Var

Var Scope

Dynamic

connect_timeout

Yes

Yes

Yes

Global

Yes

datadir

Yes

Yes

Yes

Global

No

date_format

Yes

Both

No

datetime_format

Yes

Both

No

debug

Yes

Yes

Yes

Both

Yes

default-storageengine

Yes

Yes

Yes

Both

Yes

default_week_format Yes

Yes

Yes

Both

Yes

delay-key-write

Yes

Yes

- Variable:
delay_key_write

Yes
Yes

Global

Yes

delayed_insert_limit Yes

Yes

Yes

Global

Yes

delayed_insert_timeout
Yes

Yes

Yes

Global

Yes

delayed_queue_size Yes

Yes

Yes

Global

Yes

div_precision_increment
Yes

Yes

Yes

Both

Yes

engine-conditionpushdown

Yes

Yes

Yes

- Variable:
engine_condition_pushdown

Yes

Both

Yes

error_count

Yes

Session

No

expire_logs_days

Yes

Yes

Yes

Global

Yes

flush

Yes

Yes

Yes

Global

Yes

flush_time

Yes

Yes

Yes

Global

Yes

Yes

Session

Yes

foreign_key_checks
ft_boolean_syntax

Yes

Yes

Yes

Global

Yes

ft_max_word_len

Yes

Yes

Yes

Global

No

ft_min_word_len

Yes

Yes

Yes

Global

No

ft_query_expansion_limit
Yes

Yes

Yes

Global

No

ft_stopword_file

Yes

Yes

Yes

Global

No

group_concat_max_len
Yes

Yes

Yes

Both

Yes

have_archive

Yes

Global

No

have_bdb

Yes

Global

No

have_blackhole_engine

Yes

Global

No

have_community_features

Yes

Global

No

have_compress

Yes

Global

No

have_crypt

Yes

Global

No

have_csv

Yes

Global

No

have_example_engine

Yes

Global

No

have_federated_engine

Yes

Global

No

have_geometry

Yes

Global

No

have_innodb

Yes

Global

No

have_isam

Yes

Global

No

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

System Var

Var Scope

Dynamic

have_merge_engine

Yes

Global

No

have_ndbcluster

Yes

Global

No

have_openssl

Yes

Global

No

have_profiling

Yes

Global

No

have_query_cache

Yes

Global

No

have_raid

Yes

Global

No

have_rtree_keys

Yes

Global

No

have_ssl

Yes

Global

No

have_symlink

Yes

Global

No

hostname

Yes

Global

No

identity

Yes

Session

Yes

Yes

Global

Yes

init_connect

Yes

Yes

init-file

Yes

Yes

- Variable: init_file

No
Yes

Global

No

Yes

Yes

Global

Yes

innodb_adaptive_hash_index
Yes

Yes

Yes

Global

No

innodb_additional_mem_pool_size
Yes

Yes

Yes

Global

No

innodb_autoextend_increment
Yes

Yes

Yes

Global

Yes

innodb_buffer_pool_awe_mem_mb
Yes

Yes

Yes

Global

No

innodb_buffer_pool_size
Yes

Yes

Yes

Global

No

innodb_checksums

Yes

Yes

Global

No

innodb_commit_concurrency
Yes

Yes

Yes

Global

Yes

innodb_concurrency_tickets
Yes

Yes

Yes

Global

Yes

innodb_data_file_pathYes

Yes

Yes

Global

No

innodb_data_home_dir
Yes

Yes

Yes

Global

No

innodb_doublewrite Yes

Yes

Yes

Global

No

innodb_fast_shutdownYes

Yes

Yes

Global

Yes

innodb_file_io_threadsYes

Yes

Yes

Global

No

innodb_file_per_tableYes

Yes

Yes

Global

No

innodb_flush_log_at_trx_commit
Yes

Yes

Yes

Global

Yes

innodb_flush_methodYes

Yes

Yes

Global

No

innodb_force_recovery
Yes

Yes

Yes

Global

No

innodb_lock_wait_timeout
Yes

Yes

Yes

Global

No

innodb_locks_unsafe_for_binlog
Yes

Yes

Yes

Global

No

innodb_log_arch_dir Yes

Yes

Yes

Global

No

innodb_log_archive Yes

Yes

Yes

Global

No

innodb_log_buffer_size
Yes

Yes

Yes

Global

No

innodb_log_file_size Yes

Yes

Yes

Global

No

innodb_log_files_in_group
Yes

Yes

Yes

Global

No

innodb_log_group_home_dir
Yes

Yes

Yes

Global

No

innodb_max_dirty_pages_pct
Yes

Yes

Yes

Global

Yes

init_slave

This
documentation
is for an
older version.
If you're

Yes

Yes

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

System Var

Var Scope

Dynamic

innodb_max_purge_lag
Yes

Yes

Yes

Global

Yes

innodb_mirrored_log_groups
Yes

Yes

Yes

Global

No

innodb_open_files

Yes

Yes

Global

No

innodb_rollback_on_timeout
Yes

Yes

Yes

Global

No

innodb_support_xa

Yes

Yes

Yes

Both

Yes

innodb_sync_spin_loops
Yes

Yes

Yes

Global

Yes

innodb_table_locks

Yes

Yes

Both

Yes

innodb_thread_concurrency
Yes

Yes

Yes

Global

Yes

innodb_thread_sleep_delay
Yes

Yes

Yes

Global

Yes

innodb_use_legacy_cardinality_algorithm
Yes
Yes

Yes

Global

Yes

insert_id

Yes

Session

Yes

Yes

Yes

interactive_timeout

Yes

Yes

Yes

Both

Yes

join_buffer_size

Yes

Yes

Yes

Both

Yes

keep_files_on_create Yes

Yes

Yes

Both

Yes

key_buffer_size

Yes

Yes

Global

Yes

key_cache_age_threshold
Yes

Yes

Yes

Global

Yes

key_cache_block_sizeYes

Yes

Yes

Global

Yes

key_cache_division_limit
Yes

Yes

Yes

Global

Yes

language

Yes

Yes

Global

No

large_files_support

Yes

Global

No

large_page_size

Yes

Global

No

large-pages

Yes

Yes

Yes

Yes

No

- Variable:
large_pages

Yes

Global

No

last_insert_id

Yes

Session

Yes

lc_time_names

Yes

Both

Yes

license

Yes

Global

No

local_infile

Yes

Global

Yes

locked_in_memory

Yes

Global

No

log

Yes

Yes

Yes

Global

No

log-bin

Yes

Yes

Yes

Global

No

Yes

Global

No

log_bin
log-bin-trustfunction-creators

Yes

Yes

- Variable:
log_bin_trust_function_creators
log-bin-trust-routine- Yes
creators

Yes

- Variable: log_error

This
documentation
is for an
older version.
If you're

Yes

Global

Yes

- Variable:
log_bin_trust_routine_creators
log-error

Yes
Yes
Yes
Yes

Global

Yes

Yes
No

Yes

Global

No

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

log-queries-notusing-indexes

Yes

Yes

- Variable:
log_queries_not_using_indexes
log-slave-updates

Yes

Yes

Yes

log-slow-queries

Yes

Yes

- Variable:
log_slow_queries

Yes

low-priority-updates Yes

Yes

Yes

Yes

Global

No

Yes

Global

No
No

Global

Yes

Yes

Dynamic

No

Yes

- Variable:
log_warnings
long_query_time

Global

Yes

log_slave_updates

Yes

Var Scope

Yes
Yes

- Variable:
log_slave_updates

log-warnings

System Var

No
Yes

Yes

Both

Yes

Yes

Both

Yes
Yes

- Variable:
low_priority_updates

Yes

Both

Yes

lower_case_file_system

Yes

Global

No

lower_case_table_names
Yes

Yes

Yes

Global

No

max_allowed_packet Yes

Yes

Yes

Both

Yes

max_binlog_cache_size
Yes

Yes

Yes

Global

Yes

max_binlog_size

Yes

Yes

Yes

Global

Yes

max_connect_errors Yes

Yes

Yes

Global

Yes

max_connections

Yes

Yes

Yes

Global

Yes

max_delayed_threadsYes

Yes

Yes

Both

Yes

max_error_count

Yes

Yes

Yes

Both

Yes

max_heap_table_sizeYes

Yes

Yes

Both

Yes

Yes

Both

Yes

max_insert_delayed_threads
max_join_size

Yes

Yes

Yes

Both

Yes

max_length_for_sort_data
Yes

Yes

Yes

Both

Yes

max_prepared_stmt_count
Yes

Yes

Yes

Global

Yes

max_relay_log_size Yes

Yes

Yes

Global

Yes

max_seeks_for_key Yes

Yes

Yes

Both

Yes

max_sort_length

Yes

Yes

Yes

Both

Yes

max_sp_recursion_depth
Yes

Yes

Yes

Both

Yes

Yes

Both

Yes

max_tmp_tables
max_user_connections
Yes

Yes

Yes

Varies

Yes

max_write_lock_countYes

Yes

Yes

Global

Yes

multi_range_count

Yes

Yes

Both

Yes

myisam_data_pointer_size
Yes

Yes

Yes

Global

Yes

myisam_max_extra_sort_file_size
Yes

Yes

Yes

Global

No

myisam_max_sort_file_size
Yes

Yes

Yes

Global

Yes

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

myisam_mmap_size Yes

Option File

System Var

Var Scope

Dynamic

Yes

Yes

Global

No

Yes

Global

No

myisam_recover_options
myisam_repair_threads
Yes

Yes

Yes

Both

Yes

myisam_sort_buffer_size
Yes

Yes

Yes

Both

Yes

myisam_stats_methodYes

Yes

Yes

Both

Yes

Yes

Global

No

named_pipe
ndb_autoincrement_prefetch_sz
Yes

Yes

Yes

Both

Yes

ndb_cache_check_time
Yes

Yes

Yes

Global

Yes

ndb_force_send

Yes

Yes

Both

Yes

ndb_index_stat_cache_entries
Yes

Yes

Yes

Both

Yes

ndb_index_stat_enable
Yes

Yes

Yes

Both

Yes

ndb_index_stat_update_freq
Yes

Yes

Yes

Both

Yes

ndb_optimized_node_selection
Yes

Yes

Yes

Global

No

Yes

Both

Yes

Yes

ndb_use_exact_count
ndb_use_transactionsYes

Yes

Yes

Both

Yes

net_buffer_length

Yes

Yes

Yes

Both

Yes

net_read_timeout

Yes

Yes

Yes

Both

Yes

net_retry_count

Yes

Yes

Yes

Both

Yes

net_write_timeout

Yes

Yes

Yes

Both

Yes

new

Yes

Yes

Yes

Both

Yes

Yes

Both

Yes

old_passwords
open-files-limit

Yes

Yes

- Variable:
open_files_limit

No
Yes

Global

No

optimizer_prune_levelYes

Yes

Yes

Both

Yes

optimizer_search_depth
Yes

Yes

Yes

Both

Yes

pid-file

Yes

Yes

- Variable: pid_file

No
Yes

Global

No

plugin_dir

Yes

Yes

Yes

Global

No

port

Yes

Yes

Yes

Global

No

preload_buffer_size Yes

Yes

Yes

Both

Yes

prepared_stmt_count

Yes

Global

No

profiling

Yes

Session

Yes

Yes

Both

Yes

protocol_version

Yes

Global

No

pseudo_thread_id

Yes

Session

Yes

profiling_history_size Yes

Yes

query_alloc_block_size
Yes

Yes

Yes

Both

Yes

query_cache_limit

Yes

Yes

Global

Yes

query_cache_min_res_unit
Yes

Yes

Yes

Global

Yes

query_cache_size

Yes

Yes

Yes

Global

Yes

query_cache_type

Yes

Yes

Yes

Both

Yes

This
documentation
is for an
older version.
If you're

Yes

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

System Var

Var Scope

Dynamic

query_cache_wlock_invalidate
Yes

Yes

Yes

Both

Yes

query_prealloc_size Yes

Yes

Yes

Both

Yes

rand_seed1

Yes

Session

Yes

rand_seed2

Yes

Session

Yes

range_alloc_block_size
Yes

Yes

Yes

Both

Yes

read_buffer_size

Yes

Yes

Yes

Both

Yes

read_only

Yes

Yes

Yes

Global

Yes

read_rnd_buffer_size Yes

Yes

Yes

Both

Yes

relay-log

Yes

Yes

- Variable: relay_log
relay-log-index

No
Yes

Yes

Global

Yes

- Variable:
relay_log_index

No
No

Yes

Global

No

relay_log_index

Yes

Yes

Yes

Global

No

relay_log_info_file

Yes

Yes

Yes

Global

No

relay_log_purge

Yes

Yes

Yes

Global

Yes

relay_log_space_limitYes

Yes

Yes

Global

No

Yes

Global

Yes

rpl_recovery_rank
secure-auth

Yes

Yes

- Variable:
secure_auth
secure-file-priv

Yes
Yes

Global

Yes

- Variable: server_id

Yes
No

Yes
Yes

Global

Yes

- Variable:
secure_file_priv
server-id

Yes

No
Yes

Yes

Global

Yes

Yes

Yes

Global

No

shared_memory_base_name
Yes

Yes

Yes

Global

No

skip_external_lockingYes

Yes

Yes

Global

No

skip-networking

Yes

shared_memory

Yes

Yes

- Variable:
skip_networking

No
Yes

skip-show-database Yes

Global

Yes

- Variable:
skip_show_database

No
No

Yes

Global

No

Yes

Yes

Global

No

slave_compressed_protocol
Yes

Yes

Yes

Global

Yes

slave-load-tmpdir

Yes

skip-sync-bdb-logs

Yes
Yes

- Variable:
slave_load_tmpdir
slave-net-timeout
- Variable:
slave_net_timeout
This
documentation
is for an
older version.
If you're

No
Yes

Yes

Global

Yes

No
Yes

Yes

Global

Yes

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

Option File

slave-skip-errors

Yes

Yes

- Variable:
slave_skip_errors

System Var

Var Scope

Dynamic
No

Yes

Global

No

slave_transaction_retries
Yes

Yes

Yes

Global

Yes

slow_launch_time

Yes

Yes

Yes

Global

Yes

socket

Yes

Yes

Yes

Global

No

sort_buffer_size

Yes

Yes

Yes

Both

Yes

sql_auto_is_null

Yes

Session

Yes

sql_big_selects

Yes

Session

Yes

sql_big_tables

Yes

Session

Yes

sql_buffer_result

Yes

Session

Yes

sql_log_bin

Yes

Session

Yes

sql_log_off

Yes

Session

Yes

sql_log_update

Yes

Session

Yes

sql_low_priority_updates

Yes

Both

Yes

sql_max_join_size

Yes

Both

Yes

sql-mode

Yes

Yes

Yes

- Variable: sql_mode

Yes

Both

Yes

sql_notes

Yes

Session

Yes

sql_quote_show_create

Yes

Session

Yes

sql_safe_updates

Yes

Session

Yes

sql_select_limit

Yes

Both

Yes

sql_slave_skip_counter

Yes

Global

Yes

sql_warnings

Yes

Session

Yes

ssl-ca

Yes

Yes

- Variable: ssl_ca
ssl-capath

Yes
Yes

ssl-cipher

ssl-key

No
No

Yes
Yes

Global

Yes

- Variable:
ssl_cipher

No
No

Yes
Yes

Global

Yes

- Variable: ssl_cert

No
No

Yes
Yes

Global

Yes

- Variable:
ssl_capath
ssl-cert

No

Global

Yes

No
No

- Variable: ssl_key

Yes

Global

No

storage_engine

Yes

Both

Yes

sync-bdb-logs

Yes

Yes

Yes

Global

No

sync_binlog

Yes

Yes

Yes

Global

Yes

sync_frm

Yes

Yes

Yes

Global

Yes

Yes

Global

No

Yes

Global

Yes

system_time_zone
table_cache
This
documentation
is for an
older version.
If you're

Yes

Yes

This
documentation
is for an
older version.
If you're

Server System Variables

Name

Cmd-Line

table_lock_wait_timeout
Yes

Option File

System Var

Var Scope

Dynamic

Yes

Yes

Global

Yes

Yes

Both

Yes

table_type
thread_cache_size

Yes

Yes

Yes

Global

Yes

thread_concurrency Yes

Yes

Yes

Global

No

thread_stack

Yes

Yes

Global

No

time_format

Yes

Both

No

time_zone

Yes

Both

Yes

Yes

Global

Yes

Yes

Session

Yes

Yes

timed_mutexes

Yes

Yes

timestamp
tmp_table_size

Yes

Yes

Yes

Both

Yes

tmpdir

Yes

Yes

Yes

Global

No

transaction_alloc_block_size
Yes

Yes

Yes

Both

Yes

transaction_prealloc_size
Yes

Yes

Yes

Both

Yes

tx_isolation

Yes

Both

Yes

unique_checks

Yes

Session

Yes

Yes

Both

Yes

version

Yes

Global

No

version_comment

Yes

Global

No

version_compile_machine

Yes

Global

No

version_compile_os

Yes

Global

No

Yes

Both

Yes

Yes

Session

No

updatable_views_with_limit
Yes

wait_timeout

Yes

warning_count

Yes

Yes

a

This option is dynamic, but only the server should set this information. You should not set the value of this variable manually.
This option is dynamic, but only the server should set this information. You should not set the value of this variable manually.

b

For additional system variable information, see these sections:
• Section 5.1.5, “Using System Variables”, discusses the syntax for setting and displaying system
variable values.
• Section 5.1.5.2, “Dynamic System Variables”, lists the variables that can be set at runtime.
• Information on tuning system variables can be found in Section 8.12.2, “Tuning Server Parameters”.
• Section 14.2.2, “InnoDB Startup Options and System Variables”, lists InnoDB system variables.
• MySQL Cluster System Variables, lists system variables which are specific to MySQL Cluster.
• For information on server system variables specific to replication, see Section 16.1.2, “Replication
and Binary Logging Options and Variables”.
Note
Some of the following variable descriptions refer to “enabling” or “disabling” a
variable. These variables can be enabled with the SET statement by setting
them to ON or 1, or disabled by setting them to OFF or 0. However, to set such
a variable on the command line or in an option file, you must set it to 1 or 0;
setting it to ON or OFF will not work. For example, on the command line, -delay_key_write=1 works but --delay_key_write=ON does not.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Some system variables control the size of buffers or caches. For a given buffer, the server might need
to allocate internal data structures. These structures typically are allocated from the total memory
allocated to the buffer, and the amount of space required might be platform dependent. This means
that when you assign a value to a system variable that controls a buffer size, the amount of space
actually available might differ from the value assigned. In some cases, the amount might be less than
the value assigned. It is also possible that the server will adjust a value upward. For example, if you
assign a value of 0 to a variable for which the minimal value is 1024, the server will set the value to
1024.
Values for buffer sizes, lengths, and stack sizes are given in bytes unless otherwise specified.
Some system variables take file name values. Unless otherwise specified, the default file location is
the data directory if the value is a relative path name. To specify the location explicitly, use an absolute
path name. Suppose that the data directory is /var/mysql/data. If a file-valued variable is given
as a relative path name, it will be located under /var/mysql/data. If the value is an absolute path
name, its location is as given by the path name.
•

autocommit

System Variable

Name

autocommit

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default ON
The autocommit mode. If set to 1, all changes to a table take effect immediately. If set to 0, you
must use COMMIT to accept a transaction or ROLLBACK to cancel it. If autocommit is 0 and you
change it to 1, MySQL performs an automatic COMMIT of any open transaction. Another way to begin
a transaction is to use a START TRANSACTION or BEGIN statement. See Section 13.3.1, “START
TRANSACTION, COMMIT, and ROLLBACK Syntax”.
By default, client connections begin with autocommit set to 1. To cause clients to begin with a
default of 0, set the server's init_connect system variable:
SET GLOBAL init_connect='SET autocommit=0';

The init_connect 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'

The content of init_connect is not executed for users that have the SUPER privilege.
•

automatic_sp_privileges

Introduced

5.0.3

System Variable

Name

automatic_sp_privileges

Variable Global
Scope
DynamicYes
Variable
This
Permitted Values
documentation
is for an
older version.
If you're

Type

boolean

This
documentation
is for an
older version.
If you're

Server System Variables

Default TRUE
When this variable has a value of 1 (the default), the server automatically grants the EXECUTE and
ALTER ROUTINE privileges to the creator of a stored routine, if the user cannot already execute
and alter or drop the routine. (The ALTER ROUTINE privilege is required to drop the routine.) The
server also automatically drops those privileges from the creator when the routine is dropped. If
automatic_sp_privileges is 0, the server does not automatically add or drop these privileges.
The creator of a routine is the account used to execute the CREATE statement for it. This might not
be the same as the account named as the DEFINER in the routine definition.
See also Section 18.2.2, “Stored Routines and MySQL Privileges”.
This variable was added in MySQL 5.0.3.
•

back_log

System Variable

Name

back_log

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 50
Min
Value

1

Max
Value

65535

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 Unix
listen() system call should have more details. Check your OS documentation for the maximum
value for this variable. back_log cannot be set higher than your operating system limit.
•

basedir

Command-Line Format

--basedir=dir_name

System Variable

Name

basedir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The MySQL installation base directory. This variable can be set with the --basedir option. Relative
path names for other variables usually are resolved relative to the base directory.
This
• bdb_cache_size
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

System Variable

Name

bdb_cache_size

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Min
Value

20480

The size of the buffer that is allocated for caching indexes and rows for BDB tables. If you do not use
BDB tables, you should start mysqld with --skip-bdb to not allocate memory for this cache.
•

bdb_home

Command-Line Format

--bdb-home=dir_name

System Variable

Name

bdb_home

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The base directory for BDB tables. This should be assigned the same value as the datadir variable.
•

bdb_log_buffer_size

System Variable

Name

bdb_log_buffer_size

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Min
Value

262144

Max
Value

4294967295

The size of the buffer that is allocated for caching indexes and rows for BDB tables. If you do not use
BDB tables, you should set this to 0 or start mysqld with --skip-bdb to not allocate memory for
this cache.
•

bdb_logdir

Command-Line Format

--bdb-logdir=file_name

System Variable

Name

bdb_logdir

Variable Global
Scope
DynamicNo
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

directory name
This
documentation
is for an
older version.
If you're

Server System Variables

The directory where the BDB storage engine writes its log files. This variable can be set with the -bdb-logdir option.
•

bdb_max_lock

System Variable

Name

bdb_max_lock

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 10000
The maximum number of locks that can be active for a BDB table (10,000 by default). You should
increase this value if errors such as the following occur when you perform long transactions or when
mysqld has to examine many rows to calculate a query:
bdb: Lock table is out of available locks
Got error 12 from ...

For more information, see Section 21.3.3, “The DBUG Package”.
•

bdb_shared_data

Command-Line Format

--bdb-shared-data

System Variable

Name

bdb_shared_data

Variable Global
Scope
DynamicNo
Variable
This is ON if you are using --bdb-shared-data to start Berkeley DB in multi-process mode. (Do
not use DB_PRIVATE when initializing Berkeley DB.)
•

bdb_tmpdir

Command-Line Format

--bdb-tmpdir=dir_name

System Variable

Name

bdb_tmpdir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The BDB temporary file directory.
•

big_tables

If set to 1, all temporary tables are stored on disk rather than in memory. This is a little slower, but
the error The table tbl_name is full does not occur for SELECT operations that require a
large temporary table. The default value for a new connection is 0 (use in-memory temporary tables).
Normally, you should never need to set this variable, because in-memory tables are automatically
converted to disk-based tables as required.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

Note
This variable was formerly named sql_big_tables.
•

binlog_cache_size

Command-Line Format

--binlog_cache_size=#

System Variable

Name

binlog_cache_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 32768
Min
Value

4096

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 32768
Min
Value

4096

Max
Value

18446744073709547520

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 if
the server has the binary log enabled (--log-bin option). If you often use large, multiple-statement
transactions, you can increase this cache size to get better performance. The Binlog_cache_use
and Binlog_cache_disk_use status variables can be useful for tuning the size of this variable.
See Section 5.4.3, “The Binary Log”.
•

bulk_insert_buffer_size

Command-Line Format

--bulk_insert_buffer_size=#

System Variable

Name

bulk_insert_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 8388608
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 8388608
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

0

Max
Value

18446744073709547520

MyISAM uses a special tree-like cache to make bulk inserts faster for INSERT ... SELECT,
INSERT ... VALUES (...), (...), ..., and LOAD DATA INFILE when adding data to
nonempty tables. This variable limits the size of the cache tree in bytes per thread. Setting it to 0
disables this optimization. The default value is 8MB.
•

character_set_client
System Variable

Name

character_set_client

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

The character set for statements that arrive from the client. The session value of this variable is
set using the character set requested by the client when the client connects to the server. (Many
clients support a --default-character-set option to enable this character set to be specified
explicitly. See also Section 10.1.4, “Connection Character Sets and Collations”.) The global value of
the variable is used to set the session value in cases when the client-requested value is unknown or
not available, or the server is configured to ignore client requests:
• The client is from a version of MySQL older than MySQL 4.1, and thus does not request a
character set.
• The client requests a character set not known to the server. For example, a Japanese-enabled
client requests sjis when connecting to a server not configured with sjis support.
• mysqld was started with the --skip-character-set-client-handshake option, which
causes it to ignore client character set configuration. This reproduces MySQL 4.0 behavior and is
useful should you wish to upgrade the server without upgrading all the clients.
ucs2 cannot be used as a client character set, which means that it also does not work for SET
NAMES or SET CHARACTER SET.
•

character_set_connection
System Variable

Name

character_set_connection

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

The character set used for literals that do not have a character set introducer and for number-tostring conversion.
•

character_set_database
System Variable

Name

character_set_database

Variable Global, Session
Scope

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Footnote

This option is dynamic, but only the server should set this information.
You should not set the value of this variable manually.

Permitted Values

Type

string

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.
•

character_set_filesystem

Introduced

5.0.19

Command-Line Format

--character-set-filesystem=name

System Variable

Name

character_set_filesystem

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

Default binary
The file system character set. This variable is used to interpret string literals that refer to file
names, such as in the LOAD DATA INFILE and SELECT ... INTO OUTFILE statements
and the LOAD_FILE() function. Such file names are converted from character_set_client
to character_set_filesystem before the file opening attempt occurs. The default value is
binary, which means that no conversion occurs. For systems on which multibyte file names are
permitted, a different value may be more appropriate. For example, if the system represents file
names using UTF-8, set character_set_filesystem to 'utf8'. This variable was added in
MySQL 5.0.19.
•

character_set_results

System Variable

Name

character_set_results

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

The character set used for returning query results such as result sets or error messages to the client.
•

character_set_server

Command-Line Format

--character-set-server

System Variable

Name

character_set_server

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

string

Default latin1

This
documentation
is for an
older version.
If you're

Server System Variables

The server's default character set.
•

character_set_system
System Variable

Name

character_set_system

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

Default utf8
The character set used by the server for storing identifiers. The value is always utf8.
•

character_sets_dir
Command-Line Format

--character-sets-dir=dir_name

System Variable

Name

character_sets_dir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The directory where character sets are installed.
•

collation_connection
System Variable

Name

collation_connection

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

The collation of the connection character set.
•

collation_database
System Variable

Name

collation_database

Variable Global, Session
Scope
DynamicYes
Variable
Footnote

This option is dynamic, but only the server should set this information.
You should not set the value of this variable manually.

Permitted Values

Type

string

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.
•

collation_server

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--collation-server

System Variable

Name

collation_server

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

Default latin1_swedish_ci
The server's default collation.
•

completion_type

Introduced

5.0.3

Command-Line Format

--completion_type=#

System Variable

Name

completion_type

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (>=
5.0.3)

Type

integer

Default 0
Valid
0
Values 1
2

The transaction completion type. This variable can take the values shown in the following table.

Value

Description

0

COMMIT and ROLLBACK are unaffected. This is the default value.

1

COMMIT and ROLLBACK are equivalent to COMMIT AND CHAIN and ROLLBACK AND
CHAIN, respectively. (A new transaction starts immediately with the same isolation level
as the just-terminated transaction.)

2

COMMIT and ROLLBACK are equivalent to COMMIT RELEASE and ROLLBACK
RELEASE, respectively. (The server disconnects after terminating the transaction.)

completion_type affects transactions that begin with START TRANSACTION or BEGIN and end
with COMMIT or ROLLBACK. It does not apply to implicit commits resulting from execution of the
statements listed in Section 13.3.3, “Statements That Cause an Implicit Commit”. It also does not
apply for XA COMMIT, XA ROLLBACK, or when autocommit=1.
This variable was added in MySQL 5.0.3.
•

concurrent_insert

Command-Line Format

--concurrent_insert[=#]

System Variable

Name

concurrent_insert

Variable Global
Scope
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Permitted Values (<=
5.0.5)

Type

Permitted Values (>=
5.0.6)

Type

boolean

Default TRUE
integer

Default 1
Valid
0
Values 1
2

If 1 (the default), MySQL permits INSERT and SELECT statements to run concurrently for MyISAM
tables that have no free blocks in the middle of the data file. If you start mysqld with --skip-new,
this variable is set to 0.
In MySQL 5.0.6, this variable was changed to take three integer values:

Value

Description

0

Disables concurrent inserts

1

(Default) Enables concurrent insert for MyISAM tables that do not have holes

2

Enables concurrent inserts for all MyISAM tables, even those that have holes. For a
table with a hole, new rows are inserted at the end of the table if it is in use by another
thread. Otherwise, MySQL acquires a normal write lock and inserts the row into the
hole.

See also Section 8.11.3, “Concurrent Inserts”.
•

connect_timeout

Command-Line Format

--connect_timeout=#

System Variable

Name

connect_timeout

Variable Global
Scope
DynamicYes
Variable
Permitted Values (<=
5.0.51)

Permitted Values (>=
5.0.52)

Type

integer

Default 5
Min
Value

2

Max
Value

31536000

Type

integer

Default 10
Min
Value

2

Max
Value

31536000

The number of seconds that the mysqld server waits for a connect packet before responding with
Bad handshake. The default value is 10 seconds as of MySQL 5.0.52 and 5 seconds before that.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

Increasing the connect_timeout value might help if clients frequently encounter errors of the form
Lost connection to MySQL server at 'XXX', system error: errno.
•

datadir

Command-Line Format

--datadir=dir_name

System Variable

Name

datadir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The MySQL data directory. This variable can be set with the --datadir option.
•

date_format
This variable is unused.

•

datetime_format
This variable is unused.

•

default_week_format

Command-Line Format

--default_week_format=#

System Variable

Name

default_week_format

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

7

The default mode value to use for the WEEK() function. See Section 12.7, “Date and Time
Functions”.
•

delay_key_write

Command-Line Format

--delay-key-write[=name]

System Variable

Name

delay_key_write

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

enumeration

Default ON
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Valid
ON
Values OFF
ALL
This option applies only to MyISAM tables. It can have one of the following values to affect handling
of the DELAY_KEY_WRITE table option that can be used in CREATE TABLE statements.

Option

Description

OFF

DELAY_KEY_WRITE is ignored.

ON

MySQL honors any DELAY_KEY_WRITE option specified in CREATE TABLE
statements. This is the default value.

ALL

All new opened tables are treated as if they were created with the DELAY_KEY_WRITE
option enabled.

If DELAY_KEY_WRITE is enabled for a table, the key buffer is not flushed for the table on every index
update, but only when the table is closed. This speeds up writes on keys a lot, but if you use this
feature, you should add automatic checking of all MyISAM tables by starting the server with the -myisam-recover option (for example, --myisam-recover=BACKUP,FORCE). See Section 5.1.3,
“Server Command Options”, and Section 14.1.1, “MyISAM Startup Options”.
Warning
If you enable external locking with --external-locking, there is no
protection against index corruption for tables that use delayed key writes.
•

delayed_insert_limit

Command-Line Format

--delayed_insert_limit=#

System Variable

Name

delayed_insert_limit

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 100
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 100
Min
Value

1

Max
Value

18446744073709547520

After inserting delayed_insert_limit delayed rows, the INSERT DELAYED handler thread
checks whether there are any SELECT statements pending. If so, it permits them to execute before
continuing to insert delayed rows.
• delayed_insert_timeout
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--delayed_insert_timeout=#

System Variable

Name

delayed_insert_timeout

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 300
How many seconds an INSERT DELAYED handler thread should wait for INSERT statements before
terminating.
•

delayed_queue_size

Command-Line Format

--delayed_queue_size=#

System Variable

Name

delayed_queue_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1000
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1000
Min
Value

1

Max
Value

18446744073709547520

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 an INSERT DELAYED statement waits
until there is room in the queue again.
•

div_precision_increment

Introduced

5.0.6

Command-Line Format

--div_precision_increment=#

System Variable

Name

div_precision_increment

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 4
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

0

Max
Value

30

This variable indicates the number of digits by which to increase the scale of the result of division
operations performed with the / operator. The default value is 4. The minimum and maximum values
are 0 and 30, respectively. The following example illustrates the effect of increasing the default value.
mysql> SELECT 1/7;
+--------+
| 1/7
|
+--------+
| 0.1429 |
+--------+
mysql> SET div_precision_increment = 12;
mysql> SELECT 1/7;
+----------------+
| 1/7
|
+----------------+
| 0.142857142857 |
+----------------+

This variable was added in MySQL 5.0.6.
•

engine_condition_pushdown

Introduced

5.0.3

Command-Line Format

--engine-condition-pushdown

System Variable

Name

engine_condition_pushdown

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (>=
5.0.3)

Type

boolean

Default OFF

The engine condition pushdown optimization enables processing for certain comparisons to be
“pushed down” to the storage engine level for more efficient execution. For more information, see
Section 8.2.1.5, “Engine Condition Pushdown Optimization”.
Engine condition pushdown is used only by the NDBCLUSTER storage engine. Enabling this
optimization on a MySQL Server acting as a MySQL Cluster SQL node causes WHERE conditions
on unindexed columns to be evaluated on the cluster's data nodes and only the rows that match to
be sent back to the SQL node that issued the query. This greatly reduces the amount of cluster data
that must be sent over the network, increasing the efficiency with which results are returned.
The engine_condition_pushdown variable controls whether engine condition pushdown is
enabled. By default, this variable is OFF (0). Setting it to ON (1) enables pushdown.
This variable was added in MySQL 5.0.3.
•

error_count
The number of errors that resulted from the last statement that generated messages. This variable is
read only. See Section 13.7.5.14, “SHOW ERRORS Syntax”.

• expire_logs_days
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--expire_logs_days=#

System Variable

Name

expire_logs_days

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

99

The number of days for automatic binary log file removal. The default is 0, which means “no
automatic removal.” Possible removals happen at startup and when the binary log is flushed. Log
flushing occurs as indicated in Section 5.4, “MySQL Server Logs”.
To remove binary log files manually, use the PURGE BINARY LOGS statement. See
Section 13.4.1.1, “PURGE BINARY LOGS Syntax”.
•

flush
Command-Line Format

--flush

System Variable

Name

flush

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
If ON, the server flushes (synchronizes) 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 synchronizing to disk. See Section B.5.3.3, “What to Do If MySQL Keeps
Crashing”. This variable is set to ON if you start mysqld with the --flush option.
•

flush_time
Command-Line Format

--flush_time=#

System Variable

Name

flush_time

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0

Permitted Values
(Windows)

This
documentation
is for an
older version.
If you're

Min
Value

0

Type

integer

Default 1800

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

0

If this is set to a nonzero value, all tables are closed every flush_time seconds to free up
resources and synchronize unflushed data to disk. This option is best used only on systems with
minimal resources.
•

foreign_key_checks
If set to 1 (the default), foreign key constraints for InnoDB tables are checked. If set to 0, foreign key
constraints are ignored, with a couple of exceptions. When re-creating a table that was dropped, an
error is returned if the table definition does not conform to the foreign key constraints referencing the
table. Likewise, an ALTER TABLE operation returns an error if a foreign key definition is incorrectly
formed. For more information, see Section 13.1.10.3, “Using FOREIGN KEY Constraints”.
Disabling foreign key checking can be useful for reloading InnoDB tables in an order different from
that required by their parent/child relationships. See Section 14.2.3.4, “InnoDB and FOREIGN KEY
Constraints”.
Setting foreign_key_checks to 0 also affects data definition statements: DROP DATABASE drops
a database even if it contains tables that have foreign keys that are referred to by tables outside the
database, and DROP TABLE drops tables that have foreign keys that are referred to by other tables.
Note
Setting foreign_key_checks to 1 does not trigger a scan of the existing
table data. Therefore, rows added to the table while foreign_key_checks
= 0 will not be verified for consistency.

•

ft_boolean_syntax

Command-Line Format

--ft_boolean_syntax=name

System Variable

Name

ft_boolean_syntax

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

string

Default + -><()~*:""&|
The list of operators supported by boolean full-text searches performed using IN BOOLEAN MODE.
See Section 12.9.2, “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 nonalphanumeric character.
• Either the first or second character must be a space.
• No duplicates are permitted 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.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

•

ft_max_word_len

Command-Line Format

--ft_max_word_len=#

System Variable

Name

ft_max_word_len

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Min
Value

10

The maximum length of the word to be included in a FULLTEXT index.
Note
FULLTEXT indexes must be rebuilt after changing this variable. Use REPAIR
TABLE tbl_name QUICK.
•

ft_min_word_len

Command-Line Format

--ft_min_word_len=#

System Variable

Name

ft_min_word_len

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 4
Min
Value

1

The minimum length of the word to be included in a FULLTEXT index.
Note
FULLTEXT indexes must be rebuilt after changing this variable. Use REPAIR
TABLE tbl_name QUICK.
•

ft_query_expansion_limit

Command-Line Format

--ft_query_expansion_limit=#

System Variable

Name

ft_query_expansion_limit

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 20
This
documentation
is for an
older version.
If you're

Min
Value

0
This
documentation
is for an
older version.
If you're

Server System Variables

Max
Value

1000

The number of top matches to use for full-text searches performed using WITH QUERY EXPANSION.
•

ft_stopword_file

Command-Line Format

--ft_stopword_file=file_name

System Variable

Name

ft_stopword_file

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The file from which to read the list of stopwords for full-text searches. The server looks for the file in
the data directory unless an absolute path name is given to specify a different directory. 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. See also Section 12.9.4, “Full-Text Stopwords”.
Note
FULLTEXT indexes must be rebuilt after changing this variable or the contents
of the stopword file. Use REPAIR TABLE tbl_name QUICK.
•

group_concat_max_len

Command-Line Format

--group_concat_max_len=#

System Variable

Name

group_concat_max_len

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1024
Min
Value

4

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1024
Min
Value

4

Max
Value

18446744073709547520

The maximum permitted result length in bytes for the GROUP_CONCAT() function. The default is
1024.
•

have_archive

This
YES if mysqld supports ARCHIVE tables, NO if not.
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

•

have_bdb
YES if mysqld supports BDB tables. DISABLED if --skip-bdb is used.

•

have_blackhole_engine
YES if mysqld supports BLACKHOLE tables, NO if not.

•

have_community_features
YES if statement profiling capability is present, NO if not. If present, the profiling system variable
controls whether this capability is enabled or disabled. See Section 13.7.5.29, “SHOW PROFILES
Syntax”.
This variable was added in MySQL 5.0.82.

•

have_compress
YES if the zlib compression library is available to the server, NO if not. If not, the COMPRESS() and
UNCOMPRESS() functions cannot be used.

•

have_crypt
YES if the crypt() system call is available to the server, NO if not. If not, the ENCRYPT() function
cannot be used.

•

have_csv
YES if mysqld supports CSV tables, NO if not.

•

have_example_engine
YES if mysqld supports EXAMPLE tables, NO if not.

•

have_federated_engine
YES if mysqld supports FEDERATED tables, NO if not. This variable was added in MySQL 5.0.3.

•

have_geometry
YES if the server supports spatial data types, NO if not.

•

have_innodb
YES if mysqld supports InnoDB tables. DISABLED if --skip-innodb is used.

•

have_isam
This variable appears only for reasons of backward compatibility. It is always NO because ISAM
tables are no longer supported.

•

have_merge_engine
YES if mysqld supports MERGE tables. DISABLED if --skip-merge is used. This variable was
added in MySQL 5.0.24.

•

have_openssl
YES if mysqld supports SSL connections, NO if not. As of MySQL 5.0.38, this variable is an alias for
have_ssl.

• have_profiling
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

YES if statement profiling capability is present, NO if not. If present, the profiling system variable
controls whether this capability is enabled or disabled. See Section 13.7.5.29, “SHOW PROFILES
Syntax”.
This variable was added in MySQL 5.0.82.
•

have_query_cache
YES if mysqld supports the query cache, NO if not.

•

have_raid
This variable appears only for reasons of backward compatibility. It is always NO because RAID
tables are no longer supported.

•

have_rtree_keys
YES if RTREE indexes are available, NO if not. (These are used for spatial indexes in MyISAM tables.)

•

have_ssl
YES if mysqld supports SSL connections, NO if not. DISABLED indicates that the server was
compiled with SSL support, but but was not started with the appropriate --ssl-xxx options. For
more information, see Section 6.3.6.2, “Building MySQL with Support for Secure Connections”.
This variable was added in MySQL 5.0.38. Before that, use have_openssl.

•

have_symlink
YES if symbolic link support is enabled, NO if not. This is required on Unix for support of the DATA
DIRECTORY and INDEX DIRECTORY table options, and on Windows for support of data directory
symlinks. If the server is started with the --skip-symbolic-links option, the value is DISABLED.

•

hostname
Introduced

5.0.38

System Variable

Name

hostname

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

The server sets this variable to the server host name at startup. This variable was added in MySQL
5.0.38.
•

identity
This variable is a synonym for the last_insert_id variable. It exists for compatibility with
other database systems. You can read its value with SELECT @@identity, and set it using SET
identity.

•

init_connect
Command-Line Format

--init-connect=name

System Variable

Name

init_connect

Variable Global
Scope

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Permitted Values

Type

string

A string to be executed by the server for each client that connects. The string consists of one or more
SQL statements, separated by semicolon characters. For example, each client session begins by
default with autocommit mode enabled. There is no global autocommit system 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';

The init_connect 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'

The content of init_connect is not executed for users that have the SUPER privilege. This is
done so that an erroneous value for init_connect does not prevent all clients from connecting.
For example, the value might contain a statement that has a syntax error, thus causing client
connections to fail. Not executing init_connect for users that have the SUPER privilege enables
them to open a connection and fix the init_connect value.
The server discards any result sets produced by statements in the value of of init_connect.
•

init_file
Command-Line Format

--init-file=file_name

System Variable

Name

init_file

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The name of the file specified with the --init-file option when you start the server. This should
be 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. For more information, see the
description of --init-file.
Note that the --init-file option is unavailable if MySQL was configured with the --disablegrant-options option. See Section 2.17.3, “MySQL Source-Configuration Options”.
• innodb_xxx
InnoDB system variables are listed in Section 14.2.2, “InnoDB Startup Options and System
Variables”.
•

insert_id
The value to be used by the following INSERT or ALTER TABLE statement when inserting an
AUTO_INCREMENT value. This is mainly used with the binary log.

•

interactive_timeout
Command-Line Format

This
documentation
is for an
older version.
If you're

--interactive_timeout=#

This
documentation
is for an
older version.
If you're

Server System Variables

System Variable

Name

interactive_timeout

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 28800
Min
Value

1

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 to
mysql_real_connect(). See also wait_timeout.
•

join_buffer_size

Command-Line Format

--join_buffer_size=#

System Variable

Name

join_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 131072
Min
Value

8200

Max
Value

4294967295

The minimum size of the buffer that is used for plain index scans, range index scans, and joins that
do not use indexes and thus perform full table scans. 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.
There is no gain from setting the buffer larger than required to hold each matching row, and all joins
allocate at least the minimum size, so use caution in setting this variable to a large value globally.
It is better to keep the global setting small and change to a larger setting only in sessions that are
doing large joins. Memory allocation time can cause substantial performance drops if the global size
is larger than needed by most queries that use it.
The maximum permissible setting for join_buffer_size is 4GB−1.
For additional information about join buffering, see Section 8.2.1.8, “Nested-Loop Join Algorithms”.
•

keep_files_on_create

Introduced

5.0.48

Command-Line Format

--keep_files_on_create=#

System Variable

Name

This
documentation
is for an
older version.
If you're

keep_files_on_create

Variable Global, Session
Scope

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
If a MyISAM table is created with no DATA DIRECTORY option, the .MYD file is created in the
database directory. By default, if MyISAM finds an existing .MYD file in this case, it overwrites it.
The same applies to .MYI files for tables created with no INDEX DIRECTORY option. To suppress
this behavior, set the keep_files_on_create variable to ON (1), in which case MyISAM will not
overwrite existing files and returns an error instead. The default value is OFF (0).
If a MyISAM table is created with a DATA DIRECTORY or INDEX DIRECTORY option and an existing
.MYD or .MYI file is found, MyISAM always returns an error. It will not overwrite a file in the specified
directory.
This variable was added in MySQL 5.0.48.
•

key_buffer_size

Command-Line Format

--key_buffer_size=#

System Variable

Name

key_buffer_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 8388608
Min
Value

8

Max
Value

4294967295

Index blocks for MyISAM 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 permissible setting for key_buffer_size is 4GB−1 on 32-bit platforms. As of
MySQL 5.0.52, larger values are permitted for 64-bit platforms (except 64-bit Windows, for which
large values are truncated to 4GB−1 with a warning). 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. The value of this variable indicates the amount of memory requested.
Internally, the server allocates as much memory as possible up to this amount, but the actual
allocation might be less.
You can increase the value to get better index handling for all reads and multiple writes; on a system
whose primary function is to run MySQL using the MyISAM storage engine, 25% of the machine's
total memory is an acceptable value for this variable. However, you should be aware that, if you
make the value too large (for example, more than 50% of the machine's total memory), your system
might start to page and become extremely slow. This is because MySQL relies on the operating
system to perform file system caching for data reads, so you must leave some room for the file
system cache. You should also consider the memory requirements of any other storage engines that
you may be using in addition to MyISAM.
For even more speed when writing many rows at the same time, use LOCK TABLES. See
Section 8.2.2.1, “Speed of INSERT Statements”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

You can check the performance of the key buffer by issuing a SHOW STATUS statement and
examining the Key_read_requests, Key_reads, Key_write_requests, and Key_writes
status variables. (See Section 13.7.5, “SHOW Syntax”.) The Key_reads/Key_read_requests
ratio should normally be less than 0.01. The Key_writes/Key_write_requests ratio is usually
near 1 if you are using mostly updates and deletes, but might be much smaller if you tend to do
updates that affect many rows at the same time or if you are using the DELAY_KEY_WRITE table
option.
The fraction of the key buffer in use can be determined using key_buffer_size in conjunction
with the Key_blocks_unused status variable and the buffer block size, which is available from the
key_cache_block_size system variable:
1 - ((Key_blocks_unused * key_cache_block_size) / key_buffer_size)

This value is an approximation because some space in the key buffer is allocated internally for
administrative structures. Factors that influence the amount of overhead for these structures
include block size and pointer size. As block size increases, the percentage of the key buffer lost to
overhead tends to decrease. Larger blocks results in a smaller number of read operations (because
more keys are obtained per read), but conversely an increase in reads of keys that are not examined
(if not all keys in a block are relevant to a query).
It is possible to create multiple MyISAM key caches. The size limit of 4GB applies to each cache
individually, not as a group. See Section 8.10.1, “The MyISAM Key Cache”.
•

key_cache_age_threshold
Command-Line Format

--key_cache_age_threshold=#

System Variable

Name

key_cache_age_threshold

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 300
Min
Value

100

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 300
Min
Value

100

Max
Value

18446744073709547520

This value controls the demotion of buffers from the hot sublist of a key cache to the warm sublist.
Lower values cause demotion to happen more quickly. The minimum value is 100. The default value
is 300. See Section 8.10.1, “The MyISAM Key Cache”.
•

key_cache_block_size
Command-Line Format

--key_cache_block_size=#

System Variable

Name

This
documentation
is for an
older version.
If you're

key_cache_block_size

This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 1024
Min
Value

512

Max
Value

16384

The size in bytes of blocks in the key cache. The default value is 1024. See Section 8.10.1, “The
MyISAM Key Cache”.
•

key_cache_division_limit

Command-Line Format

--key_cache_division_limit=#

System Variable

Name

key_cache_division_limit

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 100
Min
Value

1

Max
Value

100

The division point between the hot and warm sublists of the key cache buffer list. The value is the
percentage of the buffer list to use for the warm sublist. Permissible values range from 1 to 100. The
default value is 100. See Section 8.10.1, “The MyISAM Key Cache”.
•

language

Command-Line Format

--language=name

System Variable

Name

language

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

Default /usr/local/mysql/share/mysql/english/
The directory where error messages are located. See Section 10.2, “Setting the Error Message
Language”.
•

large_files_support

System Variable
This
documentation
is for an
older version.
If you're

Name

large_files_support
This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global
Scope
DynamicNo
Variable
Whether mysqld was compiled with options for large file support.
•

large_pages

Introduced

5.0.3

Command-Line Format

--large-pages

System Variable

Name

large_pages

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Linux

Permitted Values (Linux) Type

boolean

Default FALSE
Whether large page support is enabled (via the --large-pages option). See Section 8.12.5.2,
“Enabling Large Page Support”. This variable was added in MySQL 5.0.3.
For more information, see the entry for the --large-pages server option.
•

large_page_size

Introduced

5.0.3

System Variable

Name

large_page_size

Variable Global
Scope
DynamicNo
Variable
Permitted Values (Linux) Type

integer

Default 0
If large page support is enabled, this shows the size of memory pages. Large memory pages are
supported only on Linux; on other platforms, the value of this variable is always 0. This variable was
added in MySQL 5.0.3.
For more information, see the entry for the --large-pages server option.
•

last_insert_id
The value to be returned from LAST_INSERT_ID(). This is stored in the binary log when you use
LAST_INSERT_ID() in a statement that updates a table. Setting this variable does not update the
value returned by the mysql_insert_id() C API function.

•

lc_time_names

Introduced
System Variable
This
documentation
is for an
older version.
If you're

5.0.25
Name

lc_time_names

This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

This variable specifies the locale that controls the language used to display day and month names
and abbreviations. This variable affects the output from the DATE_FORMAT(), DAYNAME() and
MONTHNAME() functions. Locale names are POSIX-style values such as 'ja_JP' or 'pt_BR'.
The default value is 'en_US' regardless of your system's locale setting. For further information, see
Section 10.7, “MySQL Server Locale Support”. This variable was added in MySQL 5.0.25.
•

license
System Variable

Name

license

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

Default GPL
The type of license the server has.
•

local_infile
System Variable

Name

local_infile

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default true
Whether LOCAL is supported for LOAD DATA INFILE statements. If this variable is disabled, clients
cannot use LOCAL in LOAD DATA statements. While the default for this variable is true, whether
LOAD DATA INFILE LOCAL is actually permitted depends on how MySQL was compiled, as well
as a number of settings on both the server and the client; see Section 6.1.6, “Security Issues with
LOAD DATA LOCAL”, for details.
•

locked_in_memory
System Variable

Name

locked_in_memory

Variable Global
Scope
DynamicNo
Variable
Whether mysqld was locked in memory with --memlock.
•

log
Command-Line Format

--log[=file_name]

System Variable

Name

This
documentation
is for an
older version.
If you're

log

This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

Whether logging of all statements to the general query log is enabled. See Section 5.4.2, “The
General Query Log”.
•

log_bin_trust_function_creators

Introduced

5.0.16

Command-Line Format

--log-bin-trust-function-creators

System Variable

Name

log_bin_trust_function_creators

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default FALSE
This variable applies when binary logging is enabled. It controls whether stored function creators
can be trusted not to create stored functions that will cause unsafe events to be written to the binary
log. If set to 0 (the default), users are not permitted to create or alter stored functions unless they
have the SUPER privilege in addition to the CREATE ROUTINE or ALTER ROUTINE privilege. A
setting of 0 also enforces the restriction that a function must be declared with the DETERMINISTIC
characteristic, or with the READS SQL DATA or NO SQL characteristic. If the variable is set to 1,
MySQL does not enforce these restrictions on stored function creation. This variable also applies to
trigger creation. See Section 18.6, “Binary Logging of Stored Programs”.
This variable was added in MySQL 5.0.16.
•

log_bin_trust_routine_creators
This is the old name for log_bin_trust_function_creators. Before MySQL 5.0.16, it also
applies to stored procedures, not just stored functions. As of 5.0.16, this variable is deprecated. It is
recognized for backward compatibility but its use results in a warning.
This variable was added in MySQL 5.0.6. It is removed in MySQL 5.5.

•

log_error

Command-Line Format

--log-error[=file_name]

System Variable

Name

log_error

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The location of the error log, or empty if the server is writing error message to the standard error
output. See Section 5.4.1, “The Error Log”.
This
• log_queries_not_using_indexes
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--log-queries-not-using-indexes

System Variable (>=
5.0.23)

Name

log_queries_not_using_indexes

Variable Global
Scope
DynamicYes
Variable

Permitted Values

Type

boolean

Default OFF
Whether queries that do not use indexes are logged to the slow query log. See Section 5.4.4, “The
Slow Query Log”. This variable was added in MySQL 5.0.23.
•

log_slow_queries

Command-Line Format

--log-slow-queries[=name]

System Variable

Name

log_slow_queries

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

boolean

Whether slow queries should be logged. “Slow” is determined by the value of the
long_query_time variable. See Section 5.4.4, “The Slow Query Log”.
•

log_warnings

Command-Line Format

--log-warnings[=#]

System Variable

Name

log_warnings

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1
Min
Value

0

Max
Value

18446744073709547520

Whether to produce additional warning messages to the error log. This variable is enabled (1) by
default and can be disabled by setting it to 0. Aborted connections and access-denied errors for new
connection attempts are logged if the value is greater than 1.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

•

long_query_time
Command-Line Format

--long_query_time=#

System Variable

Name

long_query_time

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (<=
5.0.20)

Permitted Values (>=
5.0.21)

Type

integer

Default 10
Min
Value

1

Type

numeric

Default 10
Min
Value

0

If a query takes longer than this many seconds, the server increments the Slow_queries status
variable. 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. The minimum value is 1.
The default is 10. See Section 5.4.4, “The Slow Query Log”.
•

low_priority_updates
Command-Line Format

--low-priority-updates

System Variable

Name

low_priority_updates

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default FALSE
If set to 1, all INSERT, UPDATE, DELETE, and LOCK TABLE WRITE statements wait until there is no
pending SELECT or LOCK TABLE READ on the affected table. This affects only storage engines that
use only table-level locking (such as MyISAM, MEMORY, and MERGE). This variable previously was
named sql_low_priority_updates.
•

lower_case_file_system
System Variable

Name

lower_case_file_system

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

boolean

This variable describes the case sensitivity of file names on the file system where the data directory
is located. OFF means file names are case sensitive, ON means they are not case sensitive. This
variable is read only because it reflects a file system attribute and setting it would have no effect on
the file system.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

•

lower_case_table_names

Command-Line Format

--lower_case_table_names[=#]

System Variable

Name

lower_case_table_names

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

2

If set to 0, table names are stored as specified and comparisons are case sensitive. If set to 1, table
names are stored in lowercase on disk and comparisons are not case sensitive. If set to 2, table
names are stored as given but compared in lowercase. This option also applies to database names
and table aliases. For additional information, see Section 9.2.2, “Identifier Case Sensitivity”.
On Windows the default value is 1. On OS X, the default value is 2.
You should not set lower_case_table_names to 0 if you are running MySQL on a system where
the data directory resides on a case-insensitive file system (such as on Windows or OS X). It is an
unsupported combination that could result in a hang condition when running an INSERT INTO ...
SELECT ... FROM tbl_name operation with the wrong tbl_name letter case. With MyISAM,
accessing table names using different letter cases could cause index corruption.
If you are using InnoDB or MySQL Cluster (NDB) tables, you should set this variable to 1 on all
platforms to force names to be converted to lowercase.
The setting of this variable has no effect on replication filtering options. See Section 16.2.3, “How
Servers Evaluate Replication Filtering Rules”, for more information.
You should not use different settings for lower_case_table_names on replication masters and
slaves. In particular, you should not do this when the slave uses a case-sensitive file system, as
this can cause replication to fail. For more information, see Section 16.4.1.29, “Replication and
Variables”.
•

max_allowed_packet

Command-Line Format

--max_allowed_packet=#

System Variable

Name

max_allowed_packet

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 1048576

This
documentation
is for an
older version.
If you're

Min
Value

1024

Max
Value

1073741824
This
documentation
is for an
older version.
If you're

Server System Variables

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 to
max_allowed_packet bytes when needed. This value by default is small, to catch large (possibly
incorrect) packets.
You must increase this value if you are using large BLOB columns or long strings. It should be as
big as the largest BLOB you want to use. The protocol limit for max_allowed_packet is 1GB. The
value should be a multiple of 1024; nonmultiples are rounded down to the nearest multiple.
When you change the message buffer size by changing the value of the max_allowed_packet
variable, you should also change the buffer size on the client side if your client program permits
it. The default max_allowed_packet value built in to the client library is 1GB, but individual
client programs might override this. For example, mysql and mysqldump have defaults of
16MB and 24MB, respectively. They also enable you to change the client-side value by setting
max_allowed_packet on the command line or in an option file.
As of MySQL 5.0.84, the session value of this variable is read only. Before 5.0.84, setting the
session value is permitted but has no effect. The client can receive up to as many bytes as the
session value. However, the server will not send to the client more bytes than the current global
max_allowed_packet value. (The global value could be less than the session value if the global
value is changed after the client connects.)
•

max_connect_errors

Command-Line Format

--max_connect_errors=#

System Variable

Name

max_connect_errors

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 10
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 10
Min
Value

1

Max
Value

18446744073709547520

If more than this many successive connection requests from a host are interrupted without a
successful connection, the server blocks that host from further connections. You can unblock
blocked hosts by flushing the host cache. To do so, issue a FLUSH HOSTS statement or execute a
mysqladmin flush-hosts command. If a connection is established successfully within fewer than
max_connect_errors attempts after a previous connection was interrupted, the error count for the
host is cleared to zero. However, once a host is blocked, flushing the host cache is the only way to
unblock it.
•

max_connections

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--max_connections=#

System Variable

Name

max_connections

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 100
Min
Value

1

Max
Value

16384

The maximum permitted number of simultaneous client connections. By default, this is 100. See
Section B.5.2.7, “Too many connections”, for more information.
Increasing this value increases the number of file descriptors that mysqld requires. See
Section 8.4.3.1, “How MySQL Opens and Closes Tables”, for comments on file descriptor limits.
•

max_delayed_threads

Command-Line Format

--max_delayed_threads=#

System Variable

Name

max_delayed_threads

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 20
Min
Value

0

Max
Value

16384

Do not start more than this number of threads to handle INSERT DELAYED statements. If you try to
insert data into a new table after all INSERT DELAYED threads are in use, the row is inserted as if
the DELAYED attribute was not specified. If you set this to 0, MySQL never creates a thread to handle
DELAYED rows; in effect, this disables DELAYED entirely.
For the SESSION value of this variable, the only valid values are 0 or the GLOBAL value.
•

max_error_count

Command-Line Format

--max_error_count=#

System Variable

Name

max_error_count

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

integer
This
documentation
is for an
older version.
If you're

Server System Variables

Default 64
Min
Value

0

Max
Value

65535

The maximum number of error, warning, and note messages to be stored for display by the SHOW
ERRORS and SHOW WARNINGS statements.
•

max_heap_table_size

Command-Line Format

--max_heap_table_size=#

System Variable

Name

max_heap_table_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 16777216
Min
Value

16384

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 16777216
Min
Value

16384

Max
Value

1844674407370954752

This variable sets the maximum size to which user-created MEMORY tables are permitted to grow.
The value of the variable is used to calculate MEMORY table MAX_ROWS values. Setting this variable
has no effect on any existing MEMORY table, unless the table is re-created with a statement such as
CREATE TABLE or altered with ALTER TABLE or TRUNCATE TABLE. A server restart also sets the
maximum size of existing MEMORY tables to the global max_heap_table_size value.
This variable is also used in conjunction with tmp_table_size to limit the size of internal inmemory tables. See Section 8.4.4, “Internal Temporary Table Use in MySQL”.
max_heap_table_size is not replicated. See Section 16.4.1.15, “Replication and MEMORY
Tables”, and Section 16.4.1.29, “Replication and Variables”, for more information.
•

max_insert_delayed_threads

System Variable

Name

max_insert_delayed_threads

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

This variable is a synonym for max_delayed_threads.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

•

max_join_size

Command-Line Format

--max_join_size=#

System Variable

Name

max_join_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 4294967295
Min
Value

1

Max
Value

4294967295

Do not permit statements that probably need to examine more than max_join_size rows (for
single-table statements) or row combinations (for multiple-table statements) or that are likely to do
more than max_join_size disk seeks. By setting this value, you can catch statements where keys
are not used properly and that would probably take a long time. Set it if your users tend to perform
joins that lack a WHERE clause, that take a long time, or that return millions of rows.
Setting this variable to a value other than DEFAULT resets the value of sql_big_selects to 0. If
you set the sql_big_selects value again, the max_join_size variable is ignored.
If a query result is in the query cache, no result size check is performed, because the result has
previously been computed and it does not burden the server to send it to the client.
This variable previously was named sql_max_join_size.
•

max_length_for_sort_data

Command-Line Format

--max_length_for_sort_data=#

System Variable

Name

max_length_for_sort_data

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 1024
Min
Value

4

Max
Value

8388608

The cutoff on the size of index values that determines which filesort algorithm to use. See
Section 8.2.1.11, “ORDER BY Optimization”.
•

max_prepared_stmt_count

Introduced
Command-Line Format
This
System Variable
documentation
is for an
older version.
If you're

5.0.21
--max_prepared_stmt_count=# (>= 5.0.21)
Name

max_prepared_stmt_count

This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 16382
Min
Value

0

Max
Value

1048576

This variable limits the total number of prepared statements in the server. (The sum of the number of
prepared statements across all sessions.) It can be used in environments where there is the potential
for denial-of-service attacks based on running the server out of memory by preparing huge numbers
of statements. If the value is set lower than the current number of prepared statements, existing
statements are not affected and can be used, but no new statements can be prepared until the
current number drops below the limit. The default value is 16,382. The permissible range of values is
from 0 to 1 million. Setting the value to 0 disables prepared statements. This variable was added in
MySQL 5.0.21.
•

max_relay_log_size

Command-Line Format

--max_relay_log_size=#

System Variable

Name

max_relay_log_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

1073741824

If a write by a replication slave to its relay log causes the current log file size to exceed the value
of this variable, the slave rotates the relay logs (closes the current file and opens the next one).
If max_relay_log_size is 0, the server uses max_binlog_size for both the binary log and
the relay log. If max_relay_log_size is greater than 0, it constrains the size of the relay log,
which enables you to have different sizes for the two logs. You must set max_relay_log_size
to between 4096 bytes and 1GB (inclusive), or to 0. The default value is 0. See Section 16.2.1,
“Replication Implementation Details”.
•

max_seeks_for_key

Command-Line Format

--max_seeks_for_key=#

System Variable

Name

max_seeks_for_key

Variable Global, Session
Scope
DynamicYes
Variable
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Permitted Values (32-bit Type
integer
platforms)
Default 4294967295
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 18446744073709547520
Min
Value

1

Max
Value

18446744073709547520

Limit the assumed maximum number of seeks when looking up rows based on a key. The MySQL
optimizer assumes that no more than this number of key seeks are required when searching for
matching rows in a table by scanning an index, regardless of the actual cardinality of the index (see
Section 13.7.5.18, “SHOW INDEX Syntax”). By setting this to a low value (say, 100), you can force
MySQL to prefer indexes instead of table scans.
•

max_sort_length

Command-Line Format

--max_sort_length=#

System Variable

Name

max_sort_length

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 1024
Min
Value

4

Max
Value

8388608

The number of bytes to use when sorting data values. The server uses only the first
max_sort_length bytes of each value and ignores the rest. Consequently, values that differ
only after the first max_sort_length bytes compare as equal for GROUP BY, ORDER BY, and
DISTINCT operations.
•

max_sp_recursion_depth

Introduced

5.0.17

Command-Line Format

--max_sp_recursion_depth[=#]

System Variable

Name

max_sp_recursion_depth

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

integer

Default 0

This
documentation
is for an
older version.
If you're

Server System Variables

Max
Value

255

The number of times that any given stored procedure may be called recursively. The default value
for this option is 0, which completely disables recursion in stored procedures. The maximum value is
255.
Stored procedure recursion increases the demand on thread stack space. If you increase the value
of max_sp_recursion_depth, it may be necessary to increase thread stack size by increasing the
value of thread_stack at server startup.
This variable was added in MySQL 5.0.17.
•

max_tmp_tables
This variable is unused.

•

max_user_connections
Command-Line Format

--max_user_connections=#

System Variable (<=
5.0.3)

Name

max_user_connections

Variable Global
Scope
DynamicYes
Variable

System Variable (>=
5.0.3)

Name

max_user_connections

Variable Global, Session
Scope
DynamicYes
Variable

Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

4294967295

The maximum number of simultaneous connections permitted to any given MySQL user account. A
value of 0 (the default) means “no limit.”
Before MySQL 5.0.3, this variable has only a global value that can be set at server startup or
runtime. As of MySQL 5.0.3, it also has a read-only session value that indicates the effective
simultaneous-connection limit that applies to the account associated with the current session. The
session value is initialized as follows:
• If the user account has a nonzero MAX_USER_CONNECTIONS resource limit, the session
max_user_connections value is set to that limit.
• Otherwise, the session max_user_connections value is set to the global value.
Account resource limits are specified using the GRANT statement. See Section 6.3.4, “Setting
Account Resource Limits”, and Section 13.7.1.3, “GRANT Syntax”.
•

max_write_lock_count
Command-Line Format

This
documentation
is for an
older version.
If you're

--max_write_lock_count=#

This
documentation
is for an
older version.
If you're

Server System Variables

System Variable

Name

max_write_lock_count

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 4294967295
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 18446744073709547520
Min
Value

1

Max
Value

18446744073709547520

After this many write locks, permit some pending read lock requests to be processed in between.
• multi_range_count

Introduced

5.0.3

Command-Line Format

--multi_range_count=#

System Variable

Name

multi_range_count

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 256
Min
Value

1

Max
Value

4294967295

The maximum number of ranges to send to a table handler at once during range selects. The default
value is 256. Sending multiple ranges to a handler at once can improve the performance of certain
selects dramatically. This is especially true for the NDBCLUSTER table handler, which needs to send
the range requests to all nodes. Sending a batch of those requests at once reduces communication
costs significantly.
This variable was added in MySQL 5.0.3.
•

myisam_data_pointer_size

Command-Line Format

--myisam_data_pointer_size=#

System Variable

Name

This
documentation
is for an
older version.
If you're

myisam_data_pointer_size

Variable Global
Scope

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Permitted Values (<=
5.0.5)

Permitted Values (>=
5.0.6)

Type

integer

Default 4
Min
Value

2

Max
Value

8

Type

integer

Default 6
Min
Value

2

Max
Value

7

The default pointer size in bytes, to be used by CREATE TABLE for MyISAM tables when no
MAX_ROWS option is specified. This variable cannot be less than 2 or larger than 7. The default value
is 6 (4 before MySQL 5.0.6). See Section B.5.2.12, “The table is full”.
•

myisam_max_extra_sort_file_size (DEPRECATED)
This variable is unused as of MySQL 5.0.6.

•

myisam_max_sort_file_size
Command-Line Format

--myisam_max_sort_file_size=#

System Variable

Name

myisam_max_sort_file_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 2147483648
Permitted Values (64-bit Type
integer
platforms)
Default 9223372036854775807
The maximum size of the temporary file that MySQL is permitted to use while re-creating a MyISAM
index (during REPAIR TABLE, ALTER TABLE, or LOAD DATA INFILE). If the file size would be
larger than this value, the index is created using the key cache instead, which is slower. The value is
given in bytes.
If MyISAM index files exceed this size and disk space is available, increasing the value may help
performance. The space must be available in the file system containing the directory where the
original index file is located.
•

myisam_mmap_size
Introduced

5.0.90

Command-Line Format

--myisam_mmap_size=#

System Variable

Name

myisam_mmap_size

Variable Global
Scope

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicNo
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 4294967295
Min
Value

7

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 18446744073709547520
Min
Value

7

Max
Value

18446744073709547520

The maximum amount of memory to use for memory mapping compressed MyISAM files. If many
compressed MyISAM tables are used, the value can be decreased to reduce the likelihood of
memory-swapping problems. This variable was added in MySQL 5.0.90.
•

myisam_recover_options

System Variable

Name

myisam_recover_options

Variable Global
Scope
DynamicNo
Variable
The value of the --myisam-recover option. See Section 5.1.3, “Server Command Options”.
•

myisam_repair_threads

Command-Line Format

--myisam_repair_threads=#

System Variable

Name

myisam_repair_threads

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1

This
documentation
is for an
older version.
If you're

Min
Value

1

Max
Value

18446744073709547520
This
documentation
is for an
older version.
If you're

Server System Variables

If this value is greater than 1, MyISAM table indexes are created in parallel (each index in its own
thread) during the Repair by sorting process. The default value is 1.
Note
Multi-threaded repair is still beta-quality code.
•

myisam_sort_buffer_size

Command-Line Format

--myisam_sort_buffer_size=#

System Variable

Name

myisam_sort_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
(Windows)

Type

integer

Default 8388608
Min
Value

4096

Max
Value

4294967295

Permitted Values (Other, Type
integer
32-bit platforms)
Default 8388608
Min
Value

4096

Max
Value

4294967295

Permitted Values (Other, Type
integer
64-bit platforms)
Default 8388608
Min
Value

4096

Max
Value

18446744073709547520

The size of the buffer that is allocated when sorting MyISAM indexes during a REPAIR TABLE or
when creating indexes with CREATE INDEX or ALTER TABLE.
The maximum permissible setting for myisam_sort_buffer_size is 4GB−1.
•

myisam_stats_method

Introduced

5.0.14

Command-Line Format

--myisam_stats_method=name

System Variable

Name

myisam_stats_method

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (>=
5.0.14)

This
documentation
is for an
older version.
If you're

Type

enumeration
This
documentation
is for an
older version.
If you're

Server System Variables

Default nulls_unequal
Valid
nulls_equal
Values nulls_unequal
nulls_ignored
How the server treats NULL values when collecting statistics about the distribution of index values
for MyISAM tables. This variable has three possible values, nulls_equal, nulls_unequal, and
nulls_ignored. For nulls_equal, all NULL index values are considered equal and form a single
value group that has a size equal to the number of NULL values. For nulls_unequal, NULL values
are considered unequal, and each NULL forms a distinct value group of size 1. For nulls_ignored,
NULL values are ignored.
The method that is used for generating table statistics influences how the optimizer chooses indexes
for query execution, as described in Section 8.3.7, “MyISAM Index Statistics Collection”.
Any unique prefix of a valid value may be used to set the value of this variable.
This variable was added in MySQL 5.0.14. For older versions, the statistics collection method is
equivalent to nulls_equal.
•

named_pipe

System Variable

Name

named_pipe

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Windows

Permitted Values
(Windows)

Type

boolean

Default OFF

(Windows only.) Indicates whether the server supports connections over named pipes.
•

net_buffer_length

Command-Line Format

--net_buffer_length=#

System Variable

Name

net_buffer_length

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 16384
Min
Value

1024

Max
Value

1048576

Each client thread is associated with a connection buffer and result buffer. Both begin with a size
given by net_buffer_length but are dynamically enlarged up to max_allowed_packet bytes
as needed. The result buffer shrinks to net_buffer_length after each SQL statement.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

This variable should not normally be changed, but if you have very little memory, you can set it to the
expected length of statements sent by clients. If statements exceed this length, the connection buffer
is automatically enlarged. The maximum value to which net_buffer_length can be set is 1MB.
As of MySQL 5.0.84, the session value of this variable is read only. Before 5.0.84, setting the
session value is permitted but has no effect.
•

net_read_timeout

Command-Line Format

--net_read_timeout=#

System Variable

Name

net_read_timeout

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 30
Min
Value

1

The number of seconds to wait for more data from a connection before aborting the read.
This timeout applies only to TCP/IP connections, not to connections made through Unix
socket files, named pipes, or shared memory. 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 also
slave_net_timeout.
On Linux, the NO_ALARM build flag affects timeout behavior as indicated in the description of the
net_retry_count system variable.
•

net_retry_count

Command-Line Format

--net_retry_count=#

System Variable

Name

net_retry_count

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 10
Min
Value

1

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 10

This
documentation
is for an
older version.
If you're

Min
Value

1

Max
Value

18446744073709547520

This
documentation
is for an
older version.
If you're

Server System Variables

If a read or write 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.
On Linux, the NO_ALARM build flag (-DNO_ALARM) modifies how the binary treats both
net_read_timeout and net_write_timeout. With this flag enabled, neither timer cancels
the current statement until after the failing connection has been waited on an additional
net_retry_count times. This means that the effective timeout value becomes (timeout
setting) × (net_retry_count+1).
•

net_write_timeout

Command-Line Format

--net_write_timeout=#

System Variable

Name

net_write_timeout

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 60
Min
Value

1

The number of seconds to wait for a block to be written to a connection before aborting the write.
This timeout applies only to TCP/IP connections, not to connections made using Unix socket files,
named pipes, or shared memory. See also net_read_timeout.
On Linux, the NO_ALARM build flag affects timeout behavior as indicated in the description of the
net_retry_count system variable.
•

new

Command-Line Format

--new

System Variable

Name

new

Variable Global, Session
Scope
DynamicYes
Variable
Disabled by

skip-new

Permitted Values

Type

boolean

Default FALSE
This variable was used in MySQL 4.0 to turn on some 4.1 behaviors, and is retained for backward
compatibility. Its value is always OFF.
•

old_passwords

System Variable

Name

old_passwords

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

boolean

This
documentation
is for an
older version.
If you're

Server System Variables

Default 0
This variable controls the password hashing method used by the PASSWORD() function. It also
influences password hashing performed by CREATE USER and GRANT statements that specify a
password using an IDENTIFIED BY clause.
The value determines whether or not to use “old” native MySQL password hashing. A value of 0 (or
OFF) causes passwords to be encrypted using the format available from MySQL 4.1 on. A value of 1
(or ON) causes password encryption to use the older pre-4.1 format.
If old_passwords=1, PASSWORD(str) returns the same value as OLD_PASSWORD(str). The
latter function is not affected by the value of old_passwords.
For information about hashing formats, see Section 6.1.2.4, “Password Hashing in MySQL”.
•

one_shot
This is not a variable, but it can be used when setting some variables. It is described in
Section 13.7.4, “SET Syntax”.

•

open_files_limit

Command-Line Format

--open-files-limit=#

System Variable

Name

open_files_limit

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

platform dependent

The number of files that the operating system permits mysqld to open. This is the real value
permitted by the system and might be different from the value you gave using the --open-fileslimit option to mysqld or mysqld_safe. The value is 0 on systems where MySQL cannot change
the number of open files.
•

optimizer_prune_level

Introduced

5.0.1

Command-Line Format

--optimizer_prune_level[=#]

System Variable

Name

optimizer_prune_level

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 1
Controls the heuristics applied during query optimization to prune less-promising partial plans
This
This
from the optimizer search space. A value of 0 disables heuristics so that the optimizer performs
an
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

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
Introduced

5.0.1

Command-Line Format

--optimizer_search_depth[=#]

System Variable

Name

optimizer_search_depth

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 62
Min
Value

0

Max
Value

63

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 63, the optimizer switches to the algorithm used in MySQL 5.0.0 (and
previous versions) for performing searches. This variable was added in MySQL 5.0.1.
•

pid_file
Command-Line Format

--pid-file=file_name

System Variable

Name

pid_file

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The path name of the process ID (PID) file. This variable can be set with the --pid-file option.
•

plugin_dir
Introduced

5.0.67

Command-Line Format

--plugin_dir=dir_name

System Variable

Name

plugin_dir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

Default
The path name of the plugin directory. This variable was added in MySQL 5.0.67. If the value is
nonempty, user-defined function object files must be located in this directory. If the value is empty,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

the behavior that is used before 5.0.67 applies: The UDF object files must be located in a directory
that is searched by your system's dynamic linker.
If the plugin directory is writable by the server, it may be possible for a user to write executable code
to a file in the directory using SELECT ... INTO DUMPFILE. This can be prevented by making
plugin_dir read only to the server or by setting --secure-file-priv to a directory where
SELECT writes can be made safely.
•

port
Command-Line Format

--port=#

System Variable

Name

port

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 3306
Min
Value

0

Max
Value

65535

The number of the port on which the server listens for TCP/IP connections. This variable can be set
with the --port option.
•

preload_buffer_size
Command-Line Format

--preload_buffer_size=#

System Variable

Name

preload_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 32768
Min
Value

1024

Max
Value

1073741824

The size of the buffer that is allocated when preloading indexes.
•

prepared_stmt_count
Introduced

5.0.21

Removed

5.0.31

System Variable (>=
5.0.21, <= 5.0.31)

Name

prepared_stmt_count

Variable Global
Scope
DynamicNo
Variable

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Permitted Values

Type

integer

The current number of prepared statements. (The maximum number of statements is given by the
max_prepared_stmt_count system variable.) This variable was added in MySQL 5.0.21. In
MySQL 5.0.32, it was converted to the global Prepared_stmt_count status variable.
•

profiling
If set to 0 or OFF (the default), statement profiling is disabled. If set to 1 or ON, statement profiling
is enabled and the SHOW PROFILE and SHOW PROFILES statements provide access to profiling
information. See Section 13.7.5.29, “SHOW PROFILES Syntax”. This variable was added in MySQL
5.0.37. Note: This option does not apply to MySQL Enterprise Server users.

•

profiling_history_size
The number of statements for which to maintain profiling information if profiling is enabled. The
default value is 15. The maximum value is 100. Setting the value to 0 effectively disables profiling.
See Section 13.7.5.29, “SHOW PROFILES Syntax”. This variable was added in MySQL 5.0.37.
Note: This option does not apply to MySQL Enterprise Server users.

•

protocol_version

System Variable

Name

protocol_version

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

The version of the client/server protocol used by the MySQL server.
•

pseudo_thread_id

System Variable

Name

pseudo_thread_id

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

This variable is for internal server use.
•

query_alloc_block_size

Command-Line Format

--query_alloc_block_size=#

System Variable

Name

query_alloc_block_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 8192
This
documentation
is for an
older version.
If you're

Min
Value

1024

This
documentation
is for an
older version.
If you're

Server System Variables

Max
Value

4294967295

Block
Size

1024

Permitted Values (64-bit Type
integer
platforms)
Default 8192
Min
Value

1024

Max
Value

18446744073709547520

Block
Size

1024

The allocation size of memory blocks that are allocated for objects created during statement parsing
and execution. If you have problems with memory fragmentation, it might help to increase this
parameter.
•

query_cache_limit
Command-Line Format

--query_cache_limit=#

System Variable

Name

query_cache_limit

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 1048576
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 1048576
Min
Value

0

Max
Value

18446744073709547520

Do not cache results that are larger than this number of bytes. The default value is 1MB.
•

query_cache_min_res_unit
Command-Line Format

--query_cache_min_res_unit=#

System Variable

Name

query_cache_min_res_unit

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 4096

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

512

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 4096
Min
Value

512

Max
Value

18446744073709547520

The minimum size (in bytes) for blocks allocated by the query cache. The default value is 4096
(4KB). Tuning information for this variable is given in Section 8.10.3.3, “Query Cache Configuration”.
•

query_cache_size

Command-Line Format

--query_cache_size=#

System Variable

Name

query_cache_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 0
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 0
Min
Value

0

Max
Value

18446744073709547520

The amount of memory allocated for caching query results. The default value is 0, which disables the
query cache. The permissible values are multiples of 1024; other values are rounded down to the
nearest multiple. query_cache_size bytes of memory are allocated even if query_cache_type
is set to 0. See Section 8.10.3.3, “Query Cache Configuration”, for more information.
The query cache needs a minimum size of about 40KB to allocate its structures. (The exact size
depends on system architecture.) If you set the value of query_cache_size too small, a warning
will occur, as described in Section 8.10.3.3, “Query Cache Configuration”.
•

query_cache_type

Command-Line Format

--query_cache_type=#

System Variable

Name

query_cache_type

Variable Global, Session
Scope
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

DynamicYes
Variable
Permitted Values

Type

enumeration

Default 1
Valid
0
Values 1
2
Set the query cache type. Setting the GLOBAL value sets the type for all clients that connect
thereafter. Individual clients can set the SESSION value to affect their own use of the query cache.
Possible values are shown in the following table.

Option

Description

0 or OFF

Do not cache results in or retrieve results from the query cache. Note that
this does not deallocate the query cache buffer. To do that, you should set
query_cache_size to 0.

1 or ON

Cache all cacheable query results except for those that begin with SELECT
SQL_NO_CACHE.

2 or DEMAND

Cache results only for cacheable queries that begin with SELECT SQL_CACHE.

This variable defaults to ON.
Any unique prefix of a valid value may be used to set the value of this variable.
•

query_cache_wlock_invalidate

Command-Line Format

--query_cache_wlock_invalidate

System Variable

Name

query_cache_wlock_invalidate

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default FALSE
Normally, when one client acquires a WRITE lock on a MyISAM table, other clients are not blocked
from issuing statements that read from the table if the query results are present in the query cache.
Setting this variable to 1 causes acquisition of a WRITE lock for a table to invalidate any queries in
the query cache that refer to the table. This forces other clients that attempt to access the table to
wait while the lock is in effect.
•

query_prealloc_size

Command-Line Format

--query_prealloc_size=#

System Variable

Name

query_prealloc_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
This
platforms)
Default 8192
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

8192

Max
Value

4294967295

Block
Size

1024

Permitted Values (64-bit Type
integer
platforms)
Default 8192
Min
Value

8192

Max
Value

18446744073709547520

Block
Size

1024

The size of the persistent buffer used for statement parsing and execution. This buffer is not freed
between statements. 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.
•

rand_seed1
The rand_seed1 and rand_seed2 variables exist as session variables only, and can be set but not
read. They are not shown in the output of SHOW VARIABLES.
The purpose of these variables is to support replication of the RAND() function. For statements
that invoke RAND(), the master passes two values to the slave, where they are used to seed the
random number generator. The slave uses these values to set the session variables rand_seed1
and rand_seed2 so that RAND() on the slave generates the same value as on the master.

•

rand_seed2
See the description for rand_seed1.

•

range_alloc_block_size
Command-Line Format

--range_alloc_block_size=#

System Variable

Name

range_alloc_block_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 4096
Min
Value

4096

Max
Value

4294967295

Block
Size

1024

The size of blocks that are allocated when doing range optimization.
•

read_buffer_size

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--read_buffer_size=#

System Variable

Name

read_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 131072
Min
Value

8200

Max
Value

2147479552

Each thread that does a sequential scan allocates a buffer of this size (in bytes) for each table it
scans. If you do many sequential scans, you might want to increase this value, which defaults to
131072. The value of this variable should be a multiple of 4KB. If it is set to a value that is not a
multiple of 4KB, its value will be rounded down to the nearest multiple of 4KB.
The maximum permissible setting for read_buffer_size is 2GB.
read_buffer_size and read_rnd_buffer_size are not specific to any storage engine and
apply in a general manner for optimization. See Section 8.12.5.1, “How MySQL Uses Memory”, for
example.
•

read_only
Command-Line Format

--read_only

System Variable

Name

read_only

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
When the read_only system variable is enabled, the server permits no client updates except from
users who have the SUPER privilege. This variable is disabled by default.
Even with read_only enabled, the server permits these operations:
• Updates performed by slave threads, if the server is a replication slave. In replication setups, it can
be useful to enable read_only on slave servers to ensure that slaves accept updates only from
the master server and not from clients.
• Use of ANALYZE TABLE or OPTIMIZE TABLE statements. The purpose of read-only mode is to
prevent changes to table structure or contents. Analysis and optimization do not qualify as such
changes. This means, for example, that consistency checks on read-only replication slaves can be
performed with mysqlcheck --all-databases --analyze.
• Operations on TEMPORARY tables, as of MySQL 5.0.16.
read_only exists only as a GLOBAL variable, so changes to its value require the SUPER privilege.
Changes to read_only on a master server are not replicated to slave servers. The value can be set
on a slave server independent of the setting on the master.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Important
As of MySQL 5.1, enabling read_only prevents users not having the SUPER
privilege from using account-management statements such as CREATE USER
or SET PASSWORD. This is not the case for MySQL 5.0. When replicating
from a MySQL 5.0 master to a MySQL 5.1 or later slave, check whether this
will have an impact on your applications.
•

read_rnd_buffer_size

Command-Line Format

--read_rnd_buffer_size=#

System Variable

Name

read_rnd_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 262144
Min
Value

8200

Max
Value

2147483647

When reading rows in sorted order following a key-sorting operation, the rows are read through this
buffer to avoid disk seeks. See Section 8.2.1.11, “ORDER BY Optimization”. 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.
The maximum permissible setting for read_rnd_buffer_size is 2GB.
read_buffer_size and read_rnd_buffer_size are not specific to any storage engine and
apply in a general manner for optimization. See Section 8.12.5.1, “How MySQL Uses Memory”, for
example.
•

relay_log_purge

Command-Line Format

--relay_log_purge

System Variable

Name

relay_log_purge

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default TRUE
Disables or enables automatic purging of relay log files as soon as they are not needed any more.
The default value is 1 (ON).
•

relay_log_space_limit

Command-Line Format
This
System Variable
documentation
is for an
older version.
If you're

--relay_log_space_limit=#
Name

relay_log_space_limit

This
documentation
is for an
older version.
If you're

Server System Variables

Variable Global
Scope
DynamicNo
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 0
Min
Value

0

Max
Value

4294967295

Permitted Values (64-bit Type
integer
platforms)
Default 0
Min
Value

0

Max
Value

18446744073709547520

The maximum amount of space to use for all relay logs.
•

secure_auth

Command-Line Format

--secure-auth

System Variable

Name

secure_auth

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF
If this variable is enabled, the server blocks connections by clients that attempt to use accounts that
have passwords stored in the old (pre-4.1) format.
Enable this variable to prevent all use of passwords employing the old format (and hence insecure
communication over the network).
Server startup fails with an error if this variable is enabled and the privilege tables are in pre-4.1
format. See Section B.5.2.4, “Client does not support authentication protocol”.
•

secure_file_priv

Introduced

5.0.38

Command-Line Format

--secure-file-priv=dir_name

System Variable

Name

secure_file_priv

Variable Global
Scope
DynamicNo
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

string

Default empty

This
documentation
is for an
older version.
If you're

Server System Variables

Valid
empty
Values dirname
This variable is used to limit the effect of data import and export operations, such as those performed
by the LOAD DATA and SELECT ... INTO OUTFILE statements and the LOAD_FILE() function.
By default, this variable is empty. If set to the name of a directory, it limits import and export
operations to work only with files in that directory.
This variable was added in MySQL 5.0.38.
•

server_id
Command-Line Format

--server-id=#

System Variable

Name

server_id

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

4294967295

The server ID, used in replication to give each master and slave a unique identity. This variable is set
by the --server-id option. For each server participating in replication, you should pick a positive
32
integer in the range from 1 to 2 − 1 to act as that server's ID.
•

shared_memory
Command-Line Format

--shared_memory[={0,1}]

System Variable

Name

shared_memory

Variable Global
Scope
DynamicNo
Variable
Platform Specific

Windows

Permitted Values

Type

boolean

Default FALSE
(Windows only.) Whether the server permits shared-memory connections.
•

shared_memory_base_name
Command-Line Format

--shared_memory_base_name=name

System Variable

Name

shared_memory_base_name

Variable Global
Scope
DynamicNo
Variable
Platform Specific

This
documentation
is for an
older version.
If you're

Windows

This
documentation
is for an
older version.
If you're

Server System Variables

Permitted Values

Type

string

Default MYSQL
(Windows only.) The name of shared memory to use for shared-memory connections. This is useful
when running multiple MySQL instances on a single physical machine. The default name is MYSQL.
The name is case sensitive.
•

skip_external_locking

Command-Line Format

--skip-external-locking

System Variable

Name

skip_external_locking

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

boolean

Default ON
This is OFF if mysqld uses external locking (system locking), ON if external locking is disabled. This
affects only MyISAM table access.
This variable is set by the --external-locking or --skip-external-locking option.
External locking is disabled by default.
External locking affects only MyISAM table access. For more information, including conditions under
which it can and cannot be used, see Section 8.11.4, “External Locking”.
•

skip_networking

Command-Line Format

--skip-networking

System Variable

Name

skip_networking

Variable Global
Scope
DynamicNo
Variable
This is ON if the server permits only local (non-TCP/IP) connections. On Unix, local connections
use a Unix socket file. On Windows, local connections use a named pipe or shared memory. On
NetWare, only TCP/IP connections are supported, so do not set this variable to ON. This variable can
be set to ON with the --skip-networking option.
•

skip_show_database

Command-Line Format

--skip-show-database

System Variable

Name

skip_show_database

Variable Global
Scope
DynamicNo
Variable
This prevents people from using the SHOW DATABASES statement if they do not have the SHOW
DATABASES privilege. This can improve security if you have concerns about users being able to see
This
databases belonging to other users. Its effect depends on the SHOW DATABASES privilege: If the This
documentation
documentation
variable value is ON, the SHOW DATABASES statement is permitted only to users who have
the SHOW
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

DATABASES privilege, and the statement displays all database names. If the value is OFF, SHOW
DATABASES is permitted to all users, but displays the names of only those databases for which the
user has the SHOW DATABASES or other privilege. (Note that any global privilege is considered a
privilege for the database.)
•

slow_launch_time

Command-Line Format

--slow_launch_time=#

System Variable

Name

slow_launch_time

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 2
If creating a thread takes longer than this many seconds, the server increments the
Slow_launch_threads status variable.
•

socket

Command-Line Format

--socket={file_name|pipe_name}

System Variable

Name

socket

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

Default /tmp/mysql.sock
On Unix platforms, this variable is the name of the socket file that is used for local client connections.
The default is /tmp/mysql.sock. (For some distribution formats, the directory might be different,
such as /var/lib/mysql for RPMs.)
On Windows, this variable is the name of the named pipe that is used for local client connections.
The default value is MySQL (not case sensitive).
•

sort_buffer_size

Command-Line Format

--sort_buffer_size=#

System Variable

Name

sort_buffer_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 2097144

This
documentation
is for an
older version.
If you're

Min
Value

32768

Max
Value

4294967295
This
documentation
is for an
older version.
If you're

Server System Variables

Each session that needs to do a sort allocates a buffer of this size. sort_buffer_size
is not specific to any storage engine and applies in a general manner for optimization. See
Section 8.2.1.11, “ORDER BY Optimization”, for example.
If you see many Sort_merge_passes per second in SHOW GLOBAL STATUS output, you can
consider increasing the sort_buffer_size value to speed up ORDER BY or GROUP BY operations
that cannot be improved with query optimization or improved indexing. The entire buffer is allocated
even if it is not all needed, so setting it larger than required globally will slow down most queries that
sort. It is best to increase it as a session setting, and only for the sessions that need a larger size.
On Linux, there are thresholds of 256KB and 2MB where larger values may significantly slow down
memory allocation, so you should consider staying below one of those values. Experiment to find the
best value for your workload. See Section B.5.3.5, “Where MySQL Stores Temporary Files”.
The maximum permissible setting for sort_buffer_size is 4GB−1.
•

sql_auto_is_null

System Variable

Name

sql_auto_is_null

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 1
If this variable is set to 1 (the default), then after a statement that successfully inserts an
automatically generated AUTO_INCREMENT value, you can find that value by issuing a statement of
the following form:
SELECT * FROM tbl_name WHERE auto_col IS NULL

If the statement returns a row, the value returned is the same as if you invoked the
LAST_INSERT_ID() function. For details, including the return value after a multiple-row insert, see
Section 12.13, “Information Functions”. If no AUTO_INCREMENT value was successfully inserted, the
SELECT statement returns no row.
The behavior of retrieving an AUTO_INCREMENT value by using an IS NULL comparison is used by
some ODBC programs, such as Access. See Obtaining Auto-Increment Values. This behavior can
be disabled by setting sql_auto_is_null to 0.
•

sql_big_selects

System Variable

Name

sql_big_selects

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 1
If set to 0, MySQL aborts SELECT statements that are likely to take a very long time to execute (that
is, statements for which the optimizer estimates that the number of examined rows exceeds the
value of max_join_size). This is useful when an inadvisable WHERE statement has been issued.
The default value for a new connection is 1, which permits all SELECT statements.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

Server System Variables

If you set the max_join_size system variable to a value other than DEFAULT, sql_big_selects
is set to 0.
•

sql_buffer_result

System Variable

Name

sql_buffer_result

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 0
If set to 1, sql_buffer_result forces results from SELECT statements to be put into temporary
tables. This helps MySQL free the table locks early and can be beneficial in cases where it takes a
long time to send results to the client. The default value is 0.
•

sql_log_bin

System Variable

Name

sql_log_bin

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

If set to 0, no logging is done to the binary log for the client. The client must have the SUPER privilege
to set this option. The default value is 1.
•

sql_log_off

System Variable

Name

sql_log_off

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 0
If set to 1, no logging is done to the general query log for this client. The client must have the SUPER
privilege to set this option. The default value is 0.
•

sql_log_update

Deprecated

5.0.0, by sql_log_bin

System Variable

Name

sql_log_update

Variable Session
Scope
DynamicYes
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

boolean

This
documentation
is for an
older version.
If you're

Server System Variables

This variable is deprecated, and is mapped to sql_log_bin. It is removed in MySQL 5.5.
•

sql_mode
Command-Line Format

--sql-mode=name

System Variable

Name

sql_mode

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

set

Default ''
Valid
ALLOW_INVALID_DATES
Values ANSI_QUOTES
ERROR_FOR_DIVISION_BY_ZERO
HIGH_NOT_PRECEDENCE
IGNORE_SPACE
NO_AUTO_CREATE_USER
NO_AUTO_VALUE_ON_ZERO
NO_BACKSLASH_ESCAPES
NO_DIR_IN_CREATE
NO_ENGINE_SUBSTITUTION
NO_FIELD_OPTIONS
NO_KEY_OPTIONS
NO_TABLE_OPTIONS
NO_UNSIGNED_SUBTRACTION
NO_ZERO_DATE
NO_ZERO_IN_DATE
ONLY_FULL_GROUP_BY
PAD_CHAR_TO_FULL_LENGTH
PIPES_AS_CONCAT
REAL_AS_FLOAT
STRICT_ALL_TABLES
STRICT_TRANS_TABLES
The current server SQL mode, which can be set dynamically. For details, see Section 5.1.7, “Server
SQL Modes”.
Note
MySQL installation programs may configure the SQL mode during the
installation process. If the SQL mode differs from the default or from what you
expect, check for a setting in an option file that the server reads at startup.
•

sql_notes
If set to 1 (the default), warnings of Note level increment warning_count and the server records
them. If set to 0, Note warnings do not increment warning_count and the server does not record

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

them. mysqldump includes output to set this variable to 0 so that reloading the dump file does not
produce warnings for events that do not affect the integrity of the reload operation. sql_notes was
added in MySQL 5.0.3.
•

sql_quote_show_create
If set to 1 (the default), the server quotes identifiers for SHOW CREATE TABLE and SHOW CREATE
DATABASE statements. If set to 0, quoting is disabled. This option is enabled by default so that
replication works for identifiers that require quoting. See Section 13.7.5.9, “SHOW CREATE TABLE
Syntax”, and Section 13.7.5.6, “SHOW CREATE DATABASE Syntax”.

•

sql_safe_updates
If set to 1, MySQL aborts UPDATE or DELETE statements that do not use a key in the WHERE clause
or a LIMIT clause. (Specifically, UPDATE statements must have a WHERE clause that uses a key or a
LIMIT clause, or both. DELETE statements must have both.) This makes it possible to catch UPDATE
or DELETE statements where keys are not used properly and that would probably change or delete a
large number of rows. The default value is 0.

•

sql_select_limit

System Variable

Name

sql_select_limit

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

integer

The maximum number of rows to return from SELECT statements. The default value for a new
connection is the maximum number of rows that the server permits per table, which depends on
the server configuration and may be affected if the server build was configured with --with-big32
64
tables. Typical default values are (2 )−1 or (2 )−1. If you have changed the limit, the default
value can be restored by assigning a value of DEFAULT.
If a SELECT has a LIMIT clause, the LIMIT takes precedence over the value of
sql_select_limit.
•

sql_warnings
This variable controls whether single-row INSERT statements produce an information string if
warnings occur. The default is 0. Set the value to 1 to produce an information string.

•

ssl_ca

Introduced

5.0.23

Command-Line Format

--ssl-ca=file_name

System Variable

Name

ssl_ca

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The path to a file with a list of trusted SSL CAs. This variable was added in MySQL 5.0.23.
• ssl_capath
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Introduced

5.0.23

Command-Line Format

--ssl-capath=dir_name

System Variable

Name

ssl_capath

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The path to a directory that contains trusted SSL CA certificates in PEM format. This variable was
added in MySQL 5.0.23.
•

ssl_cert

Introduced

5.0.23

Command-Line Format

--ssl-cert=file_name

System Variable

Name

ssl_cert

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

file name

The name of the SSL certificate file to use for establishing a secure connection. This variable was
added in MySQL 5.0.23.
•

ssl_cipher

Introduced

5.0.23

Command-Line Format

--ssl-cipher=name

System Variable

Name

ssl_cipher

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

A list of permissible ciphers to use for SSL encryption. This variable was added in MySQL 5.0.23.
•

ssl_key

Introduced

5.0.23

Command-Line Format

--ssl-key=file_name

System Variable

Name

ssl_key

Variable Global
Scope
DynamicNo
Variable
Permitted Values
This
documentation
is for an
older version.
If you're

Type

file name
This
documentation
is for an
older version.
If you're

Server System Variables

The name of the SSL key file to use for establishing a secure connection. This variable was added in
MySQL 5.0.23.
•

storage_engine
System Variable

Name

storage_engine

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

enumeration

Default MyISAM
The default storage engine (table type). To set the storage engine at server startup, use the -default-storage-engine option. See Section 5.1.3, “Server Command Options”.
To see which storage engines are available and enabled, use the SHOW ENGINES statement.
•

sync_frm
Command-Line Format

--sync-frm

System Variable

Name

sync_frm

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default TRUE
If this variable is set to 1, when any nontemporary table is created its .frm file is synchronized to
disk (using fdatasync()). This is slower but safer in case of a crash. The default is 1.
•

system_time_zone
System Variable

Name

system_time_zone

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

The server system time zone. When the server begins executing, it inherits a time zone setting from
the machine defaults, possibly modified by the environment of the account used for running the
server or the startup script. The value is used to set system_time_zone. Typically the time zone is
specified by the TZ environment variable. It also can be specified using the --timezone option of
the mysqld_safe script.
The system_time_zone variable differs from time_zone. Although they might have the same
value, the latter variable is used to initialize the time zone for each client that connects. See
Section 10.6, “MySQL Server Time Zone Support”.
•

table_cache
Command-Line Format

This
documentation
is for an
older version.
If you're

--table_cache=#

This
documentation
is for an
older version.
If you're

Server System Variables

System Variable

Name

table_cache

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 64
Min
Value

1

Max
Value

524288

The number of open tables for all threads. Increasing this value increases the number of file
descriptors that mysqld requires. You can check whether you need to increase the table cache
by checking the Opened_tables status variable. See Section 5.1.6, “Server Status Variables”. If
the value of Opened_tables is large and you do not use FLUSH TABLES often (which just forces
all tables to be closed and reopened), then you should increase the value of the table_cache
variable. For more information about the table cache, see Section 8.4.3.1, “How MySQL Opens and
Closes Tables”.
•

table_lock_wait_timeout

Introduced

5.0.10

Command-Line Format

--table_lock_wait_timeout=#

System Variable

Name

table_lock_wait_timeout

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 50
Min
Value

1

Max
Value

1073741824

Name

table_type

This variable is unused.
•

table_type

System Variable

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

enumeration

This variable is a synonym for storage_engine, which is the preferred name; table_type is
deprecated and is removed in MySQL 5.5.
• thread_cache_size
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Command-Line Format

--thread_cache_size=#

System Variable

Name

thread_cache_size

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

integer

Default 0
Min
Value

0

Max
Value

16384

How many threads the server should cache for reuse. When a client disconnects, the client's
threads are put in the cache if there are fewer than 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 does not provide a notable performance
improvement if you have a good thread implementation. However, if your server sees hundreds of
connections per second you should normally set thread_cache_size high enough so that most
new connections use cached threads. By examining the difference between the Connections and
Threads_created status variables, you can see how efficient the thread cache is. For details, see
Section 5.1.6, “Server Status Variables”.
•

thread_concurrency
Command-Line Format

--thread_concurrency=#

System Variable

Name

thread_concurrency

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

integer

Default 10
Min
Value

1

Max
Value

512

This variable is specific to Solaris systems, for which mysqld invokes the thr_setconcurrency()
with the variable value. This function enables applications to give the threads system a hint about the
desired number of threads that should be run at the same time.
•

thread_stack
Command-Line Format

--thread_stack=#

System Variable

Name

thread_stack

Variable Global
Scope
DynamicNo
Variable

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Permitted Values (32-bit Type
integer
platforms)
Default 196608
Min
Value

131072

Max
Value

4294967295

Block
Size

1024

Permitted Values (64-bit Type
integer
platforms)
Default 262144
Min
Value

131072

Max
Value

18446744073709547520

Block
Size

1024

The stack size for each thread. Many of the limits detected by the crash-me test are dependent on
this value. See Section 8.13.2, “The MySQL Benchmark Suite”. The default of 192KB (256KB for
64-bit systems) is large enough for normal operation. If the thread stack size is too small, it limits
the complexity of the SQL statements that the server can handle, the recursion depth of stored
procedures, and other memory-consuming actions.
•

time_format
This variable is unused.

•

time_zone
System Variable

Name

time_zone

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

string

The current time zone. This variable is used to initialize the time zone for each client that
connects. By default, the initial value of this is 'SYSTEM' (which means, “use the value of
system_time_zone”). The value can be specified explicitly at server startup with the --defaulttime-zone option. See Section 10.6, “MySQL Server Time Zone Support”.
•

timed_mutexes
Introduced

5.0.3

Command-Line Format

--timed_mutexes

System Variable

Name

timed_mutexes

Variable Global
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default OFF

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

This variable controls whether InnoDB mutexes are timed. If this variable is set to 0 or OFF (the
default), mutex timing is disabled. If the variable is set to 1 or ON, mutex timing is enabled. With
timing enabled, the os_wait_times value in the output from SHOW ENGINE INNODB MUTEX
indicates the amount of time (in ms) spent in operating system waits. Otherwise, the value is 0. This
variable was added in MySQL 5.0.3.
•

timestamp

System Variable

Name

timestamp

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

numeric

Set the time for this client. This is used to get the original timestamp if you use the binary log to
restore rows. timestamp_value should be a Unix epoch timestamp (a value like that returned by
UNIX_TIMESTAMP(), not a value in 'YYYY-MM-DD hh:mm:ss' format) or DEFAULT.
Setting timestamp to a constant value causes it to retain that value until it is changed again.
Setting timestamp to DEFAULT causes its value to be the current date and time as of the time it is
accessed.
SET timestamp affects the value returned by NOW() but not by SYSDATE(). This means that
timestamp settings in the binary log have no effect on invocations of SYSDATE(). The server can be
started with the --sysdate-is-now option to cause SYSDATE() to be an alias for NOW(), in which
case SET timestamp affects both functions.
•

tmp_table_size

Command-Line Format

--tmp_table_size=#

System Variable

Name

tmp_table_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (<=
5.0.85)

Permitted Values (>=
5.0.86)

Type

integer

Default 33554432
Min
Value

1024

Max
Value

4294967295

Type

integer

Default 33554432
Min
Value

1024

Max
Value

9223372036854775807

The maximum size of internal in-memory temporary tables. This variable does not apply to usercreated MEMORY tables.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

The actual limit is determined as the minimum of tmp_table_size and max_heap_table_size.
If an in-memory temporary table exceeds the limit, MySQL automatically converts it to an on-disk
MyISAM table. Increase the value of tmp_table_size (and max_heap_table_size if necessary)
if you do many advanced GROUP BY queries and you have lots of memory.
You can compare the number of internal on-disk temporary tables created to the total number of
internal temporary tables created by comparing the values of the Created_tmp_disk_tables and
Created_tmp_tables variables.
See also Section 8.4.4, “Internal Temporary Table Use in MySQL”.
•

tmpdir

Command-Line Format

--tmpdir=dir_name

System Variable

Name

tmpdir

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

directory name

The directory used for temporary files and temporary tables. 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.
The multiple-directory 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 file system or to a directory that is cleared when the server host restarts. A
replication slave needs some of its temporary files to survive a machine restart so that it can replicate
temporary tables or LOAD DATA INFILE operations. If files in the temporary file directory are lost
when the server restarts, replication fails. You can set the slave's temporary directory using the
slave_load_tmpdir variable. In that case, the slave will not use the general tmpdir value and
you can set tmpdir to a nonpermanent location.
•

transaction_alloc_block_size

Command-Line Format

--transaction_alloc_block_size=#

System Variable

Name

transaction_alloc_block_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 8192
Min
Value

1024

Max
Value

4294967295

Block
Size

1024

Permitted Values (64-bit Type
integer
platforms)
Default 8192
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Min
Value

1024

Max
Value

18446744073709547520

Block
Size

1024

The amount in bytes by which to increase a per-transaction memory pool which needs memory. See
the description of transaction_prealloc_size.
•

transaction_prealloc_size

Command-Line Format

--transaction_prealloc_size=#

System Variable

Name

transaction_prealloc_size

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values (32-bit Type
integer
platforms)
Default 4096
Min
Value

1024

Max
Value

4294967295

Block
Size

1024

Permitted Values (64-bit Type
integer
platforms)
Default 4096
Min
Value

1024

Max
Value

18446744073709547520

Block
Size

1024

There is a per-transaction memory pool from which various transaction-related allocations take
memory. The initial size of the pool in bytes is transaction_prealloc_size. For every
allocation that cannot be satisfied from the pool because it has insufficient memory available, the
pool is increased by transaction_alloc_block_size bytes. When the transaction ends, the
pool is truncated to transaction_prealloc_size bytes.
By making transaction_prealloc_size sufficiently large to contain all statements within a
single transaction, you can avoid many malloc() calls.
•

tx_isolation

System Variable

Name

tx_isolation

Variable Global, Session
Scope
DynamicYes
Variable
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

Permitted Values

Type

enumeration

Default REPEATABLE-READ
Valid
READ-UNCOMMITTED
Values READ-COMMITTED
REPEATABLE-READ
SERIALIZABLE
The default transaction isolation level. Defaults to REPEATABLE-READ.
This variable can be set directly, or indirectly using the SET TRANSACTION statement. See
Section 13.3.6, “SET TRANSACTION Syntax”. If you set tx_isolation directly to an isolation level
name that contains a space, the name should be enclosed within quotation marks, with the space
replaced by a dash. For example:
SET tx_isolation = 'READ-COMMITTED';

Any unique prefix of a valid value may be used to set the value of this variable.
The default transaction isolation level can also be set at startup using the --transactionisolation server option.
•

unique_checks
System Variable

Name

unique_checks

Variable Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 1
If set to 1 (the default), uniqueness checks for secondary indexes in InnoDB tables are performed. If
set to 0, storage engines are permitted to assume that duplicate keys are not present in input data.
If you know for certain that your data does not contain uniqueness violations, you can set this to 0 to
speed up large table imports to InnoDB.
Setting this variable to 0 does not require storage engines to ignore duplicate keys. An engine is still
permitted to check for them and issue duplicate-key errors if it detects them.
•

updatable_views_with_limit
Introduced

5.0.2

Command-Line Format

--updatable_views_with_limit=#

System Variable

Name

updatable_views_with_limit

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values

Type

boolean

Default 1
This variable controls whether updates to a view can be made when the view does not contain
all columns of the primary key defined in the underlying table, if the update statement contains a

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server System Variables

LIMIT clause. (Such updates often are generated by GUI tools.) An update is an UPDATE or DELETE
statement. Primary key here means a PRIMARY KEY, or a UNIQUE index in which no column can
contain NULL.
The variable can have two values:
• 1 or YES: Issue a warning only (not an error message). This is the default value.
• 0 or NO: Prohibit the update.
This variable was added in MySQL 5.0.2.
•

version

System Variable

Name

version

Variable Global
Scope
DynamicNo
Variable
The version number for the server. The value might also include a suffix indicating server build or
configuration information. -log indicates that one or more of the general log, slow query log, or
binary log are enabled. -debug indicates that the server was built with debugging support enabled.

System Variable

Name

version

Variable Global
Scope
DynamicNo
Variable
Starting with MySQL 5.0.24, the version number will also indicate whether the server is a standard
release (Community) or Enterprise release (for example, 5.0.28-enterprise-gpl-nt).
•

version_bdb
The BDB storage engine version.

•

version_comment

System Variable

Name

version_comment

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

The configure script has a --with-comment option that permits a comment to be specified when
building MySQL. This variable contains the value of that comment.
For precompiled binaries, this variable will hold the server version and license information. Starting
with MySQL 5.0.24, version_comment will include the full server type and license. For community
users this will appear as MySQL Community Edition - Standard (GPL). For Enterprise
users, the version might be displayed as MySQL Enterprise Server (GPL). The corresponding
license for your MySQL binary is shown in parentheses. For server compiled from source, the default
value will be the same as that for Community releases.
This

This
documentation
• version_compile_machine
is for an
older version.
If you're

documentation
is for an
older version.
If you're

Server System Variables

System Variable

Name

version_compile_machine

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

The type of machine or architecture on which MySQL was built.
•

version_compile_os

System Variable

Name

version_compile_os

Variable Global
Scope
DynamicNo
Variable
Permitted Values

Type

string

The type of operating system on which MySQL was built.
•

wait_timeout

Command-Line Format

--wait_timeout=#

System Variable

Name

wait_timeout

Variable Global, Session
Scope
DynamicYes
Variable
Permitted Values
(Windows)

Type

integer

Default 28800
Min
Value

1

Max
Value

2147483

Permitted Values (Other) Type

integer

Default 28800
Min
Value

1

Max
Value

31536000

The number of seconds the server waits for activity on a noninteractive connection before closing it.
This timeout applies only to TCP/IP and Unix socket file connections, not to connections made using
named pipes, or shared memory.
On thread startup, the session wait_timeout value is initialized from the global wait_timeout
value or from the global interactive_timeout value, depending on the type of client (as
defined by the CLIENT_INTERACTIVE connect option to mysql_real_connect()). See also
interactive_timeout.
• warning_count
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

The number of errors, warnings, and notes that resulted from the last statement that generated
messages. This variable is read only. See Section 13.7.5.37, “SHOW WARNINGS Syntax”.

5.1.5 Using System Variables
The MySQL server maintains many system variables that indicate how it is configured. Section 5.1.4,
“Server System Variables”, describes the meaning of these variables. Each system variable has a
default value. System variables can be set at server startup using options on the command line or in
an option file. Most of them can be changed dynamically while the server is running by means of the
SET statement, which enables you to modify operation of the server without having to stop and restart
it. You can refer to system variable values in expressions.
The server maintains two kinds of system variables. Global variables affect the overall operation of
the server. Session variables affect its operation for individual client connections. A given system
variable can have both a global and a session value. Global and session system variables are related
as follows:
• When the server starts, it initializes all global variables to their default values. These defaults can
be changed by options specified on the command line or in an option file. (See Section 4.2.3,
“Specifying Program Options”.)
• 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 example, the client's SQL mode is controlled by the session sql_mode value, which is
initialized when the client connects to the value of the global sql_mode value.
System variable values can be set globally at server startup by using options on the command line or
in an option file. When you use a startup option to set a variable that takes a numeric value, the value
can be given with a suffix of K, M, or G (either uppercase or lowercase) to indicate a multiplier of 1024,
2
3
1024 or 1024 ; that is, units of kilobytes, megabytes, or gigabytes, respectively. Thus, the following
command starts the server with a query cache size of 16 megabytes and a maximum packet size of
one gigabyte:
mysqld --query_cache_size=16M --max_allowed_packet=1G

Within an option file, those variables are set like this:
[mysqld]
query_cache_size=16M
max_allowed_packet=1G

The lettercase of suffix letters does not matter; 16M and 16m are equivalent, as are 1G and 1g.
If you want to restrict the maximum value to which a system variable can be set at runtime
with the SET statement, you can specify this maximum by using an option of the form
--maximum-var_name=value 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.
Many system variables are dynamic and can be changed while the server runs by using the SET
statement. For a list, see Section 5.1.5.2, “Dynamic System Variables”. To change a system variable
with SET, refer to it as var_name, optionally preceded by a modifier:
• To indicate explicitly that a variable is a global variable, precede its name by GLOBAL or @@global..
The SUPER privilege is required to set global variables.
• To indicate explicitly that a variable is a session variable, precede its name by SESSION,
@@session., or @@. Setting a session variable requires no special privilege, but a client can change
only its own session variables, not those of any other client.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

• LOCAL and @@local. are synonyms for SESSION and @@session..
• If no modifier is present, SET changes the session variable.
A SET statement can contain multiple variable assignments, separated by commas. If you set several
system variables, the most recent GLOBAL or SESSION modifier in the statement is used for following
variables that have no modifier specified.
Examples:
SET
SET
SET
SET
SET

sort_buffer_size=10000;
@@local.sort_buffer_size=10000;
GLOBAL sort_buffer_size=1000000, SESSION sort_buffer_size=1000000;
@@sort_buffer_size=1000000;
@@global.sort_buffer_size=1000000, @@local.sort_buffer_size=1000000;

The @@var_name syntax for system variables is supported for compatibility with some other database
systems.
If you change a session system variable, the value remains in effect until your session ends or until you
change the variable to a different value. The change is not visible to other clients.
If you change a global system variable, the value is remembered and used for new connections until
the server restarts. (To make a global system variable setting permanent, you should set it in an option
file.) The change is visible to any client that accesses that global variable. However, the change affects
the corresponding session variable only for clients that connect after the change. The global variable
change does not affect the session variable for any client that is currently connected (not even that of
the client that issues the SET GLOBAL statement).
To prevent incorrect usage, MySQL produces an error if you use SET GLOBAL with a variable that
can only be used with SET SESSION or if you do not specify GLOBAL (or @@global.) when setting a
global variable.
To set a SESSION variable to the GLOBAL value or a GLOBAL value to the compiled-in MySQL default
value, use the DEFAULT keyword. For example, the following two statements are identical in setting the
session value of max_join_size to the global value:
SET max_join_size=DEFAULT;
SET @@session.max_join_size=@@global.max_join_size;

Not all system variables can be set to DEFAULT. In such cases, use of DEFAULT results in an error.
You can refer to the values of specific global or session system variables in expressions by using one
of the @@-modifiers. For example, you can retrieve values in a SELECT statement like this:
SELECT @@global.sql_mode, @@session.sql_mode, @@sql_mode;

When you refer to a system variable in an expression as @@var_name (that is, when you do not
specify @@global. or @@session.), MySQL returns the session value if it exists and the global value
otherwise. (This differs from SET @@var_name = value, which always refers to the session value.)
Note
Some variables displayed by SHOW VARIABLES may not be available using
SELECT @@var_name syntax; an Unknown system variable occurs.
As a workaround in such cases, you can use SHOW VARIABLES LIKE
'var_name'.
Suffixes for specifying a value multiplier can be used when setting a variable at server startup, but not
to set the value with SET at runtime. On the other hand, with SET you can assign a variable's value
using an expression, which is not true when you set a variable at server startup. For example, the first
of the following lines is legal at server startup, but the second is not:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

shell> mysql --max_allowed_packet=16M
shell> mysql --max_allowed_packet=16*1024*1024

Conversely, the second of the following lines is legal at runtime, but the first is not:
mysql> SET GLOBAL max_allowed_packet=16M;
mysql> SET GLOBAL max_allowed_packet=16*1024*1024;

Note
Some system variables can be enabled with the SET statement by setting
them to ON or 1, or disabled by setting them to OFF or 0. However, to set such
a variable on the command line or in an option file, you must set it to 1 or 0;
setting it to ON or OFF will not work. For example, on the command line, -delay_key_write=1 works but --delay_key_write=ON does not.
To display system variable names and values, use the SHOW VARIABLES statement:
mysql> SHOW VARIABLES;
+--------+--------------------------------------------------------------+
| Variable_name
| Value
|
+--------+--------------------------------------------------------------+
| auto_increment_increment
| 1
|
| auto_increment_offset
| 1
|
| automatic_sp_privileges
| ON
|
| back_log
| 50
|
| basedir
| /
|
| bdb_cache_size
| 8388600
|
| bdb_home
| /var/lib/mysql/
|
| bdb_log_buffer_size
| 32768
|
| bdb_logdir
|
|
| bdb_max_lock
| 10000
|
| bdb_shared_data
| OFF
|
| bdb_tmpdir
| /tmp/
|
| binlog_cache_size
| 32768
|
| bulk_insert_buffer_size
| 8388608
|
| character_set_client
| latin1
|
| character_set_connection
| latin1
|
| character_set_database
| latin1
|
| character_set_results
| latin1
|
| character_set_server
| latin1
|
| character_set_system
| utf8
|
| character_sets_dir
| /usr/share/mysql/charsets/
|
| collation_connection
| latin1_swedish_ci
|
| collation_database
| latin1_swedish_ci
|
| collation_server
| latin1_swedish_ci
|
...
| innodb_additional_mem_pool_size | 1048576
|
| innodb_autoextend_increment
| 8
|
| innodb_buffer_pool_awe_mem_mb
| 0
|
| innodb_buffer_pool_size
| 8388608
|
| innodb_checksums
| ON
|
| innodb_commit_concurrency
| 0
|
| innodb_concurrency_tickets
| 500
|
| innodb_data_file_path
| ibdata1:10M:autoextend
|
| innodb_data_home_dir
|
|
...
| version
| 5.0.19
|
| version_comment
| MySQL Community Edition - (GPL)
|
| version_compile_machine
| i686
|
| version_compile_os
| pc-linux-gnu
|
| wait_timeout
| 28800
|
+--------+--------------------------------------------------------------+

With a LIKE clause, the statement displays only those variables that match the pattern. To obtain a
specific variable name, use a LIKE clause as shown:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

SHOW VARIABLES LIKE 'max_join_size';
SHOW SESSION VARIABLES LIKE 'max_join_size';

To get a list of variables whose name match a pattern, use the “%” wildcard character in a LIKE clause:
SHOW VARIABLES LIKE '%size%';
SHOW GLOBAL VARIABLES LIKE '%size%';

Wildcard characters can be used in any position within the pattern to be matched. Strictly speaking,
because “_” is a wildcard that matches any single character, you should escape it as “\_” to match it
literally. In practice, this is rarely necessary.
For SHOW VARIABLES, if you specify neither GLOBAL nor SESSION, MySQL returns SESSION values.
The reason for requiring the GLOBAL keyword when setting GLOBAL-only variables but not when
retrieving them is to prevent problems in the future. If we were to remove a SESSION variable that has
the same name as a GLOBAL variable, a client with the SUPER privilege might accidentally change the
GLOBAL variable rather than just the SESSION variable for its own connection. If we add a SESSION
variable with the same name as a GLOBAL variable, a client that intends to change the GLOBAL variable
might find only its own SESSION variable changed.

5.1.5.1 Structured System Variables
A structured variable differs from a regular system variable in two respects:
• Its value is a structure with components that specify server parameters considered to be closely
related.
• There might be several instances of a given type of structured variable. Each one has a different
name and refers to a different resource maintained by the server.
MySQL supports one structured variable type, which specifies parameters governing the operation of
key caches. A key cache structured variable has these components:
• key_buffer_size
• key_cache_block_size
• key_cache_division_limit
• key_cache_age_threshold
This section describes the syntax for referring to structured variables. Key cache variables are used
for syntax examples, but specific details about how key caches operate are found elsewhere, in
Section 8.10.1, “The MyISAM Key Cache”.
To refer to a component of a structured variable instance, you can use a compound name in
instance_name.component_name format. Examples:
hot_cache.key_buffer_size
hot_cache.key_cache_block_size
cold_cache.key_cache_block_size

For each structured system variable, an instance with the name of default is always predefined. If
you refer to a component of a structured variable without any instance name, the default instance
is used. Thus, default.key_buffer_size and key_buffer_size both refer to the same system
variable.
Structured variable instances and components follow these naming rules:
• For a given type of structured variable, each instance must have a name that is unique within
variables of that type. However, instance names need not be unique across structured variable
types. For example, each structured variable has an instance named default, so default is not
unique across variable types.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

• The names of the components of each structured variable type must be unique across all system
variable names. If this were not true (that is, if two different types of structured variables could
share component member names), it would not be clear which default structured variable to use for
references to member names that are not qualified by an instance name.
• If a structured variable instance name is not legal as an unquoted identifier, refer to it as a quoted
identifier using backticks. For example, hot-cache is not legal, but `hot-cache` is.
• global, session, and local are not legal instance names. This avoids a conflict with notation
such as @@global.var_name for referring to nonstructured system variables.
Currently, the first two rules have no possibility of being violated because the only structured variable
type is the one for key caches. These rules will assume greater significance if some other type of
structured variable is created in the future.
With one exception, you can refer to structured variable components using compound names in any
context where simple variable names can occur. For example, you can assign a value to a structured
variable using a command-line option:
shell> mysqld --hot_cache.key_buffer_size=64K

In an option file, use this syntax:
[mysqld]
hot_cache.key_buffer_size=64K

If you start the server with this option, it creates a key cache named hot_cache with a size of 64KB in
addition to the default key cache that has a default size of 8MB.
Suppose that you start the server as follows:
shell> mysqld --key_buffer_size=256K \
--extra_cache.key_buffer_size=128K \
--extra_cache.key_cache_block_size=2048

In this case, the server sets the size of the default key cache to 256KB. (You could also have written
--default.key_buffer_size=256K.) In addition, the server creates a second key cache named
extra_cache that has a size of 128KB, with the size of block buffers for caching table index blocks
set to 2048 bytes.
The following example starts the server with three different key caches having sizes in a 3:1:1 ratio:
shell> mysqld --key_buffer_size=6M \
--hot_cache.key_buffer_size=2M \
--cold_cache.key_buffer_size=2M

Structured variable values may be set and retrieved at runtime as well. For example, to set a key cache
named hot_cache to a size of 10MB, use either of these statements:
mysql> SET GLOBAL hot_cache.key_buffer_size = 10*1024*1024;
mysql> SET @@global.hot_cache.key_buffer_size = 10*1024*1024;

To retrieve the cache size, do this:
mysql> SELECT @@global.hot_cache.key_buffer_size;

However, the following statement does not work. The variable is not interpreted as a compound name,
but as a simple string for a LIKE pattern-matching operation:
mysql> SHOW GLOBAL VARIABLES LIKE 'hot_cache.key_buffer_size';

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using System Variables

This is the exception to being able to use structured variable names anywhere a simple variable name
may occur.

5.1.5.2 Dynamic System Variables
Many server system variables are dynamic and can be set at runtime using SET GLOBAL or SET
SESSION. You can also obtain their values using SELECT. See Section 5.1.5, “Using 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. The table also lists session options that
can be set with the SET statement. Section 5.1.4, “Server System Variables”, discusses these options.
Variables that have a type of “string” take a string value. Variables that have a type of “numeric” take
a numeric value. Variables that have a type of “boolean” can be set to 0, 1, ON or OFF. (If you set
them on the command line or in an option file, use the numeric values.) 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 enumerated system
variables, the first enumeration value corresponds to 0. This differs from ENUM columns, for which the
first enumeration value corresponds to 1.
Table 5.3 Dynamic Variable Summary
Variable Name

Variable Type

auto_increment_increment

integer

GLOBAL | SESSION

auto_increment_offset

integer

GLOBAL | SESSION

autocommit

boolean

SESSION

automatic_sp_privileges

boolean

GLOBAL

big_tables

boolean

SESSION

binlog_cache_size

integer

GLOBAL

bulk_insert_buffer_size

integer

GLOBAL | SESSION

character_set_client

string

GLOBAL | SESSION

character_set_connection

string

GLOBAL | SESSION

character_set_database

string

GLOBAL | SESSION

character_set_filesystem

string

GLOBAL | SESSION

character_set_results

string

GLOBAL | SESSION

character_set_server

string

GLOBAL | SESSION

collation_connection

string

GLOBAL | SESSION

collation_database

string

GLOBAL | SESSION

collation_server

string

GLOBAL | SESSION

completion_type

integer

GLOBAL | SESSION

concurrent_insert

integer

GLOBAL

connect_timeout

integer

GLOBAL

debug

string

GLOBAL | SESSION

storage_engine

enumeration

GLOBAL | SESSION

default_week_format

integer

GLOBAL | SESSION

delay_key_write

enumeration

GLOBAL

delayed_insert_limit

integer

GLOBAL

delayed_insert_timeout

integer

GLOBAL

delayed_queue_size

integer

GLOBAL

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Using System Variables

Variable Name

Variable Type

div_precision_increment

integer

GLOBAL | SESSION

engine_condition_pushdown

boolean

GLOBAL | SESSION

expire_logs_days

integer

GLOBAL

flush

boolean

GLOBAL

flush_time

integer

GLOBAL

foreign_key_checks

boolean

SESSION

ft_boolean_syntax

string

GLOBAL

group_concat_max_len

integer

GLOBAL | SESSION

identity

integer

SESSION

init_connect

string

GLOBAL

init_slave

string

GLOBAL

innodb_autoextend_increment

integer

GLOBAL

innodb_commit_concurrency

integer

GLOBAL

innodb_concurrency_tickets

integer

GLOBAL

innodb_fast_shutdown

integer

GLOBAL

innodb_flush_log_at_trx_commit

enumeration

GLOBAL

innodb_max_dirty_pages_pct

numeric

GLOBAL

innodb_max_purge_lag

integer

GLOBAL

innodb_support_xa

boolean

GLOBAL | SESSION

innodb_sync_spin_loops

integer

GLOBAL

innodb_table_locks

boolean

GLOBAL | SESSION

innodb_thread_concurrency

integer

GLOBAL

innodb_thread_sleep_delay

integer

GLOBAL

innodb_use_legacy_cardinality_algorithm
boolean

Variable Scope

GLOBAL

insert_id

integer

SESSION

interactive_timeout

integer

GLOBAL | SESSION

join_buffer_size

integer

GLOBAL | SESSION

keep_files_on_create

boolean

GLOBAL | SESSION

key_buffer_size

integer

GLOBAL

key_cache_age_threshold

integer

GLOBAL

key_cache_block_size

integer

GLOBAL

key_cache_division_limit

integer

GLOBAL

last_insert_id

integer

SESSION

lc_time_names

string

local_infile

boolean

GLOBAL

log_bin_trust_function_creators

boolean

GLOBAL

log_bin_trust_routine_creators

boolean

GLOBAL

log_queries_not_using_indexes

boolean

GLOBAL

log_warnings

integer

GLOBAL | SESSION

long_query_time

numeric

GLOBAL | SESSION

low_priority_updates

boolean

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Using System Variables

Variable Name

Variable Type

max_allowed_packet

integer

GLOBAL | SESSION

max_binlog_cache_size

integer

GLOBAL

max_binlog_size

integer

GLOBAL

max_connect_errors

integer

GLOBAL

max_connections

integer

GLOBAL

max_delayed_threads

integer

GLOBAL | SESSION

max_error_count

integer

GLOBAL | SESSION

max_heap_table_size

integer

GLOBAL | SESSION

max_insert_delayed_threads

integer

GLOBAL | SESSION

max_join_size

integer

GLOBAL | SESSION

max_length_for_sort_data

integer

GLOBAL | SESSION

max_prepared_stmt_count

integer

GLOBAL

max_relay_log_size

integer

GLOBAL

max_seeks_for_key

integer

GLOBAL | SESSION

max_sort_length

integer

GLOBAL | SESSION

max_sp_recursion_depth

integer

GLOBAL | SESSION

max_tmp_tables

integer

GLOBAL | SESSION

max_user_connections

integer

GLOBAL | SESSION

max_write_lock_count

integer

GLOBAL

multi_range_count

integer

GLOBAL | SESSION

myisam_data_pointer_size

integer

GLOBAL

myisam_max_sort_file_size

integer

GLOBAL

myisam_repair_threads

integer

GLOBAL | SESSION

myisam_sort_buffer_size

integer

GLOBAL | SESSION

myisam_stats_method

enumeration

GLOBAL | SESSION

ndb_autoincrement_prefetch_sz

integer

GLOBAL | SESSION

ndb_cache_check_time

integer

GLOBAL

ndb_force_send

boolean

GLOBAL | SESSION

ndb_index_stat_cache_entries

integer

GLOBAL | SESSION

ndb_index_stat_enable

boolean

GLOBAL | SESSION

ndb_index_stat_update_freq

integer

GLOBAL | SESSION

ndb_use_exact_count

boolean

GLOBAL | SESSION

ndb_use_transactions

boolean

GLOBAL | SESSION

net_buffer_length

integer

GLOBAL | SESSION

net_read_timeout

integer

GLOBAL | SESSION

net_retry_count

integer

GLOBAL | SESSION

net_write_timeout

integer

GLOBAL | SESSION

new

boolean

GLOBAL | SESSION

old_passwords

boolean

GLOBAL | SESSION

optimizer_prune_level

boolean

GLOBAL | SESSION

optimizer_search_depth

integer

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Using System Variables

Variable Name

Variable Type

preload_buffer_size

integer

GLOBAL | SESSION

profiling

boolean

SESSION

profiling_history_size

integer

GLOBAL | SESSION

pseudo_thread_id

integer

SESSION

query_alloc_block_size

integer

GLOBAL | SESSION

query_cache_limit

integer

GLOBAL

query_cache_min_res_unit

integer

GLOBAL

query_cache_size

integer

GLOBAL

query_cache_type

enumeration

GLOBAL | SESSION

query_cache_wlock_invalidate

boolean

GLOBAL | SESSION

query_prealloc_size

integer

GLOBAL | SESSION

rand_seed1

integer

SESSION

rand_seed2

integer

SESSION

range_alloc_block_size

integer

GLOBAL | SESSION

read_buffer_size

integer

GLOBAL | SESSION

read_only

boolean

GLOBAL

read_rnd_buffer_size

integer

GLOBAL | SESSION

relay_log_purge

boolean

GLOBAL

rpl_recovery_rank

integer

GLOBAL

secure_auth

boolean

GLOBAL

server_id

integer

GLOBAL

slave_compressed_protocol

boolean

GLOBAL

slave_net_timeout

integer

GLOBAL

slave_transaction_retries

integer

GLOBAL

slow_launch_time

integer

GLOBAL

sort_buffer_size

integer

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

integer

GLOBAL | SESSION

sql_mode

set

GLOBAL | SESSION

sql_notes

boolean

SESSION

sql_quote_show_create

boolean

SESSION

sql_safe_updates

boolean

SESSION

sql_select_limit

integer

GLOBAL | SESSION

sql_slave_skip_counter

integer

GLOBAL

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Variable Scope

sql_warnings

boolean

storage_engine

enumeration

sync_binlog

integer

GLOBAL

sync_frm

boolean

GLOBAL

table_cache

integer

GLOBAL

table_lock_wait_timeout

integer

GLOBAL

table_type

enumeration

thread_cache_size

integer

time_zone

string

timed_mutexes

boolean

GLOBAL

timestamp

numeric

SESSION

tmp_table_size

integer

GLOBAL | SESSION

transaction_alloc_block_size

integer

GLOBAL | SESSION

transaction_prealloc_size

integer

GLOBAL | SESSION

tx_isolation

enumeration

GLOBAL | SESSION

unique_checks

boolean

SESSION

updatable_views_with_limit

boolean

GLOBAL | SESSION

wait_timeout

integer

GLOBAL | SESSION

SESSION
GLOBAL | SESSION

GLOBAL | SESSION
GLOBAL
GLOBAL | SESSION

5.1.6 Server Status Variables
The MySQL server maintains many status variables that provide information about its operation.
You can view these variables and their values by using the SHOW [GLOBAL | SESSION] STATUS
statement (see Section 13.7.5.32, “SHOW STATUS Syntax”). The optional GLOBAL keyword
aggregates the values over all connections, and SESSION shows the values for the current connection.
mysql> SHOW GLOBAL 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
| 3
|
| Created_tmp_tables
| 2
|
...
| Threads_created
| 217
|
| Threads_running
| 88
|
| Uptime
| 1389872
|
+-----------------------------------+------------+

Note
Before MySQL 5.0.2, SHOW STATUS returned global status values. Because the
default as of 5.0.2 is to return session values, this is incompatible with previous
versions. To issue a SHOW STATUS statement that will retrieve global status
values for all versions of MySQL, write it like this:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

SHOW /*!50002 GLOBAL */ STATUS;

Several status variables provide statement counts. To determine the number of statements executed,
use these relationships:
SUM(Com_xxx) + Qcache_hits
= Questions + statements executed within stored programs
= Queries

Many status variables are reset to 0 by the FLUSH STATUS statement.
The following table lists all available server status variables:
Table 5.4 Status Variable Summary
Variable Name

Variable Type

Aborted_clients

integer

GLOBAL

Aborted_connects

integer

GLOBAL

Binlog_cache_disk_use

integer

GLOBAL

Binlog_cache_use

integer

GLOBAL

Bytes_received

integer

GLOBAL | SESSION

Bytes_sent

integer

GLOBAL | SESSION

Com_admin_commands

integer

GLOBAL | SESSION

Com_alter_db

integer

GLOBAL | SESSION

Com_alter_event

integer

GLOBAL | SESSION

Com_alter_table

integer

GLOBAL | SESSION

Com_analyze

integer

GLOBAL | SESSION

Com_backup_table

integer

GLOBAL | SESSION

Com_begin

integer

GLOBAL | SESSION

Com_call_procedure

integer

GLOBAL | SESSION

Com_change_db

integer

GLOBAL | SESSION

Com_change_master

integer

GLOBAL | SESSION

Com_check

integer

GLOBAL | SESSION

Com_checksum

integer

GLOBAL | SESSION

Com_commit

integer

GLOBAL | SESSION

Com_create_db

integer

GLOBAL | SESSION

Com_create_event

integer

GLOBAL | SESSION

Com_create_function

integer

GLOBAL | SESSION

Com_create_index

integer

GLOBAL | SESSION

Com_create_table

integer

GLOBAL | SESSION

Com_create_user

integer

GLOBAL | SESSION

Com_dealloc_sql

integer

GLOBAL | SESSION

Com_delete

integer

GLOBAL | SESSION

Com_delete_multi

integer

GLOBAL | SESSION

Com_do

integer

GLOBAL | SESSION

Com_drop_db

integer

GLOBAL | SESSION

Com_drop_event

integer

GLOBAL | SESSION

Com_drop_function

integer

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Com_drop_index

integer

GLOBAL | SESSION

Com_drop_table

integer

GLOBAL | SESSION

Com_drop_user

integer

GLOBAL | SESSION

Com_execute_sql

integer

GLOBAL | SESSION

Com_flush

integer

GLOBAL | SESSION

Com_grant

integer

GLOBAL | SESSION

Com_ha_close

integer

GLOBAL | SESSION

Com_ha_open

integer

GLOBAL | SESSION

Com_ha_read

integer

GLOBAL | SESSION

Com_help

integer

GLOBAL | SESSION

Com_insert

integer

GLOBAL | SESSION

Com_insert_select

integer

GLOBAL | SESSION

Com_kill

integer

GLOBAL | SESSION

Com_load

integer

GLOBAL | SESSION

Com_lock_tables

integer

GLOBAL | SESSION

Com_optimize

integer

GLOBAL | SESSION

Com_preload_keys

integer

GLOBAL | SESSION

Com_prepare_sql

integer

GLOBAL | SESSION

Com_purge

integer

GLOBAL | SESSION

Com_purge_before_date

integer

GLOBAL | SESSION

Com_rename_table

integer

GLOBAL | SESSION

Com_repair

integer

GLOBAL | SESSION

Com_replace

integer

GLOBAL | SESSION

Com_replace_select

integer

GLOBAL | SESSION

Com_reset

integer

GLOBAL | SESSION

Com_restore_table

integer

GLOBAL | SESSION

Com_revoke

integer

GLOBAL | SESSION

Com_revoke_all

integer

GLOBAL | SESSION

Com_rollback

integer

GLOBAL | SESSION

Com_savepoint

integer

GLOBAL | SESSION

Com_select

integer

GLOBAL | SESSION

Com_set_option

integer

GLOBAL | SESSION

Com_show_binlog_events

integer

GLOBAL | SESSION

Com_show_binlogs

integer

GLOBAL | SESSION

Com_show_charsets

integer

GLOBAL | SESSION

Com_show_collations

integer

GLOBAL | SESSION

Com_show_column_types

integer

GLOBAL | SESSION

Com_show_create_db

integer

GLOBAL | SESSION

Com_show_create_event

integer

GLOBAL | SESSION

Com_show_create_table

integer

GLOBAL | SESSION

Com_show_databases

integer

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Com_show_engine_logs

integer

GLOBAL | SESSION

Com_show_engine_mutex

integer

GLOBAL | SESSION

Com_show_engine_status

integer

GLOBAL | SESSION

Com_show_errors

integer

GLOBAL | SESSION

Com_show_events

integer

GLOBAL | SESSION

Com_show_fields

integer

GLOBAL | SESSION

Com_show_grants

integer

GLOBAL | SESSION

Com_show_innodb_status

integer

GLOBAL | SESSION

Com_show_keys

integer

GLOBAL | SESSION

Com_show_logs

integer

GLOBAL | SESSION

Com_show_master_status

integer

GLOBAL | SESSION

Com_show_ndb_status

integer

GLOBAL | SESSION

Com_show_new_master

integer

GLOBAL | SESSION

Com_show_open_tables

integer

GLOBAL | SESSION

Com_show_plugins

integer

GLOBAL | SESSION

Com_show_privileges

integer

GLOBAL | SESSION

Com_show_processlist

integer

GLOBAL | SESSION

Com_show_slave_hosts

integer

GLOBAL | SESSION

Com_show_slave_status

integer

GLOBAL | SESSION

Com_show_status

integer

GLOBAL | SESSION

Com_show_storage_engines

integer

GLOBAL | SESSION

Com_show_tables

integer

GLOBAL | SESSION

Com_show_triggers

integer

GLOBAL | SESSION

Com_show_variables

integer

GLOBAL | SESSION

Com_show_warnings

integer

GLOBAL | SESSION

Com_slave_start

integer

GLOBAL | SESSION

Com_slave_stop

integer

GLOBAL | SESSION

Com_stmt_close

integer

GLOBAL | SESSION

Com_stmt_execute

integer

GLOBAL | SESSION

Com_stmt_fetch

integer

GLOBAL | SESSION

Com_stmt_prepare

integer

GLOBAL | SESSION

Com_stmt_reset

integer

GLOBAL | SESSION

Com_stmt_send_long_data

integer

GLOBAL | SESSION

Com_truncate

integer

GLOBAL | SESSION

Com_unlock_tables

integer

GLOBAL | SESSION

Com_update

integer

GLOBAL | SESSION

Com_update_multi

integer

GLOBAL | SESSION

Com_xa_commit

integer

GLOBAL | SESSION

Com_xa_end

integer

GLOBAL | SESSION

Com_xa_prepare

integer

GLOBAL | SESSION

Com_xa_recover

integer

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Com_xa_rollback

integer

GLOBAL | SESSION

Com_xa_start

integer

GLOBAL | SESSION

Compression

integer

SESSION

Connections

integer

GLOBAL

Created_tmp_disk_tables

integer

GLOBAL | SESSION

Created_tmp_files

integer

GLOBAL

Created_tmp_tables

integer

GLOBAL | SESSION

Delayed_errors

integer

GLOBAL

Delayed_insert_threads

integer

GLOBAL

Delayed_writes

integer

GLOBAL

Flush_commands

integer

GLOBAL

Handler_commit

integer

GLOBAL | SESSION

Handler_delete

integer

GLOBAL | SESSION

Handler_discover

integer

GLOBAL | SESSION

Handler_prepare

integer

GLOBAL | SESSION

Handler_read_first

integer

GLOBAL | SESSION

Handler_read_key

integer

GLOBAL | SESSION

Handler_read_next

integer

GLOBAL | SESSION

Handler_read_prev

integer

GLOBAL | SESSION

Handler_read_rnd

integer

GLOBAL | SESSION

Handler_read_rnd_next

integer

GLOBAL | SESSION

Handler_rollback

integer

GLOBAL | SESSION

Handler_savepoint

integer

GLOBAL | SESSION

Handler_savepoint_rollback

integer

GLOBAL | SESSION

Handler_update

integer

GLOBAL | SESSION

Handler_write

integer

GLOBAL | SESSION

Innodb_buffer_pool_pages_data

integer

GLOBAL

Innodb_buffer_pool_pages_dirty

integer

GLOBAL

Innodb_buffer_pool_pages_flushed

integer

GLOBAL

Innodb_buffer_pool_pages_free

integer

GLOBAL

Innodb_buffer_pool_pages_latched

integer

GLOBAL

Innodb_buffer_pool_pages_misc

integer

GLOBAL

Innodb_buffer_pool_pages_total

integer

GLOBAL

Innodb_buffer_pool_read_ahead_rnd

integer

GLOBAL

Innodb_buffer_pool_read_ahead_seq

integer

GLOBAL

Innodb_buffer_pool_read_requests

integer

GLOBAL

Innodb_buffer_pool_reads

integer

GLOBAL

Innodb_buffer_pool_wait_free

integer

GLOBAL

Innodb_buffer_pool_write_requests

integer

GLOBAL

Innodb_data_fsyncs

integer

GLOBAL

Innodb_data_pending_fsyncs

integer

GLOBAL

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Innodb_data_pending_reads

integer

GLOBAL

Innodb_data_pending_writes

integer

GLOBAL

Innodb_data_read

integer

GLOBAL

Innodb_data_reads

integer

GLOBAL

Innodb_data_writes

integer

GLOBAL

Innodb_data_written

integer

GLOBAL

Innodb_dblwr_pages_written

integer

GLOBAL

Innodb_dblwr_writes

integer

GLOBAL

Innodb_log_waits

integer

GLOBAL

Innodb_log_write_requests

integer

GLOBAL

Innodb_log_writes

integer

GLOBAL

Innodb_os_log_fsyncs

integer

GLOBAL

Innodb_os_log_pending_fsyncs

integer

GLOBAL

Innodb_os_log_pending_writes

integer

GLOBAL

Innodb_os_log_written

integer

GLOBAL

Innodb_page_size

integer

GLOBAL

Innodb_pages_created

integer

GLOBAL

Innodb_pages_read

integer

GLOBAL

Innodb_pages_written

integer

GLOBAL

Innodb_row_lock_current_waits

integer

GLOBAL

Innodb_row_lock_time

integer

GLOBAL

Innodb_row_lock_time_avg

integer

GLOBAL

Innodb_row_lock_time_max

integer

GLOBAL

Innodb_row_lock_waits

integer

GLOBAL

Innodb_rows_deleted

integer

GLOBAL

Innodb_rows_inserted

integer

GLOBAL

Innodb_rows_read

integer

GLOBAL

Innodb_rows_updated

integer

GLOBAL

Key_blocks_not_flushed

integer

GLOBAL

Key_blocks_unused

integer

GLOBAL

Key_blocks_used

integer

GLOBAL

Key_read_requests

integer

GLOBAL

Key_reads

integer

GLOBAL

Key_write_requests

integer

GLOBAL

Key_writes

integer

GLOBAL

Last_query_cost

numeric

SESSION

Max_used_connections

integer

GLOBAL

Ndb_cluster_node_id

integer

GLOBAL | SESSION

Ndb_config_from_host

integer

GLOBAL | SESSION

Ndb_config_from_port

integer

GLOBAL | SESSION

Ndb_cluster_node_id

integer

GLOBAL

This
documentation
is for an
older version.
If you're

Variable Scope

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Not_flushed_delayed_rows

integer

GLOBAL

Open_files

integer

GLOBAL

Open_streams

integer

GLOBAL

Open_tables

integer

GLOBAL | SESSION

Opened_tables

integer

GLOBAL | SESSION

Prepared_stmt_count

integer

GLOBAL

Qcache_free_blocks

integer

GLOBAL

Qcache_free_memory

integer

GLOBAL

Qcache_hits

integer

GLOBAL

Qcache_inserts

integer

GLOBAL

Qcache_lowmem_prunes

integer

GLOBAL

Qcache_not_cached

integer

GLOBAL

Qcache_queries_in_cache

integer

GLOBAL

Qcache_total_blocks

integer

GLOBAL

Queries

integer

GLOBAL | SESSION

Questions

integer

GLOBAL | SESSION

Rpl_status

string

Select_full_join

integer

GLOBAL | SESSION

Select_full_range_join

integer

GLOBAL | SESSION

Select_range

integer

GLOBAL | SESSION

Select_range_check

integer

GLOBAL | SESSION

Select_scan

integer

GLOBAL | SESSION

Slave_open_temp_tables

integer

GLOBAL

Slave_retried_transactions

integer

GLOBAL

Slave_running

boolean

GLOBAL

Slow_launch_threads

integer

GLOBAL | SESSION

Slow_queries

integer

GLOBAL | SESSION

Sort_merge_passes

integer

GLOBAL | SESSION

Sort_range

integer

GLOBAL | SESSION

Sort_rows

integer

GLOBAL | SESSION

Sort_scan

integer

GLOBAL | SESSION

Ssl_accept_renegotiates

integer

GLOBAL

Ssl_accepts

integer

GLOBAL

Ssl_callback_cache_hits

integer

GLOBAL

Ssl_cipher

string

GLOBAL | SESSION

Ssl_cipher_list

string

GLOBAL | SESSION

Ssl_client_connects

integer

GLOBAL

Ssl_connect_renegotiates

integer

GLOBAL

Ssl_ctx_verify_depth

integer

GLOBAL

Ssl_ctx_verify_mode

integer

GLOBAL

Ssl_default_timeout

integer

GLOBAL | SESSION

This
documentation
is for an
older version.
If you're

Variable Scope

GLOBAL

This
documentation
is for an
older version.
If you're

Server Status Variables

Variable Name

Variable Type

Variable Scope

Ssl_finished_accepts

integer

GLOBAL

Ssl_finished_connects

integer

GLOBAL

Ssl_session_cache_hits

integer

GLOBAL

Ssl_session_cache_misses

integer

GLOBAL

Ssl_session_cache_mode

string

GLOBAL

Ssl_session_cache_overflows

integer

GLOBAL

Ssl_session_cache_size

integer

GLOBAL

Ssl_session_cache_timeouts

integer

GLOBAL

Ssl_sessions_reused

integer

GLOBAL | SESSION

Ssl_used_session_cache_entries

integer

GLOBAL

Ssl_verify_depth

integer

GLOBAL | SESSION

Ssl_verify_mode

integer

GLOBAL | SESSION

Ssl_version

string

GLOBAL | SESSION

Table_locks_immediate

integer

GLOBAL

Table_locks_waited

integer

GLOBAL

Tc_log_max_pages_used

integer

GLOBAL

Tc_log_page_size

integer

GLOBAL

Tc_log_page_waits

integer

GLOBAL

Threads_cached

integer

GLOBAL

Threads_connected

integer

GLOBAL

Threads_created

integer

GLOBAL

Threads_running

integer

GLOBAL

Uptime

integer

GLOBAL

Uptime_since_flush_status

integer

GLOBAL

The status variables have the following meanings. For meanings of status variables specific to MySQL
Cluster, see MySQL Cluster Status Variables.
• Aborted_clients
The number of connections that were aborted because the client died without closing the connection
properly. See Section B.5.2.11, “Communication Errors and Aborted Connections”.
• Aborted_connects
The number of failed attempts to connect to the MySQL server. See Section B.5.2.11,
“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.
• Binlog_cache_use
The number of transactions that used the temporary binary log cache.
• Bytes_received
The number of bytes received from all clients.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

• Bytes_sent
The number of bytes sent to all clients.
• Com_xxx
The Com_xxx statement counter variables indicate the number of times each xxx statement has
been executed. There is one status variable for each type of statement. For example, Com_delete
and Com_update count DELETE and UPDATE statements, respectively. Com_delete_multi and
Com_update_multi are similar but apply to DELETE and UPDATE statements that use multipletable syntax.
If a query result is returned from query cache, the server increments the Qcache_hits status
variable, not Com_select. See Section 8.10.3.4, “Query Cache Status and Maintenance”.
The discussion at the beginning of this section indicates how to relate these statement-counting
status variables to other such variables.
All of the Com_stmt_xxx variables are increased even if a prepared statement argument is
unknown or an error occurred during execution. In other words, their values correspond to the
number of requests issued, not to the number of requests successfully completed.
The Com_stmt_xxx status variables were added in 5.0.8:
• Com_stmt_prepare
• Com_stmt_execute
• Com_stmt_fetch
• Com_stmt_send_long_data
• Com_stmt_reset
• Com_stmt_close
Those variables stand for prepared statement commands. Their names refer to the COM_xxx
command set used in the network layer. In other words, their values increase whenever prepared
statement API calls such as mysql_stmt_prepare(), mysql_stmt_execute(), and so forth
are executed. However, Com_stmt_prepare, Com_stmt_execute and Com_stmt_close
also increase for PREPARE, EXECUTE, or DEALLOCATE PREPARE, respectively. Additionally, the
values of the older statement counter variables Com_prepare_sql, Com_execute_sql, and
Com_dealloc_sql increase for the PREPARE, EXECUTE, and DEALLOCATE PREPARE statements.
Com_stmt_fetch stands for the total number of network round-trips issued when fetching from
cursors.
• Compression
Whether the client connection uses compression in the client/server protocol. Added in MySQL
5.0.16.
• Connections
The number of connection attempts (successful or not) to the MySQL server.
• Created_tmp_disk_tables
The number of internal on-disk temporary tables created by the server while executing statements.
If an internal temporary table is created initially as an in-memory table but becomes too large,
MySQL automatically converts it to an on-disk table. The maximum size for in-memory temporary
tables is the minimum of the tmp_table_size and max_heap_table_size values. If

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

Created_tmp_disk_tables is large, you may want to increase the tmp_table_size or
max_heap_table_size value to lessen the likelihood that internal temporary tables in memory will
be converted to on-disk tables.
You can compare the number of internal on-disk temporary tables created to the total number of
internal temporary tables created by comparing the values of the Created_tmp_disk_tables and
Created_tmp_tables variables.
See also Section 8.4.4, “Internal Temporary Table Use in MySQL”.
• Created_tmp_files
How many temporary files mysqld has created.
• Created_tmp_tables
The number of internal temporary tables created by the server while executing statements.
You can compare the number of internal on-disk temporary tables created to the total number of
internal temporary tables created by comparing the values of the Created_tmp_disk_tables and
Created_tmp_tables variables.
See also Section 8.4.4, “Internal Temporary Table Use in MySQL”.
• Delayed_errors
The number of rows written with INSERT DELAYED for which some error occurred (probably
duplicate 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 times the server flushes tables, whether because a user executed a FLUSH TABLES
statement or due to internal server operation. It is also incremented by receipt of a COM_REFRESH
packet. This is in contrast to Com_flush, which indicates how many FLUSH statements have been
executed, whether FLUSH TABLES, FLUSH LOGS, and so forth.
• Handler_commit
The number of internal COMMIT statements.
• Handler_delete
The number of times that rows have been deleted from tables.
• Handler_prepare
A counter for the prepare phase of two-phase commit operations. Added in MySQL 5.0.3.
• Handler_read_first
The number of times the first entry in an index was read. If this value is high, it suggests that the
server is doing a lot of full index scans; for example, SELECT col1 FROM foo, assuming that col1
is indexed.
• Handler_read_key

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The number of requests to read a row based on a key. If this value is high, it is a good indication that
your tables are properly indexed for your queries.
• Handler_read_next
The number of requests to read the next row in key order. This value is 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.
• Handler_read_rnd
The number of requests to read a row based on a fixed position. This value is 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 entire tables or you have joins that do not use keys properly.
• Handler_read_rnd_next
The number of requests to read the next row in the data file. This value is 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 requests for a storage engine to perform a rollback operation.
• Handler_savepoint
The number of requests for a storage engine to place a savepoint. Added in MySQL 5.0.3.
• Handler_savepoint_rollback
The number of requests for a storage engine to roll back to a savepoint. Added in MySQL 5.0.3.
• 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.
• Innodb_buffer_pool_pages_data
The number of pages containing data (dirty or clean). Added in MySQL 5.0.2.
• Innodb_buffer_pool_pages_dirty
The number of pages currently dirty. Added in MySQL 5.0.2.
• Innodb_buffer_pool_pages_flushed
The number of buffer pool page-flush requests. Added in MySQL 5.0.2.
• Innodb_buffer_pool_pages_free
The number of free pages. Added in MySQL 5.0.2.
• Innodb_buffer_pool_pages_latched

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The number of latched pages in InnoDB buffer pool. These are pages currently being read or written
or that cannot be flushed or removed for some other reason. Added in MySQL 5.0.2. Calculation of
this variable is expensive, so as of MySQL 5.0.68, it is available only when the UNIV_DEBUG system
is defined at server build time.
• Innodb_buffer_pool_pages_misc
The number of pages that are busy because they have been allocated for administrative
overhead such as row locks or the adaptive hash index. This value can also be calculated
as Innodb_buffer_pool_pages_total − Innodb_buffer_pool_pages_free −
Innodb_buffer_pool_pages_data. Added in MySQL 5.0.2.
• Innodb_buffer_pool_pages_total
The total size of buffer pool, in pages. Added in MySQL 5.0.2.
• Innodb_buffer_pool_read_ahead_rnd
The number of “random” read-aheads initiated by InnoDB. This happens when a query scans a
large portion of a table but in random order. Added in MySQL 5.0.2.
• Innodb_buffer_pool_read_ahead_seq
The number of sequential read-aheads initiated by InnoDB. This happens when InnoDB does a
sequential full table scan. Added in MySQL 5.0.2.
• Innodb_buffer_pool_read_requests
The number of logical read requests. Added in MySQL 5.0.2.
• Innodb_buffer_pool_reads
The number of logical reads that InnoDB could not satisfy from the buffer pool, and had to read
directly from the disk.
• Innodb_buffer_pool_wait_free
Normally, writes to the InnoDB buffer pool happen in the background. However, if it is necessary
to read or create a page and no clean pages are available, it is also necessary to wait for pages to
be flushed first. This counter counts instances of these waits. If the buffer pool size has been set
properly, this value should be small. Added in MySQL 5.0.2.
• Innodb_buffer_pool_write_requests
The number writes done to the InnoDB buffer pool. Added in MySQL 5.0.2.
• Innodb_data_fsyncs
The number of fsync() operations so far. Added in MySQL 5.0.2.
• Innodb_data_pending_fsyncs
The current number of pending fsync() operations. Added in MySQL 5.0.2.
• Innodb_data_pending_reads
The current number of pending reads. Added in MySQL 5.0.2.
• Innodb_data_pending_writes
The current number of pending writes. Added in MySQL 5.0.2.
• Innodb_data_read

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The amount of data read since the server was started. Added in MySQL 5.0.2.
• Innodb_data_reads
The total number of data reads. Added in MySQL 5.0.2.
• Innodb_data_writes
The total number of data writes. Added in MySQL 5.0.2.
• Innodb_data_written
The amount of data written so far, in bytes. Added in MySQL 5.0.2.
• Innodb_dblwr_pages_written
The number of pages that have been written for doublewrite operations. Added in MySQL 5.0.2. See
Section 14.2.11.1, “InnoDB Disk I/O”.
• Innodb_dblwr_writes
The number of doublewrite operations that have been performed. Added in MySQL 5.0.2. See
Section 14.2.11.1, “InnoDB Disk I/O”.
• Innodb_log_waits
The number of times that the log buffer was too small and a wait was required for it to be flushed
before continuing. Added in MySQL 5.0.2.
• Innodb_log_write_requests
The number of log write requests. Added in MySQL 5.0.2.
• Innodb_log_writes
The number of physical writes to the log file. Added in MySQL 5.0.2.
• Innodb_os_log_fsyncs
The number of fsync() writes done to the log file. Added in MySQL 5.0.2.
• Innodb_os_log_pending_fsyncs
The number of pending log file fsync() operations. Added in MySQL 5.0.2.
• Innodb_os_log_pending_writes
The number of pending log file writes. Added in MySQL 5.0.2.
• Innodb_os_log_written
The number of bytes written to the log file. Added in MySQL 5.0.2.
• Innodb_page_size
The compiled-in InnoDB page size (default 16KB). Many values are counted in pages; the page size
permits them to be easily converted to bytes. Added in MySQL 5.0.2.
• Innodb_pages_created
The number of pages created. Added in MySQL 5.0.2.
• Innodb_pages_read

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The number of pages read. Added in MySQL 5.0.2.
• Innodb_pages_written
The number of pages written. Added in MySQL 5.0.2.
• Innodb_row_lock_current_waits
The number of row locks currently being waited for. Added in MySQL 5.0.3.
• Innodb_row_lock_time
The total time spent in acquiring row locks, in milliseconds. Added in MySQL 5.0.3.
• Innodb_row_lock_time_avg
The average time to acquire a row lock, in milliseconds. Added in MySQL 5.0.3.
• Innodb_row_lock_time_max
The maximum time to acquire a row lock, in milliseconds. Added in MySQL 5.0.3.
• Innodb_row_lock_waits
The number of times a row lock had to be waited for. Added in MySQL 5.0.3.
• Innodb_rows_deleted
The number of rows deleted from InnoDB tables. Added in MySQL 5.0.2.
• Innodb_rows_inserted
The number of rows inserted into InnoDB tables. Added in MySQL 5.0.2.
• Innodb_rows_read
The number of rows read from InnoDB tables. Added in MySQL 5.0.2.
• Innodb_rows_updated
The number of rows updated in InnoDB tables. Added in MySQL 5.0.2.
• Key_blocks_not_flushed
The number of key blocks in the key cache that have changed but have not yet been flushed to disk.
• Key_blocks_unused
The number of unused 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.1.4, “Server System
Variables”.
• Key_blocks_used
The number of used blocks in the key cache. This value is a high-water mark that indicates the
maximum number of blocks that have ever been in use at one time.
• Key_read_requests
The number of requests to read a key block from the cache.
• Key_reads
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The number of physical reads of a key block from disk. If Key_reads is large, then your
key_buffer_size value is probably too small. The cache miss rate can be calculated as
Key_reads/Key_read_requests.
• Key_write_requests
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. This is useful for
comparing the cost of different query plans for the same query. The default value of 0 means that no
query has been compiled yet. This variable was added in MySQL 5.0.1, with a default value of -1. In
MySQL 5.0.7, the default was changed to 0; also in version 5.0.7, the scope of Last_query_cost
was changed to session rather than global.
The Last_query_cost value can be computed accurately only for simple “flat” queries, not
complex queries such as those with subqueries or UNION. For the latter, the value is set to 0.
Prior to MySQL 5.0.16, this variable was not updated for queries served from the query cache.
• 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 DELAYED queues.
• Open_files
The number of files that are open. This count includes regular files opened by the server. It does
not include other types of files such as sockets or pipes. Also, the count does not include files that
storage engines open using their own internal functions rather than asking the server level to do so.
• 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, your table_cache value
is probably too small.
• Prepared_stmt_count
The current number of prepared statements. (The maximum number of statements is given by the
max_prepared_stmt_count system variable.) This variable was added in MySQL 5.0.32.
• Qcache_free_blocks
The number of free memory blocks in the query cache.
• Qcache_free_memory

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

The amount of free memory for the query cache.
• Qcache_hits
The number of query cache hits.
The discussion at the beginning of this section indicates how to relate this statement-counting status
variable to other such variables.
• Qcache_inserts
The number of queries added to the query cache.
• Qcache_lowmem_prunes
The number of queries that were deleted from the query cache because of low memory.
• Qcache_not_cached
The number of noncached queries (not cacheable, or not cached due to the query_cache_type
setting).
• Qcache_queries_in_cache
The number of queries registered in the query cache.
• Qcache_total_blocks
The total number of blocks in the query cache.
• Queries
The number of statements executed by the server. This variable includes statements executed within
stored programs, unlike the Questions variable. It does not count COM_PING or COM_STATISTICS
commands. This variable was added in MySQL 5.0.76.
The discussion at the beginning of this section indicates how to relate this statement-counting status
variable to other such variables.
• Questions
The number of statements executed by the server. As of MySQL 5.0.72, this includes only
statements sent to the server by clients and no longer includes statements executed within stored
programs, unlike the Queries variable. This variable does not count COM_PING, COM_STATISTICS,
COM_STMT_PREPARE, COM_STMT_CLOSE, or COM_STMT_RESET commands.
The discussion at the beginning of this section indicates how to relate this statement-counting status
variable to other such variables.
• Rpl_status
The status of fail-safe replication (not implemented). This variable is unused and is removed in
MySQL 5.6.
• Select_full_join
The number of joins that perform table scans because they do not use indexes. If this value is not 0,
you should carefully check the indexes of your tables.
• Select_full_range_join
The number of joins that used a range search on a reference table.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

• Select_range
The number of joins that used ranges on the first table. This is normally not a critical issue even if the
value is quite large.
• 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.
• Select_scan
The number of joins that did a full scan of the first table.
• Slave_open_temp_tables
The number of temporary tables that the slave SQL thread currently has open. If the value is greater
than zero, it is not safe to shut down the slave; see Section 16.4.1.16, “Replication and Temporary
Tables”.
• Slave_retried_transactions
The total number of times since startup that the replication slave SQL thread has retried transactions.
This variable was added in version 5.0.4.
• Slave_running
This is ON if this server is a replication slave that is connected to a replication master, and both the I/
O and SQL threads are running; otherwise, it is OFF.
• Slow_launch_threads
The number of threads that have taken more than slow_launch_time seconds to create.
• Slow_queries
The number of queries that have taken more than long_query_time seconds. This counter
increments regardless of whether the slow query log is enabled. For information about that log, see
Section 5.4.4, “The Slow Query Log”.
• Sort_merge_passes
The number of merge passes that 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.
• Sort_range
The number of sorts that were done using ranges.
• Sort_rows
The number of sorted rows.
• Sort_scan
The number of sorts that were done by scanning the table.
• Ssl_accept_renegotiates
The number of negotiates needed to establish the connection.
• Ssl_accepts
The number of accepted SSL connections.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

• Ssl_callback_cache_hits
The number of callback cache hits.
• Ssl_cipher
The current encryption cipher (empty for unencrypted connections).
• Ssl_cipher_list
The list of possible SSL ciphers (empty for non-SSL connections).
• Ssl_client_connects
The number of SSL connection attempts to an SSL-enabled master.
• Ssl_connect_renegotiates
The number of negotiates needed to establish the connection to an SSL-enabled master.
• Ssl_ctx_verify_depth
The SSL context verification depth (how many certificates in the chain are tested).
• Ssl_ctx_verify_mode
The SSL context verification mode.
• Ssl_default_timeout
The default SSL timeout.
• Ssl_finished_accepts
The number of successful SSL connections to the server.
• Ssl_finished_connects
The number of successful slave connections to an SSL-enabled master.
• Ssl_session_cache_hits
The number of SSL session cache hits.
• Ssl_session_cache_misses
The number of SSL session cache misses.
• Ssl_session_cache_mode
The SSL session cache mode.
• Ssl_session_cache_overflows
The number of SSL session cache overflows.
• Ssl_session_cache_size
The SSL session cache size.
• Ssl_session_cache_timeouts
The number of SSL session cache timeouts.
• Ssl_sessions_reused

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Status Variables

How many SSL connections were reused from the cache.
• Ssl_used_session_cache_entries
How many SSL session cache entries were used.
• Ssl_verify_depth
The verification depth for replication SSL connections.
• Ssl_verify_mode
The verification mode for replication SSL connections.
• Ssl_version
The SSL protocol version of the connection; for example, TLSv1. If the connection is not encrypted,
the value is empty.
• Table_locks_immediate
The number of times that a request for a table lock could be granted immediately.
• Table_locks_waited
The number of times that a request for a table lock could not be granted 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.
• Tc_log_max_pages_used
For the memory-mapped implementation of the log that is used by mysqld when it acts as
the transaction coordinator for recovery of internal XA transactions, this variable indicates
the largest number of pages used for the log since the server started. If the product of
Tc_log_max_pages_used and Tc_log_page_size is always significantly less than the log
size, the size is larger than necessary and can be reduced. (The size is set by the --log-tcsize option. This variable is unused: It is unneeded for binary log-based recovery, and the memorymapped recovery log method is not used unless the number of storage engines that are capable
of two-phase commit and that support XA transactions is greater than one. (InnoDB is the only
applicable engine.) Added in MySQL 5.0.3.
• Tc_log_page_size
The page size used for the memory-mapped implementation of the XA recovery log. The default
value is determined using getpagesize(). This variable is unused for the same reasons as
described for Tc_log_max_pages_used. Added in MySQL 5.0.3.
• Tc_log_page_waits
For the memory-mapped implementation of the recovery log, this variable increments each time
the server was not able to commit a transaction and had to wait for a free page in the log. If this
value is large, you might want to increase the log size (with the --log-tc-size option). For binary
log-based recovery, this variable increments each time the binary log cannot be closed because
there are two-phase commits in progress. (The close operation waits until all such transactions are
finished.) Added in MySQL 5.0.3.
• Threads_cached
The number of threads in the thread cache.
• Threads_connected

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

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 the thread_cache_size value. The cache miss rate can be calculated as
Threads_created/Connections.
• Threads_running
The number of threads that are not sleeping.
• Uptime
The number of seconds that the server has been up.
• Uptime_since_flush_status
The number of seconds since the most recent FLUSH STATUS statement. This variable was added
in 5.0.35. (MySQL Community only)

5.1.7 Server SQL Modes
The MySQL server can operate in different SQL modes, and can apply these modes differently for
different clients, depending on the value of the sql_mode system variable. DBAs can set the global
SQL mode to match site server operating requirements, and each application can set its session SQL
mode to its own requirements.
Modes affect the SQL syntax MySQL supports and the data validation checks it performs. This makes
it easier to use MySQL in different environments and to use MySQL together with other database
servers.
• Setting the SQL Mode
• The Most Important SQL Modes
• Full List of SQL Modes
• Strict SQL Mode
• Combination SQL Modes

Setting the SQL Mode
The default SQL mode is empty (no modes set).
To set the SQL mode at server startup, use the --sql-mode="modes" option on the command
line, or sql-mode="modes" in an option file such as my.cnf (Unix operating systems) or my.ini
(Windows). modes is a list of different modes separated by commas. To clear the SQL mode explicitly,
set it to an empty string using --sql-mode="" on the command line, or sql-mode="" in an option
file.
Note
MySQL installation programs may configure the SQL mode during the
installation process. If the SQL mode differs from the default or from what you
expect, check for a setting in an option file that the server reads at startup.
To change the SQL mode at runtime, set the global or session sql_mode system variable using a SET
statement:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

SET GLOBAL sql_mode = 'modes';
SET SESSION sql_mode = 'modes';

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. Each client can
change its session sql_mode value at any time.
To determine the current global or session sql_mode value, use the following statements:
SELECT @@GLOBAL.sql_mode;
SELECT @@SESSION.sql_mode;

The Most Important SQL Modes
The most important sql_mode values are probably these:
•

ANSI
This mode changes syntax and behavior to conform more closely to standard SQL.

•

STRICT_TRANS_TABLES
If a value could not be inserted as given into a transactional table, abort the statement. For a
nontransactional table, abort the statement if the value occurs in a single-row statement or the first
row of a multiple-row statement. More details are given later in this section. (Implemented 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 of a warning” when inserting an incorrect value into a column.
Note
The INSERT or UPDATE aborts as soon as the error is noticed. This may
not be what you want if you are using a nontransactional storage engine,
because data changes made prior to the error may not be rolled back,
resulting in a “partially done” update. (Added in MySQL 5.0.2)

When this manual refers to “strict mode,” it means a mode with either or both STRICT_TRANS_TABLES
or STRICT_ALL_TABLES enabled.

Full List of SQL Modes
The following list describes all supported SQL modes:
•

ALLOW_INVALID_DATES
Do not perform 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 and DATETIME columns. It does not apply TIMESTAMP
columns, which always require a valid date.
This mode is implemented in MySQL 5.0.2. Before 5.0.2, this was the default MySQL datehandling mode. As of 5.0.2, the server requires that month and day values be legal, and not merely
in the range 1 to 12 and 1 to 31, respectively. With strict mode disabled, invalid dates such as
'2004-04-31' are converted to '0000-00-00' and a warning is generated. With strict mode
enabled, invalid dates generate an error. To permit such dates, enable ALLOW_INVALID_DATES.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

•

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 identifiers with this mode enabled. With ANSI_QUOTES
enabled, you cannot use double quotation marks to quote literal strings, because it is interpreted as
an identifier.

•

ERROR_FOR_DIVISION_BY_ZERO
The ERROR_FOR_DIVISION_BY_ZERO mode affects handling of division by zero, which includes
MOD(N,0). For data-change operations (INSERT, UPDATE), its effect also depends on whether strict
SQL mode is enabled.
• If this mode is not enabled, division by zero inserts NULL and produces no warning.
• If this mode is enabled, division by zero inserts NULL and produces a warning.
• If this mode and strict mode are enabled, division by zero produces an error, unless IGNORE is
given as well. For INSERT IGNORE and UPDATE IGNORE, division by zero inserts NULL and
produces a warning.
For SELECT, division by zero returns NULL. Enabling ERROR_FOR_DIVISION_BY_ZERO causes a
warning to be produced as well, regardless of whether strict mode is enabled.
This mode was implemented in MySQL 5.0.2.

•

HIGH_NOT_PRECEDENCE
From MySQL 5.0.2 on, the precedence of the NOT operator is such that expressions such as NOT
a BETWEEN b AND c are parsed as NOT (a BETWEEN b AND c). Before MySQL 5.0.2, the
expression is parsed as (NOT a) BETWEEN b AND c. The old higher-precedence behavior can be
obtained by enabling the HIGH_NOT_PRECEDENCE SQL mode. (Added in MySQL 5.0.2)
mysql> SET sql_mode
mysql> SELECT NOT 1
-> 0
mysql> SET sql_mode
mysql> SELECT NOT 1
-> 1

•

= '';
BETWEEN -5 AND 5;
= 'HIGH_NOT_PRECEDENCE';
BETWEEN -5 AND 5;

IGNORE_SPACE
Permit spaces between a function name and the “(” character. This causes built-in function names
to be treated as reserved words. As a result, identifiers that are the same as function names must
be quoted as described in Section 9.2, “Schema Object Names”. For example, because there is a
COUNT() function, the use of count as a table name in the following statement causes an error:
mysql> CREATE TABLE count (i INT);
ERROR 1064 (42000): You have an error in your SQL syntax

The table name should be quoted:
mysql> CREATE TABLE `count` (i INT);
Query OK, 0 rows affected (0.00 sec)

The IGNORE_SPACE SQL mode applies to built-in functions, not to user-defined functions or stored
functions. It is always permissible to have spaces after a UDF or stored function name, regardless of
whether IGNORE_SPACE is enabled.
For further discussion of IGNORE_SPACE, see Section 9.2.3, “Function Name Parsing and
Resolution”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

•

NO_AUTO_CREATE_USER
Prevent the GRANT statement from automatically creating new users if it would otherwise do so,
unless a nonempty password also is specified. (Added in MySQL 5.0.2)

•

NO_AUTO_VALUE_ON_ZERO
NO_AUTO_VALUE_ON_ZERO affects handling of AUTO_INCREMENT columns. Normally, you
generate the next sequence number for the column by inserting either NULL or 0 into it.
NO_AUTO_VALUE_ON_ZERO suppresses this behavior for 0 so that only NULL generates the next
sequence number.
This mode can be useful if 0 has been stored in a table's AUTO_INCREMENT column. (Storing 0
is not a recommended practice, by the way.) For example, if you dump the table with mysqldump
and then reload it, MySQL normally generates new sequence numbers when it encounters the
0 values, resulting in a table with contents different from the one that was dumped. Enabling
NO_AUTO_VALUE_ON_ZERO before reloading the dump file solves this problem. mysqldump now
automatically includes in its output a statement that enables NO_AUTO_VALUE_ON_ZERO, to avoid
this problem.

•

NO_BACKSLASH_ESCAPES
Disable the use of the backslash character (“\”) as an escape character within strings. With this
mode enabled, backslash becomes an ordinary character like any other. (Implemented in MySQL
5.0.1)

•

NO_DIR_IN_CREATE
When creating a table, ignore all INDEX DIRECTORY and DATA DIRECTORY directives. This option
is useful on slave replication servers.

•

NO_ENGINE_SUBSTITUTION
Control automatic substitution of the default storage engine when a statement such as CREATE
TABLE or ALTER TABLE specifies a storage engine that is disabled or not compiled in. (Implemented
in MySQL 5.0.8)
With NO_ENGINE_SUBSTITUTION disabled, the default engine is used and a warning occurs if the
desired engine is known but disabled or not compiled in. If the desired engine is invalid (not a known
engine name), an error occurs and the table is not created or altered.
With NO_ENGINE_SUBSTITUTION enabled, an error occurs and the table is not created or altered if
the desired engine is unavailable for any reason (whether disabled or invalid).

•

NO_FIELD_OPTIONS
Do not print MySQL-specific column options in the output of SHOW CREATE TABLE. This mode is
used by mysqldump in portability mode.

•

NO_KEY_OPTIONS
Do not print MySQL-specific index options in the output of SHOW CREATE TABLE. This mode is used
by mysqldump in portability mode.

•

NO_TABLE_OPTIONS
Do not print MySQL-specific table options (such as ENGINE) in the output of SHOW CREATE TABLE.
This mode is used by mysqldump in portability mode.

•

NO_UNSIGNED_SUBTRACTION

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

By default, subtraction between integer operands produces an UNSIGNED result if any operand is
UNSIGNED. When NO_UNSIGNED_SUBTRACTION is enabled, the subtraction result is signed, even
if any operand is unsigned. For example, compare the type of column c2 in table t1 with that of
column c2 in table t2:

mysql> SET sql_mode='';
mysql> CREATE TABLE test (c1 BIGINT UNSIGNED NOT NULL);
mysql> CREATE TABLE t1 SELECT c1 - 1 AS c2 FROM test;
mysql> DESCRIBE t1;
+-------+---------------------+------+-----+---------+-------+
| Field | Type
| Null | Key | Default | Extra |
+-------+---------------------+------+-----+---------+-------+
| c2
| bigint(21) unsigned | NO
|
| 0
|
|
+-------+---------------------+------+-----+---------+-------+
mysql> SET sql_mode='NO_UNSIGNED_SUBTRACTION';
mysql> CREATE TABLE t2 SELECT c1 - 1 AS c2 FROM test;
mysql> DESCRIBE t2;
+-------+------------+------+-----+---------+-------+
| Field | Type
| Null | Key | Default | Extra |
+-------+------------+------+-----+---------+-------+
| c2
| bigint(21) | NO
|
| 0
|
|
+-------+------------+------+-----+---------+-------+

This means that BIGINT UNSIGNED is not 100% usable in all contexts. See Section 12.10, “Cast
Functions and Operators”.
mysql> SET sql_mode = '';
mysql> SELECT CAST(0 AS UNSIGNED) - 1;
+-------------------------+
| CAST(0 AS UNSIGNED) - 1 |
+-------------------------+
|
18446744073709551615 |
+-------------------------+
mysql> SET sql_mode = 'NO_UNSIGNED_SUBTRACTION';
mysql> SELECT CAST(0 AS UNSIGNED) - 1;
+-------------------------+
| CAST(0 AS UNSIGNED) - 1 |
+-------------------------+
|
-1 |
+-------------------------+

•

NO_ZERO_DATE
The NO_ZERO_DATE mode affects whether the server permits '0000-00-00' as a valid date. Its
effect also depends on whether strict SQL mode is enabled. This mode was added in MySQL 5.0.2.
• If this mode is not enabled, '0000-00-00' is permitted and inserts produce no warning.
• If this mode is enabled, '0000-00-00' is permitted and inserts produce a warning.
• If this mode and strict mode are enabled, '0000-00-00' is not permitted and inserts produce
an error, unless IGNORE is given as well. For INSERT IGNORE and UPDATE IGNORE,
'0000-00-00' is permitted and inserts produce a warning.

•

NO_ZERO_IN_DATE
The NO_ZERO_IN_DATE mode affects whether the server permits dates in which the year part
is nonzero but the month or day part is 0. (This mode affects dates such as '2010-00-01' or
'2010-01-00', but not '0000-00-00'. To control whether the server permits '0000-00-00',
use the NO_ZERO_DATE mode.) The effect of NO_ZERO_IN_DATE also depends on whether strict
SQL mode is enabled. This mode was added in MySQL 5.0.2.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

• If this mode is not enabled, dates with zero parts are permitted and inserts produce no warning.
• If this mode is enabled, dates with zero parts are inserted as '0000-00-00' and produce a
warning.
• If this mode and strict mode are enabled, dates with zero parts are not permitted and inserts
produce an error, unless IGNORE is given as well. For INSERT IGNORE and UPDATE IGNORE,
dates with zero parts are inserted as '0000-00-00' and produce a warning.
•

ONLY_FULL_GROUP_BY
Reject queries for which the select list or (as of MySQL 5.0.23) HAVING list refer to nonaggregated
columns that are not named in the GROUP BY clause.
A MySQL extension to standard SQL permits references in the HAVING clause to aliased
expressions in the select list. Enabling ONLY_FULL_GROUP_BY disables this extension, thus
requiring the HAVING clause to be written using unaliased expressions.
For additional discussion and examples, see Section 12.16.3, “MySQL Handling of GROUP BY”.

•

PIPES_AS_CONCAT
Treat || as a string concatenation operator (same as CONCAT()) rather than as a synonym for OR.

•

REAL_AS_FLOAT
Treat REAL as a synonym for FLOAT. By default, MySQL treats REAL as a synonym for DOUBLE.

•

STRICT_ALL_TABLES
Enable strict mode for all storage engines. Invalid data values are rejected. For details, see Strict
SQL Mode. (Added in MySQL 5.0.2)

•

STRICT_TRANS_TABLES
Enable strict mode for transactional storage engines, and when possible for nontransactional storage
engines. For details, see Strict SQL Mode. (Implemented in MySQL 5.0.2)

Combination SQL Modes
The following special modes are provided as shorthand for combinations of mode values from the
preceding list. All are available beginning with version MySQL 5.0.0, except for TRADITIONAL, which
was implemented in MySQL 5.0.2.
•

ANSI
Equivalent to REAL_AS_FLOAT, PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE. Before
MySQL 5.0.3, ANSI also includes ONLY_FULL_GROUP_BY.
As of MySQL 5.0.40, ANSI mode also causes the server to return an error for queries where a set
function S with an outer reference S(outer_ref) cannot be aggregated in the outer query against
which the outer reference has been resolved. This is such a query:
SELECT * FROM t1 WHERE t1.a IN (SELECT MAX(t1.b) FROM t2 WHERE ...);

Here, MAX(t1.b) cannot aggregated in the outer query because it appears in the WHERE clause
of that query. Standard SQL requires an error in this situation. If ANSI mode is not enabled, the
server treats S(outer_ref) in such queries the same way that it would interpret S(const), as
was always done prior to 5.0.40.
See Section 1.8, “MySQL Standards Compliance”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server SQL Modes

•

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, NO_AUTO_CREATE_USER.

•

MSSQL
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS.

•

MYSQL323
Equivalent to MYSQL323, HIGH_NOT_PRECEDENCE. This means HIGH_NOT_PRECEDENCE plus
some SHOW CREATE TABLE behaviors specific to MYSQL323:
• TIMESTAMP column display does not include DEFAULT or ON UPDATE attributes that were
introduced in MySQL 4.1.
• String column display does not include character set and collation attributes that were introduced
in MySQL 4.1. For CHAR and VARCHAR columns, if the collation is binary, BINARY is appended to
the column type.
• The ENGINE=engine_name table option displays as TYPE=engine+name.
• For MEMORY tables, the storage engine is displayed as HEAP.

•

MYSQL40
Equivalent to MYSQL40, HIGH_NOT_PRECEDENCE. This means HIGH_NOT_PRECEDENCE plus some
behaviors specific to MYSQL40. These are the same as for MYSQL323, except that SHOW CREATE
TABLE does not display HEAP as the storage engine for MEMORY tables.

•

ORACLE
Equivalent to PIPES_AS_CONCAT, ANSI_QUOTES, IGNORE_SPACE, NO_KEY_OPTIONS,
NO_TABLE_OPTIONS, NO_FIELD_OPTIONS, NO_AUTO_CREATE_USER.

•

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, NO_AUTO_CREATE_USER.

Strict SQL Mode
Strict mode controls how MySQL handles invalid or missing values in data-change statements such as
INSERT or UPDATE. A value can be invalid for several reasons. For example, it might have the wrong
data type for the column, or it might be out of range. A value is missing when a new row to be inserted
does not contain a value for a non-NULL column that has no explicit DEFAULT clause in its definition.
(For a NULL column, NULL is inserted if the value is missing.)
If strict mode is not in effect, MySQL inserts adjusted values for invalid or missing values and produces
warnings (see Section 13.7.5.37, “SHOW WARNINGS Syntax”). In strict mode, you can produce this
behavior by using INSERT IGNORE or UPDATE IGNORE.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server-Side Help

For statements such as SELECT that do not change data, invalid values generate a warning in strict
mode, not an error.
Strict mode does not affect whether foreign key constraints are checked. foreign_key_checks can
be used for that. (See Section 5.1.4, “Server System Variables”.)
Strict SQL mode is in effect if either STRICT_ALL_TABLES or STRICT_TRANS_TABLES is enabled,
although the effects of these modes differ somewhat:
• For transactional tables, an error occurs for invalid or missing values in a data-change statement
when either STRICT_ALL_TABLES or STRICT_TRANS_TABLES is enabled. The statement is
aborted and rolled back.
• For nontransactional tables, the behavior is the same for either mode if the bad value occurs in the
first row to be inserted or updated: The statement is aborted and the table remains unchanged. If the
statement inserts or modifies multiple rows and the bad value occurs in the second or later row, the
result depends on which strict mode is enabled:
• For STRICT_ALL_TABLES, MySQL returns an error and ignores the rest of the rows. However,
because the earlier rows have been inserted or updated, the result is a partial update. To avoid
this, use single-row statements, which can be aborted without changing the table.
• For STRICT_TRANS_TABLES, MySQL converts an invalid value to the closest valid value for the
column and inserts the adjusted value. If a value is missing, MySQL inserts the implicit default
value for the column data type. In either case, MySQL generates a warning rather than an error
and continues processing the statement. Implicit defaults are described in Section 11.6, “Data
Type Default Values”.
Strict mode also affects handling of division by zero, zero dates, and zeros in dates, in conjunction with
the ERROR_FOR_DIVISION_BY_ZERO, NO_ZERO_DATE, and NO_ZERO_IN_DATE modes. For details,
see the descriptions of those modes.

5.1.8 Server-Side Help
MySQL Server supports a HELP statement that returns information from the MySQL Reference
manual (see Section 13.8.3, “HELP Syntax”). Several tables in the mysql system database contain
the information needed to support this statement (see Section 5.3, “The mysql System Database”).
The proper operation of this statement requires that these help tables be initialized, which is done by
processing the contents of the fill_help_tables.sql script.
If you install MySQL using a binary or source distribution on Unix, help table content initialization
occurs when you initialize the data directory (see Section 2.18.1, “Initializing the Data Directory”). For
an RPM distribution on Linux or binary distribution on Windows, content initialization occurs as part of
the MySQL installation process.
If you upgrade MySQL using a binary distribution, help table content is not upgraded automatically, but
you can upgrade it manually. Locate the fill_help_tables.sql file in the share or share/mysql
directory. Change location into that directory and process the file with the mysql client as follows:
shell> mysql -u root mysql < fill_help_tables.sql

You can also obtain the latest fill_help_tables.sql at any time to upgrade your help tables.
Download the proper file for your version of MySQL from http://dev.mysql.com/doc/index-other.html.
After downloading and uncompressing the file, process it with mysql as described previously.
If you are working with Bazaar and a MySQL development source tree, you must use a downloaded
copy of the fill_help_tables.sql file because the source tree contains only a “stub” version.

5.1.9 Server Response to Signals
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Server Shutdown Process

On Unix, signals can be sent to processes. mysqld responds to signals sent to it as follows:
• SIGTERM causes the server to shut down.
• SIGHUP causes the server to reload the grant tables and to flush tables, logs, the thread cache, and
the host cache. These actions are like various forms of the FLUSH statement. The server also writes
a status report to the error log that has this format:
Status information:
Current dir: /var/mysql/data/
Running threads: 0 Stack size: 196608
Current locks:
Key caches:
default
Buffer_size:
Block_size:
Division_limit:
Age_limit:
blocks used:
not flushed:
w_requests:
writes:
r_requests:
reads:
handler status:
read_key:
read_next:
read_rnd
read_first:
write:
delete
update:

8388600
1024
100
300
0
0
0
0
0
0

Table status:
Opened tables:
Open tables:
Open files:
Open streams:

0
0
0
1
0
0
0

5
0
7
0

Alarm status:
Active alarms:
1
Max used alarms: 2
Next alarm time: 67

5.1.10 The Server Shutdown Process
The server shutdown process takes place as follows:
1. The shutdown process is initiated.
This can occur initiated several ways. For example, a user with the SHUTDOWN privilege can
execute a mysqladmin shutdown command. mysqladmin can be used on any platform
supported by MySQL. Other operating system-specific shutdown initiation methods are possible
as well: The server shuts down on Unix when it receives a SIGTERM signal. A server running as a
service on Windows shuts down when the services manager tells it to.
2. 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 appears in the error log:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Data Directory

Error: Can't create thread to kill server

3. The server stops accepting new connections.
To prevent new activity from being initiated during shutdown, the server stops accepting new
client connections by closing the handlers for the network interfaces to which it normally listens for
connections: the TCP/IP port, the Unix socket file, the Windows named pipe, and shared memory
on Windows.
4. The server terminates current activity.
For each thread associated with a client connection, the server breaks the connection to the client
and marks the thread as killed. Threads die when they notice that they are so marked. Threads
for idle connections die quickly. Threads that currently are processing statements check their
state periodically and take longer to die. For additional information about thread termination, see
Section 13.7.6.3, “KILL Syntax”, in particular for the instructions about killed REPAIR TABLE or
OPTIMIZE TABLE operations on MyISAM tables.
For threads that have an open transaction, the transaction is rolled back. If a thread is updating a
nontransactional table, an operation such as a multiple-row UPDATE or INSERT may leave the table
partially updated because the operation can terminate before completion.
If the server is a master replication server, it treats threads associated with currently connected
slaves 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, it stops the I/O and SQL threads, if they are active, before
marking client threads as killed. The SQL thread is permitted to finish its current statement (to avoid
causing replication problems), and then stops. In MySQL 5.0.80 and earlier, if the SQL thread was
in the middle of a transaction at this point, the transaction was rolled back; in MySQL 5.0.81 and
later, the server waits until the current replication event group (if any) has finished executing, or
until the user issues a KILL QUERY or KILL CONNECTION statement. See also Section 13.4.2.8,
“STOP SLAVE Syntax”.
If the slave is updating a nontransactional table when it is forcibly killed, the slave's data may
become inconsistent with the master.
5. The server shuts down or closes storage engines.
At this stage, the server flushes the table cache and closes all open tables.
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 (starting
from 5.0.5: unless innodb_fast_shutdown is 2), writes the current LSN to the tablespace, and
terminates its own internal threads.
6. The server exits.

5.2 The MySQL Data Directory
Information managed by the MySQL server is stored under a directory known as the data directory.
The following list briefly describes the items typically found in the data directory, with cross references
for additional information:
• Each data directory subdirectory corresponds to a database managed by the server:
• The mysql directory corresponds to the mysql system database, which contains information
required by the MySQL server as it runs. See Section 5.3, “The mysql System Database”.
• Other subdirectories correspond to databases created by users or applications.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The mysql System Database

• Log files written by the server. See Section 5.4, “MySQL Server Logs”.
• InnoDB tablespace and log files. See Section 14.2, “The InnoDB Storage Engine”.
• The server process ID file (while the server is running).
Some items in the preceding list can be relocated elsewhere; for any given MySQL installation, check
the server configuration to determine whether items have been moved. In addition, the location of the
data directory itself can be discovered or configured using the datadir system variable.

5.3 The mysql System Database
The mysql database is the system database. It contains tables that store information required by the
MySQL server as it runs.
Tables in the mysql database fall into these categories:
• Grant tables
• Object information tables
• Server-side help tables
• Time zone tables

Grant System Tables
These system tables contain grant information about user accounts and the privileges held by them:
•

user: User accounts, global privileges, and other non-privilege columns.

•

db: Database-level privileges.

•

host: Obsolete.

•

tables_priv: Table-level privileges.

•

columns_priv: Column-level privileges.

•

procs_priv: Stored procedure and function privileges.

For more information about the structure, contents, and purpose of the grant tables, see Section 6.2.2,
“Grant Tables”.

Object Information System Tables
The func system table contains information about user-defined functions. See Section 21.2, “Adding
New Functions to MySQL”.

Server-Side Help System Tables
These system tables contain server-side help information:
•

help_category: Information about help categories.

•

help_keyword: Keywords associated with help topics.

•

help_relation: Mappings between help keywords and topics.

•

help_topic: Help topic contents.

For more information, see Section 5.1.8, “Server-Side Help”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Time Zone System Tables

Time Zone System Tables
These system tables contain time zone information:
•

time_zone: List of time zone IDs and whether they use leap seconds.

•

time_zone_leap_second: When leap seconds occur.

•

time_zone_name: Mappings between time zone IDs and names.

•

time_zone_transition, time_zone_transition_type: Time zone descriptions.

For more information, see Section 10.6, “MySQL Server Time Zone Support”.

5.4 MySQL Server Logs
MySQL Server has several logs that can help you find out what activity is taking place.
Log Type

Information Written to Log

Error log

Problems encountered starting, running, or stopping mysqld

General query log

Established client connections and statements received from clients

Binary log

Statements that change data (also used for replication)

Relay log

Data changes received from a replication master server

Slow query log

Queries that took more than long_query_time seconds to execute

By default, no logs are enabled (except the error log on Windows). The following log-specific sections
provide information about the server options that enable logging.
By default, the server writes files for all enabled logs in the data directory. You can force the server
to close and reopen the log files (or in some cases switch to a new log file) by flushing the logs. Log
flushing occurs when you issue a FLUSH LOGS statement; execute mysqladmin with a flush-logs
or refresh argument; or execute mysqldump with a --flush-logs or --master-data option. See
Section 13.7.6.2, “FLUSH Syntax”, Section 4.5.2, “mysqladmin — Client for Administering a MySQL
Server”, and Section 4.5.4, “mysqldump — A Database Backup Program”. In addition, the binary log is
flushed when its size reaches the value of the max_binlog_size system variable.
The relay log is used only on slave replication servers, to hold data changes from the master server
that must also be made on the slave. For discussion of relay log contents and configuration, see
Section 16.2.2.1, “The Slave Relay Log”.
For information about log maintenance operations such as expiration of old log files, see Section 5.4.5,
“Server Log Maintenance”.
For information about keeping logs secure, see Section 6.1.2.3, “Passwords and Logging”.

5.4.1 The Error Log
The error log contains information indicating when mysqld was started and stopped and also any
critical errors that occur while the server is running. If mysqld notices a table that needs to be
automatically checked or repaired, it writes a message to the error log.
On some operating systems, the error log contains a stack trace if mysqld exits abnormally. The trace
can be used to determine where mysqld exited. See Section 21.3, “Debugging and Porting MySQL”.
If mysqld_safe is used to start mysqld and mysqld exits abnormally, mysqld_safe notices this,
restarts mysqld, and writes a mysqld restarted message to the error log.
In the following discussion, “console” means stderr, the standard error output; this is your terminal or
console window unless the standard error output has been redirected.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The General Query Log

On Windows, the --log-error, --pid-file, and --console options affect error logging:
• If no log file name is specified, the default log file is host_name.err in the data directory, unless
the --pid-file option is specified. In that case, the default name is the PID file base name with a
suffix of .err in the data directory.
• Without --log-error, mysqld writes error messages to the default log file.
• With --log-error[=file_name], mysqld writes error messages to an error log file. mysqld
writes to the named file if present, creating it in the data directory unless an absolute path name is
given to specify a different directory. If no file is named, mysqld writes to the default log file.
• With --console, mysqld writes error messages to the console, unless --log-error is also
given. If both options are present, the last one takes precedence.
In addition, on Windows, the server writes events and error messages to the Windows Event Log
within the Application log. Entries marked as Warning and Note are written to the Event Log, but not
informational messages such as information statements from individual storage engines. These log
entries have a source of MySQL. You cannot disable writing information to the Windows Event Log.
On Unix and Unix-like systems, mysqld writes error log messages as follows:
• Without --log-error, mysqld writes error messages to the console.
• With --log-error[=file_name], mysqld writes error messages to an error log file. The server
uses the named file if present, creating it in the data directory unless an absolute path name is given
to specify a different directory. If no file is named, the default name is host_name.err in the data
directory.
At runtime, log_error system variable indicates the error log file name if error output is written to a
file.
If you flush the logs using FLUSH LOGS or mysqladmin flush-logs and mysqld is writing the error
log to a file (for example, if it was started with the --log-error option), it renames the current log file
with the suffix -old, then creates a new empty log file. Be aware that a second log-flushing operation
thus causes the original error log file to be lost unless you save it under a different name. For example,
you can use the following commands to save the file:
shell> mysqladmin flush-logs
shell> mv host_name.err-old backup-directory

If the server is not writing to a named file, no error log renaming occurs when the logs are flushed.
If you use mysqld_safe to start mysqld, mysqld_safe arranges for mysqld to write error
messages to a log file. If you specify a file name using --log-error to mysqld_safe or mysqld,
that file name is used. Otherwise, mysqld_safe uses the default error log file.
The --log-warnings option or log_warnings system variable can be used to control warning
logging to the error log. The default value is enabled (1). Warning logging can be disabled using
a value of 0. If the value is greater than 1, aborted connections are written to the error log. See
Section B.5.2.11, “Communication Errors and Aborted Connections”.

5.4.2 The General Query Log
The general query log is a general record of what mysqld is doing. The server writes information to
this log when clients connect or disconnect, and it logs each SQL statement received from clients. The
general query log can be very useful when you suspect an error in a client and want to know exactly
what the client sent to mysqld.
mysqld writes statements to the query log in the order that it receives them, which might differ from the
order in which they are executed. This logging order is in contrast with that of the binary log, for which
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Binary Log

statements are written after they are executed but before any locks are released. (Also, the query log
contains all statements, whereas the binary log does not contain statements that only select data.)
To enable the general query log, start mysqld with the --log[=file_name] or -l [file_name]
option.
If the general query log file is enabled but no name is specified, the default name is host_name.log
and the server creates the file in the same directory where it creates the PID file. If a name is given, the
server creates the file in the data directory unless an absolute path name is given to specify a different
directory.
Server restarts and log flushing do not cause a new general query log file to be generated (although
flushing closes and reopens it). On Unix, to rename the file and create a new one, use the following
commands:
shell> mv host_name.log host_name-old.log
shell> mysqladmin flush-logs
shell> mv host_name-old.log backup-directory

On Windows, you cannot rename a log file while the server has it open before MySQL 5.0.17. You
must stop the server, rename the file, and then restart the server to create a new log file. As of 5.0.17,
this applies only to the error log. However, a stop and restart can be avoided by using FLUSH LOGS,
which causes the server to rename the error log with an -old suffix and open a new error log.
The general query log should be protected because logged statements might contain passwords. See
Section 6.1.2.3, “Passwords and Logging”.

5.4.3 The Binary Log
The binary log contains “events” that describe database changes such as table creation operations or
changes to table data. It also contains events for statements that potentially could have made changes
(for example, a DELETE which matched no rows). The binary log also contains information about how
long each statement took that updated data. The binary log has two important purposes:
• For replication, the binary log on a master replication server provides a record of the data changes to
be sent to slave servers. The master server sends the events contained in its binary log to its slaves,
which execute those events to make the same data changes that were made on the master. See
Section 16.2, “Replication Implementation”.
• Certain data recovery operations require use of the binary log. After a backup has been restored,
the events in the binary log that were recorded after the backup was made are re-executed. These
events bring databases up to date from the point of the backup. See Section 7.5, “Point-in-Time
(Incremental) Recovery Using the Binary Log”.
Note
The binary log has replaced the old update log, which is no longer available as
of MySQL 5.0. The binary log contains all information that is available in the
update log in a more efficient format and in a manner that is transaction-safe.
If you are using transactions, you must use the MySQL binary log for backups
instead of the old update log.
The binary log is not used for statements such as SELECT or SHOW that do not modify data. To log all
statements (for example, to identify a problem query), use the general query log. See Section 5.4.2,
“The General Query Log”.
Running a server with binary logging enabled makes performance slightly slower. However, the
benefits of the binary log in enabling you to set up replication and for restore operations generally
outweigh this minor performance decrement.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Binary Log

The binary log should be protected because logged statements might contain passwords. See
Section 6.1.2.3, “Passwords and Logging”.
The following discussion describes some of the server options and variables that affect the operation of
binary logging. For a complete list, see Section 16.1.2.4, “Binary Log Options and Variables”.
For detailed information about the format of the binary log, see MySQL Internals: The Binary Log.
To enable the binary log, start the server with the --log-bin[=base_name] option. If no
base_name value is given, the default name is the value of the pid-file option (which by default is
the name of host machine) followed by -bin. If the base name is given, the server writes the file in the
data directory unless the base name is given with a leading absolute path name to specify a different
directory. It is recommended that you specify a base name explicitly rather than using the default of the
host name; see Section B.5.7, “Known Issues in MySQL”, for the reason.
Note
From MySQL 5.0.41 through 5.0.52, “mysql” was used when no base_name
was specified. Also in these versions, a path given as part of the --log-bin
options was treated as absolute rather than relative. The previous behaviors
were restored in MySQL 5.0.54. (See Bug #28603 and Bug #28597.)
If you supply an extension in the log name (for example, --log-bin=base_name.extension), the
extension is silently removed and ignored.
mysqld appends a numeric extension to the binary log base name to generate binary log file names.
The number increases each time the server creates a new log file, thus creating an ordered series of
files. The server creates a new file in the series each time it starts or flushes the logs. The server also
creates a new binary log file automatically after the current log's size reaches max_binlog_size. A
binary log file may become larger than max_binlog_size if you are using large transactions because
a transaction is written to the file in one piece, never split between files.
To keep track of which binary log files have been used, mysqld also creates a binary log index file
that contains the names of all used binary log files. By default, this has the same base name as the
binary log file, with the extension '.index'. You can change the name of the binary log index file with
the --log-bin-index[=file_name] option. You should not manually edit this file while mysqld is
running; doing so would confuse mysqld.
The term “binary log file” generally denotes an individual numbered file containing database events.
The term “binary log” collectively denotes the set of numbered binary log files plus the index file.
A client that has the SUPER privilege can disable binary logging of its own statements by using a SET
sql_log_bin=0 statement. See Section 5.1.4, “Server System Variables”.
The server evaluates the --binlog-do-db and --binlog-ignore-db options in the same way
as it does the --replicate-do-db and --replicate-ignore-db options. For information about
how this is done, see Section 16.2.3.1, “Evaluation of Database-Level Replication and Binary Logging
Options”.
A replication slave server by default does not write to its own binary log any data modifications that
are received from the replication master. To log these modifications, start the slave with the --logslave-updates option in addition to the --log-bin option (see Section 16.1.2.3, “Replication Slave
Options and Variables”). This is done when a slave is also to act as a master to other slaves in chained
replication.
You can delete all binary log files with the RESET MASTER statement, or a subset of them with PURGE
BINARY LOGS. See Section 13.7.6.5, “RESET Syntax”, and Section 13.4.1.1, “PURGE BINARY LOGS
Syntax”.
If you are using replication, you should not delete old binary log files on the master until you are sure
that no slave still needs to use them. For example, if your slaves never run more than three days
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Binary Log

behind, once a day you can execute mysqladmin flush-logs on the master and then remove any
logs that are more than three days old. You can remove the files manually, but it is preferable to use
PURGE BINARY LOGS, which also safely updates the binary log index file for you (and which can take
a date argument). See Section 13.4.1.1, “PURGE BINARY LOGS Syntax”.
You can display the contents of binary log files with the mysqlbinlog utility. This can be useful when
you want to reprocess statements in the log for a recovery operation. For example, you can update a
MySQL server from the binary log as follows:
shell> mysqlbinlog log_file | mysql -h server_name

mysqlbinlog also can be used to display replication slave relay log file contents because they are
written using the same format as binary log files. For more information on the mysqlbinlog utility and
how to use it, see Section 4.6.7, “mysqlbinlog — Utility for Processing Binary Log Files”. For more
information about the binary log and recovery operations, see Section 7.5, “Point-in-Time (Incremental)
Recovery Using the Binary Log”.
Binary logging is done immediately after a statement or transaction completes but before any locks are
released or any commit is done. This ensures that the log is logged in commit order.
Updates to nontransactional tables are stored in the binary log immediately after execution. In MySQL
5.0.53 and earlier versions of MySQL 5.0, an UPDATE statement using a stored function that modified a
nontransactional table was not logged if it failed, and an INSERT ... ON DUPLICATE KEY UPDATE
statement that encountered a duplicate key constraint—but did not actually change any data—was
not logged. Beginning with MySQL 5.0.54, both of these statements are written to the binary log. (Bug
#23333)
Within an uncommitted transaction, all updates (UPDATE, DELETE, or INSERT) that change
transactional tables such as BDB or InnoDB tables are cached until a COMMIT statement is received
by the server. At that point, mysqld writes the entire transaction to the binary log before the COMMIT is
executed.
Modifications to nontransactional tables cannot be rolled back. If a transaction that is rolled back
includes modifications to nontransactional tables, the entire transaction is logged with a ROLLBACK
statement at the end to ensure that the modifications to those tables are replicated.
When a thread that handles the transaction starts, it allocates a buffer of binlog_cache_size to
buffer statements. If a statement is bigger than this, the thread opens a temporary file to store the
transaction. The temporary file is deleted when the thread ends.
The Binlog_cache_use status variable shows the number of transactions that used this buffer (and
possibly a temporary file) for storing statements. The Binlog_cache_disk_use status variable
shows how many of those transactions actually had to use a temporary file. These two variables can be
used for tuning binlog_cache_size to a large enough value that avoids the use of temporary files.
The max_binlog_cache_size system variable (default 4GB, which is also the maximum) can be
used to restrict the total size used to cache a multiple-statement transaction. If a transaction is larger
than this many bytes, it fails and rolls back. The minimum value is 4096.
If you are using the binary log and row based logging, concurrent inserts are converted to normal
inserts for CREATE ... SELECT or INSERT ... SELECT statements. This is done to ensure that
you can re-create an exact copy of your tables by applying the log during a backup operation. If you are
using statement-based logging, the original statement is written to the log.
The binary log format has some known limitations that can affect recovery from backups. See
Section 16.4.1, “Replication Features and Issues”.
Binary logging for stored programs is done as described in Section 18.6, “Binary Logging of Stored
Programs”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The Slow Query Log

Note that the binary log format differs in MySQL 5.0 from previous versions of MySQL, due to
enhancements in replication. See Section 16.4.2, “Replication Compatibility Between MySQL
Versions”.
Writes to the binary log file and binary log index file are handled in the same way as writes to MyISAM
tables. See Section B.5.3.4, “How MySQL Handles a Full Disk”.
By default, the binary log is not synchronized to disk at each write. So if the operating system or
machine (not only the MySQL server) crashes, there is a chance that the last statements of the
binary log are lost. To prevent this, you can make the binary log be synchronized to disk after every N
writes to the binary log, with the sync_binlog system variable. See Section 5.1.4, “Server System
Variables”. 1 is the safest value for sync_binlog, but also the slowest. Even with sync_binlog
set to 1, there is still the chance of an inconsistency between the table content and binary log content
in case of a crash. For example, if you are using InnoDB tables and the MySQL server processes a
COMMIT statement, it writes the whole transaction to the binary log and then commits this transaction
into InnoDB. If the server crashes between those two operations, the transaction is rolled back by
InnoDB at restart but still exists in the binary log. This problem can be solved with the --innodbsafe-binlog option, which adds consistency between the content of InnoDB tables and the binary
log. (Note: --innodb-safe-binlog is unneeded as of MySQL 5.0; it was made obsolete by the
introduction of XA transaction support.)
For this option to provide a greater degree of safety, the MySQL server should also be configured to
synchronize the binary log and the InnoDB logs to disk at every transaction. The InnoDB logs are
synchronized by default, and sync_binlog=1 can be used to synchronize the binary log. The effect
of this option is that at restart after a crash, after doing a rollback of transactions, the MySQL server
cuts rolled back InnoDB transactions from the binary log. This ensures that the binary log reflects the
exact data of InnoDB tables, and so, that the slave remains in synchrony with the master (not receiving
a statement which has been rolled back).
Note that --innodb-safe-binlog can be used even if the MySQL server updates other storage
engines than InnoDB. Only statements and transactions that affect InnoDB tables are subject to
removal from the binary log at InnoDB's crash recovery. If the MySQL server discovers at crash
recovery that the binary log is shorter than it should have been, it lacks at least one successfully
committed InnoDB transaction. This should not happen if sync_binlog=1 and the disk/file system do
an actual sync when they are requested to (some do not), so the server prints an error message The
binary log file_name is shorter than its expected size. In this case, this binary log
is not correct and replication should be restarted from a fresh snapshot of the master's data.
For MySQL 5.0.46, the session values of the following system variables are written to the binary log
and honored by the replication slave when parsing the binary log:
• sql_mode
• foreign_key_checks
• unique_checks
• character_set_client
• collation_connection
• collation_database
• collation_server
• sql_auto_is_null

5.4.4 The Slow Query Log
The slow query log consists of SQL statements that took more than long_query_time seconds to
execute. The minimum and default values of long_query_time are 1 and 10, respectively.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Server Log Maintenance

By default, administrative statements are not logged, nor are queries that do not use indexes for
lookups. This behavior can be changed using --log-slow-admin-statements and --logqueries-not-using-indexes, as described later.
The time to acquire the initial locks is not counted as execution time. mysqld writes a statement to the
slow query log after it has been executed and after all locks have been released, so log order might
differ from execution order.
To enable the slow query log, start mysqld with the --log-slow-queries[=file_name] option.
If the slow query log file is enabled but no name is specified, the default name is host_nameslow.log and the server creates the file in the same directory where it creates the PID file. If a name
is given, the server creates the file in the data directory unless an absolute path name is given to
specify a different directory.
To include slow administrative statements in the statements written to the slow query log, use the -log-slow-admin-statements server option. Administrative statements include ALTER TABLE,
ANALYZE TABLE, CHECK TABLE, CREATE INDEX, DROP INDEX, OPTIMIZE TABLE, and REPAIR
TABLE.
To include queries that do not use indexes for row lookups in the statements written to the slow query
log, use the --log-queries-not-using-indexes server option. See Section 5.1.3, “Server
Command Options”. When such queries are logged, the slow query log may grow quickly.
The server uses the controlling parameters in the following order to determine whether to write a query
to the slow query log:
1. The query must either not be an administrative statement, or --log-slow-admin-statements
must have been specified.
2. The query must have taken at least long_query_time seconds, or --log-queries-notusing-indexes must have been specified and the query used no indexes for row lookups.
The server does not write queries handled by the query cache to the slow query log, nor queries that
would not benefit from the presence of an index because the table has zero rows or one row.
Replication slaves do not write replicated queries to the slow query log, even if the same queries were
written to the slow query log on the master. This is a known issue. (Bug #23300)
The slow query log should be protected because logged statements might contain passwords. See
Section 6.1.2.3, “Passwords and Logging”.
The slow query log can be used to find queries that take a long time to execute and are therefore
candidates for optimization. However, examining a long slow query log can become a difficult task.
To make this easier, you can process a slow query log file using the mysqldumpslow command to
summarize the queries that appear in the log. See Section 4.6.8, “mysqldumpslow — Summarize
Slow Query Log Files”.

5.4.5 Server Log Maintenance
As described in Section 5.4, “MySQL Server Logs”, MySQL Server can create several different log files
to help you see what activity is taking place. However, you must clean up these files regularly to ensure
that the logs do not take up too much disk space.
When using MySQL with logging enabled, you may want to back up and remove old log files from time
to time and tell MySQL to start logging to new files. See Section 7.2, “Database Backup Methods”.
On a Linux (Red Hat) installation, you can use the mysql-log-rotate script for this. If you installed
MySQL from an RPM distribution, this script should have been installed automatically. Be careful with
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on One Machine

this script if you are using the binary log for replication. You should not remove binary logs until you are
certain that their contents have been processed by all slaves.
On other systems, you must install a short script yourself that you start from cron (or its equivalent) for
handling log files.
For the binary log, you can set the expire_logs_days system variable to expire binary log files
automatically after a given number of days (see Section 5.1.4, “Server System Variables”). If you
are using replication, you should set the variable no lower than the maximum number of days your
slaves might lag behind the master. To remove binary logs on demand, use the PURGE BINARY LOGS
statement (see Section 13.4.1.1, “PURGE BINARY LOGS Syntax”).
You can force MySQL to start using new log files by flushing the logs. Log flushing occurs when you
issue a FLUSH LOGS statement or execute a mysqladmin flush-logs, mysqladmin refresh,
mysqldump --flush-logs, or mysqldump --master-data command. See Section 13.7.6.2,
“FLUSH Syntax”, Section 4.5.2, “mysqladmin — Client for Administering a MySQL Server”, and
Section 4.5.4, “mysqldump — A Database Backup Program”. In addition, the binary log is flushed
when its size reaches the value of the max_binlog_size system variable.
A log-flushing operation does the following:
• If general query logging (--log) or slow query logging (--log-slow-queries) to a log file is
enabled, the server closes and reopens the general query log file or slow query log file.
• If binary logging (--log-bin) is used, the server closes the current log file and opens a new log file
with the next sequence number.
• If the server was started with the --log-error option to cause the error log to be written to a file, it
renames the current log file with the suffix -old and creates a new empty error log file.
The server creates a new binary log file when you flush the logs. However, it just closes and reopens
the general and slow query log files. To cause new files to be created on Unix, rename the current log
files before flushing them. At flush time, the server opens new log files with the original names. For
example, if the general and slow query log files are named mysql.log and mysql-slow.log, you
can use a series of commands like this:
shell>
shell>
shell>
shell>

cd mysql-data-directory
mv mysql.log mysql.old
mv mysql-slow.log mysql-slow.old
mysqladmin flush-logs

On Windows, use rename rather than mv.
At this point, you can make a backup of mysql.old and mysql-slow.old and then remove them
from disk.
For older versions of MySQL, you cannot rename certain log files on Windows while the server has
them open. Before MySQL 5.0.17, this restriction applies to all log files. You must stop the server,
rename the file, then restart the server to create a new log file. From 5.0.18 on, the restriction applies
only to the error log file. To rename the error log file, a stop and restart can be avoided by flushing the
logs to cause the server to rename the current log file with the suffix -old and create a new empty
error log file.
To disable or enable general query logging for the current connection, set the session sql_log_off
variable to ON or OFF.

5.5 Running Multiple MySQL Instances on One Machine
In some cases, you might want to run multiple instances of MySQL on a single machine. You might
want to test a new MySQL release while leaving an existing production setup undisturbed. Or you
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on One Machine

might want to give different users access to different mysqld servers that they manage themselves.
(For example, you might be an Internet Service Provider that wants to provide independent MySQL
installations for different customers.)
It is possible to use a different MySQL server binary per instance, or use the same binary for multiple
instances, or any combination of the two approaches. For example, you might run a server from
MySQL 4.1 and one from MySQL 5.0, to see how different versions handle a given workload. Or
you might run multiple instances of the current production version, each managing a different set of
databases.
Whether or not you use distinct server binaries, each instance that you run must be configured with
unique values for several operating parameters. This eliminates the potential for conflict between
instances. Parameters can be set on the command line, in option files, or by setting environment
variables. See Section 4.2.3, “Specifying Program Options”. To see the values used by a given
instance, connect to it and execute a SHOW VARIABLES statement.
The primary resource managed by a MySQL instance is the data directory. Each instance should use a
different data directory, the location of which is specified using the --datadir=dir_name option. For
methods of configuring each instance with its own data directory, and warnings about the dangers of
failing to do so, see Section 5.5.1, “Setting Up Multiple Data Directories”.
In addition to using different data directories, several other options must have different values for each
server instance:
• --port=port_num
--port controls the port number for TCP/IP connections. Alternatively, if the host has multiple
network addresses, you can use --bind-address to cause each server to listen to a different
address.
• --socket={file_name|pipe_name}
--socket controls the Unix socket file path on Unix or the named pipe name on Windows. On
Windows, it is necessary to specify distinct pipe names only for those servers configured to permit
named-pipe connections.
• --shared-memory-base-name=name
This option is used only on Windows. It designates the shared-memory name used by a Windows
server to permit clients to connect using shared memory. It is necessary to specify distinct sharedmemory names only for those servers configured to permit shared-memory connections.
• --pid-file=file_name
This option indicates the path name of the file in which the server writes its process ID.
If you use the following log file options, their values must differ for each server:
• --log[=file_name]
• --log-bin[=file_name]
• --log-error[=file_name]
• --bdb-logdir=file_name
For further discussion of log file options, see Section 5.4, “MySQL Server Logs”.
To achieve better performance, you can specify the following options differently for each server, to
spread the load between several physical disks:
• --tmpdir=dir_name
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Setting Up Multiple Data Directories

• --bdb-tmpdir=dir_name
Having different temporary directories also makes it easier to determine which MySQL server created
any given temporary file.
If you have multiple MySQL installations in different locations, you can specify the base directory for
each installation with the --basedir=dir_name option. This causes each instance to automatically
use a different data directory, log files, and PID file because the default for each of those parameters
is relative to the base directory. In that case, the only other options you need to specify are the -socket and --port options. Suppose that you install different versions of MySQL using tar file
binary distributions. These install in different locations, so you can start the server for each installation
using the command bin/mysqld_safe under its corresponding base directory. mysqld_safe
determines the proper --basedir option to pass to mysqld, and you need specify only the -socket and --port options to mysqld_safe.
As discussed in the following sections, it is possible to start additional servers by specifying appropriate
command options or by setting environment variables. However, if you need to run multiple servers
on a more permanent basis, it is more convenient to use option files to specify for each server those
option values that must be unique to it. The --defaults-file option is useful for this purpose.

5.5.1 Setting Up Multiple Data Directories
Each MySQL Instance on a machine should have its own data directory. The location is specified using
the --datadir=dir_name option.
There are different methods of setting up a data directory for a new instance:
• Create a new data directory.
• Copy an existing data directory.
The following discussion provides more detail about each method.
Warning
Normally, you should never have two servers that update data in the same
databases. This may lead to unpleasant surprises if your operating system does
not support fault-free system locking. If (despite this warning) you run multiple
servers using the same data directory and they have logging enabled, you must
use the appropriate options to specify log file names that are unique to each
server. Otherwise, the servers try to log to the same files.
Even when the preceding precautions are observed, this kind of setup works
only with MyISAM and MERGE tables, and not with any of the other storage
engines. Also, this warning against sharing a data directory among servers
always applies in an NFS environment. Permitting multiple MySQL servers
to access a common data directory over NFS is a very bad idea. The primary
problem is that NFS is the speed bottleneck. It is not meant for such use.
Another risk with NFS is that you must devise a way to ensure that two or more
servers do not interfere with each other. Usually NFS file locking is handled
by the lockd daemon, but at the moment there is no platform that performs
locking 100% reliably in every situation.

Create a New Data Directory
With this method, the data directory will be in the same state as when you first install MySQL. It will
have the default set of MySQL accounts and no user data.
On Unix, initialize the data directory. See Section 2.18, “Postinstallation Setup and Testing”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on Windows

On Windows, the data directory is included in MySQL distributions. If you obtain a distribution in
Windows Zip archive format, you can unpack it into a temporary location, then copy the data directory
from this location to where you are setting up the new instance.

Copy an Existing Data Directory
With this method, any MySQL accounts or user data present in the data directory are carried over to
the new data directory.
1. Stop the existing MySQL instance using the data directory. This must be a clean shutdown so that
the instance flushes any pending changes to disk.
2. Copy the data directory to the location where the new data directory should be.
3. Copy the my.cnf or my.ini option file used by the existing instance. This serves as a basis for
the new instance.
4. Modify the new option file so that any pathnames referring to the original data directory refer to the
new data directory. Also, modify any other options that must be unique per instance, such as the
TCP/IP port number and the log files. For a list of parameters that must be unique per instance, see
Section 5.5, “Running Multiple MySQL Instances on One Machine”.
5. Start the new instance, telling it to use the new option file.

5.5.2 Running Multiple MySQL Instances on Windows
You can run multiple servers on Windows by starting them manually from the command line, each with
appropriate operating parameters, or by installing several servers as Windows services and running
them that way. General instructions for running MySQL from the command line or as a service are
given in Section 2.10, “Installing MySQL on Microsoft Windows”. The following sections describe how
to start each server with different values for those options that must be unique per server, such as the
data directory. These options are listed in Section 5.5, “Running Multiple MySQL Instances on One
Machine”.

5.5.2.1 Starting Multiple MySQL Instances at the Windows Command Line
The procedure for starting a single MySQL server manually from the command line is described
in Section 2.10.4.5, “Starting MySQL from the Windows Command Line”. To start multiple servers
this way, you can specify the appropriate options on the command line or in an option file. It is more
convenient to place the options in an option file, but it is necessary to make sure that each server gets
its own set of options. To do this, create an option file for each server and tell the server the file name
with a --defaults-file option when you run it.
Suppose that you want to run mysqld on port 3307 with a data directory of C:\mydata1, and
mysqld-debug on port 3308 with a data directory of C:\mydata2. Use this procedure:
1. Make sure that each data directory exists, including its own copy of the mysql database that
contains the grant tables.
2. Create two option files. For example, create one file named C:\my-opts1.cnf that looks like this:
[mysqld]
datadir = C:/mydata1
port = 3307

Create a second file named C:\my-opts2.cnf that looks like this:
[mysqld]
datadir = C:/mydata2
port = 3308

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on Windows

3. Use the --defaults-file option to start each server with its own option file:
C:\> C:\mysql\bin\mysqld --defaults-file=C:\my-opts1.cnf
C:\> C:\mysql\bin\mysqld-debug --defaults-file=C:\my-opts2.cnf

Each server starts in the foreground (no new prompt appears until the server exits later), so you will
need to issue those two commands in separate console windows.
To shut down the servers, connect to each using the appropriate port number:
C:\> C:\mysql\bin\mysqladmin --port=3307 --host=127.0.0.1 --user=root --password shutdown
C:\> C:\mysql\bin\mysqladmin --port=3308 --host=127.0.0.1 --user=root --password shutdown

Servers configured as just described permit clients to connect over TCP/IP. If your version of Windows
supports named pipes and you also want to permit named-pipe connections, use the mysqld-nt or
mysqld-debug server and specify options that enable the named pipe and specify its name. Each
server that supports named-pipe connections must use a unique pipe name. For example, the C:\myopts1.cnf file might be written like this:
[mysqld]
datadir = C:/mydata1
port = 3307
enable-named-pipe
socket = mypipe1

Modify C:\my-opts2.cnf similarly for use by the second server. Then start the servers as described
previously.
A similar procedure applies for servers that you want to permit shared-memory connections. Enable
such connections with the --shared-memory option and specify a unique shared-memory name for
each server with the --shared-memory-base-name option.

5.5.2.2 Starting Multiple MySQL Instances as Windows Services
On Windows, a MySQL server can run as a Windows service. The procedures for installing, controlling,
and removing a single MySQL service are described in Section 2.10.4.7, “Starting MySQL as a
Windows Service”.
To set up multiple MySQL services, you must make sure that each instance uses a different service
name in addition to the other parameters that must be unique per instance.
For the following instructions, suppose that you want to run the mysqld-nt server from two different
versions of MySQL that are installed at C:\mysql-4.1.24 and C:\mysql-5.0.96, respectively.
(This might be the case if you're running 4.1.24 as your production server, but also want to conduct
tests using 5.0.96.)
To install MySQL as a Windows service, use the --install or --install-manual option. For
information about these options, see Section 2.10.4.7, “Starting MySQL as a Windows Service”.
Based on the preceding information, you have several ways to set up multiple services. The following
instructions describe some examples. Before trying any of them, shut down and remove any existing
MySQL services.
• Approach 1: Specify the options for all services in one of the standard option files. To do this, use a
different service name for each server. Suppose that you want to run the 4.1.24 mysqld-nt using
the service name of mysqld1 and the 5.0.96 mysqld-nt using the service name mysqld2. In
this case, you can use the [mysqld1] group for 4.1.24 and the [mysqld2] group for 5.0.96. For
example, you can set up C:\my.cnf like this:
# options for mysqld1 service
[mysqld1]

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on Windows

basedir = C:/mysql-4.1.24
port = 3307
enable-named-pipe
socket = mypipe1
# options for mysqld2 service
[mysqld2]
basedir = C:/mysql-5.0.96
port = 3308
enable-named-pipe
socket = mypipe2

Install the services as follows, using the full server path names to ensure that Windows registers the
correct executable program for each service:
C:\> C:\mysql-4.1.24\bin\mysqld-nt --install mysqld1
C:\> C:\mysql-5.0.96\bin\mysqld-nt --install mysqld2

To start the services, use the services manager, or use NET START with the appropriate service
names:
C:\> NET START mysqld1
C:\> NET START mysqld2

To stop the services, use the services manager, or use NET STOP with the appropriate service
names:
C:\> NET STOP mysqld1
C:\> NET STOP mysqld2

• Approach 2: Specify options for each server in separate files and use --defaults-file when
you install the services to tell each server what file to use. In this case, each file should list options
using a [mysqld] group.
With this approach, to specify options for the 4.1.24 mysqld-nt, create a file C:\my-opts1.cnf
that looks like this:
[mysqld]
basedir = C:/mysql-4.1.24
port = 3307
enable-named-pipe
socket = mypipe1

For the 5.0.96 mysqld-nt, create a file C:\my-opts2.cnf that looks like this:
[mysqld]
basedir = C:/mysql-5.0.96
port = 3308
enable-named-pipe
socket = mypipe2

Install the services as follows (enter each command on a single line):
C:\> C:\mysql-4.1.24\bin\mysqld-nt --install mysqld1
--defaults-file=C:\my-opts1.cnf
C:\> C:\mysql-5.0.96\bin\mysqld-nt --install mysqld2
--defaults-file=C:\my-opts2.cnf

When you install a MySQL server as a service and use a --defaults-file option, the service
name must precede the option.
After installing the services, start and stop them the same way as in the preceding example.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Running Multiple MySQL Instances on Unix

To remove multiple services, use mysqld --remove for each one, specifying a service name
following the --remove option. If the service name is the default (MySQL), you can omit it.

5.5.3 Running Multiple MySQL Instances on Unix
One way is to run multiple MySQL instances on Unix is to compile different servers with different
default TCP/IP ports and Unix socket files so that each one listens on different network interfaces.
Compiling in different base directories for each installation also results automatically in a separate,
compiled-in data directory, log file, and PID file location for each server.
Assume that an existing 4.1 server is configured for the default TCP/IP port number (3306) and
Unix socket file (/tmp/mysql.sock). To configure a new 5.0.96 server to have different operating
parameters, use a configure command something like this:
shell> ./configure --with-tcp-port=port_number \
--with-unix-socket-path=file_name \
--prefix=/usr/local/mysql-5.0.96

Here, port_number and file_name must be different from the default TCP/IP port number and Unix
socket file path name, and the --prefix value should specify an installation directory different from
the one under which the existing MySQL installation is located.
If you have a MySQL server listening on a given port number, you can use the following command to
find out what operating parameters it is using for several important configurable variables, including the
base directory and Unix socket file name:
shell> mysqladmin --host=host_name --port=port_number variables

With the information displayed by that command, you can tell what option values not to use when
configuring an additional server.
If you specify localhost as the host name, mysqladmin defaults to using a Unix socket
file connection rather than TCP/IP. To explicitly specify the connection protocol, use the -protocol={TCP|SOCKET|PIPE|MEMORY} option.
You need not compile a new MySQL server just to start with a different Unix socket file and TCP/IP port
number. It is also possible to use the same server binary and start each invocation of it with different
parameter values at runtime. One way to do so is by using command-line options:
shell> mysqld_safe --socket=file_name --port=port_number

To start a second server, provide different --socket and --port option values, and pass a -datadir=dir_name option to mysqld_safe so that the server uses a different data directory.
Alternatively, put the options for each server in a different option file, then start each server using a -defaults-file option that specifies the path to the appropriate option file. For example, if the option
files for two server instances are named /usr/local/mysql/my.cnf and /usr/local/mysql/
my.cnf2, start the servers like this: command:
shell> mysqld_safe --defaults-file=/usr/local/mysql/my.cnf
shell> mysqld_safe --defaults-file=/usr/local/mysql/my.cnf2

Another way to achieve a similar effect is to use environment variables to set the Unix socket file name
and TCP/IP port number:
shell>
shell>
shell>
shell>

This
documentation
is for an
older version.
If you're

MYSQL_UNIX_PORT=/tmp/mysqld-new.sock
MYSQL_TCP_PORT=3307
export MYSQL_UNIX_PORT MYSQL_TCP_PORT
mysql_install_db --user=mysql

This
documentation
is for an
older version.
If you're

Using Client Programs in a Multiple-Server Environment

shell> mysqld_safe --datadir=/path/to/datadir &

This is a quick way of starting a second server to use for testing. The nice thing about this method is
that the environment variable settings apply to any client programs that you invoke from the same shell.
Thus, connections for those clients are automatically directed to the second server.
Section 2.21, “Environment Variables”, includes a list of other environment variables you can use to
affect MySQL programs.
On Unix, the mysqld_multi script provides another way to start multiple servers. See Section 4.3.4,
“mysqld_multi — Manage Multiple MySQL Servers”.

5.5.4 Using Client Programs in a Multiple-Server Environment
To connect with a client program to a MySQL server that is listening to different network interfaces from
those compiled into your client, you can use one of the following methods:
• Start the client with --host=host_name --port=port_number to connect using TCP/IP to a
remote server, with --host=127.0.0.1 --port=port_number to connect using TCP/IP to a
local server, or with --host=localhost --socket=file_name to connect to a local server using
a Unix socket file or a Windows named pipe.
• Start the client with --protocol=TCP to connect using TCP/IP, --protocol=SOCKET to
connect using a Unix socket file, --protocol=PIPE to connect using a named pipe, or -protocol=MEMORY to connect using shared memory. For TCP/IP connections, you may also need
to specify --host and --port options. For the other types of connections, you may need to specify
a --socket option to specify a Unix socket file or Windows named-pipe name, or a --sharedmemory-base-name option to specify the shared-memory name. Shared-memory connections are
supported only on Windows.
•

On Unix, set the MYSQL_UNIX_PORT and MYSQL_TCP_PORT environment variables to point to the
Unix socket file and TCP/IP port number before you start your clients. If you normally use a specific
socket file or port number, you can place commands to set these environment variables in your
.login file so that they apply each time you log in. See Section 2.21, “Environment Variables”.

•

Specify the default Unix socket file and TCP/IP port number in the [client] group of an option
file. For example, you can use C:\my.cnf on Windows, or the .my.cnf file in your home directory
on Unix. See Section 4.2.6, “Using Option Files”.

• In a C program, you can specify the socket file or port number arguments in the
mysql_real_connect() call. You can also have the program read option files by calling
mysql_options(). See Section 20.6.7, “C API Function Descriptions”.
• If you are using the Perl DBD::mysql module, you can read options from MySQL option files. For
example:
$dsn = "DBI:mysql:test;mysql_read_default_group=client;"
. "mysql_read_default_file=/usr/local/mysql/data/my.cnf";
$dbh = DBI->connect($dsn, $user, $password);

See Section 20.8, “MySQL Perl API”.
Other programming interfaces may provide similar capabilities for reading option files.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 6 Security
Table of Contents
6.1 General Security Issues ......................................................................................................
6.1.1 Security Guidelines ...................................................................................................
6.1.2 Keeping Passwords Secure ......................................................................................
6.1.3 Making MySQL Secure Against Attackers ..................................................................
6.1.4 Security-Related mysqld Options and Variables .........................................................
6.1.5 How to Run MySQL as a Normal User ......................................................................
6.1.6 Security Issues with LOAD DATA LOCAL ..................................................................
6.1.7 Client Programming Security Guidelines ....................................................................
6.2 The MySQL Access Privilege System ..................................................................................
6.2.1 Privileges Provided by MySQL ..................................................................................
6.2.2 Grant Tables ............................................................................................................
6.2.3 Specifying Account Names .......................................................................................
6.2.4 Access Control, Stage 1: Connection Verification .......................................................
6.2.5 Access Control, Stage 2: Request Verification ...........................................................
6.2.6 When Privilege Changes Take Effect ........................................................................
6.2.7 Troubleshooting Problems Connecting to MySQL .......................................................
6.3 MySQL User Account Management .....................................................................................
6.3.1 User Names and Passwords .....................................................................................
6.3.2 Adding User Accounts ..............................................................................................
6.3.3 Removing User Accounts .........................................................................................
6.3.4 Setting Account Resource Limits ...............................................................................
6.3.5 Assigning Account Passwords ...................................................................................
6.3.6 Using Secure Connections ........................................................................................
6.3.7 Creating SSL Certificates and Keys Using openssl .....................................................
6.3.8 Connecting to MySQL Remotely from Windows with SSH ...........................................
6.3.9 SQL-Based MySQL Account Activity Auditing ............................................................

577
578
579
587
588
589
590
591
592
593
597
601
603
606
608
608
613
613
615
618
618
620
621
629
634
634

When thinking about security within a MySQL installation, you should consider a wide range of possible
topics and how they affect the security of your MySQL server and related applications:
• General factors that affect security. These include choosing good passwords, not granting
unnecessary privileges to users, ensuring application security by preventing SQL injections and data
corruption, and others. See Section 6.1, “General Security Issues”.
• Security of the installation itself. The data files, log files, and the all the application files of your
installation should be protected to ensure that they are not readable or writable by unauthorized
parties. For more information, see Section 2.18, “Postinstallation Setup and Testing”.
• Access control and security within the database system itself, including the users and databases
granted with access to the databases, views and stored programs in use within the database. For
more information, see Section 6.2, “The MySQL Access Privilege System”, and Section 6.3, “MySQL
User Account Management”.
• Network security of MySQL and your system. The security is related to the grants for individual
users, but you may also wish to restrict MySQL so that it is available only locally on the MySQL
server host, or to a limited set of other hosts.
• Ensure that you have adequate and appropriate backups of your database files, configuration
and log files. Also be sure that you have a recovery solution in place and test that you are able to
successfully recover the information from your backups. See Chapter 7, Backup and Recovery.

6.1 General Security Issues
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Security Guidelines

This section describes 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 6.2, “The MySQL Access Privilege System”.
For answers to some questions that are often asked about MySQL Server security issues, see
Section A.9, “MySQL 5.0 FAQ: Security”.

6.1.1 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, it is necessary to consider 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 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:
• Do not ever give anyone (except MySQL root accounts) access to the user table in the
mysql database! This is critical.
• Learn how the MySQL access privilege system works (see Section 6.2, “The MySQL Access
Privilege System”). Use the GRANT and REVOKE statements to control access to MySQL. Do not
grant 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, anyone can connect to your MySQL server as the MySQL root user with full
privileges! Review the MySQL installation instructions, paying particular attention to the information
about setting a root password. See Section 2.18.4, “Securing the Initial MySQL Accounts”.
• Use the SHOW GRANTS statement to check which accounts have access to what. Then use the
REVOKE statement to remove those privileges that are not necessary.
• Do not store cleartext passwords in your database. If your computer becomes compromised, the
intruder can take the full list of passwords and use them. Instead, use SHA1(), MD5(), or some
other one-way hashing function and store the hash value.
To prevent password recovery using rainbow tables, do not use these functions on a plain password;
instead, choose some string to be used as a salt, and use hash(hash(password)+salt) values.
• Do not choose passwords from dictionaries. Special programs exist to break passwords. 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
a password that is taken from the first characters of each word in a sentence (for example, “Four
score and seven years ago” results in a password of “Fsasya”). The password is easy to remember
and type, but difficult to guess for someone who does not know the sentence. In this case, you can
additionally substitute digits for the number words to obtain the phrase “4 score and 7 years ago”,
yielding the password “4sa7ya” which is even more difficult to guess.
• 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:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

• 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. As a simple way to check
whether your MySQL port is open, try the following command from some remote machine, where
server_host is the host name or IP address of the host on which your MySQL server runs:
shell> telnet server_host 3306

If telnet hangs or the connection is refused, the port is blocked, which is how you want it to be.
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.
• Applications that access MySQL should not trust any data entered by users, and should be written
using proper defensive programming techniques. See Section 6.1.7, “Client Programming Security
Guidelines”.
• 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. Another
technique is to use SSH port-forwarding to create an encrypted (and compressed) tunnel for the
communication.
• Learn to use the tcpdump and strings utilities. In 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 cleartext data, this does not always mean that the
information actually is encrypted. If you need high security, consult with a
security expert.

6.1.2 Keeping Passwords Secure
Passwords occur in several contexts within MySQL. The following sections provide guidelines that
enable end users and administrators to keep these passwords secure and avoid exposing them. There
is also a discussion of how MySQL uses password hashing internally.

6.1.2.1 End-User Guidelines for Password Security
MySQL users should use the following guidelines to keep passwords secure.
When you run a client program to connect to the MySQL server, it is inadvisable to specify your
password in a way that exposes it to discovery by other users. The methods you can use to specify
your password when you run client programs are listed here, along with an assessment of the risks of
each method. In short, the safest methods are to have the client program prompt for the password or to
specify the password in a properly protected option file.
•

Use a -pyour_pass or --password=your_pass option on the command line. For example:
shell> mysql -u francis -pfrank db_name

This is convenient but insecure. On some systems, your password becomes visible to system
status programs such as ps that may be invoked by other users to display command lines. MySQL
clients typically overwrite the command-line password argument with zeros during their initialization
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

sequence. However, there is still a brief interval during which the value is visible. Also, on some
systems this overwriting strategy is ineffective and the password remains visible to ps. (SystemV
Unix systems and perhaps others are subject to this problem.)
If your operating environment is set up to display your current command in the title bar of your
terminal window, the password remains visible as long as the command is running, even if the
command has scrolled out of view in the window content area.
• Use the -p or --password option on the command line with no password value specified. In this
case, the client program solicits the password interactively:
shell> mysql -u francis -p db_name
Enter password: ********

The “*” characters indicate where you enter your password. The password is not displayed as you
enter it.
It is more secure to enter your password this way than to specify it on the command line because it is
not visible to other users. However, this method of entering a password is suitable only for programs
that you run interactively. If you want to invoke a client from a script that runs noninteractively, there
is no opportunity to enter the password from the keyboard. On some systems, you may even find
that the first line of your script is read and interpreted (incorrectly) as your password.
• Store your password in an option file. For example, on Unix, you can list your password in the
[client] section of the .my.cnf file in your home directory:
[client]
password=your_pass

To keep the password safe, the file should not be accessible to anyone but yourself. To ensure this,
set the file access mode to 400 or 600. For example:
shell> chmod 600 .my.cnf

To name from the command line a specific option file containing the password, use the -defaults-file=file_name option, where file_name is the full path name to the file. For
example:
shell> mysql --defaults-file=/home/francis/mysql-opts

Section 4.2.6, “Using Option Files”, discusses option files in more detail.
• Store your password in the MYSQL_PWD environment variable. See Section 2.21, “Environment
Variables”.
This method of specifying your MySQL password must be considered extremely insecure and should
not be used. Some versions of ps include an option to display the environment of running processes.
On some systems, if you set MYSQL_PWD, your password is exposed to any other user who runs
ps. Even on systems without such a version of ps, it is unwise to assume that there are no other
methods by which users can examine process environments.

On Unix, the mysql client writes a record of executed statements to a history file (see Section 4.5.1.3,
“mysql Logging”). By default, this file is named .mysql_history and is created in your home
directory. Passwords can be written as plain text in SQL statements such as CREATE USER, GRANT,
and SET PASSWORD, so if you use these statements, they are logged in the history file. To keep this file
safe, use a restrictive access mode, the same way as described earlier for the .my.cnf file.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

If your command interpreter is configured to maintain a history, any file in which the commands
are saved will contain MySQL passwords entered on the command line. For example, bash uses
~/.bash_history. Any such file should have a restrictive access mode.

6.1.2.2 Administrator Guidelines for Password Security
Database administrators should use the following guidelines to keep passwords secure.
MySQL stores passwords for user accounts in the mysql.user table. Access to this table should
never be granted to any nonadministrative accounts.
A user who has access to modify the plugin directory (the value of the plugin_dir system variable)
or the my.cnf file that specifies the location of the plugin directory can replace plugins and modify the
capabilities provided by plugins.
Files such as log files to which passwords might be written should be protected. See Section 6.1.2.3,
“Passwords and Logging”.

6.1.2.3 Passwords and Logging
Passwords can be written as plain text in SQL statements such as CREATE USER, GRANT, SET
PASSWORD, and statements that invoke the PASSWORD() function. If such statements are logged by
the MySQL server as written, passwords in them become visible to anyone with access to the logs.
This applies to the general query log, the slow query log, and the binary log (see Section 5.4, “MySQL
Server Logs”).
To guard log files against unwarranted exposure, locate them in a directory that restricts access to the
server and the database administrator.
Replication slaves store the password for the replication master in the master.info file. Retrict this
file to be accessible only to the database administrator.
Use a restricted access mode to protect database backups that include log files containing passwords.

6.1.2.4 Password Hashing in MySQL
MySQL lists user accounts in the user table of the mysql database. Each MySQL account can be
assigned a password, although the user table does not store the cleartext version of the password, but
a hash value computed from it.
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 the client wants to use.
• After the client connects, it can (if it has sufficient privileges) set or change the password hash
for accounts listed in the user table. The client can do this by using the PASSWORD() function to
generate a password hash, or by using a password-generating statement (CREATE USER, GRANT, or
SET PASSWORD).
In other words, the server checks 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 password-generating statement to set or change a password.
Password hashing methods in MySQL have the history described following. These changes are
illustrated by changes in the result from the PASSWORD() function that computes password hash
values and in the structure of the user table where passwords are stored.
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”
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

release because it has a slightly different method than that implemented in 4.1.1
and up. Differences between 4.1.0 and more recent versions are described
further in MySQL 3.23, 4.0, 4.1 Reference Manual.

The Original (Pre-4.1) Hashing Method
The original hashing method produced a 16-byte string. Such hashes look like this:
mysql> SELECT PASSWORD('mypass');
+--------------------+
| PASSWORD('mypass') |
+--------------------+
| 6f8c114b58f2ce9e
|
+--------------------+

To store account passwords, the Password column of the user table was at this point 16 bytes long.

The 4.1 Hashing Method
MySQL 4.1 introduced password hashing that provided better security and reduced the risk of
passwords being intercepted. There were several aspects to this change:
• Different format of password values produced by the PASSWORD() function
• Widening of the Password column
• Control over the default hashing method
• Control over the permitted hashing methods for clients attempting to connect to the server
The changes in MySQL 4.1 took place in two stages:
• MySQL 4.1.0 used a preliminary version of the 4.1 hashing method. This method was short lived and
the following discussion says nothing more about it.
• In MySQL 4.1.1, the hashing method was modified to produce a longer 41-byte hash value:
mysql> SELECT PASSWORD('mypass');
+-------------------------------------------+
| PASSWORD('mypass')
|
+-------------------------------------------+
| *6C8989366EAF75BB670AD8EA7A7FC1176A95CEF4 |
+-------------------------------------------+

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.
To accommodate longer password hashes, the Password column in the user table was changed at
this point to be 41 bytes, its current length.
A widened Password column can store password hashes in both the pre-4.1 and 4.1 formats. The
format of any given hash value can be determined two ways:
• The length: 4.1 and pre-4.1 hashes are 41 and 16 bytes, respectively.
• Password hashes in the 4.1 format always begin with a “*” character, whereas passwords in the
pre-4.1 format never do.
To permit explicit generation of pre-4.1 password hashes, two additional changes were made:
• The OLD_PASSWORD() function was added, which returns hash values in the 16-byte format.
• For compatibility purposes, the old_passwords system variable was added, to enable DBAs and
applications control over the hashing method. The default old_passwords value of 0 causes

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

hashing to use the 4.1 method (41-byte hash values), but setting old_passwords=1 causes
hashing to use the pre-4.1 method. In this case, PASSWORD() produces 16-byte values and is
equivalent to OLD_PASSWORD()
To permit DBAs control over how clients are permitted to connect, the secure_auth system
variable was added. Starting the server with this variable disabled or enabled permits or prohibits
clients to connect using the older pre-4.1 password hashing method. Before MySQL 5.6.5,
secure_auth is disabled by default. As of 5.6.5, secure_auth is enabled by default to promote
a more secure default configuration. (DBAs can disable it at their discretion, but this is not
recommended.)
In addition, the mysql client supports a --secure-auth option that is analogous to secure_auth,
but from the client side. It can be used to prevent connections to less secure accounts that
use pre-4.1 password hashing. This option is disabled by default before MySQL 5.6.7, enabled
thereafter.

Compatibility Issues Related to Hashing Methods
The widening of the Password column in MySQL 4.1 from 16 bytes to 41 bytes affects installation or
upgrade operations as follows:
• If you perform a new installation of MySQL, the Password column is made 41 bytes long
automatically.
• Upgrades from MySQL 4.1 or later to current versions of MySQL should not give rise to any issues in
regard to the Password column because both versions use the same column length and password
hashing method.
• For upgrades from a pre-4.1 release to 4.1 or later, you must upgrade the system tables after
upgrading. (See Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.)
The 4.1 hashing method is understood only by MySQL 4.1 (and newer) servers and clients, which can
result in some compatibility problems. A 4.1 or newer client can connect to a pre-4.1 server, because
the client understands both the pre-4.1 and 4.1 password hashing methods. However, a pre-4.1 client
that attempts to connect to a 4.1 or newer server may run into difficulties. For example, a 4.0 mysql
client 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

This phenomenon also occurs for attempts to use the older PHP mysql extension after upgrading to
MySQL 4.1 or newer. (See Common Problems with MySQL and PHP.)
The following discussion describes the differences between the pre-4.1 and 4.1 hashing methods,
and what you should do if you upgrade your server but need to maintain backward compatibility with
pre-4.1 clients. (However, permitting connections by old clients is not recommended and should be
avoided if possible.) Additional information can be found in Section B.5.2.4, “Client does not support
authentication protocol”. This information is of particular importance to PHP programmers migrating
MySQL databases from versions older than 4.1 to 4.1 or higher.
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:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

• Pre-4.1 clients can connect, but because they know only about the pre-4.1 hashing method, they
can authenticate only using accounts that have short hashes.
• 4.1 and later clients can authenticate using accounts that have short or long hashes.
Even for short-hash accounts, the authentication process is actually a bit more secure for 4.1 and later
clients than for older clients. In terms of security, the gradient from least to most secure is:
• Pre-4.1 client authenticating with short password hash
• 4.1 or later client authenticating with short password hash
• 4.1 or later client authenticating 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 system variable. A 4.1 or later server generates
long hashes only if certain conditions are met: The Password column must be wide enough to hold
long values and old_passwords must not be set to 1.
Those 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
using the PASSWORD() function or a password-generating statement. This is the behavior that
occurs if you have upgraded from a version of MySQL older than 4.1 to 4.1 or later but have not yet
run the mysql_upgrade program to widen the Password column.
• If the Password column is wide, it can store either short or long password hashes. In this case, the
PASSWORD() function and password-generating statements generate long hashes unless the server
was started with the old_passwords system variable set to 1 to force the server to generate short
password hashes instead.
The purpose of the old_passwords system variable is to permit backward compatibility with pre-4.1
clients under circumstances where the server would otherwise generate long password hashes.
The option does not affect authentication (4.1 and later 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 permitted to occur, the account could no longer be used
by pre-4.1 clients. With old_passwords disabled, the following undesirable scenario is possible:
• An old pre-4.1 client connects to an account that has a short password hash.
• The client changes its own password. With old_passwords disabled, 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 has
a long password hash that requires the 4.1 hashing method during authentication. (Once an account
has a long password hash in the user table, only 4.1 and later 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 problematic to run a 4.1
or newer server without old_passwords set to 1. By running the server with old_passwords=1,
password-changing operations do not generate long password hashes and thus do not cause accounts
to become inaccessible to older clients. (Those clients cannot inadvertently lock themselves out by
changing their password and ending up with a long password hash.)
The downside of old_passwords=1 is that any passwords created or changed use short hashes,
even for 4.1 or later clients. Thus, you lose the additional security provided by long password hashes.
To create an account that has a long hash (for example, for use by 4.1 clients) or to change an existing
account to use a long password hash, an administrator can set the session value of old_passwords
set to 0 while leaving the global value set to 1:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

mysql> SET @@session.old_passwords = 0;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @@session.old_passwords, @@global.old_passwords;
+-------------------------+------------------------+
| @@session.old_passwords | @@global.old_passwords |
+-------------------------+------------------------+
|
0 |
1 |
+-------------------------+------------------------+
1 row in set (0.00 sec)
mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'newpass';
Query OK, 0 rows affected (0.03 sec)
mysql> SET PASSWORD FOR 'existinguser'@'localhost' = PASSWORD('existingpass');
Query OK, 0 rows affected (0.00 sec)

The following scenarios are possible in MySQL 4.1 or later. The factors are whether the Password
column is short or long, and, if long, whether the server is started with old_passwords enabled or
disabled.
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 the PASSWORD() function
or password-generating statements use short hashes exclusively. Any change to an account's
password results in that account having a short password hash.
• The value of old_passwords is irrelevant because with a short Password column, the server
generates only short password hashes anyway.
This scenario occurs when a pre-4.1 MySQL installation has been upgraded to 4.1 or later but
mysql_upgrade has not been run to upgrade the system tables in the mysql database. (This is not a
recommended configuration because it does not permit use of more secure 4.1 password hashing.)
Scenario 2: Long Password column; server started with old_passwords=1:
• Short or long hashes can be stored in the Password column.
• 4.1 and later 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 the PASSWORD() function
or password-generating statements use short hashes exclusively. Any change to an account's
password results in that account having a short password hash.
In this scenario, newly created accounts have short password hashes because old_passwords=1
prevents generation of long hashes. Also, if you create an account with a long hash before setting
old_passwords to 1, changing the account's password while old_passwords=1 results in the
account being given a short password, causing it to lose the security benefits of a longer hash.
To create a new account that has a long password hash, or to change the password of any existing
account to use a long hash, first set the session value of old_passwords set to 0 while leaving the
global value set to 1, as described previously.
In this scenario, the server has an up to date Password column, but is running with the default
password hashing method set to generate pre-4.1 hash values. This is not a recommended
configuration but may be useful during a transitional period in which pre-4.1 clients and passwords
are upgraded to 4.1 or later. When that has been done, it is preferable to run the server with
old_passwords=0 and secure_auth=1.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keeping Passwords Secure

Scenario 3: Long Password column; server started with old_passwords=0:
• Short or long hashes can be stored in the Password column.
• 4.1 and later clients can authenticate using accounts that have short or long hashes.
• Pre-4.1 clients can authenticate only using accounts that have short hashes.
• For connected clients, password hash-generating operations involving the PASSWORD() function or
password-generating statements 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 using the PASSWORD() function or a password-generating statement results in the account being
given a long password hash. From that point on, no pre-4.1 client can connect to the server using that
account. The client must upgrade to 4.1 or later.
If this is a problem, you can change a password in a special way. For example, normally you use SET
PASSWORD as follows to change an account password:
SET PASSWORD FOR 'some_user'@'some_host' = PASSWORD('mypass');

To change the password but create a short hash, use the OLD_PASSWORD() function instead:
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.
The disadvantages for each of the preceding scenarios may be summarized as follows:
In scenario 1, you cannot take advantage of longer hashes that provide more secure authentication.
In scenario 2, old_passwords=1 prevents accounts with short hashes from becoming inaccessible,
but password-changing operations cause accounts with long hashes to revert to short hashes unless
you take care to change the session value of old_passwords to 0 first.
In scenario 3, accounts with short hashes become inaccessible to pre-4.1 clients if you change their
passwords without explicitly using OLD_PASSWORD().
The best way to avoid compatibility problems related to short password hashes is to not use them:
• Upgrade all client programs to MySQL 4.1 or later.
• Run the server with old_passwords=0.
• Reset the password for any account with a short password hash to use a long password hash.
• For additional security, run the server with secure_auth=1.

6.1.2.5 Implications of Password Hashing Changes in MySQL 4.1 for Application
Programs
An upgrade to MySQL version 4.1 or later can cause compatibility issues 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 or later from a pre-4.1 version of MySQL and run the server under conditions
where it generates long password hashes, an application using PASSWORD() for its own passwords
breaks. The recommended course of action in such cases 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
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Making MySQL Secure Against Attackers

OLD_PASSWORD() function, which is provided for generate short hashes in the old format. However,
you should note that OLD_PASSWORD() may one day no longer be supported.
If the server is running with old_passwords=1, it generates short hashes and OLD_PASSWORD() is
equivalent to PASSWORD().
PHP programmers migrating their MySQL databases from version 4.0 or lower to version 4.1 or higher
should see MySQL and PHP.

6.1.3 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 still using pre-4.1.1-style passwords, the encryption
algorithm is not as strong as the newer algorithm. With some effort, a clever attacker who can sniff
the traffic between the client and the server can crack the password. (See Section 6.1.2.4, “Password
Hashing in MySQL”, for a discussion of the different password handling methods.)
All other information is transferred as text, and can be read by anyone who is able to watch the
connection. If the connection between the client and the server goes through an untrusted network, and
you are concerned about this, you can use the compressed protocol to make traffic much more difficult
to decipher. You can also use MySQL's internal SSL support to make the connection even more
secure. See Section 6.3.6, “Using Secure Connections”. Alternatively, 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/.
To make a MySQL system secure, you should strongly consider the following suggestions:
• Require all MySQL accounts to have a password. 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 user name to the client program. For example, anyone can use the 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 accounts have a password, connecting using another user's
account becomes much more difficult.
For a discussion of methods for setting passwords, see Section 6.3.5, “Assigning Account
Passwords”.
• Make sure that the only Unix user account with read or write privileges in the database directories is
the account that is used for running mysqld.
• Never run the MySQL server as the Unix root user. This is extremely dangerous, because any
user with the FILE privilege is able to cause the server to create files as root (for example,
~root/.bashrc). To prevent this, mysqld refuses to run as root unless that is specified explicitly
using the --user=root option.
mysqld can (and should) be run as an ordinary, unprivileged user instead. You can create a
separate Unix account named mysql to make everything even more secure. Use this account only
for administering MySQL. To start mysqld as a different Unix user, add a user option that specifies
the user name in the [mysqld] group of the my.cnf option file where you specify server options.
For example:
[mysqld]
user=mysql

This causes the server to start as the designated user whether you start it manually or by using
mysqld_safe or mysql.server. For more details, see Section 6.1.5, “How to Run MySQL as a
Normal User”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Security-Related mysqld Options and Variables

Running mysqld as a Unix user other than root does not mean that you need to change the root
user name in the user table. User names for MySQL accounts have nothing to do with user names
for Unix accounts.
• Do not grant the FILE privilege to nonadministrative users. Any user that has this privilege can
write a file anywhere in the file system with the privileges of the mysqld daemon. This includes
the server's data directory containing the files that implement the privilege tables. To make FILEprivilege operations a bit safer, files generated with SELECT ... INTO OUTFILE do not overwrite
existing files and are writable by everyone.
The FILE privilege may also be used to read any file that is world-readable or accessible to the Unix
user that the server runs as. With this privilege, you can read any file into a database table. This
could be abused, for example, by using LOAD DATA to load /etc/passwd into a table, which then
can be displayed with SELECT.
To limit the location in which files can be read and written, set the secure_file_priv system to a
specific directory. See Section 5.1.4, “Server System Variables”.
• Do not grant the PROCESS or SUPER privilege to nonadministrative users. The output of
mysqladmin processlist and SHOW PROCESSLIST shows the text of any statements
currently being executed, so any user who is permitted to see the server process list
might be able to see statements issued by other users such as UPDATE user SET
password=PASSWORD('not_secure').
mysqld reserves an extra connection for users who have the SUPER privilege, so that a MySQL
root user can log in and check server activity even if all normal connections are in use.
The SUPER privilege can be used to terminate client connections, change server operation by
changing the value of system variables, and control replication servers.
• Do not permit the use of symlinks to tables. (This capability can be disabled with the --skipsymbolic-links option.) This is especially important if you run mysqld as root, because anyone
that has write access to the server's data directory then could delete any file in the system! See
Section 8.12.4.2, “Using Symbolic Links for MyISAM Tables on Unix”.
• Stored programs and views should be written using the security guidelines discussed in
Section 18.5, “Access Control for Stored Programs and Views”.
• If you do not trust your DNS, you should use IP addresses rather than host names in the grant
tables. In any case, you should be very careful about creating grant table entries using host name
values that contain wildcards.
• If you want to restrict the number of connections permitted to a single account, you can do
so by setting the max_user_connections variable in mysqld. The GRANT statement also
supports resource control options for limiting the extent of server use permitted to an account. See
Section 13.7.1.3, “GRANT Syntax”.
• If the plugin directory is writable by the server, it may be possible for a user to write executable code
to a file in the directory using SELECT ... INTO DUMPFILE. This can be prevented by making
plugin_dir read only to the server or by setting --secure-file-priv to a directory where
SELECT writes can be made safely.

6.1.4 Security-Related mysqld Options and Variables
The following table shows mysqld options and system variables that affect security. For descriptions
of each of these, see Section 5.1.3, “Server Command Options”, and Section 5.1.4, “Server System
Variables”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Run MySQL as a Normal User

Table 6.1 Security Option/Variable Summary
Name

Cmd-Line

System Var Status Var

Var Scope

Dynamic

Yes

Global

Yes

local_infile

Yes

Global

Yes

old_passwords

Yes

Both

Yes

Global

Yes

Global

Yes

Global

No

Global

No

Global

No

Global

No

Global

No

Global

No

allow-suspicious- Yes
udfs

Option File
Yes

automatic_sp_privileges
chroot

Yes

Yes

des-key-file

Yes

Yes

safe-showdatabase

Yes

Yes

safe-user-create

Yes

Yes

secure-auth

Yes

Yes

- Variable:
secure_auth
secure-file-priv

Yes
Yes

Yes

- Variable:
secure_file_priv

Yes

skip-grant-tables Yes

Yes

skip-nameresolve

Yes

Yes

skip-networking

Yes

Yes

- Variable:
skip_networking
skip-showdatabase

Yes
Yes

- Variable:
skip_show_database

Yes
Yes

6.1.5 How to Run MySQL as a Normal User
On Windows, you can run the server as a Windows service using a normal user account.
On Unix, the MySQL server mysqld can be started and run by any user. However, you should avoid
running the server as the Unix root user for security reasons. To change mysqld to run as a normal
unprivileged Unix user user_name, you must do the following:
1. Stop the server if it is running (use mysqladmin shutdown).
2. Change the database directories and files so that user_name has privileges to read and write files
in them (you might need to do this as the Unix root user):
shell> chown -R user_name /path/to/mysql/datadir

If you do not do this, the server will not be able to access databases or tables when it runs as
user_name.
If directories or files within the MySQL data directory are symbolic links, chown -R might not
follow symbolic links for you. If it does not, you will also need to follow those links and change the
directories and files they point to.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Security Issues with LOAD DATA LOCAL

3. Start the server as user user_name. Another alternative is to start mysqld as the Unix root user
and use the --user=user_name option. mysqld starts up, then switches to run as the Unix user
user_name before accepting any connections.
4. To start the server as the given user automatically at system startup time, specify the user name
by adding a user option 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=user_name

If your Unix machine itself is not secured, you should assign passwords to the MySQL root accounts
in the grant tables. Otherwise, any user with a login account on that machine can run the mysql client
with a --user=root option and perform any operation. (It is a good idea to assign passwords to
MySQL accounts in any case, but especially so when other login accounts exist on the server host.)
See Section 2.18.4, “Securing the Initial MySQL Accounts”.

6.1.6 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 remote program being run by the user who
connects to the Web server.
To deal with these problems, LOAD DATA LOCAL works like this:
• By default, all MySQL clients and libraries in binary distributions are compiled with the --enablelocal-infile option.
• If you build MySQL from source but do not invoke configure with the --enable-localinfile option, LOAD DATA LOCAL cannot be used by any client unless it is written explicitly
to invoke mysql_options(... MYSQL_OPT_LOCAL_INFILE, 0). See Section 20.6.7.49,
“mysql_options()”.
• You can disable all LOAD DATA LOCAL statements from the server side by starting mysqld with the
--local-infile=0 option.
• For the mysql command-line client, enable LOAD DATA LOCAL by specifying the --localinfile[=1] option, or disable it with the --local-infile=0 option. For mysqlimport, local
data file loading is off by default; enable it with the --local or -L option. In any case, successful
use of a local load operation requires that the server permits it.
• If you use LOAD DATA LOCAL in Perl scripts or other programs that read the [client] group from
option files, you can add the local-infile=1 option to that group. However, to keep this from
causing problems for programs that do not understand local-infile, specify it using the looseprefix:
[client]

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Client Programming Security Guidelines

loose-local-infile=1

• If LOAD DATA LOCAL 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

6.1.7 Client Programming Security Guidelines
Applications that access MySQL should not trust any data entered by users, who 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 as SELECT * FROM table WHERE ID=234 when a user enters
the value 234, the user can enter the value 234 OR 1=1 to cause the application to generate the
query SELECT * FROM table WHERE ID=234 OR 1=1. As a result, the server retrieves every row
in the table. This exposes every row and causes excessive server load. The simplest way to protect
from this type of attack is to use single quotation marks around the numeric constants: SELECT *
FROM table WHERE ID='234'. If the user enters extra information, it all becomes part of the string.
In a numeric context, MySQL automatically converts this string to a number and strips any trailing
nonnumeric 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 permissible to display any row 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:
• Enable strict SQL mode to tell the server to be more restrictive of what data values it accepts. See
Section 5.1.7, “Server SQL Modes”.
• Try to enter single and double quotation marks (“'” and “"”) in all of your Web forms. If you get any
kind of MySQL error, investigate the problem right away.
• Try to modify dynamic URLs by adding %22 (“"”), %23 (“#”), and %27 (“'”) to them.
• Try to modify data types in dynamic URLs from numeric to character types using the characters
shown in the previous examples. Your application should be safe against these 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 the size of data before passing it to MySQL.
• Have your application connect to the database using a user name different from 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 and quote modifiers for query streams.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Access Privilege System

• PHP: Use either the mysqli or pdo_mysql extensions, and not the older ext/mysql extension.
The preferred API's support the improved MySQL authentication protocol and passwords, as well as
prepared statements with placeholders. See also Choosing an API.
If the older ext/mysql extension must be used, then for escaping use the
mysql_real_escape_string() function and not mysql_escape_string() or addslashes()
because only mysql_real_escape_string() is character set-aware; the other functions can be
“bypassed” when using (invalid) multibyte character sets.
• Perl DBI: Use placeholders or the quote() method.
• Ruby DBI: Use placeholders or the quote() method.
• Java JDBC: Use a PreparedStatement object and placeholders.
Other programming interfaces might have similar capabilities.

6.2 The MySQL Access Privilege System
The primary function of the MySQL privilege system is to authenticate a user who connects from a
given host and to associate that user with privileges on a database such as SELECT, INSERT, UPDATE,
and DELETE. Additional functionality includes the ability to have anonymous users and to grant
privileges for MySQL-specific functions such as LOAD DATA INFILE and administrative operations.
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.
• A password applies globally to an account. You cannot associate a password with a specific object
such as a database, table, or routine.
The user interface to the MySQL privilege system consists of SQL statements such as CREATE USER,
GRANT, and REVOKE. See Section 13.7.1, “Account Management Statements”.
Internally, 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 bases access-control decisions on the in-memory copies of the grant tables.
The MySQL privilege system ensures that all users may perform only the operations permitted 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 user name you specify. When you issue requests after connecting, the system
grants privileges according to your identity and what you want to do.
MySQL considers both your host name and user name in identifying you because there is no reason
to assume that a given user name belongs to the same person on all hosts. For example, the user
joe who connects from office.example.com need not be the same person as the user joe who
connects from home.example.com. MySQL handles this by enabling you to distinguish users on
different hosts that happen to have the same name: You can grant one set of privileges for connections
by joe from office.example.com, and a different set of privileges for connections by joe from
home.example.com. To see what privileges a given account has, use the SHOW GRANTS statement.
For example:
SHOW GRANTS FOR 'joe'@'office.example.com';
SHOW GRANTS FOR 'joe'@'home.example.com';

MySQL access control involves two stages when you run a client program that connects to the server:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Privileges Provided by MySQL

Stage 1: The server accepts or rejects the connection based on your identity and whether you can
verify your identity by supplying the correct password.
Stage 2: Assuming that you can connect, the server checks each statement you issue to determine
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 the DROP privilege for the database.
For a more detailed description of what happens during each stage, see Section 6.2.4, “Access
Control, Stage 1: Connection Verification”, and Section 6.2.5, “Access Control, Stage 2: Request
Verification”.
If your privileges are changed (either by yourself or someone else) while you are connected, those
changes do not necessarily take effect immediately for the next statement that you issue. For details
about the conditions under which the server reloads the grant tables, see Section 6.2.6, “When
Privilege Changes Take Effect”.
For general security-related advice, see Section 6.1, “General Security Issues”. For help in diagnosing
privilege-related problems, see Section 6.2.7, “Troubleshooting Problems Connecting to MySQL”.

6.2.1 Privileges Provided by MySQL
MySQL provides privileges that apply in different contexts and at different levels of operation:
• Administrative privileges enable users to manage operation of the MySQL server. These privileges
are global because they are not specific to a particular database.
• Database privileges apply to a database and to all objects within it. These privileges can be granted
for specific databases, or globally so that they apply to all databases.
• Privileges for database objects such as tables, indexes, views, and stored routines can be granted
for specific objects within a database, for all objects of a given type within a database (for example,
all tables in a database), or globally for all objects of a given type in all databases).
Information about account privileges is stored in the user, db, host, tables_priv, columns_priv,
and procs_priv tables in the mysql database (see Section 6.2.2, “Grant Tables”). The MySQL
server reads the contents of these tables into memory when it starts and reloads them under the
circumstances indicated in Section 6.2.6, “When Privilege Changes Take Effect”. Access-control
decisions are based on the in-memory copies of the grant tables.
Some releases of MySQL introduce changes to the structure of the grant tables to add new privileges
or features. To make sure that you can take advantage of any new capabilities, update your
grant tables to have the current structure whenever you update to a new version of MySQL. See
Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.
The following table shows the privilege names used at the SQL level in the GRANT and REVOKE
statements, along with the column name associated with each privilege in the grant tables and the
context in which the privilege applies.
Table 6.2 Permissible Privileges for GRANT and REVOKE
Privilege

Column

Context

CREATE

Create_priv

databases, tables, or indexes

DROP

Drop_priv

databases, tables, or views

GRANT OPTION

Grant_priv

databases, tables, or stored routines

LOCK TABLES

Lock_tables_priv

databases

REFERENCES

References_priv

databases or tables

ALTER

Alter_priv

tables

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Privileges Provided by MySQL

Privilege

Column

Context

DELETE

Delete_priv

tables

INDEX

Index_priv

tables

INSERT

Insert_priv

tables or columns

SELECT

Select_priv

tables or columns

UPDATE

Update_priv

tables or columns

CREATE TEMPORARY
TABLES

Create_tmp_table_priv

tables

CREATE VIEW

Create_view_priv

views

SHOW VIEW

Show_view_priv

views

ALTER ROUTINE

Alter_routine_priv

stored routines

CREATE ROUTINE

Create_routine_priv

stored routines

EXECUTE

Execute_priv

stored routines

FILE

File_priv

file access on server host

CREATE USER

Create_user_priv

server administration

PROCESS

Process_priv

server administration

RELOAD

Reload_priv

server administration

REPLICATION CLIENT

Repl_client_priv

server administration

REPLICATION SLAVE

Repl_slave_priv

server administration

SHOW DATABASES

Show_db_priv

server administration

SHUTDOWN

Shutdown_priv

server administration

SUPER

Super_priv

server administration

ALL [PRIVILEGES]

server administration

USAGE

server administration

The following list provides a general description of each privilege available in MySQL. Particular SQL
statements might have more specific privilege requirements than indicated here. If so, the description
for the statement in question provides the details.
• The ALL or ALL PRIVILEGES privilege specifier is shorthand. It stands for “all privileges available
at a given privilege level” (except GRANT OPTION). For example, granting ALL at the global or table
level grants all global privileges or all table-level privileges.
• The ALTER privilege enables use of ALTER TABLE to change the structure of tables. ALTER TABLE
also requires the CREATE and INSERT privileges. Renaming a table requires ALTER and DROP on
the old table, CREATE, and INSERT on the new table.
• The ALTER ROUTINE privilege is needed to alter or drop stored routines (procedures and functions).
This privilege was added in MySQL 5.0.3.
• The CREATE privilege enables creation of new databases and tables.
• The CREATE ROUTINE privilege is needed to create stored routines (procedures and functions). This
privilege was added in MySQL 5.0.3.
• The CREATE TEMPORARY TABLES privilege enables the creation of temporary tables using the
CREATE TEMPORARY TABLE statement.
However, other operations on a temporary table, such as INSERT, UPDATE, or SELECT, require
additional privileges for those operations for the database containing the temporary table, or for the
nontemporary table of the same name.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Privileges Provided by MySQL

To keep privileges for temporary and nontemporary tables separate, a common workaround for this
situation is to create a database dedicated to the use of temporary tables. Then for that database,
a user can be granted the CREATE TEMPORARY TABLES privilege, along with any other privileges
required for temporary table operations done by that user.
• The CREATE USER privilege enables use of CREATE USER, DROP USER, RENAME USER, and
REVOKE ALL PRIVILEGES. This privilege was added in MySQL 5.0.3.
• The CREATE VIEW privilege enables use of CREATE VIEW. This privilege was added in MySQL
5.0.1.
• The DELETE privilege enables rows to be deleted from tables in a database.
• The DROP privilege enables you 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 EXECUTE privilege is required to execute stored routines (procedures and functions). This
privilege was added in MySQL 5.0.0 but did not become operational until MySQL 5.0.3.
• 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 and the LOAD_FILE() function. 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 enables the user to
create new files in any directory where the MySQL server has write access. This includes the
server's data directory containing the files that implement the privilege tables. As a security measure,
the server will not overwrite existing files.
To limit the location in which files can be read and written, set the secure_file_priv system to a
specific directory. See Section 5.1.4, “Server System Variables”.
• The GRANT OPTION privilege enables you to give to other users or remove from other users those
privileges that you yourself possess.
• The INDEX privilege enables 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 INSERT privilege enables rows to be inserted into tables in a database. INSERT is also required
for the ANALYZE TABLE, OPTIMIZE TABLE, and REPAIR TABLE table-maintenance statements.
• The LOCK TABLES privilege enables 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 other
sessions from reading the locked table.
• The PROCESS privilege pertains to display of information about the threads executing within the
server (that is, information about the statements being executed by sessions). The privilege enables
use of SHOW PROCESSLIST or mysqladmin processlist to see threads belonging to other
accounts; you can always see your own threads.
• The REFERENCES privilege is unused.
• The RELOAD privilege enables use of the FLUSH statement. It also enables mysqladmin commands
that are equivalent to FLUSH operations: flush-hosts, flush-logs, flush-privileges,
flush-status, flush-tables, flush-threads, refresh, and reload.
The reload command tells the server to reload 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

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Privileges Provided by MySQL

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 REPLICATION CLIENT privilege enables the use of SHOW MASTER STATUS and SHOW SLAVE
STATUS.
• The REPLICATION SLAVE privilege should be granted to accounts that are used by slave servers to
connect to the current server as their master. Without this privilege, the slave cannot request updates
that have been made to databases on the master server.
• The SELECT privilege enables you to select rows from 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 SELECT as a simple calculator to evaluate expressions that make no
reference to tables:
SELECT 1+1;
SELECT PI()*2;

The SELECT privilege is also needed for other statements that read column values. For example,
SELECT is needed for columns referenced on the right hand side of col_name=expr assignment in
UPDATE statements or for columns named in the WHERE clause of DELETE or UPDATE statements.
• The SHOW DATABASES privilege enables 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 --skipshow-database option. Note that any global privilege is a privilege for the database.
• The SHOW VIEW privilege enables use of SHOW CREATE VIEW. This privilege was added in MySQL
5.0.1.
• The SHUTDOWN privilege enables use of the mysqladmin shutdown command and the
mysql_shutdown() C API function. There is no corresponding SQL statement.
• The SUPER privilege enables an account to use CHANGE MASTER TO, KILL or mysqladmin
kill to kill threads belonging to other accounts (you can always kill your own threads), PURGE
BINARY LOGS, configuration changes using SET GLOBAL to modify global system variables,
the mysqladmin debug command, enabling or disabling logging, performing updates even if
the read_only system variable is enabled, starting and stopping replication on slave servers,
specification of any account in the DEFINER attribute of stored programs and views, and enables you
to connect (once) even if the connection limit controlled by the max_connections system variable
is reached.
To create or alter stored routines if binary logging is enabled, you may also need the SUPER
privilege, as described in Section 18.6, “Binary Logging of Stored Programs”.
• The UPDATE privilege enables rows to be updated in tables in a database.
• The USAGE privilege specifier stands for “no privileges.” It is used at the global level with GRANT to
modify account attributes such as resource limits or SSL characteristics without affecting existing
account privileges.
It is a good idea to grant to an account only those privileges that it needs. You should exercise
particular caution in granting the FILE and administrative privileges:
• 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 using SELECT to transfer its contents to the client host.
• The GRANT OPTION privilege enables users to give their privileges to other users. Two users that
have different privileges and with the GRANT OPTION privilege are able to combine privileges.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Grant Tables

• The ALTER privilege may be used to subvert the privilege system by renaming tables.
• 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 statements, including
statements that set or change passwords.
• The SUPER privilege can be used to terminate other sessions 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 the user table Password
column can change an account's password, and then connect to the MySQL server using that
account.

6.2.2 Grant Tables
The mysql system database includes several grant tables that contain information about user
accounts and the privileges held by them. This section describes those tables. For information about
other tables in the system database, see Section 5.3, “The mysql System Database”.
Normally, to manipulate the contents of grant tables, you modify them indirectly by using accountmanagement statements such as CREATE USER, GRANT, and REVOKE to set up accounts and control
the privileges available to each one. See Section 13.7.1, “Account Management Statements”. The
discussion here describes the underlying structure of the grant tables and how the server uses their
contents when interacting with clients.
Note
Direct modification of grant tables using statements such as INSERT, UPDATE,
or DELETE is discouraged and done at your own risk. The server is free to
ignore rows that become malformed as a result of such modifications.
These mysql database tables contain grant information:
•

user: User accounts, global privileges, and other non-privilege columns.

•

db: Database-level privileges.

•

host: Obsolete.

•

tables_priv: Table-level privileges.

•

columns_priv: Column-level privileges.

•

procs_priv: Stored procedure and function privileges.

Each grant table contains scope columns and privilege columns:
• Scope columns determine the scope of each row in the tables; that is, the context in which the row
applies. For example, a user table row with Host and User values of 'thomas.loc.gov' and
'bob' applies to authenticating connections made to the server from the host thomas.loc.gov by
a client that specifies a user name of bob. Similarly, a db table row with Host, User, and Db column
values of 'thomas.loc.gov', 'bob' and 'reports' applies when bob connects from the host
thomas.loc.gov to access the reports database. The tables_priv and columns_priv
tables contain scope columns indicating tables or table/column combinations to which each row
applies. The procs_priv scope columns indicate the stored routine to which each row applies.
• Privilege columns indicate which privileges a table row grants; that is, which operations it permits to
be performed. The server combines the information in the various grant tables to form a complete
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Grant Tables

description of a user's privileges. Section 6.2.5, “Access Control, Stage 2: Request Verification”,
describes the rules for this.
The server uses the grant tables in the following manner:
• The user table scope columns determine whether to reject or permit incoming connections. For
permitted connections, any privileges granted in the user table indicate the user's global privileges.
Any privileges granted in this table apply to all databases on the server.
Caution
Because any global privilege is considered a privilege for all databases,
any global privilege enables a user to see all database names with SHOW
DATABASES or by examining the SCHEMATA table of INFORMATION_SCHEMA.
• The db table scope columns determine which users can access which databases from which hosts.
The privilege columns determine the permitted operations. A privilege granted at the database level
applies to the database and to all objects in the database, such as tables and stored programs.
• The host table is used in conjunction with the db table when you want a given db table row to apply
to several hosts. For example, if you want a user to be able to use a database from several hosts
in your network, leave the Host value empty in the user's db table row, then populate the host
table with a row for each of those hosts. This mechanism is described more detail in Section 6.2.5,
“Access Control, Stage 2: Request Verification”.
Note
The host table must be modified directly with statements such as INSERT,
UPDATE, and DELETE. It is not affected by statements such as GRANT and
REVOKE that modify the grant tables indirectly. Most MySQL installations need
not use this table at all.
• The tables_priv and columns_priv tables are similar to the db table, but are more fine-grained:
They apply at the table and column levels rather than at the database level. A privilege granted at the
table level applies to the table and to all its columns. A privilege granted at the column level applies
only to a specific column.
• The procs_priv table applies to stored routines (procedures and functions). A privilege granted at
the routine level applies only to a single procedure or function.
The server uses the user, db, and host tables in the mysql database at both the first and second
stages of access control (see Section 6.2, “The MySQL Access Privilege System”). The columns in the
user and db tables are shown here. The host table is similar to the db table but has a specialized use
as described in Section 6.2.5, “Access Control, Stage 2: Request Verification”.
Table 6.3 user and db Table Columns
Table Name

user

db

Scope columns

Host

Host

User

Db

Password

User

Select_priv

Select_priv

Insert_priv

Insert_priv

Update_priv

Update_priv

Delete_priv

Delete_priv

Index_priv

Index_priv

Alter_priv

Alter_priv

Privilege columns

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Grant Tables

Table Name

user

db

Create_priv

Create_priv

Drop_priv

Drop_priv

Grant_priv

Grant_priv

Create_view_priv

Create_view_priv

Show_view_priv

Show_view_priv

Create_routine_priv

Create_routine_priv

Alter_routine_priv

Alter_routine_priv

Execute_priv

Execute_priv

Create_tmp_table_priv

Create_tmp_table_priv

Lock_tables_priv

Lock_tables_priv

References_priv

References_priv

Reload_priv
Shutdown_priv
Process_priv
File_priv
Show_db_priv
Super_priv
Repl_slave_priv
Repl_client_priv
Create_user_priv
Security columns

ssl_type
ssl_cipher
x509_issuer
x509_subject

Resource control columns

max_questions
max_updates
max_connections
max_user_connections

Execute_priv was present in MySQL 5.0.0, but did not become operational until MySQL 5.0.3.
The Create_view_priv and Show_view_priv columns were added in MySQL 5.0.1.
The Create_routine_priv, Alter_routine_priv, and max_user_connections columns were
added in MySQL 5.0.3.
During the second stage of access control, the server performs request verification to ensure that each
client has sufficient privileges for each request that it issues. In addition to the user, db, and host
grant tables, the server may also consult the tables_priv and columns_priv tables for requests
that involve tables. The latter tables provide finer privilege control at the table and column levels. They
have the columns shown in the following table.
Table 6.4 tables_priv and columns_priv Table Columns
Table Name

tables_priv

columns_priv

Scope columns

Host

Host

Db

Db

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Grant Tables

Table Name

tables_priv

columns_priv

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 are unused.
For verification of requests that involve stored routines, the server may consult the procs_priv table,
which has the columns shown in the following table.
Table 6.5 procs_priv Table Columns
Table Name

procs_priv

Scope columns

Host
Db
User
Routine_name
Routine_type

Privilege columns

Proc_priv

Other columns

Timestamp
Grantor

The procs_priv table exists as of MySQL 5.0.3. The Routine_type column was added in MySQL
5.0.6. It is an ENUM column with values of 'FUNCTION' or 'PROCEDURE' to indicate the type of
routine the row refers to. This column enables privileges to be granted separately for a function and a
procedure with the same name.
The Timestamp and Grantor columns are set to the current timestamp and the CURRENT_USER
value, respectively, but are otherwise unused.
Scope columns in the grant tables contain strings. The default value for each is the empty string. The
following table shows the number of characters permitted in each column.
Table 6.6 Grant Table Scope Column Lengths
Column Name

Maximum Permitted Characters

Host

60

User

16

Password

41

Db

64

Table_name

64

Column_name

64

Routine_name

64

For access-checking purposes, comparisons of User, Password, Db, and Table_name values
are case sensitive. Comparisons of Host, Column_name, and Routine_name values are not case
sensitive.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Account Names

The user, db, and host tables list each privilege in a separate column that is declared as
ENUM('N','Y') DEFAULT 'N'. In other words, each privilege can be disabled or enabled, with the
default being disabled.
The tables_priv, columns_priv, and procs_priv tables declare the privilege columns as SET
columns. Values in these columns can contain any combination of the privileges controlled by the table.
Only those privileges listed in the column value are enabled.
Table 6.7 Set-Type Privilege Column Values
Table Name

Column Name

Possible Set Elements

tables_priv

Table_priv

'Select', 'Insert', 'Update',
'Delete', 'Create', 'Drop', 'Grant',
'References', 'Index', 'Alter',
'Create View', 'Show view'

tables_priv

Column_priv

'Select', 'Insert', 'Update',
'References'

columns_priv

Column_priv

'Select', 'Insert', 'Update',
'References'

procs_priv

Proc_priv

'Execute', 'Alter Routine', 'Grant'

Only the user table specifies administrative privileges, such as RELOAD and SHUTDOWN. 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. Consequently, the server need consult only the user table to
determine whether a user can perform an administrative operation.
The FILE privilege also is specified only in the user table. It is not an administrative privilege as
such, but a user's ability to read or write files on the server host is independent of the database being
accessed.
The server reads the contents of the grant tables into memory when it starts. You can tell it to reload
the tables by issuing a FLUSH PRIVILEGES statement or executing a mysqladmin flushprivileges or mysqladmin reload command. Changes to the grant tables take effect as indicated
in Section 6.2.6, “When Privilege Changes Take Effect”.
When you modify an account, it is a good idea to verify that your changes have the intended effect.
To check the privileges for a given account, use the SHOW GRANTS statement. For example, to
determine the privileges that are granted to an account with user name and host name values of bob
and pc84.example.com, use this statement:
SHOW GRANTS FOR 'bob'@'pc84.example.com';

6.2.3 Specifying Account Names
MySQL account names consist of a user name and a host name. This enables creation of accounts for
users with the same name who can connect from different hosts. This section describes how to write
account names, including special values and wildcard rules.
In SQL statements such as CREATE USER, GRANT, and SET PASSWORD, write account names using
the following rules:
• Syntax for account names is 'user_name'@'host_name'.
• An account name consisting only of a user name is equivalent to 'user_name'@'%'. For example,
'me' is equivalent to 'me'@'%'.
• The user name and host name need not be quoted if they are legal as unquoted identifiers. Quotes
are necessary to specify a user_name string containing special characters (such as “-”), or a
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Account Names

host_name string containing special characters or wildcard characters (such as “%”); for example,
'test-user'@'%.com'.
• Quote user names and host names as identifiers or as strings, using either backticks (“`”), single
quotation marks (“'”), or double quotation marks (“"”).
• The user name and host name parts, if quoted, must be quoted separately. That is, write
'me'@'localhost', not 'me@localhost'; the latter is interpreted as 'me@localhost'@'%'.
MySQL stores account names in grant tables in the mysql database using separate columns for the
user name and host name parts:
• The user table contains one row for each account. The User and Host columns store the user
name and host name. This table also indicates which global privileges the account has.
• Other grant tables indicate privileges an account has for databases and objects within databases.
These tables have User and Host columns to store the account name. Each row in these tables
associates with the account in the user table that has the same User and Host values.
• A reference to the CURRENT_USER or CURRENT_USER() function is equivalent to specifying the
current client's user name and host name literally.
For additional detail about grant table structure, see Section 6.2.2, “Grant Tables”.
User names and host names have certain special values or wildcard conventions, as described
following.
A user name is either a nonblank value that literally matches the user name for incoming connection
attempts, or a blank value (empty string) that matches any user name. An account with a blank user
name is an anonymous user. To specify an anonymous user in SQL statements, use a quoted empty
user name part, such as ''@'localhost'.
The host name part of an account name can take many forms, and wildcards are permitted:
• A host value can be a host name or an IP address. The name 'localhost' indicates the local
host. The IP address '127.0.0.1' indicates the loopback interface.
• You can use the wildcard characters “%” and “_” in host name or IP address values. These have the
same meaning as for pattern-matching operations performed with the LIKE operator. For example, a
host value of '%' matches any host name, whereas a value of '%.mysql.com' matches any host
in the mysql.com domain. '192.168.1.%' matches any host in the 192.168.1 class C network.
Because you can use IP wildcard values in host values (for example, '192.168.1.%' to
match every host on a subnet), someone could try to exploit this capability by naming a host
192.168.1.somewhere.com. To foil such attempts, MySQL disallows matching on host names
that start with digits and a dot. Thus, if you have a host named something like 1.2.example.com,
its name never matches the host part of account names. An IP wildcard value can match only IP
addresses, not host names.
• For a host value specified as an IP address, you can specify a netmask indicating how many
address bits to use for the network number. The syntax is host_ip/netmask. For example:
CREATE USER 'david'@'192.58.197.0/255.255.255.0';

This enables david to connect from any client host having an IP address client_ip for which the
following condition is true:
client_ip & netmask = host_ip

That is, for the CREATE USER statement just shown:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Access Control, Stage 1: Connection Verification

client_ip & 255.255.255.0 = 192.58.197.0

IP addresses that satisfy this condition and can connect to the MySQL server are those in the range
from 192.58.197.0 to 192.58.197.255.
A netmask typically begins with bits set to 1, followed by bits set to 0. Examples:
• 192.0.0.0/255.0.0.0: Any host on the 192 class A network
• 192.168.0.0/255.255.0.0: Any host on the 192.168 class B network
• 192.168.1.0/255.255.255.0: Any host on the 192.168.1 class C network
• 192.168.1.1: Only the host with this specific IP address
The following netmask will not work because it masks 28 bits, and 28 is not a multiple of 8:
192.168.0.1/255.255.255.240

The server performs matching of host values in account names against the client host using the value
returned by the system DNS resolver for the client host name or IP address. Except in the case that the
account host value is specified using netmask notation, this comparison is performed as a string match,
even for an account host value given as an IP address. This means that you should specify account
host values in the same format used by DNS. Here are examples of problems to watch out for:
• Suppose that a host on the local network has a fully qualified name of host1.example.com. If DNS
returns name lookups for this host as host1.example.com, use that name in account host values.
But if DNS returns just host1, use host1 instead.
• If DNS returns the IP address for a given host as 192.168.1.2, that will match an account host
value of 192.168.1.2 but not 192.168.01.2. Similarly, it will match an account host pattern like
192.168.1.% but not 192.168.01.%.
To avoid problems like this, it is advisable to check the format in which your DNS returns host names
and addresses, and use values in the same format in MySQL account names.

6.2.4 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, and then enters
Stage 2 and waits for requests.
Credential 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 row match the client host name and user name and the client supplies the password specified
in that row. The rules for permissible Host and User values are given in Section 6.2.3, “Specifying
Account Names”.
Your identity is based on two pieces of information:
• The client host from which you connect
• Your MySQL user name
If the User column value is nonblank, the user name in an incoming connection must match exactly.
If the User value is blank, it matches any user name. If the user table row that matches an incoming
connection has a blank user name, the user is considered to be an anonymous user with no name, not
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Access Control, Stage 1: Connection Verification

a user with the name that the client actually specified. This means that a blank user name 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.
Nonblank Password values in the user table represent encrypted passwords. MySQL does not
store passwords in cleartext 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. See Section 6.3.1, “User Names
and Passwords”.
From MySQL's point of view, the encrypted password is the real password, so you should never give
anyone access to it. In particular, do not give nonadministrative users read access to tables in the
mysql database.
The following table shows how various combinations of User and Host values in the user table apply
to incoming connections.
User Value

Host Value

Permissible Connections

'fred'

'thomas.loc.gov'

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

'fred'

'%.loc.gov'

fred, connecting from any host in the loc.gov
domain

'fred'

'x.y.%'

fred, connecting from x.y.net, x.y.com,
x.y.edu, and so on; this is probably not useful

'fred'

'192.168.10.177'

fred, connecting from the host with IP address
192.168.10.177

'fred'

'192.168.10.%'

fred, connecting from any host in the
192.168.10 class C subnet

'fred'

'192.168.10.0/255.255.255.0'
Same as previous example

It is possible for the client host name and user name of an incoming connection to match more than
one row in the user table. The preceding set of examples demonstrates this: Several of the entries
shown match a connection from thomas.loc.gov by fred.
When multiple matches are possible, the server must determine which of them to use. It resolves this
issue as follows:
• Whenever the server reads the user table into memory, it sorts the rows.
• When a client attempts to connect, the server looks through the rows in sorted order.
• The server uses the first row that matches the client host name and user name.
The server uses sorting rules that order rows with the most-specific Host values first. Literal host
names and IP addresses are the most specific. (The specificity of a literal IP address is not affected by
whether it has a netmask, so 192.168.1.13 and 192.168.1.0/255.255.255.0 are considered
equally specific.) The pattern '%' means “any host” and is least specific. The empty string '' also
means “any host” but sorts after '%'. Rows with the same Host value are ordered with the mostspecific User values first (a blank User value means “any user” and is least specific). For rows with
equally-specific Host and User values, the order is indeterminate.
To see how this works, suppose that the user table looks like this:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Access Control, Stage 1: Connection Verification

+-----------+----------+| Host
| User
| ...
+-----------+----------+| %
| root
| ...
| %
| jeffrey | ...
| localhost | root
| ...
| localhost |
| ...
+-----------+----------+-

When the server reads the table into memory, it sorts the rows using the rules just described. 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 rows and uses the first match
found. For a connection from localhost by jeffrey, two of the rows from the table match: the
one with Host and User values of 'localhost' and '', and the one with values of '%' and
'jeffrey'. The 'localhost' row appears first in sorted order, so that is the one the server uses.
Here is another example. Suppose that the user table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| %
| jeffrey | ...
| thomas.loc.gov |
| ...
+----------------+----------+-

The sorted table looks like this:
+----------------+----------+| Host
| User
| ...
+----------------+----------+| thomas.loc.gov |
| ...
| %
| jeffrey | ...
+----------------+----------+-

A connection by jeffrey from thomas.loc.gov is matched by the first row, whereas a connection
by jeffrey from any host is matched by the second.
Note
It is a common misconception to think that, for a given user name, all rows
that explicitly name that user are used first when the server attempts to find a
match for the connection. This is not true. The preceding example illustrates
this, where a connection from thomas.loc.gov by jeffrey is first matched
not by the row containing 'jeffrey' as the User column value, but by the row
with no user name. As a result, jeffrey is authenticated as an anonymous
user, even though he specified a user name 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. (See Section 12.13, “Information Functions”.) It returns a
value in user_name@host_name format that indicates the User and Host values from the matching
user table row. Suppose that jeffrey connects and issues the following query:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Access Control, Stage 2: Request Verification

mysql> SELECT CURRENT_USER();
+----------------+
| CURRENT_USER() |
+----------------+
| @localhost
|
+----------------+

The result shown here indicates that the matching user table row had a blank User column value. In
other words, the server is treating jeffrey as an anonymous user.
Another way 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.

6.2.5 Access Control, Stage 2: Request Verification
After you establish a connection, the server enters Stage 2 of access control. For each request that
you issue through that 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,
columns_priv, or procs_priv tables. (You may find it helpful to refer to Section 6.2.2, “Grant
Tables”, 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 default 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! It is wise to grant privileges in the user
table only to people who need them, such as database administrators. For other users, you should
leave all privileges in the user table set to 'N' and grant privileges at more specific levels only. You
can grant privileges for particular databases, tables, columns, or routines.
The db and host tables grant database-specific privileges. Values in the scope columns of these
tables can take the following forms:
• A blank User value in the db table matches the anonymous user. A nonblank value matches literally;
there are no wildcards in user names.
• The wildcard characters “%” and “_” can be used in the Host and Db columns of either table. These
have the same meaning as for pattern-matching operations performed with the LIKE operator. If you
want to use either character literally when granting privileges, you must escape it with a backslash.
For example, to include the underscore character (“_”) as part of a database name, specify it as “\_”
in the GRANT statement.
• A '%' Host value in the db table means “any host.” A blank Host value in the db table means
“consult the host table for further information” (a process that is described later in this section).
• A '%' or blank Host value in the host table means “any host.”
• A '%' or blank Db value in either table means “any database.”
The server reads the db and host tables into memory and sorts them 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
rows, it uses the first match that it finds.
The tables_priv, columns_priv, and procs_priv tables grant table-specific, column-specific,
and routine-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 column. These have the same meaning
as for pattern-matching operations performed with the LIKE operator.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Access Control, Stage 2: Request Verification

• A '%' or blank Host value means “any host.”
• The Db, Table_name, Column_name, and Routine_name columns cannot contain wildcards or be
blank.
The server sorts the tables_priv, columns_priv, and procs_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 server uses the sorted tables to verify each request that it receives. For requests that require
administrative privileges such as SHUTDOWN or RELOAD, the server checks only the user table row
because that is the only table that specifies administrative privileges. The server grants access if the
row permits the requested operation and denies access otherwise. For example, if you want to execute
mysqladmin shutdown but your user table row does not 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
privileges by looking in the user table row. If the row permits 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:
1. The server looks in the db table for a match on the Host, Db, and User columns. The Host and
User columns are matched to the connecting user's host name and MySQL user name. The Db
column is matched to the database that the user wants to access. If there is no row for the Host
and User, access is denied.
2. If there is a matching db table row and its Host column is not blank, that row defines the user's
database-specific privileges.
3. If the matching db table row's Host column is blank, it signifies that the host table enumerates
which hosts should be permitted access to the database. In this case, a further lookup is done
in the host table to find a match on the Host and Db columns. If no host table row matches,
access is denied. If there is a match, the user's database-specific privileges are computed as the
intersection (not the union!) of the privileges in the db and host table rows; that is, the privileges
that are 'Y' in both rows. (This way you can grant general privileges in the db table row and then
selectively restrict them on a host-by-host basis using the host table rows.)
After determining the database-specific privileges granted by the db and host table rows, the server
adds them to the global privileges granted by the user table. If the result permits 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
permits or denies access based on the result. For stored-routine operations, the server uses the
procs_priv table rather than tables_priv and columns_priv.
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
OR routine privileges

It may not be apparent why, if the global user row privileges are initially found to be insufficient for the
requested operation, the server adds those privileges to the database, table, and column privileges
later. The reason is that a request might require more than one type of privilege. For example, if you
execute an INSERT INTO ... SELECT statement, you need both the INSERT and the SELECT
privileges. Your privileges might be such that the user table row grants one privilege and the db table
row grants the other. In this case, you have the necessary privileges to perform the request, but the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

When Privilege Changes Take Effect

server cannot tell that from either table by itself; the privileges granted by the rows in both tables must
be combined.
The host table is not affected by the GRANT or REVOKE statements, so it is unused in most MySQL
installations. If you modify it directly, you can use it for some specialized purposes, such as to maintain
a list of secure servers on the local network that 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 enable access to all hosts on your network except that machine by using host table rows like this:
+--------------------+----+| Host
| Db | ...
+--------------------+----+| public.your.domain | % | ... (all privileges set to 'N')
| %.your.domain
| % | ... (all privileges set to 'Y')
+--------------------+----+-

6.2.6 When Privilege Changes Take Effect
When mysqld starts, it reads all grant table contents into memory. The in-memory tables become
effective for access control at that point.
If you modify the grant tables indirectly using account-management statements such as GRANT,
REVOKE, or SET PASSWORD, the server notices these changes and loads 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. If you change the grant tables directly but forget to reload them, your changes have no effect
until you restart the server. This may leave you wondering why your changes do not seem to make any
difference!
To tell the server to reload the grant tables, perform a flush-privileges operation. This can be done by
issuing a FLUSH PRIVILEGES statement or by executing a mysqladmin flush-privileges or
mysqladmin reload command.
When the server reloads the grant tables, privileges for each existing client connection are affected as
follows:
• Table and column privilege changes take effect with the client's next request.
• Database privilege changes take effect the next time the client executes a USE db_name statement.
Note
Client applications may cache the database name; thus, this effect may not
be visible to them without actually changing to a different database or flushing
the privileges.
• Global privileges and passwords are unaffected for a connected client. These changes take effect
only for subsequent connections.
If the server is started with the --skip-grant-tables option, it does not read the grant tables or
implement any access control. Anyone can connect and do anything. To cause a server thus started to
read the tables and enable access checking, flush the privileges.

6.2.7 Troubleshooting Problems Connecting to MySQL
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.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting Problems Connecting to MySQL

• Make sure that the server is running. If it is not, clients cannot connect to it. For example, if an
attempt to connect to the server fails with 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 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 the one on which the server is listening. To correct this when you
invoke a client program, specify a --port option to indicate the proper port number, or a --socket
option to indicate the proper named pipe or Unix socket file. To find out where the socket file is, you
can use this command:
shell> netstat -ln | grep mysql

• Make sure that the server has not been configured to ignore network connections or (if you
are attempting to connect remotely) that it has not been configured to listen only locally on its
network interfaces. If the server was started with --skip-networking, it will not accept TCP/IP
connections at all. If the server was started with --bind-address=127.0.0.1, it will listen for
TCP/IP connections only locally on the loopback interface and will not accept remote connections.
• Check to make sure that there is no firewall blocking access to MySQL. Your firewall may be
configured on the basis of the application being executed, or the port number used by MySQL for
communication (3306 by default). Under Linux or Unix, check your IP tables (or similar) configuration
to ensure that the port has not been blocked. Under Windows, applications such as ZoneAlarm or
the Windows XP personal firewall may need to be configured not to block the MySQL port.
• 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, or RPM distributions on Linux), the
installation process initializes the MySQL data directory, including the mysql database containing
the grant tables. For distributions that do not do this, you must initialize the data directory manually.
For details, see Section 2.18, “Postinstallation Setup and Testing”.
To determine whether you need to initialize the grant tables, 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 not, initialize the data directory. After doing so and starting the server, test the initial
privileges by executing this command:
shell> mysql -u root

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 MySQL root user has no password initially. That is
also a security risk, so setting the password for the root accounts is something you should do while
you're setting up your other MySQL accounts. For instructions on setting the initial passwords, see
Section 2.18.4, “Securing the Initial MySQL Accounts”.
• If you have updated an existing MySQL installation to a newer version, did you run the
mysql_upgrade 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
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting Problems Connecting to MySQL

the current structure. For instructions, see Section 4.4.9, “mysql_upgrade — Check Tables for
MySQL Upgrade”.
• 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 6.1.2.4, “Password Hashing in MySQL”, and
Section B.5.2.4, “Client does not support authentication protocol”.
•

Remember that client programs use connection parameters specified in option files or
environment variables. If a client program seems to be sending incorrect default connection
parameters when you have not specified them on the command line, check any applicable option
files and your environment. For example, if you get Access denied when you run a client without
any options, make sure that you have not 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.2.6, “Using Option Files”. Environment
variables are listed in Section 2.21, “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 have not 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 6.3.5, “Assigning Account Passwords”.
If you have lost or forgotten the root password, see Section B.5.3.2, “How to Reset the Root
Password”.
• If you change a password by using SET PASSWORD, INSERT, or UPDATE, you must encrypt the
password using the PASSWORD() function. If you do not use PASSWORD() for these statements, the
password will not work. For example, the following statement assigns a password, but fails to encrypt
it, so the user is not able to connect afterward:
SET PASSWORD FOR 'abe'@'host_name' = 'eagle';

Instead, set the password like this:
SET PASSWORD FOR 'abe'@'host_name' = PASSWORD('eagle');

The PASSWORD() function is unnecessary when you specify a password using the GRANT or
(beginning with MySQL 5.0.2) CREATE USER statements, or the mysqladmin password
command. Each of those automatically uses PASSWORD() to encrypt the password. See
Section 6.3.5, “Assigning Account Passwords”, and Section 13.7.1.1, “CREATE USER Syntax”.
• localhost is a synonym for your local host name, and is also the default host to which clients try to
connect if you specify no host explicitly.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting Problems Connecting to MySQL

You can use a --host=127.0.0.1 option to name the server host explicitly. This will make a TCP/
IP connection to the local mysqld server. You can also use TCP/IP by specifying a --host option
that uses the actual host name of the local host. In this case, the host name must be specified in a
user table row on the server host, even though you are running the client program on the same host
as the server.
• The Access denied error message tells you who you are trying to log in as, the client host from
which you are trying to connect, and whether you were using a password. Normally, you should have
one row in the user table that exactly matches the host name and user name that were given in the
error message. For example, if you get an error message that contains using password: NO, it
means that you tried to log in without a password.
• If you get an Access denied error when trying to connect to the database with mysql -u
user_name, you may have a problem with the user table. Check this by executing mysql -u
root mysql and issuing this SQL statement:
SELECT * FROM user;

The result should include a row with the Host and User columns matching your client's host name
and your MySQL user name.
• 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 a Host 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 host name and user name that
you are using when trying to connect.
If you do not know the IP address or host name of the machine from which you are connecting, you
should put a row with '%' as the Host column value in the user table. After trying to connect from
the client machine, use a SELECT USER() query to see how you really did connect. Then change
the '%' in the user table row to the actual host name that shows up in the log. Otherwise, your
system is left insecure because it permits connections from any host for the given user name.
On Linux, another reason that this error might occur is that you are using a binary MySQL version
that is compiled with a different version of the glibc library than the one you are using. In this case,
you should either upgrade your operating system or glibc, or download a source distribution of
MySQL version and compile it yourself. A source RPM is normally trivial to compile and install, so
this is not a big problem.
• If you specify a host name when trying to connect, but get an error message where the host name
is not shown or is an IP address, it means that the MySQL server got an error when trying to resolve
the IP address of the client host to a name:
shell> mysqladmin -u root -pxxxx -h some_hostname ver
Access denied for user 'root'@'' (using password: YES)

If you try to connect as root and get the following error, it means that you do not have a row in the
user table with a User column value of 'root' and that mysqld cannot resolve the host name for
your client:
Access denied for user ''@'unknown'

These errors indicate a DNS problem. To fix it, execute mysqladmin flush-hosts to reset the
internal DNS host cache. See Section 8.12.6.2, “DNS Lookup Optimization and the Host Cache”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Troubleshooting Problems Connecting to MySQL

Some permanent solutions are:
• Determine what is wrong with your DNS server and fix it.
• Specify IP addresses rather than host names in the MySQL grant tables.
• Put an entry for the client machine name in /etc/hosts on Unix or \windows\hosts on
Windows.
• Start mysqld with the --skip-name-resolve option.
• Start 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. For connections to localhost, MySQL programs attempt to connect to the local
server by using a Unix socket file, unless there are connection parameters specified to ensure that
the client makes a TCP/IP connection. For more information, see Section 4.2.2, “Connecting to the
MySQL Server”.
• 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 host name . (period). Connections to . use a
named pipe rather than TCP/IP.
• If mysql -u root works but mysql -h your_hostname -u root results in Access denied
(where your_hostname is the actual host name of the local host), you may not have the correct
name for your host in the user table. A common problem here is that the Host value in the user
table row specifies an unqualified host name, but your system's name resolution routines return a
fully qualified domain name (or vice versa). For example, if you have a row with host 'pluto' in
the user table, but your DNS tells MySQL that your host name is 'pluto.example.com', the
row does not work. Try adding a row to the user table that contains the IP address of your host as
the Host column value. (Alternatively, you could add a row to the user table with a Host value
that contains a wildcard; for example, 'pluto.%'. However, use of Host values ending with “%” is
insecure and is not recommended!)
• If mysql -u user_name works but mysql -u user_name some_db does not, you have not
granted access to the given user for the database named some_db.
• If mysql -u user_name works when executed on the server host, but mysql -h host_name u user_name does not work when executed on a remote client host, you have not enabled access
to the server for the given user name from the remote host.
• If you cannot figure out why you get Access denied, remove from the user table all rows that
have Host values containing wildcards (rows that contain '%' or '_' characters). A very common
error is to insert a new row with Host='%' and User='some_user', thinking that this enables
you to specify localhost to connect from the same machine. The reason that this does not work
is that the default privileges include a row with Host='localhost' and User=''. Because that
row has a Host value 'localhost' that is more specific than '%', it is used in preference to the
new row when connecting from localhost! The correct procedure is to insert a second row with
Host='localhost' and User='some_user', or to delete the row with Host='localhost' and
User=''. After deleting the row, remember to issue a FLUSH PRIVILEGES statement to reload the
grant tables. See also Section 6.2.4, “Access Control, Stage 1: Connection Verification”.
• If you are able to connect to the MySQL server, but get an Access denied message whenever you
issue a SELECT ... INTO OUTFILE or LOAD DATA INFILE statement, your row in the user
table does not have the FILE privilege enabled.
• If you change the grant tables directly (for example, by using INSERT, UPDATE, or DELETE
statements) and your changes seem to be ignored, remember that you must execute a FLUSH
PRIVILEGES statement or a mysqladmin flush-privileges command to cause the server to
reload the privilege tables. Otherwise, your changes have no effect until the next time the server is

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL User Account Management

restarted. Remember that after you change the root password with an UPDATE statement, you will
not need to specify the new password until after you flush the privileges, because the server will not
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 6.2.6, “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 or mysql -u user_name -pyour_pass
db_name. If you are able to connect using the mysql client, the problem lies with your program, not
with the access privileges. (There is no space between -p and the password; you can also use the
--password=your_pass syntax to specify the password. If you use the -p or --password option
with no password value, MySQL prompts you for the password.)
• For testing purposes, start the mysqld server with the --skip-grant-tables option. Then
you can change the MySQL grant tables and use the mysqlaccess script to check whether
your modifications have the desired effect. When you are satisfied with your changes, execute
mysqladmin flush-privileges to tell the mysqld server to reload the privileges. This enables
you to begin using the new grant table contents without stopping and restarting the server.
• If you get the following error, you may have a problem with the db or host table:
Access to database denied

If the row selected from the db table has an empty value in the Host column, make sure that there
are one or more corresponding rows in the host table specifying which hosts the db table row
applies to. This problem occurs infrequently because the host table is rarely used.
• If everything else fails, start the mysqld server with a debugging option (for example, -debug=d,general,query). This prints host and user information about attempted connections, as
well as information about each command issued. See Section 21.3.3, “The DBUG Package”.
• 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 mysqldump mysql command. To file a bug report, see the instructions at Section 1.7, “How to
Report Bugs or Problems”. In some cases, you may need to restart mysqld with --skip-granttables to run mysqldump.

6.3 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
See also Section 13.7.1, “Account Management Statements”, which describes the syntax and use for
all user-management SQL statements.

6.3.1 User Names and Passwords
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

User Names and Passwords

MySQL stores accounts in the user table of the mysql system database. An account is defined in
terms of a user name and the client host or hosts from which the user can connect to the server. The
account may also have a password. For information about account representation in the user table,
see Section 6.2.2, “Grant Tables”.
There are several distinctions between the way user names and passwords are used by MySQL and
your operating system:
• User names, as used by MySQL for authentication purposes, have nothing to do with user names
(login names) as used by Windows or Unix. On Unix, most MySQL clients by default try to log in
using the current Unix user name as the MySQL user name, but that is for convenience only. The
default can be overridden easily, because client programs permit any user name to be specified
with a -u or --user option. This means that anyone can attempt to connect to the server using
any user name, so you cannot make a database secure in any way unless all MySQL accounts
have passwords. Anyone who specifies a user name for an account that has no password is able to
connect successfully to the server.
• MySQL user names can be up to 16 characters long. Operating system user names may be of a
different maximum length. For example, Unix user names typically are limited to eight characters.
Warning
The limit on MySQL user name length is hard-coded in MySQL servers and
clients, and trying to circumvent it by modifying the definitions of the tables in
the mysql database does not work.
You should never alter the structure of tables in the mysql database in any
manner whatsoever except by means of the procedure that is described in
Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.
Attempting to redefine MySQL's system tables in any other fashion results in
undefined (and unsupported!) behavior. The server is free to ignore rows that
become malformed as a result of such modifications.
• To authenticate client connections that use MySQL built-in authentication, the server uses MySQL
passwords stored in the user table. These passwords are distinct from passwords for logging in to
your operating system. There is no necessary connection between the “external” 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 stored in the user table using its own algorithm. This encryption is the
same as that implemented by the PASSWORD() SQL function but differs from that used during the
Unix login process. Unix password encryption is the same as that implemented by the ENCRYPT()
SQL function. See the descriptions of the PASSWORD() and ENCRYPT() functions in Section 12.12,
“Encryption and Compression Functions”.
From version 4.1 on, MySQL employs a stronger authentication method that has better password
protection during the connection process than in earlier versions. It is secure even if TCP/IP packets
are sniffed or the mysql database is captured. (In earlier versions, even though passwords are
stored in encrypted form in the user table, knowledge of the encrypted password value could be
used to connect to the MySQL server.) Section 6.1.2.4, “Password Hashing in MySQL”, discusses
password encryption further.
• If the user name and password contain only ASCII characters, it is possible to connect to the
server regardless of character set settings. To connect when the user name or password contain
non-ASCII characters, the client should call the mysql_options() C API function with the
MYSQL_SET_CHARSET_NAME option and appropriate character set name as arguments. This causes
authentication to take place using the specified character set. Otherwise, authentication will fail
unless the server default character set is the same as the encoding in the authentication defaults.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Adding User Accounts

Standard MySQL client programs support a --default-character-set option that causes
mysql_options() to be called as just described. For programs that use a connector that is not
based on the C API, the connector may provide an equivalent to mysql_options() that can be
used instead. Check the connector documentation.
The preceding notes do not apply for ucs2, which is not permitted as a client character set.
The MySQL installation process populates the grant tables with an initial account or accounts. The
names and access privileges for these accounts are described in Section 2.18.4, “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 statements such as CREATE USER, DROP USER,
GRANT, and REVOKE. See Section 13.7.1, “Account Management Statements”.
To connect to a MySQL server with a command-line client, specify user name and password options as
necessary for the account that you want to use:
shell> mysql --user=monty --password db_name

If you prefer short options, the command looks like this:
shell> mysql -u monty -p db_name

If you omit the password value following the --password or -p option on the command line (as just
shown), the client prompts for one. Alternatively, the password can be specified on the command line:
shell> mysql --user=monty --password=password db_name
shell> mysql -u monty -ppassword db_name

If you use the -p option, there must be no space between -p and the following password value.
Specifying a password on the command line should be considered insecure. See Section 6.1.2.1, “EndUser Guidelines for Password Security”. You can use an option file to avoid giving the password on the
command line. See Section 4.2.6, “Using Option Files”.
For additional information about specifying user names, passwords, and other connection parameters,
see Section 4.2.2, “Connecting to the MySQL Server”.

6.3.2 Adding User Accounts
You can create MySQL accounts two ways:
• By using account-management statements intended for creating accounts and establishing their
privileges, such as CREATE USER and GRANT. These statements cause the server to make
appropriate modifications to the underlying grant tables.
• By manipulating the MySQL grant tables directly with statements such as INSERT, UPDATE, or
DELETE.
The preferred method is to use account-management statements because they are more concise
and less error-prone than manipulating the grant tables directly. All such statements are described in
Section 13.7.1, “Account Management Statements”. Direct grant table manipulation is discouraged,
and the server is free to ignore rows that become malformed as a result of such modifications.
Another option for creating accounts is to use the GUI tool MySQL Workbench. Also, several third-party
programs offer capabilities for MySQL account administration. phpMyAdmin is one such program.
The following examples show how to use the mysql client program to set up new accounts.
These examples assume that privileges have been set up according to the defaults described in
Section 2.18.4, “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, which has the CREATE
USER privilege, the INSERT privilege for the mysql database and the RELOAD administrative privilege.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Adding User Accounts

As noted in the examples where appropriate, some of the statements will fail if the server's SQL
mode has been set to enable certain restrictions. In particular, strict mode (STRICT_TRANS_TABLES,
STRICT_ALL_TABLES) and NO_AUTO_CREATE_USER will prevent the server from accepting some
of the statements. Workarounds are indicated for these cases. For more information about SQL
modes and their effect on grant table manipulation, see Section 5.1.7, “Server SQL Modes”, and
Section 13.7.1.3, “GRANT Syntax”.
First, use the mysql program to connect to the server as the MySQL root user:
shell> mysql --user=root mysql

If you have assigned a password to the root account, you must also supply a --password or -p
option, both for this mysql command and for those later in this section.
After connecting to the server as root, you can add new accounts. The following example uses
CREATE USER and GRANT statements to set up four accounts:
mysql>
mysql>
->
mysql>
mysql>
->
mysql>
mysql>
mysql>

CREATE USER 'monty'@'localhost' IDENTIFIED BY 'some_pass';
GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'
WITH GRANT OPTION;
CREATE USER 'monty'@'%' IDENTIFIED BY 'some_pass';
GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'
WITH GRANT OPTION;
CREATE USER 'admin'@'localhost' IDENTIFIED BY 'admin_pass';
GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';
CREATE USER 'dummy'@'localhost';

The accounts created by those statements have the following properties:
• Two accounts have a user name of monty and a password of some_pass. Both are superuser
accounts with full privileges to do anything. The 'monty'@'localhost' account can be used only
when connecting from the local host. The 'monty'@'%' account uses the '%' wildcard for the host
part, so it can be used to connect from any host.
The 'monty'@'localhost' account is necessary if there is an anonymous-user account for
localhost. Without the 'monty'@'localhost' account, that anonymous-user account takes
precedence when monty connects from the local host and monty is treated as an anonymous user.
The reason for this is that the anonymous-user account has a more specific Host column value than
the 'monty'@'%' account and thus comes earlier in the user table sort order. (user table sorting
is discussed in Section 6.2.4, “Access Control, Stage 1: Connection Verification”.)
• The 'admin'@'localhost' account has a password of admin_pass. This account can be used
only by admin to connect from the local host. It is granted the RELOAD and PROCESS administrative
privileges. These privileges enable the admin user to execute the mysqladmin reload,
mysqladmin refresh, and mysqladmin flush-xxx commands, as well as mysqladmin
processlist . No privileges are granted for accessing any databases. You could add such
privileges using GRANT statements.
• The 'dummy'@'localhost' account has no password (which is insecure and not recommended).
This account can be used only to connect from the local host. No privileges are granted. It is
assumed that you will grant specific privileges to the account using GRANT statements.
The statements that create accounts with no password will fail if the NO_AUTO_CREATE_USER SQL
mode is enabled. To deal with this, use an IDENTIFIED BY clause that specifies a nonempty
password.
To see the privileges for an account, use SHOW GRANTS:
mysql> SHOW GRANTS FOR 'admin'@'localhost';
+-----------------------------------------------------+
| Grants for admin@localhost
|
+-----------------------------------------------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Adding User Accounts

| GRANT RELOAD, PROCESS ON *.* TO 'admin'@'localhost' |
+-----------------------------------------------------+

As an alternative to CREATE USER and GRANT, you can create the same accounts directly by issuing
INSERT statements and then telling the server to reload the grant tables using FLUSH PRIVILEGES:
shell>
mysql>
->
->
mysql>
->
->
->
->
mysql>
->
->
mysql>
->
mysql>

mysql --user=root mysql
INSERT INTO user
VALUES('localhost','monty',PASSWORD('some_pass'),
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
INSERT INTO user
VALUES('%','monty',PASSWORD('some_pass'),
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y',
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y',
'','','','',0,0,0,0);
INSERT INTO user SET Host='localhost',User='admin',
Password=PASSWORD('admin_pass'),
Reload_priv='Y', Process_priv='Y';
INSERT INTO user (Host,User,Password)
VALUES('localhost','dummy','');
FLUSH PRIVILEGES;

When you create accounts with INSERT, it is necessary to use FLUSH PRIVILEGES to tell the server
to reload the grant tables. Otherwise, the changes go unnoticed until you restart the server. With
CREATE USER, FLUSH PRIVILEGES is unnecessary.
The reason for using the PASSWORD() function with INSERT is to encrypt the password. The CREATE
USER statement encrypts the password for you, so PASSWORD() is unnecessary.
The 'Y' values enable privileges for the accounts. Depending on your MySQL version, you may have
to use a different number of 'Y' values in the first two INSERT statements. The INSERT statement for
the admin account employs the more readable extended INSERT syntax using SET.
In the INSERT statement for the dummy account, only the Host, User, and Password columns in
the user table row are assigned values. None of the privilege columns are set explicitly, so MySQL
assigns them all the default value of 'N'. This is equivalent to what CREATE USER does.
If strict SQL mode is enabled, all columns that have no default value must have a value specified. In
this case, INSERT statements must explicitly specify values for the ssl_cipher, x509_issuer, and
x509_subject columns.
To set up a superuser account, it is necessary only to insert a user table row with all privilege columns
set to 'Y'. The user table privileges are global, so no entries in any of the other grant tables are
needed.
The next examples create three accounts and grant them access to specific databases. Each of them
has a user name of custom and password of obscure.
To create the accounts with CREATE USER and GRANT, use the following statements:
shell>
mysql>
mysql>
->
->
mysql>
mysql>
->
->
mysql>
mysql>
->
->

mysql --user=root mysql
CREATE USER 'custom'@'localhost' IDENTIFIED BY 'obscure';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON bankaccount.*
TO 'custom'@'localhost';
CREATE USER 'custom'@'host47.example.com' IDENTIFIED BY 'obscure';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON expenses.*
TO 'custom'@'host47.example.com';
CREATE USER 'custom'@'%.example.com' IDENTIFIED BY 'obscure';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP
ON customer.*
TO 'custom'@'%.example.com';

The three accounts can be used as follows:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Removing User Accounts

• The first account can access the bankaccount database, but only from the local host.
• The second account can access the expenses database, but only from the host
host47.example.com.
• The third account can access the customer database, from any host in the example.com domain.
This account has access from all machines in the domain due to use of the “%” wildcard character in
the host part of the account name.
To set up the custom accounts without GRANT, use INSERT statements as follows to modify the grant
tables directly:
shell>
mysql>
->
mysql>
->
mysql>
->
mysql>
->
->
->
->
mysql>
->
->
->
->
mysql>
->
->
->
->
mysql>

mysql --user=root mysql
INSERT INTO user (Host,User,Password)
VALUES('localhost','custom',PASSWORD('obscure'));
INSERT INTO user (Host,User,Password)
VALUES('host47.example.com','custom',PASSWORD('obscure'));
INSERT INTO user (Host,User,Password)
VALUES('%.example.com','custom',PASSWORD('obscure'));
INSERT INTO db
(Host,Db,User,Select_priv,Insert_priv,
Update_priv,Delete_priv,Create_priv,Drop_priv)
VALUES('localhost','bankaccount','custom',
'Y','Y','Y','Y','Y','Y');
INSERT INTO db
(Host,Db,User,Select_priv,Insert_priv,
Update_priv,Delete_priv,Create_priv,Drop_priv)
VALUES('host47.example.com','expenses','custom',
'Y','Y','Y','Y','Y','Y');
INSERT INTO db
(Host,Db,User,Select_priv,Insert_priv,
Update_priv,Delete_priv,Create_priv,Drop_priv)
VALUES('%.example.com','customer','custom',
'Y','Y','Y','Y','Y','Y');
FLUSH PRIVILEGES;

The first three INSERT statements add user table entries that permit the user custom to connect from
the various hosts with the given password, but grant no global privileges (all privileges are set to the
default value of 'N'). The next three INSERT statements add db table entries that grant privileges to
custom for the bankaccount, expenses, and customer databases, but only when accessed from
the proper hosts. As usual when you modify the grant tables directly, you must tell the server to reload
them with FLUSH PRIVILEGES so that the privilege changes take effect.

6.3.3 Removing User Accounts
To remove an account, use the DROP USER statement, which is described in Section 13.7.1.2, “DROP
USER Syntax”. For example:
mysql> DROP USER 'jeffrey'@'localhost';

6.3.4 Setting Account Resource Limits
One means of restricting client use of MySQL server resources is to set the global
max_user_connections system variable to a nonzero value. This limits the number of simultaneous
connections that can be made by any given account, but places no limits on what a client can do once
connected. In addition, setting max_user_connections does not enable management of individual
accounts. Both types of control are of interest to MySQL administrators.
To address such concerns, MySQL permits limits for individual accounts on use of these server
resources:
• The number of queries an account can issue per hour
• The number of updates an account can issue per hour
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Setting Account Resource Limits

• The number of times an account can connect to the server per hour
• The number of simultaneous connections to the server by an account
Any statement that a client can issue counts against the query limit, unless its results are served from
the query cache. Only statements that modify databases or tables count against the update limit.
An “account” in this context corresponds to a row in the mysql.user table. That is, a connection is
assessed against the User and Host values in the user table row that applies to the connection. For
example, an account 'usera'@'%.example.com' corresponds to a row in the user table that has
User and Host values of usera and %.example.com, to permit usera to connect from any host in
the example.com domain. In this case, the server applies resource limits in this row collectively to all
connections by usera from any host in the example.com domain because all such connections use
the same account.
Before MySQL 5.0.3, an “account” was assessed against the actual host from which a user connects.
This older method of accounting may be selected by starting the server with the --old-styleuser-limits option. In this case, if usera connects simultaneously from host1.example.com and
host2.example.com, the server applies the account resource limits separately to each connection.
If usera connects again from host1.example.com, the server applies the limits for that connection
together with the existing connection from that host.
To establish resource limits for an account, use the GRANT statement (see Section 13.7.1.3, “GRANT
Syntax”). Provide a WITH clause that names each resource to be limited. The default value for each
limit is zero (no limit). For example, to create a new account that can access the customer database,
but only in a limited fashion, issue these statements:
mysql> CREATE USER 'francis'@'localhost' IDENTIFIED BY 'frank';
mysql> GRANT ALL ON customer.* TO 'francis'@'localhost'
->
WITH MAX_QUERIES_PER_HOUR 20
->
MAX_UPDATES_PER_HOUR 10
->
MAX_CONNECTIONS_PER_HOUR 5
->
MAX_USER_CONNECTIONS 2;

The limit types need not all be named in the WITH clause, but those named can be present in any
order. The value for each per-hour limit should be an integer representing a count per hour. For
MAX_USER_CONNECTIONS, the limit is an integer representing the maximum number of simultaneous
connections by the account. If this limit is set to zero, the global max_user_connections system
variable value determines the number of simultaneous connections. If max_user_connections is
also zero, there is no limit for the account.
To modify limits for an existing account, use a GRANT USAGE statement at the global level (ON *.*).
The following statement changes the query limit for francis to 100:
mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
->
WITH MAX_QUERIES_PER_HOUR 100;

The statement modifies only the limit value specified and leaves the account otherwise unchanged.
To remove a limit, set its value to zero. For example, to remove the limit on how many times per hour
francis can connect, use this statement:
mysql> GRANT USAGE ON *.* TO 'francis'@'localhost'
->
WITH MAX_CONNECTIONS_PER_HOUR 0;

As mentioned previously, the simultaneous-connection limit for an account is determined from the
MAX_USER_CONNECTIONS limit and the max_user_connections system variable. Suppose that
the global max_user_connections value is 10 and three accounts have individual resource limits
specified as follows:
GRANT ... TO 'user1'@'localhost' WITH MAX_USER_CONNECTIONS 0;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Assigning Account Passwords

GRANT ... TO 'user2'@'localhost' WITH MAX_USER_CONNECTIONS 5;
GRANT ... TO 'user3'@'localhost' WITH MAX_USER_CONNECTIONS 20;

user1 has a connection limit of 10 (the global max_user_connections value) because it has
a MAX_USER_CONNECTIONS limit of zero. user2 and user3 have connection limits of 5 and 20,
respectively, because they have nonzero MAX_USER_CONNECTIONS limits.
The server stores resource limits for an account in the user table row corresponding to the account.
The max_questions, max_updates, and max_connections columns store the per-hour limits,
and the max_user_connections column stores the MAX_USER_CONNECTIONS limit. (See
Section 6.2.2, “Grant Tables”.) If your user table does not have these columns, it must be upgraded;
see Section 4.4.9, “mysql_upgrade — Check Tables for MySQL Upgrade”.
Resource-use counting takes place when any account has a nonzero limit placed on its use of any of
the resources.
As the server runs, it counts the number of times each account uses resources. If an account reaches
its limit on number of connections within the last hour, the server rejects further connections for the
account until that hour is up. Similarly, if the account reaches its limit on the number of queries or
updates, the server rejects further queries or updates until the hour is up. In all such cases, the server
issues appropriate error messages.
Resource counting occurs per account, not per client. For example, if your account has a query limit of
50, you cannot increase your limit to 100 by making two simultaneous client connections to the server.
Queries issued on both connections are counted together.
The current per-hour resource-use counts can be reset globally for all accounts, or individually for a
given account:
• To reset the current counts to zero for all accounts, issue a FLUSH USER_RESOURCES statement.
The counts also can be reset by reloading the grant tables (for example, with a FLUSH PRIVILEGES
statement or a mysqladmin reload command).
• The counts for an individual account can be reset to zero by setting any of its limits again. Specify a
limit value equal to the value currently assigned to the account.
Per-hour counter resets do not affect the MAX_USER_CONNECTIONS limit.
All counts begin at zero when the server starts. Counts do not carry over through server restarts.
For the MAX_USER_CONNECTIONS limit, an edge case can occur if the account currently has open the
maximum number of connections permitted to it: A disconnect followed quickly by a connect can result
in an error (ER_TOO_MANY_USER_CONNECTIONS or ER_USER_LIMIT_REACHED) if the server has not
fully processed the disconnect by the time the connect occurs. When the server finishes disconnect
processing, another connection will once more be permitted.

6.3.5 Assigning Account Passwords
Required credentials for clients that connect to the MySQL server can include a password. This section
describes how to assign passwords for MySQL accounts.
MySQL stores passwords in the user table in the mysql system database. Operations that assign
or modify passwords are permitted only to users with the CREATE USER privilege, or, alternatively,
privileges for the mysql database (INSERT privilege to create new accounts, UPDATE privilege to
modify existing accounts).
The discussion here summarizes syntax only for the most common password-assignment statements.
For complete details on other possibilities, see Section 13.7.1.1, “CREATE USER Syntax”,
Section 13.7.1.3, “GRANT Syntax”, and Section 13.7.1.6, “SET PASSWORD Syntax”.
MySQL hashes passwords stored in the mysql.user table to obfuscate them. For most statements
described here, MySQL automatically hashes the password specified. An exception is SET
PASSWORD ... = PASSWORD('auth_string'), for which you use the PASSWORD() function
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

explicitly to hash the password. There are also syntaxes for CREATE USER, GRANT, and SET
PASSWORD that permit hashed values to be specified literally; for details, see the descriptions of those
statements.
To assign a password when you create a new account, use CREATE USER and include an
IDENTIFIED BY clause:
mysql> CREATE USER 'jeffrey'@'localhost'
-> IDENTIFIED BY 'mypass';

For this CREATE USER syntax, MySQL automatically hashes the password before storing it in the
mysql.user table.
To assign or change a password for an existing account, use one of the following methods:
• Use SET PASSWORD with the PASSWORD() function:
mysql> SET PASSWORD FOR
-> 'jeffrey'@'localhost' = PASSWORD('mypass');

If you are not connected as an anonymous user, you can change your own password by omitting the
FOR clause:
mysql> SET PASSWORD = PASSWORD('mypass');

The PASSWORD() function hashes the password using the hashing method determined by the value
of the old_passwords system variable value. If SET PASSWORD rejects the hashed password
value returned by PASSWORD() as not being in the correct format, it may be necessary to change
old_passwords to change the hashing method. For descriptions of the permitted values, see
Section 5.1.4, “Server System Variables”.
• You can also use a GRANT USAGE statement at the global level (ON *.*) to assign a password to
an account without affecting the account's current privileges:
mysql> GRANT USAGE ON *.* TO 'jeffrey'@'localhost'
-> IDENTIFIED BY 'mypass';

For this GRANT syntax, MySQL automatically hashes the password before storing it in the
mysql.user table.
• To change an account password from the command line, use the mysqladmin command:
shell> mysqladmin -u user_name -h host_name password "new_password"

The account for which this command sets the password is the one with a mysql.user table row that
matches user_name in the User column and the client host from which you connect in the Host
column.
For password changes made using mysqladmin, MySQL automatically hashes the password before
storing it in the mysql.user table.

6.3.6 Using Secure Connections
With an unencrypted connection between the MySQL client and the server, someone with access to
the network could watch all your traffic and inspect the data being sent or received between client and
server.
When you must move information over a network in a secure fashion, an unencrypted connection
is unacceptable. To make any kind of data unreadable, use encryption. Encryption algorithms must
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

include security elements to resist many kinds of known attacks such as changing the order of
encrypted messages or replaying data twice.
MySQL supports secure (encrypted) connections between clients and the server using the TLS
(Transport Layer Security) protocol. TLS is sometimes referred to as SSL (Secure Sockets Layer).
TLS uses encryption algorithms to ensure that data received over a public network can be trusted. It
has mechanisms to detect data change, loss, or replay. TLS also incorporates algorithms that provide
identity verification using the X509 standard.
X509 makes it possible to identify someone on the Internet. In basic terms, there should be some entity
called a “Certificate Authority” (or CA) that assigns electronic certificates to anyone who needs them.
Certificates rely on asymmetric encryption algorithms that have two encryption keys (a public key and
a secret key). A certificate owner can present the certificate to another party as proof of identity. A
certificate consists of its owner's public key. Any data encrypted using this public key can be decrypted
only using the corresponding secret key, which is held by the owner of the certificate.
For more information about TLS, SSL, X509, encryption, or public-key cryptography, perform an
Internet search for the keywords in which you are interested.
MySQL can be compiled for secure-connection support using OpenSSL or yaSSL. For a comparison of
the two packages, see Section 6.3.6.1, “OpenSSL Versus yaSSL” For information about the encryption
protocols and ciphers each package supports, see Section 6.3.6.3, “Secure Connection Protocols and
Ciphers”.
MySQL performs encryption on a per-connection basis, and use of encryption can be optional or
mandatory. This enables you to choose an encrypted or unencrypted connection according to the
requirements of individual applications. For information on how to require users to use encrypted
connections, see the discussion of the REQUIRE clause of the GRANT statement in Section 13.7.1.3,
“GRANT Syntax”.
Encrypted connections are not used by default. For applications that require the security provided by
encrypted connections, the extra computation to encrypt the data is worthwhile.
Secure connections are available through the MySQL C API using the mysql_ssl_set() and
mysql_options() functions. See Section 20.6.7.67, “mysql_ssl_set()”, and Section 20.6.7.49,
“mysql_options()”.
Replication uses the C API, so secure connections can be used between master and slave servers.
See Section 16.3.7, “Setting Up Replication to Use Secure Connections”.
It is also possible to connect securely from within an SSH connection to the MySQL server host. For an
example, see Section 6.3.8, “Connecting to MySQL Remotely from Windows with SSH”.

6.3.6.1 OpenSSL Versus yaSSL
MySQL can be compiled using OpenSSL or yaSSL, both of which enable secure conections based on
the OpenSSL API.
OpenSSL and yaSSL offer the same basic functionality, but additional features are available in
MySQL distributions compiled using OpenSSL: OpenSSL supports a wider range of encryption ciphers
from which to choose for the --ssl-cipher option, and supports the --ssl-capath option. See
Section 6.3.6.5, “Command Options for Secure Connections”.

6.3.6.2 Building MySQL with Support for Secure Connections
To use SSL connections between the MySQL server and client programs, your system must support
either OpenSSL or yaSSL, and your version of MySQL must be built with SSL support. To make it
easier to use secure connections, as of version 5.0.10, MySQL is bundled with yaSSL, which uses the
same licensing model as MySQL. (OpenSSL uses an Apache-style license.) yaSSL support is available
on all platforms supported by Oracle Corporation.
To get secure connections to work with MySQL and SSL, you must do the following:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

1. If you are not using a binary (precompiled) version of MySQL that has been built with SSL support,
and you are going to use OpenSSL rather than the bundled yaSSL library, install OpenSSL if it has
not already been installed. We have tested MySQL with OpenSSL 0.9.6. To obtain OpenSSL, visit
http://www.openssl.org.
Building MySQL using OpenSSL requires a shared OpenSSL library, otherwise linker errors occur.
Alternatively, build MySQL using yaSSL.
2. If you are not using a binary (precompiled) version of MySQL that has been built with SSL support,
configure a MySQL source distribution to use SSL. When you configure MySQL, invoke the
configure script with the appropriate option to select the SSL library that you want to use.
For yaSSL:
shell> ./configure --with-yassl

For OpenSSL:
shell> ./configure --with-openssl

Before MySQL 5.0, it was also neccessary to use --with-vio, but that option is no longer
required.
Then compile and install the distribution.
On Unix platforms, yaSSL retrieves true random numbers from either /dev/urandom or /dev/
random. Bug#13164 lists workarounds for some very old platforms which do not support these
devices.
3. To check whether a server binary is compiled with SSL support, invoke it with the --ssl option. An
error will occur if the server does not support SSL:
shell> mysqld --ssl --help
060525 14:18:52 [ERROR] mysqld: unknown option '--ssl'

To check whether a running mysqld server supports secure connections, examine the value of the
have_ssl system variable (if you have no have_ssl variable, check for have_openssl):
mysql> SHOW VARIABLES LIKE 'have_ssl';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| have_ssl
| YES
|
+---------------+-------+

If the value is YES, the server supports secure connections. If the value is DISABLED, the server
is capable of supporting secure connections but was not started with the appropriate --ssl-xxx
options to enable secure connections to be used; see Section 6.3.6.4, “Configuring MySQL to Use
Secure Connections”.

6.3.6.3 Secure Connection Protocols and Ciphers
To determine which encryption protocol and cipher are in use for an encrypted connection, use the
following statements to check the values of the Ssl_version and Ssl_cipher status variables:
mysql> SHOW SESSION STATUS LIKE 'Ssl_version';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| Ssl_version
| TLSv1 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

+---------------+-------+
mysql> SHOW SESSION STATUS LIKE 'Ssl_cipher';
+---------------+--------------------+
| Variable_name | Value
|
+---------------+--------------------+
| Ssl_cipher
| DHE-RSA-AES256-SHA |
+---------------+--------------------+

If the connection is not encrypted, both variables have an empty value.
MySQL supports encrypted connections using the TLSv1 protocol.
To determine which ciphers a given server supports, use the following statement to check the value of
the Ssl_cipher_list status variable:
SHOW SESSION STATUS LIKE 'Ssl_cipher_list';

The set of available ciphers depends on your MySQL version and whether MySQL was compiled using
OpenSSL or yaSSL, and (for OpenSSL) the library version used to compile MySQL.
For example, for OpenSSL, the list may include these ciphers:
AES256-GCM-SHA384
AES256-SHA
AES256-SHA256
CAMELLIA256-SHA
DES-CBC3-SHA
DHE-DSS-AES256-GCM-SHA384
DHE-DSS-AES256-SHA
DHE-DSS-AES256-SHA256
DHE-DSS-CAMELLIA256-SHA
DHE-RSA-AES256-GCM-SHA384
DHE-RSA-AES256-SHA
DHE-RSA-AES256-SHA256
DHE-RSA-CAMELLIA256-SHA
ECDH-ECDSA-AES256-GCM-SHA384
ECDH-ECDSA-AES256-SHA
ECDH-ECDSA-AES256-SHA384
ECDH-ECDSA-DES-CBC3-SHA
ECDH-RSA-AES256-GCM-SHA384
ECDH-RSA-AES256-SHA
ECDH-RSA-AES256-SHA384
ECDH-RSA-DES-CBC3-SHA
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-SHA
ECDHE-ECDSA-AES128-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA
ECDHE-ECDSA-AES256-SHA384
ECDHE-ECDSA-DES-CBC3-SHA
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-SHA
ECDHE-RSA-AES128-SHA256
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-SHA
ECDHE-RSA-AES256-SHA384
ECDHE-RSA-DES-CBC3-SHA
EDH-DSS-DES-CBC3-SHA
EDH-RSA-DES-CBC3-SHA
PSK-3DES-EDE-CBC-SHA
PSK-AES256-CBC-SHA
SRP-DSS-3DES-EDE-CBC-SHA
SRP-DSS-AES-128-CBC-SHA
SRP-DSS-AES-256-CBC-SHA
SRP-RSA-3DES-EDE-CBC-SHA
SRP-RSA-AES-128-CBC-S
SRP-RSA-AES-256-CBC-SHA

yaSSL supports these ciphers:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

AES128-RMD
AES128-SHA
AES256-RMD
AES256-SHA
DES-CBC-SHA
DES-CBC3-RMD
DES-CBC3-SHA
DHE-RSA-AES128-RMD
DHE-RSA-AES128-SHA
DHE-RSA-AES256-RMD
DHE-RSA-AES256-SHA
DHE-RSA-DES-CBC3-RMD
EDH-RSA-DES-CBC-SHA
EDH-RSA-DES-CBC3-SHA
RC4-MD5
RC4-SHA

6.3.6.4 Configuring MySQL to Use Secure Connections
To enable secure connections, your MySQL distribution must be built with SSL support, as described
in Section 6.3.6.2, “Building MySQL with Support for Secure Connections”. In addition, the proper
options must be used to specify the appropriate certificate and key files. For a complete list of options
related to establishment of secure connections, see Section 6.3.6.5, “Command Options for Secure
Connections”.
If you need to create the required SSL files, see Section 6.3.7, “Creating SSL Certificates and Keys
Using openssl”.

Server-Side Configuration for Secure Connections
To start the MySQL server so that it permits clients to connect securely, use options that identify the
certificate and key files the server uses when establishing a secure connection:
• --ssl-ca identifies the Certificate Authority (CA) certificate.
• --ssl-cert identifies the server public key certificate. This can be sent to the client and
authenticated against the CA certificate that it has.
• --ssl-key identifies the server private key.
For example, start the server with these lines in the my.cnf file, changing the file names as necessary:
[mysqld]
ssl-ca=ca.pem
ssl-cert=server-cert.pem
ssl-key=server-key.pem

Each option names a file in PEM format. If you have a MySQL source distribution, you can test your
setup using the demonstration certificate and key files in its mysql-test/std_data directory.

Client-Side Configuration for Secure Connections
For client programs, options for secure connections are similar to those used on the server side, but -ssl-cert and --ssl-key identify the client public and private key:
• --ssl-ca identifies the Certificate Authority (CA) certificate. This option, if used, must specify the
same certificate used by the server.
• --ssl-cert identifies the client public key certificate.
• --ssl-key identifies the client private key.
To connect securely to a MySQL server that supports secure connections, the options that a client
must specify depend on the encryption requirements of the MySQL account used by the client. (See
the discussion of the REQUIRE clause in Section 13.7.1.3, “GRANT Syntax”.)
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

Suppose that you want to connect using an account that has no special encryption requirements or
was created using a GRANT statement that includes the REQUIRE SSL option. As a recommended set
of secure-connection options, start the server with at least --ssl-cert and --ssl-key, and invoke
the client with --ssl-ca. A client can connect securely like this:
shell> mysql --ssl-ca=ca.pem

To require that a client certificate also be specified, create the account using the REQUIRE X509
option. Then the client must also specify the proper client key and certificate files or the server will
reject the connection:
shell> mysql --ssl-ca=ca.pem \
--ssl-cert=client-cert.pem \
--ssl-key=client-key.pem

To prevent use of encryption and override other --ssl-xxx options, invoke the client program with -ssl=0 or a synonym (--skip-ssl, --disable-ssl):
shell> mysql --ssl=0

A client can determine whether the current connection with the server uses encryption by checking the
value of the Ssl_cipher status variable. If the value is empty, the connection is encrypted. Otherwise,
the connection is encrypted and the value indicates the encryption cipher. For example:
mysql> SHOW STATUS LIKE 'Ssl_cipher';
+---------------+--------------------+
| Variable_name | Value
|
+---------------+--------------------+
| Ssl_cipher
| DHE-RSA-AES256-SHA |
+---------------+--------------------+

For the mysql client, an alternative is to use the STATUS or \s command and check the SSL line:
mysql> \s
...
SSL: Cipher in use is DHE-RSA-AES256-SHA
...

Or:
mysql> \s
...
SSL: Not in use
...

C API Configuration for Secure Connections
The C API enables application programs to use secure connections:
• To establish a secure connection, use the mysql_ssl_set() C API function to set the
appropriate certificate options before calling mysql_real_connect(). See Section 20.6.7.67,
“mysql_ssl_set()”.
• To determine whether encryption is in use after the connection is established, use
mysql_get_ssl_cipher(). A non-NULL return value indicates an encrypted connection and
names the cipher used for encryption. A NULL return value indicates that encryption is not being
used. See Section 20.6.7.33, “mysql_get_ssl_cipher()”.
Replication uses the C API, so secure connections can be used between master and slave servers.
See Section 16.3.7, “Setting Up Replication to Use Secure Connections”.

6.3.6.5 Command Options for Secure Connections
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

This section describes options that specify whether to use secure connections and the names of
certificate and key files. These options can be given on the command line or in an option file. They are
not available unless MySQL has been built with SSL support. See Section 6.3.6.2, “Building MySQL
with Support for Secure Connections”. For examples of suggested use and how to check whether a
connection is secure, see Section 6.3.6.4, “Configuring MySQL to Use Secure Connections”. (There
are also --master-ssl* options that can be used for setting up a secure connection from a slave
replication server to a master server; see Section 16.1.2, “Replication and Binary Logging Options and
Variables”.)
Table 6.8 Secure-Connection Option Summary
Format

Description

--skip-ssl

Do not use secure connection

--ssl

Enable secure connection

--ssl-ca

Path of file that contains list of trusted SSL CAs

5.0.23

--ssl-capath

Path of directory that contains trusted SSL CA
certificates in PEM format

5.0.23

--ssl-cert

Path of file that contains X509 certificate in PEM format

5.0.23

--ssl-cipher

List of permitted ciphers to use for connection encryption 5.0.23

--ssl-key

Path of file that contains X509 key in PEM format

5.0.23

--ssl-verify-server-cert

Verify server certificate Common Name value against
host name used when connecting to server

5.0.23

•

Introduced

--ssl
For the MySQL server, this option specifies that the server permits but does not require secure
connections.
For MySQL client programs, this option permits but does not require the client to connect to the
server using encryption. Therefore, this option is not sufficient in itself to cause a secure connection
to be used. For example, if you specify this option for a client program but the server has not been
configured to support secure connections, the client falls back to an unencrypted connection.
As a recommended set of options to enable secure connections, use at least --ssl-cert and -ssl-key on the server side and --ssl-ca on the client side. See Section 6.3.6.4, “Configuring
MySQL to Use Secure Connections”.
--ssl may be implied by other --ssl-xxx options, as indicated in the descriptions for those
options.
The --ssl option in negated form overrides other --ssl-xxx options and indicates that encryption
should not be used. To do this, specify the option as --ssl=0 or a synonym (--skip-ssl, -disable-ssl). For example, you might have options specified in the [client] group of your
option file to use secure connections by default when you invoke MySQL client programs. To use an
unencrypted connection instead, invoke the client program with --ssl=0 on the command line to
override the options in the option file.
To require use of secure connections for a MySQL account, use a GRANT statement for the account
that includes at least a REQUIRE SSL clause. Connections for the account will be rejected unless
MySQL supports secure connections and the server and client have been started with the proper
secure-connection options.
The REQUIRE clause permits other encryption-related options, which can be used to enforce stricter
requirements than REQUIRE SSL. For additional details about which command options may or must
be specified by clients that connect using accounts configured using the various REQUIRE options,
see the description of REQUIRE in Section 13.7.1.3, “GRANT Syntax”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Secure Connections

• --ssl-ca=file_name
The path to a file in PEM format that contains a list of trusted SSL certificate authorities. This option
implies --ssl.
As of MySQL 5.0.40, if you use encryption when establishing a client connection, to tell the client not
to authenticate the server certificate, specify neither --ssl-ca nor --ssl-capath. The server still
verifies the client according to any applicable requirements established for the client account, and it
still uses any --ssl-ca or --ssl-capath option values specified at server startup.
• --ssl-capath=dir_name
The path to a directory that contains trusted SSL certificate authority certificates in PEM format. This
option implies --ssl.
As of MySQL 5.0.40, if you use encryption when establishing a client connection, to tell the client not
to authenticate the server certificate, specify neither --ssl-ca nor --ssl-capath. The server still
verifies the client according to any applicable requirements established for the client account, and it
still uses any --ssl-ca or --ssl-capath option values specified at server startup.
MySQL distributions compiled using OpenSSL support the --ssl-capath option (see
Section 6.3.6.1, “OpenSSL Versus yaSSL”). Distributions compiled using yaSSL do not because
yaSSL does not look in any directory and does not follow a chained certificate tree. yaSSL requires
that all components of the CA certificate tree be contained within a single CA certificate tree and that
each certificate in the file has a unique SubjectName value. To work around this yaSSL limitation,
concatenate the individual certificate files comprising the certificate tree into a new file and specify
that file as the value of the --ssl-ca option.
• --ssl-cert=file_name
The name of the SSL certificate file in PEM format to use for establishing a secure connection. This
option implies --ssl.
• --ssl-cipher=cipher_list
A list of permissible ciphers to use for connection encryption. If no cipher in the list is supported,
encrypted connections will not work. This option implies --ssl.
For greatest portability, cipher_list should be a list of one or more cipher names, separated by
colons. This format is understood both by OpenSSL and yaSSL. Examples:
--ssl-cipher=AES128-SHA
--ssl-cipher=DHE-RSA-AES256-SHA:AES128-SHA

OpenSSL supports a more flexible syntax for specifying ciphers, as described in the OpenSSL
documentation at http://www.openssl.org/docs/apps/ciphers.html. However, yaSSL does not, so
attempts to use that extended syntax fail for a MySQL distribution compiled using yaSSL.
For information about which encryption ciphers MySQL supports, see Section 6.3.6.3, “Secure
Connection Protocols and Ciphers”.
• --ssl-key=file_name
The name of the SSL key file in PEM format to use for establishing a secure connection. This option
implies --ssl.
If the MySQL distribution was compiled using OpenSSL and the key file is protected by a
passphrase, the program prompts the user for the passphrase. The password must be given
interactively; it cannot be stored in a file. If the passphrase is incorrect, the program continues as if it
could not read the key. If the MySQL distribution was built using yaSSL and the key file is protected
by a passphrase, an error occurs.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating SSL Certificates and Keys Using openssl

• --ssl-verify-server-cert
This option is available only for client programs, not the server. It causes the client to check the
server's Common Name value in the certificate that the server sends to the client. The client verifies
that name against the host name the client uses for connecting to the server, and the connection
fails if there is a mismatch. For encrypted connections, this option helps prevent man-in-the-middle
attacks. Verification is disabled by default. This option was added in MySQL 5.0.23.

6.3.7 Creating SSL Certificates and Keys Using openssl
This section describes how to use the openssl command to set up SSL certificate and key files
for use by MySQL servers and clients. The first example shows a simplified procedure such as you
might use from the command line. The second shows a script that contains more detail. The first two
examples are intended for use on Unix and both use the openssl command that is part of OpenSSL.
The third example describes how to set up SSL files on Windows.
Important
Whatever method you use to generate the certificate and key files, the Common
Name value used for the server and client certificates/keys must each differ
from the Common Name value used for the CA certificate. Otherwise, the
certificate and key files will not work for servers compiled using OpenSSL. A
typical error in this case is:
ERROR 2026 (HY000): SSL connection error:
error:00000001:lib(0):func(0):reason(1)

Example 1: Creating SSL Files from the Command Line on Unix
The following example shows a set of commands to create MySQL server and client certificate and key
files. You will need to respond to several prompts by the openssl commands. To generate test files,
you can press Enter to all prompts. To generate files for production use, you should provide nonempty
responses.
# Create clean environment
shell> rm -rf newcerts
shell> mkdir newcerts && cd newcerts
# Create CA certificate
shell> openssl genrsa 2048 > ca-key.pem
shell> openssl req -new -x509 -nodes -days 3600 \
-key ca-key.pem -out ca.pem
# Create server certificate, remove passphrase, and sign it
# server-cert.pem = public key, server-key.pem = private key
shell> openssl req -newkey rsa:2048 -days 3600 \
-nodes -keyout server-key.pem -out server-req.pem
shell> openssl rsa -in server-key.pem -out server-key.pem
shell> openssl x509 -req -in server-req.pem -days 3600 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 -out server-cert.pem
# Create client certificate, remove passphrase, and sign it
# client-cert.pem = public key, client-key.pem = private key
shell> openssl req -newkey rsa:2048 -days 3600 \
-nodes -keyout client-key.pem -out client-req.pem
shell> openssl rsa -in client-key.pem -out client-key.pem
shell> openssl x509 -req -in client-req.pem -days 3600 \
-CA ca.pem -CAkey ca-key.pem -set_serial 01 -out client-cert.pem

After generating the certificates, verify them:
shell> openssl verify -CAfile ca.pem server-cert.pem client-cert.pem
server-cert.pem: OK
client-cert.pem: OK

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating SSL Certificates and Keys Using openssl

Now you have a set of files that can be used as follows:
• ca.pem: Use this as the argument to --ssl-ca on the server and client sides. (The CA certificate, if
used, must be the same on both sides.)
• server-cert.pem, server-key.pem: Use these as the arguments to --ssl-cert and --sslkey on the server side.
• client-cert.pem, client-key.pem: Use these as the arguments to --ssl-cert and --sslkey on the client side.
To use the files for SSL connections, see Section 6.3.6.4, “Configuring MySQL to Use Secure
Connections”.

Example 2: Creating SSL Files Using a Script on Unix
Here is an example script that shows how to set up SSL certificate and key files for MySQL. After
executing the script, use the files for SSL connections as described in Section 6.3.6.4, “Configuring
MySQL to Use Secure Connections”.
DIR=`pwd`/openssl
PRIV=$DIR/private
mkdir $DIR $PRIV $DIR/newcerts
cp /usr/share/ssl/openssl.cnf $DIR
replace ./demoCA $DIR -- $DIR/openssl.cnf
# Create necessary files: $database, $serial and $new_certs_dir
# directory (optional)
touch $DIR/index.txt
echo "01" > $DIR/serial
#
# Generation of Certificate Authority(CA)
#
openssl req -new -x509 -keyout $PRIV/cakey.pem -out $DIR/ca.pem \
-days 3600 -config $DIR/openssl.cnf
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#

Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
................++++++
.........++++++
writing new private key to '/home/monty/openssl/private/cakey.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL admin
Email Address []:

#
# Create server request and key
#
openssl req -new -keyout $DIR/server-key.pem -out \

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating SSL Certificates and Keys Using openssl

$DIR/server-req.pem -days 3600 -config $DIR/openssl.cnf
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#

Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
..++++++
..........++++++
writing new private key to '/home/monty/openssl/server-key.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL server
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

#
# Remove the passphrase from the key
#
openssl rsa -in $DIR/server-key.pem -out $DIR/server-key.pem
#
# Sign server cert
#
openssl ca -cert $DIR/ca.pem -policy policy_anything \
-out $DIR/server-cert.pem -config $DIR/openssl.cnf \
-infiles $DIR/server-req.pem
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#

Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName
:PRINTABLE:'FI'
organizationName
:PRINTABLE:'MySQL AB'
commonName
:PRINTABLE:'MySQL admin'
Certificate is to be certified until Sep 13 14:22:46 2003 GMT
(365 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

#
# Create client request and key
#
openssl req -new -keyout $DIR/client-key.pem -out \
$DIR/client-req.pem -days 3600 -config $DIR/openssl.cnf
#
#
#
#

Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Generating a 1024 bit RSA private key
.....................................++++++

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating SSL Certificates and Keys Using openssl

#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#

.............................................++++++
writing new private key to '/home/monty/openssl/client-key.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
----You are about to be asked to enter information that will be
incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name
or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
----Country Name (2 letter code) [AU]:FI
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MySQL AB
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:MySQL user
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

#
# Remove the passphrase from the key
#
openssl rsa -in $DIR/client-key.pem -out $DIR/client-key.pem
#
# Sign client cert
#
openssl ca -cert $DIR/ca.pem -policy policy_anything \
-out $DIR/client-cert.pem -config $DIR/openssl.cnf \
-infiles $DIR/client-req.pem
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#
#

Sample output:
Using configuration from /home/monty/openssl/openssl.cnf
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
countryName
:PRINTABLE:'FI'
organizationName
:PRINTABLE:'MySQL AB'
commonName
:PRINTABLE:'MySQL user'
Certificate is to be certified until Sep 13 16:45:17 2003 GMT
(365 days)
Sign the certificate? [y/n]:y

1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated

#
# Create a my.cnf file that you can use to test the certificates
#
cat < $DIR/my.cnf
[client]
ssl-ca=$DIR/ca.pem
ssl-cert=$DIR/client-cert.pem
ssl-key=$DIR/client-key.pem
[mysqld]
ssl-ca=$DIR/ca.pem
ssl-cert=$DIR/server-cert.pem
ssl-key=$DIR/server-key.pem
EOF

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Creating SSL Certificates and Keys Using openssl

Example 3: Creating SSL Files on Windows
Download OpenSSL for Windows if it is not installed on your system. An overview of available
packages can be seen here:
http://www.slproweb.com/products/Win32OpenSSL.html

Choose the Win32 OpenSSL Light or Win64 OpenSSL Light package, depending on your architecture
(32-bit or 64-bit). The default installation location will be C:\OpenSSL-Win32 or C:\OpenSSL-Win64,
depending on which package you downloaded. The following instructions assume a default location of
C:\OpenSSL-Win32. Modify this as necessary if you are using the 64-bit package.
If a message occurs during setup indicating '...critical component is missing:
Microsoft Visual C++ 2008 Redistributables', cancel the setup and download one of the
following packages as well, again depending on your architecture (32-bit or 64-bit):
• Visual C++ 2008 Redistributables (x86), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF

• Visual C++ 2008 Redistributables (x64), available at:
http://www.microsoft.com/downloads/details.aspx?familyid=bd2a6171-e2d6-4230-b809-9a8d7548c1b6

After installing the additional package, restart the OpenSSL setup procedure.
During installation, leave the default C:\OpenSSL-Win32 as the install path, and also leave the
default option 'Copy OpenSSL DLL files to the Windows system directory' selected.
When the installation has finished, add C:\OpenSSL-Win32\bin to the Windows System Path
variable of your server:
1. On the Windows desktop, right-click the My Computer icon, and select Properties.
2. Select the Advanced tab from the System Properties menu that appears, and click the
Environment Variables button.
3. Under System Variables, select Path, then click the Edit button. The Edit System Variable
dialogue should appear.
4. Add ';C:\OpenSSL-Win32\bin' to the end (notice the semicolon).
5. Press OK 3 times.
6. Check that OpenSSL was correctly integrated into the Path variable by opening a new command
console (Start>Run>cmd.exe) and verifying that OpenSSL is available:
Microsoft Windows [Version ...]
Copyright (c) 2006 Microsoft Corporation. All rights reserved.
C:\Windows\system32>cd \
C:\>openssl
OpenSSL> exit <<< If you see the OpenSSL prompt, installation was successful.
C:\>

Depending on your version of Windows, the preceding path-setting instructions might differ slightly.
After OpenSSL has been installed, use instructions similar to those from from Example 1 (shown earlier
in this section), with the following changes:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connecting to MySQL Remotely from Windows with SSH

• Change the following Unix commands:
# Create clean environment
shell> rm -rf newcerts
shell> mkdir newcerts && cd newcerts

On Windows, use these commands instead:
# Create clean environment
C:\> md c:\newcerts
C:\> cd c:\newcerts

• When a '\' character is shown at the end of a command line, this '\' character must be removed
and the command lines entered all on a single line.
After generating the certificate and key files, to use them for SSL connections, see Section 6.3.6.4,
“Configuring MySQL to Use Secure Connections”.

6.3.8 Connecting to MySQL Remotely from Windows with SSH
This section describes how to get a secure connection to a remote MySQL server with SSH. The
information was provided by David Carlson .
1. Install an SSH client on your Windows machine. As a user, the best nonfree one I have found is
from SecureCRT from http://www.vandyke.com/. Another option is f-secure from http://www.fsecure.com/. You can also find some free ones on Google at http://directory.google.com/Top/
Computers/Internet/Protocols/SSH/Clients/Windows/.
2. Start your Windows SSH client. Set Host_Name = yourmysqlserver_URL_or_IP. Set
userid=your_userid to log in to your server. This userid value might not be the same as the
user name of your MySQL account.
3. Set up port forwarding. Either do a remote forward (Set local_port: 3306, remote_host:
yourmysqlservername_or_ip, remote_port: 3306 ) or a local forward (Set port: 3306,
host: localhost, remote port: 3306).
4. Save everything, otherwise you will have to redo it the next time.
5. Log in to your server with the SSH session you just created.
6. On your Windows machine, start some ODBC application (such as Access).
7. Create a new file in Windows and link to MySQL using the ODBC driver the same way you normally
do, except type in localhost for the MySQL host server, not yourmysqlservername.
At this point, you should have an ODBC connection to MySQL, encrypted using SSH.

6.3.9 SQL-Based MySQL Account Activity Auditing
Applications can use the following guidelines to perform SQL-based auditing that ties database activity
to MySQL accounts.
MySQL accounts correspond to rows in the mysql.user table. When a client connects successfully,
the server authenticates the client to a particular row in this table. The User and Host column values
in this row uniquely identify the account and correspond to the 'user_name'@'host_name' format in
which account names are written in SQL statements.
The account used to authenticate a client determines which privileges the client has. Normally, the
CURRENT_USER() function can be invoked to determine which account this is for the client user. Its
value is constructed from the User and Host columns of the user table row for the account.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

SQL-Based MySQL Account Activity Auditing

However, there are circumstances under which the CURRENT_USER() value corresponds not to the
client user but to a different account. This occurs in contexts when privilege checking is not based the
client's account:
• Stored routines (procedures and functions) defined with the SQL SECURITY DEFINER
characteristic.
• Views defined with the SQL SECURITY DEFINER characteristic (as of MySQL 5.0.24).
• Triggers (as of MySQL 5.0.17).
In those contexts, privilege checking is done against the DEFINER account and CURRENT_USER()
refers to that account, not to the account for the client who invoked the stored routine or view or who
caused the trigger to activate. To determine the invoking user, you can call the USER() function, which
returns a value indicating the actual user name provided by the client and the host from which the client
connected. However, this value does not necessarily correspond directly to an account in the user
table, because the USER() value never contains wildcards, whereas account values (as returned by
CURRENT_USER()) may contain user name and host name wildcards.
For example, a blank user name matches any user, so an account of ''@'localhost' enables
clients to connect as an anonymous user from the local host with any user name. In this case, if a client
connects as user1 from the local host, USER() and CURRENT_USER() return different values:
mysql> SELECT USER(), CURRENT_USER();
+-----------------+----------------+
| USER()
| CURRENT_USER() |
+-----------------+----------------+
| user1@localhost | @localhost
|
+-----------------+----------------+

The host name part of an account can contain wildcards, too. If the host name contains a '%' or
'_' pattern character or uses netmask notation, the account can be used for clients connecting from
multiple hosts and the CURRENT_USER() value will not indicate which one. For example, the account
'user2'@'%.example.com' can be used by user2 to connect from any host in the example.com
domain. If user2 connects from remote.example.com, USER() and CURRENT_USER() return
different values:
mysql> SELECT USER(), CURRENT_USER();
+--------------------------+---------------------+
| USER()
| CURRENT_USER()
|
+--------------------------+---------------------+
| user2@remote.example.com | user2@%.example.com |
+--------------------------+---------------------+

If an application must invoke USER() for user auditing (for example, if it does auditing from within
triggers) but must also be able to associate the USER() value with an account in the user table, it
is necessary to avoid accounts that contain wildcards in the User or Host column. Specifically, do
not permit User to be empty (which creates an anonymous-user account), and do not permit pattern
characters or netmask notation in Host values. All accounts must have a nonempty User value and
literal Host value.
With respect to the previous examples, the ''@'localhost' and 'user2'@'%.example.com'
accounts should be changed not to use wildcards:
RENAME USER ''@'localhost' TO 'user1'@'localhost';
RENAME USER 'user2'@'%.example.com' TO 'user2'@'remote.example.com';

If user2 must be able to connect from several hosts in the example.com domain, there should be a
separate account for each host.
To extract the user name or host name part from a CURRENT_USER() or USER() value, use the
SUBSTRING_INDEX() function:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

SQL-Based MySQL Account Activity Auditing

mysql> SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',1);
+---------------------------------------+
| SUBSTRING_INDEX(CURRENT_USER(),'@',1) |
+---------------------------------------+
| user1
|
+---------------------------------------+
mysql> SELECT SUBSTRING_INDEX(CURRENT_USER(),'@',-1);
+----------------------------------------+
| SUBSTRING_INDEX(CURRENT_USER(),'@',-1) |
+----------------------------------------+
| localhost
|
+----------------------------------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 7 Backup and Recovery
Table of Contents
7.1 Backup and Recovery Types ...............................................................................................
7.2 Database Backup Methods ..................................................................................................
7.3 Example Backup and Recovery Strategy ..............................................................................
7.3.1 Establishing a Backup Policy ....................................................................................
7.3.2 Using Backups for Recovery .....................................................................................
7.3.3 Backup Strategy Summary .......................................................................................
7.4 Using mysqldump for Backups .............................................................................................
7.4.1 Dumping Data in SQL Format with mysqldump ..........................................................
7.4.2 Reloading SQL-Format Backups ...............................................................................
7.4.3 Dumping Data in Delimited-Text Format with mysqldump ...........................................
7.4.4 Reloading Delimited-Text Format Backups .................................................................
7.4.5 mysqldump Tips .......................................................................................................
7.5 Point-in-Time (Incremental) Recovery Using the Binary Log ..................................................
7.5.1 Point-in-Time Recovery Using Event Times ...............................................................
7.5.2 Point-in-Time Recovery Using Event Positions ...........................................................
7.6 MyISAM Table Maintenance and Crash Recovery ................................................................
7.6.1 Using myisamchk for Crash Recovery .......................................................................
7.6.2 How to Check MyISAM Tables for Errors ..................................................................
7.6.3 How to Repair MyISAM Tables .................................................................................
7.6.4 MyISAM Table Optimization ......................................................................................
7.6.5 Setting Up a MyISAM Table Maintenance Schedule ...................................................

638
640
642
643
645
645
645
646
647
647
649
649
651
652
653
654
654
655
655
658
658

It is important to back up your databases so that you can recover your data and be up and running
again in case problems occur, such as system crashes, hardware failures, or users deleting data by
mistake. Backups are also essential as a safeguard before upgrading a MySQL installation, and they
can be used to transfer a MySQL installation to another system or to set up replication slave servers.
MySQL offers a variety of backup strategies from which you can choose the methods that best suit
the requirements for your installation. This chapter discusses several backup and recovery topics with
which you should be familiar:
• Types of backups: Logical versus physical, full versus incremental, and so forth
• Methods for creating backups
• Recovery methods, including point-in-time recovery
• Backup scheduling, compression, and encryption
• Table maintenance, to enable recovery of corrupt tables

Additional Resources
Resources related to backup or to maintaining data availability include the following:
• A forum dedicated to backup issues is available at http://forums.mysql.com/list.php?28.
• Details for mysqldump, mysqlhotcopy, and other MySQL backup programs can be found in
Chapter 4, MySQL Programs.
• The syntax of the SQL statements described here is given in Chapter 13, SQL Statement Syntax.
• For additional information about InnoDB backup procedures, see Section 14.2.6, “Backing Up and
Recovering an InnoDB Database”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Backup and Recovery Types

• Replication enables you to maintain identical data on multiple servers. This has several benefits,
such as enabling client query load to be distributed over servers, availability of data even if a given
server is taken offline or fails, and the ability to make backups with no impact on the master by using
a slave server. See Chapter 16, Replication.
• MySQL Cluster provides a high-availability, high-redundancy version of MySQL adapted for the
distributed computing environment. See Chapter 17, MySQL Cluster. For information specifically
about MySQL Cluster backup, see Section 17.5.3, “Online Backup of MySQL Cluster”.

7.1 Backup and Recovery Types
This section describes the characteristics of different types of backups.
Logical Versus Physical (Raw) Backups
Logical backups save information represented as logical database structure (CREATE DATABASE,
CREATE TABLE statements) and content (INSERT statements or delimited-text files). Physical backups
consist of raw copies of the directories and files that store database contents.
Logical backup methods have these characteristics:
• The backup is done by querying the MySQL server to obtain database structure and content
information.
• Backup is slower than physical methods because the server must access database information and
convert it to logical format. If the output is written on the client side, the server must also send it to
the backup program.
• Output is larger than for physical backup, particularly when saved in text format.
• Backup and restore granularity is available at the server level (all databases), database level (all
tables in a particular database), or table level. This is true regardless of storage engine.
• The backup does not include log or configuration files, or other database-related files that are not
part of databases.
• Backups stored in logical format are machine independent and highly portable.
• Logical backups are performed with the MySQL server running. The server is not taken offline.
• Logical backup tools include the mysqldump program and the SELECT ... INTO OUTFILE
statement. These work for any storage engine, even MEMORY.
• To restore logical backups, SQL-format dump files can be processed using the mysql client. To load
delimited-text files, use the LOAD DATA INFILE statement or the mysqlimport client.
Physical backup methods have these characteristics:
• The backup consists of exact copies of database directories and files. Typically this is a copy of all or
part of the MySQL data directory. Data from MEMORY tables cannot be backed up this way because
their contents are not stored on disk.
• Physical backup methods are faster than logical because they involve only file copying without
conversion.
• Output is more compact than for logical backup.
• Backup and restore granularity ranges from the level of the entire data directory down to the level of
individual files. This may or may not provide for table-level granularity, depending on storage engine.
(Each MyISAM table corresponds uniquely to a set of files, but an InnoDB table shares file storage
with other InnoDB tables.)
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Backup and Recovery Types

• In addition to databases, the backup can include any related files such as log or configuration files.
• Backups are portable only to other machines that have identical or similar hardware characteristics.
• Backups can be performed while the MySQL server is not running. If the server is running, it is
necessary to perform appropriate locking so that the server does not change database contents
during the backup.
• Physical backup tools include file system-level commands (such as cp, scp, tar, rsync),
mysqlhotcopy for MyISAM tables, ibbackup for InnoDB tables, or START BACKUP for NDB
tables.
• For restore, files copied at the file system level or with mysqlhotcopy can be copied back to
their original locations with file system commands; ibbackup restores InnoDB tables, and
ndb_restore restores NDB tables.
Online Versus Offline Backups
Online backups take place while the MySQL server is running so that the database information can be
obtained from the server. Offline backups take place while the server is stopped. This distinction can
also be described as “hot” versus “cold” backups; a “warm” backup is one where the server remains
running but locked against modifying data while you access database files externally.
Online backup methods have these characteristics:
• The backup is less intrusive to other clients, which can connect to the MySQL server during the
backup and may be able to access data depending on what operations they need to perform.
• Care must be taken to impose appropriate locking so that data modifications do not take place that
would compromise backup integrity.
Offline backup methods have these characteristics:
• Clients can be affected adversely because the server is unavailable during backup.
• The backup procedure is simpler because there is no possibility of interference from client activity.
A similar distinction between online and offline applies for recovery operations, and similar
characteristics apply. However, it is more likely that clients will be affected for online recovery than for
online backup because recovery requires stronger locking. During backup, clients might be able to read
data while it is being backed up. Recovery modifies data and does not just read it, so clients must be
prevented from accessing data while it is being restored.
Local Versus Remote Backups
A local backup is performed on the same host where the MySQL server runs, whereas a remote
backup is done from a different host. For some types of backups, the backup can be initiated from a
remote host even if the output is written locally on the server. host.
• mysqldump can connect to local or remote servers. For SQL output (CREATE and INSERT
statements), local or remote dumps can be done and generate output on the client. For delimited-text
output (with the --tab option), data files are created on the server host.
• mysqlhotcopy performs only local backups: It connects to the server to lock it against data
modifications and then copies local table files.
• SELECT ... INTO OUTFILE can be initiated from a local or remote client host, but the output file
is created on the server host.
• Physical backup methods typically are initiated locally on the MySQL server host so that the server
can be taken offline, although the destination for copied files might be remote.
Snapshot Backups
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Database Backup Methods

Some file system implementations enable “snapshots” to be taken. These provide logical copies of
the file system at a given point in time, without requiring a physical copy of the entire file system. (For
example, the implementation may use copy-on-write techniques so that only parts of the file system
modified after the snapshot time need be copied.) MySQL itself does not provide the capability for
taking file system snapshots. It is available through third-party solutions such as Veritas, LVM, or ZFS.
Full Versus Incremental Backups
A full backup includes all data managed by a MySQL server at a given point in time. An incremental
backup consists of the changes made to the data during a given time span (from one point in time to
another). MySQL has different ways to perform full backups, such as those described earlier in this
section. Incremental backups are made possible by enabling the server's binary log, which the server
uses to record data changes.
Full Versus Point-in-Time (Incremental) Recovery
A full recovery restores all data from a full backup. This restores the server instance to the state that it
had when the backup was made. If that state is not sufficiently current, a full recovery can be followed
by recovery of incremental backups made since the full backup, to bring the server to a more up-todate state.
Incremental recovery is recovery of changes made during a given time span. This is also called pointin-time recovery because it makes a server's state current up to a given time. Point-in-time recovery
is based on the binary log and typically follows a full recovery from the backup files that restores the
server to its state when the backup was made. Then the data changes written in the binary log files are
applied as incremental recovery to redo data modifications and bring the server up to the desired point
in time.
Table Maintenance
Data integrity can be compromised if tables become corrupt. MySQL provides programs for checking
MyISAM tables and repairing them should problems be found. See Section 7.6, “MyISAM Table
Maintenance and Crash Recovery”.
Backup Scheduling, Compression, and Encryption
Backup scheduling is valuable for automating backup procedures. Compression of backup
output reduces space requirements, and encryption of the output provides better security against
unauthorized access of backed-up data. MySQL itself does not provide these capabilities. ibbackup
can compress InnoDB backups, and compression or encryption of backup output can be achieved
using file system utilities. Other third-party solutions may be available.

7.2 Database Backup Methods
This section summarizes some general methods for making backups.
Making Backups with mysqldump or mysqlhotcopy
The mysqldump program and the mysqlhotcopy script can make backups. mysqldump is more
general because it can back up all kinds of tables. mysqlhotcopy works only with some storage
engines. (See Section 7.4, “Using mysqldump for Backups”, and Section 4.6.9, “mysqlhotcopy — A
Database Backup Program”.)
For InnoDB tables, it is possible to perform an online backup that takes no locks on tables using the -single-transaction option to mysqldump. See Section 7.3.1, “Establishing a Backup Policy”.
Making Backups by Copying Table Files
For storage engines that represent each table using its own files, tables can be backed up by copying
those files. For example, MyISAM tables are stored as files, so it is easy to do a backup by copying files
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Database Backup Methods

(*.frm, *.MYD, and *.MYI files). To get a consistent backup, stop the server or lock and flush the
relevant tables:
LOCK TABLES tbl_list READ;
FLUSH TABLES tbl_list;

You need only a read lock; this enables other clients to continue to query the tables while you are
making a copy of the files in the database directory. The FLUSH TABLES statement is needed
to ensure that the all active index pages are written to disk before you start the backup. See
Section 13.3.5, “LOCK TABLES and UNLOCK TABLES Syntax”, and Section 13.7.6.2, “FLUSH
Syntax”.
You can also create a binary backup simply by copying all table files, as long as the server isn't
updating anything. The mysqlhotcopy script uses this method. (But note that table file copying
methods do not work if your database contains InnoDB tables. mysqlhotcopy does not work for
InnoDB tables because InnoDB does not necessarily store table contents in database directories.
Also, even if the server is not actively updating data, InnoDB may still have modified data cached in
memory and not flushed to disk.)
Making Delimited-Text File Backups
To create a text file containing a table's data, you can use SELECT * INTO OUTFILE 'file_name'
FROM tbl_name. The file is created on the MySQL server host, not the client host. For this statement,
the output file cannot already exist because permitting files to be overwritten constitutes a security risk.
See Section 13.2.8, “SELECT Syntax”. This method works for any kind of data file, but saves only table
data, not the table structure.
Another way to create text data files (along with files containing CREATE TABLE statements for the
backed up tables) is to use mysqldump with the --tab option. See Section 7.4.3, “Dumping Data in
Delimited-Text Format with mysqldump”.
To reload a delimited-text data file, use LOAD DATA INFILE or mysqlimport.
Making Incremental Backups by Enabling the Binary Log
MySQL supports incremental backups: You must start the server with the --log-bin option to
enable binary logging; see Section 5.4.3, “The Binary Log”. The binary log files provide you with the
information you need to replicate changes to the database that are made subsequent to the point at
which you performed a backup. At the moment you want to make an incremental backup (containing
all changes that happened since the last full or incremental backup), you should rotate the binary log
by using FLUSH LOGS. This done, you need to copy to the backup location all binary logs which range
from the one of the moment of the last full or incremental backup to the last but one. These binary logs
are the incremental backup; at restore time, you apply them as explained in Section 7.5, “Point-inTime (Incremental) Recovery Using the Binary Log”. The next time you do a full backup, you should
also rotate the binary log using FLUSH LOGS, mysqldump --flush-logs, or mysqlhotcopy -flushlog. See Section 4.5.4, “mysqldump — A Database Backup Program”, and Section 4.6.9,
“mysqlhotcopy — A Database Backup Program”.
Making Backups Using Replication Slaves
If you have performance problems with your master server while making backups, one strategy that
can help is to set up replication and perform backups on the slave rather than on the master. See
Section 16.3.1, “Using Replication for Backups”.
If you are backing up a slave replication server, you should back up its master.info and relaylog.info files when you back up the slave's databases, regardless of the backup method you
choose. These information files are always needed to resume replication after you restore the slave's
data. If your slave is replicating LOAD DATA INFILE statements, you should also back up any
SQL_LOAD-* files that exist in the directory that the slave uses for this purpose. The slave needs these
files to resume replication of any interrupted LOAD DATA INFILE operations. The location of this
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Example Backup and Recovery Strategy

directory is the value of the --slave-load-tmpdir option. If the server was not started with that
option, the directory location is the value of the tmpdir system variable.
Recovering Corrupt Tables
If you have to restore MyISAM tables that have become corrupt, try to recover them using REPAIR
TABLE or myisamchk -r first. That should work in 99.9% of all cases. If myisamchk fails, see
Section 7.6, “MyISAM Table Maintenance and Crash Recovery”.
Making Backups Using a File System Snapshot
If you are using a Veritas file system, you can make a backup like this:
1. From a client program, execute FLUSH TABLES WITH READ LOCK.
2. From another shell, execute mount vxfs snapshot.
3. From the first client, execute UNLOCK TABLES.
4. Copy files from the snapshot.
5. Unmount the snapshot.
Similar snapshot capabilities may be available in other file systems, such as LVM or ZFS.

7.3 Example Backup and Recovery Strategy
This section discusses a procedure for performing backups that enables you to recover data after
several types of crashes:
• Operating system crash
• Power failure
• File system crash
• Hardware problem (hard drive, motherboard, and so forth)
The example commands do not include options such as --user and --password for the mysqldump
and mysql client programs. You should include such options as necessary to enable client programs
to connect to the MySQL server.
Assume that data is stored in the InnoDB storage engine, which has support for transactions and
automatic crash recovery. Assume also that the MySQL server is under load at the time of the crash. If
it were not, no recovery would ever be needed.
For cases of operating system crashes or power failures, we can assume that MySQL's disk data is
available after a restart. The InnoDB data files might not contain consistent data due to the crash, but
InnoDB reads its logs and finds in them the list of pending committed and noncommitted transactions
that have not been flushed to the data files. InnoDB automatically rolls back those transactions that
were not committed, and flushes to its data files those that were committed. Information about this
recovery process is conveyed to the user through the MySQL error log. The following is an example log
excerpt:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
...

This
documentation
is for an
older version.
If you're

Database was not shut down normally.
Starting recovery from log files...
Starting log scan based on checkpoint at
log sequence number 0 13674004
Doing recovery: scanned up to log sequence
Doing recovery: scanned up to log sequence
Doing recovery: scanned up to log sequence
Doing recovery: scanned up to log sequence

number
number
number
number

0
0
0
0

13739520
13805056
13870592
13936128

This
documentation
is for an
older version.
If you're

Establishing a Backup Policy

InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
InnoDB:
mysqld:

Doing recovery: scanned up to log sequence number 0 20555264
Doing recovery: scanned up to log sequence number 0 20620800
Doing recovery: scanned up to log sequence number 0 20664692
1 uncommitted transaction(s) which must be rolled back
Starting rollback of uncommitted transactions
Rolling back trx no 16745
Rolling back of trx no 16745 completed
Rollback of uncommitted transactions completed
Starting an apply batch of log records to the database...
Apply batch completed
Started
ready for connections

For the cases of file system crashes or hardware problems, we can assume that the MySQL disk data
is not available after a restart. This means that MySQL fails to start successfully because some blocks
of disk data are no longer readable. In this case, it is necessary to reformat the disk, install a new one,
or otherwise correct the underlying problem. Then it is necessary to recover our MySQL data from
backups, which means that backups must already have been made. To make sure that is the case,
design and implement a backup policy.

7.3.1 Establishing a Backup Policy
To be useful, backups must be scheduled regularly. A full backup (a snapshot of the data at a point in
time) can be done in MySQL with several tools. For example, InnoDB Hot Backup provides online
nonblocking physical backup of the InnoDB data files, and mysqldump provides online logical backup.
This discussion uses mysqldump.
Assume that we make a full backup of all our InnoDB tables in all databases using the following
command on Sunday at 1 p.m., when load is low:
shell> mysqldump --single-transaction --all-databases > backup_sunday_1_PM.sql

The resulting .sql file produced by mysqldump contains a set of SQL INSERT statements that can be
used to reload the dumped tables at a later time.
This backup operation acquires a global read lock on all tables at the beginning of the dump (using
FLUSH TABLES WITH READ LOCK). As soon as this lock has been acquired, the binary log
coordinates are read and the lock is released. If long updating statements are running when the FLUSH
statement is issued, the backup operation may stall until those statements finish. After that, the dump
becomes lock-free and does not disturb reads and writes on the tables.
It was assumed earlier that the tables to back up are InnoDB tables, so --single-transaction
uses a consistent read and guarantees that data seen by mysqldump does not change. (Changes
made by other clients to InnoDB tables are not seen by the mysqldump process.) If the backup
operation includes nontransactional tables, consistency requires that they do not change during the
backup. For example, for the MyISAM tables in the mysql database, there must be no administrative
changes to MySQL accounts during the backup.
Full backups are necessary, but it is not always convenient to create them. They produce large backup
files and take time to generate. They are not optimal in the sense that each successive full backup
includes all data, even that part that has not changed since the previous full backup. It is more efficient
to make an initial full backup, and then to make incremental backups. The incremental backups are
smaller and take less time to produce. The tradeoff is that, at recovery time, you cannot restore your
data just by reloading the full backup. You must also process the incremental backups to recover the
incremental changes.
To make incremental backups, we need to save the incremental changes. In MySQL, these changes
are represented in the binary log, so the MySQL server should always be started with the --log-bin
option to enable that log. With binary logging enabled, the server writes each data change into a file
while it updates data. Looking at the data directory of a MySQL server that was started with the -log-bin option and that has been running for some days, we find these MySQL binary log files:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Establishing a Backup Policy

-rw-rw----rw-rw----rw-rw----rw-rw----rw-rw----rw-rw----rw-rw----

1
1
1
1
1
1
1

guilhem
guilhem
guilhem
guilhem
guilhem
guilhem
guilhem

guilhem
1277324 Nov 10
guilhem
4 Nov 10
guilhem
79 Nov 11
guilhem
508 Nov 11
guilhem 220047446 Nov 12
guilhem
998412 Nov 14
guilhem
361 Nov 14

23:59
23:59
11:06
11:08
16:47
10:08
10:07

gbichot2-bin.000001
gbichot2-bin.000002
gbichot2-bin.000003
gbichot2-bin.000004
gbichot2-bin.000005
gbichot2-bin.000006
gbichot2-bin.index

Each time it restarts, the MySQL server creates a new binary log file using the next number in the
sequence. While the server is running, you can also tell it to close the current binary log file and begin
a new one manually by issuing a FLUSH LOGS SQL statement or with a mysqladmin flush-logs
command. mysqldump also has an option to flush the logs. The .index file in the data directory
contains the list of all MySQL binary logs in the directory.
The MySQL binary logs are important for recovery because they form the set of incremental backups. If
you make sure to flush the logs when you make your full backup, the binary log files created afterward
contain all the data changes made since the backup. Let's modify the previous mysqldump command
a bit so that it flushes the MySQL binary logs at the moment of the full backup, and so that the dump
file contains the name of the new current binary log:
shell> mysqldump --single-transaction --flush-logs --master-data=2 \
--all-databases > backup_sunday_1_PM.sql

After executing this command, the data directory contains a new binary log file, gbichot2bin.000007, because the --flush-logs option causes the server to flush its logs. The --masterdata option causes mysqldump to write binary log information to its output, so the resulting .sql
dump file includes these lines:
-- Position to start replication or point-in-time recovery from
-- CHANGE MASTER TO MASTER_LOG_FILE='gbichot2-bin.000007',MASTER_LOG_POS=4;

Because the mysqldump command made a full backup, those lines mean two things:
• The dump file contains all changes made before any changes written to the gbichot2bin.000007 binary log file or newer.
• All data changes logged after the backup are not present in the dump file, but are present in the
gbichot2-bin.000007 binary log file or newer.
On Monday at 1 p.m., we can create an incremental backup by flushing the logs to begin a new
binary log file. For example, executing a mysqladmin flush-logs command creates gbichot2bin.000008. All changes between the Sunday 1 p.m. full backup and Monday 1 p.m. will be in the
gbichot2-bin.000007 file. This incremental backup is important, so it is a good idea to copy it to
a safe place. (For example, back it up on tape or DVD, or copy it to another machine.) On Tuesday
at 1 p.m., execute another mysqladmin flush-logs command. All changes between Monday 1
p.m. and Tuesday 1 p.m. will be in the gbichot2-bin.000008 file (which also should be copied
somewhere safe).
The MySQL binary logs take up disk space. To free up space, purge them from time to time. One
way to do this is by deleting the binary logs that are no longer needed, such as when we make a full
backup:
shell> mysqldump --single-transaction --flush-logs --master-data=2 \
--all-databases --delete-master-logs > backup_sunday_1_PM.sql

Note
Deleting the MySQL binary logs with mysqldump --delete-master-logs
can be dangerous if your server is a replication master server, because slave
servers might not yet fully have processed the contents of the binary log. The
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Backups for Recovery

description for the PURGE BINARY LOGS statement explains what should be
verified before deleting the MySQL binary logs. See Section 13.4.1.1, “PURGE
BINARY LOGS Syntax”.

7.3.2 Using Backups for Recovery
Now, suppose that we have a catastrophic crash on Wednesday at 8 a.m. that requires recovery from
backups. To recover, first we restore the last full backup we have (the one from Sunday 1 p.m.). The
full backup file is just a set of SQL statements, so restoring it is very easy:
shell> mysql < backup_sunday_1_PM.sql

At this point, the data is restored to its state as of Sunday 1 p.m.. To restore the changes made since
then, we must use the incremental backups; that is, the gbichot2-bin.000007 and gbichot2bin.000008 binary log files. Fetch the files if necessary from where they were backed up, and then
process their contents like this:
shell> mysqlbinlog gbichot2-bin.000007 gbichot2-bin.000008 | mysql

We now have recovered the data to its state as of Tuesday 1 p.m., but still are missing the changes
from that date to the date of the crash. To not lose them, we would have needed to have the MySQL
server store its MySQL binary logs into a safe location (RAID disks, SAN, ...) different from the place
where it stores its data files, so that these logs were not on the destroyed disk. (That is, we can start
the server with a --log-bin option that specifies a location on a different physical device from the
one on which the data directory resides. That way, the logs are safe even if the device containing
the directory is lost.) If we had done this, we would have the gbichot2-bin.000009 file (and any
subsequent files) at hand, and we could apply them using mysqlbinlog and mysql to restore the
most recent data changes with no loss up to the moment of the crash:
shell> mysqlbinlog gbichot2-bin.000009 ... | mysql

For more information about using mysqlbinlog to process binary log files, see Section 7.5, “Point-inTime (Incremental) Recovery Using the Binary Log”.

7.3.3 Backup Strategy Summary
In case of an operating system crash or power failure, InnoDB itself does all the job of recovering data.
But to make sure that you can sleep well, observe the following guidelines:
• Always run the MySQL server with the --log-bin option, or even --log-bin=log_name, where
the log file name is located on some safe media different from the drive on which the data directory is
located. If you have such safe media, this technique can also be good for disk load balancing (which
results in a performance improvement).
• Make periodic full backups, using the mysqldump command shown earlier in Section 7.3.1,
“Establishing a Backup Policy”, that makes an online, nonblocking backup.
• Make periodic incremental backups by flushing the logs with FLUSH LOGS or mysqladmin flushlogs.

7.4 Using mysqldump for Backups
This section describes how to use mysqldump to produce dump files, and how to reload dump files. A
dump file can be used in several ways:
• As a backup to enable data recovery in case of data loss.
• As a source of data for setting up replication slaves.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Dumping Data in SQL Format with mysqldump

• As a source of data for experimentation:
• To make a copy of a database that you can use without changing the original data.
• To test potential upgrade incompatibilities.
mysqldump produces two types of output, depending on whether the --tab option is given:
• Without --tab, mysqldump writes SQL statements to the standard output. This output consists of
CREATE statements to create dumped objects (databases, tables, stored routines, and so forth), and
INSERT statements to load data into tables. The output can be saved in a file and reloaded later
using mysql to recreate the dumped objects. Options are available to modify the format of the SQL
statements, and to control which objects are dumped.
• With --tab, mysqldump produces two output files for each dumped table. The server writes one
file as tab-delimited text, one line per table row. This file is named tbl_name.txt in the output
directory. The server also sends a CREATE TABLE statement for the table to mysqldump, which
writes it as a file named tbl_name.sql in the output directory.

7.4.1 Dumping Data in SQL Format with mysqldump
This section describes how to use mysqldump to create SQL-format dump files. For information about
reloading such dump files, see Section 7.4.2, “Reloading SQL-Format Backups”.
By default, mysqldump writes information as SQL statements to the standard output. You can save the
output in a file:
shell> mysqldump [arguments] > file_name

To dump all databases, invoke mysqldump with the --all-databases option:
shell> mysqldump --all-databases > dump.sql

To dump only specific databases, name them on the command line and use the --databases option:
shell> mysqldump --databases db1 db2 db3 > dump.sql

The --databases option causes all names on the command line to be treated as database names.
Without this option, mysqldump treats the first name as a database name and those following as table
names.
With --all-databases or --databases, mysqldump writes CREATE DATABASE and USE
statements prior to the dump output for each database. This ensures that when the dump file is
reloaded, it creates each database if it does not exist and makes it the default database so database
contents are loaded into the same database from which they came. If you want to cause the dump file
to force a drop of each database before recreating it, use the --add-drop-database option as well.
In this case, mysqldump writes a DROP DATABASE statement preceding each CREATE DATABASE
statement.
To dump a single database, name it on the command line:
shell> mysqldump --databases test > dump.sql

In the single-database case, it is permissible to omit the --databases option:
shell> mysqldump test > dump.sql

The difference between the two preceding commands is that without --databases, the dump output
contains no CREATE DATABASE or USE statements. This has several implications:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Reloading SQL-Format Backups

• When you reload the dump file, you must specify a default database name so that the server knows
which database to reload.
• For reloading, you can specify a database name different from the original name, which enables you
to reload the data into a different database.
• If the database to be reloaded does not exist, you must create it first.
• Because the output will contain no CREATE DATABASE statement, the --add-drop-database
option has no effect. If you use it, it produces no DROP DATABASE statement.
To dump only specific tables from a database, name them on the command line following the database
name:
shell> mysqldump test t1 t3 t7 > dump.sql

7.4.2 Reloading SQL-Format Backups
To reload a dump file written by mysqldump that consists of SQL statements, use it as input to
the mysql client. If the dump file was created by mysqldump with the --all-databases or -databases option, it contains CREATE DATABASE and USE statements and it is not necessary to
specify a default database into which to load the data:
shell> mysql < dump.sql

Alternatively, from within mysql, use a source command:
mysql> source dump.sql

If the file is a single-database dump not containing CREATE DATABASE and USE statements, create the
database first (if necessary):
shell> mysqladmin create db1

Then specify the database name when you load the dump file:
shell> mysql db1 < dump.sql

Alternatively, from within mysql, create the database, select it as the default database, and load the
dump file:
mysql> CREATE DATABASE IF NOT EXISTS db1;
mysql> USE db1;
mysql> source dump.sql

7.4.3 Dumping Data in Delimited-Text Format with mysqldump
This section describes how to use mysqldump to create delimited-text dump files. For information
about reloading such dump files, see Section 7.4.4, “Reloading Delimited-Text Format Backups”.
If you invoke mysqldump with the --tab=dir_name option, it uses dir_name as the output directory
and dumps tables individually in that directory using two files for each table. The table name is the base
name for these files. For a table named t1, the files are named t1.sql and t1.txt. The .sql file
contains a CREATE TABLE statement for the table. The .txt file contains the table data, one line per
table row.
The following command dumps the contents of the db1 database to files in the /tmp database:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Dumping Data in Delimited-Text Format with mysqldump

shell> mysqldump --tab=/tmp db1

The .txt files containing table data are written by the server, so they are owned by the system
account used for running the server. The server uses SELECT ... INTO OUTFILE to write the files,
so you must have the FILE privilege to perform this operation, and an error occurs if a given .txt file
already exists.
The server sends the CREATE definitions for dumped tables to mysqldump, which writes them to .sql
files. These files therefore are owned by the user who executes mysqldump.
It is best that --tab be used only for dumping a local server. If you use it with a remote server, the
--tab directory must exist on both the local and remote hosts, and the .txt files will be written
by the server in the remote directory (on the server host), whereas the .sql files will be written by
mysqldump in the local directory (on the client host).
For mysqldump --tab, the server by default writes table data to .txt files one line per row with tabs
between column values, no quotation marks around column values, and newline as the line terminator.
(These are the same defaults as for SELECT ... INTO OUTFILE.)
To enable data files to be written using a different format, mysqldump supports these options:
• --fields-terminated-by=str
The string for separating column values (default: tab).
• --fields-enclosed-by=char
The character within which to enclose column values (default: no character).
• --fields-optionally-enclosed-by=char
The character within which to enclose non-numeric column values (default: no character).
• --fields-escaped-by=char
The character for escaping special characters (default: no escaping).
• --lines-terminated-by=str
The line-termination string (default: newline).
Depending on the value you specify for any of these options, it might be necessary on the command
line to quote or escape the value appropriately for your command interpreter. Alternatively, specify the
value using hex notation. Suppose that you want mysqldump to quote column values within double
quotation marks. To do so, specify double quote as the value for the --fields-enclosed-by option.
But this character is often special to command interpreters and must be treated specially. For example,
on Unix, you can quote the double quote like this:
--fields-enclosed-by='"'

On any platform, you can specify the value in hex:
--fields-enclosed-by=0x22

It is common to use several of the data-formatting options together. For example, to dump tables in
comma-separated values format with lines terminated by carriage-return/newline pairs (\r\n), use this
command (enter it on a single line):
shell> mysqldump --tab=/tmp --fields-terminated-by=,

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Reloading Delimited-Text Format Backups

--fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1

Should you use any of the data-formatting options to dump table data, you will need to specify the
same format when you reload data files later, to ensure proper interpretation of the file contents.

7.4.4 Reloading Delimited-Text Format Backups
For backups produced with mysqldump --tab, each table is represented in the output directory by an
.sql file containing the CREATE TABLE statement for the table, and a .txt file containing the table
data. To reload a table, first change location into the output directory. Then process the .sql file with
mysql to create an empty table and process the .txt file to load the data into the table:
shell> mysql db1 < t1.sql
shell> mysqlimport db1 t1.txt

An alternative to using mysqlimport to load the data file is to use the LOAD DATA INFILE statement
from within the mysql client:
mysql> USE db1;
mysql> LOAD DATA INFILE 't1.txt' INTO TABLE t1;

If you used any data-formatting options with mysqldump when you initially dumped the table, you must
use the same options with mysqlimport or LOAD DATA INFILE to ensure proper interpretation of
the data file contents:
shell> mysqlimport --fields-terminated-by=,
--fields-enclosed-by='"' --lines-terminated-by=0x0d0a db1 t1.txt

Or:
mysql>
mysql>
->
->

USE db1;
LOAD DATA INFILE 't1.txt' INTO TABLE t1
FIELDS TERMINATED BY ',' FIELDS ENCLOSED BY '"'
LINES TERMINATED BY '\r\n';

7.4.5 mysqldump Tips
This section surveys techniques that enable you to use mysqldump to solve specific problems:
• How to make a copy a database
• How to copy a database from one server to another
• How to dump stored programs (stored procedures and functions and triggers)
• How to dump definitions and data separately

7.4.5.1 Making a Copy of a Database
shell> mysqldump db1 > dump.sql
shell> mysqladmin create db2
shell> mysql db2 < dump.sql

Do not use --databases on the mysqldump command line because that causes USE db1 to be
included in the dump file, which overrides the effect of naming db2 on the mysql command line.

7.4.5.2 Copy a Database from one Server to Another
On Server 1:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

mysqldump Tips

shell> mysqldump --databases db1 > dump.sql

Copy the dump file from Server 1 to Server 2.
On Server 2:
shell> mysql < dump.sql

Use of --databases with the mysqldump command line causes the dump file to include CREATE
DATABASE and USE statements that create the database if it does exist and make it the default
database for the reloaded data.
Alternatively, you can omit --databases from the mysqldump command. Then you will need to
create the database on Server 2 (if necessary) and specify it as the default database when you reload
the dump file.
On Server 1:
shell> mysqldump db1 > dump.sql

On Server 2:
shell> mysqladmin create db1
shell> mysql db1 < dump.sql

You can specify a different database name in this case, so omitting --databases from the
mysqldump command enables you to dump data from one database and load it into another.

7.4.5.3 Dumping Stored Programs
Several options control how mysqldump handles stored programs (stored procedures and functions
and triggers):
• --routines: Dump stored procedures and functions
• --triggers: Dump triggers for tables
The --triggers option is enabled by default so that when tables are dumped, they are accompanied
by any triggers they have. The other options are disabled by default and must be specified explicitly to
dump the corresponding objects. To disable any of these options explicitly, use its skip form: --skiproutines or --skip-triggers.

7.4.5.4 Dumping Table Definitions and Content Separately
The --no-data option tells mysqldump not to dump table data, resulting in the dump file containing
only statements to create the tables. Conversely, the --no-create-info option tells mysqldump to
suppress CREATE statements from the output, so that the dump file contains only table data.
For example, to dump table definitions and data separately for the test database, use these
commands:
shell> mysqldump --no-data test > dump-defs.sql
shell> mysqldump --no-create-info test > dump-data.sql

For a definition-only dump, add the --routines option to also include stored routine definitions:
shell> mysqldump --no-data --routines test > dump-defs.sql

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Point-in-Time (Incremental) Recovery Using the Binary Log

7.4.5.5 Using mysqldump to Test for Upgrade Incompatibilities
When contemplating a MySQL upgrade, it is prudent to install the newer version separately from your
current production version. Then you can dump the database and database object definitions from the
production server and load them into the new server to verify that they are handled properly. (This is
also useful for testing downgrades.)
On the production server:
shell> mysqldump --all-databases --no-data --routines > dump-defs.sql

On the upgraded server:
shell> mysql < dump-defs.sql

Because the dump file does not contain table data, it can be processed quickly. This enables you to
spot potential incompatibilities without waiting for lengthy data-loading operations. Look for warnings or
errors while the dump file is being processed.
After you have verified that the definitions are handled properly, dump the data and try to load it into the
upgraded server.
On the production server:
shell> mysqldump --all-databases --no-create-info > dump-data.sql

On the upgraded server:
shell> mysql < dump-data.sql

Now check the table contents and run some test queries.

7.5 Point-in-Time (Incremental) Recovery Using the Binary Log
Point-in-time recovery refers to recovery of data changes made since a given point in time. Typically,
this type of recovery is performed after restoring a full backup that brings the server to its state as of
the time the backup was made. (The full backup can be made in several ways, such as those listed
in Section 7.2, “Database Backup Methods”.) Point-in-time recovery then brings the server up to date
incrementally from the time of the full backup to a more recent time.
Point-in-time recovery is based on these principles:
• The source of information for point-in-time recovery is the set of incremental backups represented by
the binary log files generated subsequent to the full backup operation. Therefore, the server must be
started with the --log-bin option to enable binary logging (see Section 5.4.3, “The Binary Log”).
To restore data from the binary log, you must know the name and location of the current binary log
files. By default, the server creates binary log files in the data directory, but a path name can be
specified with the --log-bin option to place the files in a different location. Section 5.4.3, “The
Binary Log”.
To see a listing of all binary log files, use this statement:
mysql> SHOW BINARY LOGS;

To determine the name of the current binary log file, issue the following statement:
mysql> SHOW MASTER STATUS;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Point-in-Time Recovery Using Event Times

• The mysqlbinlog utility converts the events in the binary log files from binary format to text so
that they can be executed or viewed. mysqlbinlog has options for selecting sections of the binary
log based on event times or position of events within the log. See Section 4.6.7, “mysqlbinlog —
Utility for Processing Binary Log Files”.
• Executing events from the binary log causes the data modifications they represent to be redone. This
enables recovery of data changes for a given span of time. To execute events from the binary log,
process mysqlbinlog output using the mysql client:
shell> mysqlbinlog binlog_files | mysql -u root -p

• Viewing log contents can be useful when you need to determine event times or positions to select
partial log contents prior to executing events. To view events from the log, send mysqlbinlog
output into a paging program:
shell> mysqlbinlog binlog_files | more

Alternatively, save the output in a file and view the file in a text editor:
shell> mysqlbinlog binlog_files > tmpfile
shell> ... edit tmpfile ...

• Saving the output in a file is useful as a preliminary to executing the log contents with certain events
removed, such as an accidental DROP DATABASE. You can delete from the file any statements not to
be executed before executing its contents. After editing the file, execute the contents as follows:
shell> mysql -u root -p < tmpfile

If you have more than one binary log to execute on the MySQL server, the safe method is to process
them all using a single connection to the server. Here is an example that demonstrates what may be
unsafe:
shell> mysqlbinlog binlog.000001 | mysql -u root -p # DANGER!!
shell> mysqlbinlog binlog.000002 | mysql -u root -p # DANGER!!

Processing binary logs this way using different connections to the server causes problems if the
first log file contains a CREATE TEMPORARY TABLE statement and the second log contains a
statement that uses the temporary table. When the first mysql process terminates, the server drops
the temporary table. When the second mysql process attempts to use the table, the server reports
“unknown table.”
To avoid problems like this, use a single connection to execute the contents of all binary logs that you
want to process. Here is one way to do so:
shell> mysqlbinlog binlog.000001 binlog.000002 | mysql -u root -p

Another approach is to write all the logs to a single file and then process the file:
shell> mysqlbinlog binlog.000001 > /tmp/statements.sql
shell> mysqlbinlog binlog.000002 >> /tmp/statements.sql
shell> mysql -u root -p -e "source /tmp/statements.sql"

7.5.1 Point-in-Time Recovery Using Event Times
To indicate the start and end times for recovery, specify the --start-datetime and --stopdatetime options for mysqlbinlog, in DATETIME format. As an example, suppose that exactly at
10:00 a.m. on April 20, 2005 an SQL statement was executed that deleted a large table. To restore
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Point-in-Time Recovery Using Event Positions

the table and data, you could restore the previous night's backup, and then execute the following
command:
shell> mysqlbinlog --stop-datetime="2005-04-20 9:59:59" \
/var/log/mysql/bin.123456 | mysql -u root -p

This command recovers all of the data up until the date and time given by the --stop-datetime
option. If you did not detect the erroneous SQL statement that was entered until hours later, you
will probably also want to recover the activity that occurred afterward. Based on this, you could run
mysqlbinlog again with a start date and time, like so:
shell> mysqlbinlog --start-datetime="2005-04-20 10:01:00" \
/var/log/mysql/bin.123456 | mysql -u root -p

In this command, the SQL statements logged from 10:01 a.m. on will be re-executed. The combination
of restoring of the previous night's dump file and the two mysqlbinlog commands restores everything
up until one second before 10:00 a.m. and everything from 10:01 a.m. on.
To use this method of point-in-time recovery, you should examine the log to be sure of the exact
times to specify for the commands. To display the log file contents without executing them, use this
command:
shell> mysqlbinlog /var/log/mysql/bin.123456 > /tmp/mysql_restore.sql

Then open the /tmp/mysql_restore.sql file with a text editor to examine it.
Excluding specific changes by specifying times for mysqlbinlog does not work well if multiple
statements executed at the same time as the one to be excluded.

7.5.2 Point-in-Time Recovery Using Event Positions
Instead of specifying dates and times, the --start-position and --stop-position options for
mysqlbinlog can be used for specifying log positions. They work the same as the start and stop
date options, except that you specify log position numbers rather than dates. Using positions may
enable you to be more precise about which part of the log to recover, especially if many transactions
occurred around the same time as a damaging SQL statement. To determine the position numbers, run
mysqlbinlog for a range of times near the time when the unwanted transaction was executed, but
redirect the results to a text file for examination. This can be done like so:
shell> mysqlbinlog --start-datetime="2005-04-20 9:55:00" \
--stop-datetime="2005-04-20 10:05:00" \
/var/log/mysql/bin.123456 > /tmp/mysql_restore.sql

This command creates a small text file in the /tmp directory that contains the SQL statements around
the time that the deleterious SQL statement was executed. Open this file with a text editor and look
for the statement that you do not want to repeat. Determine the positions in the binary log for stopping
and resuming the recovery and make note of them. Positions are labeled as log_pos followed by a
number. After restoring the previous backup file, use the position numbers to process the binary log
file. For example, you would use commands something like these:
shell> mysqlbinlog --stop-position=368312 /var/log/mysql/bin.123456 \
| mysql -u root -p
shell> mysqlbinlog --start-position=368315 /var/log/mysql/bin.123456 \
| mysql -u root -p

The first command recovers all the transactions up until the stop position given. The second command
recovers all transactions from the starting position given until the end of the binary log. Because the
output of mysqlbinlog includes SET TIMESTAMP statements before each SQL statement recorded,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MyISAM Table Maintenance and Crash Recovery

the recovered data and related MySQL logs will reflect the original times at which the transactions were
executed.

7.6 MyISAM Table Maintenance and Crash Recovery
This section discusses how to use myisamchk to check or repair MyISAM tables (tables that have
.MYD and .MYI files for storing data and indexes). For general myisamchk background, see
Section 4.6.3, “myisamchk — MyISAM Table-Maintenance Utility”. Other table-repair information can
be found at Section 2.19.4, “Rebuilding or Repairing Tables or Indexes”.
You can use myisamchk to check, repair, or optimize database tables. The following sections describe
how to perform these operations and how to set up a table maintenance schedule. For information
about using myisamchk to get information about your tables, see Section 4.6.3.5, “Obtaining Table
Information with myisamchk”.
Even though table repair with myisamchk is quite secure, it is always a good idea to make a backup
before doing a repair or any maintenance operation that could make a lot of changes to a table.
myisamchk operations that affect indexes can cause FULLTEXT indexes to be rebuilt with full-text
parameters that are incompatible with the values used by the MySQL server. To avoid this problem,
follow the guidelines in Section 4.6.3.1, “myisamchk General Options”.
MyISAM table maintenance can also be done using the SQL statements that perform operations similar
to what myisamchk can do:
• To check MyISAM tables, use CHECK TABLE.
• To repair MyISAM tables, use REPAIR TABLE.
• To optimize MyISAM tables, use OPTIMIZE TABLE.
• To analyze MyISAM tables, use ANALYZE TABLE.
For additional information about these statements, see Section 13.7.2, “Table Maintenance
Statements”.
These statements can be used directly or by means of the mysqlcheck client program. One
advantage of these statements over myisamchk is that the server does all the work. With myisamchk,
you must make sure that the server does not use the tables at the same time so that there is no
unwanted interaction between myisamchk and the server.

7.6.1 Using myisamchk for Crash Recovery
This section describes how to check for and deal with data corruption in MySQL databases. If your
tables become corrupted frequently, you should try to find the reason why. See Section B.5.3.3, “What
to Do If MySQL Keeps Crashing”.
For an explanation of how MyISAM tables can become corrupted, see Section 14.1.4, “MyISAM Table
Problems”.
If you run mysqld with external locking disabled (which is the default), you cannot reliably use
myisamchk to check a table when mysqld is using the same table. If you can be certain that no
one will access the tables through mysqld while you run myisamchk, you only have to execute
mysqladmin flush-tables before you start checking the tables. If you cannot guarantee this, you
must stop mysqld while you check the tables. If you run myisamchk to check tables that mysqld is
updating at the same time, you may get a warning that a table is corrupt even when it is not.
If the server is run with external locking enabled, you can use myisamchk to check tables at any
time. In this case, if the server tries to update a table that myisamchk is using, the server will wait for
myisamchk to finish before it continues.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Check MyISAM Tables for Errors

If you use myisamchk to repair or optimize tables, you must always ensure that the mysqld server
is not using the table (this also applies if external locking is disabled). If you do not stop mysqld, you
should at least do a mysqladmin flush-tables before you run myisamchk. Your tables may
become corrupted if the server and myisamchk access the tables simultaneously.
When performing crash recovery, it is important to understand that each MyISAM table tbl_name in a
database corresponds to the three files in the database directory shown in the following table.
File

Purpose

tbl_name.frm

Definition (format) file

tbl_name.MYD

Data file

tbl_name.MYI

Index file

Each of these three file types is subject to corruption in various ways, but problems occur most often in
data files and index files.
myisamchk works by creating a copy of the .MYD data file row by row. It ends the repair stage by
removing the old .MYD file and renaming the new file to the original file name. If you use --quick,
myisamchk does not create a temporary .MYD file, but instead assumes that the .MYD file is correct
and generates only a new index file without touching the .MYD file. This is safe, because myisamchk
automatically detects whether the .MYD file is corrupt and aborts the repair if it is. You can also specify
the --quick option twice to myisamchk. In this case, myisamchk does not abort on some errors
(such as duplicate-key errors) but instead tries to resolve them by modifying the .MYD file. Normally
the use of two --quick options is useful only if you have too little free disk space to perform a normal
repair. In this case, you should at least make a backup of the table before running myisamchk.

7.6.2 How to Check MyISAM Tables for Errors
To check a MyISAM table, use the following commands:
• myisamchk tbl_name
This finds 99.99% of all errors. What it cannot find is corruption that involves only the data file (which
is very unusual). If you want to check a table, you should normally run myisamchk without options or
with the -s (silent) option.
• myisamchk -m tbl_name
This finds 99.999% of all errors. It first checks all index entries for errors and then reads through all
rows. It calculates a checksum for all key values in the rows and verifies that the checksum matches
the checksum for the keys in the index tree.
• myisamchk -e tbl_name
This does a complete and thorough check of all data (-e means “extended check”). It does a checkread of every key for each row to verify that they indeed point to the correct row. This may take a
long time for a large table that has many indexes. Normally, myisamchk stops after the first error
it finds. If you want to obtain more information, you can add the -v (verbose) option. This causes
myisamchk to keep going, up through a maximum of 20 errors.
• myisamchk -e -i tbl_name
This is like the previous command, but the -i option tells myisamchk to print additional statistical
information.
In most cases, a simple myisamchk command with no arguments other than the table name is
sufficient to check a table.

7.6.3 How to Repair MyISAM Tables
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Repair MyISAM Tables

The discussion in this section describes how to use myisamchk on MyISAM tables (extensions .MYI
and .MYD).
You can also use the CHECK TABLE and REPAIR TABLE statements to check and repair MyISAM
tables. See Section 13.7.2.3, “CHECK TABLE Syntax”, and Section 13.7.2.6, “REPAIR TABLE
Syntax”.
Symptoms of corrupted tables include queries that abort unexpectedly and observable errors such as
these:
• tbl_name.frm is locked against change
• Can't find file tbl_name.MYI (Errcode: nnn)
• Unexpected end of file
• Record file is crashed
• Got error nnn from table handler
To get more information about the error, run perror nnn, where nnn is the error number. The
following example shows how to use perror to find the meanings for the most common error numbers
that indicate a problem with a table:
shell> perror 126 127 132 134 135 136 141 144 145
MySQL error code 126 = Index file is crashed
MySQL error code 127 = Record-file is crashed
MySQL error code 132 = Old database file
MySQL error code 134 = Record was already deleted (or record file crashed)
MySQL error code 135 = No more room in record file
MySQL error code 136 = No more room in index file
MySQL error code 141 = Duplicate unique key or constraint on write or update
MySQL error code 144 = Table is crashed and last repair failed
MySQL error code 145 = Table was marked as crashed and should be repaired

Note that error 135 (no more room in record file) and error 136 (no more room in index file) are not
errors that can be fixed by a simple repair. In this case, you must use ALTER TABLE to increase the
MAX_ROWS and AVG_ROW_LENGTH table option values:
ALTER TABLE tbl_name MAX_ROWS=xxx AVG_ROW_LENGTH=yyy;

If you do not know the current table option values, use SHOW CREATE TABLE.
For the other errors, you must repair your tables. myisamchk can usually detect and fix most problems
that occur.
The repair process involves up to four stages, described here. Before you begin, you should change
location to the database directory and check the permissions of the table files. On Unix, make sure that
they are readable by the user that mysqld runs as (and to you, because you need to access the files
you are checking). If it turns out you need to modify files, they must also be writable by you.
This section is for the cases where a table check fails (such as those described in Section 7.6.2, “How
to Check MyISAM Tables for Errors”), or you want to use the extended features that myisamchk
provides.
The myisamchk options used for table maintenance with are described in Section 4.6.3, “myisamchk
— MyISAM Table-Maintenance Utility”. myisamchk also has variables that you can set to control
memory allocation that may improve performance. See Section 4.6.3.6, “myisamchk Memory Usage”.
If you are going to repair a table from the command line, you must first stop the mysqld server. Note
that when you do mysqladmin shutdown on a remote server, the mysqld server is still available for
a while after mysqladmin returns, until all statement-processing has stopped and all index changes
have been flushed to disk.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How to Repair MyISAM Tables

Stage 1: Checking your tables
Run myisamchk *.MYI or myisamchk -e *.MYI if you have more time. Use the -s (silent) option
to suppress unnecessary information.
If the mysqld server is stopped, you should use the --update-state option to tell myisamchk to
mark the table as “checked.”
You have to repair only those tables for which myisamchk announces an error. For such tables,
proceed to Stage 2.
If you get unexpected errors when checking (such as out of memory errors), or if myisamchk
crashes, go to Stage 3.
Stage 2: Easy safe repair
First, try myisamchk -r -q tbl_name (-r -q means “quick recovery mode”). This attempts to
repair the index file without touching the data file. If the data file contains everything that it should and
the delete links point at the correct locations within the data file, this should work, and the table is fixed.
Start repairing the next table. Otherwise, use the following procedure:
1. Make a backup of the data file before continuing.
2. Use myisamchk -r tbl_name (-r means “recovery mode”). This removes incorrect rows and
deleted rows from the data file and reconstructs the index file.
3. If the preceding step fails, use myisamchk --safe-recover tbl_name. Safe recovery mode
uses an old recovery method that handles a few cases that regular recovery mode does not (but is
slower).
Note
If you want a repair operation to go much faster, you should set the values of
the sort_buffer_size and key_buffer_size variables each to about 25%
of your available memory when running myisamchk.
If you get unexpected errors when repairing (such as out of memory errors), or if myisamchk
crashes, go to Stage 3.
Stage 3: Difficult repair
You should reach this stage only if the first 16KB block in the index file is destroyed or contains
incorrect information, or if the index file is missing. In this case, it is necessary to create a new index
file. Do so as follows:
1. Move the data file to a safe place.
2. Use the table description file to create new (empty) data and index files:
shell>
mysql>
mysql>
mysql>

mysql db_name
SET autocommit=1;
TRUNCATE TABLE tbl_name;
quit

3. Copy the old data file back onto the newly created data file. (Do not just move the old file back onto
the new file. You want to retain a copy in case something goes wrong.)
Important
If you are using replication, you should stop it prior to performing the above
procedure, since it involves file system operations, and these are not logged by
MySQL.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MyISAM Table Optimization

Go back to Stage 2. myisamchk -r -q should work. (This should not be an endless loop.)
You can also use the REPAIR TABLE tbl_name USE_FRM SQL statement, which performs
the whole procedure automatically. There is also no possibility of unwanted interaction between
a utility and the server, because the server does all the work when you use REPAIR TABLE. See
Section 13.7.2.6, “REPAIR TABLE Syntax”.
Stage 4: Very difficult repair
You should reach this stage only if the .frm description file has also crashed. That should never
happen, because the description file is not changed after the table is created:
1. Restore the description file from a backup and go back to Stage 3. You can also restore the index
file and go back to Stage 2. In the latter case, you should start with myisamchk -r.
2. If you do not have a backup but know exactly how the table was created, create a copy of the table
in another database. Remove the new data file, and then move the .frm description and .MYI
index files from the other database to your crashed database. This gives you new description and
index files, but leaves the .MYD data file alone. Go back to Stage 2 and attempt to reconstruct the
index file.

7.6.4 MyISAM Table Optimization
To coalesce fragmented rows and eliminate wasted space that results from deleting or updating rows,
run myisamchk in recovery mode:
shell> myisamchk -r tbl_name

You can optimize a table in the same way by using the OPTIMIZE TABLE SQL statement. OPTIMIZE
TABLE does a table repair and a key analysis, and also sorts the index tree so that key lookups are
faster. There is also no possibility of unwanted interaction between a utility and the server, because the
server does all the work when you use OPTIMIZE TABLE. See Section 13.7.2.5, “OPTIMIZE TABLE
Syntax”.
myisamchk has a number of other options that you can use to improve the performance of a table:
• --analyze or -a: Perform key distribution analysis. This improves join performance by enabling the
join optimizer to better choose the order in which to join the tables and which indexes it should use.
• --sort-index or -S: Sort the index blocks. This optimizes seeks and makes table scans that use
indexes faster.
• --sort-records=index_num or -R index_num: Sort data rows according to a given index.
This makes your data much more localized and may speed up range-based SELECT and ORDER BY
operations that use this index.
For a full description of all available options, see Section 4.6.3, “myisamchk — MyISAM TableMaintenance Utility”.

7.6.5 Setting Up a MyISAM Table Maintenance Schedule
It is a good idea to perform table checks on a regular basis rather than waiting for problems to
occur. One way to check and repair MyISAM tables is with the CHECK TABLE and REPAIR TABLE
statements. See Section 13.7.2, “Table Maintenance Statements”.
Another way to check tables is to use myisamchk. For maintenance purposes, you can use
myisamchk -s. The -s option (short for --silent) causes myisamchk to run in silent mode,
printing messages only when errors occur.
It is also a good idea to enable automatic MyISAM table checking. For example, whenever the machine
has done a restart in the middle of an update, you usually need to check each table that could have
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Setting Up a MyISAM Table Maintenance Schedule

been affected before it is used further. (These are “expected crashed tables.”) To cause the server to
check MyISAM tables automatically, start it with the --myisam-recover option. See Section 5.1.3,
“Server Command Options”.
You should also check your tables regularly during normal system operation. For example, you can run
a cron job to check important tables once a week, using a line like this in a crontab file:
35 0 * * 0 /path/to/myisamchk --fast --silent /path/to/datadir/*/*.MYI

This prints out information about crashed tables so that you can examine and repair them as
necessary.
To start with, execute myisamchk -s each night on all tables that have been updated during the last
24 hours. As you see that problems occur infrequently, you can back off the checking frequency to
once a week or so.
Normally, MySQL tables need little maintenance. If you are performing many updates to MyISAM tables
with dynamic-sized rows (tables with VARCHAR, BLOB, or TEXT columns) or have tables with many
deleted rows you may want to defragment/reclaim space from the tables from time to time. You can do
this by using OPTIMIZE TABLE on the tables in question. Alternatively, if you can stop the mysqld
server for a while, change location into the data directory and use this command while the server is
stopped:
shell> myisamchk -r -s --sort-index --sort_buffer_size=16M */*.MYI

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 8 Optimization
Table of Contents
8.1 Optimization Overview .........................................................................................................
8.2 Optimizing SQL Statements .................................................................................................
8.2.1 Optimizing SELECT Statements ................................................................................
8.2.2 Optimizing DML Statements ......................................................................................
8.2.3 Optimizing Database Privileges .................................................................................
8.2.4 Other Optimization Tips ............................................................................................
8.3 Optimization and Indexes ....................................................................................................
8.3.1 How MySQL Uses Indexes .......................................................................................
8.3.2 Using Primary Keys ..................................................................................................
8.3.3 Using Foreign Keys ..................................................................................................
8.3.4 Column Indexes .......................................................................................................
8.3.5 Multiple-Column Indexes ...........................................................................................
8.3.6 Verifying Index Usage ..............................................................................................
8.3.7 MyISAM Index Statistics Collection ...........................................................................
8.3.8 Comparison of B-Tree and Hash Indexes ..................................................................
8.4 Optimizing Database Structure .............................................................................................
8.4.1 Optimizing Data Size ................................................................................................
8.4.2 Optimizing MySQL Data Types .................................................................................
8.4.3 Optimizing for Many Tables ......................................................................................
8.4.4 Internal Temporary Table Use in MySQL ...................................................................
8.5 Optimizing for MyISAM Tables .............................................................................................
8.5.1 Optimizing MyISAM Queries .....................................................................................
8.5.2 Bulk Data Loading for MyISAM Tables ......................................................................
8.5.3 Speed of REPAIR TABLE Statements .......................................................................
8.6 Optimizing for InnoDB Tables ..............................................................................................
8.6.1 Optimizing Storage Layout for InnoDB Tables ............................................................
8.6.2 Optimizing InnoDB Transaction Management .............................................................
8.6.3 Optimizing InnoDB Redo Logging .............................................................................
8.6.4 Bulk Data Loading for InnoDB Tables ........................................................................
8.6.5 Optimizing InnoDB Queries .......................................................................................
8.6.6 Optimizing InnoDB DDL Operations ..........................................................................
8.6.7 Optimizing InnoDB Disk I/O ......................................................................................
8.6.8 Optimizing InnoDB for Systems with Many Tables ......................................................
8.7 Optimizing for MEMORY Tables ..........................................................................................
8.8 Understanding the Query Execution Plan .............................................................................
8.8.1 Optimizing Queries with EXPLAIN .............................................................................
8.8.2 EXPLAIN Output Format ...........................................................................................
8.8.3 EXPLAIN EXTENDED Output Format .......................................................................
8.8.4 Estimating Query Performance ..................................................................................
8.9 Controlling the Query Optimizer ...........................................................................................
8.9.1 Controlling Query Plan Evaluation .............................................................................
8.9.2 Index Hints ...............................................................................................................
8.10 Buffering and Caching .......................................................................................................
8.10.1 The MyISAM Key Cache ........................................................................................
8.10.2 The InnoDB Buffer Pool ..........................................................................................
8.10.3 The MySQL Query Cache .......................................................................................
8.11 Optimizing Locking Operations ...........................................................................................
8.11.1 Internal Locking Methods ........................................................................................
8.11.2 Table Locking Issues ..............................................................................................
8.11.3 Concurrent Inserts ..................................................................................................
8.11.4 External Locking .....................................................................................................
8.12 Optimizing the MySQL Server ............................................................................................
This
documentation
is for an
older version.
If you're

662
664
664
698
699
700
700
700
702
702
702
703
704
704
706
707
707
709
711
712
713
713
715
716
717
717
718
719
719
720
720
721
721
721
722
722
722
732
734
734
734
735
736
736
740
741
747
747
749
750
751
752

This
documentation
is for an
older version.
If you're

Optimization Overview

8.12.1 System Factors and Startup Parameter Tuning ........................................................
8.12.2 Tuning Server Parameters ......................................................................................
8.12.3 Optimizing Disk I/O .................................................................................................
8.12.4 Using Symbolic Links ..............................................................................................
8.12.5 Optimizing Memory Use ..........................................................................................
8.12.6 Optimizing Network Use ..........................................................................................
8.13 Measuring Performance (Benchmarking) ............................................................................
8.13.1 Measuring the Speed of Expressions and Functions .................................................
8.13.2 The MySQL Benchmark Suite .................................................................................
8.13.3 Using Your Own Benchmarks .................................................................................
8.14 Examining Thread Information ...........................................................................................
8.14.1 Thread Command Values .......................................................................................
8.14.2 General Thread States ............................................................................................
8.14.3 Delayed-Insert Thread States ..................................................................................
8.14.4 Query Cache Thread States ....................................................................................
8.14.5 Replication Master Thread States ............................................................................
8.14.6 Replication Slave I/O Thread States ........................................................................
8.14.7 Replication Slave SQL Thread States ......................................................................
8.14.8 Replication Slave Connection Thread States ............................................................
8.14.9 MySQL Cluster Thread States .................................................................................

752
753
754
755
758
761
763
764
764
765
765
766
768
773
774
775
775
776
776
777

This chapter explains how to optimize MySQL performance and provides examples. Optimization
involves configuring, tuning, and measuring performance, at several levels. Depending on your job
role (developer, DBA, or a combination of both), you might optimize at the level of individual SQL
statements, entire applications, a single database server, or multiple networked database servers.
Sometimes you can be proactive and plan in advance for performance, while other times you might
troubleshoot a configuration or code issue after a problem occurs. Optimizing CPU and memory usage
can also improve scalability, allowing the database to handle more load without slowing down.

8.1 Optimization Overview
Database performance depends on several factors at the database level, such as tables, queries,
and configuration settings. These software constructs result in CPU and I/O operations at the
hardware level, which you must minimize and make as efficient as possible. As you work on database
performance, you start by learning the high-level rules and guidelines for the software side, and
measuring performance using wall-clock time. As you become an expert, you learn more about what
happens internally, and start measuring things such as CPU cycles and I/O operations.
Typical users aim to get the best database performance out of their existing software and hardware
configurations. Advanced users look for opportunities to improve the MySQL software itself, or develop
their own storage engines and hardware appliances to expand the MySQL ecosystem.

Optimizing at the Database Level
The most important factor in making a database application fast is its basic design:
• Are the tables structured properly? In particular, do the columns have the right data types, and
does each table have the appropriate columns for the type of work? For example, applications that
perform frequent updates often have many tables with few columns, while applications that analyze
large amounts of data often have few tables with many columns.
• Are the right indexes in place to make queries efficient?
• Are you using the appropriate storage engine for each table, and taking advantage of the strengths
and features of each storage engine you use? In particular, the choice of a nontransactional
storage engine such as MyISAM or a transactional one such as InnoDB can be very important for
performance and scalability.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing at the Hardware Level

• Does each table use an appropriate row format? This choice also depends on the storage engine
used for the table. In particular, compressed tables use less disk space and so require less disk I/O
to read and write the data. Compression is available for read-only MyISAM tables, and for all kinds of
workloads with InnoDB tables.
• Does the application use an appropriate locking strategy? For example, by allowing shared access
when possible so that database operations can run concurrently, and requesting exclusive access
when appropriate so that critical operations get top priority. Again, the choice of storage engine is
significant. The InnoDB storage engine handles most locking issues without involvement from you,
allowing for better concurrency in the database and reducing the amount of experimentation and
tuning for your code.
• Are all memory areas used for caching sized correctly? That is, large enough to hold frequently
accessed data, but not so large that they overload physical memory and cause paging. The main
memory areas to configure are the MyISAM key cache, the InnoDB buffer pool, and the MySQL
query cache.

Optimizing at the Hardware Level
Any database application eventually hits hardware limits as the database becomes more and more
busy. A DBA must evaluate whether it is possible to tune the application or reconfigure the server
to avoid these bottlenecks, or whether more hardware resources are required. System bottlenecks
typically arise from these sources:
• Disk seeks. It takes time for the disk to find a piece of data. With modern disks, the mean time
for this is usually lower than 10ms, so we can in theory do about 100 seeks a second. This time
improves slowly with new disks and is very hard to optimize for a single table. The way to optimize
seek time is to distribute the data onto more than one disk.
• Disk reading and writing. When the disk is at the correct position, we need to read or write the data.
With modern disks, one disk delivers at least 10–20MB/s throughput. This is easier to optimize than
seeks because you can read in parallel from multiple disks.
• CPU cycles. When the data is in main memory, we must process it to get our result. Having large
tables compared to the amount of memory is the most common limiting factor. But with small tables,
speed is usually not the problem.
• Memory bandwidth. When the CPU needs more data than can fit in the CPU cache, main memory
bandwidth becomes a bottleneck. This is an uncommon bottleneck for most systems, but one to be
aware of.

Balancing Portability and Performance
Because all SQL servers implement different parts of standard SQL, it takes work to write portable
database applications. It is very easy to achieve portability for very simple selects and inserts, but
becomes more difficult the more capabilities you require. If you want an application that is fast with
many database systems, it becomes even more difficult.
All database systems have some weak points. That is, they have different design compromises that
lead to different behavior.
To make a complex application portable, you need to determine which SQL servers it must work with,
and then determine what features those servers support. You can use the MySQL crash-me program
to find functions, types, and limits that you can use with a selection of database servers. crash-me
does not check for every possible feature, but it is still reasonably comprehensive, performing about
450 tests. An example of the type of information crash-me can provide is that you should not use
column names that are longer than 18 characters if you want to be able to use Informix or DB2.
The crash-me program and the MySQL benchmarks are all very database independent. By taking a
look at how they are written, you can get a feeling for what you must do to make your own applications
database independent. The programs can be found in the sql-bench directory of MySQL source
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SQL Statements

distributions. They are written in Perl and use the DBI database interface. Use of DBI in itself solves
part of the portability problem because it provides database-independent access methods. See
Section 8.13.2, “The MySQL Benchmark Suite”.
If you strive for database independence, you need to get a good feeling for each SQL server's
bottlenecks. For example, MySQL is very fast in retrieving and updating rows for MyISAM tables, but
has a problem in mixing slow readers and writers on the same table. Transactional database systems
in general are not very good at generating summary tables from log tables, because in this case row
locking is almost useless.
To make your application really database independent, you should define an easily extendable
interface through which you manipulate your data. For example, C++ is available on most systems, so
it makes sense to use a C++ class-based interface to the databases.
If you use some feature that is specific to a given database system (such as the REPLACE statement,
which is specific to MySQL), you should implement the same feature for other SQL servers by coding
an alternative method. Although the alternative might be slower, it enables the other servers to perform
the same tasks.
To use performance-oriented SQL extensions in a portable MySQL program, you can wrap MySQLspecific keywords in a statement within /*! */ comment delimiters. Other SQL servers ignore the
commented keywords. For information about writing comments, see Section 9.6, “Comment Syntax”.
If high performance is more important than exactness, as for some Web applications, it is possible
to create an application layer that caches all results to give you even higher performance. By letting
old results expire after a while, you can keep the cache reasonably fresh. This provides a method
to handle high load spikes, in which case you can dynamically increase the cache size and set the
expiration timeout higher until things get back to normal.
In this case, the table creation information should contain information about the initial cache size and
how often the table should normally be refreshed.
An attractive alternative to implementing an application cache is to use the MySQL query cache. By
enabling the query cache, the server handles the details of determining whether a query result can be
reused. This simplifies your application. See Section 8.10.3, “The MySQL Query Cache”.

8.2 Optimizing SQL Statements
The core logic of a database application is performed through SQL statements, whether issued directly
through an interpreter or submitted behind the scenes through an API. The tuning guidelines in this
section help to speed up all kinds of MySQL applications. The guidelines cover SQL operations that
read and write data, the behind-the-scenes overhead for SQL operations in general, and operations
used in specific scenarios such as database monitoring.

8.2.1 Optimizing SELECT Statements
Queries, in the form of SELECT statements, perform all the lookup operations in the database. Tuning
these statements is a top priority, whether to achieve sub-second response times for dynamic web
pages, or to chop hours off the time to generate huge overnight reports.
Besides SELECT statements, the tuning techniques for queries also apply to constructs such as
CREATE TABLE...AS SELECT, INSERT INTO...SELECT, and WHERE clauses in DELETE
statements. Those statements have additional performance considerations because they combine write
operations with the read-oriented query operations.

8.2.1.1 Speed of SELECT Statements
The main considerations for optimizing queries are:
• To make a slow SELECT ... WHERE query faster, the first thing to check is whether you can add
an index. Set up indexes on columns used in the WHERE clause, to speed up evaluation, filtering, and
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

the final retrieval of results. To avoid wasted disk space, construct a small set of indexes that speed
up many related queries used in your application.
Indexes are especially important for queries that reference different tables, using features such as
joins and foreign keys. You can use the EXPLAIN statement to determine which indexes are used for
a SELECT. See Section 8.3.1, “How MySQL Uses Indexes” and Section 8.8.1, “Optimizing Queries
with EXPLAIN”.
• Isolate and tune any part of the query, such as a function call, that takes excessive time. Depending
on how the query is structured, a function could be called once for every row in the result set, or even
once for every row in the table, greatly magnifying any inefficiency.
• Minimize the number of full table scans in your queries, particularly for big tables.
• Keep table statistics up to date by using the ANALYZE TABLE statement periodically, so the
optimizer has the information needed to construct an efficient execution plan.
• Learn the tuning techniques, indexing techniques, and configuration parameters that are specific to
the storage engine for each table. Both InnoDB and MyISAM have sets of guidelines for enabling
and sustaining high performance in queries. For details, see Section 8.6.5, “Optimizing InnoDB
Queries” and Section 8.5.1, “Optimizing MyISAM Queries”.
• Avoid transforming the query in ways that make it hard to understand, especially if the optimizer does
some of the same transformations automatically.
• If a performance issue is not easily solved by one of the basic guidelines, investigate the internal
details of the specific query by reading the EXPLAIN plan and adjusting your indexes, WHERE
clauses, join clauses, and so on. (When you reach a certain level of expertise, reading the EXPLAIN
plan might be your first step for every query.)
• Adjust the size and properties of the memory areas that MySQL uses for caching. With efficient use
of the MyISAM key cache, InnoDB buffer pool, and the MySQL query cache, repeated queries run
faster because the results are retrieved from memory the second and subsequent times.
• Even for a query that runs fast using the cache memory areas, you might still optimize further so that
they require less cache memory, making your application more scalable. Scalability means that your
application can handle more simultaneous users, larger requests, and so on without experiencing a
big drop in performance.
• Deal with locking issues, where the speed of your query might be affected by other sessions
accessing the tables at the same time.

8.2.1.2 How MySQL Optimizes WHERE Clauses
This section discusses optimizations that can be made for processing WHERE clauses. The examples
use SELECT statements, but the same optimizations apply for WHERE clauses in DELETE and UPDATE
statements.
Work on the MySQL optimizer is ongoing, so this section is incomplete. MySQL performs a great many
optimizations, not all of which are documented here.
Some of the optimizations performed by MySQL follow:
• Removal of unnecessary parentheses:
((a AND b) AND c OR (((a AND b) AND (c AND d))))
-> (a AND b AND c) OR (a AND b AND c AND d)

• Constant folding:
(a b>5 AND b=c AND a=5

• Constant condition removal (needed because of constant folding):
(B>=5 AND B=5) OR (B=6 AND 5=5) OR (B=7 AND 5=6)
-> B=5 OR B=6

• Constant expressions used by indexes are evaluated only once.
• COUNT(*) on a single table without a WHERE is retrieved directly from the table information for
MyISAM and MEMORY tables. This is also done for any NOT NULL expression when used with only
one table.
• Early detection of invalid constant expressions. MySQL quickly detects that some SELECT
statements are impossible and returns no rows.
• HAVING is merged with WHERE if you do not use GROUP BY or aggregate functions (COUNT(),
MIN(), and so on).
• For each table in a join, a simpler WHERE is constructed to get a fast WHERE evaluation for the table
and also to skip rows as soon as possible.
•

All constant tables are read first before any other tables in the query. A constant table is any of the
following:
• An empty table or a table with one row.
• A table that is used with a WHERE clause on a PRIMARY KEY or a UNIQUE index, where all index
parts are compared to constant expressions and are defined as NOT NULL.
All of the following tables are used as constant tables:
SELECT * FROM t WHERE primary_key=1;
SELECT * FROM t1,t2
WHERE t1.primary_key=1 AND t2.primary_key=t1.id;

• The best join combination for joining the tables is found by trying all possibilities. If all columns in
ORDER BY and GROUP BY clauses come from the same table, that table is preferred first when
joining.
• If there is an ORDER BY clause and a different GROUP BY clause, or if the ORDER BY or GROUP BY
contains columns from tables other than the first table in the join queue, a temporary table is created.
• If you use the SQL_SMALL_RESULT option, MySQL uses an in-memory temporary table.
• Each table index is queried, and the best index is used unless the optimizer believes that it is more
efficient to use a table scan. At one time, a scan was used based on whether the best index spanned
more than 30% of the table, but a fixed percentage no longer determines the choice between using
an index or a scan. The optimizer now is more complex and bases its estimate on additional factors
such as table size, number of rows, and I/O block size.
• MySQL can sometimes produce query results using data from the index, without consulting the table
data. If all columns used from the index are numeric, only the index data is used to resolve the query.
• Before each row is output, those that do not match the HAVING clause are skipped.
Some examples of queries that are very fast:
SELECT COUNT(*) FROM tbl_name;
SELECT MIN(key_part1),MAX(key_part1) FROM tbl_name;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

SELECT MAX(key_part2) FROM tbl_name
WHERE key_part1=constant;
SELECT ... FROM tbl_name
ORDER BY key_part1,key_part2,... LIMIT 10;
SELECT ... FROM tbl_name
ORDER BY key_part1 DESC, key_part2 DESC, ... LIMIT 10;

MySQL resolves the following queries using only the index tree, assuming that the indexed columns
are numeric:
SELECT key_part1,key_part2 FROM tbl_name WHERE key_part1=val;
SELECT COUNT(*) FROM tbl_name
WHERE key_part1=val1 AND key_part2=val2;
SELECT key_part2 FROM tbl_name GROUP BY key_part1;

The following queries use indexing to retrieve the rows in sorted order without a separate sorting pass:
SELECT ... FROM tbl_name
ORDER BY key_part1,key_part2,... ;
SELECT ... FROM tbl_name
ORDER BY key_part1 DESC, key_part2 DESC, ... ;

8.2.1.3 Range Optimization
The range access method uses a single index to retrieve a subset of table rows that are contained
within one or several index value intervals. It can be used for a single-part or multiple-part index. The
following sections give a detailed description of how intervals are extracted from the WHERE clause.

The Range Access Method for Single-Part Indexes
For a single-part index, index value intervals can be conveniently represented by corresponding
conditions in the WHERE clause, denoted as range conditions rather than “intervals.”
The definition of a range condition for a single-part index is as follows:
• For both BTREE and HASH indexes, comparison of a key part with a constant value is a range
condition when using the =, <=>, IN(), IS NULL, or IS NOT NULL operators.
• Additionally, for BTREE indexes, comparison of a key part with a constant value is a range condition
when using the >, <, >=, <=, BETWEEN, !=, or <> operators, or LIKE comparisons if the argument to
LIKE is a constant string that does not start with a wildcard character.
• For all index types, multiple range conditions combined with OR or AND form a range condition.
“Constant value” in the preceding descriptions means one of the following:
• A constant from the query string
• A column of a const or system table from the same join
• The result of an uncorrelated subquery
• Any expression composed entirely from subexpressions of the preceding types
Here are some examples of queries with range conditions in the WHERE clause:
SELECT * FROM t1
WHERE key_col > 1
AND key_col < 10;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

SELECT * FROM t1
WHERE key_col = 1
OR key_col IN (15,18,20);
SELECT * FROM t1
WHERE key_col LIKE 'ab%'
OR key_col BETWEEN 'bar' AND 'foo';

Some nonconstant values may be converted to constants during the optimizer constant propagation
phase.
MySQL tries to extract range conditions from the WHERE clause for each of the possible indexes.
During the extraction process, conditions that cannot be used for constructing the range condition are
dropped, conditions that produce overlapping ranges are combined, and conditions that produce empty
ranges are removed.
Consider the following statement, where key1 is an indexed column and nonkey is not indexed:
SELECT * FROM t1 WHERE
(key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR
(key1 < 'bar' AND nonkey = 4) OR
(key1 < 'uux' AND key1 > 'z');

The extraction process for key key1 is as follows:
1. Start with original WHERE clause:
(key1 < 'abc' AND (key1 LIKE 'abcde%' OR key1 LIKE '%b')) OR
(key1 < 'bar' AND nonkey = 4) OR
(key1 < 'uux' AND key1 > 'z')

2. Remove nonkey = 4 and key1 LIKE '%b' because they cannot be used for a range scan. The
correct way to remove them is to replace them with TRUE, so that we do not miss any matching
rows when doing the range scan. Having replaced them with TRUE, we get:
(key1 < 'abc' AND (key1 LIKE 'abcde%' OR TRUE)) OR
(key1 < 'bar' AND TRUE) OR
(key1 < 'uux' AND key1 > 'z')

3. Collapse conditions that are always true or false:
• (key1 LIKE 'abcde%' OR TRUE) is always true
• (key1 < 'uux' AND key1 > 'z') is always false
Replacing these conditions with constants, we get:
(key1 < 'abc' AND TRUE) OR (key1 < 'bar' AND TRUE) OR (FALSE)

Removing unnecessary TRUE and FALSE constants, we obtain:
(key1 < 'abc') OR (key1 < 'bar')

4. Combining overlapping intervals into one yields the final condition to be used for the range scan:
(key1 < 'bar')

In general (and as demonstrated by the preceding example), the condition used for a range scan is
less restrictive than the WHERE clause. MySQL performs an additional check to filter out rows that
satisfy the range condition but not the full WHERE clause.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

The range condition extraction algorithm can handle nested AND/OR constructs of arbitrary depth, and
its output does not depend on the order in which conditions appear in WHERE clause.
MySQL does not support merging multiple ranges for the range access method for spatial indexes. To
work around this limitation, you can use a UNION with identical SELECT statements, except that you put
each spatial predicate in a different SELECT.

The Range Access Method for Multiple-Part Indexes
Range conditions on a multiple-part index are an extension of range conditions for a single-part index.
A range condition on a multiple-part index restricts index rows to lie within one or several key tuple
intervals. Key tuple intervals are defined over a set of key tuples, using ordering from the index.
For example, consider a multiple-part index defined as key1(key_part1, key_part2,
key_part3), and the following set of key tuples listed in key order:
key_part1
NULL
NULL
NULL
1
1
1
2

key_part2
1
1
2
1
1
2
1

key_part3
'abc'
'xyz'
'foo'
'abc'
'xyz'
'abc'
'aaa'

The condition key_part1 = 1 defines this interval:
(1,-inf,-inf) <= (key_part1,key_part2,key_part3) < (1,+inf,+inf)

The interval covers the 4th, 5th, and 6th tuples in the preceding data set and can be used by the range
access method.
By contrast, the condition key_part3 = 'abc' does not define a single interval and cannot be used
by the range access method.
The following descriptions indicate how range conditions work for multiple-part indexes in greater
detail.
• For HASH indexes, each interval containing identical values can be used. This means that the interval
can be produced only for conditions in the following form:
key_part1 cmp const1
AND key_part2 cmp const2
AND ...
AND key_partN cmp constN;

Here, const1, const2, … are constants, cmp is one of the =, <=>, or IS NULL comparison
operators, and the conditions cover all index parts. (That is, there are N conditions, one for each part
of an N-part index.) For example, the following is a range condition for a three-part HASH index:
key_part1 = 1 AND key_part2 IS NULL AND key_part3 = 'foo'

For the definition of what is considered to be a constant, see The Range Access Method for SinglePart Indexes.
• For a BTREE index, an interval might be usable for conditions combined with AND, where each
condition compares a key part with a constant value using =, <=>, IS NULL, >, <, >=, <=, !=, <>,
BETWEEN, or LIKE 'pattern' (where 'pattern' does not start with a wildcard). An interval can
be used as long as it is possible to determine a single key tuple containing all rows that match the
condition (or two intervals if <> or != is used).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

The optimizer attempts to use additional key parts to determine the interval as long as the
comparison operator is =, <=>, or IS NULL. If the operator is >, <, >=, <=, !=, <>, BETWEEN,
or LIKE, the optimizer uses it but considers no more key parts. For the following expression,
the optimizer uses = from the first comparison. It also uses >= from the second comparison but
considers no further key parts and does not use the third comparison for interval construction:
key_part1 = 'foo' AND key_part2 >= 10 AND key_part3 > 10

The single interval is:
('foo',10,-inf) < (key_part1,key_part2,key_part3) < ('foo',+inf,+inf)

It is possible that the created interval contains more rows than the initial condition. For example,
the preceding interval includes the value ('foo', 11, 0), which does not satisfy the original
condition.
• If conditions that cover sets of rows contained within intervals are combined with OR, they form a
condition that covers a set of rows contained within the union of their intervals. If the conditions are
combined with AND, they form a condition that covers a set of rows contained within the intersection
of their intervals. For example, for this condition on a two-part index:
(key_part1 = 1 AND key_part2 < 2) OR (key_part1 > 5)

The intervals are:
(1,-inf) < (key_part1,key_part2) < (1,2)
(5,-inf) < (key_part1,key_part2)

In this example, the interval on the first line uses one key part for the left bound and two key parts for
the right bound. The interval on the second line uses only one key part. The key_len column in the
EXPLAIN output indicates the maximum length of the key prefix used.
In some cases, key_len may indicate that a key part was used, but that might be not what you
would expect. Suppose that key_part1 and key_part2 can be NULL. Then the key_len column
displays two key part lengths for the following condition:
key_part1 >= 1 AND key_part2 < 2

But, in fact, the condition is converted to this:
key_part1 >= 1 AND key_part2 IS NOT NULL

The Range Access Method for Single-Part Indexes, describes how optimizations are performed
to combine or eliminate intervals for range conditions on a single-part index. Analogous steps are
performed for range conditions on multiple-part indexes.

8.2.1.4 Index Merge Optimization
The Index Merge method is used to retrieve rows with several range scans and to merge their results
into one. The merge can produce unions, intersections, or unions-of-intersections of its underlying
scans. This access method merges index scans from a single table; it does not merge scans across
multiple tables.
Note
If you have upgraded from a previous version of MySQL, you should be
aware that this type of join optimization is first introduced in MySQL 5.0, and

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

represents a significant change in behavior with regard to indexes. (Formerly,
MySQL was able to use at most only one index for each referenced table.)
In EXPLAIN output, the Index Merge method appears as index_merge in the type column. In this
case, the key column contains a list of indexes used, and key_len contains a list of the longest key
parts for those indexes.
Examples:
SELECT * FROM tbl_name WHERE key1 = 10 OR key2 = 20;
SELECT * FROM tbl_name
WHERE (key1 = 10 OR key2 = 20) AND non_key=30;
SELECT * FROM t1, t2
WHERE (t1.key1 IN (1,2) OR t1.key2 LIKE 'value%')
AND t2.key1=t1.some_col;
SELECT * FROM t1, t2
WHERE t1.key1=1
AND (t2.key1=t1.some_col OR t2.key2=t1.some_col2);

The Index Merge method has several access algorithms (seen in the Extra field of EXPLAIN output):
• Using intersect(...)
• Using union(...)
• Using sort_union(...)
The following sections describe these methods in greater detail.
Note
The Index Merge optimization algorithm has the following known deficiencies:
• If your query has a complex WHERE clause with deep AND/OR nesting and
MySQL does not choose the optimal plan, try distributing terms using the
following identity laws:
(x AND y) OR z = (x OR z) AND (y OR z)
(x OR y) AND z = (x AND z) OR (y AND z)

• Index Merge is not applicable to full-text indexes. We plan to extend it to
cover these in a future MySQL release.
• If a range scan is possible on some key, the optimizer will not consider using
Index Merge Union or Index Merge Sort-Union algorithms. For example,
consider this query:
SELECT * FROM t1 WHERE (goodkey1 < 10 OR goodkey2 < 20) AND badkey < 30;

For this query, two plans are possible:
• An Index Merge scan using the (goodkey1 < 10 OR goodkey2 < 20)
condition.
• A range scan using the badkey < 30 condition.
However, the optimizer considers only the second plan.
The choice between different possible variants of the Index Merge access method and other access
methods is based on cost estimates of various available options.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

The Index Merge Intersection Access Algorithm
This access algorithm can be employed when a WHERE clause was converted to several range
conditions on different keys combined with AND, and each condition is one of the following:
• In this form, where the index has exactly N parts (that is, all index parts are covered):
key_part1=const1 AND key_part2=const2 ... AND key_partN=constN

• Any range condition over a primary key of an InnoDB or BDB table.
Examples:
SELECT * FROM innodb_table WHERE primary_key < 10 AND key_col1=20;
SELECT * FROM tbl_name
WHERE (key1_part1=1 AND key1_part2=2) AND key2=2;

The Index Merge intersection algorithm performs simultaneous scans on all used indexes and
produces the intersection of row sequences that it receives from the merged index scans.
If all columns used in the query are covered by the used indexes, full table rows are not retrieved
(EXPLAIN output contains Using index in Extra field in this case). Here is an example of such a
query:
SELECT COUNT(*) FROM t1 WHERE key1=1 AND key2=1;

If the used indexes do not cover all columns used in the query, full rows are retrieved only when the
range conditions for all used keys are satisfied.
If one of the merged conditions is a condition over a primary key of an InnoDB or BDB table, it is not
used for row retrieval, but is used to filter out rows retrieved using other conditions.

The Index Merge Union Access Algorithm
The applicability criteria for this algorithm are similar to those for the Index Merge method intersection
algorithm. The algorithm can be employed when the table's WHERE clause was converted to several
range conditions on different keys combined with OR, and each condition is one of the following:
• In this form, where the index has exactly N parts (that is, all index parts are covered):
key_part1=const1 AND key_part2=const2 ... AND key_partN=constN

• Any range condition over a primary key of an InnoDB or BDB table.
• A condition for which the Index Merge method intersection algorithm is applicable.
Examples:
SELECT * FROM t1 WHERE key1=1 OR key2=2 OR key3=3;
SELECT * FROM innodb_table WHERE (key1=1 AND key2=2) OR
(key3='foo' AND key4='bar') AND key5=5;

The Index Merge Sort-Union Access Algorithm
This access algorithm is employed when the WHERE clause was converted to several range conditions
combined by OR, but for which the Index Merge method union algorithm is not applicable.
Examples:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

SELECT * FROM tbl_name WHERE key_col1 < 10 OR key_col2 < 20;
SELECT * FROM tbl_name
WHERE (key_col1 > 10 OR key_col2 = 20) AND nonkey_col=30;

The difference between the sort-union algorithm and the union algorithm is that the sort-union algorithm
must first fetch row IDs for all rows and sort them before returning any rows.

8.2.1.5 Engine Condition Pushdown Optimization
This optimization improves the efficiency of direct comparisons between a nonindexed column and
a constant. In such cases, the condition is “pushed down” to the storage engine for evaluation. This
optimization can be used only by the NDB storage engine.
For MySQL Cluster, this optimization can eliminate the need to send nonmatching rows over the
network between the cluster's data nodes and the MySQL Server that issued the query, and can speed
up queries where it is used by a factor of 5 to 10 times over cases where condition pushdown could be
but is not used.
Suppose that a MySQL Cluster table is defined as follows:
CREATE TABLE t1 (
a INT,
b INT,
KEY(a)
) ENGINE=NDB;

Condition pushdown can be used with queries such as the one shown here, which includes a
comparison between a nonindexed column and a constant:
SELECT a, b FROM t1 WHERE b = 10;

The use of condition pushdown can be seen in the output of EXPLAIN:
mysql> EXPLAIN SELECT a,b FROM t1 WHERE b = 10\G
*************************** 1. row ***************************
id: 1
select_type: SIMPLE
table: t1
type: ALL
possible_keys: NULL
key: NULL
key_len: NULL
ref: NULL
rows: 10
Extra: Using where with pushed condition

However, condition pushdown cannot be used with either of these two queries:
SELECT a,b FROM t1 WHERE a = 10;
SELECT a,b FROM t1 WHERE b + 1 = 10;

Condition pushdown is not applicable to the first query because an index exists on column a. (An index
access method would be more efficient and so would be chosen in preference to condition pushdown.)
Condition pushdown cannot be employed for the second query because the comparison involving the
nonindexed column b is indirect. (However, condition pushdown could be applied if you were to reduce
b + 1 = 10 to b = 9 in the WHERE clause.)
Condition pushdown may also be employed when an indexed column is compared with a constant
using a > or < operator:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

mysql> EXPLAIN SELECT a, b FROM t1 WHERE a < 2\G
*************************** 1. row ***************************
id: 1
select_type: SIMPLE
table: t1
type: range
possible_keys: a
key: a
key_len: 5
ref: NULL
rows: 2
Extra: Using where with pushed condition

Other supported comparisons for condition pushdown include the following:
• column [NOT] LIKE pattern
pattern must be a string literal containing the pattern to be matched; for syntax, see
Section 12.5.1, “String Comparison Functions”.
• column IS [NOT] NULL
• column IN (value_list)
Each item in the value_list must be a constant, literal value.
• column BETWEEN constant1 AND constant2
constant1 and constant2 must each be a constant, literal value.
In all of the cases in the preceding list, it is possible for the condition to be converted into the form of
one or more direct comparisons between a column and a constant.
Engine condition pushdown is disabled by default. To enable it at server startup, set the
engine_condition_pushdown system variable. For example, in a my.cnf file, use these lines:
[mysqld]
engine_condition_pushdown=1

At runtime, enable condition pushdown with either of the following statements:
SET engine_condition_pushdown=ON;

SET engine_condition_pushdown=1;

Limitations.

Engine condition pushdown is subject to the following limitations:

• Condition pushdown is supported only by the NDB storage engine.
• Columns may be compared with constants only; however, this includes expressions which evaluate
to constant values.
• Columns used in comparisons cannot be of any of the BLOB or TEXT types.
• A string value to be compared with a column must use the same collation as the column.
• Joins are not directly supported; conditions involving multiple tables are pushed separately where
possible. Use EXPLAIN EXTENDED to determine which conditions are actually pushed down.

8.2.1.6 IS NULL Optimization
MySQL can perform the same optimization on col_name IS NULL that it can use for col_name =
constant_value. For example, MySQL can use indexes and ranges to search for NULL with IS
NULL.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

Examples:
SELECT * FROM tbl_name WHERE key_col IS NULL;
SELECT * FROM tbl_name WHERE key_col <=> NULL;
SELECT * FROM tbl_name
WHERE key_col=const1 OR key_col=const2 OR key_col IS NULL;

If a WHERE clause includes a col_name IS NULL condition for a column that is declared as NOT
NULL, that expression is optimized away. This optimization does not occur in cases when the column
might produce NULL anyway; for example, if it comes from a table on the right side of a LEFT JOIN.
MySQL can also optimize the combination col_name = expr OR col_name IS NULL, a form that
is common in resolved subqueries. EXPLAIN shows ref_or_null when this optimization is used.
This optimization can handle one IS NULL for any key part.
Some examples of queries that are optimized, assuming that there is an index on columns a and b of
table t2:
SELECT * FROM t1 WHERE t1.a=expr OR t1.a IS NULL;
SELECT * FROM t1, t2 WHERE t1.a=t2.a OR t2.a IS NULL;
SELECT * FROM t1, t2
WHERE (t1.a=t2.a OR t2.a IS NULL) AND t2.b=t1.b;
SELECT * FROM t1, t2
WHERE t1.a=t2.a AND (t2.b=t1.b OR t2.b IS NULL);
SELECT * FROM t1, t2
WHERE (t1.a=t2.a AND t2.a IS NULL AND ...)
OR (t1.a=t2.a AND t2.a IS NULL AND ...);

ref_or_null works by first doing a read on the reference key, and then a separate search for rows
with a NULL key value.
The optimization can handle only one IS NULL level. In the following query, MySQL uses key lookups
only on the expression (t1.a=t2.a AND t2.a IS NULL) and is not able to use the key part on b:
SELECT * FROM t1, t2
WHERE (t1.a=t2.a AND t2.a IS NULL)
OR (t1.b=t2.b AND t2.b IS NULL);

8.2.1.7 LEFT JOIN and RIGHT JOIN Optimization
MySQL implements an A LEFT JOIN B join_condition as follows:
• Table B is set to depend on table A and all tables on which A depends.
• Table A is set to depend on all tables (except B) that are used in the LEFT JOIN condition.
• The LEFT JOIN condition is used to decide how to retrieve rows from table B. (In other words, any
condition in the WHERE clause is not used.)
• All standard join optimizations are performed, with the exception that a table is always read after all
tables on which it depends. If there is a circular dependence, MySQL issues an error.
• All standard WHERE optimizations are performed.
• If there is a row in A that matches the WHERE clause, but there is no row in B that matches the ON
condition, an extra B row is generated with all columns set to NULL.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

• If you use LEFT JOIN to find rows that do not exist in some table and you have the following test:
col_name IS NULL in the WHERE part, where col_name is a column that is declared as NOT
NULL, MySQL stops searching for more rows (for a particular key combination) after it has found one
row that matches the LEFT JOIN condition.
The implementation of RIGHT JOIN is analogous to that of LEFT JOIN with the roles of the tables
reversed.
The join optimizer calculates the order in which tables should be joined. The table read order forced by
LEFT JOIN or STRAIGHT_JOIN helps the join optimizer do its work much more quickly, because there
are fewer table permutations to check. Note that this means that if you do a query of the following type,
MySQL does a full scan on b because the LEFT JOIN forces it to be read before d:
SELECT *
FROM a JOIN b LEFT JOIN c ON (c.key=a.key)
LEFT JOIN d ON (d.key=a.key)
WHERE b.key=d.key;

The fix in this case is reverse the order in which a and b are listed in the FROM clause:
SELECT *
FROM b JOIN a LEFT JOIN c ON (c.key=a.key)
LEFT JOIN d ON (d.key=a.key)
WHERE b.key=d.key;

For a LEFT JOIN, if the WHERE condition is always false for the generated NULL row, the LEFT JOIN
is changed to a normal join. For example, the WHERE clause would be false in the following query if
t2.column1 were NULL:
SELECT * FROM t1 LEFT JOIN t2 ON (column1) WHERE t2.column2=5;

Therefore, it is safe to convert the query to a normal join:
SELECT * FROM t1, t2 WHERE t2.column2=5 AND t1.column1=t2.column1;

This can be made faster because MySQL can use table t2 before table t1 if doing so would result
in a better query plan. To provide a hint about the table join order, use STRAIGHT_JOIN. (See
Section 13.2.8, “SELECT Syntax”.)

8.2.1.8 Nested-Loop Join Algorithms
MySQL executes joins between tables using a nested-loop algorithm or variations on it.
Nested-Loop Join Algorithm
A simple nested-loop join (NLJ) algorithm reads rows from the first table in a loop one at a time,
passing each row to a nested loop that processes the next table in the join. This process is repeated as
many times as there remain tables to be joined.
Assume that a join between three tables t1, t2, and t3 is to be executed using the following join
types:
Table
t1
t2
t3

Join Type
range
ref
ALL

If a simple NLJ algorithm is used, the join is processed like this:
for each row in t1 matching range {

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

for each row in t2 matching reference key {
for each row in t3 {
if row satisfies join conditions,
send to client
}
}
}

Because the NLJ algorithm passes rows one at a time from outer loops to inner loops, it typically reads
tables processed in the inner loops many times.
Block Nested-Loop Join Algorithm
A Block Nested-Loop (BNL) join algorithm uses buffering of rows read in outer loops to reduce the
number of times that tables in inner loops must be read. For example, if 10 rows are read into a buffer
and the buffer is passed to the next inner loop, each row read in the inner loop can be compared
against all 10 rows in the buffer. The reduces the number of times the inner table must be read by an
order of magnitude.
MySQL uses join buffering under these conditions:
• The join_buffer_size system variable determines the size of each join buffer.
• Join buffering can be used when the join is of type ALL or index (in other words, when no possible
keys can be used, and a full scan is done, of either the data or index rows, respectively), or range.
• One buffer is allocated for each join that can be buffered, so a given query might be processed using
multiple join buffers.
• A join buffer is never allocated for the first nonconst table, even if it would be of type ALL or index.
• A join buffer is allocated prior to executing the join and freed after the query is done.
• Only columns of interest to the join are stored in the join buffer, not whole rows.
For the example join described previously for the NLJ algorithm (without buffering), the join is done as
follow using join buffering:
for each row in t1 matching range {
for each row in t2 matching reference key {
store used columns from t1, t2 in join buffer
if buffer is full {
for each row in t3 {
for each t1, t2 combination in join buffer {
if row satisfies join conditions,
send to client
}
}
empty buffer
}
}
}
if buffer is not empty {
for each row in t3 {
for each t1, t2 combination in join buffer {
if row satisfies join conditions,
send to client
}
}
}

If S is the size of each stored t1, t2 combination is the join buffer and C is the number of combinations
in the buffer, the number of times table t3 is scanned is:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

(S * C)/join_buffer_size + 1

The number of t3 scans decreases as the value of join_buffer_size increases, up to the point
when join_buffer_size is large enough to hold all previous row combinations. At that point, there
is no speed to be gained by making it larger.

8.2.1.9 Nested Join Optimization
As of MySQL 5.0.1, the syntax for expressing joins permits nested joins. The following discussion
refers to the join syntax described in Section 13.2.8.2, “JOIN Syntax”.
The syntax of table_factor is extended in comparison with the SQL Standard. The latter accepts
only table_reference, not a list of them inside a pair of parentheses. This is a conservative
extension if we consider each comma in a list of table_reference items as equivalent to an inner
join. For example:
SELECT * FROM t1 LEFT JOIN (t2, t3, t4)
ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)

is equivalent to:
SELECT * FROM t1 LEFT JOIN (t2 CROSS JOIN t3 CROSS JOIN t4)
ON (t2.a=t1.a AND t3.b=t1.b AND t4.c=t1.c)

In MySQL, CROSS JOIN is a syntactic equivalent to INNER JOIN (they can replace each other). In
standard SQL, they are not equivalent. INNER JOIN is used with an ON clause; CROSS JOIN is used
otherwise.
In versions of MySQL prior to 5.0.1, parentheses in table_references were just omitted and all
join operations were grouped to the left. In general, parentheses can be ignored in join expressions
containing only inner join operations.
After removing parentheses and grouping operations to the left, the join expression:
t1 LEFT JOIN (t2 LEFT JOIN t3 ON t2.b=t3.b OR t2.b IS NULL)
ON t1.a=t2.a

transforms into the expression:
(t1 LEFT JOIN t2 ON t1.a=t2.a) LEFT JOIN t3
ON t2.b=t3.b OR t2.b IS NULL

Yet, the two expressions are not equivalent. To see this, suppose that the tables t1, t2, and t3 have
the following state:
• Table t1 contains rows (1), (2)
• Table t2 contains row (1,101)
• Table t3 contains row (101)
In this case, the first expression returns a result set including the rows (1,1,101,101),
(2,NULL,NULL,NULL), whereas the second expression returns the rows (1,1,101,101),
(2,NULL,NULL,101):
mysql> SELECT *
-> FROM t1
->
LEFT JOIN
->
(t2 LEFT JOIN t3 ON t2.b=t3.b OR t2.b IS NULL)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

->
ON t1.a=t2.a;
+------+------+------+------+
| a
| a
| b
| b
|
+------+------+------+------+
|
1 |
1 | 101 | 101 |
|
2 | NULL | NULL | NULL |
+------+------+------+------+
mysql> SELECT *
-> FROM (t1 LEFT JOIN t2 ON t1.a=t2.a)
->
LEFT JOIN t3
->
ON t2.b=t3.b OR t2.b IS NULL;
+------+------+------+------+
| a
| a
| b
| b
|
+------+------+------+------+
|
1 |
1 | 101 | 101 |
|
2 | NULL | NULL | 101 |
+------+------+------+------+

In the following example, an outer join operation is used together with an inner join operation:
t1 LEFT JOIN (t2, t3) ON t1.a=t2.a

That expression cannot be transformed into the following expression:
t1 LEFT JOIN t2 ON t1.a=t2.a, t3.

For the given table states, the two expressions return different sets of rows:
mysql> SELECT *
-> FROM t1 LEFT JOIN (t2, t3) ON t1.a=t2.a;
+------+------+------+------+
| a
| a
| b
| b
|
+------+------+------+------+
|
1 |
1 | 101 | 101 |
|
2 | NULL | NULL | NULL |
+------+------+------+------+
mysql> SELECT *
-> FROM t1 LEFT JOIN t2 ON t1.a=t2.a, t3;
+------+------+------+------+
| a
| a
| b
| b
|
+------+------+------+------+
|
1 |
1 | 101 | 101 |
|
2 | NULL | NULL | 101 |
+------+------+------+------+

Therefore, if we omit parentheses in a join expression with outer join operators, we might change the
result set for the original expression.
More exactly, we cannot ignore parentheses in the right operand of the left outer join operation and in
the left operand of a right join operation. In other words, we cannot ignore parentheses for the inner
table expressions of outer join operations. Parentheses for the other operand (operand for the outer
table) can be ignored.
The following expression:
(t1,t2) LEFT JOIN t3 ON P(t2.b,t3.b)

is equivalent to this expression:
t1, t2 LEFT JOIN t3 ON P(t2.b,t3.b)

for any tables t1,t2,t3 and any condition P over attributes t2.b and t3.b.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

Whenever the order of execution of the join operations in a join expression (join_table) is not from
left to right, we talk about nested joins. Consider the following queries:
SELECT * FROM t1 LEFT JOIN (t2 LEFT JOIN t3 ON t2.b=t3.b) ON t1.a=t2.a
WHERE t1.a > 1
SELECT * FROM t1 LEFT JOIN (t2, t3) ON t1.a=t2.a
WHERE (t2.b=t3.b OR t2.b IS NULL) AND t1.a > 1

Those queries are considered to contain these nested joins:
t2 LEFT JOIN t3 ON t2.b=t3.b
t2, t3

The nested join is formed in the first query with a left join operation, whereas in the second query it is
formed with an inner join operation.
In the first query, the parentheses can be omitted: The grammatical structure of the join expression will
dictate the same order of execution for join operations. For the second query, the parentheses cannot
be omitted, although the join expression here can be interpreted unambiguously without them. (In our
extended syntax the parentheses in (t2, t3) of the second query are required, although theoretically
the query could be parsed without them: We still would have unambiguous syntactical structure for the
query because LEFT JOIN and ON would play the role of the left and right delimiters for the expression
(t2,t3).)
The preceding examples demonstrate these points:
• For join expressions involving only inner joins (and not outer joins), parentheses can be removed.
You can remove parentheses and evaluate left to right (or, in fact, you can evaluate the tables in any
order).
• The same is not true, in general, for outer joins or for outer joins mixed with inner joins. Removal of
parentheses may change the result.
Queries with nested outer joins are executed in the same pipeline manner as queries with inner joins.
More exactly, a variation of the nested-loop join algorithm is exploited. Recall by what algorithmic
schema the nested-loop join executes a query. Suppose that we have a join query over 3 tables
T1,T2,T3 of the form:
SELECT * FROM T1 INNER JOIN T2 ON P1(T1,T2)
INNER JOIN T3 ON P2(T2,T3)
WHERE P(T1,T2,T3).

Here, P1(T1,T2) and P2(T3,T3) are some join conditions (on expressions), whereas P(T1,T2,T3)
is a condition over columns of tables T1,T2,T3.
The nested-loop join algorithm would execute this query in the following manner:
FOR each row t1 in T1 {
FOR each row t2 in T2 such that P1(t1,t2) {
FOR each row t3 in T3 such that P2(t2,t3) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
}
}
}

The notation t1||t2||t3 means “a row constructed by concatenating the columns of rows t1,
t2, and t3.” In some of the following examples, NULL where a row name appears means that NULL
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

is used for each column of that row. For example, t1||t2||NULL means “a row constructed by
concatenating the columns of rows t1 and t2, and NULL for each column of t3.”
Now let's consider a query with nested outer joins:
SELECT * FROM T1 LEFT JOIN
(T2 LEFT JOIN T3 ON P2(T2,T3))
ON P1(T1,T2)
WHERE P(T1,T2,T3).

For this query, we modify the nested-loop pattern to get:
FOR each row t1 in T1 {
BOOL f1:=FALSE;
FOR each row t2 in T2 such that P1(t1,t2) {
BOOL f2:=FALSE;
FOR each row t3 in T3 such that P2(t2,t3) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
f2=TRUE;
f1=TRUE;
}
IF (!f2) {
IF P(t1,t2,NULL) {
t:=t1||t2||NULL; OUTPUT t;
}
f1=TRUE;
}
}
IF (!f1) {
IF P(t1,NULL,NULL) {
t:=t1||NULL||NULL; OUTPUT t;
}
}
}

In general, for any nested loop for the first inner table in an outer join operation, a flag is introduced that
is turned off before the loop and is checked after the loop. The flag is turned on when for the current
row from the outer table a match from the table representing the inner operand is found. If at the end of
the loop cycle the flag is still off, no match has been found for the current row of the outer table. In this
case, the row is complemented by NULL values for the columns of the inner tables. The result row is
passed to the final check for the output or into the next nested loop, but only if the row satisfies the join
condition of all embedded outer joins.
In our example, the outer join table expressed by the following expression is embedded:
(T2 LEFT JOIN T3 ON P2(T2,T3))

For the query with inner joins, the optimizer could choose a different order of nested loops, such as this
one:
FOR each row t3 in T3 {
FOR each row t2 in T2 such that P2(t2,t3) {
FOR each row t1 in T1 such that P1(t1,t2) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
}
}
}

For the queries with outer joins, the optimizer can choose only such an order where loops for outer
tables precede loops for inner tables. Thus, for our query with outer joins, only one nesting order is
possible. For the following query, the optimizer will evaluate two different nestings:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

SELECT * T1 LEFT JOIN (T2,T3) ON P1(T1,T2) AND P2(T1,T3)
WHERE P(T1,T2,T3)

The nestings are these:
FOR each row t1 in T1 {
BOOL f1:=FALSE;
FOR each row t2 in T2 such that P1(t1,t2) {
FOR each row t3 in T3 such that P2(t1,t3) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
f1:=TRUE
}
}
IF (!f1) {
IF P(t1,NULL,NULL) {
t:=t1||NULL||NULL; OUTPUT t;
}
}
}

and:
FOR each row t1 in T1 {
BOOL f1:=FALSE;
FOR each row t3 in T3 such that P2(t1,t3) {
FOR each row t2 in T2 such that P1(t1,t2) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
f1:=TRUE
}
}
IF (!f1) {
IF P(t1,NULL,NULL) {
t:=t1||NULL||NULL; OUTPUT t;
}
}
}

In both nestings, T1 must be processed in the outer loop because it is used in an outer join. T2 and T3
are used in an inner join, so that join must be processed in the inner loop. However, because the join is
an inner join, T2 and T3 can be processed in either order.
When discussing the nested-loop algorithm for inner joins, we omitted some details whose impact
on the performance of query execution may be huge. We did not mention so-called “pushed-down”
conditions. Suppose that our WHERE condition P(T1,T2,T3) can be represented by a conjunctive
formula:
P(T1,T2,T2) = C1(T1) AND C2(T2) AND C3(T3).

In this case, MySQL actually uses the following nested-loop schema for the execution of the query with
inner joins:
FOR each row t1 in T1 such that C1(t1) {
FOR each row t2 in T2 such that P1(t1,t2) AND C2(t2) {
FOR each row t3 in T3 such that P2(t2,t3) AND C3(t3) {
IF P(t1,t2,t3) {
t:=t1||t2||t3; OUTPUT t;
}
}
}
}

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

You see that each of the conjuncts C1(T1), C2(T2), C3(T3) are pushed out of the most inner loop to
the most outer loop where it can be evaluated. If C1(T1) is a very restrictive condition, this condition
pushdown may greatly reduce the number of rows from table T1 passed to the inner loops. As a result,
the execution time for the query may improve immensely.
For a query with outer joins, the WHERE condition is to be checked only after it has been found that
the current row from the outer table has a match in the inner tables. Thus, the optimization of pushing
conditions out of the inner nested loops cannot be applied directly to queries with outer joins. Here we
have to introduce conditional pushed-down predicates guarded by the flags that are turned on when a
match has been encountered.
For our example with outer joins with:
P(T1,T2,T3)=C1(T1) AND C(T2) AND C3(T3)

the nested-loop schema using guarded pushed-down conditions looks like this:
FOR each row t1 in T1 such that C1(t1) {
BOOL f1:=FALSE;
FOR each row t2 in T2
such that P1(t1,t2) AND (f1?C2(t2):TRUE) {
BOOL f2:=FALSE;
FOR each row t3 in T3
such that P2(t2,t3) AND (f1&&f2?C3(t3):TRUE) {
IF (f1&&f2?TRUE:(C2(t2) AND C3(t3))) {
t:=t1||t2||t3; OUTPUT t;
}
f2=TRUE;
f1=TRUE;
}
IF (!f2) {
IF (f1?TRUE:C2(t2) && P(t1,t2,NULL)) {
t:=t1||t2||NULL; OUTPUT t;
}
f1=TRUE;
}
}
IF (!f1 && P(t1,NULL,NULL)) {
t:=t1||NULL||NULL; OUTPUT t;
}
}

In general, pushed-down predicates can be extracted from join conditions such as P1(T1,T2) and
P(T2,T3). In this case, a pushed-down predicate is guarded also by a flag that prevents checking the
predicate for the NULL-complemented row generated by the corresponding outer join operation.
Access by key from one inner table to another in the same nested join is prohibited if it is induced
by a predicate from the WHERE condition. (We could use conditional key access in this case, but this
technique is not employed yet in MySQL 5.0.)

8.2.1.10 Outer Join Simplification
Table expressions in the FROM clause of a query are simplified in many cases.
At the parser stage, queries with right outer joins operations are converted to equivalent queries
containing only left join operations. In the general case, the conversion is performed according to the
following rule:
(T1, ...) RIGHT JOIN (T2,...) ON P(T1,...,T2,...) =
(T2, ...) LEFT JOIN (T1,...) ON P(T1,...,T2,...)

All inner join expressions of the form T1 INNER JOIN T2 ON P(T1,T2) are replaced by the list
T1,T2, P(T1,T2) being joined as a conjunct to the WHERE condition (or to the join condition of the
embedding join, if there is any).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

When the optimizer evaluates plans for join queries with outer join operation, it takes into consideration
only the plans where, for each such operation, the outer tables are accessed before the inner tables.
The optimizer options are limited because only such plans enables us to execute queries with outer
joins operations by the nested loop schema.
Suppose that we have a query of the form:
SELECT * T1 LEFT JOIN T2 ON P1(T1,T2)
WHERE P(T1,T2) AND R(T2)

with R(T2) narrowing greatly the number of matching rows from table T2. If we executed the query as
it is, the optimizer would have no other choice besides to access table T1 before table T2 that may lead
to a very inefficient execution plan.
Fortunately, MySQL converts such a query into a query without an outer join operation if the WHERE
condition is null-rejected. A condition is called null-rejected for an outer join operation if it evaluates to
FALSE or to UNKNOWN for any NULL-complemented row built for the operation.
Thus, for this outer join:
T1 LEFT JOIN T2 ON T1.A=T2.A

Conditions such as these are null-rejected:
T2.B
T2.B
T2.C
T2.B

IS NOT NULL,
> 3,
<= T1.C,
< 2 OR T2.C > 1

Conditions such as these are not null-rejected:
T2.B IS NULL,
T1.B < 3 OR T2.B IS NOT NULL,
T1.B < 3 OR T2.B > 3

The general rules for checking whether a condition is null-rejected for an outer join operation are
simple. A condition is null-rejected in the following cases:
• If it is of the form A IS NOT NULL, where A is an attribute of any of the inner tables
• If it is a predicate containing a reference to an inner table that evaluates to UNKNOWN when one of its
arguments is NULL
• If it is a conjunction containing a null-rejected condition as a conjunct
• If it is a disjunction of null-rejected conditions
A condition can be null-rejected for one outer join operation in a query and not null-rejected for another.
In the query:
SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
LEFT JOIN T3 ON T3.B=T1.B
WHERE T3.C > 0

the WHERE condition is null-rejected for the second outer join operation but is not null-rejected for the
first one.
If the WHERE condition is null-rejected for an outer join operation in a query, the outer join operation is
replaced by an inner join operation.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

For example, the preceding query is replaced with the query:
SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
INNER JOIN T3 ON T3.B=T1.B
WHERE T3.C > 0

For the original query, the optimizer would evaluate plans compatible with only one access order
T1,T2,T3. For the replacing query, it additionally considers the access sequence T3,T1,T2.
A conversion of one outer join operation may trigger a conversion of another. Thus, the query:
SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
LEFT JOIN T3 ON T3.B=T2.B
WHERE T3.C > 0

will be first converted to the query:
SELECT * FROM T1 LEFT JOIN T2 ON T2.A=T1.A
INNER JOIN T3 ON T3.B=T2.B
WHERE T3.C > 0

which is equivalent to the query:
SELECT * FROM (T1 LEFT JOIN T2 ON T2.A=T1.A), T3
WHERE T3.C > 0 AND T3.B=T2.B

Now the remaining outer join operation can be replaced by an inner join, too, because the condition
T3.B=T2.B is null-rejected and we get a query without outer joins at all:
SELECT * FROM (T1 INNER JOIN T2 ON T2.A=T1.A), T3
WHERE T3.C > 0 AND T3.B=T2.B

Sometimes we succeed in replacing an embedded outer join operation, but cannot convert the
embedding outer join. The following query:
SELECT * FROM T1 LEFT JOIN
(T2 LEFT JOIN T3 ON T3.B=T2.B)
ON T2.A=T1.A
WHERE T3.C > 0

is converted to:
SELECT * FROM T1 LEFT JOIN
(T2 INNER JOIN T3 ON T3.B=T2.B)
ON T2.A=T1.A
WHERE T3.C > 0,

That can be rewritten only to the form still containing the embedding outer join operation:
SELECT * FROM T1 LEFT JOIN
(T2,T3)
ON (T2.A=T1.A AND T3.B=T2.B)
WHERE T3.C > 0.

When trying to convert an embedded outer join operation in a query, we must take into account the join
condition for the embedding outer join together with the WHERE condition. In the query:
SELECT * FROM T1 LEFT JOIN

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

(T2 LEFT JOIN T3 ON T3.B=T2.B)
ON T2.A=T1.A AND T3.C=T1.C
WHERE T3.D > 0 OR T1.D > 0

the WHERE condition is not null-rejected for the embedded outer join, but the join condition of the
embedding outer join T2.A=T1.A AND T3.C=T1.C is null-rejected. So the query can be converted to:
SELECT * FROM T1 LEFT JOIN
(T2, T3)
ON T2.A=T1.A AND T3.C=T1.C AND T3.B=T2.B
WHERE T3.D > 0 OR T1.D > 0

The algorithm that converts outer join operations into inner joins was implemented in full measure, as it
has been described here, in MySQL 5.0.1. MySQL 4.1 performs only some simple conversions.

8.2.1.11 ORDER BY Optimization
In some cases, MySQL can use an index to satisfy an ORDER BY clause without doing extra sorting.
The index can also be used even if the ORDER BY does not match the index exactly, as long as all
unused portions of the index and all extra ORDER BY columns are constants in the WHERE clause. The
following queries use the index to resolve the ORDER BY part:
SELECT * FROM t1
ORDER BY key_part1,key_part2,... ;
SELECT * FROM t1
WHERE key_part1 = constant
ORDER BY key_part2;
SELECT * FROM t1
ORDER BY key_part1 DESC, key_part2 DESC;
SELECT * FROM t1
WHERE key_part1 = 1
ORDER BY key_part1 DESC, key_part2 DESC;
SELECT * FROM t1
WHERE key_part1 > constant
ORDER BY key_part1 ASC;
SELECT * FROM t1
WHERE key_part1 < constant
ORDER BY key_part1 DESC;
SELECT * FROM t1
WHERE key_part1 = constant1 AND key_part2 > constant2
ORDER BY key_part2;

In some cases, MySQL cannot use indexes to resolve the ORDER BY, although it still uses indexes to
find the rows that match the WHERE clause. These cases include the following:
• The query uses ORDER BY on different indexes:
SELECT * FROM t1 ORDER BY key1, key2;

• The query uses ORDER BY on nonconsecutive parts of an index:
SELECT * FROM t1 WHERE key2=constant ORDER BY key_part2;

• The query mixes ASC and DESC:
SELECT * FROM t1 ORDER BY key_part1 DESC, key_part2 ASC;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

• The index used to fetch the rows differs from the one used in the ORDER BY:
SELECT * FROM t1 WHERE key2=constant ORDER BY key1;

• The query uses ORDER BY with an expression that includes terms other than the index column
name:
SELECT * FROM t1 ORDER BY ABS(key);
SELECT * FROM t1 ORDER BY -key;

• The query joins many tables, and the columns in the ORDER BY are not all from the first nonconstant
table that is used to retrieve rows. (This is the first table in the EXPLAIN output that does not have a
const join type.)
• The query has different ORDER BY and GROUP BY expressions.
• There is an index on only a prefix of a column named in the ORDER BY clause. In this case, the index
cannot be used to fully resolve the sort order. For example, if only the first 10 bytes of a CHAR(20)
column are indexed, the index cannot distinguish values past the 10th byte and a filesort will be
needed.
• The index does not store rows in order. For example, this is true for a HASH index in a MEMORY table.
Availability of an index for sorting may be affected by the use of column aliases. Suppose that the
column t1.a is indexed. In this statement, the name of the column in the select list is a. It refers to
t1.a, so for the reference to a in the ORDER BY, the index can be used:
SELECT a FROM t1 ORDER BY a;

In this statement, the name of the column in the select list is also a, but it is the alias name. It refers to
ABS(a), so for the reference to a in the ORDER BY, the index cannot be used:
SELECT ABS(a) AS a FROM t1 ORDER BY a;

In the following statement, the ORDER BY refers to a name that is not the name of a column in the
select list. But there is a column in t1 named a, so the ORDER BY uses that and the index can be
used. (The resulting sort order may be completely different from the order for ABS(a), of course.)
SELECT ABS(a) AS b FROM t1 ORDER BY a;

By default, MySQL sorts all GROUP BY col1, col2, ... queries as if you specified ORDER BY
col1, col2, ... in the query as well. If you include an explicit ORDER BY clause that contains the
same column list, MySQL optimizes it away without any speed penalty, although the sorting still occurs.
If a query includes GROUP BY but you want to avoid the overhead of sorting the result, you can
suppress sorting by specifying ORDER BY NULL. For example:
INSERT INTO foo
SELECT a, COUNT(*) FROM bar GROUP BY a ORDER BY NULL;

The optimizer may still choose to use sorting to implement grouping operations. ORDER BY NULL
suppresses sorting of the result, not prior sorting done by grouping operations to determine the result.
With EXPLAIN SELECT ... ORDER BY, you can check whether MySQL can use indexes to resolve
the query. It cannot if you see Using filesort in the Extra column. See Section 8.8.1, “Optimizing
Queries with EXPLAIN”. Filesort uses a fixed-length row-storage format similar to that used by the
MEMORY storage engine. Variable-length types such as VARCHAR are stored using a fixed length.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

MySQL has two filesort algorithms for sorting and retrieving results. The original method uses
only the ORDER BY columns. The modified method uses not just the ORDER BY columns, but all the
columns referenced by the query.
The optimizer selects which filesort algorithm to use. It normally uses the modified algorithm
except when BLOB or TEXT columns are involved, in which case it uses the original algorithm. For both
algorithms, the sort buffer size is the sort_buffer_size system variable value.
The original filesort algorithm works as follows:
1. Read all rows according to key or by table scanning. Skip rows that do not match the WHERE
clause.
2. For each row, store in the sort buffer a tuple consisting of a pair of values (the sort key value and
the row ID).
3. If all pairs fit into the sort buffer, no temporary file is created. Otherwise, when the sort buffer
becomes full, run a qsort (quicksort) on it in memory and write it to a temporary file. Save a pointer
to the sorted block.
4. Repeat the preceding steps until all rows have been read.
5. Do a multi-merge of up to MERGEBUFF (7) regions to one block in another temporary file. Repeat
until all blocks from the first file are in the second file.
6. Repeat the following until there are fewer than MERGEBUFF2 (15) blocks left.
7. On the last multi-merge, only the row ID (the last part of the value pair) is written to a result file.
8. Read the rows in sorted order using the row IDs in the result file. To optimize this, read in a large
block of row IDs, sort them, and use them to read the rows in sorted order into a row buffer. The
row buffer size is the read_rnd_buffer_size system variable value. The code for this step is in
the sql/records.cc source file.
One problem with this approach is that it reads rows twice: One time during WHERE clause evaluation,
and again after sorting the value pairs. And even if the rows were accessed successively the first time
(for example, if a table scan is done), the second time they are accessed randomly. (The sort keys are
ordered, but the row positions are not.)
The modified filesort algorithm incorporates an optimization to avoid reading the rows twice: It
records the sort key value, but instead of the row ID, it records the columns referenced by the query.
The modified filesort algorithm works like this:
1. Read the rows that match the WHERE clause.
2. For each row, store in the sort buffer a tuple consisting of the sort key value and the columns
referenced by the query.
3. When the sort buffer becomes full, sort the tuples by sort key value in memory and write it to a
temporary file.
4. After merge-sorting the temporary file, retrieve the rows in sorted order, but read the columns
required by the query directly from the sorted tuples rather than by accessing the table a second
time.
The tuples used by the modified filesort algorithm are longer than the pairs used by the original
algorithm, and fewer of them fit in the sort buffer. As a result, it is possible for the extra I/O to make
the modified approach slower, not faster. To avoid a slowdown, the optimizer uses the modified
algorithm only if the total size of the extra columns in the sort tuple does not exceed the value of the
max_length_for_sort_data system variable. (A symptom of setting the value of this variable too
high is a combination of high disk activity and low CPU activity.)
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

If a filesort is done, EXPLAIN output includes Using filesort in the Extra column.
Suppose that a table t1 has four VARCHAR columns a, b, c, and d and that the optimizer uses
filesort for this query:
SELECT * FROM t1 ORDER BY a, b;

The query sorts by a and b, but returns all columns, so the columns referenced by the query are a,
b, c, and d. Depending on which filesort algorithm the optimizer chooses, the query executes as
follows:
For the original algorithm, sort buffer tuples have these contents:
(fixed size a value, fixed size b value,
row ID into t1)

The optimizer sorts on the fixed size values. After sorting, the optimizer reads the tuples in order and
uses the row ID in each tuple to read rows from t1 to obtain the select list column values.
For the modified algorithm, sort buffer tuples have these contents:
(fixed size a value, fixed size b value,
a value, b value, c value, d value)

The optimizer sorts on the fixed size values. After sorting, the optimizer reads the tuples in order and
uses the values for a, b, c, and d to obtain the select list column values without reading t1 again.
For slow queries for which filesort is not used, try lowering max_length_for_sort_data to a
value that is appropriate to trigger a filesort.
To increase ORDER BY speed, check whether you can get MySQL to use indexes rather than an extra
sorting phase. If this is not possible, you can try the following strategies:
• Increase the sort_buffer_size variable value.
• Increase the read_rnd_buffer_size variable value.
• Use less RAM per row by declaring columns only as large as they need to be to hold the values
stored in them. For example, CHAR(16) is better than CHAR(200) if values never exceed 16
characters.
• Change the tmpdir system variable to point to a dedicated file system with large amounts of free
space. The variable value can list several paths that are used in round-robin fashion; you can use
this feature to spread the load across several directories. Paths should be separated by colon
characters (“:”) on Unix and semicolon characters (“;”) on Windows, NetWare, and OS/2. The paths
should name directories in file systems located on different physical disks, not different partitions on
the same disk.

8.2.1.12 GROUP BY Optimization
The most general way to satisfy a GROUP BY clause is to scan the whole table and create a new
temporary table where all rows from each group are consecutive, and then use this temporary table
to discover groups and apply aggregate functions (if any). In some cases, MySQL is able to do much
better than that and to avoid creation of temporary tables by using index access.
The most important preconditions for using indexes for GROUP BY are that all GROUP BY columns
reference attributes from the same index, and that the index stores its keys in order (for example, this
is a BTREE index and not a HASH index). Whether use of temporary tables can be replaced by index
access also depends on which parts of an index are used in a query, the conditions specified for these
parts, and the selected aggregate functions.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

There are two ways to execute a GROUP BY query through index access, as detailed in the following
sections. In the first method, the grouping operation is applied together with all range predicates (if
any). The second method first performs a range scan, and then groups the resulting tuples.
In MySQL, GROUP BY is used for sorting, so the server may also apply ORDER BY optimizations to
grouping. See Section 8.2.1.11, “ORDER BY Optimization”.

Loose Index Scan
The most efficient way to process GROUP BY is when an index is used to directly retrieve the grouping
columns. With this access method, MySQL uses the property of some index types that the keys are
ordered (for example, BTREE). This property enables use of lookup groups in an index without having
to consider all keys in the index that satisfy all WHERE conditions. This access method considers only
a fraction of the keys in an index, so it is called a loose index scan. When there is no WHERE clause, a
loose index scan reads as many keys as the number of groups, which may be a much smaller number
than that of all keys. If the WHERE clause contains range predicates (see the discussion of the range
join type in Section 8.8.1, “Optimizing Queries with EXPLAIN”), a loose index scan looks up the first
key of each group that satisfies the range conditions, and again reads the least possible number of
keys. This is possible under the following conditions:
• The query is over a single table.
• The GROUP BY names only columns that form a leftmost prefix of the index and no other columns.
(If, instead of GROUP BY, the query has a DISTINCT clause, all distinct attributes refer to columns
that form a leftmost prefix of the index.) For example, if a table t1 has an index on (c1,c2,c3),
loose index scan is applicable if the query has GROUP BY c1, c2,. It is not applicable if the query
has GROUP BY c2, c3 (the columns are not a leftmost prefix) or GROUP BY c1, c2, c4 (c4 is
not in the index).
• The only aggregate functions used in the select list (if any) are MIN() and MAX(), and all of them
refer to the same column. The column must be in the index and must follow the columns in the
GROUP BY.
• Any other parts of the index than those from the GROUP BY referenced in the query must be
constants (that is, they must be referenced in equalities with constants), except for the argument of
MIN() or MAX() functions.
• For columns in the index, full column values must be indexed, not just a prefix. For example, with c1
VARCHAR(20), INDEX (c1(10)), the index cannot be used for loose index scan.
If loose index scan is applicable to a query, the EXPLAIN output shows Using index for groupby in the Extra column.
Assume that there is an index idx(c1,c2,c3) on table t1(c1,c2,c3,c4). The loose index scan
access method can be used for the following queries:
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT
SELECT

c1, c2 FROM t1 GROUP BY c1, c2;
DISTINCT c1, c2 FROM t1;
c1, MIN(c2) FROM t1 GROUP BY c1;
c1, c2 FROM t1 WHERE c1 < const GROUP BY c1, c2;
MAX(c3), MIN(c3), c1, c2 FROM t1 WHERE c2 > const GROUP BY c1, c2;
c2 FROM t1 WHERE c1 < const GROUP BY c1, c2;
c1, c2 FROM t1 WHERE c3 = const GROUP BY c1, c2;

The following queries cannot be executed with this quick select method, for the reasons given:
• There are aggregate functions other than MIN() or MAX():
SELECT c1, SUM(c2) FROM t1 GROUP BY c1;

• The columns in the GROUP BY clause do not form a leftmost prefix of the index:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

SELECT c1, c2 FROM t1 GROUP BY c2, c3;

• The query refers to a part of a key that comes after the GROUP BY part, and for which there is no
equality with a constant:
SELECT c1, c3 FROM t1 GROUP BY c1, c2;

Were the query to include WHERE c3 = const, loose index scan could be used.

Tight Index Scan
A tight index scan may be either a full index scan or a range index scan, depending on the query
conditions.
When the conditions for a loose index scan are not met, it still may be possible to avoid creation of
temporary tables for GROUP BY queries. If there are range conditions in the WHERE clause, this method
reads only the keys that satisfy these conditions. Otherwise, it performs an index scan. Because this
method reads all keys in each range defined by the WHERE clause, or scans the whole index if there
are no range conditions, we term it a tight index scan. With a tight index scan, the grouping operation is
performed only after all keys that satisfy the range conditions have been found.
For this method to work, it is sufficient that there is a constant equality condition for all columns in
a query referring to parts of the key coming before or in between parts of the GROUP BY key. The
constants from the equality conditions fill in any “gaps” in the search keys so that it is possible to form
complete prefixes of the index. These index prefixes then can be used for index lookups. If we require
sorting of the GROUP BY result, and it is possible to form search keys that are prefixes of the index,
MySQL also avoids extra sorting operations because searching with prefixes in an ordered index
already retrieves all the keys in order.
Assume that there is an index idx(c1,c2,c3) on table t1(c1,c2,c3,c4). The following queries
do not work with the loose index scan access method described earlier, but still work with the tight
index scan access method.
• There is a gap in the GROUP BY, but it is covered by the condition c2 = 'a':
SELECT c1, c2, c3 FROM t1 WHERE c2 = 'a' GROUP BY c1, c3;

• The GROUP BY does not begin with the first part of the key, but there is a condition that provides a
constant for that part:
SELECT c1, c2, c3 FROM t1 WHERE c1 = 'a' GROUP BY c2, c3;

8.2.1.13 DISTINCT Optimization
DISTINCT combined with ORDER BY needs a temporary table in many cases.
Because DISTINCT may use GROUP BY, learn how MySQL works with columns in ORDER BY or
HAVING clauses that are not part of the selected columns. See Section 12.16.3, “MySQL Handling of
GROUP BY”.
In most cases, a DISTINCT clause can be considered as a special case of GROUP BY. For example,
the following two queries are equivalent:
SELECT DISTINCT c1, c2, c3 FROM t1
WHERE c1 > const;
SELECT c1, c2, c3 FROM t1
WHERE c1 > const GROUP BY c1, c2, c3;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

Due to this equivalence, the optimizations applicable to GROUP BY queries can be also applied to
queries with a DISTINCT clause. Thus, for more details on the optimization possibilities for DISTINCT
queries, see Section 8.2.1.12, “GROUP BY Optimization”.
When combining LIMIT row_count with DISTINCT, MySQL stops as soon as it finds row_count
unique rows.
If you do not use columns from all tables named in a query, MySQL stops scanning any unused tables
as soon as it finds the first match. In the following case, assuming that t1 is used before t2 (which you
can check with EXPLAIN), MySQL stops reading from t2 (for any particular row in t1) when it finds the
first row in t2:
SELECT DISTINCT t1.a FROM t1, t2 where t1.a=t2.a;

8.2.1.14 Optimizing Subqueries with EXISTS Strategy
Certain optimizations are applicable to comparisons that use the IN operator to test subquery results
(or that use =ANY, which is equivalent). This section discusses these optimizations, particularly with
regard to the challenges that NULL values present. The last part of the discussion includes suggestions
on what you can do to help the optimizer.
Consider the following subquery comparison:
outer_expr IN (SELECT inner_expr FROM ... WHERE subquery_where)

MySQL evaluates queries “from outside to inside.” That is, it first obtains the value of the outer
expression outer_expr, and then runs the subquery and captures the rows that it produces.
A very useful optimization is to “inform” the subquery that the only rows of interest are those where the
inner expression inner_expr is equal to outer_expr. This is done by pushing down an appropriate
equality into the subquery's WHERE clause. That is, the comparison is converted to this:
EXISTS (SELECT 1 FROM ... WHERE subquery_where AND outer_expr=inner_expr)

After the conversion, MySQL can use the pushed-down equality to limit the number of rows that it must
examine when evaluating the subquery.
More generally, a comparison of N values to a subquery that returns N-value rows is subject to the
same conversion. If oe_i and ie_i represent corresponding outer and inner expression values, this
subquery comparison:
(oe_1, ..., oe_N) IN
(SELECT ie_1, ..., ie_N FROM ... WHERE subquery_where)

Becomes:
EXISTS (SELECT 1 FROM ... WHERE subquery_where
AND oe_1 = ie_1
AND ...
AND oe_N = ie_N)

The following discussion assumes a single pair of outer and inner expression values for simplicity.
The conversion just described has its limitations. It is valid only if we ignore possible NULL values. That
is, the “pushdown” strategy works as long as both of these two conditions are true:
• outer_expr and inner_expr cannot be NULL.
• You do not need to distinguish NULL from FALSE subquery results. (If the subquery is a part of an OR
or AND expression in the WHERE clause, MySQL assumes that you do not care.)
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

When either or both of those conditions do not hold, optimization is more complex.
Suppose that outer_expr is known to be a non-NULL value but the subquery does not produce a row
such that outer_expr = inner_expr. Then outer_expr IN (SELECT ...) evaluates as follows:
• NULL, if the SELECT produces any row where inner_expr is NULL
• FALSE, if the SELECT produces only non-NULL values or produces nothing
In this situation, the approach of looking for rows with outer_expr = inner_expr is no longer valid.
It is necessary to look for such rows, but if none are found, also look for rows where inner_expr is
NULL. Roughly speaking, the subquery can be converted to:
EXISTS (SELECT 1 FROM ... WHERE subquery_where AND
(outer_expr=inner_expr OR inner_expr IS NULL))

The need to evaluate the extra IS NULL condition is why MySQL has the ref_or_null access
method:
mysql> EXPLAIN
-> SELECT outer_expr IN (SELECT t2.maybe_null_key
->
FROM t2, t3 WHERE ...)
-> FROM t1;
*************************** 1. row ***************************
id: 1
select_type: PRIMARY
table: t1
...
*************************** 2. row ***************************
id: 2
select_type: DEPENDENT SUBQUERY
table: t2
type: ref_or_null
possible_keys: maybe_null_key
key: maybe_null_key
key_len: 5
ref: func
rows: 2
Extra: Using where; Using index
...

The unique_subquery and index_subquery subquery-specific access methods also have
“or NULL” variants. However, they are not visible in EXPLAIN output, so you must use EXPLAIN
EXTENDED followed by SHOW WARNINGS (note the checking NULL in the warning message):
mysql> EXPLAIN EXTENDED
-> SELECT outer_expr IN (SELECT maybe_null_key FROM t2) FROM t1\G
*************************** 1. row ***************************
id: 1
select_type: PRIMARY
table: t1
...
*************************** 2. row ***************************
id: 2
select_type: DEPENDENT SUBQUERY
table: t2
type: index_subquery
possible_keys: maybe_null_key
key: maybe_null_key
key_len: 5
ref: func
rows: 2
Extra: Using index
mysql> SHOW WARNINGS\G
*************************** 1. row ***************************

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

Level: Note
Code: 1003
Message: select (`test`.`t1`.`outer_expr`,
(((`test`.`t1`.`outer_expr`) in t2 on
maybe_null_key checking NULL))) AS `outer_expr IN (SELECT
maybe_null_key FROM t2)` from `test`.`t1`

The additional OR ... IS NULL condition makes query execution slightly more complicated (and
some optimizations within the subquery become inapplicable), but generally this is tolerable.
The situation is much worse when outer_expr can be NULL. According to the SQL interpretation of
NULL as “unknown value,” NULL IN (SELECT inner_expr ...) should evaluate to:
• NULL, if the SELECT produces any rows
• FALSE, if the SELECT produces no rows
For proper evaluation, it is necessary to be able to check whether the SELECT has produced any rows
at all, so outer_expr = inner_expr cannot be pushed down into the subquery. This is a problem,
because many real world subqueries become very slow unless the equality can be pushed down.
Essentially, there must be different ways to execute the subquery depending on the value of
outer_expr. In MySQL 5.0 before 5.0.36, the optimizer chose speed over distinguishing a NULL from
FALSE result, so for some queries, you might get a FALSE result rather than NULL.
As of MySQL 5.0.36, the optimizer chooses SQL compliance over speed, so it accounts for the
possibility that outer_expr might be NULL.
If outer_expr is NULL, to evaluate the following expression, it is necessary to run the SELECT to
determine whether it produces any rows:
NULL IN (SELECT inner_expr FROM ... WHERE subquery_where)

It is necessary to run the original SELECT here, without any pushed-down equalities of the kind
mentioned earlier.
On the other hand, when outer_expr is not NULL, it is absolutely essential that this comparison:
outer_expr IN (SELECT inner_expr FROM ... WHERE subquery_where)

be converted to this expression that uses a pushed-down condition:
EXISTS (SELECT 1 FROM ... WHERE subquery_where AND outer_expr=inner_expr)

Without this conversion, subqueries will be slow. To solve the dilemma of whether to push down or not
push down conditions into the subquery, the conditions are wrapped in “trigger” functions. Thus, an
expression of the following form:
outer_expr IN (SELECT inner_expr FROM ... WHERE subquery_where)

is converted into:
EXISTS (SELECT 1 FROM ... WHERE subquery_where
AND trigcond(outer_expr=inner_expr))

More generally, if the subquery comparison is based on several pairs of outer and inner expressions,
the conversion takes this comparison:
(oe_1, ..., oe_N) IN (SELECT ie_1, ..., ie_N FROM ... WHERE subquery_where)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

and converts it to this expression:
EXISTS (SELECT 1 FROM ... WHERE subquery_where
AND trigcond(oe_1=ie_1)
AND ...
AND trigcond(oe_N=ie_N)
)

Each trigcond(X) is a special function that evaluates to the following values:
• X when the “linked” outer expression oe_i is not NULL
• TRUE when the “linked” outer expression oe_i is NULL
Note
Trigger functions are not triggers of the kind that you create with CREATE
TRIGGER.
Equalities that are wrapped into trigcond() functions are not first class predicates for the query
optimizer. Most optimizations cannot deal with predicates that may be turned on and off at query
execution time, so they assume any trigcond(X) to be an unknown function and ignore it. At the
moment, triggered equalities can be used by those optimizations:
• Reference optimizations: trigcond(X=Y [OR Y IS NULL]) can be used to construct ref,
eq_ref, or ref_or_null table accesses.
• Index lookup-based subquery execution engines: trigcond(X=Y) can be used to construct
unique_subquery or index_subquery accesses.
• Table-condition generator: If the subquery is a join of several tables, the triggered condition will be
checked as soon as possible.
When the optimizer uses a triggered condition to create some kind of index lookup-based access
(as for the first two items of the preceding list), it must have a fallback strategy for the case when the
condition is turned off. This fallback strategy is always the same: Do a full table scan. In EXPLAIN
output, the fallback shows up as Full scan on NULL key in the Extra column:
mysql> EXPLAIN SELECT t1.col1,
-> t1.col1 IN (SELECT t2.key1 FROM t2 WHERE t2.col2=t1.col2) FROM t1\G
*************************** 1. row ***************************
id: 1
select_type: PRIMARY
table: t1
...
*************************** 2. row ***************************
id: 2
select_type: DEPENDENT SUBQUERY
table: t2
type: index_subquery
possible_keys: key1
key: key1
key_len: 5
ref: func
rows: 2
Extra: Using where; Full scan on NULL key

If you run EXPLAIN EXTENDED followed by SHOW WARNINGS, you can see the triggered condition:
*************************** 1. row ***************************
Level: Note
Code: 1003
Message: select `test`.`t1`.`col1` AS `col1`,

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

(`test`.`t1`.`col1`,
(((`test`.`t1`.`col1`) in t2
on key1 checking NULL
where (`test`.`t2`.`col2` = `test`.`t1`.`col2`) having
trigcond((`test`.`t2`.`key1`))))) AS
`t1.col1 IN (select t2.key1 from t2 where t2.col2=t1.col2)`
from `test`.`t1`

The use of triggered conditions has some performance implications. A NULL IN (SELECT ...)
expression now may cause a full table scan (which is slow) when it previously did not. This is the price
paid for correct results (the goal of the trigger-condition strategy was to improve compliance and not
speed).
For multiple-table subqueries, execution of NULL IN (SELECT ...) will be particularly slow because
the join optimizer does not optimize for the case where the outer expression is NULL. It assumes that
subquery evaluations with NULL on the left side are very rare, even if there are statistics that indicate
otherwise. On the other hand, if the outer expression might be NULL but never actually is, there is no
performance penalty.
To help the query optimizer better execute your queries, use these tips:
• Declare a column as NOT NULL if it really is. (This also helps other aspects of the optimizer by
simplifying condition testing for the column.)
• If you do not need to distinguish a NULL from FALSE subquery result, you can easily avoid the slow
execution path. Replace a comparison that looks like this:
outer_expr IN (SELECT inner_expr FROM ...)

with this expression:
(outer_expr IS NOT NULL) AND (outer_expr IN (SELECT inner_expr FROM ...))

Then NULL IN (SELECT ...) will never be evaluated because MySQL stops evaluating AND
parts as soon as the expression result is clear.

8.2.1.15 LIMIT Query Optimization
In some cases, MySQL handles a query differently when you are using LIMIT row_count and not
using HAVING:
• If you select only a few rows with LIMIT, MySQL uses indexes in some cases when normally it
would prefer to do a full table scan.
• If you combine LIMIT row_count with ORDER BY, MySQL ends the sorting as soon as it has
found the first row_count rows of the sorted result, rather than sorting the entire result. If ordering
is done by using an index, this is very fast. If a filesort must be done, all rows that match the query
without the LIMIT clause must be selected, and most or all of them must be sorted, before it can be
ascertained that the first row_count rows have been found. In either case, after the initial rows have
been found, there is no need to sort any remainder of the result set, and MySQL does not do so.
• If you combine LIMIT row_count with DISTINCT, MySQL stops as soon as it finds row_count
unique rows.
• In some cases, a GROUP BY can be resolved by reading the index in order (or doing a sort on
the index) and then calculating summaries until the index value changes. In this case, LIMIT
row_count does not calculate any unnecessary GROUP BY values.
• As soon as MySQL has sent the required number of rows to the client, it aborts the query unless
you are using SQL_CALC_FOUND_ROWS. The number of rows can then be retrieved with SELECT
FOUND_ROWS(). See Section 12.13, “Information Functions”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing SELECT Statements

• LIMIT 0 quickly returns an empty set. This can be useful for checking the validity of a query. When
using one of the MySQL APIs, it can also be employed for obtaining the types of the result columns.
This technique does not work with the mysql client program, which merely displays Empty set in
such cases. Instead, use SHOW COLUMNS or DESCRIBE for this purpose.
• When the server uses temporary tables to resolve the query, it uses the LIMIT row_count clause
to calculate how much space is required.

8.2.1.16 Row Constructor Expression Optimization
Row constructors permit simultaneous comparisons of multiple values. For example, these two
statements are semantically equivalent:
SELECT * FROM t1 WHERE (column1,column2) = (1,1);
SELECT * FROM t1 WHERE column1 = 1 AND column2 = 1;

In addition, the optimizer handles both expressions the same way.
The optimizer is less likely to use available indexes if the row constructor columns do not cover the
prefix of an index. Consider the following table, which has a primary key on (c1, c2, c3):
CREATE TABLE t1 (
c1 INT, c2 INT, c3 INT, c4 CHAR(100),
PRIMARY KEY(c1,c2,c3)
);

In this query, the WHERE clause uses all columns in the index. However, the row constructor itself does
not cover an index prefix, with the result that the optimizer uses only c1 (key_len=4, the size of c1):
mysql> EXPLAIN SELECT * FROM t1
-> WHERE c1=1 AND (c2,c3) > (1,1)\G
*************************** 1. row ***************************
id: 1
select_type: SIMPLE
table: t1
partitions: NULL
type: ref
possible_keys: PRIMARY
key: PRIMARY
key_len: 4
ref: const
rows: 3
Extra: Using where

In such cases, rewriting the row constructor expression using an equivalent nonconstructor expression
may result in more complete index use. For the given query, the row constructor and equivalent
nonconstructor expressions are:
(c2,c3) > (1,1)
c2 > 1 OR ((c2 = 1) AND (c3 > 1))

Rewriting the query to use the nonconstructor expression results in the optimizer using all three
columns in the index (key_len=12):
mysql> EXPLAIN SELECT * FROM t1
-> WHERE c1 = 1 AND (c2 > 1 OR ((c2 = 1) AND (c3 > 1)))\G
*************************** 1. row ***************************
id: 1
select_type: SIMPLE
table: t1
partitions: NULL

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing DML Statements

type:
possible_keys:
key:
key_len:
ref:
rows:
Extra:

range
PRIMARY
PRIMARY
12
NULL
3
Using where

Thus, for better results, avoid mixing row constructors with AND/OR expressions. Use one or the other.

8.2.1.17 How to Avoid Full Table Scans
The output from EXPLAIN shows ALL in the type column when MySQL uses a table scan to resolve a
query. This usually happens under the following conditions:
• The table is so small that it is faster to perform a table scan than to bother with a key lookup. This is
common for tables with fewer than 10 rows and a short row length.
• There are no usable restrictions in the ON or WHERE clause for indexed columns.
• You are comparing indexed columns with constant values and MySQL has calculated (based on
the index tree) that the constants cover too large a part of the table and that a table scan would be
faster. See Section 8.2.1.2, “How MySQL Optimizes WHERE Clauses”.
• You are using a key with low cardinality (many rows match the key value) through another column.
In this case, MySQL assumes that by using the key it probably will do many key lookups and that a
table scan would be faster.
For small tables, a table scan often is appropriate and the performance impact is negligible. For large
tables, try the following techniques to avoid having the optimizer incorrectly choose a table scan:
• Use ANALYZE TABLE tbl_name to update the key distributions for the scanned table. See
Section 13.7.2.1, “ANALYZE TABLE Syntax”.
• Use FORCE INDEX for the scanned table to tell MySQL that table scans are very expensive
compared to using the given index:
SELECT * FROM t1, t2 FORCE INDEX (index_for_column)
WHERE t1.col_name=t2.col_name;

See Section 8.9.2, “Index Hints”.
• Start mysqld with the --max-seeks-for-key=1000 option or use SET
max_seeks_for_key=1000 to tell the optimizer to assume that no key scan causes more than
1,000 key seeks. See Section 5.1.4, “Server System Variables”.

8.2.2 Optimizing DML Statements
This section explains how to speed up the data manipulation language (DML) statements, INSERT,
UPDATE, and DELETE. Traditional OLTP applications and modern web applications typically do many
small DML operations, where concurrency is vital. Data analysis and reporting applications typically
run DML operations that affect many rows at once, where the main considerations is the I/O to write
large amounts of data and keep indexes up-to-date. For inserting and updating large volumes of data
(known in the industry as ETL, for “extract-transform-load”), sometimes you use other SQL statements
or external commands, that mimic the effects of INSERT, UPDATE, and DELETE statements.

8.2.2.1 Speed of INSERT Statements
To optimize insert speed, combine many small operations into a single large operation. Ideally, you
make a single connection, send the data for many new rows at once, and delay all index updates and
consistency checking until the very end.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Database Privileges

The time required for inserting a row is determined by the following factors, where the numbers indicate
approximate proportions:
• Connecting: (3)
• Sending query to server: (2)
• Parsing query: (2)
• Inserting row: (1 × size of row)
• Inserting indexes: (1 × number of indexes)
• Closing: (1)
This does not take into consideration the initial overhead to open tables, which is done once for each
concurrently running query.
The size of the table slows down the insertion of indexes by log N, assuming B-tree indexes.
You can use the following methods to speed up inserts:
• If you are inserting many rows from the same client at the same time, use INSERT statements with
multiple VALUES lists to insert several rows at a time. This is considerably faster (many times faster
in some cases) than using separate single-row INSERT statements. If you are adding data to a
nonempty table, you can tune the bulk_insert_buffer_size variable to make data insertion
even faster. See Section 5.1.4, “Server System Variables”.
• When loading a table from a text file, use LOAD DATA INFILE. This is usually 20 times faster than
using INSERT statements. See Section 13.2.6, “LOAD DATA INFILE Syntax”.
• Take advantage of the fact that columns have default values. Insert values explicitly only when the
value to be inserted differs from the default. This reduces the parsing that MySQL must do and
improves the insert speed.
• See Section 8.5.2, “Bulk Data Loading for MyISAM Tables” for tips specific to MyISAM tables.

8.2.2.2 Speed of UPDATE Statements
An update statement is optimized like a SELECT query with the additional overhead of a write. The
speed of the write depends on the amount of data being updated and the number of indexes that are
updated. Indexes that are not changed do not get updated.
Another way to get fast updates is to delay updates and then do many updates in a row later.
Performing multiple updates together is much quicker than doing one at a time if you lock the table.
For a MyISAM table that uses dynamic row format, updating a row to a longer total length may
split the row. If you do this often, it is very important to use OPTIMIZE TABLE occasionally. See
Section 13.7.2.5, “OPTIMIZE TABLE Syntax”.

8.2.2.3 Speed of DELETE Statements
The time required to delete individual rows is exactly proportional to the number of indexes. To delete
rows more quickly, you can increase the size of the key cache by increasing the key_buffer_size
system variable. See Section 8.12.2, “Tuning Server Parameters”.
To delete all rows from a table, TRUNCATE TABLE tbl_name is faster than DELETE FROM
tbl_name. Truncate operations are not transaction-safe; an error occurs when attempting one in the
course of an active transaction or active table lock. See Section 13.1.21, “TRUNCATE TABLE Syntax”.

8.2.3 Optimizing Database Privileges
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Other Optimization Tips

The more complex your privilege setup, the more overhead applies to all SQL statements. Simplifying
the privileges established by GRANT statements enables MySQL to reduce permission-checking
overhead when clients execute statements. For example, if you do not grant any table-level or columnlevel privileges, the server need not ever check the contents of the tables_priv and columns_priv
tables. Similarly, if you place no resource limits on any accounts, the server does not have to perform
resource counting. If you have a very high statement-processing load, consider using a simplified grant
structure to reduce permission-checking overhead.

8.2.4 Other Optimization Tips
This section lists a number of miscellaneous tips for improving query processing speed:
• If your application makes several database requests to perform related updates, combining the
statements into a stored routine can help performance. Similarly, if your application computes a
single result based on several column values or large volumes of data, combining the computation
into a UDF (user-defined function) can help performance. The resulting fast database operations
are then available to be reused by other queries, applications, and even code written in different
programming languages. See Section 18.2, “Using Stored Routines (Procedures and Functions)”
and Section 21.2, “Adding New Functions to MySQL” for more information.
• To fix any compression issues that occur with ARCHIVE tables, use OPTIMIZE TABLE. See
Section 14.8, “The ARCHIVE Storage Engine”.
• If possible, classify reports as “live” or as “statistical”, where data needed for statistical reports is
created only from summary tables that are generated periodically from the live data.
• If you have data that does not conform well to a rows-and-columns table structure, you can pack and
store data into a BLOB column. In this case, you must provide code in your application to pack and
unpack information, but this might save I/O operations to read and write the sets of related values.
• With Web servers, store images and other binary assets as files, with the path name stored in the
database rather than the file itself. Most Web servers are better at caching files than database
contents, so using files is generally faster. (Although you must handle backups and storage issues
yourself in this case.)
• If you need really high speed, look at the low-level MySQL interfaces. For example, by accessing
the MySQL InnoDB or MyISAM storage engine directly, you could get a substantial speed increase
compared to using the SQL interface.
• Replication can provide a performance benefit for some operations. You can distribute client
retrievals among replication servers to split up the load. To avoid slowing down the master while
making backups, you can make backups using a slave server. See Chapter 16, Replication.

8.3 Optimization and Indexes
The best way to improve the performance of SELECT operations is to create indexes on one or more of
the columns that are tested in the query. The index entries act like pointers to the table rows, allowing
the query to quickly determine which rows match a condition in the WHERE clause, and retrieve the
other column values for those rows. All MySQL data types can be indexed.
Although it can be tempting to create an indexes for every possible column used in a query,
unnecessary indexes waste space and waste time for MySQL to determine which indexes to use.
Indexes also add to the cost of inserts, updates, and deletes because each index must be updated.
You must find the right balance to achieve fast queries using the optimal set of indexes.

8.3.1 How MySQL Uses Indexes
Indexes are used to find rows with specific column values quickly. Without an index, MySQL must
begin with the first row and then read through the entire table to find the relevant rows. The larger the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

How MySQL Uses Indexes

table, the more this costs. If the table has an index for the columns in question, MySQL can quickly
determine the position to seek to in the middle of the data file without having to look at all the data. This
is much faster than reading every row sequentially.
Most MySQL indexes (PRIMARY KEY, UNIQUE, INDEX, and FULLTEXT) are stored in B-trees.
Exceptions are that indexes on spatial data types use R-trees, and that MEMORY tables also support
hash indexes.
Strings are automatically prefix- and end-space compressed. See Section 13.1.8, “CREATE INDEX
Syntax”.
In general, indexes are used as described in the following discussion. Characteristics specific to hash
indexes (as used in MEMORY tables) are described in Section 8.3.8, “Comparison of B-Tree and Hash
Indexes”.
MySQL uses indexes for these operations:
• To find the rows matching a WHERE clause quickly.
• To eliminate rows from consideration. If there is a choice between multiple indexes, MySQL normally
uses the index that finds the smallest number of rows.
•

If the table has a multiple-column index, any leftmost prefix of the index can be used by the
optimizer to look up rows. For example, if you have a three-column index on (col1, col2,
col3), you have indexed search capabilities on (col1), (col1, col2), and (col1, col2,
col3). For more information, see Section 8.3.5, “Multiple-Column Indexes”.

• To retrieve rows from other tables when performing joins. MySQL can use indexes on columns
more efficiently if they are declared as the same type and size. In this context, VARCHAR and CHAR
are considered the same if they are declared as the same size. For example, VARCHAR(10) and
CHAR(10) are the same size, but VARCHAR(10) and CHAR(15) are not.
For comparisons between nonbinary string columns, both columns should use the same character
set. For example, comparing a utf8 column with a latin1 column precludes use of an index.
Comparison of dissimilar columns (comparing a string column to a temporal or numeric column, for
example) may prevent use of indexes if values cannot be compared directly without conversion. For
a given value such as 1 in the numeric column, it might compare equal to any number of values in
the string column such as '1', ' 1', '00001', or '01.e1'. This rules out use of any indexes for
the string column.
• To find the MIN() or MAX() value for a specific indexed column key_col. This is optimized by a
preprocessor that checks whether you are using WHERE key_part_N = constant on all key
parts that occur before key_col in the index. In this case, MySQL does a single key lookup for each
MIN() or MAX() expression and replaces it with a constant. If all expressions are replaced with
constants, the query returns at once. For example:
SELECT MIN(key_part2),MAX(key_part2)
FROM tbl_name WHERE key_part1=10;

• To sort or group a table if the sorting or grouping is done on a leftmost prefix of a usable index (for
example, ORDER BY key_part1, key_part2). If all key parts are followed by DESC, the key
is read in reverse order. See Section 8.2.1.11, “ORDER BY Optimization”, and Section 8.2.1.12,
“GROUP BY Optimization”.
• In some cases, a query can be optimized to retrieve values without consulting the data rows. If a
query uses from a table only columns that are included in some index, the selected values can be be
retrieved from the index tree for greater speed:
SELECT key_part3 FROM tbl_name

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Primary Keys

WHERE key_part1=1

Indexes are less important for queries on small tables, or big tables where report queries process most
or all of the rows. When a query needs to access most of the rows, reading sequentially is faster than
working through an index. Sequential reads minimize disk seeks, even if not all the rows are needed for
the query. See Section 8.2.1.17, “How to Avoid Full Table Scans” for details.

8.3.2 Using Primary Keys
The primary key for a table represents the column or set of columns that you use in your most vital
queries. It has an associated index, for fast query performance. Query performance benefits from
the NOT NULL optimization, because it cannot include any NULL values. With the InnoDB storage
engine, the table data is physically organized to do ultra-fast lookups and sorts based on the primary
key column or columns.
If your table is big and important, but does not have an obvious column or set of columns to use as a
primary key, you might create a separate column with auto-increment values to use as the primary key.
These unique IDs can serve as pointers to corresponding rows in other tables when you join tables
using foreign keys.

8.3.3 Using Foreign Keys
If a table has many columns, and you query many different combinations of columns, it might be
efficient to split the less-frequently used data into separate tables with a few columns each, and relate
them back to the main table by duplicating the numeric ID column from the main table. That way,
each small table can have a primary key for fast lookups of its data, and you can query just the set of
columns that you need using a join operation. Depending on how the data is distributed, the queries
might perform less I/O and take up less cache memory because the relevant columns are packed
together on disk. (To maximize performance, queries try to read as few data blocks as possible from
disk; tables with only a few columns can fit more rows in each data block.)

8.3.4 Column Indexes
All MySQL data types can be indexed. Use of indexes on the relevant columns is the best way to
improve the performance of SELECT operations.
The maximum number of indexes per table and the maximum index length is defined per storage
engine. See Chapter 14, Storage Engines. All storage engines support at least 16 indexes per table
and a total index length of at least 256 bytes. Most storage engines have higher limits.
For additional information about column indexes, see Section 13.1.8, “CREATE INDEX Syntax”.

Prefix Indexes
With col_name(N) syntax in an index specification for a string column, you can create an index that
uses only the first N characters of the column. Indexing only a prefix of column values in this way can
make the index file much smaller. When you index a BLOB or TEXT column, you must specify a prefix
length for the index. For example:
CREATE TABLE test (blob_col BLOB, INDEX(blob_col(10)));

Prefixes can be up to 1000 bytes long (767 bytes for InnoDB tables).
Note
Prefix limits are measured in bytes, whereas the prefix length in CREATE
TABLE, ALTER TABLE, and CREATE INDEX statements is interpreted as
number of characters for nonbinary string types (CHAR, VARCHAR, TEXT) and
number of bytes for binary string types (BINARY, VARBINARY, BLOB). Take this
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Multiple-Column Indexes

into account when specifying a prefix length for a nonbinary string column that
uses a multibyte character set.
For additional information about index prefixes, see Section 13.1.8, “CREATE INDEX Syntax”.

FULLTEXT Indexes
FULLTEXT indexes are used for full-text searches. Only the MyISAM storage engine supports
FULLTEXT indexes and only for CHAR, VARCHAR, and TEXT columns. Indexing always takes place over
the entire column and column prefix indexing is not supported. For details, see Section 12.9, “Full-Text
Search Functions”.

Spatial Indexes
You can create indexes on spatial data types. Only MyISAM supports R-tree indexes on spatial types.
As of MySQL 5.0.16, other storage engines use B-trees for indexing spatial types (except for ARCHIVE
and NDB, which do not support spatial type indexing).

Indexes in the MEMORY Storage Engine
The MEMORY storage engine uses HASH indexes by default, but also supports BTREE indexes.

8.3.5 Multiple-Column Indexes
MySQL can create composite indexes (that is, indexes on multiple columns). An index may consist
of up to 16 columns. For certain data types, you can index a prefix of the column (see Section 8.3.4,
“Column Indexes”).
MySQL can use multiple-column indexes for queries that test all the columns in the index, or queries
that test just the first column, the first two columns, the first three columns, and so on. If you specify the
columns in the right order in the index definition, a single composite index can speed up several kinds
of queries on the same table.
A multiple-column index can be considered a sorted array, the rows of which contain values that are
created by concatenating the values of the indexed columns.
Note
As an alternative to a composite index, you can introduce a column that is
“hashed” based on information from other columns. If this column is short,
reasonably unique, and indexed, it might be faster than a “wide” index on many
columns. In MySQL, it is very easy to use this extra column:
SELECT * FROM tbl_name
WHERE hash_col=MD5(CONCAT(val1,val2))
AND col1=val1 AND col2=val2;

Suppose that a table has the following specification:
CREATE TABLE test (
id
INT NOT NULL,
last_name CHAR(30) NOT NULL,
first_name CHAR(30) NOT NULL,
PRIMARY KEY (id),
INDEX name (last_name,first_name)
);

The name index is an index over the last_name and first_name columns. The index can be used
for lookups in queries that specify values in a known range for combinations of last_name and
first_name values. It can also be used for queries that specify just a last_name value because that
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Verifying Index Usage

column is a leftmost prefix of the index (as described later in this section). Therefore, the name index is
used for lookups in the following queries:
SELECT * FROM test WHERE last_name='Widenius';
SELECT * FROM test
WHERE last_name='Widenius' AND first_name='Michael';
SELECT * FROM test
WHERE last_name='Widenius'
AND (first_name='Michael' OR first_name='Monty');
SELECT * FROM test
WHERE last_name='Widenius'
AND first_name >='M' AND first_name < 'N';

However, the name index is not used for lookups in the following queries:
SELECT * FROM test WHERE first_name='Michael';
SELECT * FROM test
WHERE last_name='Widenius' OR first_name='Michael';

Suppose that you issue the following SELECT statement:
SELECT * FROM tbl_name
WHERE col1=val1 AND col2=val2;

If a multiple-column index exists on col1 and col2, the appropriate rows can be fetched directly.
If separate single-column indexes exist on col1 and col2, the optimizer attempts to use the Index
Merge optimization (see Section 8.2.1.4, “Index Merge Optimization”), or attempts to find the most
restrictive index by deciding which index excludes more rows and using that index to fetch the rows.
If the table has a multiple-column index, any leftmost prefix of the index can be used by the optimizer
to look up rows. For example, if you have a three-column index on (col1, col2, col3), you have
indexed search capabilities on (col1), (col1, col2), and (col1, col2, col3).
MySQL cannot use the index to perform lookups if the columns do not form a leftmost prefix of the
index. Suppose that you have the SELECT statements shown here:
SELECT * FROM tbl_name WHERE col1=val1;
SELECT * FROM tbl_name WHERE col1=val1 AND col2=val2;
SELECT * FROM tbl_name WHERE col2=val2;
SELECT * FROM tbl_name WHERE col2=val2 AND col3=val3;

If an index exists on (col1, col2, col3), only the first two queries use the index. The third and
fourth queries do involve indexed columns, but (col2) and (col2, col3) are not leftmost prefixes
of (col1, col2, col3).

8.3.6 Verifying Index Usage
Always check whether all your queries really use the indexes that you have created in the tables. Use
the EXPLAIN statement, as described in Section 8.8.1, “Optimizing Queries with EXPLAIN”.

8.3.7 MyISAM Index Statistics Collection
Storage engines collect statistics about tables for use by the optimizer. Table statistics are based
on value groups, where a value group is a set of rows with the same key prefix value. For optimizer
purposes, an important statistic is the average value group size.
MySQL uses the average value group size in the following ways:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MyISAM Index Statistics Collection

• To estimate how may rows must be read for each ref access
• To estimate how many row a partial join will produce; that is, the number of rows that an operation of
this form will produce:
(...) JOIN tbl_name ON tbl_name.key = expr

As the average value group size for an index increases, the index is less useful for those two purposes
because the average number of rows per lookup increases: For the index to be good for optimization
purposes, it is best that each index value target a small number of rows in the table. When a given
index value yields a large number of rows, the index is less useful and MySQL is less likely to use it.
The average value group size is related to table cardinality, which is the number of value groups. The
SHOW INDEX statement displays a cardinality value based on N/S, where N is the number of rows
in the table and S is the average value group size. That ratio yields an approximate number of value
groups in the table.
For a join based on the <=> comparison operator, NULL is not treated differently from any other value:
NULL <=> NULL, just as N <=> N for any other N.
However, for a join based on the = operator, NULL is different from non-NULL values: expr1 = expr2
is not true when expr1 or expr2 (or both) are NULL. This affects ref accesses for comparisons of the
form tbl_name.key = expr: MySQL will not access the table if the current value of expr is NULL,
because the comparison cannot be true.
For = comparisons, it does not matter how many NULL values are in the table. For optimization
purposes, the relevant value is the average size of the non-NULL value groups. However, MySQL does
not currently enable that average size to be collected or used.
For MyISAM tables, you have some control over collection of table statistics by means of the
myisam_stats_method system variable. This variable has three possible values, which differ as
follows:
• When myisam_stats_method is nulls_equal, all NULL values are treated as identical (that is,
they all form a single value group).
If the NULL value group size is much higher than the average non-NULL value group size, this
method skews the average value group size upward. This makes index appear to the optimizer to be
less useful than it really is for joins that look for non-NULL values. Consequently, the nulls_equal
method may cause the optimizer not to use the index for ref accesses when it should.
• When myisam_stats_method is nulls_unequal, NULL values are not considered the same.
Instead, each NULL value forms a separate value group of size 1.
If you have many NULL values, this method skews the average value group size downward. If
the average non-NULL value group size is large, counting NULL values each as a group of size 1
causes the optimizer to overestimate the value of the index for joins that look for non-NULL values.
Consequently, the nulls_unequal method may cause the optimizer to use this index for ref
lookups when other methods may be better.
• When myisam_stats_method is nulls_ignored, NULL values are ignored.
If you tend to use many joins that use <=> rather than =, NULL values are not special in comparisons
and one NULL is equal to another. In this case, nulls_equal is the appropriate statistics method.
The myisam_stats_method system variable has global and session values. Setting the global value
affects MyISAM statistics collection for all MyISAM tables. Setting the session value affects statistics
collection only for the current client connection. This means that you can force a table's statistics to
be regenerated with a given method without affecting other clients by setting the session value of
myisam_stats_method.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Comparison of B-Tree and Hash Indexes

To regenerate MyISAM table statistics, you can use any of the following methods:
• Execute myisamchk --stats_method=method_name --analyze
• Change the table to cause its statistics to go out of date (for example, insert a row and then delete it),
and then set myisam_stats_method and issue an ANALYZE TABLE statement
Some caveats regarding the use of myisam_stats_method:
• You can force table statistics to be collected explicitly, as just described. However, MySQL may also
collect statistics automatically. For example, if during the course of executing statements for a table,
some of those statements modify the table, MySQL may collect statistics. (This may occur for bulk
inserts or deletes, or some ALTER TABLE statements, for example.) If this happens, the statistics
are collected using whatever value myisam_stats_method has at the time. Thus, if you collect
statistics using one method, but myisam_stats_method is set to the other method when a table's
statistics are collected automatically later, the other method will be used.
• There is no way to tell which method was used to generate statistics for a given MyISAM table.
• myisam_stats_method applies only to MyISAM tables. Other storage engines have only one
method for collecting table statistics. Usually it is closer to the nulls_equal method.

8.3.8 Comparison of B-Tree and Hash Indexes
Understanding the B-tree and hash data structures can help predict how different queries perform on
different storage engines that use these data structures in their indexes, particularly for the MEMORY
storage engine that lets you choose B-tree or hash indexes.

B-Tree Index Characteristics
A B-tree index can be used for column comparisons in expressions that use the =, >, >=, <, <=, or
BETWEEN operators. The index also can be used for LIKE comparisons if the argument to LIKE is
a constant string that does not start with a wildcard character. For example, the following SELECT
statements use indexes:
SELECT * FROM tbl_name WHERE key_col LIKE 'Patrick%';
SELECT * FROM tbl_name WHERE key_col LIKE 'Pat%_ck%';

In the first statement, only rows with 'Patrick' <= key_col < 'Patricl' are considered. In the
second statement, only rows with 'Pat' <= key_col < 'Pau' are considered.
The following SELECT statements do not use indexes:
SELECT * FROM tbl_name WHERE key_col LIKE '%Patrick%';
SELECT * FROM tbl_name WHERE key_col LIKE other_col;

In the first statement, the LIKE value begins with a wildcard character. In the second statement, the
LIKE value is not a constant.
If you use ... LIKE '%string%' and string is longer than three characters, MySQL uses the
Turbo Boyer-Moore algorithm to initialize the pattern for the string and then uses this pattern to perform
the search more quickly.
A search using col_name IS NULL employs indexes if col_name is indexed.
Any index that does not span all AND levels in the WHERE clause is not used to optimize the query. In
other words, to be able to use an index, a prefix of the index must be used in every AND group.
The following WHERE clauses use indexes:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Database Structure

... WHERE index_part1=1 AND index_part2=2 AND other_column=3
/* index = 1 OR index = 2 */
... WHERE index=1 OR A=10 AND index=2
/* optimized like "index_part1='hello'" */
... WHERE index_part1='hello' AND index_part3=5
/* Can use index on index1 but not on index2 or index3 */
... WHERE index1=1 AND index2=2 OR index1=3 AND index3=3;

These WHERE clauses do not use indexes:
/* index_part1 is not used */
... WHERE index_part2=1 AND index_part3=2
/* Index is not used in both parts of the WHERE clause
... WHERE index=1 OR A=10

*/

/* No index spans all rows */
... WHERE index_part1=1 OR index_part2=10

Sometimes MySQL does not use an index, even if one is available. One circumstance under which
this occurs is when the optimizer estimates that using the index would require MySQL to access a
very large percentage of the rows in the table. (In this case, a table scan is likely to be much faster
because it requires fewer seeks.) However, if such a query uses LIMIT to retrieve only some of the
rows, MySQL uses an index anyway, because it can much more quickly find the few rows to return in
the result.

Hash Index Characteristics
Hash indexes have somewhat different characteristics from those just discussed:
• They are used only for equality comparisons that use the = or <=> operators (but are very fast). They
are not used for comparison operators such as < that find a range of values. Systems that rely on
this type of single-value lookup are known as “key-value stores”; to use MySQL for such applications,
use hash indexes wherever possible.
• The optimizer cannot use a hash index to speed up ORDER BY operations. (This type of index cannot
be used to search for the next entry in order.)
• MySQL cannot determine approximately how many rows there are between two values (this is used
by the range optimizer to decide which index to use). This may affect some queries if you change a
MyISAM or InnoDB table to a hash-indexed MEMORY table.
• Only whole keys can be used to search for a row. (With a B-tree index, any leftmost prefix of the key
can be used to find rows.)

8.4 Optimizing Database Structure
In your role as a database designer, look for the most efficient way to organize your schemas, tables,
and columns. As when tuning application code, you minimize I/O, keep related items together, and plan
ahead so that performance stays high as the data volume increases. Starting with an efficient database
design makes it easier for team members to write high-performing application code, and makes the
database likely to endure as applications evolve and are rewritten.

8.4.1 Optimizing Data Size
Design your tables to minimize their space on the disk. This can result in huge improvements by
reducing the amount of data written to and read from disk. Smaller tables normally require less main
memory while their contents are being actively processed during query execution. Any space reduction
for table data also results in smaller indexes that can be processed faster.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Data Size

MySQL supports many different storage engines (table types) and row formats. For each table, you
can decide which storage and indexing method to use. Choosing the proper table format for your
application can give you a big performance gain. See Chapter 14, Storage Engines.
You can get better performance for a table and minimize storage space by using the techniques listed
here:

Table Columns
• Use the most efficient (smallest) data types possible. MySQL has many specialized types that save
disk space and memory. For example, use the smaller integer types if possible to get smaller tables.
MEDIUMINT is often a better choice than INT because a MEDIUMINT column uses 25% less space.
• Declare columns to be NOT NULL if possible. It makes SQL operations faster, by enabling better use
of indexes and eliminating overhead for testing whether each value is NULL. You also save some
storage space, one bit per column. If you really need NULL values in your tables, use them. Just
avoid the default setting that allows NULL values in every column.

Row Format
• For MyISAM tables, if you do not have any variable-length columns (VARCHAR, TEXT, or BLOB
columns), a fixed-size row format is used. This is faster but unfortunately may waste some
space. See Section 14.1.3, “MyISAM Table Storage Formats”. You can hint that you want to
have fixed length rows even if you have VARCHAR columns with the CREATE TABLE option
ROW_FORMAT=FIXED.
• Starting with MySQL 5.0.3, InnoDB tables use a more compact storage format. In earlier versions
of MySQL, InnoDB rows contain some redundant information, such as the number of columns and
the length of each column, even for fixed-size columns. By default, tables are created in the compact
format (ROW_FORMAT=COMPACT). If you wish to downgrade to older versions of MySQL, you can
request the old format with ROW_FORMAT=REDUNDANT.
The presence of the compact row format decreases row storage space by about 20% at the cost of
increasing CPU use for some operations. If your workload is a typical one that is limited by cache hit
rates and disk speed it is likely to be faster. If it is a rare case that is limited by CPU speed, it might
be slower.
The compact InnoDB format also changes how CHAR columns containing UTF-8 data are
stored. With ROW_FORMAT=REDUNDANT, a UTF-8 CHAR(N) occupies 3 × N bytes, given that the
maximum length of a UTF-8 encoded character is three bytes. Many languages can be written
primarily using single-byte UTF-8 characters, so a fixed storage length often wastes space. With
ROW_FORMAT=COMPACT format, InnoDB allocates a variable amount of storage in the range from
N to 3 × N bytes for these columns by stripping trailing spaces if necessary. The minimum storage
length is kept as N bytes to facilitate in-place updates in typical cases.

Indexes
• The primary index of a table should be as short as possible. This makes identification of each row
easy and efficient.
• Create only the indexes that you need to improve query performance. Indexes are good for retrieval,
but slow down insert and update operations. If you access a table mostly by searching on a
combination of columns, create a single composite index on them rather than a separate index for
each column. The first part of the index should be the column most used. If you always use many
columns when selecting from the table, the first column in the index should be the one with the most
duplicates, to obtain better compression of the index.
• If it is very likely that a string column has a unique prefix on the first number of characters, it is better
to index only this prefix, using MySQL's support for creating an index on the leftmost part of the
column (see Section 13.1.8, “CREATE INDEX Syntax”). Shorter indexes are faster, not only because
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing MySQL Data Types

they require less disk space, but because they also give you more hits in the index cache, and thus
fewer disk seeks. See Section 8.12.2, “Tuning Server Parameters”.

Joins
• In some circumstances, it can be beneficial to split into two a table that is scanned very often. This is
especially true if it is a dynamic-format table and it is possible to use a smaller static format table that
can be used to find the relevant rows when scanning the table.
• Declare columns with identical information in different tables with identical data types, to speed up
joins based on the corresponding columns.
• Keep column names simple, so that you can use the same name across different tables and simplify
join queries. For example, in a table named customer, use a column name of name instead of
customer_name. To make your names portable to other SQL servers, consider keeping them
shorter than 18 characters.

Normalization
• Normally, try to keep all data nonredundant (observing what is referred to in database theory as
third normal form). Instead of repeating lengthy values such as names and addresses, assign them
unique IDs, repeat these IDs as needed across multiple smaller tables, and join the tables in queries
by referencing the IDs in the join clause.
• If speed is more important than disk space and the maintenance costs of keeping multiple copies
of data, for example in a business intelligence scenario where you analyze all the data from large
tables, you can relax the normalization rules, duplicating information or creating summary tables to
gain more speed.

8.4.2 Optimizing MySQL Data Types
8.4.2.1 Optimizing for Numeric Data
• For unique IDs or other values that can be represented as either strings or numbers, prefer numeric
columns to string columns. Since large numeric values can be stored in fewer bytes than the
corresponding strings, it is faster and takes less memory to transfer and compare them.
• If you are using numeric data, it is faster in many cases to access information from a database (using
a live connection) than to access a text file. Information in the database is likely to be stored in a
more compact format than in the text file, so accessing it involves fewer disk accesses. You also
save code in your application because you can avoid parsing the text file to find line and column
boundaries.

8.4.2.2 Optimizing for Character and String Types
For character and string columns, follow these guidelines:
• Use binary collation order for fast comparison and sort operations, when you do not need languagespecific collation features. You can use the BINARY operator to use binary collation within a
particular query.
• When comparing values from different columns, declare those columns with the same character set
and collation wherever possible, to avoid string conversions while running the query.
• For column values less than 8KB in size, use binary VARCHAR instead of BLOB. The GROUP BY and
ORDER BY clauses can generate temporary tables, and these temporary tables can use the MEMORY
storage engine if the original table does not contain any BLOB columns.
• If a table contains string columns such as name and address, but many queries do not retrieve
those columns, consider splitting the string columns into a separate table and using join queries
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing MySQL Data Types

with a foreign key when necessary. When MySQL retrieves any value from a row, it reads a data
block containing all the columns of that row (and possibly other adjacent rows). Keeping each row
small, with only the most frequently used columns, allows more rows to fit in each data block. Such
compact tables reduce disk I/O and memory usage for common queries.
• When you use a randomly generated value as a primary key in an InnoDB table, prefix it with an
ascending value such as the current date and time if possible. When consecutive primary values are
physically stored near each other, InnoDB can insert and retrieve them faster.
• See Section 8.4.2.1, “Optimizing for Numeric Data” for reasons why a numeric column is usually
preferable to an equivalent string column.

8.4.2.3 Optimizing for BLOB Types
• When storing a large blob containing textual data, consider compressing it first. Do not use this
technique when the entire table is compressed by InnoDB or MyISAM.
• For a table with several columns, to reduce memory requirements for queries that do not use the
BLOB column, consider splitting the BLOB column into a separate table and referencing it with a join
query when needed.
• Since the performance requirements to retrieve and display a BLOB value might be very different
from other data types, you could put the BLOB-specific table on a different storage device or even a
separate database instance. For example, to retrieve a BLOB might require a large sequential disk
read that is better suited to a traditional hard drive than to an SSD device.
• See Section 8.4.2.2, “Optimizing for Character and String Types” for reasons why a binary VARCHAR
column is sometimes preferable to an equivalent BLOB column.
• Rather than testing for equality against a very long text string, you can store a hash of the column
value in a separate column, index that column, and test the hashed value in queries. (Use the MD5()
or CRC32() function to produce the hash value.) Since hash functions can produce duplicate results
for different inputs, you still include a clause AND blob_column = long_string_value in
the query to guard against false matches; the performance benefit comes from the smaller, easily
scanned index for the hashed values.

8.4.2.4 Using PROCEDURE ANALYSE
ANALYSE([max_elements[,max_memory]])
ANALYSE() examines the result from a query and returns an analysis of the results that suggests
optimal data types for each column that may help reduce table sizes. To obtain this analysis, append
PROCEDURE ANALYSE to the end of a SELECT statement:
SELECT ... FROM ... WHERE ... PROCEDURE ANALYSE([max_elements,[max_memory]])

For example:
SELECT col1, col2 FROM table1 PROCEDURE ANALYSE(10, 2000);

The results show some statistics for the values returned by the query, and propose an optimal data
type for the columns. This can be helpful for checking your existing tables, or after importing new data.
You may need to try different settings for the arguments so that PROCEDURE ANALYSE() does not
suggest the ENUM data type when it is not appropriate.
The arguments are optional and are used as follows:
• max_elements (default 256) is the maximum number of distinct values that ANALYSE() notices per
column. This is used by ANALYSE() to check whether the optimal data type should be of type ENUM;
if there are more than max_elements distinct values, then ENUM is not a suggested type.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing for Many Tables

• max_memory (default 8192) is the maximum amount of memory that ANALYSE() should allocate per
column while trying to find all distinct values.
A PROCEDURE clause is not permitted in a UNION statement.

8.4.3 Optimizing for Many Tables
Some techniques for keeping individual queries fast involve splitting data across many tables. When
the number of tables runs into the thousands or even millions, the overhead of dealing with all these
tables becomes a new performance consideration.

8.4.3.1 How MySQL Opens and Closes Tables
When you execute a mysqladmin status command, you should see something like this:
Uptime: 426 Running threads: 1 Questions: 11082
Reloads: 1 Open tables: 12

The Open tables value of 12 can be somewhat puzzling if you have only six tables.
MySQL is multi-threaded, so there may be many clients issuing queries for a given table
simultaneously. To minimize the problem with multiple client sessions having different states on the
same table, the table is opened independently by each concurrent session. This uses additional
memory but normally increases performance. With MyISAM tables, one extra file descriptor is required
for the data file for each client that has the table open. (By contrast, the index file descriptor is shared
between all sessions.)
The table_cache and max_connections system variables affect the maximum number of files the
server keeps open. If you increase one or both of these values, you may run up against a limit imposed
by your operating system on the per-process number of open file descriptors. Many operating systems
permit you to increase the open-files limit, although the method varies widely from system to system.
Consult your operating system documentation to determine whether it is possible to increase the limit
and how to do so.
table_cache is related to max_connections. For example, for 200 concurrent running connections,
you should have a table cache size of at least 200 * N, where N is the maximum number of tables
per join in any of the queries which you execute. You must also reserve some extra file descriptors for
temporary tables and files.
Make sure that your operating system can handle the number of open file descriptors implied by
the table_cache setting. If table_cache is set too high, MySQL may run out of file descriptors
and refuse connections, fail to perform queries, and be very unreliable. You also have to take into
account that the MyISAM storage engine needs two file descriptors for each unique open table. You
can increase the number of file descriptors available to MySQL using the --open-files-limit
startup option to mysqld. See Section B.5.2.18, “File Not Found and Similar Errors”.
The cache of open tables is kept at a level of table_cache entries. The default value is 64; this can
be changed with the --table_cache option to mysqld. Note that MySQL may temporarily open more
tables than this to execute queries.
MySQL closes an unused table and removes it from the table cache under the following circumstances:
• When the cache is full and a thread tries to open a table that is not in the cache.
• When the cache contains more than table_cache entries and a table in the cache is no longer
being used by any threads.
• When a table flushing operation occurs. This happens when someone issues a FLUSH TABLES
statement or executes a mysqladmin flush-tables or mysqladmin refresh command.
When the table cache fills up, the server uses the following procedure to locate a cache entry to use:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Internal Temporary Table Use in MySQL

• Tables that are not currently in use are released, beginning with the table least recently used.
• If a new table needs to be opened, but the cache is full and no tables can be released, the cache is
temporarily extended as necessary. When the cache is in a temporarily extended state and a table
goes from a used to unused state, the table is closed and released from the cache.
A MyISAM table is opened for each concurrent access. This means the table needs to be opened twice
if two threads access the same table or if a thread accesses the table twice in the same query (for
example, by joining the table to itself). Each concurrent open requires an entry in the table cache. The
first open of any MyISAM table takes two file descriptors: one for the data file and one for the index file.
Each additional use of the table takes only one file descriptor for the data file. The index file descriptor
is shared among all threads.
If you are opening a table with the HANDLER tbl_name OPEN statement, a dedicated table object
is allocated for the thread. This table object is not shared by other threads and is not closed until the
thread calls HANDLER tbl_name CLOSE or the thread terminates. When this happens, the table is put
back in the table cache (if the cache is not full). See Section 13.2.4, “HANDLER Syntax”.
You can determine whether your table cache is too small by checking the mysqld status variable
Opened_tables, which indicates the number of table-opening operations since the server started:
mysql> SHOW GLOBAL STATUS LIKE 'Opened_tables';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| Opened_tables | 2741 |
+---------------+-------+

If the value is very large or increases rapidly, even when you have not issued many FLUSH TABLES
statements, you should increase the table cache size. See Section 5.1.4, “Server System Variables”,
and Section 5.1.6, “Server Status Variables”.

8.4.3.2 Disadvantages of Creating Many Tables in the Same Database
If you have many MyISAM tables in the same database directory, open, close, and create operations
are slow. If you execute SELECT statements on many different tables, there is a little overhead when
the table cache is full, because for every table that has to be opened, another must be closed. You can
reduce this overhead by increasing the number of entries permitted in the table cache.

8.4.4 Internal Temporary Table Use in MySQL
In some cases, the server creates internal temporary tables while processing statements. Users have
no direct control over when this occurs.
The server creates temporary tables under conditions such as these:
• Evaluation of UNION statements.
• Evaluation of some views, such those that use the TEMPTABLE algorithm, UNION, or aggregation.
• Evaluation of statements that contain an ORDER BY clause and a different GROUP BY clause, or for
which the ORDER BY or GROUP BY contains columns from tables other than the first table in the join
queue.
• Evaluation of DISTINCT combined with ORDER BY may require a temporary table.
• For queries that use the SQL_SMALL_RESULT option, MySQL uses an in-memory temporary table,
unless the query also contains elements (described later) that require on-disk storage.
• Evaluation of multiple-table UPDATE statements.
• Evaluation of GROUP_CONCAT() or COUNT(DISTINCT) expressions.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing for MyISAM Tables

To determine whether a statement requires a temporary table, use EXPLAIN and check the Extra
column to see whether it says Using temporary (see Section 8.8.1, “Optimizing Queries with
EXPLAIN”).

Storage Engines Used for Temporary Tables
An internal temporary table can be held in memory and processed by the MEMORY storage engine, or
stored on disk and processed by the MyISAM storage engine.
If an internal temporary table is created as an in-memory table but becomes too large, MySQL
automatically converts it to an on-disk table. The maximum size for in-memory temporary tables is the
minimum of the tmp_table_size and max_heap_table_size values. This differs from MEMORY
tables explicitly created with CREATE TABLE: For such tables, only the max_heap_table_size
system variable determines how large the table is permitted to grow and there is no conversion to ondisk format.
Some conditions prevent the use of an in-memory temporary table, in which case the server uses an
on-disk table instead:
• Presence of a BLOB or TEXT column in the table
• Presence of any string column in a GROUP BY or DISTINCT clause larger than 512 bytes
• Presence of any string column with a maximum length larger than 512 (bytes for binary strings,
characters for nonbinary strings) in the SELECT list, if UNION or UNION ALL is used
• The SHOW COLUMNS and DESCRIBE statements use BLOB as the type for some columns, thus the
temporary table used for the results is an on-disk table.
When the server creates an internal temporary table (either in memory or on disk), it increments the
Created_tmp_tables status variable. If the server creates the table on disk (either initially or by
converting an in-memory table) it increments the Created_tmp_disk_tables status variable.

Temporary Table Storage Format
Internal temporary tables are stored using fixed-length row format, whether managed by the MEMORY or
MyISAM storage engine.

8.5 Optimizing for MyISAM Tables
The MyISAM storage engine performs best with read-mostly data or with low-concurrency operations,
because table locks limit the ability to perform simultaneous updates.

8.5.1 Optimizing MyISAM Queries
Some general tips for speeding up queries on MyISAM tables:
• To help MySQL better optimize queries, use ANALYZE TABLE or run myisamchk --analyze on
a table after it has been loaded with data. This updates a value for each index part that indicates
the average number of rows that have the same value. (For unique indexes, this is always 1.)
MySQL uses this to decide which index to choose when you join two tables based on a nonconstant
expression. You can check the result from the table analysis by using SHOW INDEX FROM
tbl_name and examining the Cardinality value. myisamchk --description --verbose
shows index distribution information.
• To sort an index and data according to an index, use myisamchk --sort-index --sortrecords=1 (assuming that you want to sort on index 1). This is a good way to make queries faster
if you have a unique index from which you want to read all rows in order according to the index. The
first time you sort a large table this way, it may take a long time.
• Try to avoid complex SELECT queries on MyISAM tables that are updated frequently, to avoid
problems with table locking that occur due to contention between readers and writers.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing MyISAM Queries

• MyISAM supports concurrent inserts: If a table has no free blocks in the middle of the data file, you
can INSERT new rows into it at the same time that other threads are reading from the table. If it is
important to be able to do this, consider using the table in ways that avoid deleting rows. Another
possibility is to run OPTIMIZE TABLE to defragment the table after you have deleted a lot of rows
from it. This behavior is altered by setting the concurrent_insert variable. You can force new
rows to be appended (and therefore permit concurrent inserts), even in tables that have deleted
rows. See Section 8.11.3, “Concurrent Inserts”.
• For MyISAM tables that change frequently, try to avoid all variable-length columns (VARCHAR, BLOB,
and TEXT). The table uses dynamic row format if it includes even a single variable-length column.
See Chapter 14, Storage Engines.
• It is normally not useful to split a table into different tables just because the rows become large. In
accessing a row, the biggest performance hit is the disk seek needed to find the first byte of the row.
After finding the data, most modern disks can read the entire row fast enough for most applications.
The only cases where splitting up a table makes an appreciable difference is if it is a MyISAM table
using dynamic row format that you can change to a fixed row size, or if you very often need to scan
the table but do not need most of the columns. See Chapter 14, Storage Engines.
• Use ALTER TABLE ... ORDER BY expr1, expr2, ... if you usually retrieve rows in expr1,
expr2, ... order. By using this option after extensive changes to the table, you may be able to get
higher performance.
• If you often need to calculate results such as counts based on information from a lot of rows, it may
be preferable to introduce a new table and update the counter in real time. An update of the following
form is very fast:
UPDATE tbl_name SET count_col=count_col+1 WHERE key_col=constant;

This is very important when you use a MySQL storage engine such as MyISAM that has only tablelevel locking (multiple readers with single writers). This also gives better performance with most
database systems, because the row locking manager in this case has less to do.
• Use INSERT DELAYED when you do not need to know when your data is written. This reduces the
overall insertion impact because many rows can be written with a single disk write.
• Use INSERT LOW_PRIORITY when you want to give SELECT statements higher priority than your
inserts.
Use SELECT HIGH_PRIORITY to get retrievals that jump the queue. That is, the SELECT is
executed even if there is another client waiting to do a write.
LOW_PRIORITY and HIGH_PRIORITY have an effect only for storage engines that use only tablelevel locking (such as MyISAM, MEMORY, and MERGE).
• Use OPTIMIZE TABLE periodically to avoid fragmentation with dynamic-format MyISAM tables. See
Section 14.1.3, “MyISAM Table Storage Formats”.
• Declaring a MyISAM table with the DELAY_KEY_WRITE=1 table option makes index updates faster
because they are not flushed to disk until the table is closed. The downside is that if something
kills the server while such a table is open, you must ensure that the table is okay by running the
server with the --myisam-recover option, or by running myisamchk before restarting the server.
(However, even in this case, you should not lose anything by using DELAY_KEY_WRITE, because
the key information can always be generated from the data rows.)
• Strings are automatically prefix- and end-space compressed in MyISAM indexes. See Section 13.1.8,
“CREATE INDEX Syntax”.
• You can increase performance by caching queries or answers in your application and then executing
many inserts or updates together. Locking the table during this operation ensures that the index
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Bulk Data Loading for MyISAM Tables

cache is only flushed once after all updates. You can also take advantage of MySQL's query cache
to achieve similar results; see Section 8.10.3, “The MySQL Query Cache”.

8.5.2 Bulk Data Loading for MyISAM Tables
These performance tips supplement the general guidelines for fast inserts in Section 8.2.2.1, “Speed of
INSERT Statements”.
• To improve performance when multiple clients insert a lot of rows, use the INSERT DELAYED
statement. See Section 13.2.5.2, “INSERT DELAYED Syntax”. This technique works for MyISAM and
some other storage engines, but not InnoDB.
• For a MyISAM table, you can use concurrent inserts to add rows at the same time that SELECT
statements are running, if there are no deleted rows in middle of the data file. See Section 8.11.3,
“Concurrent Inserts”.
• With some extra work, it is possible to make LOAD DATA INFILE run even faster for a MyISAM
table when the table has many indexes. Use the following procedure:
1. Execute a FLUSH TABLES statement or a mysqladmin flush-tables command.
2. Use myisamchk --keys-used=0 -rq /path/to/db/tbl_name to remove all use of
indexes for the table.
3. Insert data into the table with LOAD DATA INFILE. This does not update any indexes and
therefore is very fast.
4. If you intend only to read from the table in the future, use myisampack to compress it. See
Section 14.1.3.3, “Compressed Table Characteristics”.
5. Re-create the indexes with myisamchk -rq /path/to/db/tbl_name. This creates the index
tree in memory before writing it to disk, which is much faster than updating the index during LOAD
DATA INFILE because it avoids lots of disk seeks. The resulting index tree is also perfectly
balanced.
6. Execute a FLUSH TABLES statement or a mysqladmin flush-tables command.
LOAD DATA INFILE performs the preceding optimization automatically if the MyISAM table into
which you insert data is empty. The main difference between automatic optimization and using the
procedure explicitly is that you can let myisamchk allocate much more temporary memory for the
index creation than you might want the server to allocate for index re-creation when it executes the
LOAD DATA INFILE statement.
You can also disable or enable the nonunique indexes for a MyISAM table by using the following
statements rather than myisamchk. If you use these statements, you can skip the FLUSH TABLE
operations:
ALTER TABLE tbl_name DISABLE KEYS;
ALTER TABLE tbl_name ENABLE KEYS;

• To speed up INSERT operations that are performed with multiple statements for nontransactional
tables, lock your tables:
LOCK TABLES a WRITE;
INSERT INTO a VALUES (1,23),(2,34),(4,33);
INSERT INTO a VALUES (8,26),(6,29);
...
UNLOCK TABLES;

This benefits performance because the index buffer is flushed to disk only once, after all INSERT
statements have completed. Normally, there would be as many index buffer flushes as there are

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Speed of REPAIR TABLE Statements

INSERT statements. Explicit locking statements are not needed if you can insert all rows with a
single INSERT.
Locking also lowers the total time for multiple-connection tests, although the maximum wait time for
individual connections might go up because they wait for locks. Suppose that five clients attempt to
perform inserts simultaneously as follows:
• Connection 1 does 1000 inserts
• Connections 2, 3, and 4 do 1 insert
• Connection 5 does 1000 inserts
If you do not use locking, connections 2, 3, and 4 finish before 1 and 5. If you use locking,
connections 2, 3, and 4 probably do not finish before 1 or 5, but the total time should be about 40%
faster.
INSERT, UPDATE, and DELETE operations are very fast in MySQL, but you can obtain better overall
performance by adding locks around everything that does more than about five successive inserts
or updates. If you do very many successive inserts, you could do a LOCK TABLES followed by an
UNLOCK TABLES once in a while (each 1,000 rows or so) to permit other threads to access table.
This would still result in a nice performance gain.
INSERT is still much slower for loading data than LOAD DATA INFILE, even when using the
strategies just outlined.
• To increase performance for MyISAM tables, for both LOAD DATA INFILE and INSERT, enlarge
the key cache by increasing the key_buffer_size system variable. See Section 8.12.2, “Tuning
Server Parameters”.

8.5.3 Speed of REPAIR TABLE Statements
REPAIR TABLE for MyISAM tables is similar to using myisamchk for repair operations, and some of
the same performance optimizations apply:
• myisamchk has variables that control memory allocation. You may be able to its improve
performance by setting these variables, as described in Section 4.6.3.6, “myisamchk Memory
Usage”.
• For REPAIR TABLE, the same principle applies, but because the repair is done by the server, you
set server system variables instead of myisamchk variables. Also, In addition to setting memoryallocation variables, increasing the myisam_max_sort_file_size system variable increases the
likelihood that the repair will use the faster filesort method and avoid the slower repair by key cache
method. Set the variable to the maximum file size for your system, after checking to be sure that
there is enough free space to hold a copy of the table files. The free space must be available in the
file system containing the original table files.
Suppose that a myisamchk table-repair operation is done using the following options to set its
memory-allocation variables:
--key_buffer_size=128M --sort_buffer_size=256M
--read_buffer_size=64M --write_buffer_size=64M

Some of those myisamchk variables correspond to server system variables:
myisamchk Variable

System Variable

key_buffer_size

key_buffer_size

sort_buffer_size

myisam_sort_buffer_size

read_buffer_size

read_buffer_size

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing for InnoDB Tables

myisamchk Variable

System Variable

write_buffer_size

none

Each of the server system variables can be set at runtime, and some of them
(myisam_sort_buffer_size, read_buffer_size) have a session value in addition to a global
value. Setting a session value limits the effect of the change to your current session and does not affect
other users. Changing a global-only variable (key_buffer_size, myisam_max_sort_file_size)
affects other users as well. For key_buffer_size, you must take into account that the buffer
is shared with those users. For example, if you set the myisamchk key_buffer_size variable
to 128MB, you could set the corresponding key_buffer_size system variable larger than that
(if it is not already set larger), to permit key buffer use by activity in other sessions. However,
changing the global key buffer size invalidates the buffer, causing increased disk I/O and slowdown
for other sessions. An alternative that avoids this problem is to use a separate key cache, assign
to it the indexes from the table to be repaired, and deallocate it when the repair is complete. See
Section 8.10.1.2, “Multiple Key Caches”.
Based on the preceding remarks, a REPAIR TABLE operation can be done as follows to use settings
similar to the myisamchk command. Here a separate 128MB key buffer is allocated and the file
system is assumed to permit a file size of at least 100GB.
SET SESSION myisam_sort_buffer_size = 256*1024*1024;
SET SESSION read_buffer_size = 64*1024*1024;
SET GLOBAL myisam_max_sort_file_size = 100*1024*1024*1024;
SET GLOBAL repair_cache.key_buffer_size = 128*1024*1024;
CACHE INDEX tbl_name IN repair_cache;
LOAD INDEX INTO CACHE tbl_name;
REPAIR TABLE tbl_name ;
SET GLOBAL repair_cache.key_buffer_size = 0;

If you intend to change a global variable but want to do so only for the duration of a REPAIR TABLE
operation to minimally affect other users, save its value in a user variable and restore it afterward. For
example:
SET @old_myisam_sort_buffer_size = @@global.myisam_max_sort_file_size;
SET GLOBAL myisam_max_sort_file_size = 100*1024*1024*1024;
REPAIR TABLE tbl_name ;
SET GLOBAL myisam_max_sort_file_size = @old_myisam_max_sort_file_size;

The system variables that affect REPAIR TABLE can be set globally at server startup if you want the
values to be in effect by default. For example, add these lines to the server my.cnf file:
[mysqld]
myisam_sort_buffer_size=256M
key_buffer_size=1G
myisam_max_sort_file_size=100G

These settings do not include read_buffer_size. Setting read_buffer_size globally to a
large value does so for all sessions and can cause performance to suffer due to excessive memory
allocation for a server with many simultaneous sessions.

8.6 Optimizing for InnoDB Tables
This section explains how to optimize database operations for InnoDB tables.

8.6.1 Optimizing Storage Layout for InnoDB Tables
• Once your data reaches a stable size, or a growing table has increased by tens or some hundreds
of megabytes, consider using the OPTIMIZE TABLE statement to reorganize the table and compact
any wasted space. The reorganized tables require less disk I/O to perform full table scans. This is a
straightforward technique that can improve performance when other techniques such as improving
index usage or tuning application code are not practical.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing InnoDB Transaction Management

OPTIMIZE TABLE copies the data part of the table and rebuilds the indexes. The benefits come
from improved packing of data within indexes, and reduced fragmentation within the tablespaces
and on disk. The benefits vary depending on the data in each table. You may find that there are
significant gains for some and not for others, or that the gains decrease over time until you next
optimize the table. This operation can be slow if the table is large or if the indexes being rebuilt do
not fit into the buffer pool. The first run after adding a lot of data to a table is often much slower than
later runs.
• In InnoDB, having a long PRIMARY KEY (either a single column with a lengthy value, or several
columns that form a long composite value) wastes a lot of disk space. The primary key value for a
row is duplicated in all the secondary index records that point to the same row. (See Section 14.2.10,
“InnoDB Table and Index Structures”.) Create an AUTO_INCREMENT column as the primary key if
your primary key is long, or index a prefix of a long VARCHAR column instead of the entire column.
• Use the VARCHAR data type instead of CHAR to store variable-length strings or for columns with many
NULL values. A CHAR(N) column always takes N characters to store data, even if the string is shorter
or its value is NULL. Smaller tables fit better in the buffer pool and reduce disk I/O.
When using COMPACT row format (the default InnoDB format) and variable-length character sets,
such as utf8 or sjis, CHAR(N) columns occupy a variable amount of space, but still at least N
bytes.
• For tables that are big, or contain lots of repetitive text or numeric data, consider using COMPRESSED
row format. Less disk I/O is required to bring data into the buffer pool, or to perform full table scans.
Before making a permanent decision, measure the amount of compression you can achieve by using
COMPRESSED versus COMPACT row format.

8.6.2 Optimizing InnoDB Transaction Management
To optimize InnoDB transaction processing, find the ideal balance between the performance overhead
of transactional features and the workload of your server. For example, an application might encounter
performance issues if it commits thousands of times per second, and different performance issues if it
commits only every 2-3 hours.
• The default MySQL setting AUTOCOMMIT=1 can impose performance limitations on a busy database
server. Where practical, wrap several related DML operations into a single transaction, by issuing
SET AUTOCOMMIT=0 or a START TRANSACTION statement, followed by a COMMIT statement after
making all the changes.
InnoDB must flush the log to disk at each transaction commit if that transaction made modifications
to the database. When each change is followed by a commit (as with the default autocommit setting),
the I/O throughput of the storage device puts a cap on the number of potential operations per
second.
• Avoid performing rollbacks after inserting, updating, or deleting huge numbers of rows. If a big
transaction is slowing down server performance, rolling it back can make the problem worse,
potentially taking several times as long to perform as the original DML operations. Killing the
database process does not help, because the rollback starts again on server startup.
To minimize the chance of this issue occurring:
• Increase the size of the buffer pool so that all the DML changes can be cached rather than
immediately written to disk.
• Consider issuing COMMIT statements periodically during the big DML operation, possibly breaking
a single delete or update into multiple statements that operate on smaller numbers of rows.
To get rid of a runaway rollback once it occurs, increase the buffer pool so that the rollback becomes
CPU-bound and runs fast, or kill the server and restart with innodb_force_recovery=3, as
explained in Section 14.2.6.1, “The InnoDB Recovery Process”.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing InnoDB Redo Logging

• If you can afford the loss of some of the latest committed transactions if a crash occurs, you can set
the innodb_flush_log_at_trx_commit parameter to 0. InnoDB tries to flush the log once per
second anyway, although the flush is not guaranteed. Also, set the value of innodb_support_xa
to 0, which will reduce the number of disk flushes due to synchronizing on disk data and the binary
log.
• When rows are modified or deleted, the rows and associated undo logs are not physically removed
immediately, or even immediately after the transaction commits. The old data is preserved until
transactions that started earlier or concurrently are finished, so that those transactions can access
the previous state of modified or deleted rows. Thus, a long-running transaction can prevent InnoDB
from purging data that was changed by a different transaction.
• When rows are modified or deleted within a long-running transaction, other transactions using the
READ COMMITTED and REPEATABLE READ isolation levels have to do more work to reconstruct the
older data if they read those same rows.
• When a long-running transaction modifies a table, queries against that table from other transactions
do not make use of the covering index technique. Queries that normally could retrieve all the result
columns from a secondary index, instead look up the appropriate values from the table data.

8.6.3 Optimizing InnoDB Redo Logging
Consider the following guidelines for optimizing redo logging:
• Make your redo log files big, even as big as the buffer pool. When InnoDB has written the redo log
files full, it must write the modified contents of the buffer pool to disk in a checkpoint. Small redo log
files cause many unnecessary disk writes. Although historically big redo log files caused lengthy
recovery times, recovery is now much faster and you can confidently use large redo log files.
The size and number of redo log files are configured using the innodb_log_file_size and
innodb_log_files_in_group configuration options. For information about modifying an existing
redo log file configuration, see Section 14.2.4, “Changing the Number or Size of InnoDB Redo Log
Files”.
• Consider increasing the size of the log_buffer. A large log buffer enables large transactions to run
without a need to write the log to disk before the transactions commit. Thus, if you have transactions
that update, insert, or delete many rows, making the log buffer larger saves disk I/O. Log buffer size
is configured using the innodb_log_buffer_size configuration option.

8.6.4 Bulk Data Loading for InnoDB Tables
These performance tips supplement the general guidelines for fast inserts in Section 8.2.2.1, “Speed of
INSERT Statements”.
• When importing data into InnoDB, turn off autocommit mode, because it performs a log flush to
disk for every insert. To disable autocommit during your import operation, surround it with SET
autocommit and COMMIT statements:
SET autocommit=0;
... SQL import statements ...
COMMIT;

The mysqldump option --opt creates dump files that are fast to import into an InnoDB table, even
without wrapping them with the SET autocommit and COMMIT statements.
• If you have UNIQUE constraints on secondary keys, you can speed up table imports by temporarily
turning off the uniqueness checks during the import session:
SET unique_checks=0;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing InnoDB Queries

... SQL import statements ...
SET unique_checks=1;

For big tables, this saves a lot of disk I/O because InnoDB can use its change buffer to write
secondary index records in a batch. Be certain that the data contains no duplicate keys.
• If you have FOREIGN KEY constraints in your tables, you can speed up table imports by turning off
the foreign key checks for the duration of the import session:
SET foreign_key_checks=0;
... SQL import statements ...
SET foreign_key_checks=1;

For big tables, this can save a lot of disk I/O.
• Use the multiple-row INSERT syntax to reduce communication overhead between the client and the
server if you need to insert many rows:
INSERT INTO yourtable VALUES (1,2), (5,5), ...;

This tip is valid for inserts into any table, not just InnoDB tables.

8.6.5 Optimizing InnoDB Queries
To tune queries for InnoDB tables, create an appropriate set of indexes on each table. See
Section 8.3.1, “How MySQL Uses Indexes” for details. Follow these guidelines for InnoDB indexes:
• Because each InnoDB table has a primary key (whether you request one or not), specify a set of
primary key columns for each table, columns that are used in the most important and time-critical
queries.
• Do not specify too many or too long columns in the primary key, because these column values are
duplicated in each secondary index. When an index contains unnecessary data, the I/O to read this
data and memory to cache it reduce the performance and scalability of the server.
• Do not create a separate secondary index for each column, because each query can only make
use of one index. Indexes on rarely tested columns or columns with only a few different values
might not be helpful for any queries. If you have many queries for the same table, testing different
combinations of columns, try to create a small number of concatenated indexes rather than a large
number of single-column indexes. If an index contains all the columns needed for the result set
(known as a covering index), the query might be able to avoid reading the table data at all.
• If an indexed column cannot contain any NULL values, declare it as NOT NULL when you create the
table. The optimizer can better determine which index is most effective to use for a query, when it
knows whether each column contains NULL values.
• If you often have recurring queries for tables that are not updated frequently, enable the query cache:
[mysqld]
query_cache_type = 1
query_cache_size = 10M

8.6.6 Optimizing InnoDB DDL Operations
• “Fast index creation” makes it faster in some cases to drop an index before loading data into a table,
then re-create the index after loading the data.
• Use TRUNCATE TABLE to empty a table, not DELETE FROM tbl_name. Foreign key constraints
can make a TRUNCATE statement work like a regular DELETE statement, in which case a sequence
of commands like DROP TABLE and CREATE TABLE might be fastest.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing InnoDB Disk I/O

• Because the primary key is integral to the storage layout of each InnoDB table, and changing the
definition of the primary key involves reorganizing the whole table, always set up the primary key as
part of the CREATE TABLE statement, and plan ahead so that you do not need to ALTER or DROP
the primary key afterward.

8.6.7 Optimizing InnoDB Disk I/O
If you follow the best practices for database design and the tuning techniques for SQL operations, but
your database is still slowed by heavy disk I/O activity, explore these low-level techniques related to
disk I/O. If the Unix top tool or the Windows Task Manager shows that the CPU usage percentage with
your workload is less than 70%, your workload is probably disk-bound.
• When table data is cached in the InnoDB buffer pool, it can be accessed repeatedly
by queries without requiring any disk I/O. Specify the size of the buffer pool with the
innodb_buffer_pool_size option. This memory area is important enough that busy databases
often specify a size approximately 80% of the amount of physical memory. For more information, see
Section 8.10.2, “The InnoDB Buffer Pool”.
• In some versions of GNU/Linux and Unix, flushing files to disk with the Unix fsync() call (which
InnoDB uses by default) and similar methods is surprisingly slow. If database write performance is
an issue, conduct benchmarks with the innodb_flush_method parameter set to O_DSYNC.
• When using the InnoDB storage engine on Solaris 10 for x86_64 architecture (AMD Opteron),
use direct I/O for InnoDB-related files, to avoid degradation of InnoDB performance. To use
direct I/O for an entire UFS file system used for storing InnoDB-related files, mount it with the
forcedirectio option; see mount_ufs(1M). (The default on Solaris 10/x86_64 is not to use this
option.) Alternatively, as of MySQL 5.0.42, to apply direct I/O only to InnoDB file operations rather
than the whole file system, set innodb_flush_method = O_DIRECT. With this setting, InnoDB
calls directio() instead of fcntl() for I/O to data files (not for I/O to log files).
• When using the InnoDB storage engine with a large innodb_buffer_pool_size value on any
release of Solaris 2.6 and up and any platform (sparc/x86/x64/amd64), conduct benchmarks with
InnoDB data files and log files on raw devices or on a separate direct I/O UFS file system, using the
forcedirectio mount option as described earlier. (It is necessary to use the mount option rather
than setting innodb_flush_method if you want direct I/O for the log files.) Users of the Veritas file
system VxFS should use the convosync=direct mount option.
Do not place other MySQL data files, such as those for MyISAM tables, on a direct I/O file system.
Executables or libraries must not be placed on a direct I/O file system.
• If you have additional storage devices available to set up a RAID configuration or symbolic links to
different disks, Section 8.12.3, “Optimizing Disk I/O” for additional low-level I/O tips.
• Other InnoDB configuration options to consider when tuning I/O-bound workloads include
innodb_log_buffer_size, innodb_log_file_size, innodb_max_dirty_pages_pct,
innodb_max_purge_lag, innodb_open_files, and sync_binlog.

8.6.8 Optimizing InnoDB for Systems with Many Tables
• InnoDB computes index cardinality values for a table the first time that table is accessed after
startup, instead of storing such values in the table. This step can take significant time on systems
that partition the data into many tables. Since this overhead only applies to the initial table open
operation, to “warm up” a table for later use, access it immediately after startup by issuing a
statement such as SELECT 1 FROM tbl_name LIMIT 1.

8.7 Optimizing for MEMORY Tables
Consider using MEMORY tables for noncritical data that is accessed often, and is read-only or rarely
updated. Benchmark your application against equivalent InnoDB or MyISAM tables under a realistic
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Understanding the Query Execution Plan

workload, to confirm that any additional performance is worth the risk of losing data, or the overhead of
copying data from a disk-based table at application start.
For best performance with MEMORY tables, examine the kinds of queries against each table, and
specify the type to use for each associated index, either a B-tree index or a hash index. On the CREATE
INDEX statement, use the clause USING BTREE or USING HASH. B-tree indexes are fast for queries
that do greater-than or less-than comparisons through operators such as > or BETWEEN. Hash indexes
are only fast for queries that look up single values through the = operator, or a restricted set of values
through the IN operator. For why USING BTREE is often a better choice than the default USING HASH,
see Section 8.2.1.17, “How to Avoid Full Table Scans”. For implementation details of the different types
of MEMORY indexes, see Section 8.3.8, “Comparison of B-Tree and Hash Indexes”.

8.8 Understanding the Query Execution Plan
Depending on the details of your tables, columns, indexes, and the conditions in your WHERE clause,
the MySQL optimizer considers many techniques to efficiently perform the lookups involved in an SQL
query. A query on a huge table can be performed without reading all the rows; a join involving several
tables can be performed without comparing every combination of rows. The set of operations that the
optimizer chooses to perform the most efficient query is called the “query execution plan”, also known
as the EXPLAIN plan. Your goals are to recognize the aspects of the EXPLAIN plan that indicate a
query is optimized well, and to learn the SQL syntax and indexing techniques to improve the plan if you
see some inefficient operations.

8.8.1 Optimizing Queries with EXPLAIN
The EXPLAIN statement can be used to obtain information about how MySQL executes a statement:
• When you precede a SELECT statement with the keyword EXPLAIN, MySQL displays information
from the optimizer about the statement execution plan. That is, MySQL explains how it would
process the statement, including information about how tables are joined and in which order. For
information about using EXPLAIN to obtain execution plan information, see Section 8.8.2, “EXPLAIN
Output Format”.
• EXPLAIN EXTENDED can be used to obtain additional execution plan information. See Section 8.8.3,
“EXPLAIN EXTENDED Output Format”.
With the help of EXPLAIN, you can see where you should add indexes to tables so that the statement
executes faster by using indexes to find rows. You can also use EXPLAIN to check whether the
optimizer joins the tables in an optimal order. To give a hint to the optimizer to use a join order
corresponding to the order in which the tables are named in a SELECT statement, begin the statement
with SELECT STRAIGHT_JOIN rather than just SELECT. (See Section 13.2.8, “SELECT Syntax”.)
If you have a problem with indexes not being used when you believe that they should be, run ANALYZE
TABLE to update table statistics, such as cardinality of keys, that can affect the choices the optimizer
makes. See Section 13.7.2.1, “ANALYZE TABLE Syntax”.
Note
EXPLAIN can also be used to obtain information about the columns in a
table. EXPLAIN tbl_name is synonymous with DESCRIBE tbl_name and
SHOW COLUMNS FROM tbl_name. For more information, see Section 13.8.1,
“DESCRIBE Syntax”, and Section 13.7.5.5, “SHOW COLUMNS Syntax”.

8.8.2 EXPLAIN Output Format
The EXPLAIN statement provides information about the execution plan for a SELECT statement.
EXPLAIN returns a row of information for each table used in the SELECT statement. It lists the tables in
the output in the order that MySQL would read them while processing the statement. MySQL resolves
all joins using a nested-loop join method. This means that MySQL reads a row from the first table,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

and then finds a matching row in the second table, the third table, and so on. When all tables are
processed, MySQL outputs the selected columns and backtracks through the table list until a table is
found for which there are more matching rows. The next row is read from this table and the process
continues with the next table.
When the EXTENDED keyword is used, EXPLAIN produces extra information that can be viewed by
issuing a SHOW WARNINGS statement following the EXPLAIN statement. See Section 8.8.3, “EXPLAIN
EXTENDED Output Format”.
• EXPLAIN Output Columns
• EXPLAIN Join Types
• EXPLAIN Extra Information
• EXPLAIN Output Interpretation

EXPLAIN Output Columns
This section describes the output columns produced by EXPLAIN. Later sections provide additional
information about the type and Extra columns.
Each output row from EXPLAIN provides information about one table. Each row contains the values
summarized in Table 8.1, “EXPLAIN Output Columns”, and described in more detail following the table.
Table 8.1 EXPLAIN Output Columns
Column

Meaning

id

The SELECT identifier

select_type

The SELECT type

table

The table for the output row

type

The join type

possible_keys

The possible indexes to choose

key

The index actually chosen

key_len

The length of the chosen key

ref

The columns compared to the index

rows

Estimate of rows to be examined

Extra

Additional information

• id
The SELECT identifier. This is the sequential number of the SELECT within the query. The value can
be NULL if the row refers to the union result of other rows. In this case, the table column shows a
value like  to indicate that the row refers to the union of the rows with id values of M
and N.
• select_type
The type of SELECT, which can be any of those shown in the following table.
select_type Value

Meaning

SIMPLE

Simple SELECT (not using UNION or subqueries)

PRIMARY

Outermost SELECT

UNION

Second or later SELECT statement in a UNION

DEPENDENT UNION

Second or later SELECT statement in a UNION, dependent on outer query

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

select_type Value

Meaning

UNION RESULT

Result of a UNION.

SUBQUERY

First SELECT in subquery

DEPENDENT
SUBQUERY

First SELECT in subquery, dependent on outer query

DERIVED

Derived table SELECT (subquery in FROM clause)

UNCACHEABLE
SUBQUERY

A subquery for which the result cannot be cached and must be reevaluated for each row of the outer query

DEPENDENT typically signifies the use of a correlated subquery. See Section 13.2.9.7, “Correlated
Subqueries”.
DEPENDENT SUBQUERY evaluation differs from UNCACHEABLE SUBQUERY evaluation. For
DEPENDENT SUBQUERY, the subquery is re-evaluated only once for each set of different values of
the variables from its outer context. For UNCACHEABLE SUBQUERY, the subquery is re-evaluated for
each row of the outer context.
Cacheability of subqueries differs from caching of query results in the query cache (which is
described in Section 8.10.3.1, “How the Query Cache Operates”). Subquery caching occurs during
query execution, whereas the query cache is used to store results only after query execution
finishes.
• table
The name of the table to which the row of output refers. This can also be one of the following values:
• : The row refers to the union of the rows with id values of M and N.
• : The row refers to the derived table result for the row with an id value of N. A
derived table may result, for example, from a subquery in the FROM clause.
• type
The join type. For descriptions of the different types, see EXPLAIN Join Types.
• possible_keys
The possible_keys column indicates which indexes MySQL can choose from use to find the rows
in this table. Note that this column is totally independent of the order of the tables as displayed in the
output from EXPLAIN. That means that some of the keys in possible_keys might not be usable in
practice with the generated table order.
If this column is NULL, there are no relevant indexes. In this case, you may be able to improve
the performance of your query by examining the WHERE clause to check whether it refers to some
column or columns that would be suitable for indexing. If so, create an appropriate index and check
the query with EXPLAIN again. See Section 13.1.4, “ALTER TABLE Syntax”.
To see what indexes a table has, use SHOW INDEX FROM tbl_name.
• key
The key column indicates the key (index) that MySQL actually decided to use. If MySQL decides to
use one of the possible_keys indexes to look up rows, that index is listed as the key value.
It is possible that key will name an index that is not present in the possible_keys value. This
can happen if none of the possible_keys indexes are suitable for looking up rows, but all the
columns selected by the query are columns of some other index. That is, the named index covers
the selected columns, so although it is not used to determine which rows to retrieve, an index scan is
more efficient than a data row scan.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

For InnoDB, a secondary index might cover the selected columns even if the query also selects
the primary key because InnoDB stores the primary key value with each secondary index. If key is
NULL, MySQL found no index to use for executing the query more efficiently.
To force MySQL to use or ignore an index listed in the possible_keys column, use FORCE
INDEX, USE INDEX, or IGNORE INDEX in your query. See Section 8.9.2, “Index Hints”.
For MyISAM, NDB, and BDB tables, running ANALYZE TABLE helps the optimizer choose better
indexes. For MyISAM tables, myisamchk --analyze does the same as ANALYZE TABLE. See
Section 7.6, “MyISAM Table Maintenance and Crash Recovery”.
• key_len
The key_len column indicates the length of the key that MySQL decided to use. The length is NULL
if the key column says NULL. Note that the value of key_len enables you to determine how many
parts of a multiple-part key MySQL actually uses.
• ref
The ref column shows which columns or constants are compared to the index named in the key
column to select rows from the table.
• rows
The rows column indicates the number of rows MySQL believes it must examine to execute the
query.
For InnoDB tables, this number is an estimate, and may not always be exact.
• Extra
This column contains additional information about how MySQL resolves the query. For descriptions
of the different values, see EXPLAIN Extra Information.

EXPLAIN Join Types
The type column of EXPLAIN output describes how tables are joined. The following list describes the
join types, ordered from the best type to the worst:
•

system
The table has only one row (= system table). This is a special case of the const join type.

•

const
The table has at most one matching row, which is read at the start of the query. Because there is
only one row, values from the column in this row can be regarded as constants by the rest of the
optimizer. const tables are very fast because they are read only once.
const is used when you compare all parts of a PRIMARY KEY or UNIQUE index to constant values.
In the following queries, tbl_name can be used as a const table:
SELECT * FROM tbl_name WHERE primary_key=1;
SELECT * FROM tbl_name
WHERE primary_key_part1=1 AND primary_key_part2=2;

•

eq_ref
One row is read from this table for each combination of rows from the previous tables. Other than the
system and const types, this is the best possible join type. It is used when all parts of an index are
used by the join and the index is a PRIMARY KEY or UNIQUE NOT NULL index.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

eq_ref can be used for indexed columns that are compared using the = operator. The comparison
value can be a constant or an expression that uses columns from tables that are read before this
table. In the following examples, MySQL can use an eq_ref join to process ref_table:
SELECT * FROM ref_table,other_table
WHERE ref_table.key_column=other_table.column;
SELECT * FROM ref_table,other_table
WHERE ref_table.key_column_part1=other_table.column
AND ref_table.key_column_part2=1;

•

ref
All rows with matching index values are read from this table for each combination of rows from the
previous tables. ref is used if the join uses only a leftmost prefix of the key or if the key is not a
PRIMARY KEY or UNIQUE index (in other words, if the join cannot select a single row based on the
key value). If the key that is used matches only a few rows, this is a good join type.
ref can be used for indexed columns that are compared using the = or <=> operator. In the
following examples, MySQL can use a ref join to process ref_table:
SELECT * FROM ref_table WHERE key_column=expr;
SELECT * FROM ref_table,other_table
WHERE ref_table.key_column=other_table.column;
SELECT * FROM ref_table,other_table
WHERE ref_table.key_column_part1=other_table.column
AND ref_table.key_column_part2=1;

•

fulltext
The join is performed using a FULLTEXT index.

•

ref_or_null
This join type is like ref, but with the addition that MySQL does an extra search for rows that contain
NULL values. This join type optimization is used most often in resolving subqueries. In the following
examples, MySQL can use a ref_or_null join to process ref_table:
SELECT * FROM ref_table
WHERE key_column=expr OR key_column IS NULL;

See Section 8.2.1.6, “IS NULL Optimization”.
•

index_merge
This join type indicates that the Index Merge optimization is used. In this case, the key column in the
output row contains a list of indexes used, and key_len contains a list of the longest key parts for
the indexes used. For more information, see Section 8.2.1.4, “Index Merge Optimization”.

•

unique_subquery
This type replaces eq_ref for some IN subqueries of the following form:
value IN (SELECT primary_key FROM single_table WHERE some_expr)

unique_subquery is just an index lookup function that replaces the subquery completely for better
efficiency.
•

index_subquery

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

This join type is similar to unique_subquery. It replaces IN subqueries, but it works for nonunique
indexes in subqueries of the following form:
value IN (SELECT key_column FROM single_table WHERE some_expr)

•

range
Only rows that are in a given range are retrieved, using an index to select the rows. The key column
in the output row indicates which index is used. The key_len contains the longest key part that was
used. The ref column is NULL for this type.
range can be used when a key column is compared to a constant using any of the =, <>, >, >=, <,
<=, IS NULL, <=>, BETWEEN, or IN() operators:
SELECT * FROM tbl_name
WHERE key_column = 10;
SELECT * FROM tbl_name
WHERE key_column BETWEEN 10 and 20;
SELECT * FROM tbl_name
WHERE key_column IN (10,20,30);
SELECT * FROM tbl_name
WHERE key_part1= 10 AND key_part2 IN (10,20,30);

•

index
The index join type is the same as ALL, except that the index tree is scanned. This occurs two
ways:
• If the index is a covering index for the queries and can be used to satisfy all data required from
the table, only the index tree is scanned. In this case, the Extra column says Using index. An
index-only scan usually is faster than ALL because the size of the index usually is smaller than the
table data.
• A full table scan is performed using reads from the index to look up data rows in index order. Uses
index does not appear in the Extra column.
MySQL can use this join type when the query uses only columns that are part of a single index.

•

ALL
A full table scan is done for each combination of rows from the previous tables. This is normally
not good if the table is the first table not marked const, and usually very bad in all other cases.
Normally, you can avoid ALL by adding indexes that enable row retrieval from the table based on
constant values or column values from earlier tables.

EXPLAIN Extra Information
The Extra column of EXPLAIN output contains additional information about how MySQL resolves the
query. The following list explains the values that can appear in this column. If you want to make your
queries as fast as possible, look out for Extra values of Using filesort and Using temporary.
• const row not found
For a query such as SELECT ... FROM tbl_name, the table was empty.
• Distinct
MySQL is looking for distinct values, so it stops searching for more rows for the current row
combination after it has found the first matching row.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

• Full scan on NULL key
This occurs for subquery optimization as a fallback strategy when the optimizer cannot use an indexlookup access method.
• Impossible HAVING
The HAVING clause is always false and cannot select any rows.
• Impossible WHERE
The WHERE clause is always false and cannot select any rows.
• Impossible WHERE noticed after reading const tables
MySQL has read all const (and system) tables and notice that the WHERE clause is always false.
• No matching min/max row
No row satisfies the condition for a query such as SELECT MIN(...) FROM ... WHERE
condition.
• no matching row in const table
For a query with a join, there was an empty table or a table with no rows satisfying a unique index
condition.
• No tables used
The query has no FROM clause, or has a FROM DUAL clause.
• Not exists
MySQL was able to do a LEFT JOIN optimization on the query and does not examine more rows
in this table for the previous row combination after it finds one row that matches the LEFT JOIN
criteria. Here is an example of the type of query that can be optimized this way:
SELECT * FROM t1 LEFT JOIN t2 ON t1.id=t2.id
WHERE t2.id IS NULL;

Assume that t2.id is defined as NOT NULL. In this case, MySQL scans t1 and looks up the rows
in t2 using the values of t1.id. If MySQL finds a matching row in t2, it knows that t2.id can
never be NULL, and does not scan through the rest of the rows in t2 that have the same id value.
In other words, for each row in t1, MySQL needs to do only a single lookup in t2, regardless of how
many rows actually match in t2.
• Range checked for each record (index map: N)
MySQL found no good index to use, but found that some of indexes might be used after column
values from preceding tables are known. For each row combination in the preceding tables, MySQL
checks whether it is possible to use a range or index_merge access method to retrieve rows. This
is not very fast, but is faster than performing a join with no index at all. The applicability criteria are as
described in Section 8.2.1.3, “Range Optimization”, and Section 8.2.1.4, “Index Merge Optimization”,
with the exception that all column values for the preceding table are known and considered to be
constants.
Indexes are numbered beginning with 1, in the same order as shown by SHOW INDEX for the table.
The index map value N is a bitmask value that indicates which indexes are candidates. For example,
a value of 0x19 (binary 11001) means that indexes 1, 4, and 5 will be considered.
• Select tables optimized away
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

The optimizer determined 1) that at most one row should be returned, and 2) that to produce this
row, a deterministic set of rows must be read. When the rows to be read can be read during the
optimization phase (for example, by reading index rows), there is no need to read any tables during
query execution.
The first condition is fulfilled when the query is implicitly grouped (contains an aggregate function but
no GROUP BY clause). The second condition is fulfilled when one row lookup is performed per index
used. The number of indexes read determines the number of rows to read.
Consider the following implicitly grouped query:
SELECT MIN(c1), MIN(c2) FROM t1;

Suppose that MIN(c1) can be retrieved by reading one index row and MIN(c2) can be retrieved
by reading one row from a different index. That is, for each column c1 and c2, there exists an index
where the column is the first column of the index. In this case, one row is returned, produced by
reading two deterministic rows.
This Extra value does not occur if the rows to read are not deterministic. Consider this query:
SELECT MIN(c2) FROM t1 WHERE c1 <= 10;

Suppose that (c1, c2) is a covering index. Using this index, all rows with c1 <= 10 must be
scanned to find the minimum c2 value. By contrast, consider this query:
SELECT MIN(c2) FROM t1 WHERE c1 = 10;

In this case, the first index row with c1 = 10 contains the minimum c2 value. Only one row must be
read to produce the returned row.
For storage engines that maintain an exact row count per table (such as MyISAM, but not InnoDB),
this Extra value can occur for COUNT(*) queries for which the WHERE clause is missing or always
true and there is no GROUP BY clause. (This is an instance of an implicitly grouped query where the
storage engine influences whether a deterministic number of rows can be read.)
• unique row not found
For a query such as SELECT ... FROM tbl_name, no rows satisfy the condition for a UNIQUE
index or PRIMARY KEY on the table.
• Using filesort
MySQL must do an extra pass to find out how to retrieve the rows in sorted order. The sort is done
by going through all rows according to the join type and storing the sort key and pointer to the row for
all rows that match the WHERE clause. The keys then are sorted and the rows are retrieved in sorted
order. See Section 8.2.1.11, “ORDER BY Optimization”.
• Using index
The column information is retrieved from the table using only information in the index tree without
having to do an additional seek to read the actual row. This strategy can be used when the query
uses only columns that are part of a single index.
• Using index for group-by
Similar to the Using index table access method, Using index for group-by indicates that
MySQL found an index that can be used to retrieve all columns of a GROUP BY or DISTINCT query
without any extra disk access to the actual table. Additionally, the index is used in the most efficient
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're

EXPLAIN Output Format

way so that for each group, only a few index entries are read. For details, see Section 8.2.1.12,
“GROUP BY Optimization”.
• Using sort_union(...), Using union(...), Using intersect(...)
These indicate how index scans are merged for the index_merge join type. See Section 8.2.1.4,
“Index Merge Optimization”.
• Using temporary
To resolve the query, MySQL needs to create a temporary table to hold the result. This typically
happens if the query contains GROUP BY and ORDER BY clauses that list columns differently.
• Using where
A WHERE clause is used to restrict which rows to match against the next table or send to the client.
Unless you specifically intend to fetch or examine all rows from the table, you may have something
wrong in your query if the Extra value is not Using where and the table join type is ALL or index.
Even if you are using an index for all parts of a WHERE clause, you may see Using where if the
column can be NULL.
• Using where with pushed condition
This item applies to NDB tables only. It means that MySQL Cluster is using the Condition Pushdown
optimization to improve the efficiency of a direct comparison between a nonindexed column and a
constant. In such cases, the condition is “pushed down” to the cluster's data nodes and is evaluated
on all data nodes simultaneously. This eliminates the need to send nonmatching rows over the
network, and can speed up such queries by a factor of 5 to 10 times over cases where Condition
Pushdown could be but is not used. For more information, see Section 8.2.1.5, “Engine Condition
Pushdown Optimization”.

EXPLAIN Output Interpretation
You can get a good indication of how good a join is by taking the product of the values in the rows
column of the EXPLAIN output. This should tell you roughly how many rows MySQL must examine to
execute the query. If you restrict queries with the max_join_size system variable, this row product
also is used to determine which multiple-table SELECT statements to execute and which to abort. See
Section 8.12.2, “Tuning Server Parameters”.
The following example shows how a multiple-table join can be optimized progressively based on the
information provided by EXPLAIN.
Suppose that you have the SELECT statement shown here and that you plan to examine it using
EXPLAIN:
EXPLAIN SELECT tt.TicketNumber, tt.TimeIn,
tt.ProjectReference, tt.EstimatedShipDate,
tt.ActualShipDate, tt.ClientID,
tt.ServiceCodes, tt.RepetitiveID,
tt.CurrentProcess, tt.CurrentDPPerson,
tt.RecordVolume, tt.DPPrinted, et.COUNTRY,
et_1.COUNTRY, do.CUSTNAME
FROM tt, et, et AS et_1, do
WHERE tt.SubmitTime IS NULL
AND tt.ActualPC = et.EMPLOYID
AND tt.AssignedPC = et_1.EMPLOYID
AND tt.ClientID = do.CUSTNMBR;

For this example, make the following assumptions:
• The columns being compared have been declared as follows.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN Output Format

Table

Column

Data Type

tt

ActualPC

CHAR(10)

tt

AssignedPC

CHAR(10)

tt

ClientID

CHAR(10)

et

EMPLOYID

CHAR(15)

do

CUSTNMBR

CHAR(15)

• The tables have the following indexes.
Table

Index

tt

ActualPC

tt

AssignedPC

tt

ClientID

et

EMPLOYID (primary key)

do

CUSTNMBR (primary key)

• The tt.ActualPC values are not evenly distributed.
Initially, before any optimizations have been performed, the EXPLAIN statement produces the following
information:
table
et
do
et_1
tt

type
ALL
ALL
ALL
ALL

possible_keys key key_len ref
PRIMARY
NULL NULL
NULL
PRIMARY
NULL NULL
NULL
PRIMARY
NULL NULL
NULL
AssignedPC,
NULL NULL
NULL
ClientID,
ActualPC
Range checked for each record (index

rows
74
2135
74
3872

Extra

map: 0x23)

Because type is ALL for each table, this output indicates that MySQL is generating a Cartesian
product of all the tables; that is, every combination of rows. This takes quite a long time, because the
product of the number of rows in each table must be examined. For the case at hand, this product is 74
× 2135 × 74 × 3872 = 45,268,558,720 rows. If the tables were bigger, you can only imagine how long it
would take.
One problem here is that MySQL can use indexes on columns more efficiently if they are declared
as the same type and size. In this context, VARCHAR and CHAR are considered the same if they are
declared as the same size. tt.ActualPC is declared as CHAR(10) and et.EMPLOYID is CHAR(15),
so there is a length mismatch.
To fix this disparity between column lengths, use ALTER TABLE to lengthen ActualPC from 10
characters to 15 characters:
mysql> ALTER TABLE tt MODIFY ActualPC VARCHAR(15);

Now tt.ActualPC and et.EMPLOYID are both VARCHAR(15). Executing the EXPLAIN statement
again produces this result:
table type
tt
ALL

ref
NULL

rows
3872

do

NULL
map: 0x1)
NULL

2135

et_1

This
documentation
is for an
older version.
If you're

possible_keys key
key_len
AssignedPC,
NULL
NULL
ClientID,
ActualPC
ALL
PRIMARY
NULL
NULL
Range checked for each record (index
ALL
PRIMARY
NULL
NULL

Extra
Using
where

74

This
documentation
is for an
older version.
If you're

EXPLAIN EXTENDED Output Format

et

Range checked for each record (index map: 0x1)
eq_ref PRIMARY
PRIMARY 15
tt.ActualPC 1

This is not perfect, but is much better: The product of the rows values is less by a factor of 74. This
version executes in a couple of seconds.
A second alteration can be made to eliminate the column length mismatches for the tt.AssignedPC
= et_1.EMPLOYID and tt.ClientID = do.CUSTNMBR comparisons:
mysql> ALTER TABLE tt MODIFY AssignedPC VARCHAR(15),
->
MODIFY ClientID
VARCHAR(15);

After that modification, EXPLAIN produces the output shown here:
table type
et
ALL
tt
ref

possible_keys
PRIMARY
AssignedPC,
ClientID,
ActualPC
eq_ref PRIMARY
eq_ref PRIMARY

key
key_len ref
NULL
NULL
NULL
ActualPC 15
et.EMPLOYID

et_1
do

PRIMARY
PRIMARY

15
15

rows Extra
74
52
Using
where

tt.AssignedPC 1
tt.ClientID
1

At this point, the query is optimized almost as well as possible. The remaining problem is that, by
default, MySQL assumes that values in the tt.ActualPC column are evenly distributed, and that is
not the case for the tt table. Fortunately, it is easy to tell MySQL to analyze the key distribution:
mysql> ANALYZE TABLE tt;

With the additional index information, the join is perfect and EXPLAIN produces this result:
table type
tt
ALL

possible_keys
AssignedPC
ClientID,
ActualPC
eq_ref PRIMARY
eq_ref PRIMARY
eq_ref PRIMARY

key
NULL

key_len ref
NULL
NULL

et
et_1
do

PRIMARY 15
PRIMARY 15
PRIMARY 15

rows Extra
3872 Using
where

tt.ActualPC
1
tt.AssignedPC 1
tt.ClientID
1

The rows column in the output from EXPLAIN is an educated guess from the MySQL join optimizer.
You should check whether the numbers are even close to the truth by comparing the rows product
with the actual number of rows that the query returns. If the numbers are quite different, you might get
better performance by using STRAIGHT_JOIN in your SELECT statement and trying to list the tables in
a different order in the FROM clause.
It is possible in some cases to execute statements that modify data when EXPLAIN SELECT is used
with a subquery; for more information, see Section 13.2.9.8, “Subqueries in the FROM Clause”.

8.8.3 EXPLAIN EXTENDED Output Format
When EXPLAIN is used with the EXTENDED keyword, the output includes a filtered column not
otherwise displayed. This column indicates the estimated percentage of table rows that will be filtered
by the table condition. In addition, the statement produces extra information that can be viewed by
issuing a SHOW WARNINGS statement following the EXPLAIN statement. The Message value in
SHOW WARNINGS output displays how the optimizer qualifies table and column names in the SELECT
statement, what the SELECT looks like after the application of rewriting and optimization rules, and
possibly other notes about the optimization process.
Here is an example of extended output:
mysql> EXPLAIN EXTENDED
-> SELECT t1.a, t1.a IN (SELECT t2.a FROM t2) FROM t1\G
*************************** 1. row ***************************

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

EXPLAIN EXTENDED Output Format

id: 1
select_type: PRIMARY
table: t1
type: index
possible_keys: NULL
key: PRIMARY
key_len: 4
ref: NULL
rows: 4
Extra: Using index
*************************** 2. row ***************************
id: 2
select_type: DEPENDENT SUBQUERY
table: t2
type: index_subquery
possible_keys: a
key: a
key_len: 5
ref: func
rows: 2
Extra: Using index
2 rows in set, 1 warning (0.00 sec)
mysql> SHOW WARNINGS\G
*************************** 1. row ***************************
Level: Note
Code: 1003
Message: select `test`.`t1`.`a` AS `a`,
(`test`.`t1`.`a`,
(((`test`.`t1`.`a`)
in t2 on a checking NULL having
(`test`.`t2`.`a`)))) AS `t1.a
IN (SELECT t2.a FROM t2)` from `test`.`t1`
1 row in set (0.00 sec)

Because the statement displayed by SHOW WARNINGS may contain special markers to provide
information about query rewriting or optimizer actions, the statement is not necessarily valid SQL and
is not intended to be executed. The output may also include rows with Message values that provide
additional non-SQL explanatory notes about actions taken by the optimizer.
The following list describes special markers that can appear in EXTENDED output displayed by SHOW
WARNINGS:
• (expr)
The expression (such as a scalar subquery) is executed once and the resulting value is saved in
memory for later use.
• (query fragment)
The subquery predicate is converted to an EXISTS predicate and the subquery is transformed so
that it can be used together with the EXISTS predicate.
• (query fragment)
This is an internal optimizer object with no user significance.
• (query fragment)
The query fragment is processed using an index lookup to find qualifying rows.
• (expr)
A test to verify that the expression does not evaluate to NULL.
• (query fragment)
The query fragment is processed using a primary key lookup to find qualifying rows.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Estimating Query Performance

• (expr)
This is an internal optimizer object with no user significance.
When some tables are of const or system type, expressions involving columns from these tables
are evaluated early by the optimizer and are not part of the displayed statement. However, with
FORMAT=JSON, some const table accesses are displayed as a ref access that uses a const value.

8.8.4 Estimating Query Performance
In most cases, you can estimate query performance by counting disk seeks. For small tables, you can
usually find a row in one disk seek (because the index is probably cached). For bigger tables, you can
estimate that, using B-tree indexes, you need this many seeks to find a row: log(row_count) /
log(index_block_length / 3 * 2 / (index_length + data_pointer_length)) + 1.
In MySQL, an index block is usually 1,024 bytes and the data pointer is usually four bytes. For a
500,000-row table with a key value length of three bytes (the size of MEDIUMINT), the formula indicates
log(500,000)/log(1024/3*2/(3+4)) + 1 = 4 seeks.
This index would require storage of about 500,000 * 7 * 3/2 = 5.2MB (assuming a typical index buffer fill
ratio of 2/3), so you probably have much of the index in memory and so need only one or two calls to
read data to find the row.
For writes, however, you need four seek requests to find where to place a new index value and
normally two seeks to update the index and write the row.
The preceding discussion does not mean that your application performance slowly degenerates by
log N. As long as everything is cached by the OS or the MySQL server, things become only marginally
slower as the table gets bigger. After the data gets too big to be cached, things start to go much slower
until your applications are bound only by disk seeks (which increase by log N). To avoid this, increase
the key cache size as the data grows. For MyISAM tables, the key cache size is controlled by the
key_buffer_size system variable. See Section 8.12.2, “Tuning Server Parameters”.

8.9 Controlling the Query Optimizer
MySQL provides optimizer control through system variables that affect how query plans are evaluated
index hints.

8.9.1 Controlling Query Plan Evaluation
The task of the query optimizer is to find an optimal plan for executing an SQL query. Because the
difference in performance between “good” and “bad” plans can be orders of magnitude (that is,
seconds versus hours or even days), most query optimizers, including that of MySQL, perform a more
or less exhaustive search for an optimal plan among all possible query evaluation plans. For join
queries, the number of possible plans investigated by the MySQL optimizer grows exponentially with
the number of tables referenced in a query. For small numbers of tables (typically less than 7 to 10)
this is not a problem. However, when larger queries are submitted, the time spent in query optimization
may easily become the major bottleneck in the server's performance.
MySQL 5.0.1 introduces a more flexible method for query optimization that enables the user to control
how exhaustive the optimizer is in its search for an optimal query evaluation plan. The general idea is
that the fewer plans that are investigated by the optimizer, the less time it spends in compiling a query.
On the other hand, because the optimizer skips some plans, it may miss finding an optimal plan.
The behavior of the optimizer with respect to the number of plans it evaluates can be controlled using
two system variables:
• The optimizer_prune_level variable tells the optimizer to skip certain plans based on
estimates of the number of rows accessed for each table. Our experience shows that this kind of
“educated guess” rarely misses optimal plans, and may dramatically reduce query compilation
times. That is why this option is on (optimizer_prune_level=1) by default. However,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Index Hints

if you believe that the optimizer missed a better query plan, this option can be switched off
(optimizer_prune_level=0) with the risk that query compilation may take much longer. Note
that, even with the use of this heuristic, the optimizer still explores a roughly exponential number of
plans.
• The optimizer_search_depth variable tells how far into the “future” of each incomplete plan
the optimizer should look to evaluate whether it should be expanded further. Smaller values of
optimizer_search_depth may result in orders of magnitude smaller query compilation times.
For example, queries with 12, 13, or more tables may easily require hours and even days to
compile if optimizer_search_depth is close to the number of tables in the query. At the same
time, if compiled with optimizer_search_depth equal to 3 or 4, the optimizer may compile
in less than a minute for the same query. If you are unsure of what a reasonable value is for
optimizer_search_depth, this variable can be set to 0 to tell the optimizer to determine the
value automatically.

8.9.2 Index Hints
Index hints give the optimizer information about how to choose indexes during query processing.
Index hints are specified following a table name. (For the general syntax for specifying tables in a
SELECT statement, see Section 13.2.8.2, “JOIN Syntax”.) The syntax for referring to an individual table,
including index hints, looks like this:
tbl_name [[AS] alias] [index_hint]
index_hint:
USE {INDEX|KEY} [FOR JOIN] (index_list)
| IGNORE {INDEX|KEY} [FOR JOIN] (index_list)
| FORCE {INDEX|KEY} [FOR JOIN] (index_list)
index_list:
index_name [, index_name] ...

The USE INDEX (index_list) hint tells MySQL to use only one of the named indexes to find rows
in the table. The alternative syntax IGNORE INDEX (index_list) tells MySQL to not use some
particular index or indexes. These hints are useful if EXPLAIN shows that MySQL is using the wrong
index from the list of possible indexes.
The FORCE INDEX hint acts like USE INDEX (index_list), with the addition that a table scan is
assumed to be very expensive. In other words, a table scan is used only if there is no way to use one
of the named indexes to find rows in the table.
Each hint requires the names of indexes, not the names of columns. To refer to a primary key, use the
name PRIMARY. To see the index names for a table, use SHOW INDEX.
An index_name value need not be a full index name. It can be an unambiguous prefix of an index
name. If a prefix is ambiguous, an error occurs.
USE INDEX, IGNORE INDEX, and FORCE INDEX affect only which indexes are used when MySQL
decides how to find rows in the table and how to do the join. They do not affect whether an index is
used when resolving an ORDER BY or GROUP BY clause. As of MySQL 5.0.40, the optional FOR JOIN
clause can be added to make this explicit.
Examples:
SELECT * FROM table1 USE INDEX (col1_index,col2_index)
WHERE col1=1 AND col2=2 AND col3=3;
SELECT * FROM table1 IGNORE INDEX (col3_index)
WHERE col1=1 AND col2=2 AND col3=3;

For FULLTEXT searches, index hints do not work before MySQL 5.0.74. As of 5.0.74, index hints work
as follows:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Buffering and Caching

• For natural language mode searches, index hints are silently ignored. For example, IGNORE
INDEX(i1) is ignored with no warning and the index is still used.
• For boolean mode searches, index hints are honored.

8.10 Buffering and Caching
MySQL uses several strategies that cache information in memory buffers to increase performance.

8.10.1 The MyISAM Key Cache
To minimize disk I/O, the MyISAM storage engine exploits a strategy that is used by many database
management systems. It employs a cache mechanism to keep the most frequently accessed table
blocks in memory:
• For index blocks, a special structure called the key cache (or key buffer) is maintained. The structure
contains a number of block buffers where the most-used index blocks are placed.
• For data blocks, MySQL uses no special cache. Instead it relies on the native operating system file
system cache.
This section first describes the basic operation of the MyISAM key cache. Then it discusses features
that improve key cache performance and that enable you to better control cache operation:
• Access to the key cache no longer is serialized among threads. Multiple sessions can access the
cache concurrently.
• You can set up multiple key caches and assign table indexes to specific caches.
To control the size of the key cache, use the key_buffer_size system variable. If this variable is set
equal to zero, no key cache is used. The key cache also is not used if the key_buffer_size value is
too small to allocate the minimal number of block buffers (8).
When the key cache is not operational, index files are accessed using only the native file system
buffering provided by the operating system. (In other words, table index blocks are accessed using the
same strategy as that employed for table data blocks.)
An index block is a contiguous unit of access to the MyISAM index files. Usually the size of an index
block is equal to the size of nodes of the index B-tree. (Indexes are represented on disk using a B-tree
data structure. Nodes at the bottom of the tree are leaf nodes. Nodes above the leaf nodes are nonleaf
nodes.)
All block buffers in a key cache structure are the same size. This size can be equal to, greater than, or
less than the size of a table index block. Usually one these two values is a multiple of the other.
When data from any table index block must be accessed, the server first checks whether it is available
in some block buffer of the key cache. If it is, the server accesses data in the key cache rather than
on disk. That is, it reads from the cache or writes into it rather than reading from or writing to disk.
Otherwise, the server chooses a cache block buffer containing a different table index block (or blocks)
and replaces the data there by a copy of required table index block. As soon as the new index block is
in the cache, the index data can be accessed.
If it happens that a block selected for replacement has been modified, the block is considered “dirty.” In
this case, prior to being replaced, its contents are flushed to the table index from which it came.
Usually the server follows an LRU (Least Recently Used) strategy: When choosing a block for
replacement, it selects the least recently used index block. To make this choice easier, the key cache
module maintains all used blocks in a special list (LRU chain) ordered by time of use. When a block
is accessed, it is the most recently used and is placed at the end of the list. When blocks need to be
replaced, blocks at the beginning of the list are the least recently used and become the first candidates
for eviction.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MyISAM Key Cache

The InnoDB storage engine also uses an LRU algorithm, to manage its buffer pool. See
Section 8.10.2, “The InnoDB Buffer Pool”.

8.10.1.1 Shared Key Cache Access
Threads can access key cache buffers simultaneously, subject to the following conditions:
• A buffer that is not being updated can be accessed by multiple sessions.
• A buffer that is being updated causes sessions that need to use it to wait until the update is
complete.
• Multiple sessions can initiate requests that result in cache block replacements, as long as they do not
interfere with each other (that is, as long as they need different index blocks, and thus cause different
cache blocks to be replaced).
Shared access to the key cache enables the server to improve throughput significantly.

8.10.1.2 Multiple Key Caches
Shared access to the key cache improves performance but does not eliminate contention among
sessions entirely. They still compete for control structures that manage access to the key cache
buffers. To reduce key cache access contention further, MySQL also provides multiple key caches.
This feature enables you to assign different table indexes to different key caches.
Where there are multiple key caches, the server must know which cache to use when processing
queries for a given MyISAM table. By default, all MyISAM table indexes are cached in the default
key cache. To assign table indexes to a specific key cache, use the CACHE INDEX statement (see
Section 13.7.6.1, “CACHE INDEX Syntax”). For example, the following statement assigns indexes from
the tables t1, t2, and t3 to the key cache named hot_cache:
mysql> CACHE INDEX t1, t2, t3 IN hot_cache;
+---------+--------------------+----------+----------+
| Table
| Op
| Msg_type | Msg_text |
+---------+--------------------+----------+----------+
| test.t1 | assign_to_keycache | status
| OK
|
| test.t2 | assign_to_keycache | status
| OK
|
| test.t3 | assign_to_keycache | status
| OK
|
+---------+--------------------+----------+----------+

The key cache referred to in a CACHE INDEX statement can be created by setting its size with a SET
GLOBAL parameter setting statement or by using server startup options. For example:
mysql> SET GLOBAL keycache1.key_buffer_size=128*1024;

To destroy a key cache, set its size to zero:
mysql> SET GLOBAL keycache1.key_buffer_size=0;

You cannot destroy the default key cache. Any attempt to do this is ignored:
mysql> SET GLOBAL key_buffer_size = 0;
mysql> SHOW VARIABLES LIKE 'key_buffer_size';
+-----------------+---------+
| Variable_name
| Value
|
+-----------------+---------+
| key_buffer_size | 8384512 |
+-----------------+---------+

Key cache variables are structured system variables that have a name and components. For
keycache1.key_buffer_size, keycache1 is the cache variable name and key_buffer_size
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MyISAM Key Cache

is the cache component. See Section 5.1.5.1, “Structured System Variables”, for a description of the
syntax used for referring to structured key cache system variables.
By default, table indexes are assigned to the main (default) key cache created at the server startup.
When a key cache is destroyed, all indexes assigned to it are reassigned to the default key cache.
For a busy server, you can use a strategy that involves three key caches:
• A “hot” key cache that takes up 20% of the space allocated for all key caches. Use this for tables that
are heavily used for searches but that are not updated.
• A “cold” key cache that takes up 20% of the space allocated for all key caches. Use this cache for
medium-sized, intensively modified tables, such as temporary tables.
• A “warm” key cache that takes up 60% of the key cache space. Employ this as the default key cache,
to be used by default for all other tables.
One reason the use of three key caches is beneficial is that access to one key cache structure does not
block access to the others. Statements that access tables assigned to one cache do not compete with
statements that access tables assigned to another cache. Performance gains occur for other reasons
as well:
• The hot cache is used only for retrieval queries, so its contents are never modified. Consequently,
whenever an index block needs to be pulled in from disk, the contents of the cache block chosen for
replacement need not be flushed first.
• For an index assigned to the hot cache, if there are no queries requiring an index scan, there is a
high probability that the index blocks corresponding to nonleaf nodes of the index B-tree remain in
the cache.
• An update operation most frequently executed for temporary tables is performed much faster when
the updated node is in the cache and need not be read in from disk first. If the size of the indexes of
the temporary tables are comparable with the size of cold key cache, the probability is very high that
the updated node is in the cache.
The CACHE INDEX statement sets up an association between a table and a key cache, but the
association is lost each time the server restarts. If you want the association to take effect each time the
server starts, one way to accomplish this is to use an option file: Include variable settings that configure
your key caches, and an init-file option that names a file containing CACHE INDEX statements to
be executed. For example:
key_buffer_size = 4G
hot_cache.key_buffer_size = 2G
cold_cache.key_buffer_size = 2G
init_file=/path/to/data-directory/mysqld_init.sql

The statements in mysqld_init.sql are executed each time the server starts. The file should
contain one SQL statement per line. The following example assigns several tables each to hot_cache
and cold_cache:
CACHE INDEX db1.t1, db1.t2, db2.t3 IN hot_cache
CACHE INDEX db1.t4, db2.t5, db2.t6 IN cold_cache

8.10.1.3 Midpoint Insertion Strategy
By default, the key cache management system uses a simple LRU strategy for choosing key cache
blocks to be evicted, but it also supports a more sophisticated method called the midpoint insertion
strategy.
When using the midpoint insertion strategy, the LRU chain is divided into two parts: a hot
sublist and a warm sublist. The division point between two parts is not fixed, but the key cache
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MyISAM Key Cache

management system takes care that the warm part is not “too short,” always containing at least
key_cache_division_limit percent of the key cache blocks. key_cache_division_limit is a
component of structured key cache variables, so its value is a parameter that can be set per cache.
When an index block is read from a table into the key cache, it is placed at the end of the warm sublist.
After a certain number of hits (accesses of the block), it is promoted to the hot sublist. At present, the
number of hits required to promote a block (3) is the same for all index blocks.
A block promoted into the hot sublist is placed at the end of the list. The block then circulates within
this sublist. If the block stays at the beginning of the sublist for a long enough time, it is demoted to the
warm sublist. This time is determined by the value of the key_cache_age_threshold component of
the key cache.
The threshold value prescribes that, for a key cache containing N blocks, the block at the beginning of
the hot sublist not accessed within the last N * key_cache_age_threshold / 100 hits is to be
moved to the beginning of the warm sublist. It then becomes the first candidate for eviction, because
blocks for replacement always are taken from the beginning of the warm sublist.
The midpoint insertion strategy enables you to keep more-valued blocks always in the cache. If you
prefer to use the plain LRU strategy, leave the key_cache_division_limit value set to its default
of 100.
The midpoint insertion strategy helps to improve performance when execution of a query that
requires an index scan effectively pushes out of the cache all the index blocks corresponding to
valuable high-level B-tree nodes. To avoid this, you must use a midpoint insertion strategy with the
key_cache_division_limit set to much less than 100. Then valuable frequently hit nodes are
preserved in the hot sublist during an index scan operation as well.

8.10.1.4 Index Preloading
If there are enough blocks in a key cache to hold blocks of an entire index, or at least the blocks
corresponding to its nonleaf nodes, it makes sense to preload the key cache with index blocks before
starting to use it. Preloading enables you to put the table index blocks into a key cache buffer in the
most efficient way: by reading the index blocks from disk sequentially.
Without preloading, the blocks are still placed into the key cache as needed by queries. Although the
blocks will stay in the cache, because there are enough buffers for all of them, they are fetched from
disk in random order, and not sequentially.
To preload an index into a cache, use the LOAD INDEX INTO CACHE statement. For example, the
following statement preloads nodes (index blocks) of indexes of the tables t1 and t2:
mysql> LOAD INDEX INTO CACHE t1, t2 IGNORE LEAVES;
+---------+--------------+----------+----------+
| Table
| Op
| Msg_type | Msg_text |
+---------+--------------+----------+----------+
| test.t1 | preload_keys | status
| OK
|
| test.t2 | preload_keys | status
| OK
|
+---------+--------------+----------+----------+

The IGNORE LEAVES modifier causes only blocks for the nonleaf nodes of the index to be preloaded.
Thus, the statement shown preloads all index blocks from t1, but only blocks for the nonleaf nodes
from t2.
If an index has been assigned to a key cache using a CACHE INDEX statement, preloading places
index blocks into that cache. Otherwise, the index is loaded into the default key cache.

8.10.1.5 Key Cache Block Size
It is possible to specify the size of the block buffers for an individual key cache using the
key_cache_block_size variable. This permits tuning of the performance of I/O operations for index
files.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The InnoDB Buffer Pool

The best performance for I/O operations is achieved when the size of read buffers is equal to the size
of the native operating system I/O buffers. But setting the size of key nodes equal to the size of the I/
O buffer does not always ensure the best overall performance. When reading the big leaf nodes, the
server pulls in a lot of unnecessary data, effectively preventing reading other leaf nodes.
To control the size of blocks in the .MYI index file of MyISAM tables, use the --myisam-block-size
option at server startup.

8.10.1.6 Restructuring a Key Cache
A key cache can be restructured at any time by updating its parameter values. For example:
mysql> SET GLOBAL cold_cache.key_buffer_size=4*1024*1024;

If you assign to either the key_buffer_size or key_cache_block_size key cache component a
value that differs from the component's current value, the server destroys the cache's old structure and
creates a new one based on the new values. If the cache contains any dirty blocks, the server saves
them to disk before destroying and re-creating the cache. Restructuring does not occur if you change
other key cache parameters.
When restructuring a key cache, the server first flushes the contents of any dirty buffers to disk. After
that, the cache contents become unavailable. However, restructuring does not block queries that need
to use indexes assigned to the cache. Instead, the server directly accesses the table indexes using
native file system caching. File system caching is not as efficient as using a key cache, so although
queries execute, a slowdown can be anticipated. After the cache has been restructured, it becomes
available again for caching indexes assigned to it, and the use of file system caching for the indexes
ceases.

8.10.2 The InnoDB Buffer Pool
InnoDB maintains a buffer pool for caching data and indexes in memory. InnoDB manages the pool
as a list, using a least recently used (LRU) algorithm incorporating a midpoint insertion strategy. When
room is needed to add a new block to the pool, InnoDB evicts the least recently used block and adds
the new block to the middle of the list. The midpoint insertion strategy in effect causes the list to be
treated as two sublists:
• At the head, a sublist of “new” (or “young”) blocks that have been recently used.
• At the tail, a sublist of “old” blocks that are less recently used.
As a result of the algorithm, the new sublist contains blocks that are heavily used by queries. The old
sublist contains less-used blocks, and candidates for eviction are taken from this sublist.
The LRU algorithm operates as follows by default:
• 3/8 of the buffer pool is devoted to the old sublist.
• The midpoint of the list is the boundary where the tail of the new sublist meets the head of the old
sublist.
• When InnoDB reads a block into the buffer pool, it initially inserts it at the midpoint (the head of the
old sublist). A block can be read in as a result of two types of read requests: Because it is required
(for example, to satisfy query execution), or as part of read-ahead performed in anticipation that it will
be required.
• The first access to a block in the old sublist makes it “young”, causing it to move to the head of the
buffer pool (the head of the new sublist). If the block was read in because it was required, the first
access occurs immediately and the block is made young. If the block was read in due to read-ahead,
the first access does not occur immediately (and might not occur at all before the block is evicted).
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

• As long as no accesses occur for a block in the pool, it “ages” by moving toward the tail of the list.
Blocks in both the new and old sublists age as other blocks are made new. Blocks in the old sublist
also age as blocks are inserted at the midpoint. Eventually, a block that remains unused for long
enough reaches the tail of the old sublist and is evicted.
In the default operation of the buffer pool, a block when read in is loaded at the midpoint and then
moved immediately to the head of the new sublist as soon as an access occurs. In the case of a table
scan (such as performed for a mysqldump operation), each block read by the scan ends up moving
to the head of the new sublist because multiple rows are accessed from each block. This occurs even
for a one-time scan, where the blocks are not otherwise used by other queries. Blocks may also be
loaded by the read-ahead background thread and then moved to the head of the new sublist by a
single access. These effects can be disadvantageous because they push blocks that are in heavy use
by other queries out of the new sublist to the old sublist where they become subject to eviction.
The innodb_buffer_pool_size system variable specifies the size of the buffer pool. If your buffer
pool is small and you have sufficient memory, making the pool larger can improve performance by
reducing the amount of disk I/O needed as queries access InnoDB tables.
The MyISAM storage engine also uses an LRU algorithm, to manage its key cache. See Section 8.10.1,
“The MyISAM Key Cache”.

8.10.3 The MySQL Query Cache
The query cache stores the text of a SELECT statement together with the corresponding result that was
sent to the client. If an identical statement is received later, the server retrieves the results from the
query cache rather than parsing and executing the statement again. The query cache is shared among
sessions, so a result set generated by one client can be sent in response to the same query issued by
another client.
The query cache can be useful in an environment where you have tables that do not change very
often and for which the server receives many identical queries. This is a typical situation for many Web
servers that generate many dynamic pages based on database content.
The query cache does not return stale data. When tables are modified, any relevant entries in the
query cache are flushed.
Note
The query cache does not work in an environment where you have multiple
mysqld servers updating the same MyISAM tables.
Note
The query cache is not used for prepared statements. If you are using prepared
statements, consider that these statements will not be satisfied by the query
cache. See Section 20.6.8, “C API Prepared Statements”.
Some performance data for the query cache follows. These results were generated by running the
MySQL benchmark suite on a Linux Alpha 2×500MHz system with 2GB RAM and a 64MB query
cache.
• If all the queries you are performing are simple (such as selecting a row from a table with one row),
but still differ so that the queries cannot be cached, the overhead for having the query cache active
is 13%. This could be regarded as the worst case scenario. In real life, queries tend to be much more
complicated, so the overhead normally is significantly lower.
• Searches for a single row in a single-row table are 238% faster with the query cache than without it.
This can be regarded as close to the minimum speedup to be expected for a query that is cached.
To disable the query cache at server startup, set the query_cache_size system variable to 0. By
disabling the query cache code, there is no noticeable overhead. If you build MySQL from source,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

query cache capabilities can be excluded from the server entirely by invoking configure with the -without-query-cache option.
The query cache offers the potential for substantial performance improvement, but you should not
assume that it will do so under all circumstances. With some query cache configurations or server
workloads, you might actually see a performance decrease:
• Be cautious about sizing the query cache excessively large, which increases the overhead required
to maintain the cache, possibly beyond the benefit of enabling it. Sizes in tens of megabytes are
usually beneficial. Sizes in the hundreds of megabytes might not be.
• Server workload has a significant effect on query cache efficiency. A query mix consisting almost
entirely of a fixed set of SELECT statements is much more likely to benefit from enabling the cache
than a mix in which frequent INSERT statements cause continual invalidation of results in the cache.
In some cases, a workaround is to use the SQL_NO_CACHE option to prevent results from even
entering the cache for SELECT statements that use frequently modified tables. (See Section 8.10.3.2,
“Query Cache SELECT Options”.)
To verify that enabling the query cache is beneficial, test the operation of your MySQL server with the
cache enabled and disabled. Then retest periodically because query cache efficiency may change as
server workload changes.

8.10.3.1 How the Query Cache Operates
This section describes how the query cache works when it is operational. Section 8.10.3.3, “Query
Cache Configuration”, describes how to control whether it is operational.
Incoming queries are compared to those in the query cache before parsing, so the following two
queries are regarded as different by the query cache:
SELECT * FROM tbl_name
Select * from tbl_name

Queries must be exactly the same (byte for byte) to be seen as identical. In addition, query strings
that are identical may be treated as different for other reasons. Queries that use different databases,
different protocol versions, or different default character sets are considered different queries and are
cached separately.
Because comparison of a query against those in the cache occurs before parsing, the cache is not
used for queries of the following types:
• Prepared statements
• Queries that are a subquery of an outer query
• Queries executed within the body of a stored function or trigger
Before a query result is fetched from the query cache, MySQL checks whether the user has SELECT
privilege for all databases and tables involved. If this is not the case, the cached result is not used.
If a query result is returned from query cache, the server increments the Qcache_hits status variable,
not Com_select. See Section 8.10.3.4, “Query Cache Status and Maintenance”.
If a table changes, all cached queries that use the table become invalid and are removed from the
cache. This includes queries that use MERGE tables that map to the changed table. A table can be
changed by many types of statements, such as INSERT, UPDATE, DELETE, TRUNCATE TABLE, ALTER
TABLE, DROP TABLE, or DROP DATABASE.
The query cache also works within transactions when using InnoDB tables.
The result from a SELECT query on a view is cached.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

Before MySQL 5.0, a query that began with a leading comment could be cached, but could not be
fetched from the cache. This problem is fixed in MySQL 5.0.
The query cache works for SELECT SQL_CALC_FOUND_ROWS ... queries and stores a value that
is returned by a following SELECT FOUND_ROWS() query. FOUND_ROWS() returns the correct value
even if the preceding query was fetched from the cache because the number of found rows is also
stored in the cache. The SELECT FOUND_ROWS() query itself cannot be cached.
A query cannot be cached if it contains any of the functions shown in the following table.
BENCHMARK()

CONNECTION_ID()

CONVERT_TZ()

CURDATE()

CURRENT_DATE()

CURRENT_TIME()

CURRENT_TIMESTAMP()

CURRENT_USER()

CURTIME()

DATABASE()

ENCRYPT() with one parameter

FOUND_ROWS()

GET_LOCK()

IS_FREE_LOCK()

IS_USED_LOCK()

LAST_INSERT_ID()

LOAD_FILE()

MASTER_POS_WAIT()

NOW()

RAND()

RELEASE_ALL_LOCKS()

RELEASE_LOCK()

SLEEP()

SYSDATE()

UNIX_TIMESTAMP() with no
parameters

USER()

UUID()

A query also is not cached under these conditions:
• It refers to user-defined functions (UDFs) or stored functions.
• It refers to user variables or local stored program variables.
• It refers to tables in the mysql or INFORMATION_SCHEMA system database.
• It is of any of the following forms:
SELECT
SELECT
SELECT
SELECT
SELECT

... LOCK IN SHARE MODE
... FOR UPDATE
... INTO OUTFILE ...
... INTO DUMPFILE ...
* FROM ... WHERE autoincrement_col IS NULL

The last form is not cached because it is used as the ODBC workaround for obtaining the last insert
ID value. See the Connector/ODBC section of Chapter 20, Connectors and APIs.
Statements within transactions that use SERIALIZABLE isolation level also cannot be cached
because they use LOCK IN SHARE MODE locking.
• It was issued as a prepared statement, even if no placeholders were employed. For example, the
query used here is not cached:
char *my_sql_stmt = "SELECT a, b FROM table_c";
/* ... */
mysql_stmt_prepare(stmt, my_sql_stmt, strlen(my_sql_stmt));

See Section 20.6.8, “C API Prepared Statements”.
• It uses TEMPORARY tables.
• It does not use any tables.
• It generates warnings.
• The user has a column-level privilege for any of the involved tables.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

8.10.3.2 Query Cache SELECT Options
Two query cache-related options may be specified in SELECT statements:
• SQL_CACHE
The query result is cached if it is cacheable and the value of the query_cache_type system
variable is ON or DEMAND.
•
SQL_NO_CACHE
The server does not use the query cache. It neither checks the query cache to see whether the
result is already cached, nor does it cache the query result. (Due to a limitation in the parser, a space
character must precede and follow the SQL_NO_CACHE keyword; a nonspace such as a newline
causes the server to check the query cache to see whether the result is already cached.)
Examples:
SELECT SQL_CACHE id, name FROM customer;
SELECT SQL_NO_CACHE id, name FROM customer;

8.10.3.3 Query Cache Configuration
The have_query_cache server system variable indicates whether the query cache is available:
mysql> SHOW VARIABLES LIKE 'have_query_cache';
+------------------+-------+
| Variable_name
| Value |
+------------------+-------+
| have_query_cache | YES
|
+------------------+-------+

When using a standard MySQL binary, this value is always YES, even if query caching is disabled.
Several other system variables control query cache operation. These can be set in an option file or
on the command line when starting mysqld. The query cache system variables all have names that
begin with query_cache_. They are described briefly in Section 5.1.4, “Server System Variables”,
with additional configuration information given here.
To set the size of the query cache, set the query_cache_size system variable. Setting it to 0
disables the query cache. The default size is 0, so the query cache is disabled by default.
Be careful not to set the size of the cache too large. Due to the need for threads to lock the cache
during updates, you may see lock contention issues with a very large cache.
Note
When using the Windows Configuration Wizard to install or configure MySQL,
the default value for query_cache_size will be configured automatically
for you based on the different configuration types available. When using the
Windows Configuration Wizard, the query cache may be enabled (that is, set
to a nonzero value) due to the selected configuration. The query cache is also
controlled by the setting of the query_cache_type variable. You should check
the values of these variables as set in your my.ini file after configuration has
taken place.
When you set query_cache_size to a nonzero value, keep in mind that the query cache needs
a minimum size of about 40KB to allocate its structures. (The exact size depends on system
architecture.) If you set the value too small, you'll get a warning, as in this example:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

mysql> SET GLOBAL query_cache_size = 40000;
Query OK, 0 rows affected, 1 warning (0.00 sec)
mysql> SHOW WARNINGS\G
*************************** 1. row ***************************
Level: Warning
Code: 1282
Message: Query cache failed to set size 39936;
new query cache size is 0
mysql> SET GLOBAL query_cache_size = 41984;
Query OK, 0 rows affected (0.00 sec)
mysql> SHOW VARIABLES LIKE 'query_cache_size';
+------------------+-------+
| Variable_name
| Value |
+------------------+-------+
| query_cache_size | 41984 |
+------------------+-------+

For the query cache to actually be able to hold any query results, its size must be set larger:
mysql> SET GLOBAL query_cache_size = 1000000;
Query OK, 0 rows affected (0.04 sec)
mysql> SHOW VARIABLES LIKE 'query_cache_size';
+------------------+--------+
| Variable_name
| Value |
+------------------+--------+
| query_cache_size | 999424 |
+------------------+--------+
1 row in set (0.00 sec)

The query_cache_size value is aligned to the nearest 1024 byte block. The value reported may
therefore be different from the value that you assign.
If the query cache size is greater than 0, the query_cache_type variable influences how it works.
This variable can be set to the following values:
• A value of 0 or OFF prevents caching or retrieval of cached results.
• A value of 1 or ON enables caching except of those statements that begin with SELECT
SQL_NO_CACHE.
• A value of 2 or DEMAND causes caching of only those statements that begin with SELECT
SQL_CACHE.
Setting the GLOBAL query_cache_type value determines query cache behavior for all clients
that connect after the change is made. Individual clients can control cache behavior for their own
connection by setting the SESSION query_cache_type value. For example, a client can disable use
of the query cache for its own queries like this:
mysql> SET SESSION query_cache_type = OFF;

If you set query_cache_type at server startup (rather than at runtime with a SET statement), only the
numeric values are permitted.
To control the maximum size of individual query results that can be cached, set the
query_cache_limit system variable. The default value is 1MB.
When a query is to be cached, its result (the data sent to the client) is stored in the query cache
during result retrieval. Therefore the data usually is not handled in one big chunk. The query cache
allocates blocks for storing this data on demand, so when one block is filled, a new block is allocated.
Because memory allocation operation is costly (timewise), the query cache allocates blocks with
a minimum size given by the query_cache_min_res_unit system variable. When a query is
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

The MySQL Query Cache

executed, the last result block is trimmed to the actual data size so that unused memory is freed.
Depending on the types of queries your server executes, you might find it helpful to tune the value of
query_cache_min_res_unit:
• The default value of query_cache_min_res_unit is 4KB. This should be adequate for most
cases.
• If you have a lot of queries with small results, the default block size may lead to memory
fragmentation, as indicated by a large number of free blocks. Fragmentation can force the
query cache to prune (delete) queries from the cache due to lack of memory. In this case, you
should decrease the value of query_cache_min_res_unit. The number of free blocks and
queries removed due to pruning are given by the values of the Qcache_free_blocks and
Qcache_lowmem_prunes status variables.
• If most of your queries have large results (check the Qcache_total_blocks and
Qcache_queries_in_cache status variables), you can increase performance by increasing
query_cache_min_res_unit. However, be careful to not make it too large (see the previous
item).

8.10.3.4 Query Cache Status and Maintenance
To check whether the query cache is present in your MySQL server, use the following statement:
mysql> SHOW VARIABLES LIKE 'have_query_cache';
+------------------+-------+
| Variable_name
| Value |
+------------------+-------+
| have_query_cache | YES
|
+------------------+-------+

You can defragment the query cache to better utilize its memory with the FLUSH QUERY CACHE
statement. The statement does not remove any queries from the cache.
The RESET QUERY CACHE statement removes all query results from the query cache. The FLUSH
TABLES statement also does this.
To monitor query cache performance, use SHOW STATUS to view the cache status variables:
mysql> SHOW STATUS LIKE 'Qcache%';
+-------------------------+--------+
| Variable_name
| Value |
+-------------------------+--------+
| Qcache_free_blocks
| 36
|
| Qcache_free_memory
| 138488 |
| Qcache_hits
| 79570 |
| Qcache_inserts
| 27087 |
| Qcache_lowmem_prunes
| 3114
|
| Qcache_not_cached
| 22989 |
| Qcache_queries_in_cache | 415
|
| Qcache_total_blocks
| 912
|
+-------------------------+--------+

Descriptions of each of these variables are given in Section 5.1.6, “Server Status Variables”. Some
uses for them are described here.
The total number of SELECT queries is given by this formula:
Com_select
+ Qcache_hits
+ queries with errors found by parser

The Com_select value is given by this formula:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Locking Operations

Qcache_inserts
+ Qcache_not_cached
+ queries with errors found during the column-privileges check

The query cache uses variable-length blocks, so Qcache_total_blocks and
Qcache_free_blocks may indicate query cache memory fragmentation. After FLUSH QUERY
CACHE, only a single free block remains.
Every cached query requires a minimum of two blocks (one for the query text and one or more for the
query results). Also, every table that is used by a query requires one block. However, if two or more
queries use the same table, only one table block needs to be allocated.
The information provided by the Qcache_lowmem_prunes status variable can help you tune the
query cache size. It counts the number of queries that have been removed from the cache to free up
memory for caching new queries. The query cache uses a least recently used (LRU) strategy to decide
which queries to remove from the cache. Tuning information is given in Section 8.10.3.3, “Query Cache
Configuration”.

8.11 Optimizing Locking Operations
When your database is busy with multiple sessions reading and writing data, the mechanism that
controls access to data files and memory areas can become a consideration for performance tuning.
Otherwise, sessions can spend time waiting for access to resources when they could be running
concurrently.
MySQL manages contention for table contents using locking:
• Internal locking is performed within the MySQL server itself to manage contention for table contents
by multiple threads. This type of locking is internal because it is performed entirely by the server and
involves no other programs. See Section 8.11.1, “Internal Locking Methods”.
• External locking occurs when the server and other programs lock MyISAM table files to coordinate
among themselves which program can access the tables at which time. See Section 8.11.4,
“External Locking”.

8.11.1 Internal Locking Methods
This section discusses internal locking; that is, locking performed within the MySQL server itself to
manage contention for table contents by multiple sessions. This type of locking is internal because it
is performed entirely by the server and involves no other programs. External locking occurs when the
server and other programs lock MyISAM table files to coordinate among themselves which program can
access the tables at which time. See Section 8.11.4, “External Locking”.
MySQL uses table-level locking for MyISAM, MEMORY and MERGE tables, page-level locking for BDB
tables, and row-level locking for InnoDB tables.
In many cases, you can make an educated guess about which locking type is best for an application,
but generally it is difficult to say that a given lock type is better than another. Everything depends on the
application and different parts of an application may require different lock types.
To decide whether you want to use a storage engine with row-level locking, you should look at what
your application does and what mix of select and update statements it uses. For example, most Web
applications perform many selects, relatively few deletes, updates based mainly on key values, and
inserts into a few specific tables. The base MySQL MyISAM setup is very well tuned for this.
Table locking in MySQL is deadlock-free for storage engines that use table-level locking. Deadlock
avoidance is managed by always requesting all needed locks at once at the beginning of a query and
always locking the tables in the same order.
MySQL grants table write locks as follows:
1. If there are no locks on the table, put a write lock on it.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Internal Locking Methods

2. Otherwise, put the lock request in the write lock queue.
MySQL grants table read locks as follows:
1. If there are no write locks on the table, put a read lock on it.
2. Otherwise, put the lock request in the read lock queue.
Table updates are given higher priority than table retrievals. Therefore, when a lock is released, the
lock is made available to the requests in the write lock queue and then to the requests in the read lock
queue. This ensures that updates to a table are not “starved” even when there is heavy SELECT activity
for the table. However, if there are many updates for a table, SELECT statements wait until there are no
more updates.
For information on altering the priority of reads and writes, see Section 8.11.2, “Table Locking Issues”.
You can analyze the table lock contention on your system by checking the Table_locks_immediate
and Table_locks_waited status variables, which indicate the number of times that requests for
table locks could be granted immediately and the number that had to wait, respectively:
mysql> SHOW STATUS LIKE 'Table%';
+-----------------------+---------+
| Variable_name
| Value
|
+-----------------------+---------+
| Table_locks_immediate | 1151552 |
| Table_locks_waited
| 15324
|
+-----------------------+---------+

The MyISAM storage engine supports concurrent inserts to reduce contention between readers and
writers for a given table: If a MyISAM table has no free blocks in the middle of the data file, rows are
always inserted at the end of the data file. In this case, you can freely mix concurrent INSERT and
SELECT statements for a MyISAM table without locks. That is, you can insert rows into a MyISAM table
at the same time other clients are reading from it. Holes can result from rows having been deleted
from or updated in the middle of the table. If there are holes, concurrent inserts are disabled but are
enabled again automatically when all holes have been filled with new data. This behavior is altered by
the concurrent_insert system variable. See Section 8.11.3, “Concurrent Inserts”.
If you acquire a table lock explicitly with LOCK TABLES, you can request a READ LOCAL lock rather
than a READ lock to enable other sessions to perform concurrent inserts while you have the table
locked.
To perform many INSERT and SELECT operations on a table t1 when concurrent inserts are not
possible, you can insert rows into a temporary table temp_t1 and update the real table with the rows
from the temporary table:
mysql>
mysql>
mysql>
mysql>

LOCK TABLES t1 WRITE, temp_t1 WRITE;
INSERT INTO t1 SELECT * FROM temp_t1;
DELETE FROM temp_t1;
UNLOCK TABLES;

InnoDB uses row locks and BDB uses page locks. Deadlocks are possible for these storage engines
because they automatically acquire locks during the processing of SQL statements, not at the start of
the transaction.
Advantages of row-level locking:
• Fewer lock conflicts when different sessions access different rows
• Fewer changes for rollbacks
• Possible to lock a single row for a long time
Disadvantages of row-level locking:
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Table Locking Issues

• Requires more memory than page-level or table-level locks
• Slower than page-level or table-level locks when used on a large part of the table because you must
acquire many more locks
• Slower than other locks if you often do GROUP BY operations on a large part of the data or if you
must scan the entire table frequently
Generally, table locks are superior to page-level or row-level locks in the following cases:
• Most statements for the table are reads
• Statements for the table are a mix of reads and writes, where writes are updates or deletes for a
single row that can be fetched with one key read:
UPDATE tbl_name SET column=value WHERE unique_key_col=key_value;
DELETE FROM tbl_name WHERE unique_key_col=key_value;

• SELECT combined with concurrent INSERT statements, and very few UPDATE or DELETE statements
• Many scans or GROUP BY operations on the entire table without any writers
With higher-level locks, you can more easily tune applications by supporting locks of different types,
because the lock overhead is less than for row-level locks.
Options other than row-level or page-level locking:
• Versioning (such as that used in MySQL for concurrent inserts) where it is possible to have one
writer at the same time as many readers. This means that the database or table supports different
views for the data depending on when access begins. Other common terms for this are “time travel,”
“copy on write,” or “copy on demand.”
• Copy on demand is in many cases superior to page-level or row-level locking. However, in the worst
case, it can use much more memory than using normal locks.
• Instead of using row-level locks, you can employ application-level locks, such as those provided by
GET_LOCK() and RELEASE_LOCK() in MySQL. These are advisory locks, so they work only with
applications that cooperate with each other. See Section 12.15, “Miscellaneous Functions”.

8.11.2 Table Locking Issues
To achieve a very high lock speed, MySQL uses table locking (instead of page, row, or column locking)
for all storage engines except InnoDB, BDB, and NDB.
For InnoDB and BDB tables, MySQL uses table locking only if you explicitly lock the table with
LOCK TABLES. For these storage engines, avoid using LOCK TABLES at all, because InnoDB uses
automatic row-level locking and BDB uses page-level locking to ensure transaction isolation.
For large tables, table locking is often better than row locking, but there are some disadvantages:
• Table locking enables many sessions to read from a table at the same time, but if a session wants to
write to a table, it must first get exclusive access. During the update, all other sessions that want to
access this particular table must wait until the update is done.
• Table locking causes problems in cases such as when a session is waiting because the disk is full
and free space needs to become available before the session can proceed. In this case, all sessions
that want to access the problem table are also put in a waiting state until more disk space is made
available.
Table locking is also disadvantageous under the following scenario:
• A session issues a SELECT that takes a long time to run.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Concurrent Inserts

• Another session then issues an UPDATE on the same table. This session waits until the SELECT is
finished.
• Another session issues another SELECT statement on the same table. Because UPDATE has higher
priority than SELECT, this SELECT waits for the UPDATE to finish, after waiting for the first SELECT to
finish.
The following items describe some ways to avoid or reduce contention caused by table locking:
• Try to get the SELECT statements to run faster so that they lock tables for a shorter time. You might
have to create some summary tables to do this.
• Start mysqld with --low-priority-updates. For storage engines that use only table-level
locking (such as MyISAM, MEMORY, and MERGE), this gives all statements that update (modify) a
table lower priority than SELECT statements. In this case, the second SELECT statement in the
preceding scenario would execute before the UPDATE statement, and would not need to wait for the
first SELECT to finish.
• To specify that all updates issued in a specific connection should be done with low priority, set the
low_priority_updates server system variable equal to 1.
• To give a specific INSERT, UPDATE, or DELETE statement lower priority, use the LOW_PRIORITY
attribute.
• To give a specific SELECT statement higher priority, use the HIGH_PRIORITY attribute. See
Section 13.2.8, “SELECT Syntax”.
• Start mysqld with a low value for the max_write_lock_count system variable to force MySQL to
temporarily elevate the priority of all SELECT statements that are waiting for a table after a specific
number of inserts to the table occur. This permits READ locks after a certain number of WRITE locks.
• If you have problems with INSERT combined with SELECT, consider switching to MyISAM tables,
which support concurrent SELECT and INSERT statements. (See Section 8.11.3, “Concurrent
Inserts”.)
• If you mix inserts and deletes on the same table, INSERT DELAYED may be of great help. See
Section 13.2.5.2, “INSERT DELAYED Syntax”.
• If you have problems with mixed SELECT and DELETE statements, the LIMIT option to DELETE may
help. See Section 13.2.2, “DELETE Syntax”.
• Using SQL_BUFFER_RESULT with SELECT statements can help to make the duration of table locks
shorter. See Section 13.2.8, “SELECT Syntax”.
• You could change the locking code in mysys/thr_lock.c to use a single queue. In this case, write
locks and read locks would have the same priority, which might help some applications.
Here are some tips concerning table locks in MySQL:
• Concurrent users are not a problem if you do not mix updates with selects that need to examine
many rows in the same table.
• You can use LOCK TABLES to increase speed, because many updates within a single lock is much
faster than updating without locks. Splitting table contents into separate tables may also help.
• If you encounter speed problems with table locks in MySQL, you may be able to improve
performance by converting some of your tables to InnoDB or BDB tables. See Section 14.2, “The
InnoDB Storage Engine”, and Section 14.5, “The BDB (BerkeleyDB) Storage Engine”.

8.11.3 Concurrent Inserts
The MyISAM storage engine supports concurrent inserts to reduce contention between readers and
writers for a given table: If a MyISAM table has no holes in the data file (deleted rows in the middle), an
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

External Locking

INSERT statement can be executed to add rows to the end of the table at the same time that SELECT
statements are reading rows from the table. If there are multiple INSERT statements, they are queued
and performed in sequence, concurrently with the SELECT statements. The results of a concurrent
INSERT may not be visible immediately.
The concurrent_insert system variable can be set to modify the concurrent-insert processing.
By default, the variable is set to 1 and concurrent inserts are handled as just described. If
concurrent_insert is set to 0, concurrent inserts are disabled. If the variable is set to 2, concurrent
inserts at the end of the table are permitted even for tables that have deleted rows. See also the
description of the concurrent_insert system variable.
Under circumstances where concurrent inserts can be used, there is seldom any need to use the
DELAYED modifier for INSERT statements. See Section 13.2.5.2, “INSERT DELAYED Syntax”.
If you are using the binary log, concurrent inserts are converted to normal inserts for CREATE ...
SELECT or INSERT ... SELECT statements. This is done to ensure that you can re-create an exact
copy of your tables by applying the log during a backup operation. See Section 5.4.3, “The Binary Log”.
In addition, for those statements a read lock is placed on the selected-from table such that inserts into
that table are blocked. The effect is that concurrent inserts for that table must wait as well.
With LOAD DATA INFILE, if you specify CONCURRENT with a MyISAM table that satisfies the condition
for concurrent inserts (that is, it contains no free blocks in the middle), other sessions can retrieve data
from the table while LOAD DATA is executing. Use of the CONCURRENT option affects the performance
of LOAD DATA a bit, even if no other session is using the table at the same time.
If you specify HIGH_PRIORITY, it overrides the effect of the --low-priority-updates option if the
server was started with that option. It also causes concurrent inserts not to be used.
For LOCK TABLE, the difference between READ LOCAL and READ is that READ LOCAL permits
nonconflicting INSERT statements (concurrent inserts) to execute while the lock is held. However, this
cannot be used if you are going to manipulate the database using processes external to the server
while you hold the lock.

8.11.4 External Locking
External locking is the use of file system locking to manage contention for MyISAM database tables by
multiple processes. External locking is used in situations where a single process such as the MySQL
server cannot be assumed to be the only process that requires access to tables. Here are some
examples:
• If you run multiple servers that use the same database directory (not recommended), each server
must have external locking enabled.
• If you use myisamchk to perform table maintenance operations on MyISAM tables, you must either
ensure that the server is not running, or that the server has external locking enabled so that it locks
table files as necessary to coordinate with myisamchk for access to the tables. The same is true for
use of myisampack to pack MyISAM tables.
If the server is run with external locking enabled, you can use myisamchk at any time for read
operations such a checking tables. In this case, if the server tries to update a table that myisamchk
is using, the server will wait for myisamchk to finish before it continues.
If you use myisamchk for write operations such as repairing or optimizing tables, or if you use
myisampack to pack tables, you must always ensure that the mysqld server is not using the table.
If you do not stop mysqld, you should at least do a mysqladmin flush-tables before you run
myisamchk. Your tables may become corrupted if the server and myisamchk access the tables
simultaneously.
With external locking in effect, each process that requires access to a table acquires a file system lock
for the table files before proceeding to access the table. If all necessary locks cannot be acquired,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing the MySQL Server

the process is blocked from accessing the table until the locks can be obtained (after the process that
currently holds the locks releases them).
External locking affects server performance because the server must sometimes wait for other
processes before it can access tables.
External locking is unnecessary if you run a single server to access a given data directory (which is
the usual case) and if no other programs such as myisamchk need to modify tables while the server
is running. If you only read tables with other programs, external locking is not required, although
myisamchk might report warnings if the server changes tables while myisamchk is reading them.
With external locking disabled, to use myisamchk, you must either stop the server while myisamchk
executes or else lock and flush the tables before running myisamchk. (See Section 8.12.1, “System
Factors and Startup Parameter Tuning”.) To avoid this requirement, use the CHECK TABLE and
REPAIR TABLE statements to check and repair MyISAM tables.
For mysqld, external locking is controlled by the value of the skip_external_locking system
variable. When this variable is enabled, external locking is disabled, and vice versa. External locking is
disabled by default.
Use of external locking can be controlled at server startup by using the --external-locking or -skip-external-locking option.
If you do use external locking option to enable updates to MyISAM tables from many MySQL
processes, you must ensure that the following conditions are satisfied:
• You should not use the query cache for queries that use tables that are updated by another process.
• You should not start the server with the --delay-key-write=ALL option or use the
DELAY_KEY_WRITE=1 table option for any shared tables. Otherwise, index corruption can occur.
The easiest way to satisfy these conditions is to always use --external-locking together with
--delay-key-write=OFF and --query-cache-size=0. (This is not done by default because in
many setups it is useful to have a mixture of the preceding options.)

8.12 Optimizing the MySQL Server
8.12.1 System Factors and Startup Parameter Tuning
We start with system-level factors, because some of these decisions must be made very early to
achieve large performance gains. In other cases, a quick look at this section may suffice. However, it is
always nice to have a sense of how much can be gained by changing factors that apply at this level.
Before using MySQL in production, we advise you to test it on your intended platform.
Other tips:
• If you have enough RAM, you could remove all swap devices. Some operating systems use a swap
device in some contexts even if you have free memory.
• Avoid external locking for MyISAM tables. The default is for external locking to be disabled. The
--external-locking and --skip-external-locking options explicitly enable and disable
external locking.
Disabling external locking does not affect MySQL's functionality as long as you run only one server.
Just remember to take down the server (or lock and flush the relevant tables) before you run
myisamchk. On some systems it is mandatory to disable external locking because it does not work,
anyway.
The only case in which you cannot disable external locking is when you run multiple MySQL servers
(not clients) on the same data, or if you run myisamchk to check (not repair) a table without telling
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Tuning Server Parameters

the server to flush and lock the tables first. Note that using multiple MySQL servers to access the
same data concurrently is generally not recommended, except when using MySQL Cluster.
The LOCK TABLES and UNLOCK TABLES statements use internal locking, so you can use them
even if external locking is disabled.

8.12.2 Tuning Server Parameters
You can determine the default buffer sizes used by the mysqld server using this command:
shell> mysqld --verbose --help

This command produces a list of all mysqld options and configurable system variables. The output
includes the default variable values and looks something like this:
help
abort-slave-event-count
allow-suspicious-udfs
auto-increment-increment
auto-increment-offset
automatic-sp-privileges
basedir
...
tmpdir
transaction_alloc_block_size
transaction_prealloc_size
updatable_views_with_limit
use-symbolic-links
verbose
wait_timeout
warnings

TRUE
0
FALSE
1
1
TRUE
/home/jon/bin/mysql-5.0/
(No default value)
8192
4096
1
TRUE
TRUE
28800
1

For a mysqld server that is currently running, you can see the current values of its system variables by
connecting to it and issuing this statement:
mysql> SHOW VARIABLES;

You can also see some statistical and status indicators for a running server by issuing this statement:
mysql> SHOW STATUS;

System variable and status information also can be obtained using mysqladmin:
shell> mysqladmin variables
shell> mysqladmin extended-status

For a full description of all system and status variables, see Section 5.1.4, “Server System Variables”,
and Section 5.1.6, “Server Status Variables”.
MySQL uses algorithms that are very scalable, so you can usually run with very little memory.
However, normally better performance results from giving MySQL more memory.
When tuning a MySQL server, the two most important variables to configure are key_buffer_size
and table_cache. You should first feel confident that you have these set appropriately before trying
to change any other variables.
The following examples indicate some typical variable values for different runtime configurations.
• If you have at least 1-2GB of memory and many tables and want maximum performance with a
moderate number of clients, use something like this:
shell> mysqld_safe --key_buffer_size=384M --table_open_cache=4000 \

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Disk I/O

--sort_buffer_size=4M --read_buffer_size=1M &

• If you have only 256MB of memory and only a few tables, but you still do a lot of sorting, you can use
something like this:
shell> mysqld_safe --key_buffer_size=64M --sort_buffer_size=1M

If there are very many simultaneous connections, swapping problems may occur unless mysqld has
been configured to use very little memory for each connection. mysqld performs better if you have
enough memory for all connections.
• With little memory and lots of connections, use something like this:
shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=100K \
--read_buffer_size=100K &

Or even this:
shell> mysqld_safe --key_buffer_size=512K --sort_buffer_size=16K \
--table_cache=32 --read_buffer_size=8K \
--net_buffer_length=1K &

If you are performing GROUP BY or ORDER BY operations on tables that are much larger than your
available memory, increase the value of read_rnd_buffer_size to speed up the reading of rows
following sorting operations.
You can make use of the example option files included with your MySQL distribution; see
Section 5.1.2, “Server Configuration Defaults”.
If you specify an option on the command line for mysqld or mysqld_safe, it remains in effect only for
that invocation of the server. To use the option every time the server runs, put it in an option file.
To see the effects of a parameter change, do something like this:
shell> mysqld --key_buffer_size=128M --verbose --help

The variable values are listed near the end of the output. Make sure that the --verbose and --help
options are last. Otherwise, the effect of any options listed after them on the command line are not
reflected in the output.
For information on tuning the InnoDB storage engine, see Section 8.6, “Optimizing for InnoDB Tables”.

8.12.3 Optimizing Disk I/O
This section describes ways to configure storage devices when you can devote more and faster
storage hardware to the database server.
• Disk seeks are a huge performance bottleneck. This problem becomes more apparent when
the amount of data starts to grow so large that effective caching becomes impossible. For large
databases where you access data more or less randomly, you can be sure that you need at least
one disk seek to read and a couple of disk seeks to write things. To minimize this problem, use disks
with low seek times.
• Increase the number of available disk spindles (and thereby reduce the seek overhead) by either
symlinking files to different disks or striping the disks:
• Using symbolic links
This means that, for MyISAM tables, you symlink the index file and data files from their usual
location in the data directory to another disk (that may also be striped). This makes both the
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Symbolic Links

seek and read times better, assuming that the disk is not used for other purposes as well. See
Section 8.12.4, “Using Symbolic Links”.
• Striping
Striping means that you have many disks and put the first block on the first disk, the second block
on the second disk, and the N-th block on the (N MOD number_of_disks) disk, and so on. This
means if your normal data size is less than the stripe size (or perfectly aligned), you get much
better performance. Striping is very dependent on the operating system and the stripe size, so
benchmark your application with different stripe sizes. See Section 8.13.3, “Using Your Own
Benchmarks”.
The speed difference for striping is very dependent on the parameters. Depending on how you
set the striping parameters and number of disks, you may get differences measured in orders of
magnitude. You have to choose to optimize for random or sequential access.
• For reliability, you may want to use RAID 0+1 (striping plus mirroring), but in this case, you need
2 × N drives to hold N drives of data. This is probably the best option if you have the money for it.
However, you may also have to invest in some volume-management software to handle it efficiently.
• A good option is to vary the RAID level according to how critical a type of data is. For example, store
semi-important data that can be regenerated on a RAID 0 disk, but store really important data such
as host information and logs on a RAID 0+1 or RAID N disk. RAID N can be a problem if you have
many writes, due to the time required to update the parity bits.
• On Linux, you can get much better performance by using hdparm to configure your disk's interface.
(Up to 100% under load is not uncommon.) The following hdparm options should be quite good for
MySQL, and probably for many other applications:
hdparm -m 16 -d 1

Performance and reliability when using this command depend on your hardware, so we strongly
suggest that you test your system thoroughly after using hdparm. Please consult the hdparm
manual page for more information. If hdparm is not used wisely, file system corruption may result, so
back up everything before experimenting!
• You can also set the parameters for the file system that the database uses:
If you do not need to know when files were last accessed (which is not really useful on a database
server), you can mount your file systems with the -o noatime option. That skips updates to the last
access time in inodes on the file system, which avoids some disk seeks.
On many operating systems, you can set a file system to be updated asynchronously by mounting
it with the -o async option. If your computer is reasonably stable, this should give you better
performance without sacrificing too much reliability. (This flag is on by default on Linux.)

8.12.4 Using Symbolic Links
You can move databases or tables from the database directory to other locations and replace them
with symbolic links to the new locations. You might want to do this, for example, to move a database
to a file system with more free space or increase the speed of your system by spreading your tables to
different disks.
The recommended way to do this is to symlink entire database directories to a different disk. Symlink
MyISAM tables only as a last resort.
To determine the location of your data directory, use this statement:
SHOW VARIABLES LIKE 'datadir';

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Symbolic Links

8.12.4.1 Using Symbolic Links for Databases on Unix
On Unix, the way to symlink a database is first to create a directory on some disk where you have free
space and then to create a soft link to it from the MySQL data directory.
shell> mkdir /dr1/databases/test
shell> ln -s /dr1/databases/test /path/to/datadir

MySQL does not support linking one directory to multiple databases. Replacing a database directory
with a symbolic link works as long as you do not make a symbolic link between databases. Suppose
that you have a database db1 under the MySQL data directory, and then make a symlink db2 that
points to db1:
shell> cd /path/to/datadir
shell> ln -s db1 db2

The result is that, or any table tbl_a in db1, there also appears to be a table tbl_a in db2. If one
client updates db1.tbl_a and another client updates db2.tbl_a, problems are likely to occur.

8.12.4.2 Using Symbolic Links for MyISAM Tables on Unix
Symlinks are fully supported only for MyISAM tables. For files used by tables for other storage engines,
you may get strange problems if you try to use symbolic links.
Do not symlink tables on systems that do not have a fully operational realpath() call. (Linux and
Solaris support realpath()). To determine whether your system supports symbolic links, check the
value of the have_symlink system variable using this statement:
SHOW VARIABLES LIKE 'have_symlink';

The handling of symbolic links for MyISAM tables works as follows:
• In the data directory, you always have the table format (.frm) file, the data (.MYD) file, and the index
(.MYI) file. The data file and index file can be moved elsewhere and replaced in the data directory by
symlinks. The format file cannot.
• You can symlink the data file and the index file independently to different directories.
• To instruct a running MySQL server to perform the symlinking, use the DATA DIRECTORY and
INDEX DIRECTORY options to CREATE TABLE. See Section 13.1.10, “CREATE TABLE Syntax”.
Alternatively, if mysqld is not running, symlinking can be accomplished manually using ln -s from
the command line.
Note
Beginning with MySQL 5.0.60, the path used with either or both of the DATA
DIRECTORY and INDEX DIRECTORY options may not include the MySQL
data directory. (Bug #32167)
• myisamchk does not replace a symlink with the data file or index file. It works directly on the file to
which the symlink points. Any temporary files are created in the directory where the data file or index
file is located. The same is true for the ALTER TABLE, OPTIMIZE TABLE, and REPAIR TABLE
statements.
•

Note
When you drop a table that is using symlinks, both the symlink and the file
to which the symlink points are dropped. This is an extremely good reason
not to run mysqld as the system root or permit system users to have write
access to MySQL database directories.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Symbolic Links

• If you rename a table with ALTER TABLE ... RENAME or RENAME TABLE and you do not move
the table to another database, the symlinks in the database directory are renamed to the new names
and the data file and index file are renamed accordingly.
• If you use ALTER TABLE ... RENAME or RENAME TABLE to move a table to another database,
the table is moved to the other database directory. If the table name changed, the symlinks in the
new database directory are renamed to the new names and the data file and index file are renamed
accordingly.
• If you are not using symlinks, start mysqld with the --skip-symbolic-links option to ensure
that no one can use mysqld to drop or rename a file outside of the data directory.
These table symlink operations are not supported:
• ALTER TABLE ignores the DATA DIRECTORY and INDEX DIRECTORY table options.
• BACKUP TABLE and RESTORE TABLE do not respect symbolic links.
• As indicated previously, only the data and index files can be symbolic links. The .frm file must
never be a symbolic link. Attempting to do this (for example, to make one table name a synonym
for another) produces incorrect results. Suppose that you have a database db1 under the MySQL
data directory, a table tbl1 in this database, and in the db1 directory you make a symlink tbl2 that
points to tbl1:
shell>
shell>
shell>
shell>

cd
ln
ln
ln

/path/to/datadir/db1
-s tbl1.frm tbl2.frm
-s tbl1.MYD tbl2.MYD
-s tbl1.MYI tbl2.MYI

Problems result if one thread reads db1.tbl1 and another thread updates db1.tbl2:
• The query cache is “fooled” (it has no way of knowing that tbl1 has not been updated, so it
returns outdated results).
• ALTER statements on tbl2 fail.

8.12.4.3 Using Symbolic Links for Databases on Windows
On Windows, symbolic links can be used for database directories. This enables you to put a database
directory at a different location (for example, on a different disk) by setting up a symbolic link to it. Use
of database symlinks on Windows is similar to their use on Unix, although the procedure for setting up
the link differs.
Suppose that you want to place the database directory for a database named mydb at D:\data\mydb.
To do this, create a symbolic link in the MySQL data directory that points to D:\data\mydb. However,
before creating the symbolic link, make sure that the D:\data\mydb directory exists by creating it if
necessary. If you already have a database directory named mydb in the data directory, move it to D:
\data. Otherwise, the symbolic link will be ineffective. To avoid problems, make sure that the server is
not running when you move the database directory.
On Windows, create a symbolic link to a MySQL database by creating a .sym file in the data directory
that contains the path to the destination directory. The file should be named db_name.sym, where
db_name is the database name.
Support for database symbolic links on Windows using .sym files is enabled by default. If you do not
need .sym file symbolic links, you can disable support for them by starting mysqld with the --skipsymbolic-links option. To determine whether your system supports .sym file symbolic links, check
the value of the have_symlink system variable using this statement:
SHOW VARIABLES LIKE 'have_symlink';

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Memory Use

To create a .sym file symlink, use this procedure:
1. Change location into the data directory:
C:\> cd \path\to\datadir

2. In the data directory, create a text file named mydb.sym that contains this path name: D:\data
\mydb\
Note
The path name to the new database and tables should be absolute. If you
specify a relative path, the location will be relative to the mydb.sym file.
After this, all tables created in the database mydb are created in D:\data\mydb.
The following limitations apply to the use of .sym files for database symbolic linking on Windows:
• The symbolic link is not used if a directory with the same name as the database exists in the MySQL
data directory.
• The --innodb_file_per_table option cannot be used.
• If you run mysqld as a service, you cannot use a mapped drive to a remote server as the destination
of the symbolic link. As a workaround, you can use the full path (\\servername\path\).

8.12.5 Optimizing Memory Use
8.12.5.1 How MySQL Uses Memory
MySQL allocates buffers and caches to improve performance of database operations. You can improve
MySQL performance by increasing the values of certain cache and buffer-related system variables.
You can also modify these variables to run MySQL on systems with limited memory.
The following list describes some of the ways that MySQL uses memory. Where applicable, relevant
system variables are referenced. Some items are storage engine specific.
• The InnoDB buffer pool is a memory area that holds cached InnoDB data for tables, indexes, and
other auxiliary buffers. For efficiency of high-volume read operations, the buffer pool is divided into
pages that can potentially hold multiple rows. For efficiency of cache management, the buffer pool
is implemented as a linked list of pages; data that is rarely used is aged out of the cache, using a
variation of the LRU algorithm. For more information, see Section 8.10.2, “The InnoDB Buffer Pool”.
The size of the buffer pool is important for system performance.
• Typically, it is recommended that innodb_buffer_pool_size is configured to 50 to 75 percent
of system memory.
• InnoDB allocates memory for the entire buffer pool at server startup. Memory
allocation is performed by malloc() operations. Buffer pool size is defined by the
innodb_buffer_pool_size configuration option.
• On systems with a large amount of memory, you can improve concurrency by dividing the buffer
pool into multiple buffer pool instances. The number of buffer pool instances is controlled by
innodb_buffer_pool_instances.
• A buffer pool that is too small may cause excessive churning as pages are flushed from the buffer
pool only to be required again a short time later.
• A buffer pool that is too large may cause swapping due to competition for memory.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Memory Use

• All threads share the MyISAM key buffer; its size is determined by the key_buffer_size variable.
Other buffers used by the server are allocated as needed. See Section 8.12.2, “Tuning Server
Parameters”.
For each MyISAM table that is opened, the index file is opened once; the data file is opened once for
each concurrently running thread. For each concurrent thread, a table structure, column structures
for each column, and a buffer of size 3 * N are allocated (where N is the maximum row length, not
counting BLOB columns). A BLOB column requires five to eight bytes plus the length of the BLOB
data. The MyISAM storage engine maintains one extra row buffer for internal use.
• Each thread that is used to manage client connections uses some thread-specific space. The
following list indicates these and which variables control their size:
• A stack (variable thread_stack)
• A connection buffer (variable net_buffer_length)
• A result buffer (variable net_buffer_length)
The connection buffer and result buffer each begin with a size equal to net_buffer_length bytes,
but are dynamically enlarged up to max_allowed_packet bytes as needed. The result buffer
shrinks to net_buffer_length bytes after each SQL statement. While a statement is running, a
copy of the current statement string is also allocated.
• All threads share the same base memory.
• When a thread is no longer needed, the memory allocated to it is released and returned to the
system unless the thread goes back into the thread cache. In that case, the memory remains
allocated.
• Only compressed MyISAM tables are memory mapped. This is because the 32-bit memory space
of 4GB is not large enough for most big tables. When systems with a 64-bit address space become
more common, we may add general support for memory mapping.
• Each request that performs a sequential scan of a table allocates a read buffer (variable
read_buffer_size).
• When reading rows in an arbitrary sequence (for example, following a sort), a random-read buffer
(variable read_rnd_buffer_size) may be allocated to avoid disk seeks.
• All joins are executed in a single pass, and most joins can be done without even using a temporary
table. Most temporary tables are memory-based hash tables. Temporary tables with a large row
length (calculated as the sum of all column lengths) or that contain BLOB columns are stored on disk.
If an internal in-memory temporary table becomes too large, MySQL handles this automatically by
changing the table from in-memory to on-disk format, to be handled by the MyISAM storage engine.
You can increase the permissible temporary table size as described in Section 8.4.4, “Internal
Temporary Table Use in MySQL”.
• Most requests that perform a sort allocate a sort buffer and zero to two temporary files depending on
the result set size. See Section B.5.3.5, “Where MySQL Stores Temporary Files”.
• Almost all parsing and calculating is done in thread-local and reusable memory pools. No memory
overhead is needed for small items, so the normal slow memory allocation and freeing is avoided.
Memory is allocated only for unexpectedly large strings.
• For each table having BLOB columns, a buffer is enlarged dynamically to read in larger BLOB values.
If you scan a table, a buffer as large as the largest BLOB value is allocated.
• MySQL requires memory and descriptors for the table cache. Handler structures for all in-use tables
are saved in the table cache and managed as “First In, First Out” (FIFO). The initial table cache size
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Memory Use

is defined by the table_cache system variable; see Section 8.4.3.1, “How MySQL Opens and
Closes Tables”.
• A FLUSH TABLES statement or mysqladmin flush-tables command closes all tables that
are not in use at once and marks all in-use tables to be closed when the currently executing thread
finishes. This effectively frees most in-use memory. FLUSH TABLES does not return until all tables
have been closed.
• The server caches information in memory as a result of GRANT and CREATE USER statements. This
memory is not released by the corresponding REVOKE and DROP USER statements, so for a server
that executes many instances of the statements that cause caching, there will be an increase in
memory use. This cached memory can be freed with FLUSH PRIVILEGES.
ps and other system status programs may report that mysqld uses a lot of memory. This may be
caused by thread stacks on different memory addresses. For example, the Solaris version of ps counts
the unused memory between stacks as used memory. To verify this, check available swap with swap
-s. We test mysqld with several memory-leakage detectors (both commercial and Open Source), so
there should be no memory leaks.

8.12.5.2 Enabling Large Page Support
Some hardware/operating system architectures support memory pages greater than the default
(usually 4KB). The actual implementation of this support depends on the underlying hardware and
operating system. Applications that perform a lot of memory accesses may obtain performance
improvements by using large pages due to reduced Translation Lookaside Buffer (TLB) misses.
In MySQL, large pages can be used by InnoDB, to allocate memory for its buffer pool and additional
memory pool.
MySQL supports only the Linux implementation of large page support (which is called HugeTLB in
Linux).
Before large pages can be used on Linux, the kernel must be enabled to support them and it is
necessary to configure the HugeTLB memory pool. For reference, the HugeTBL API is documented in
the Documentation/vm/hugetlbpage.txt file of your Linux sources.
The kernel for some recent systems such as Red Hat Enterprise Linux appear to have the large pages
feature enabled by default. To check whether this is true for your kernel, use the following command
and look for output lines containing “huge”:
shell> cat /proc/meminfo | grep -i huge
HugePages_Total:
0
HugePages_Free:
0
HugePages_Rsvd:
0
HugePages_Surp:
0
Hugepagesize:
4096 kB

The nonempty command output indicates that large page support is present, but the zero values
indicate that no pages are configured for use.
If your kernel needs to be reconfigured to support large pages, consult the hugetlbpage.txt file for
instructions.
Assuming that your Linux kernel has large page support enabled, configure it for use by MySQL using
the following commands. Normally, you put these in an rc file or equivalent startup file that is executed
during the system boot sequence, so that the commands execute each time the system starts. The
commands should execute early in the boot sequence, before the MySQL server starts. Be sure to
change the allocation numbers and the group number as appropriate for your system.
# Set the number of pages to be used.
# Each page is normally 2MB, so a value of 20 = 40MB.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Network Use

# This command actually allocates memory, so this much
# memory must be available.
echo 20 > /proc/sys/vm/nr_hugepages
# Set the group number that is permitted to access this
# memory (102 in this case). The mysql user must be a
# member of this group.
echo 102 > /proc/sys/vm/hugetlb_shm_group
# Increase the amount of shmem permitted per segment
# (12G in this case).
echo 1560281088 > /proc/sys/kernel/shmmax
# Increase total amount of shared memory. The value
# is the number of pages. At 4KB/page, 4194304 = 16GB.
echo 4194304 > /proc/sys/kernel/shmall

For MySQL usage, you normally want the value of shmmax to be close to the value of shmall.
To verify the large page configuration, check /proc/meminfo again as described previously. Now you
should see some nonzero values:
shell> cat /proc/meminfo | grep -i huge
HugePages_Total:
20
HugePages_Free:
20
HugePages_Rsvd:
0
HugePages_Surp:
0
Hugepagesize:
4096 kB

The final step to make use of the hugetlb_shm_group is to give the mysql user an “unlimited”
value for the memlock limit. This can by done either by editing /etc/security/limits.conf or by
adding the following command to your mysqld_safe script:
ulimit -l unlimited

Adding the ulimit command to mysqld_safe causes the root user to set the memlock limit to
unlimited before switching to the mysql user. (This assumes that mysqld_safe is started by
root.)
Large page support in MySQL is disabled by default. To enable it, start the server with the --largepages option. For example, you can use the following lines in your server's my.cnf file:
[mysqld]
large-pages

With this option, InnoDB uses large pages automatically for its buffer pool and additional memory pool.
If InnoDB cannot do this, it falls back to use of traditional memory and writes a warning to the error log:
Warning: Using conventional memory pool
To verify that large pages are being used, check /proc/meminfo again:
shell> cat /proc/meminfo | grep -i huge
HugePages_Total:
20
HugePages_Free:
20
HugePages_Rsvd:
2
HugePages_Surp:
0
Hugepagesize:
4096 kB

8.12.6 Optimizing Network Use
8.12.6.1 How MySQL Uses Threads for Client Connections
Connection manager threads handle client connection requests on the network interfaces that the
server listens to. On all platforms, one manager thread handles TCP/IP connection requests. On Unix,
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Optimizing Network Use

this manager thread also handles Unix socket file connection requests. On Windows, a manager thread
handles shared-memory connection requests, and another handles named-pipe connection requests.
The server does not create threads to handle interfaces that it does not listen to. For example, a
Windows server that does not have support for named-pipe connections enabled does not create a
thread to handle them.
Connection manager threads associate each client connection with a thread dedicated to it that
handles authentication and request processing for that connection. Manager threads create a new
thread when necessary but try to avoid doing so by consulting the thread cache first to see whether it
contains a thread that can be used for the connection. When a connection ends, its thread is returned
to the thread cache if the cache is not full.
In this connection thread model, there are as many threads as there are clients currently connected,
which has some disadvantages when server workload must scale to handle large numbers of
connections. For example, thread creation and disposal becomes expensive. Also, each thread
requires server and kernel resources, such as stack space. To accommodate a large number of
simultaneous connections, the stack size per thread must be kept small, leading to a situation where
it is either too small or the server consumes large amounts of memory. Exhaustion of other resources
can occur as well, and scheduling overhead can become significant.
To control and monitor how the server manages threads that handle client connections, several system
and status variables are relevant. (See Section 5.1.4, “Server System Variables”, and Section 5.1.6,
“Server Status Variables”.)
The thread cache has a size determined by the thread_cache_size system variable. The default
value is 0 (no caching), which causes a thread to be set up for each new connection and disposed
of when the connection terminates. Set thread_cache_size to N to enable N inactive connection
threads to be cached. thread_cache_size can be set at server startup or changed while the server
runs. A connection thread becomes inactive when the client connection with which it was associated
terminates.
To monitor the number of threads in the cache and how many threads have been created because a
thread could not be taken from the cache, monitor the Threads_cached and Threads_created
status variables.
You can set max_connections at server startup or at runtime to control the maximum number of
clients that can connect simultaneously.
When the thread stack is too small, this limits the complexity of the SQL statements which the server
can handle, the recursion depth of stored procedures, and other memory-consuming actions. To set a
stack size of N bytes for each thread, start the server with --thread_stack=N.

8.12.6.2 DNS Lookup Optimization and the Host Cache
The MySQL server maintains a host cache in memory that contains information about clients: IP
address, host name, and error information. The server uses this cache for nonlocal TCP connections.
It does not use the cache for TCP connections established using the loopback interface address
(127.0.0.1), or for connections established using a Unix socket file, named pipe, or shared memory.
For each new client connection, the server uses the client IP address to check whether the client host
name is in the host cache. If not, the server attempts to resolve the host name. First, it resolves the
IP address to a host name and resolves that host name back to an IP address. Then it compares
the result to the original IP address to ensure that they are the same. The server stores information
about the result of this operation in the host cache. If the cache is full, the least recently used entry is
discarded.
The server performs host name resolution using the thread-safe gethostbyaddr_r() and
gethostbyname_r() calls if the operating system supports them. Otherwise, the thread performing
the lookup locks a mutex and calls gethostbyaddr() and gethostbyname() instead. In this case,
no other thread can resolve host names that are not in the host cache until the thread holding the
mutex lock releases it.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Measuring Performance (Benchmarking)

The server uses the host cache for several purposes:
• By caching the results of IP-to-host name lookups, the server avoids doing a DNS lookup for each
client connection. Instead, for a given host, it needs to perform a lookup only for the first connection
from that host.
• The cache contains information about errors that occur during the connection process. Some
errors are considered “blocking.” If too many of these occur successively from a given host
without a successful connection, the server blocks further connections from that host. The
max_connect_errors system variable determines the number of permitted errors before blocking
occurs. See Section B.5.2.6, “Host 'host_name' is blocked”.
To unblock blocked hosts, flush the host cache by issuing a FLUSH HOSTS statement or executing a
mysqladmin flush-hosts command.
It is possible for a blocked host to become unblocked even without FLUSH HOSTS if activity from other
hosts has occurred since the last connection attempt from the blocked host. This can occur because
the server discards the least recently used cache entry to make room for a new entry if the cache is full
when a connection arrives from a client IP not in the cache. If the discarded entry is for a blocked host,
that host becomes unblocked.
The host cache is enabled by default. To disable it, start the server with the --skip-host-cache
option.
To disable DNS host name lookups, start the server with the --skip-name-resolve option. In this
case, the server uses only IP addresses and not host names to match connecting hosts to rows in the
MySQL grant tables. Only accounts specified in those tables using IP addresses can be used. (Be sure
that an account exists that specifies an IP address or you may not be able to connect.)
If you have a very slow DNS and many hosts, you might be able to improve performance either by
disabling DNS lookups with --skip-name-resolve or by increasing the HOST_CACHE_SIZE define
(default value: 128) and recompiling the server
To disallow TCP/IP connections entirely, start the server with the --skip-networking option.
Some connection errors are not associated with TCP connections, occur very early in the connection
process (even before an IP address is known), or are not specific to any particular IP address (such as
out-of-memory conditions).

8.13 Measuring Performance (Benchmarking)
To measure performance, consider the following factors:
• Whether you are measuring the speed of a single operation on a quiet system, or how a set of
operations (a “workload”) works over a period of time. With simple tests, you usually test how
changing one aspect (a configuration setting, the set of indexes on a table, the SQL clauses in a
query) affects performance. Benchmarks are typically long-running and elaborate performance tests,
where the results could dictate high-level choices such as hardware and storage configuration, or
how soon to upgrade to a new MySQL version.
• For benchmarking, sometimes you must simulate a heavy database workload to get an accurate
picture.
• Performance can vary depending on so many different factors that a difference of a few percentage
points might not be a decisive victory. The results might shift the opposite way when you test in a
different environment.
• Certain MySQL features help or do not help performance depending on the workload. For
completeness, always test performance with those features turned on and turned off. The two most
important features to try with each workload are the MySQL query cache, and the adaptive hash
index for InnoDB tables.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Measuring the Speed of Expressions and Functions

This section progresses from simple and direct measurement techniques that a single developer can
do, to more complicated ones that require additional expertise to perform and interpret the results.

8.13.1 Measuring the Speed of Expressions and Functions
To measure the speed of a specific MySQL expression or function, invoke the BENCHMARK() function
using the mysql client program. Its syntax is BENCHMARK(loop_count,expression). The return
value is always zero, but mysql prints a line displaying approximately how long the statement took to
execute. For example:
mysql> SELECT BENCHMARK(1000000,1+1);
+------------------------+
| BENCHMARK(1000000,1+1) |
+------------------------+
|
0 |
+------------------------+
1 row in set (0.32 sec)

This result was obtained on a Pentium II 400MHz system. It shows that MySQL can execute 1,000,000
simple addition expressions in 0.32 seconds on that system.
The built-in MySQL functions are typically highly optimized, but there may be some exceptions.
BENCHMARK() is an excellent tool for finding out if some function is a problem for your queries.

8.13.2 The MySQL Benchmark Suite
This benchmark suite is meant to tell any user what operations a given SQL implementation performs
well or poorly. You can get a good idea for how the benchmarks work by looking at the code and
results in the sql-bench directory in any MySQL source distribution.
To use the benchmark suite, the following requirements must be satisfied:
• The benchmark suite is provided with MySQL source distributions. You can either download a
released distribution from http://dev.mysql.com/downloads/, or use the current development source
tree. (See Section 2.17.2, “Installing MySQL Using a Development Source Tree”.)
• The benchmark scripts are written in Perl and use the Perl DBI module to access database servers,
so DBI must be installed. You also need the server-specific DBD drivers for each of the servers you
want to test. For example, to test MySQL, PostgreSQL, and DB2, you must have the DBD::mysql,
DBD::Pg, and DBD::DB2 modules installed. See Section 2.22, “Perl Installation Notes”.
After you obtain a MySQL source distribution, you can find the benchmark suite located in its sqlbench directory. To run the benchmark tests, build MySQL, and then change location into the sqlbench directory and execute the run-all-tests script:
shell> cd sql-bench
shell> perl run-all-tests --server=server_name

server_name should be the name of one of the supported servers. To get a list of all options and
supported servers, invoke this command:
shell> perl run-all-tests --help

The crash-me script also is located in the sql-bench directory. crash-me tries to determine what
features a database system supports and what its capabilities and limitations are by actually running
queries. For example, it determines:
• What data types are supported
• How many indexes are supported
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Using Your Own Benchmarks

• What functions are supported
• How big a query can be
• How big a VARCHAR column can be
For more information about benchmark results, visit http://www.mysql.com/why-mysql/benchmarks/.

8.13.3 Using Your Own Benchmarks
Benchmark your application and database to find out where the bottlenecks are. After fixing one
bottleneck (or by replacing it with a “dummy” module), you can proceed to identify the next bottleneck.
Even if the overall performance for your application currently is acceptable, you should at least make a
plan for each bottleneck and decide how to solve it if someday you really need the extra performance.
For examples of portable benchmark programs, look at those in the MySQL benchmark suite. See
Section 8.13.2, “The MySQL Benchmark Suite”. You can take any program from this suite and modify it
for your own needs. By doing this, you can try different solutions to your problem and test which really
is fastest for you.
Another free benchmark suite is the Open Source Database Benchmark, available at http://
osdb.sourceforge.net/.
It is very common for a problem to occur only when the system is very heavily loaded. We have
had many customers who contact us when they have a (tested) system in production and have
encountered load problems. In most cases, performance problems turn out to be due to issues of
basic database design (for example, table scans are not good under high load) or problems with the
operating system or libraries. Most of the time, these problems would be much easier to fix if the
systems were not already in production.
To avoid problems like this, benchmark your whole application under the worst possible load. For
example, you can try benchmarking packages such as SysBench and DBT2, available at https://
launchpad.net/sysbench, and http://osdldbt.sourceforge.net/#dbt2. These packages can bring a system
to its knees, so be sure to use them only on your development systems.

8.14 Examining Thread Information
When you are attempting to ascertain what your MySQL server is doing, it can be helpful to examine
the process list, which is the set of threads currently executing within the server. Process list
information is available from these sources:
• The SHOW [FULL] PROCESSLIST statement: Section 13.7.5.27, “SHOW PROCESSLIST Syntax”
• The SHOW PROFILE statement: Section 13.7.5.29, “SHOW PROFILES Syntax”
• The mysqladmin processlist command: Section 4.5.2, “mysqladmin — Client for
Administering a MySQL Server”
You can always view information about your own threads. To view information about threads being
executed for other accounts, you must have the PROCESS privilege.
Each process list entry contains several pieces of information:
• Id is the connection identifier for the client associated with the thread.
• User and Host indicate the account associated with the thread.
• db is the default database for the thread, or NULL if none is selected.
• Command and State indicate what the thread is doing.
Most states correspond to very quick operations. If a thread stays in a given state for many seconds,
there might be a problem that needs to be investigated.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Thread Command Values

• Time indicates how long the thread has been in its current state. The thread's notion of the current
time may be altered in some cases: The thread can change the time with SET TIMESTAMP =
value. For a thread running on a slave that is processing events from the master, the thread time is
set to the time found in the events and thus reflects current time on the master and not the slave.
• Info contains the text of the statement being executed by the thread, or NULL if it is not executing
one. By default, this value contains only the first 100 characters of the statement. To see the
complete statements, use SHOW FULL PROCESSLIST.
The following sections list the possible Command values, and State values grouped by category. The
meaning for some of these values is self-evident. For others, additional description is provided.

8.14.1 Thread Command Values
A thread can have any of the following Command values:
•

Binlog Dump
This is a thread on a master server for sending binary log contents to a slave server.

•

Change user
The thread is executing a change-user operation.

•

Close stmt
The thread is closing a prepared statement.

•

Connect
A replication slave is connected to its master.

•

Connect Out
A replication slave is connecting to its master.

•

Create DB
The thread is executing a create-database operation.

•

Daemon
This thread is internal to the server, not a thread that services a client connection.

•

Debug
The thread is generating debugging information.

•

Delayed insert
The thread is a delayed-insert handler.

•

Drop DB
The thread is executing a drop-database operation.

•

Error

•

Execute
The thread is executing a prepared statement.

•

Fetch

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Thread Command Values

The thread is fetching the results from executing a prepared statement.
•

Field List
The thread is retrieving information for table columns.

•

Init DB
The thread is selecting a default database.

•

Kill
The thread is killing another thread.

•

Long Data
The thread is retrieving long data in the result of executing a prepared statement.

•

Ping
The thread is handling a server-ping request.

•

Prepare
The thread is preparing a prepared statement.

•

Processlist
The thread is producing information about server threads.

•

Query
The thread is executing a statement.

•

Quit
The thread is terminating.

•

Refresh
The thread is flushing table, logs, or caches, or resetting status variable or replication server
information.

•

Register Slave
The thread is registering a slave server.

•

Reset stmt
The thread is resetting a prepared statement.

•

Set option
The thread is setting or resetting a client statement-execution option.

•

Shutdown
The thread is shutting down the server.

•

Sleep
The thread is waiting for the client to send a new statement to it.

•

Statistics

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

General Thread States

The thread is producing server-status information.
•

Table Dump
The thread is sending table contents to a slave server.

•

Time
Unused.

8.14.2 General Thread States
The following list describes thread State values that are associated with general query processing
and not more specialized activities such as replication. Many of these are useful only for finding bugs in
the server.
•

After create
This occurs when the thread creates a table (including internal temporary tables), at the end of the
function that creates the table. This state is used even if the table could not be created due to some
error.

•

Analyzing
The thread is calculating a MyISAM table key distributions (for example, for ANALYZE TABLE).

•

checking permissions
The thread is checking whether the server has the required privileges to execute the statement.

•

Checking table
The thread is performing a table check operation.

•

cleaning up
The thread has processed one command and is preparing to free memory and reset certain state
variables.

•

closing tables
The thread is flushing the changed table data to disk and closing the used tables. This should be a
fast operation. If not, you should verify that you do not have a full disk and that the disk is not in very
heavy use.

•

converting HEAP to MyISAM
The thread is converting an internal temporary table from a MEMORY table to an on-disk MyISAM
table.

•

copy to tmp table
The thread is processing an ALTER TABLE statement. This state occurs after the table with the new
structure has been created but before rows are copied into it.

•

Copying to group table
If a statement has different ORDER BY and GROUP BY criteria, the rows are sorted by group and
copied to a temporary table.

•

Copying to tmp table

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

General Thread States

The server is copying to a temporary table in memory.
•

Copying to tmp table on disk
The server is copying to a temporary table on disk. The temporary result set has become too large
(see Section 8.4.4, “Internal Temporary Table Use in MySQL”). Consequently, the thread is changing
the temporary table from in-memory to disk-based format to save memory.

•

Creating index
The thread is processing ALTER TABLE ... ENABLE KEYS for a MyISAM table.

•

Creating sort index
The thread is processing a SELECT that is resolved using an internal temporary table.

•

creating table
The thread is creating a table. This includes creation of temporary tables.

•

Creating tmp table
The thread is creating a temporary table in memory or on disk. If the table is created in memory
but later is converted to an on-disk table, the state during that operation will be Copying to tmp
table on disk.

•

deleting from main table
The server is executing the first part of a multiple-table delete. It is deleting only from the first table,
and saving columns and offsets to be used for deleting from the other (reference) tables.

•

deleting from reference tables
The server is executing the second part of a multiple-table delete and deleting the matched rows
from the other tables.

•

discard_or_import_tablespace
The thread is processing an ALTER TABLE ... DISCARD TABLESPACE or ALTER TABLE ...
IMPORT TABLESPACE statement.

•

end
This occurs at the end but before the cleanup of ALTER TABLE, CREATE VIEW, DELETE, INSERT,
SELECT, or UPDATE statements.

•

executing
The thread has begun executing a statement.

•

Execution of init_command
The thread is executing statements in the value of the init_command system variable.

•

freeing items
The thread has executed a command. Some freeing of items done during this state involves the
query cache. This state is usually followed by cleaning up.

•

Flushing tables
The thread is executing FLUSH TABLES and is waiting for all threads to close their tables.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

General Thread States

•

FULLTEXT initialization
The server is preparing to perform a natural-language full-text search.

•

init
This occurs before the initialization of ALTER TABLE, DELETE, INSERT, SELECT, or UPDATE
statements. Actions taken by the server in this state include flushing the binary log, the InnoDB log,
and some query cache cleanup operations.
For the end state, the following operations could be happening:
• Removing query cache entries after data in a table is changed
• Writing an event to the binary log
• Freeing memory buffers, including for blobs

•

Killed
Someone has sent a KILL statement to the thread and it should abort next time it checks the kill flag.
The flag is checked in each major loop in MySQL, but in some cases it might still take a short time
for the thread to die. If the thread is locked by some other thread, the kill takes effect as soon as the
other thread releases its lock.

•

Locked
The query is locked by another query.

•

logging slow query
The thread is writing a statement to the slow-query log.

•

login
The initial state for a connection thread until the client has been authenticated successfully.

•

NULL
This state is used for the SHOW PROCESSLIST state.

•

Opening tables, Opening table
The thread is trying to open a table. This is should be very fast procedure, unless something
prevents opening. For example, an ALTER TABLE or a LOCK TABLE statement can prevent opening
a table until the statement is finished. It is also worth checking that your table_cache value is large
enough.

•

optimizing
The server is performing initial optimizations for a query.

•

preparing
This state occurs during query optimization.

•

Purging old relay logs
The thread is removing unneeded relay log files.

•

query end
This state occurs after processing a query but before the freeing items state.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

General Thread States

•

Reading from net
The server is reading a packet from the network.

•

Removing duplicates
The query was using SELECT DISTINCT in such a way that MySQL could not optimize away the
distinct operation at an early stage. Because of this, MySQL requires an extra stage to remove all
duplicated rows before sending the result to the client.

•

removing tmp table
The thread is removing an internal temporary table after processing a SELECT statement. This state
is not used if no temporary table was created.

•

rename
The thread is renaming a table.

•

rename result table
The thread is processing an ALTER TABLE statement, has created the new table, and is renaming it
to replace the original table.

•

Reopen tables
The thread got a lock for the table, but noticed after getting the lock that the underlying table
structure changed. It has freed the lock, closed the table, and is trying to reopen it.

•

Repair by sorting
The repair code is using a sort to create indexes.

•

Repair done
The thread has completed a multi-threaded repair for a MyISAM table.

•

Repair with keycache
The repair code is using creating keys one by one through the key cache. This is much slower than
Repair by sorting.

•

Rolling back
The thread is rolling back a transaction.

•

Saving state
For MyISAM table operations such as repair or analysis, the thread is saving the new table state to
the .MYI file header. State includes information such as number of rows, the AUTO_INCREMENT
counter, and key distributions.

•

Searching rows for update
The thread is doing a first phase to find all matching rows before updating them. This has to be done
if the UPDATE is changing the index that is used to find the involved rows.

• Sending data
The thread is reading and processing rows for a SELECT statement, and sending data to the client.
Because operations occurring during this this state tend to perform large amounts of disk access
(reads), it is often the longest-running state over the lifetime of a given query.
•

setup

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

General Thread States

The thread is beginning an ALTER TABLE operation.
•

Sorting for group
The thread is doing a sort to satisfy a GROUP BY.

•

Sorting for order
The thread is doing a sort to satisfy an ORDER BY.

•

Sorting index
The thread is sorting index pages for more efficient access during a MyISAM table optimization
operation.

•

Sorting result
For a SELECT statement, this is similar to Creating sort index, but for nontemporary tables.

•

statistics
The server is calculating statistics to develop a query execution plan. If a thread is in this state for a
long time, the server is probably disk-bound performing other work.

•

System lock
The thread is going to request or is waiting for an internal or external system lock for the table. For
example, this can occur when InnoDB waits for a table-level lock during execution of LOCK TABLES.
If this state is being caused by requests for external locks and you are not using multiple mysqld
servers that are accessing the same MyISAM tables, you can disable external system locks with the
--skip-external-locking option. However, external locking is disabled by default, so it is likely
that this option will have no effect. For SHOW PROFILE, this state means the thread is requesting the
lock (not waiting for it).

•

Table lock
The next thread state after System lock. After acquiring a system lock, the thread is going to
request an internal table lock (a THR_LOCK lock).
For more information about table lock indicators, see Section 8.11.1, “Internal Locking Methods”.

•

update
The thread is getting ready to start updating the table.

•

Updating
The thread is searching for rows to update and is updating them.

•

updating main table
The server is executing the first part of a multiple-table update. It is updating only the first table, and
saving columns and offsets to be used for updating the other (reference) tables.

•

updating reference tables
The server is executing the second part of a multiple-table update and updating the matched rows
from the other tables.

•

User lock
The thread is going to request or is waiting for an advisory lock requested with a GET_LOCK() call.
For SHOW PROFILE, this state means the thread is requesting the lock (not waiting for it).

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Delayed-Insert Thread States

•

Waiting for release of readlock
The thread is waiting for a global read lock obtained by another thread (with FLUSH TABLES WITH
READ LOCK) to be released.

•

Waiting for tables, Waiting for table
The thread got a notification that the underlying structure for a table has changed and it needs to
reopen the table to get the new structure. However, to reopen the table, it must wait until all other
threads have closed the table in question.
This notification takes place if another thread has used FLUSH TABLES or one of the following
statements on the table in question: FLUSH TABLES tbl_name, ALTER TABLE, RENAME TABLE,
REPAIR TABLE, ANALYZE TABLE, or OPTIMIZE TABLE.

•

Waiting on cond
A generic state in which the thread is waiting for a condition to become true. No specific state
information is available.

•

Waiting to get readlock
The thread has issued a FLUSH TABLES WITH READ LOCK statement to obtain a global read lock
and is waiting to obtain the lock.

•

Writing to net
The server is writing a packet to the network.

8.14.3 Delayed-Insert Thread States
These thread states are associated with processing for DELAYED inserts (see Section 13.2.5.2,
“INSERT DELAYED Syntax”). Some states are associated with connection threads that process
INSERT DELAYED statements from clients. Other states are associated with delayed-insert handler
threads that insert the rows. There is a delayed-insert handler thread for each table for which INSERT
DELAYED statements are issued.
States associated with a connection thread that processes an INSERT DELAYED statement from the
client:
•

allocating local table
The thread is preparing to feed rows to the delayed-insert handler thread.

•

Creating delayed handler
The thread is creating a handler for DELAYED inserts.

•

got handler lock
This occurs before the allocating local table state and after the waiting for handler
lock state, when the connection thread gets access to the delayed-insert handler thread.

•

got old table
This occurs after the waiting for handler open state. The delayed-insert handler thread
has signaled that it has ended its initialization phase, which includes opening the table for delayed
inserts.

•

storing row into queue
The thread is adding a new row to the list of rows that the delayed-insert handler thread must insert.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Query Cache Thread States

•

waiting for delay_list
This occurs during the initialization phase when the thread is trying to find the delayed-insert handler
thread for the table, and before attempting to gain access to the list of delayed-insert threads.

•

waiting for handler insert
An INSERT DELAYED handler has processed all pending inserts and is waiting for new ones.

•

waiting for handler lock
This occurs before the allocating local table state when the connection thread waits for
access to the delayed-insert handler thread.

•

waiting for handler open
This occurs after the Creating delayed handler state and before the got old table state.
The delayed-insert handler thread has just been started, and the connection thread is waiting for it to
initialize.

States associated with a delayed-insert handler thread that inserts the rows:
•

insert
The state that occurs just before inserting rows into the table.

•

reschedule
After inserting a number of rows, the delayed-insert thread sleeps to let other threads do work.

•

upgrading lock
A delayed-insert handler is trying to get a lock for the table to insert rows.

•

Waiting for INSERT
A delayed-insert handler is waiting for a connection thread to add rows to the queue (see storing
row into queue).

8.14.4 Query Cache Thread States
These thread states are associated with the query cache (see Section 8.10.3, “The MySQL Query
Cache”).
•

checking privileges on cached query
The server is checking whether the user has privileges to access a cached query result.

•

checking query cache for query
The server is checking whether the current query is present in the query cache.

•

invalidating query cache entries
Query cache entries are being marked invalid because the underlying tables have changed.

•

sending cached result to client
The server is taking the result of a query from the query cache and sending it to the client.

•

storing result in query cache
The server is storing the result of a query in the query cache.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Replication Master Thread States

8.14.5 Replication Master Thread States
The following list shows the most common states you may see in the State column for the master's
Binlog Dump thread. If you see no Binlog Dump threads on a master server, this means that
replication is not running—that is, that no slaves are currently connected.
•

Sending binlog event to slave
Binary logs consist of events, where an event is usually an update plus some other information. The
thread has read an event from the binary log and is now sending it to the slave.

•

Finished reading one binlog; switching to next binlog
The thread has finished reading a binary log file and is opening the next one to send to the slave.

•

Has sent all binlog to slave; waiting for binlog to be updated
The thread has read all outstanding updates from the binary logs and sent them to the slave. The
thread is now idle, waiting for new events to appear in the binary log resulting from new updates
occurring on the master.

•

Waiting to finalize termination
A very brief state that occurs as the thread is stopping.

8.14.6 Replication Slave I/O Thread States
The following list shows the most common states you see in the State column for a slave server I/O
thread. This state also appears in the Slave_IO_State column displayed by SHOW SLAVE STATUS,
so you can get a good view of what is happening by using that statement.
•

Waiting for master update
The initial state before Connecting to master.

•

Connecting to master
The thread is attempting to connect to the master.

•

Checking master version
A state that occurs very briefly, after the connection to the master is established.

•

Registering slave on master
A state that occurs very briefly after the connection to the master is established.

•

Requesting binlog dump
A state that occurs very briefly, after the connection to the master is established. The thread sends
to the master a request for the contents of its binary logs, starting from the requested binary log file
name and position.

•

Waiting to reconnect after a failed binlog dump request
If the binary log dump request failed (due to disconnection), the thread goes into this state while it
sleeps, then tries to reconnect periodically. The interval between retries can be specified using the
CHANGE MASTER TO statement or the --master-connect-retry option.

•

Reconnecting after a failed binlog dump request
The thread is trying to reconnect to the master.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Replication Slave SQL Thread States

•

Waiting for master to send event
The thread has connected to the master and is waiting for binary log events to arrive. This can last
for a long time if the master is idle. If the wait lasts for slave_net_timeout seconds, a timeout
occurs. At that point, the thread considers the connection to be broken and makes an attempt to
reconnect.

•

Queueing master event to the relay log
The thread has read an event and is copying it to the relay log so that the SQL thread can process it.

•

Waiting to reconnect after a failed master event read
An error occurred while reading (due to disconnection). The thread is sleeping for the number of
seconds set by the CHANGE MASTER TO statement or --master-connect-retry option (default
60) before attempting to reconnect.

•

Reconnecting after a failed master event read
The thread is trying to reconnect to the master. When connection is established again, the state
becomes Waiting for master to send event.

•

Waiting for the slave SQL thread to free enough relay log space
You are using a nonzero relay_log_space_limit value, and the relay logs have grown large
enough that their combined size exceeds this value. The I/O thread is waiting until the SQL thread
frees enough space by processing relay log contents so that it can delete some relay log files.

•

Waiting for slave mutex on exit
A state that occurs briefly as the thread is stopping.

8.14.7 Replication Slave SQL Thread States
The following list shows the most common states you may see in the State column for a slave server
SQL thread:
•

Waiting for the next event in relay log
The initial state before Reading event from the relay log.

•

Reading event from the relay log
The thread has read an event from the relay log so that the event can be processed.

•

Has read all relay log; waiting for the slave I/O thread to update it
The thread has processed all events in the relay log files, and is now waiting for the I/O thread to
write new events to the relay log.

•

Making temp file
The thread is executing a LOAD DATA INFILE statement and is creating a temporary file containing
the data from which the slave will read rows.

•

Waiting for slave mutex on exit
A very brief state that occurs as the thread is stopping.

The State column for the I/O thread may also show the text of a statement. This indicates that the
thread has read an event from the relay log, extracted the statement from it, and is executing it.

8.14.8 Replication Slave Connection Thread States
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Cluster Thread States

These thread states occur on a replication slave but are associated with connection threads, not with
the I/O or SQL threads.
•

Changing master
The thread is processing a CHANGE MASTER TO statement.

•

Creating table from master dump
The slave is creating a table using the CREATE TABLE statement contained in the dump from the
master. Used for LOAD TABLE FROM MASTER and LOAD DATA FROM MASTER.

•

Killing slave
The thread is processing a STOP SLAVE statement.

•

Opening master dump table
This state occurs after Creating table from master dump.

•

Reading master dump table data
This state occurs after Opening master dump table.

•

Rebuilding the index on master dump table
This state occurs after Reading master dump table data.

•

starting slave
The thread is starting the slave threads after processing a successful LOAD DATA FROM MASTER
load operation.

8.14.9 MySQL Cluster Thread States
•

Committing events to binlog

•

Opening mysql.ndb_apply_status

•

Processing events
The thread is processing events for binary logging.

•

Processing events from schema table
The thread is doing the work of schema replication.

•

Shutting down

•

Syncing ndb table schema operation and binlog
This is used to have a correct binary log of schema operations for NDB.

•

Waiting for event from ndbcluster
The server is acting as an SQL node in a MySQL Cluster, and is connected to a cluster management
node.

•

Waiting for first event from ndbcluster

•

Waiting for ndbcluster binlog update to reach current position

•

Waiting for ndbcluster to start

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

MySQL Cluster Thread States

•

Waiting for schema epoch
The thread is waiting for a schema epoch (that is, a global checkpoint).

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 9 Language Structure
Table of Contents
9.1 Literal Values ......................................................................................................................
9.1.1 String Literals ...........................................................................................................
9.1.2 Number Literals ........................................................................................................
9.1.3 Date and Time Literals .............................................................................................
9.1.4 Hexadecimal Literals ................................................................................................
9.1.5 Boolean Literals .......................................................................................................
9.1.6 Bit-Field Literals .......................................................................................................
9.1.7 NULL Values ............................................................................................................
9.2 Schema Object Names ........................................................................................................
9.2.1 Identifier Qualifiers ....................................................................................................
9.2.2 Identifier Case Sensitivity ..........................................................................................
9.2.3 Function Name Parsing and Resolution .....................................................................
9.3 Keywords and Reserved Words ...........................................................................................
9.4 User-Defined Variables ........................................................................................................
9.5 Expression Syntax ..............................................................................................................
9.6 Comment Syntax .................................................................................................................

779
779
782
782
784
784
785
785
785
787
788
790
792
798
801
803

This chapter discusses the rules for writing the following elements of SQL statements when using
MySQL:
• Literal values such as strings and numbers
• Identifiers such as database, table, and column names
• Keywords and reserved words
• User-defined and system variables
• Comments

9.1 Literal Values
This section describes how to write literal values in MySQL. These include strings, numbers,
hexadecimal values, boolean values, and NULL. The section also covers the various nuances and
“gotchas” that you may run into when dealing with these basic types in MySQL.

9.1.1 String Literals
A string is a sequence of bytes or characters, enclosed within either single quote (“'”) or double quote
(“"”) characters. Examples:
'a string'
"another string"

Quoted strings placed next to each other are concatenated to a single string. The following lines are
equivalent:
'a string'
'a' ' ' 'string'

If the ANSI_QUOTES SQL mode is enabled, string literals can be quoted only within single quotation
marks because a string quoted within double quotation marks is interpreted as an identifier.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

String Literals

A binary string is a string of bytes that has no character set or collation. A nonbinary string is a string of
characters that has a character set and collation. For both types of strings, comparisons are based on
the numeric values of the string unit. For binary strings, the unit is the byte. For nonbinary strings the
unit is the character and some character sets support multibyte characters. Character value ordering is
a function of the string collation.
String literals may have an optional character set introducer and COLLATE clause:
[_charset_name]'string' [COLLATE collation_name]

Examples:
SELECT _latin1'string';
SELECT _latin1'string' COLLATE latin1_danish_ci;

You can use N'literal' (or n'literal') to create a string in the national character set. These
statements are equivalent:
SELECT N'some text';
SELECT n'some text';
SELECT _utf8'some text';

For more information about these forms of string syntax, see Section 10.1.3.5, “Character String Literal
Character Set and Collation”, and Section 10.1.3.6, “National Character Set”.
Within a string, certain sequences have special meaning unless the NO_BACKSLASH_ESCAPES SQL
mode is enabled. Each of these sequences begins with a backslash (“\”), known as the escape
character. MySQL recognizes the escape sequences shown in Table 9.1, “Special Character Escape
Sequences”. For all other escape sequences, backslash is ignored. That is, the escaped character is
interpreted as if it was not escaped. For example, “\x” is just “x”. These sequences are case sensitive.
For example, “\b” is interpreted as a backspace, but “\B” is interpreted as “B”. Escape processing is
done according to the character set indicated by the character_set_connection system variable.
This is true even for strings that are preceded by an introducer that indicates a different character set,
as discussed in Section 10.1.3.5, “Character String Literal Character Set and Collation”.
Table 9.1 Special Character Escape Sequences
Escape
Sequence

Character Represented by Sequence

\0

An ASCII NUL (X'00') character

\'

A single quote (“'”) character

\"

A double quote (“"”) character

\b

A backspace character

\n

A newline (linefeed) character

\r

A carriage return character

\t

A tab character

\Z

ASCII 26 (Control+Z); see note following the table

\\

A backslash (“\”) character

\%

A “%” character; see note following the table

\_

A “_” character; see note following the table

The ASCII 26 character can be encoded as “\Z” to enable you to work around the problem that ASCII
26 stands for END-OF-FILE on Windows. ASCII 26 within a file causes problems if you try to use
mysql db_name < file_name.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

String Literals

The “\%” and “\_” sequences are used to search for literal instances of “%” and “_” in pattern-matching
contexts where they would otherwise be interpreted as wildcard characters. See the description of
the LIKE operator in Section 12.5.1, “String Comparison Functions”. If you use “\%” or “\_” outside of
pattern-matching contexts, they evaluate to the strings “\%” and “\_”, not to “%” and “_”.
There are several ways to include quote characters within a string:
• A “'” inside a string quoted with “'” may be written as “''”.
• A “"” inside a string quoted with “"” may be written as “""”.
• Precede the quote character by an escape character (“\”).
• A “'” inside a string quoted with “"” needs no special treatment and need not be doubled or escaped.
In the same way, “"” inside a string quoted with “'” needs no special treatment.
The following SELECT statements demonstrate how quoting and escaping work:
mysql> SELECT 'hello', '"hello"', '""hello""', 'hel''lo', '\'hello';
+-------+---------+-----------+--------+--------+
| hello | "hello" | ""hello"" | hel'lo | 'hello |
+-------+---------+-----------+--------+--------+
mysql> SELECT "hello", "'hello'", "''hello''", "hel""lo", "\"hello";
+-------+---------+-----------+--------+--------+
| hello | 'hello' | ''hello'' | hel"lo | "hello |
+-------+---------+-----------+--------+--------+
mysql> SELECT 'This\nIs\nFour\nLines';
+--------------------+
| This
Is
Four
Lines |
+--------------------+
mysql> SELECT 'disappearing\ backslash';
+------------------------+
| disappearing backslash |
+------------------------+

If you want to insert binary data into a string column (such as a BLOB column), you should represent
certain characters by escape sequences. Backslash (“\”) and the quote character used to quote
the string must be escaped. In certain client environments, it may also be necessary to escape
NUL or Control+Z. The mysql client truncates quoted strings containing NUL characters if they are
not escaped, and Control+Z may be taken for END-OF-FILE on Windows if not escaped. For the
escape sequences that represent each of these characters, see Table 9.1, “Special Character Escape
Sequences”.
When writing application programs, any string that might contain any of these special characters must
be properly escaped before the string is used as a data value in an SQL statement that is sent to the
MySQL server. You can do this in two ways:
• Process the string with a function that escapes the special characters. In a C program, you can use
the mysql_real_escape_string() C API function to escape characters. See Section 20.6.7.53,
“mysql_real_escape_string()”. Within SQL statements that construct other SQL statements, you
can use the QUOTE() function. The Perl DBI interface provides a quote method to convert special
characters to the proper escape sequences. See Section 20.8, “MySQL Perl API”. Other language
interfaces may provide a similar capability.
• As an alternative to explicitly escaping special characters, many MySQL APIs provide a placeholder
capability that enables you to insert special markers into a statement string, and then bind data
values to them when you issue the statement. In this case, the API takes care of escaping special
characters in the values for you.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Number Literals

9.1.2 Number Literals
Number literals include exact-value (integer and DECIMAL) literals and approximate-value (floatingpoint) literals.
Integers are represented as a sequence of digits. Numbers may include “.” as a decimal separator.
Numbers may be preceded by “-” or “+” to indicate a negative or positive value, respectively. Numbers
represented in scientific notation with a mantissa and exponent are approximate-value numbers.
Exact-value numeric literals have an integer part or fractional part, or both. They may be signed.
Examples: 1, .2, 3.4, -5, -6.78, +9.10.
Approximate-value numeric literals are represented in scientific notation with a mantissa and exponent.
Either or both parts may be signed. Examples: 1.2E3, 1.2E-3, -1.2E3, -1.2E-3.
Two numbers that look similar may be treated differently. For example, 2.34 is an exact-value (fixedpoint) number, whereas 2.34E0 is an approximate-value (floating-point) number.
The DECIMAL data type is a fixed-point type and calculations are exact. In MySQL, the DECIMAL type
has several synonyms: NUMERIC, DEC, FIXED. The integer types also are exact-value types. For more
information about exact-value calculations, see Section 12.17, “Precision Math”.
The FLOAT and DOUBLE data types are floating-point types and calculations are approximate. In
MySQL, types that are synonymous with FLOAT or DOUBLE are DOUBLE PRECISION and REAL.
An integer may be used in a floating-point context; it is interpreted as the equivalent floating-point
number.

9.1.3 Date and Time Literals
Date and time values can be represented in several formats, such as quoted strings or as numbers,
depending on the exact type of the value and other factors. For example, in contexts where MySQL
expects a date, it interprets any of '2015-07-21', '20150721', and 20150721 as a date.
This section describes the acceptable formats for date and time literals. For more information about the
temporal data types, such as the range of permitted values, consult these sections:
• Section 11.1.2, “Date and Time Type Overview”
• Section 11.3, “Date and Time Types”
Standard SQL and ODBC Date and Time Literals.
Standard SQL permits temporal literals to be
specified using a type keyword and a string. The space between the keyword and string is optional.
DATE 'str'
TIME 'str'
TIMESTAMP 'str'

MySQL recognizes those constructions and also the corresponding ODBC syntax:
{ d 'str' }
{ t 'str' }
{ ts 'str' }

However, MySQL ignores the type keyword and each of the preceding constructions produces the
string value 'str', with a type of VARCHAR.
String and Numeric Literals in Date and Time Context.
formats:

MySQL recognizes DATE values in these

• As a string in either 'YYYY-MM-DD' or 'YY-MM-DD' format. A “relaxed” syntax is permitted:
Any punctuation character may be used as the delimiter between date parts. For example,
'2012-12-31', '2012/12/31', '2012^12^31', and '2012@12@31' are equivalent.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Date and Time Literals

• As a string with no delimiters in either 'YYYYMMDD' or 'YYMMDD' format, provided that the
string makes sense as a date. For example, '20070523' and '070523' are interpreted as
'2007-05-23', but '071332' is illegal (it has nonsensical month and day parts) and becomes
'0000-00-00'.
• As a number in either YYYYMMDD or YYMMDD format, provided that the number makes sense as a
date. For example, 19830905 and 830905 are interpreted as '1983-09-05'.
MySQL recognizes DATETIME and TIMESTAMP values in these formats:
• As a string in either 'YYYY-MM-DD HH:MM:SS' or 'YY-MM-DD HH:MM:SS' format. A “relaxed”
syntax is permitted here, too: Any punctuation character may be used as the delimiter between
date parts or time parts. For example, '2012-12-31 11:30:45', '2012^12^31 11+30+45',
'2012/12/31 11*30*45', and '2012@12@31 11^30^45' are equivalent.
The date and time parts can be separated by T rather than a space. For example, '2012-12-31
11:30:45' '2012-12-31T11:30:45' are equivalent.
• As a string with no delimiters in either 'YYYYMMDDHHMMSS' or 'YYMMDDHHMMSS' format, provided
that the string makes sense as a date. For example, '20070523091528' and '070523091528'
are interpreted as '2007-05-23 09:15:28', but '071122129015' is illegal (it has a nonsensical
minute part) and becomes '0000-00-00 00:00:00'.
• As a number in either YYYYMMDDHHMMSS or YYMMDDHHMMSS format, provided that the number
makes sense as a date. For example, 19830905132800 and 830905132800 are interpreted as
'1983-09-05 13:28:00'.
A DATETIME or TIMESTAMP value can include a trailing fractional seconds part in up to microseconds
(6 digits) precision. Although this fractional part is recognized, it is discarded from values stored into
DATETIME or TIMESTAMP columns. For information about fractional seconds support in MySQL, see
Section 11.3.6, “Fractional Seconds in Time Values”.
Dates containing two-digit year values are ambiguous because the century is unknown. MySQL
interprets two-digit year values using these rules:
• Year values in the range 70-99 are converted to 1970-1999.
• Year values in the range 00-69 are converted to 2000-2069.
See also Section 11.3.8, “Two-Digit Years in Dates”.
For values specified as strings that include date part delimiters, it is unnecessary to specify two digits
for month or day values that are less than 10. '2015-6-9' is the same as '2015-06-09'. Similarly,
for values specified as strings that include time part delimiters, it is unnecessary to specify two digits
for hour, minute, or second values that are less than 10. '2015-10-30 1:2:3' is the same as
'2015-10-30 01:02:03'.
Values specified as numbers should be 6, 8, 12, or 14 digits long. If a number is 8 or 14 digits long, it
is assumed to be in YYYYMMDD or YYYYMMDDHHMMSS format and that the year is given by the first 4
digits. If the number is 6 or 12 digits long, it is assumed to be in YYMMDD or YYMMDDHHMMSS format and
that the year is given by the first 2 digits. Numbers that are not one of these lengths are interpreted as
though padded with leading zeros to the closest length.
Values specified as nondelimited strings are interpreted according their length. For a string 8 or 14
characters long, the year is assumed to be given by the first 4 characters. Otherwise, the year is
assumed to be given by the first 2 characters. The string is interpreted from left to right to find year,
month, day, hour, minute, and second values, for as many parts as are present in the string. This
means you should not use strings that have fewer than 6 characters. For example, if you specify
'9903', thinking that represents March, 1999, MySQL converts it to the “zero” date value. This occurs
because the year and month values are 99 and 03, but the day part is completely missing. However,
you can explicitly specify a value of zero to represent missing month or day parts. For example, to
insert the value '1999-03-00', use '990300'.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Hexadecimal Literals

MySQL recognizes TIME values in these formats:
• As a string in 'D HH:MM:SS' format. You can also use one of the following “relaxed” syntaxes:
'HH:MM:SS', 'HH:MM', 'D HH:MM', 'D HH', or 'SS'. Here D represents days and can have a
value from 0 to 34.
• As a string with no delimiters in 'HHMMSS' format, provided that it makes sense as a time. For
example, '101112' is understood as '10:11:12', but '109712' is illegal (it has a nonsensical
minute part) and becomes '00:00:00'.
• As a number in HHMMSS format, provided that it makes sense as a time. For example, 101112 is
understood as '10:11:12'. The following alternative formats are also understood: SS, MMSS, or
HHMMSS.
A trailing fractional seconds part is recognized in the 'D HH:MM:SS.fraction',
'HH:MM:SS.fraction', 'HHMMSS.fraction', and HHMMSS.fraction time formats, where
fraction is the fractional part in up to microseconds (6 digits) precision. Although this fractional part
is recognized, it is discarded from values stored into TIME columns. For information about fractional
seconds support in MySQL, see Section 11.3.6, “Fractional Seconds in Time Values”.
For TIME values specified as strings that include a time part delimiter, it is unnecessary to specify
two digits for hours, minutes, or seconds values that are less than 10. '8:3:2' is the same as
'08:03:02'.

9.1.4 Hexadecimal Literals
MySQL supports hexadecimal values, written using X'val', x'val', or 0xval format, where val
contains hexadecimal digits (0..9, A..F). Lettercase of the digits does not matter. For values written
using X'val' or x'val' format, val must contain an even number of digits. For values written using
0xval syntax, values that contain an odd number of digits are treated as having an extra leading 0.
For example, 0x0a and 0xaaa are interpreted as 0x0a and 0x0aaa.
In numeric contexts, hexadecimal values act like integers (64-bit precision). In string contexts, they act
like binary strings, where each pair of hex digits is converted to a character:
mysql> SELECT X'4D7953514C';
-> 'MySQL'
mysql> SELECT x'0a'+0;
-> 10
mysql> SELECT 0x5061756c;
-> 'Paul'

The default type of a hexadecimal value is a string. If you want to ensure that the value is treated as a
number, you can use CAST(... AS UNSIGNED):
mysql> SELECT X'41', CAST(X'41' AS UNSIGNED);
-> 'A', 65

The X'hexstring' and x'val' syntaxes are based on standard SQL. The 0x syntax is based on
ODBC. Hexadecimal strings are often used by ODBC to supply values for BLOB columns.
To convert a string or a number to a string in hexadecimal format, use the HEX() function:
mysql> SELECT HEX('cat');
-> '636174'
mysql> SELECT X'636174';
-> 'cat'

9.1.5 Boolean Literals
The constants TRUE and FALSE evaluate to 1 and 0, respectively. The constant names can be written
in any lettercase.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Bit-Field Literals

mysql> SELECT TRUE, true, FALSE, false;
-> 1, 1, 0, 0

9.1.6 Bit-Field Literals
Beginning with MySQL 5.0.3, bit-field values can be written using b'value' or 0bvalue notation.
value is a binary value written using zeros and ones.
Bit-field notation is convenient for specifying values to be assigned to BIT columns:

mysql>
mysql>
mysql>
mysql>

CREATE
INSERT
INSERT
INSERT

TABLE t (b
INTO t SET
INTO t SET
INTO t SET

BIT(8));
b = b'11111111';
b = b'1010';
b = b'0101';

Bit values are returned as binary values. To display them in printable form, add 0 or use a conversion
function such as BIN(). High-order 0 bits are not displayed in the converted value.
mysql> SELECT b+0, BIN(b+0), OCT(b+0), HEX(b+0) FROM t;
+------+----------+----------+----------+
| b+0 | BIN(b+0) | OCT(b+0) | HEX(b+0) |
+------+----------+----------+----------+
| 255 | 11111111 | 377
| FF
|
|
10 | 1010
| 12
| A
|
|
5 | 101
| 5
| 5
|
+------+----------+----------+----------+

Bit values assigned to user variables are treated as binary strings. To assign a bit value as a number to
a user variable, use CAST() or +0:
mysql> SET @v1 = 0b1000001;
mysql> SET @v2 = CAST(0b1000001 AS UNSIGNED), @v3 = 0b1000001+0;
mysql> SELECT @v1, @v2, @v3;
+------+------+------+
| @v1 | @v2 | @v3 |
+------+------+------+
| A
|
65 |
65 |
+------+------+------+

9.1.7 NULL Values
The NULL value means “no data.” NULL can be written in any lettercase. A synonym is \N (case
sensitive).
For text file import or export operations performed with LOAD DATA INFILE or SELECT ... INTO
OUTFILE, NULL is represented by the \N sequence. See Section 13.2.6, “LOAD DATA INFILE
Syntax”.
Be aware that the NULL value is different from values such as 0 for numeric types or the empty string
for string types. For more information, see Section B.5.4.3, “Problems with NULL Values”.

9.2 Schema Object Names
Certain objects within MySQL, including database, table, index, column, alias, view, stored procedure,
partition, and other object names are known as identifiers. This section describes the permissible
syntax for identifiers in MySQL. Section 9.2.2, “Identifier Case Sensitivity”, describes which types of
identifiers are case sensitive and under what conditions.
An identifier may be quoted or unquoted. If an identifier contains special characters or is a reserved
word, you must quote it whenever you refer to it. (Exception: A reserved word that follows a period
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Schema Object Names

in a qualified name must be an identifier, so it need not be quoted.) Reserved words are listed at
Section 9.3, “Keywords and Reserved Words”.
Identifiers are converted to Unicode internally. They may contain these characters:
• Permitted characters in unquoted identifiers:
• ASCII: [0-9,a-z,A-Z$_] (basic Latin letters, digits 0-9, dollar, underscore)
• Extended: U+0080 .. U+FFFF
• Permitted characters in quoted identifiers include the full Unicode Basic Multilingual Plane (BMP),
except U+0000:
• ASCII: U+0001 .. U+007F
• Extended: U+0080 .. U+FFFF
• ASCII NUL (U+0000) and supplementary characters (U+10000 and higher) are not permitted in
quoted or unquoted identifiers.
• Identifiers may begin with a digit but unless quoted may not consist solely of digits.
• Database, table, and column names cannot end with space characters.
• Database and table names cannot contain “/”, “\”, “.”, or characters that are not permitted in file
names.
The identifier quote character is the backtick (“`”):
mysql> SELECT * FROM `select` WHERE `select`.id > 100;

If the ANSI_QUOTES SQL mode is enabled, it is also permissible to quote identifiers within double
quotation marks:
mysql> CREATE TABLE "test" (col INT);
ERROR 1064: You have an error in your SQL syntax...
mysql> SET sql_mode='ANSI_QUOTES';
mysql> CREATE TABLE "test" (col INT);
Query OK, 0 rows affected (0.00 sec)

The ANSI_QUOTES mode causes the server to interpret double-quoted strings as identifiers.
Consequently, when this mode is enabled, string literals must be enclosed within single quotation
marks. They cannot be enclosed within double quotation marks. The server SQL mode is controlled as
described in Section 5.1.7, “Server SQL Modes”.
Identifier quote characters can be included within an identifier if you quote the identifier. If the character
to be included within the identifier is the same as that used to quote the identifier itself, then you need
to double the character. The following statement creates a table named a`b that contains a column
named c"d:
mysql> CREATE TABLE `a``b` (`c"d` INT);

In the select list of a query, a quoted column alias can be specified using identifier or string quoting
characters:
mysql> SELECT 1 AS `one`, 2 AS 'two';
+-----+-----+
| one | two |
+-----+-----+
|
1 |
2 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Identifier Qualifiers

+-----+-----+

Elsewhere in the statement, quoted references to the alias must use identifier quoting or the reference
is treated as a string literal.
It is recommended that you do not use names that begin with Me or MeN, where M and N are integers.
For example, avoid using 1e as an identifier, because an expression such as 1e+3 is ambiguous.
Depending on context, it might be interpreted as the expression 1e + 3 or as the number 1e+3.
Be careful when using MD5() to produce table names because it can produce names in illegal or
ambiguous formats such as those just described.
A user variable cannot be used directly in an SQL statement as an identifier or as part of an identifier.
See Section 9.4, “User-Defined Variables”, for more information and examples of workarounds.
The following table describes the maximum length for each type of identifier.
Identifier

Maximum Length (characters)

Database

64 (NDB storage engine: 63)

Table

64 (NDB storage engine: 63)

Column

64

Index

64

Constraint

64

Stored Program

64

View

64

Alias

256 (see exception following table)

Compound Statement Label

16

As of MySQL 5.0.52, aliases for column names in CREATE VIEW statements are checked against the
maximum column length of 64 characters (not the maximum alias length of 256 characters).
Identifiers are stored using Unicode (UTF-8). This applies to identifiers in table definitions that are
stored in .frm files and to identifiers stored in the grant tables in the mysql database. The sizes of
the identifier string columns in the grant tables are measured in characters. You can use multibyte
characters without reducing the number of characters permitted for values stored in these columns. As
indicated earlier, the permissible Unicode characters are those in the Basic Multilingual Plane (BMP).
Supplementary characters are not permitted.
For tables using the NDB storage engine, there is an additional requirement that the combined length of
a table name and the name of the database in which it is found must not exceed 122 characters. See
Section 17.1.5.5, “Limits Associated with Database Objects in MySQL Cluster”.

9.2.1 Identifier Qualifiers
MySQL permits names that consist of a single identifier or multiple identifiers. The components of a
multiple-part name must be separated by period (“.”) characters. The initial parts of a multiple-part
name act as qualifiers that affect the context within which the final identifier is interpreted.
In MySQL, you can refer to a table column using any of the following forms.
Column Reference

Meaning

col_name

The column col_name from whichever table used in the statement
contains a column of that name.

tbl_name.col_name

The column col_name from table tbl_name of the default database.

db_name.tbl_name.col_name
The column col_name from table tbl_name of the database
db_name.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Identifier Case Sensitivity

The qualifier character is a separate token and need not be contiguous with the associated identifiers.
For example, tbl_name.col_name and tbl_name . col_name are equivalent.
If any components of a multiple-part name require quoting, quote them individually rather than quoting
the name as a whole. For example, write `my-table`.`my-column`, not `my-table.mycolumn`.
A reserved word that follows a period in a qualified name must be an identifier, so in that context it
need not be quoted.
You need not specify a tbl_name or db_name.tbl_name prefix for a column reference in a
statement unless the reference would be ambiguous. Suppose that tables t1 and t2 each contain
a column c, and you retrieve c in a SELECT statement that uses both t1 and t2. In this case, c is
ambiguous because it is not unique among the tables used in the statement. You must qualify it with a
table name as t1.c or t2.c to indicate which table you mean. Similarly, to retrieve from a table t in
database db1 and from a table t in database db2 in the same statement, you must refer to columns in
those tables as db1.t.col_name and db2.t.col_name.
The syntax .tbl_name means the table tbl_name in the default database. This syntax is accepted
for ODBC compatibility because some ODBC programs prefix table names with a “.” character.

9.2.2 Identifier Case Sensitivity
In MySQL, databases correspond to directories within the data directory. Each table within a database
corresponds to at least one file within the database directory (and possibly more, depending on the
storage engine). Consequently, the case sensitivity of the underlying operating system plays a part
in the case sensitivity of database and table names. This means database and table names are not
case sensitive in Windows, and case sensitive in most varieties of Unix. One notable exception is OS
X, which is Unix-based but uses a default file system type (HFS+) that is not case sensitive. However,
OS X also supports UFS volumes, which are case sensitive just as on any Unix. See Section 1.8.1,
“MySQL Extensions to Standard SQL”. The lower_case_table_names system variable also affects
how the server handles identifier case sensitivity, as described later in this section.
Note
Although database and table names are not case sensitive on some platforms,
you should not refer to a given database or table using different cases within the
same statement. The following statement would not work because it refers to a
table both as my_table and as MY_TABLE:
mysql> SELECT * FROM my_table WHERE MY_TABLE.col=1;

Column, index, and stored routine names are not case sensitive on any platform, nor are column
aliases. Trigger names are case sensitive, which differs from standard SQL.
By default, table aliases are case sensitive on Unix, but not so on Windows or OS X. The following
statement would not work on Unix, because it refers to the alias both as a and as A:
mysql> SELECT col_name FROM tbl_name AS a
-> WHERE a.col_name = 1 OR A.col_name = 2;

However, this same statement is permitted on Windows. To avoid problems caused by such
differences, it is best to adopt a consistent convention, such as always creating and referring to
databases and tables using lowercase names. This convention is recommended for maximum
portability and ease of use.
How table and database names are stored on disk and used in MySQL is affected by the
lower_case_table_names system variable, which you can set when starting mysqld.
lower_case_table_names can take the values shown in the following table. On Unix, the default
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Identifier Case Sensitivity

value of lower_case_table_names is 0. On Windows, the default value is 1. On OS X, the default
value is 2.
Value

Meaning

0

Table and database names are stored on disk using the lettercase specified in the CREATE
TABLE or CREATE DATABASE statement. Name comparisons are case sensitive. You
should not set this variable to 0 if you are running MySQL on a system that has caseinsensitive file names (such as Windows or OS X). If you force this variable to 0 with -lower-case-table-names=0 on a case-insensitive file system and access MyISAM
tablenames using different lettercases, index corruption may result.

1

Table names are stored in lowercase on disk and name comparisons are not case
sensitive. MySQL converts all table names to lowercase on storage and lookup. This
behavior also applies to database names and table aliases.

2

Table and database names are stored on disk using the lettercase specified in the
CREATE TABLE or CREATE DATABASE statement, but MySQL converts them to
lowercase on lookup. Name comparisons are not case sensitive. This works only on file
systems that are not case sensitive! InnoDB table names are stored in lowercase, as for
lower_case_table_names=1.

If you are using MySQL on only one platform, you do not normally have to change the
lower_case_table_names variable from its default value. However, you may encounter difficulties if
you want to transfer tables between platforms that differ in file system case sensitivity. For example, on
Unix, you can have two different tables named my_table and MY_TABLE, but on Windows these two
names are considered identical. To avoid data transfer problems arising from lettercase of database or
table names, you have two options:
• Use lower_case_table_names=1 on all systems. The main disadvantage with this is that when
you use SHOW TABLES or SHOW DATABASES, you do not see the names in their original lettercase.
• Use lower_case_table_names=0 on Unix and lower_case_table_names=2 on Windows.
This preserves the lettercase of database and table names. The disadvantage of this is that you
must ensure that your statements always refer to your database and table names with the correct
lettercase on Windows. If you transfer your statements to Unix, where lettercase is significant, they
do not work if the lettercase is incorrect.
Exception: If you are using InnoDB tables and you are trying to avoid these data transfer problems,
you should set lower_case_table_names to 1 on all platforms to force names to be converted to
lowercase.
If you plan to set the lower_case_table_names system variable to 1 on Unix, you must first convert
your old database and table names to lowercase before stopping mysqld and restarting it with the new
variable setting. To do this for an individual table, use RENAME TABLE:
RENAME TABLE T1 TO t1;

To convert one or more entire databases, dump them before setting lower_case_table_names,
then drop the databases, and reload them after setting lower_case_table_names:
1. Use mysqldump to dump each database:
mysqldump --databases db1 > db1.sql
mysqldump --databases db2 > db2.sql
...

Do this for each database that must be recreated.
2. Use DROP DATABASE to drop each database.
3. Stop the server, set lower_case_table_names, and restart the server.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Function Name Parsing and Resolution

4. Reload the dump file for each database. Because lower_case_table_names is set, each
database and table name will be converted to lowercase as it is recreated:
mysql < db1.sql
mysql < db2.sql
...

Object names may be considered duplicates if their uppercase forms are equal according to a binary
collation. That is true for names of cursors, conditions, procedures, functions, savepoints, stored
routine parameters and stored program local variables. It is not true for names of names of columns,
constraints, databases, statements prepared with PREPARE, tables, triggers, users, and user-defined
variables.

9.2.3 Function Name Parsing and Resolution
MySQL 5.0 supports built-in (native) functions, user-defined functions (UDFs), and stored functions.
This section describes how the server recognizes whether the name of a built-in function is used as
a function call or as an identifier, and how the server determines which function to use in cases when
functions of different types exist with a given name.
Built-In Function Name Parsing
The parser uses default rules for parsing names of built-in functions. These rules can be changed by
enabling the IGNORE_SPACE SQL mode.
When the parser encounters a word that is the name of a built-in function, it must determine whether
the name signifies a function call or is instead a nonexpression reference to an identifier such as a
table or column name. For example, in the following statements, the first reference to count is a
function call, whereas the second reference is a table name:
SELECT COUNT(*) FROM mytable;
CREATE TABLE count (i INT);

The parser should recognize the name of a built-in function as indicating a function call only when
parsing what is expected to be an expression. That is, in nonexpression context, function names are
permitted as identifiers.
However, some built-in functions have special parsing or implementation considerations, so the parser
uses the following rules by default to distinguish whether their names are being used as function calls
or as identifiers in nonexpression context:
• To use the name as a function call in an expression, there must be no whitespace between the name
and the following “(” parenthesis character.
• Conversely, to use the function name as an identifier, it must not be followed immediately by a
parenthesis.
The requirement that function calls be written with no whitespace between the name and the
parenthesis applies only to the built-in functions that have special considerations. COUNT is one such
name. The sql_functions[] array in the sql/lex.h source file lists the names of these special
functions for which following whitespace determines their interpretation. Before MySQL 5.1, these are
rather numerous (about 200). In MySQL 5.1, parser improvements reduce to about 30 the number of
affected function names. You may find it easiest to treat the no-whitespace requirement as applying to
all function calls.
For functions not listed as special in sql/lex.h, whitespace does not matter. They are interpreted as
function calls only when used in expression context and may be used freely as identifiers otherwise.
ASCII is one such name. However, for these nonaffected function names, interpretation may vary in
expression context: func_name () is interpreted as a built-in function if there is one with the given
name; if not, func_name () is interpreted as a user-defined function or stored function if one exists
with that name.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Function Name Parsing and Resolution

The IGNORE_SPACE SQL mode can be used to modify how the parser treats function names that are
whitespace-sensitive:
• With IGNORE_SPACE disabled, the parser interprets the name as a function call when there is no
whitespace between the name and the following parenthesis. This occurs even when the function
name is used in nonexpression context:
mysql> CREATE TABLE count(i INT);
ERROR 1064 (42000): You have an error in your SQL syntax ...
near 'count(i INT)'

To eliminate the error and cause the name to be treated as an identifier, either use whitespace
following the name or write it as a quoted identifier (or both):
CREATE TABLE count (i INT);
CREATE TABLE `count`(i INT);
CREATE TABLE `count` (i INT);

• With IGNORE_SPACE enabled, the parser loosens the requirement that there be no whitespace
between the function name and the following parenthesis. This provides more flexibility in writing
function calls. For example, either of the following function calls are legal:
SELECT COUNT(*) FROM mytable;
SELECT COUNT (*) FROM mytable;

However, enabling IGNORE_SPACE also has the side effect that the parser treats the affected
function names as reserved words (see Section 9.3, “Keywords and Reserved Words”). This means
that a space following the name no longer signifies its use as an identifier. The name can be used
in function calls with or without following whitespace, but causes a syntax error in nonexpression
context unless it is quoted. For example, with IGNORE_SPACE enabled, both of the following
statements fail with a syntax error because the parser interprets count as a reserved word:
CREATE TABLE count(i INT);
CREATE TABLE count (i INT);

To use the function name in nonexpression context, write it as a quoted identifier:
CREATE TABLE `count`(i INT);
CREATE TABLE `count` (i INT);

To enable the IGNORE_SPACE SQL mode, use this statement:
SET sql_mode = 'IGNORE_SPACE';

IGNORE_SPACE is also enabled by certain other composite modes such as ANSI that include it in their
value:
SET sql_mode = 'ANSI';

Check Section 5.1.7, “Server SQL Modes”, to see which composite modes enable IGNORE_SPACE.
To minimize the dependency of SQL code on the IGNORE_SPACE setting, use these guidelines:
• Avoid creating UDFs or stored functions that have the same name as a built-in function.
• Avoid using function names in nonexpression context. For example, these statements use count
(one of the affected function names affected by IGNORE_SPACE), so they fail with or without
whitespace following the name if IGNORE_SPACE is enabled:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

CREATE TABLE count(i INT);
CREATE TABLE count (i INT);

If you must use a function name in nonexpression context, write it as a quoted identifier:
CREATE TABLE `count`(i INT);
CREATE TABLE `count` (i INT);

Function Name Resolution
The following rules describe how the server resolves references to function names for function creation
and invocation:
• Built-in functions and user-defined functions
A UDF can be created with the same name as a built-in function but the UDF cannot be invoked
because the parser resolves invocations of the function to refer to the built-in function. For example,
if you create a UDF named ABS, references to ABS() invoke the built-in function.
• Built-in functions and stored functions
It is possible to create a stored function with the same name as a built-in function, but to invoke the
stored function it is necessary to qualify it with a database name. For example, if you create a stored
function named PI in the test database, you invoke it as test.PI() because the server resolves
PI() as a reference to the built-in function.
• User-defined functions and stored functions
User-defined functions and stored functions share the same namespace, so you cannot create a
UDF and a stored function with the same name.
The preceding function name resolution rules have implications for upgrading to versions of MySQL
that implement new built-in functions:
• If you have already created a user-defined function with a given name and upgrade MySQL to a
version that implements a new built-in function with the same name, the UDF becomes inaccessible.
To correct this, use DROP FUNCTION to drop the UDF and CREATE FUNCTION to re-create the UDF
with a different nonconflicting name. Then modify any affected code to use the new name.
• If a new version of MySQL implements a built-in function with the same name as an existing stored
function, you have two choices: Rename the stored function to use a nonconflicting name, or change
calls to the function so that they use a schema qualifier (that is, use schema_name.func_name()
syntax). In either case, modify any affected code accordingly.

9.3 Keywords and Reserved Words
Keywords are words that have significance in SQL. Certain keywords, such as SELECT, DELETE, or
BIGINT, are reserved and require special treatment for use as identifiers such as table and column
names. This may also be true for the names of built-in functions.
Nonreserved keywords are permitted as identifiers without quoting. Reserved words are permitted as
identifiers if you quote them as described in Section 9.2, “Schema Object Names”:
mysql> CREATE TABLE interval (begin INT, end INT);
ERROR 1064 (42000): You have an error in your SQL syntax ...
near 'interval (begin INT, end INT)'

BEGIN and END are keywords but not reserved, so their use as identifiers does not require quoting.
INTERVAL is a reserved keyword and must be quoted to be used as an identifier:
mysql> CREATE TABLE `interval` (begin INT, end INT);
Query OK, 0 rows affected (0.01 sec)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

Exception: A word that follows a period in a qualified name must be an identifier, so it need not be
quoted even if it is reserved:
mysql> CREATE TABLE mydb.interval (begin INT, end INT);
Query OK, 0 rows affected (0.01 sec)

Names of built-in functions are permitted as identifiers but may require care to be used as such. For
example, COUNT is acceptable as a column name. However, by default, no whitespace is permitted
in function invocations between the function name and the following “(” character. This requirement
enables the parser to distinguish whether the name is used in a function call or in nonfunction context.
For further details on recognition of function names, see Section 9.2.3, “Function Name Parsing and
Resolution”.
The following table shows the keywords and reserved words in MySQL 5.0. Reserved keywords are
marked with (R).
At some point, you might upgrade to a higher version, so it is a good idea to have a look at future
reserved words, too. You can find these in the manuals that cover higher versions of MySQL. Most of
the reserved words in the table are forbidden by standard SQL as column or table names (for example,
GROUP). A few are reserved because MySQL needs them and uses a yacc parser.
Table 9.2 Keywords and Reserved Words in MySQL 5.0
ACTION

ADD (R)

AFTER

AGAINST

AGGREGATE

ALGORITHM

ALL (R)

ALTER (R)

ANALYZE (R)

AND (R)

ANY

AS (R)

ASC (R)

ASCII

ASENSITIVE (R)

AUTO_INCREMENT

AVG

AVG_ROW_LENGTH

BACKUP

BDB

BEFORE (R)

BEGIN

BERKELEYDB

BETWEEN (R)

BIGINT (R)

BINARY (R)

BINLOG

BIT

BLOB (R)

BLOCK

BOOL

BOOLEAN

BOTH (R)

BTREE

BY (R)

BYTE

CACHE

CALL (R)

CASCADE (R)

CASCADED

CASE (R)

CHAIN

CHANGE (R)

CHANGED

CHAR (R)

CHARACTER (R)

CHARSET

CHECK (R)

CHECKSUM

CIPHER

CLIENT

CLOSE

CODE

COLLATE (R)

COLLATION

COLUMN (R)

COLUMNS

COMMENT

COMMIT

COMMITTED

COMPACT

COMPRESSED

CONCURRENT

CONDITION (R)

CONNECTION

CONSISTENT

CONSTRAINT (R)

CONTAINS

CONTEXT

CONTINUE (R)

CONVERT (R)

CPU

CREATE (R)

CROSS (R)

CUBE

CURRENT_DATE (R)

CURRENT_TIME (R)

CURRENT_TIMESTAMP (R)

CURRENT_USER (R)

CURSOR (R)

DATA

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

DATABASE (R)

DATABASES (R)

DATE

DATETIME

DAY

DAY_HOUR (R)

DAY_MICROSECOND (R)

DAY_MINUTE (R)

DAY_SECOND (R)

DEALLOCATE

DEC (R)

DECIMAL (R)

DECLARE (R)

DEFAULT (R)

DEFINER

DELAYED (R)

DELAY_KEY_WRITE

DELETE (R)

DESC (R)

DESCRIBE (R)

DES_KEY_FILE

DETERMINISTIC (R)

DIRECTORY

DISABLE

DISCARD

DISTINCT (R)

DISTINCTROW (R)

DIV (R)

DO

DOUBLE (R)

DROP (R)

DUAL (R)

DUMPFILE

DUPLICATE

DYNAMIC

EACH (R)

ELSE (R)

ELSEIF (R)

ENABLE

ENCLOSED (R)

END

ENGINE

ENGINES

ENUM

ERRORS

ESCAPE

ESCAPED (R)

EVENTS

EXECUTE

EXISTS (R)

EXIT (R)

EXPANSION

EXPLAIN (R)

EXTENDED

FALSE (R)

FAST

FAULTS

FETCH (R)

FIELDS

FILE

FIRST

FIXED

FLOAT (R)

FLOAT4 (R)

FLOAT8 (R)

FLUSH

FOR (R)

FORCE (R)

FOREIGN (R)

FOUND

FRAC_SECOND

FROM (R)

FULL

FULLTEXT (R)

FUNCTION

GEOMETRY

GEOMETRYCOLLECTION

GET_FORMAT

GLOBAL

GRANT (R)

GRANTS

GROUP (R)

HANDLER

HASH

HAVING (R)

HELP

HIGH_PRIORITY (R)

HOSTS

HOUR

HOUR_MICROSECOND (R)

HOUR_MINUTE (R)

HOUR_SECOND (R)

IDENTIFIED

IF (R)

IGNORE (R)

IMPORT

IN (R)

INDEX (R)

INDEXES

INFILE (R)

INNER (R)

INNOBASE

INNODB

INOUT (R)

INSENSITIVE (R)

INSERT (R)

INSERT_METHOD

INT (R)

INT1 (R)

INT2 (R)

INT3 (R)

INT4 (R)

INT8 (R)

INTEGER (R)

INTERVAL (R)

INTO (R)

INVOKER

IO

IO_THREAD

IPC

IS (R)

ISOLATION

ISSUER

ITERATE (R)

JOIN (R)

KEY (R)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

KEYS (R)

KILL (R)

LANGUAGE

LAST

LEADING (R)

LEAVE (R)

LEAVES

LEFT (R)

LEVEL

LIKE (R)

LIMIT (R)

LINES (R)

LINESTRING

LOAD (R)

LOCAL

LOCALTIME (R)

LOCALTIMESTAMP (R)

LOCK (R)

LOCKS

LOGS

LONG (R)

LONGBLOB (R)

LONGTEXT (R)

LOOP (R)

LOW_PRIORITY (R)

MASTER

MASTER_CONNECT_RETRY

MASTER_HOST

MASTER_LOG_FILE

MASTER_LOG_POS

MASTER_PASSWORD

MASTER_PORT

MASTER_SERVER_ID

MASTER_SSL

MASTER_SSL_CA

MASTER_SSL_CAPATH

MASTER_SSL_CERT

MASTER_SSL_CIPHER

MASTER_SSL_KEY

MASTER_USER

MATCH (R)

MAX_CONNECTIONS_PER_HOUR

MAX_QUERIES_PER_HOUR

MAX_ROWS

MAX_UPDATES_PER_HOUR

MAX_USER_CONNECTIONS

MEDIUM

MEDIUMBLOB (R)

MEDIUMINT (R)

MEDIUMTEXT (R)

MEMORY

MERGE

MICROSECOND

MIDDLEINT (R)

MIGRATE

MINUTE

MINUTE_MICROSECOND (R)

MINUTE_SECOND (R)

MIN_ROWS

MOD (R)

MODE

MODIFIES (R)

MODIFY

MONTH

MULTILINESTRING

MULTIPOINT

MULTIPOLYGON

MUTEX

NAME

NAMES

NATIONAL

NATURAL (R)

NCHAR

NDB

NDBCLUSTER

NEW

NEXT

NO

NONE

NOT (R)

NO_WRITE_TO_BINLOG (R)

NULL (R)

NUMERIC (R)

NVARCHAR

OFFSET

OLD_PASSWORD

ON (R)

ONE

ONE_SHOT

OPEN

OPTIMIZE (R)

OPTION (R)

OPTIONALLY (R)

OR (R)

ORDER (R)

OUT (R)

OUTER (R)

OUTFILE (R)

PACK_KEYS

PAGE

PARTIAL

PASSWORD

PHASE

POINT

POLYGON

PRECISION (R)

PREPARE

PREV

PRIMARY (R)

PRIVILEGES

PROCEDURE (R)

PROCESSLIST

PROFILE

PROFILES

PURGE (R)

QUARTER

QUERY

QUICK

RAID0

RAID_CHUNKS

RAID_CHUNKSIZE

RAID_TYPE

READ (R)

READS (R)

REAL (R)

RECOVER

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

REDUNDANT

REFERENCES (R)

REGEXP (R)

RELAY_LOG_FILE

RELAY_LOG_POS

RELAY_THREAD

RELEASE (R)

RELOAD

RENAME (R)

REPAIR

REPEAT (R)

REPEATABLE

REPLACE (R)

REPLICATION

REQUIRE (R)

RESET

RESTORE

RESTRICT (R)

RESUME

RETURN (R)

RETURNS

REVOKE (R)

RIGHT (R)

RLIKE (R)

ROLLBACK

ROLLUP

ROUTINE

ROW

ROWS

ROW_FORMAT

RTREE

SAVEPOINT

SCHEMA (R)

SCHEMAS (R)

SECOND

SECOND_MICROSECOND (R)

SECURITY

SELECT (R)

SENSITIVE (R)

SEPARATOR (R)

SERIAL

SERIALIZABLE

SESSION

SET (R)

SHARE

SHOW (R)

SHUTDOWN

SIGNED

SIMPLE

SLAVE

SMALLINT (R)

SNAPSHOT

SOME

SONAME (R)

SOUNDS

SOURCE

SPATIAL (R)

SPECIFIC (R)

SQL (R)

SQLEXCEPTION (R)

SQLSTATE (R)

SQLWARNING (R)

SQL_BIG_RESULT (R)

SQL_BUFFER_RESULT

SQL_CACHE

SQL_CALC_FOUND_ROWS (R)

SQL_NO_CACHE

SQL_SMALL_RESULT (R)

SQL_THREAD

SQL_TSI_DAY

SQL_TSI_FRAC_SECOND

SQL_TSI_HOUR

SQL_TSI_MINUTE

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_SECOND

SQL_TSI_WEEK

SQL_TSI_YEAR

SSL (R)

START

STARTING (R)

STATUS

STOP

STORAGE

STRAIGHT_JOIN (R)

STRING

STRIPED

SUBJECT

SUPER

SUSPEND

SWAPS

SWITCHES

TABLE (R)

TABLES

TABLESPACE

TEMPORARY

TEMPTABLE

TERMINATED (R)

TEXT

THEN (R)

TIME

TIMESTAMP

TIMESTAMPADD

TIMESTAMPDIFF

TINYBLOB (R)

TINYINT (R)

TINYTEXT (R)

TO (R)

TRAILING (R)

TRANSACTION

TRIGGER (R)

TRIGGERS

TRUE (R)

TRUNCATE

TYPE

TYPES

UNCOMMITTED

UNDEFINED

UNDO (R)

UNICODE

UNION (R)

UNIQUE (R)

UNKNOWN

UNLOCK (R)

UNSIGNED (R)

UNTIL

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Keywords and Reserved Words

UPDATE (R)

UPGRADE

USAGE (R)

USE (R)

USER

USER_RESOURCES

USE_FRM

USING (R)

UTC_DATE (R)

UTC_TIME (R)

UTC_TIMESTAMP (R)

VALUE

VALUES (R)

VARBINARY (R)

VARCHAR (R)

VARCHARACTER (R)

VARIABLES

VARYING (R)

VIEW

WARNINGS

WEEK

WHEN (R)

WHERE (R)

WHILE (R)

WITH (R)

WORK

WRITE (R)

X509

XA

XOR (R)

YEAR

YEAR_MONTH (R)

ZEROFILL (R)

The following table shows the keywords and reserved words that are new in MySQL 5.0. Reserved
keywords are marked with (R).
Table 9.3 New Keywords and Reserved Words in MySQL 5.0 compared to MySQL 4.1
ALGORITHM

ASENSITIVE (R)

BLOCK

CALL (R)

CASCADED

CHAIN

CODE

COMPACT

CONDITION (R)

CONNECTION

CONTAINS

CONTEXT

CONTINUE (R)

CPU

CURSOR (R)

DECLARE (R)

DEFINER

DETERMINISTIC (R)

EACH (R)

ELSEIF (R)

EXIT (R)

FAULTS

FETCH (R)

FOUND

FRAC_SECOND

INOUT (R)

INSENSITIVE (R)

INVOKER

IO

IPC

ITERATE (R)

LANGUAGE

LEAVE (R)

LOOP (R)

MAX_USER_CONNECTIONS

MEMORY

MERGE

MIGRATE

MODIFIES (R)

MUTEX

NAME

ONE

OUT (R)

PAGE

PHASE

PROFILE

PROFILES

QUARTER

READS (R)

RECOVER

REDUNDANT

RELEASE (R)

REPEAT (R)

RESUME

RETURN (R)

ROUTINE

SCHEMA (R)

SCHEMAS (R)

SECURITY

SENSITIVE (R)

SOURCE

SPECIFIC (R)

SQL (R)

SQLEXCEPTION (R)

SQLSTATE (R)

SQLWARNING (R)

SQL_TSI_DAY

SQL_TSI_FRAC_SECOND

SQL_TSI_HOUR

SQL_TSI_MINUTE

SQL_TSI_MONTH

SQL_TSI_QUARTER

SQL_TSI_SECOND

SQL_TSI_WEEK

SQL_TSI_YEAR

SUSPEND

SWAPS

SWITCHES

TEMPTABLE

TIMESTAMPADD

TIMESTAMPDIFF

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

User-Defined Variables

TRIGGER (R)

TRIGGERS

UNDEFINED

UNDO (R)

UNKNOWN

UPGRADE

VIEW

WEEK

WHILE (R)

XA

9.4 User-Defined Variables
You can store a value in a user-defined variable in one statement and then refer to it later in another
statement. This enables you to pass values from one statement to another.
User variables are written as @var_name, where the variable name var_name consists of
alphanumeric characters, “.”, “_”, and “$”. A user variable name can contain other characters if you
quote it as a string or identifier (for example, @'my-var', @"my-var", or @`my-var`).
User-defined variables are session-specific. That is, a user variable defined by one client cannot be
seen or used by other clients. All variables for a given client session are automatically freed when that
client exits.
User variable names are not case sensitive in MySQL 5.0 and up, but are case sensitive before
MySQL 5.0.
One way to set a user-defined variable is by issuing a SET statement:
SET @var_name = expr [, @var_name = expr] ...

For SET, either = or := can be used as the assignment operator.
You can also assign a value to a user variable in statements other than SET. In this case, the
assignment operator must be := and not = because the latter is treated as the comparison operator =
in non-SET statements:
mysql> SET @t1=1, @t2=2, @t3:=4;
mysql> SELECT @t1, @t2, @t3, @t4 := @t1+@t2+@t3;
+------+------+------+--------------------+
| @t1 | @t2 | @t3 | @t4 := @t1+@t2+@t3 |
+------+------+------+--------------------+
|
1 |
2 |
4 |
7 |
+------+------+------+--------------------+

User variables can be assigned a value from a limited set of data types: integer, decimal, floating-point,
binary or nonbinary string, or NULL value. Assignment of decimal and real values does not preserve the
precision or scale of the value. A value of a type other than one of the permissible types is converted to
a permissible type. For example, a value having a temporal or spatial data type is converted to a binary
string.
If a user variable is assigned a nonbinary (character) string value, it has the same character set and
collation as the string. The coercibility of user variables is implicit as of MySQL 5.0.3. (This is the same
coercibility as for table column values.)
Bit values assigned to user variables are treated as binary strings. To assign a bit value as a number to
a user variable, use CAST() or +0:
mysql> SET @v1 = b'1000001';
mysql> SET @v2 = CAST(b'1000001' AS UNSIGNED), @v3 = b'1000001'+0;
mysql> SELECT @v1, @v2, @v3;
+------+------+------+
| @v1 | @v2 | @v3 |
+------+------+------+
| A
|
65 |
65 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

User-Defined Variables

+------+------+------+

If the value of a user variable is selected in a result set, it is returned to the client as a string.
If you refer to a variable that has not been initialized, it has a value of NULL and a type of string.
User variables may be used in most contexts where expressions are permitted. This does not currently
include contexts that explicitly require a literal value, such as in the LIMIT clause of a SELECT
statement, or the IGNORE N LINES clause of a LOAD DATA statement.
As a general rule, other than in SET statements, you should never assign a value to a user variable and
read the value within the same statement. For example, to increment a variable, this is okay:
SET @a = @a + 1;

For other statements, such as SELECT, you might get the results you expect, but this is not
guaranteed. In the following statement, you might think that MySQL will evaluate @a first and then do
an assignment second:
SELECT @a, @a:=@a+1, ...;

However, the order of evaluation for expressions involving user variables is undefined.
Another issue with assigning a value to a variable and reading the value within the same non-SET
statement is that the default result type of a variable is based on its type at the start of the statement.
The following example illustrates this:
mysql> SET @a='test';
mysql> SELECT @a,(@a:=20) FROM tbl_name;

For this SELECT statement, MySQL reports to the client that column one is a string and converts all
accesses of @a to strings, even though @a is set to a number for the second row. After the SELECT
statement executes, @a is regarded as a number for the next statement.
To avoid problems with this behavior, either do not assign a value to and read the value of the same
variable within a single statement, or else set the variable to 0, 0.0, or '' to define its type before you
use it.
In a SELECT statement, each select expression is evaluated only when sent to the client. This means
that in a HAVING, GROUP BY, or ORDER BY clause, referring to a variable that is assigned a value in
the select expression list does not work as expected:
mysql> SELECT (@aa:=id) AS a, (@aa+3) AS b FROM tbl_name HAVING b=5;

The reference to b in the HAVING clause refers to an alias for an expression in the select list that uses
@aa. This does not work as expected: @aa contains the value of id from the previous selected row, not
from the current row.
User variables are intended to provide data values. They cannot be used directly in an SQL statement
as an identifier or as part of an identifier, such as in contexts where a table or database name is
expected, or as a reserved word such as SELECT. This is true even if the variable is quoted, as shown
in the following example:
mysql> SELECT c1 FROM t;
+----+
| c1 |
+----+
| 0 |
+----+
| 1 |

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

User-Defined Variables

+----+
2 rows in set (0.00 sec)
mysql> SET @col = "c1";
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @col FROM t;
+------+
| @col |
+------+
| c1
|
+------+
1 row in set (0.00 sec)
mysql> SELECT `@col` FROM t;
ERROR 1054 (42S22): Unknown column '@col' in 'field list'
mysql> SET @col = "`c1`";
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT @col FROM t;
+------+
| @col |
+------+
| `c1` |
+------+
1 row in set (0.00 sec)

An exception to this principle that user variables cannot be used to provide identifiers is that if you are
constructing a string for use as a prepared statement to be executed later. In this case, user variables
can be used to provide any part of the statement. The following example illustrates how this can be
done:
mysql> SET @c = "c1";
Query OK, 0 rows affected (0.00 sec)
mysql> SET @s = CONCAT("SELECT ", @c, " FROM t");
Query OK, 0 rows affected (0.00 sec)
mysql> PREPARE stmt FROM @s;
Query OK, 0 rows affected (0.04 sec)
Statement prepared
mysql> EXECUTE stmt;
+----+
| c1 |
+----+
| 0 |
+----+
| 1 |
+----+
2 rows in set (0.00 sec)
mysql> DEALLOCATE PREPARE stmt;
Query OK, 0 rows affected (0.00 sec)

See Section 13.5, “SQL Syntax for Prepared Statements”, for more information.
A similar technique can be used in application programs to construct SQL statements using program
variables, as shown here using PHP 5:
query($query);
while($row = $result->fetch_assoc())
{
echo "
" . $row["$col"] . "
\n";
}
$result->close();
$mysqli->close();
?>

Assembling an SQL statement in this fashion is sometimes known as “Dynamic SQL”.

9.5 Expression Syntax
The following rules define expression syntax in MySQL. The grammar shown here is based on that
given in the sql/sql_yacc.yy file of MySQL source distributions. See the notes after the grammar
for additional information about some of the terms.
expr:
expr OR expr
| expr || expr
| expr XOR expr
| expr AND expr
| expr && expr
| NOT expr
| ! expr
| boolean_primary IS [NOT] {TRUE | FALSE | UNKNOWN}
| boolean_primary
boolean_primary:
boolean_primary
| boolean_primary
| boolean_primary
| boolean_primary
| predicate

IS [NOT] NULL
<=> predicate
comparison_operator predicate
comparison_operator {ALL | ANY} (subquery)

comparison_operator: = | >= | > | <= | < | <> | !=
predicate:
bit_expr
| bit_expr
| bit_expr
| bit_expr
| bit_expr
| bit_expr
| bit_expr

[NOT] IN (subquery)
[NOT] IN (expr [, expr] ...)
[NOT] BETWEEN bit_expr AND predicate
SOUNDS LIKE bit_expr
[NOT] LIKE simple_expr [ESCAPE simple_expr]
[NOT] REGEXP bit_expr

bit_expr:
bit_expr | bit_expr
| bit_expr & bit_expr
| bit_expr << bit_expr
| bit_expr >> bit_expr
| bit_expr + bit_expr
| bit_expr - bit_expr
| bit_expr * bit_expr
| bit_expr / bit_expr
| bit_expr DIV bit_expr
| bit_expr MOD bit_expr
| bit_expr % bit_expr
| bit_expr ^ bit_expr
| bit_expr + interval_expr
| bit_expr - interval_expr
| simple_expr
simple_expr:
literal

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Expression Syntax

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

identifier
function_call
simple_expr COLLATE collation_name
param_marker
variable
simple_expr || simple_expr
+ simple_expr
- simple_expr
~ simple_expr
! simple_expr
BINARY simple_expr
(expr [, expr] ...)
ROW (expr, expr [, expr] ...)
(subquery)
EXISTS (subquery)
{identifier expr}
match_expr
case_expr
interval_expr

Notes:
For operator precedence, see in Section 12.3.1, “Operator Precedence”.
For literal value syntax, see Section 9.1, “Literal Values”.
For identifier syntax, see Section 9.2, “Schema Object Names”.
Variables can be user variables, system variables, or stored program local variables or parameters:
• User variables: Section 9.4, “User-Defined Variables”
• System variables: Section 5.1.5, “Using System Variables”
• Local variables: Section 13.6.4.1, “Local Variable DECLARE Syntax”
• Parameters: Section 13.1.9, “CREATE PROCEDURE and CREATE FUNCTION Syntax”
param_marker is ? as used in prepared statements for placeholders. See Section 13.5.1, “PREPARE
Syntax”.
(subquery) indicates a subquery that returns a single value; that is, a scalar subquery. See
Section 13.2.9.1, “The Subquery as Scalar Operand”.
{identifier expr} is ODBC escape syntax and is accepted for ODBC compatibility. The value
is expr. The curly braces in the syntax should be written literally; they are not metasyntax as used
elsewhere in syntax descriptions.
match_expr indicates a MATCH expression. See Section 12.9, “Full-Text Search Functions”.
case_expr indicates a CASE expression. See Section 12.4, “Control Flow Functions”.
interval_expr represents a time interval. The syntax is INTERVAL expr unit, where unit is
a specifier such as HOUR, DAY, or WEEK. For the full list of unit specifiers, see the description of the
DATE_ADD() function in Section 12.7, “Date and Time Functions”.
The meaning of some operators depends on the SQL mode:
• By default, || is a logical OR operator. With PIPES_AS_CONCAT enabled, || is string concatenation,
with a precedence between ^ and the unary operators.
• By default, ! has a higher precedence than NOT as of MySQL 5.0.2. For earlier versions, or from
5.0.2 on with HIGH_NOT_PRECEDENCE enabled, ! and NOT have the same precedence.
See Section 5.1.7, “Server SQL Modes”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Comment Syntax

9.6 Comment Syntax
MySQL Server supports three comment styles:
• From a “#” character to the end of the line.
• From a “-- ” sequence to the end of the line. In MySQL, the “-- ” (double-dash) comment style
requires the second dash to be followed by at least one whitespace or control character (such as a
space, tab, newline, and so on). This syntax differs slightly from standard SQL comment syntax, as
discussed in Section 1.8.2.5, “'--' as the Start of a Comment”.
• From a /* sequence to the following */ sequence, as in the C programming language. This syntax
enables a comment to extend over multiple lines because the beginning and closing sequences need
not be on the same line.
The following example demonstrates all three comment styles:
mysql> SELECT
mysql> SELECT
mysql> SELECT
mysql> SELECT
/*
this is a
multiple-line
*/
1;

1+1;
# This comment continues to the end of line
1+1;
-- This comment continues to the end of line
1 /* this is an in-line comment */ + 1;
1+

comment

Nested comments are not supported.
MySQL Server supports some variants of C-style comments. These enable you to write code that
includes MySQL extensions, but is still portable, by using comments of the following form:
/*! MySQL-specific code */

In this case, MySQL Server parses and executes the code within the comment as it would any other
SQL statement, but other SQL servers will ignore the extensions. For example, MySQL Server
recognizes the STRAIGHT_JOIN keyword in the following statement, but other servers will not:
SELECT /*! STRAIGHT_JOIN */ col1 FROM table1,table2 WHERE ...

If you add a version number after the “!” character, the syntax within the comment is executed only if
the MySQL version is greater than or equal to the specified version number. The TEMPORARY keyword
in the following comment is executed only by servers from MySQL 3.23.02 or higher:
CREATE /*!32302 TEMPORARY */ TABLE t (a INT);

The comment syntax just described applies to how the mysqld server parses SQL statements. The
mysql client program also performs some parsing of statements before sending them to the server. (It
does this to determine statement boundaries within a multiple-statement input line.)
Comments in this format, /*!12345 ... */, are not stored on the server. If this format is used to
comment stored routines, the comments will not be retained on the server.
The use of short-form mysql commands such as \C within multiple-line /* ... */ comments is not
supported.

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Chapter 10 Globalization
Table of Contents
10.1 Character Set Support .......................................................................................................
10.1.1 Character Sets and Collations in General ................................................................
10.1.2 Character Sets and Collations in MySQL .................................................................
10.1.3 Specifying Character Sets and Collations ................................................................
10.1.4 Connection Character Sets and Collations ...............................................................
10.1.5 Configuring the Character Set and Collation for Applications .....................................
10.1.6 Character Set for Error Messages ...........................................................................
10.1.7 Collation Issues ......................................................................................................
10.1.8 String Repertoire ....................................................................................................
10.1.9 Operations Affected by Character Set Support .........................................................
10.1.10 Unicode Support ...................................................................................................
10.1.11 UTF-8 for Metadata ..............................................................................................
10.1.12 Column Character Set Conversion .........................................................................
10.1.13 Character Sets and Collations That MySQL Supports .............................................
10.2 Setting the Error Message Language .................................................................................
10.3 Adding a Character Set .....................................................................................................
10.3.1 Character Definition Arrays .....................................................................................
10.3.2 String Collating Support for Complex Character Sets ................................................
10.3.3 Multi-Byte Character Support for Complex Character Sets ........................................
10.4 Adding a Collation to a Character Set ................................................................................
10.4.1 Collation Implementation Types ...............................................................................
10.4.2 Choosing a Collation ID ..........................................................................................
10.4.3 Adding a Simple Collation to an 8-Bit Character Set .................................................
10.4.4 Adding a UCA Collation to a Unicode Character Set .................................................
10.5 Character Set Configuration ...............................................................................................
10.6 MySQL Server Time Zone Support ....................................................................................
10.6.1 Staying Current with Time Zone Changes ................................................................
10.6.2 Time Zone Leap Second Support ............................................................................
10.7 MySQL Server Locale Support ...........................................................................................

805
806
807
808
815
817
819
819
826
828
831
832
833
834
845
845
847
848
848
849
850
851
852
853
856
857
859
861
862

This chapter covers issues of globalization, which includes internationalization (MySQL's capabilities
for adapting to local use) and localization (selecting particular local conventions):
• MySQL support for character sets in SQL statements.
• How to configure the server to support different character sets.
• Selecting the language for error messages.
• How to set the server's time zone and enable per-connection time zone support.
• Selecting the locale for day and month names.

10.1 Character Set Support
MySQL includes character set support that enables you to store data using a variety of character sets
and perform comparisons according to a variety of collations. You can specify character sets at the
server, database, table, and column level. MySQL supports the use of character sets for the MyISAM,
MEMORY, NDBCLUSTER, and InnoDB storage engines.
This chapter discusses the following topics:
• What are character sets and collations?
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations in General

• The multiple-level default system for character set assignment
• Syntax for specifying character sets and collations
• Affected functions and operations
• Unicode support
• The character sets and collations that are available, with notes
Character set issues affect not only data storage, but also communication between client programs and
the MySQL server. If you want the client program to communicate with the server using a character
set different from the default, you'll need to indicate which one. For example, to use the utf8 Unicode
character set, issue this statement after connecting to the server:
SET NAMES 'utf8';

For more information about configuring character sets for application use and character set-related
issues in client/server communication, see Section 10.1.5, “Configuring the Character Set and Collation
for Applications”, and Section 10.1.4, “Connection Character Sets and Collations”.

10.1.1 Character Sets and Collations in General
A character set is a set of symbols and encodings. A collation is a set of rules for comparing characters
in a character set. Let's make the distinction clear with an example of an imaginary character set.
Suppose that we have an alphabet with four letters: “A”, “B”, “a”, “b”. We give each letter a number: “A”
= 0, “B” = 1, “a” = 2, “b” = 3. The letter “A” is a symbol, the number 0 is the encoding for “A”, and the
combination of all four letters and their encodings is a character set.
Suppose that we want to compare two string values, “A” and “B”. The simplest way to do this is to look
at the encodings: 0 for “A” and 1 for “B”. Because 0 is less than 1, we say “A” is less than “B”. What
we've just done is apply a collation to our character set. The collation is a set of rules (only one rule in
this case): “compare the encodings.” We call this simplest of all possible collations a binary collation.
But what if we want to say that the lowercase and uppercase letters are equivalent? Then we would
have at least two rules: (1) treat the lowercase letters “a” and “b” as equivalent to “A” and “B”; (2) then
compare the encodings. We call this a case-insensitive collation. It is a little more complex than a
binary collation.
In real life, most character sets have many characters: not just “A” and “B” but whole alphabets,
sometimes multiple alphabets or eastern writing systems with thousands of characters, along with
many special symbols and punctuation marks. Also in real life, most collations have many rules, not
just for whether to distinguish lettercase, but also for whether to distinguish accents (an “accent” is a
mark attached to a character as in German “Ö”), and for multiple-character mappings (such as the rule
that “Ö” = “OE” in one of the two German collations).
MySQL can do these things for you:
• Store strings using a variety of character sets
• Compare strings using a variety of collations
• Mix strings with different character sets or collations in the same server, the same database, or even
the same table
• Enable specification of character set and collation at any level
In these respects, MySQL is far ahead of most other database management systems. However, to use
these features effectively, you need to know what character sets and collations are available, how to
change the defaults, and how they affect the behavior of string operators and functions.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations in MySQL

10.1.2 Character Sets and Collations in MySQL
The MySQL server can support multiple character sets. To list the available character sets, use the
SHOW CHARACTER SET statement. A partial listing follows. For more complete information, see
Section 10.1.13, “Character Sets and Collations That MySQL Supports”.
mysql> SHOW CHARACTER SET;
+----------+-----------------------------+---------------------+--------+
| Charset | Description
| Default collation
| Maxlen |
+----------+-----------------------------+---------------------+--------+
| big5
| Big5 Traditional Chinese
| big5_chinese_ci
|
2 |
| dec8
| DEC West European
| dec8_swedish_ci
|
1 |
| cp850
| DOS West European
| cp850_general_ci
|
1 |
| hp8
| HP West European
| hp8_english_ci
|
1 |
| koi8r
| KOI8-R Relcom Russian
| koi8r_general_ci
|
1 |
| latin1
| cp1252 West European
| latin1_swedish_ci
|
1 |
| latin2
| ISO 8859-2 Central European | latin2_general_ci
|
1 |
| swe7
| 7bit Swedish
| swe7_swedish_ci
|
1 |
| ascii
| US ASCII
| ascii_general_ci
|
1 |
| ujis
| EUC-JP Japanese
| ujis_japanese_ci
|
3 |
| sjis
| Shift-JIS Japanese
| sjis_japanese_ci
|
2 |
| hebrew
| ISO 8859-8 Hebrew
| hebrew_general_ci
|
1 |
| tis620
| TIS620 Thai
| tis620_thai_ci
|
1 |
| euckr
| EUC-KR Korean
| euckr_korean_ci
|
2 |
| koi8u
| KOI8-U Ukrainian
| koi8u_general_ci
|
1 |
| gb2312
| GB2312 Simplified Chinese
| gb2312_chinese_ci
|
2 |
| greek
| ISO 8859-7 Greek
| greek_general_ci
|
1 |
| cp1250
| Windows Central European
| cp1250_general_ci
|
1 |
| gbk
| GBK Simplified Chinese
| gbk_chinese_ci
|
2 |
| latin5
| ISO 8859-9 Turkish
| latin5_turkish_ci
|
1 |
...

Any given character set always has at least one collation. It may have several collations. To list the
collations for a character set, use the SHOW COLLATION statement. For example, to see the collations
for the latin1 (cp1252 West European) character set, use this statement to find those collation
names that begin with latin1:
mysql> SHOW COLLATION LIKE 'latin1%';
+---------------------+---------+----+---------+----------+---------+
| Collation
| Charset | Id | Default | Compiled | Sortlen |
+---------------------+---------+----+---------+----------+---------+
| latin1_german1_ci
| latin1 | 5 |
|
|
0 |
| latin1_swedish_ci
| latin1 | 8 | Yes
| Yes
|
1 |
| latin1_danish_ci
| latin1 | 15 |
|
|
0 |
| latin1_german2_ci
| latin1 | 31 |
| Yes
|
2 |
| latin1_bin
| latin1 | 47 |
| Yes
|
1 |
| latin1_general_ci
| latin1 | 48 |
|
|
0 |
| latin1_general_cs
| latin1 | 49 |
|
|
0 |
| latin1_spanish_ci
| latin1 | 94 |
|
|
0 |
+---------------------+---------+----+---------+----------+---------+

The latin1 collations have the following meanings.
Collation

Meaning

latin1_german1_ci

German DIN-1

latin1_swedish_ci

Swedish/Finnish

latin1_danish_ci

Danish/Norwegian

latin1_german2_ci

German DIN-2

latin1_bin

Binary according to latin1 encoding

latin1_general_ci

Multilingual (Western European)

latin1_general_cs

Multilingual (ISO Western European), case sensitive

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

Collation

Meaning

latin1_spanish_ci

Modern Spanish

Collations have these general characteristics:
• Two different character sets cannot have the same collation.
• Each character set has one collation that is the default collation. For example, the default collation for
latin1 is latin1_swedish_ci. The output for SHOW CHARACTER SET indicates which collation
is the default for each displayed character set.
• There is a convention for collation names: They start with the name of the character set with which
they are associated, they usually include a language name, and they end with _ci (case insensitive),
_cs (case sensitive), or _bin (binary).
In cases where a character set has multiple collations, it might not be clear which collation is most
suitable for a given application. To avoid choosing the wrong collation, it can be helpful to perform
some comparisons with representative data values to make sure that a given collation sorts values the
way you expect.
Collation-Charts.Org is a useful site for information that shows how one collation compares to another.

10.1.3 Specifying Character Sets and Collations
There are default settings for character sets and collations at four levels: server, database, table,
and column. The description in the following sections may appear complex, but it has been found in
practice that multiple-level defaulting leads to natural and obvious results.
CHARACTER SET is used in clauses that specify a character set. CHARSET can be used as a synonym
for CHARACTER SET.
Character set issues affect not only data storage, but also communication between client programs and
the MySQL server. If you want the client program to communicate with the server using a character
set different from the default, you'll need to indicate which one. For example, to use the utf8 Unicode
character set, issue this statement after connecting to the server:
SET NAMES 'utf8';

For more information about character set-related issues in client/server communication, see
Section 10.1.4, “Connection Character Sets and Collations”.

10.1.3.1 Server Character Set and Collation
MySQL Server has a server character set and a server collation. These can be set at server startup on
the command line or in an option file and changed at runtime.
Initially, the server character set and collation depend on the options that you use when you start
mysqld. You can use --character-set-server for the character set. Along with it, you can add
--collation-server for the collation. If you don't specify a character set, that is the same as saying
--character-set-server=latin1. If you specify only a character set (for example, latin1) but
not a collation, that is the same as saying --character-set-server=latin1 --collationserver=latin1_swedish_ci because latin1_swedish_ci is the default collation for latin1.
Therefore, the following three commands all have the same effect:
shell> mysqld
shell> mysqld --character-set-server=latin1
shell> mysqld --character-set-server=latin1 \
--collation-server=latin1_swedish_ci

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

One way to change the settings is by recompiling. If you want to change the default server character
set and collation when building from sources, use: --with-charset and --with-collation as
arguments for configure. For example:
shell> ./configure --with-charset=latin1

Or:
shell> ./configure --with-charset=latin1 \
--with-collation=latin1_german1_ci

Both mysqld and configure verify that the character set/collation combination is valid. If not, each
program displays an error message and terminates.
The server character set and collation are used as default values if the database character set and
collation are not specified in CREATE DATABASE statements. They have no other purpose.
The current server character set and collation can be determined from the values of the
character_set_server and collation_server system variables. These variables can be
changed at runtime.

10.1.3.2 Database Character Set and Collation
Every database has a database character set and a database collation. The CREATE DATABASE and
ALTER DATABASE statements have optional clauses for specifying the database character set and
collation:
CREATE DATABASE db_name
[[DEFAULT] CHARACTER SET charset_name]
[[DEFAULT] COLLATE collation_name]
ALTER DATABASE db_name
[[DEFAULT] CHARACTER SET charset_name]
[[DEFAULT] COLLATE collation_name]

The keyword SCHEMA can be used instead of DATABASE.
All database options are stored in a text file named db.opt that can be found in the database
directory.
The CHARACTER SET and COLLATE clauses make it possible to create databases with different
character sets and collations on the same MySQL server.
Example:
CREATE DATABASE db_name CHARACTER SET latin1 COLLATE latin1_swedish_ci;

MySQL chooses the database character set and database collation in the following manner:
• If both CHARACTER SET X and COLLATE Y are specified, character set X and collation Y are used.
• If CHARACTER SET X is specified without COLLATE, character set X and its default collation are
used. To see the default collation for each character set, use the SHOW COLLATION statement.
• If COLLATE Y is specified without CHARACTER SET, the character set associated with Y and
collation Y are used.
• Otherwise, the server character set and server collation are used.
The character set and collation for the default database can be determined from the values of the
character_set_database and collation_database system variables. The server sets these
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

variables whenever the default database changes. If there is no default database, the variables have
the same value as the corresponding server-level system variables, character_set_server and
collation_server.
To see the default character set and collation for a given database, use these statements:
USE db_name;
SELECT @@character_set_database, @@collation_database;

Alternatively, to display the values without changing the default database:
SELECT DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME
FROM INFORMATION_SCHEMA.SCHEMATA WHERE SCHEMA_NAME = 'db_name';

The database character set and collation affect these aspects of server operation:
• For CREATE TABLE statements, the database character set and collation are used as default values
for table definitions if the table character set and collation are not specified. To override this, provide
explicit CHARACTER SET and COLLATE table options.
• For LOAD DATA statements that include no CHARACTER SET clause, the server uses the character
set indicated by the character_set_database system variable to interpret the information in the
file. To override this, provide an explicit CHARACTER SET clause.
• For stored routines (procedures and functions), the database character set and collation in effect at
routine creation time are used as the character set and collation of character data parameters for
which the declaration includes no CHARACTER SET attribute. To override this, provide an explicit
CHARACTER SET attribute.

10.1.3.3 Table Character Set and Collation
Every table has a table character set and a table collation. The CREATE TABLE and ALTER TABLE
statements have optional clauses for specifying the table character set and collation:
CREATE TABLE tbl_name (column_list)
[[DEFAULT] CHARACTER SET charset_name]
[COLLATE collation_name]]
ALTER TABLE tbl_name
[[DEFAULT] CHARACTER SET charset_name]
[COLLATE collation_name]

Example:
CREATE TABLE t1 ( ... )
CHARACTER SET latin1 COLLATE latin1_danish_ci;

MySQL chooses the table character set and collation in the following manner:
• If both CHARACTER SET X and COLLATE Y are specified, character set X and collation Y are used.
• If CHARACTER SET X is specified without COLLATE, character set X and its default collation are
used. To see the default collation for each character set, use the SHOW COLLATION statement.
• If COLLATE Y is specified without CHARACTER SET, the character set associated with Y and
collation Y are used.
• Otherwise, the database character set and collation are used.
The table character set and collation are used as default values for column definitions if the column
character set and collation are not specified in individual column definitions. The table character set
and collation are MySQL extensions; there are no such things in standard SQL.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

10.1.3.4 Column Character Set and Collation
Every “character” column (that is, a column of type CHAR, VARCHAR, or TEXT) has a column character
set and a column collation. Column definition syntax for CREATE TABLE and ALTER TABLE has
optional clauses for specifying the column character set and collation:
col_name {CHAR | VARCHAR | TEXT} (col_length)
[CHARACTER SET charset_name]
[COLLATE collation_name]

These clauses can also be used for ENUM and SET columns:
col_name {ENUM | SET} (val_list)
[CHARACTER SET charset_name]
[COLLATE collation_name]

Examples:
CREATE TABLE t1
(
col1 VARCHAR(5)
CHARACTER SET latin1
COLLATE latin1_german1_ci
);
ALTER TABLE t1 MODIFY
col1 VARCHAR(5)
CHARACTER SET latin1
COLLATE latin1_swedish_ci;

MySQL chooses the column character set and collation in the following manner:
• If both CHARACTER SET X and COLLATE Y are specified, character set X and collation Y are used.
CREATE TABLE t1
(
col1 CHAR(10) CHARACTER SET utf8 COLLATE utf8_unicode_ci
) CHARACTER SET latin1 COLLATE latin1_bin;

The character set and collation are specified for the column, so they are used. The column has
character set utf8 and collation utf8_unicode_ci.
• If CHARACTER SET X is specified without COLLATE, character set X and its default collation are
used.
CREATE TABLE t1
(
col1 CHAR(10) CHARACTER SET utf8
) CHARACTER SET latin1 COLLATE latin1_bin;

The character set is specified for the column, but the collation is not. The column has character set
utf8 and the default collation for utf8, which is utf8_general_ci. To see the default collation for
each character set, use the SHOW COLLATION statement.
• If COLLATE Y is specified without CHARACTER SET, the character set associated with Y and
collation Y are used.
CREATE TABLE t1
(
col1 CHAR(10) COLLATE utf8_polish_ci
) CHARACTER SET latin1 COLLATE latin1_bin;

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

The collation is specified for the column, but the character set is not. The column has collation
utf8_polish_ci and the character set is the one associated with the collation, which is utf8.
• Otherwise, the table character set and collation are used.
CREATE TABLE t1
(
col1 CHAR(10)
) CHARACTER SET latin1 COLLATE latin1_bin;

Neither the character set nor collation are specified for the column, so the table defaults are used.
The column has character set latin1 and collation latin1_bin.
The CHARACTER SET and COLLATE clauses are standard SQL.
If you use ALTER TABLE to convert a column from one character set to another, MySQL attempts to
map the data values, but if the character sets are incompatible, there may be data loss.

10.1.3.5 Character String Literal Character Set and Collation
Every character string literal has a character set and a collation.
A character string literal may have an optional character set introducer and COLLATE clause:
[_charset_name]'string' [COLLATE collation_name]

Examples:
SELECT 'string';
SELECT _latin1'string';
SELECT _latin1'string' COLLATE latin1_danish_ci;

For the simple statement SELECT 'string', the string has the character set and collation defined by
the character_set_connection and collation_connection system variables.
The _charset_name expression is formally called an introducer. It tells the parser, “the string that is
about to follow uses character set X.” Because this has confused people in the past, we emphasize
that an introducer does not change the string to the introducer character set like CONVERT() would do.
It does not change the string's value, although padding may occur. The introducer is just a signal. An
introducer is also legal before standard hex literal and numeric hex literal notation (x'literal' and
0xnnnn), or before bit-field literal notation (b'literal' and 0bnnnn).
Examples:
SELECT
SELECT
SELECT
SELECT

_latin1
_latin1
_latin1
_latin1

x'AABBCC';
0xAABBCC;
b'1100011';
0b1100011;

MySQL determines a literal's character set and collation in the following manner:
• If both _X and COLLATE Y are specified, character set X and collation Y are used.
• If _X is specified but COLLATE is not specified, character set X and its default collation are used. To
see the default collation for each character set, use the SHOW COLLATION statement.
• Otherwise, the character set and collation given by the character_set_connection and
collation_connection system variables are used.
Examples:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

• A string with latin1 character set and latin1_german1_ci collation:
SELECT _latin1'Müller' COLLATE latin1_german1_ci;

• A string with latin1 character set and its default collation (that is, latin1_swedish_ci):
SELECT _latin1'Müller';

• A string with the connection default character set and collation:
SELECT 'Müller';

Character set introducers and the COLLATE clause are implemented according to standard SQL
specifications.
An introducer indicates the character set for the following string, but does not change now how the
parser performs escape processing within the string. Escapes are always interpreted by the parser
according to the character set given by character_set_connection.
The following examples show that escape processing occurs using character_set_connection
even in the presence of an introducer. The examples use SET NAMES (which changes
character_set_connection, as discussed in Section 10.1.4, “Connection Character Sets and
Collations”), and display the resulting strings using the HEX() function so that the exact string contents
can be seen.
Example 1:
mysql> SET NAMES latin1;
Query OK, 0 rows affected (0.01 sec)
mysql> SELECT HEX('à\n'), HEX(_sjis'à\n');
+------------+-----------------+
| HEX('à\n') | HEX(_sjis'à\n') |
+------------+-----------------+
| E00A
| E00A
|
+------------+-----------------+
1 row in set (0.00 sec)

Here, “à” (hex value E0) is followed by “\n”, the escape sequence for newline. The escape sequence
is interpreted using the character_set_connection value of latin1 to produce a literal newline
(hex value 0A). This happens even for the second string. That is, the introducer of _sjis does not
affect the parser's escape processing.
Example 2:
mysql> SET NAMES sjis;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT HEX('à\n'), HEX(_latin1'à\n');
+------------+-------------------+
| HEX('à\n') | HEX(_latin1'à\n') |
+------------+-------------------+
| E05C6E
| E05C6E
|
+------------+-------------------+
1 row in set (0.04 sec)

Here, character_set_connection is sjis, a character set in which the sequence of “à” followed
by “\” (hex values 05 and 5C) is a valid multibyte character. Hence, the first two bytes of the string
are interpreted as a single sjis character, and the “\” is not interpreted as an escape character. The
following “n” (hex value 6E) is not interpreted as part of an escape sequence. This is true even for the
second string; the introducer of _latin1 does not affect escape processing.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Specifying Character Sets and Collations

10.1.3.6 National Character Set
Standard SQL defines NCHAR or NATIONAL CHAR as a way to indicate that a CHAR column should
use some predefined character set. MySQL uses utf8 as this predefined character set. For example,
these data type declarations are equivalent:
CHAR(10) CHARACTER SET utf8
NATIONAL CHARACTER(10)
NCHAR(10)

As are these:
VARCHAR(10) CHARACTER SET utf8
NATIONAL VARCHAR(10)
NVARCHAR(10)
NCHAR VARCHAR(10)
NATIONAL CHARACTER VARYING(10)
NATIONAL CHAR VARYING(10)

You can use N'literal' (or n'literal') to create a string in the national character set. These
statements are equivalent:
SELECT N'some text';
SELECT n'some text';
SELECT _utf8'some text';

For information on upgrading character sets to MySQL 5.0 from versions prior to 4.1, see the MySQL
3.23, 4.0, 4.1 Reference Manual.

10.1.3.7 Examples of Character Set and Collation Assignment
The following examples show how MySQL determines default character set and collation values.
Example 1: Table and Column Definition
CREATE TABLE t1
(
c1 CHAR(10) CHARACTER SET latin1 COLLATE latin1_german1_ci
) DEFAULT CHARACTER SET latin2 COLLATE latin2_bin;

Here we have a column with a latin1 character set and a latin1_german1_ci collation. The
definition is explicit, so that is straightforward. Notice that there is no problem with storing a latin1
column in a latin2 table.
Example 2: Table and Column Definition
CREATE TABLE t1
(
c1 CHAR(10) CHARACTER SET latin1
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;

This time we have a column with a latin1 character set and a default collation. Although it
might seem natural, the default collation is not taken from the table level. Instead, because the
default collation for latin1 is always latin1_swedish_ci, column c1 has a collation of
latin1_swedish_ci (not latin1_danish_ci).
Example 3: Table and Column Definition
CREATE TABLE t1
(

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connection Character Sets and Collations

c1 CHAR(10)
) DEFAULT CHARACTER SET latin1 COLLATE latin1_danish_ci;

We have a column with a default character set and a default collation. In this circumstance, MySQL
checks the table level to determine the column character set and collation. Consequently, the character
set for column c1 is latin1 and its collation is latin1_danish_ci.
Example 4: Database, Table, and Column Definition
CREATE DATABASE d1
DEFAULT CHARACTER SET latin2 COLLATE latin2_czech_ci;
USE d1;
CREATE TABLE t1
(
c1 CHAR(10)
);

We create a column without specifying its character set and collation. We're also not specifying a
character set and a collation at the table level. In this circumstance, MySQL checks the database
level to determine the table settings, which thereafter become the column settings.) Consequently, the
character set for column c1 is latin2 and its collation is latin2_czech_ci.

10.1.3.8 Compatibility with Other DBMSs
For MaxDB compatibility these two statements are the same:
CREATE TABLE t1 (f1 CHAR(N) UNICODE);
CREATE TABLE t1 (f1 CHAR(N) CHARACTER SET ucs2);

10.1.4 Connection Character Sets and Collations
Several character set and collation system variables relate to a client's interaction with the server.
Some of these have been mentioned in earlier sections:
• The server character set and collation are the values of the character_set_server and
collation_server system variables.
• The character set and collation of the default database are the values of the
character_set_database and collation_database system variables.
Additional character set and collation system variables are involved in handling traffic for the
connection between a client and the server. Every client has connection-related character set and
collation system variables.
A “connection” is what you make when you connect to the server. The client sends SQL statements,
such as queries, over the connection to the server. The server sends responses, such as result sets or
error messages, over the connection back to the client. This leads to several questions about character
set and collation handling for client connections, each of which can be answered in terms of system
variables:
• What character set is the statement in when it leaves the client?
The server takes the character_set_client system variable to be the character set in which
statements are sent by the client.
• What character set should the server translate a statement to after receiving it?
For this, the server uses the character_set_connection and collation_connection
system variables. It converts statements sent by the client from character_set_client
to character_set_connection (except for string literals that have an introducer such as
_latin1 or _utf8). collation_connection is important for comparisons of literal strings. For
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Connection Character Sets and Collations

comparisons of strings with column values, collation_connection does not matter because
columns have their own collation, which has a higher collation precedence.
• What character set should the server translate to before shipping result sets back to the client?
The character_set_results system variable indicates the character set in which the server
returns query results to the client. This includes result data such as column values, and result
metadata such as column names.
Clients can fine-tune the settings for these variables, or depend on the defaults (in which case, you can
skip the rest of this section). If you do not use the defaults, you must change the character settings for
each connection to the server.
Two statements affect the connection-related character set variables as a group:
• SET NAMES 'charset_name' [COLLATE 'collation_name']
SET NAMES indicates what character set the client will use to send SQL statements to the server.
Thus, SET NAMES 'cp1251' tells the server, “future incoming messages from this client are in
character set cp1251.” It also specifies the character set that the server should use for sending
results back to the client. (For example, it indicates what character set to use for column values if you
use a SELECT statement.)
A SET NAMES 'charset_name' statement is equivalent to these three statements:
SET character_set_client = charset_name;
SET character_set_results = charset_name;
SET character_set_connection = charset_name;

Setting character_set_connection to charset_name also implicitly sets
collation_connection to the default collation for charset_name. It is unnecessary to set that
collation explicitly. To specify a particular collation, use the optional COLLATE clause:
SET NAMES 'charset_name' COLLATE 'collation_name'

• SET CHARACTER SET charset_name
SET CHARACTER SET is similar to SET NAMES but sets character_set_connection and
collation_connection to character_set_database and collation_database. A SET
CHARACTER SET charset_name statement is equivalent to these three statements:
SET character_set_client = charset_name;
SET character_set_results = charset_name;
SET collation_connection = @@collation_database;

Setting collation_connection also implicitly sets character_set_connection
to the character set associated with the collation (equivalent to executing SET
character_set_connection = @@character_set_database). It is unnecessary to set
character_set_connection explicitly.
Note
ucs2 cannot be used as a client character set, which means that it does not
work for SET NAMES or SET CHARACTER SET.
The MySQL client programs mysql, mysqladmin, mysqlcheck, mysqlimport, and mysqlshow
determine the default character set to use as follows:
• In the absence of other information, the programs use the compiled-in default character set, usually
latin1.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Configuring the Character Set and Collation for Applications

• The programs support a --default-character-set option, which enables users to specify the
character set explicitly to override whatever default the client otherwise determines.
When a client connects to the server, it sends the name of the character set that it wants to use.
The server uses the name to set the character_set_client, character_set_results, and
character_set_connection system variables. In effect, the server performs a SET NAMES
operation using the character set name.
With the mysql client, to use a character set different from the default, you could explicitly execute
SET NAMES every time you start up. To accomplish the same result more easily, add the --defaultcharacter-set option setting to your mysql command line or in your option file. For example, the
following option file setting changes the three connection-related character set variables set to koi8r
each time you invoke mysql:
[mysql]
default-character-set=koi8r

If you are using the mysql client with auto-reconnect enabled (which is not recommended), it is
preferable to use the charset command rather than SET NAMES. For example:
mysql> charset utf8
Charset changed

The charset command issues a SET NAMES statement, and also changes the default character set
that mysql uses when it reconnects after the connection has dropped.
Example: Suppose that column1 is defined as CHAR(5) CHARACTER SET latin2. If you do not say
SET NAMES or SET CHARACTER SET, then for SELECT column1 FROM t, the server sends back
all the values for column1 using the character set that the client specified when it connected. On the
other hand, if you say SET NAMES 'latin1' or SET CHARACTER SET latin1 before issuing the
SELECT statement, the server converts the latin2 values to latin1 just before sending results back.
Conversion may be lossy if there are characters that are not in both character sets.
If you want the server to perform no conversion of result sets or error messages, set
character_set_results to NULL or binary:
SET character_set_results = NULL;

To see the values of the character set and collation system variables that apply to your connection, use
these statements:
SHOW VARIABLES LIKE 'character_set%';
SHOW VARIABLES LIKE 'collation%';

You must also consider the environment within which your MySQL applications execute. See
Section 10.1.5, “Configuring the Character Set and Collation for Applications”.
For more information about character sets and error messages, see Section 10.1.6, “Character Set for
Error Messages”.

10.1.5 Configuring the Character Set and Collation for Applications
For applications that store data using the default MySQL character set and collation (latin1,
latin1_swedish_ci), no special configuration should be needed. If applications require data storage
using a different character set or collation, you can configure character set information several ways:
• Specify character settings per database. For example, applications that use one database might
require utf8, whereas applications that use another database might require sjis.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Configuring the Character Set and Collation for Applications

• Specify character settings at server startup. This causes the server to use the given settings for all
applications that do not make other arrangements.
• Specify character settings at configuration time, if you build MySQL from source. This causes the
server to use the given settings for all applications, without having to specify them at server startup.
When different applications require different character settings, the per-database technique provides
a good deal of flexibility. If most or all applications use the same character set, specifying character
settings at server startup or configuration time may be most convenient.
For the per-database or server-startup techniques, the settings control the character set for
data storage. Applications must also tell the server which character set to use for client/server
communications, as described in the following instructions.
The examples shown here assume use of the utf8 character set and utf8_general_ci collation.
Specify character settings per database. To create a database such that its tables will use a given
default character set and collation for data storage, use a CREATE DATABASE statement like this:
CREATE DATABASE mydb
DEFAULT CHARACTER SET utf8
DEFAULT COLLATE utf8_general_ci;

Tables created in the database will use utf8 and utf8_general_ci by default for any character
columns.
Applications that use the database should also configure their connection to the server each time
they connect. This can be done by executing a SET NAMES 'utf8' statement after connecting. The
statement can be used regardless of connection method: The mysql client, PHP scripts, and so forth.
In some cases, it may be possible to configure the connection to use the desired character set some
other way. For example, for connections made using mysql, you can specify the --defaultcharacter-set=utf8 command-line option to achieve the same effect as SET NAMES 'utf8'.
For more information about configuring client connections, see Section 10.1.4, “Connection Character
Sets and Collations”.
If you change the default character set or collation for a database, stored routines that use the
database defaults must be dropped and recreated so that they use the new defaults. (In a stored
routine, variables with character data types use the database defaults if the character set or collation
are not specified explicitly. See Section 13.1.9, “CREATE PROCEDURE and CREATE FUNCTION
Syntax”.)
Specify character settings at server startup. To select a character set and collation at server
startup, use the --character-set-server and --collation-server options. For example, to
specify the options in an option file, include these lines:
[mysqld]
character-set-server=utf8
collation-server=utf8_general_ci

These settings apply server-wide and apply as the defaults for databases created by any application,
and for tables created in those databases.
It is still necessary for applications to configure their connection using SET NAMES or equivalent
after they connect, as described previously. You might be tempted to start the server with the -init_connect="SET NAMES 'utf8'" option to cause SET NAMES to be executed automatically
for each client that connects. However, this will yield inconsistent results because the init_connect
value is not executed for users who have the SUPER privilege.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Set for Error Messages

Specify character settings at MySQL configuration time. To select a character set and collation
when you configure and build MySQL from source, use the --with-charset and --withcollation options:
shell> ./configure --with-charset=utf8 --with-collation=utf8_general_ci

The resulting server uses utf8 and utf8_general_ci as the default for databases and tables and
for client connections. It is unnecessary to use --character-set-server and --collationserver to specify those defaults at server startup. It is also unnecessary for applications to configure
their connection using SET NAMES or equivalent after they connect to the server.
Regardless of how you configure the MySQL character set for application use, you must also consider
the environment within which those applications execute. If you will send statements using UTF-8 text
taken from a file that you create in an editor, you should edit the file with the locale of your environment
set to UTF-8 so that the file encoding is correct and so that the operating system handles it correctly.
If you use the mysql client from within a terminal window, the window must be configured to use
UTF-8 or characters may not display properly. For a script that executes in a Web environment, the
script must handle character encoding properly for its interaction with the MySQL server, and it must
generate pages that correctly indicate the encoding so that browsers know how to display the content
of the pages. For example, you can include this  tag within your  element:


10.1.6 Character Set for Error Messages
This section describes how the server uses character sets for constructing error messages and
returning them to clients. For information about the language of error messages (rather than the
character set), see Section 10.2, “Setting the Error Message Language”.
In MySQL, the server constructs error messages and returns them to clients as follows:
• The message template has the character set associated with the error message language. For
example, English, Korean, and Russian messages use latin1, euckr, and koi8r, respectively.
• Parameters in the message template are replaced with values that apply to a specific error
occurrence. These parameters use their own character set. Identifiers such as table or column
names use UTF-8. Data values retain their character set. For example, in the following duplicate-key
message, 'xxx' has the character set of the table column associated with key 1:
Duplicate entry 'xxx' for key1

The preceding method of error-message construction can result in messages that contain a mix of
character sets unless all items involved contain only ASCII characters. This issue is resolved in MySQL
5.5, in which error messages are constructed internally within the server using UTF-8 and returned to
the client in the character set specified by the character_set_results system variable.

10.1.7 Collation Issues
The following sections discuss various aspects of character set collations.

10.1.7.1 Collation Naming Conventions
MySQL collation names follow these conventions:
• A name ending in _ci indicates a case-insensitive collation.
• A name ending in _cs indicates a case-sensitive collation.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

• A name ending in _bin indicates a binary collation. Character comparisons are based on character
binary code values.

10.1.7.2 Using COLLATE in SQL Statements
With the COLLATE clause, you can override whatever the default collation is for a comparison.
COLLATE may be used in various parts of SQL statements. Here are some examples:
• With ORDER BY:
SELECT k
FROM t1
ORDER BY k COLLATE latin1_german2_ci;

• With AS:
SELECT k COLLATE latin1_german2_ci AS k1
FROM t1
ORDER BY k1;

• With GROUP BY:
SELECT k
FROM t1
GROUP BY k COLLATE latin1_german2_ci;

• With aggregate functions:
SELECT MAX(k COLLATE latin1_german2_ci)
FROM t1;

• With DISTINCT:
SELECT DISTINCT k COLLATE latin1_german2_ci
FROM t1;

• With WHERE:
SELECT *
FROM t1
WHERE _latin1 'Müller' COLLATE latin1_german2_ci = k;

SELECT *
FROM t1
WHERE k LIKE _latin1 'Müller' COLLATE latin1_german2_ci;

• With HAVING:
SELECT k
FROM t1
GROUP BY k
HAVING k = _latin1 'Müller' COLLATE latin1_german2_ci;

10.1.7.3 COLLATE Clause Precedence
The COLLATE clause has high precedence (higher than ||), so the following two expressions are
equivalent:
x || y COLLATE z

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

x || (y COLLATE z)

10.1.7.4 Collations Must Be for the Right Character Set
Each character set has one or more collations, but each collation is associated with one and only one
character set. Therefore, the following statement causes an error message because the latin2_bin
collation is not legal with the latin1 character set:
mysql> SELECT _latin1 'x' COLLATE latin2_bin;
ERROR 1253 (42000): COLLATION 'latin2_bin' is not valid
for CHARACTER SET 'latin1'

10.1.7.5 Collation of Expressions
In the great majority of statements, it is obvious what collation MySQL uses to resolve a comparison
operation. For example, in the following cases, it should be clear that the collation is the collation of
column charset_name:
SELECT x FROM T ORDER BY x;
SELECT x FROM T WHERE x = x;
SELECT DISTINCT x FROM T;

However, with multiple operands, there can be ambiguity. For example:
SELECT x FROM T WHERE x = 'Y';

Should the comparison use the collation of the column x, or of the string literal 'Y'? Both x and 'Y'
have collations, so which collation takes precedence?
Standard SQL resolves such questions using what used to be called “coercibility” rules. MySQL
assigns coercibility values as follows:
• An explicit COLLATE clause has a coercibility of 0. (Not coercible at all.)
• The concatenation of two strings with different collations has a coercibility of 1.
• The collation of a column or a stored routine parameter or local variable has a coercibility of 2.
• A “system constant” (the string returned by functions such as USER() or VERSION()) has a
coercibility of 3.
• The collation of a literal has a coercibility of 4.
• NULL or an expression that is derived from NULL has a coercibility of 5.
The preceding coercibility values are current as of MySQL 5.0.3. Prior to 5.0.3, there is no system
constant or NULL coercibility. Functions such as USER() have a coercibility of 2 rather than 3, and
literals have a coercibility of 3 rather than 4.
MySQL uses coercibility values with the following rules to resolve ambiguities:
• Use the collation with the lowest coercibility value.
• If both sides have the same coercibility, then:
• If both sides are Unicode, or both sides are not Unicode, it is an error.
• If one of the sides has a Unicode character set, and another side has a non-Unicode character set,
the side with Unicode character set wins, and automatic character set conversion is applied to the
non-Unicode side. For example, the following statement does not return an error:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

SELECT CONCAT(utf8_column, latin1_column) FROM t1;

It returns a result that has a character set of utf8 and the same collation as utf8_column.
Values of latin1_column are automatically converted to utf8 before concatenating.
• For an operation with operands from the same character set but that mix a _bin collation and
a _ci or _cs collation, the _bin collation is used. This is similar to how operations that mix
nonbinary and binary strings evaluate the operands as binary strings, except that it is for collations
rather than data types.
Although automatic conversion is not in the SQL standard, the SQL standard document does say that
every character set is (in terms of supported characters) a “subset” of Unicode. Because it is a wellknown principle that “what applies to a superset can apply to a subset,” we believe that a collation for
Unicode can apply for comparisons with non-Unicode strings.
Examples:
Comparison

Collation Used

column1 = 'A'

Use collation of column1

column1 = 'A' COLLATE x

Use collation of 'A' COLLATE x

column1 COLLATE x = 'A' COLLATE y

Error

The COERCIBILITY() function can be used to determine the coercibility of a string expression:
mysql> SELECT COERCIBILITY('A' COLLATE latin1_swedish_ci);
-> 0
mysql> SELECT COERCIBILITY(VERSION());
-> 3
mysql> SELECT COERCIBILITY('A');
-> 4

See Section 12.13, “Information Functions”.
For implicit conversion of a numeric or temporal value to a string, such as occurs for the argument 1
in the expression CONCAT(1, 'abc'), the result is a binary string for which the character set and
collation are binary. See Section 12.2, “Type Conversion in Expression Evaluation”.

10.1.7.6 The _bin and binary Collations
This section describes how _bin collations for nonbinary strings differ from the binary “collation” for
binary strings.
Nonbinary strings (as stored in the CHAR, VARCHAR, and TEXT data types) have a character set and
collation. A given character set can have several collations, each of which defines a particular sorting
and comparison order for the characters in the set. One of these is the binary collation for the character
set, indicated by a _bin suffix in the collation name. For example, latin1 and utf8 have binary
collations named latin1_bin and utf8_bin.
Binary strings (as stored in the BINARY, VARBINARY, and BLOB data types) have no character set
or collation in the sense that nonbinary strings do. (Applied to a binary string, the CHARSET() and
COLLATION() functions both return a value of binary.) Binary strings are sequences of bytes and the
numeric values of those bytes determine sort order.
The _bin collations differ from the binary collation in several respects.
The unit for sorting and comparison. Binary strings are sequences of bytes. Sorting and comparison
is always based on numeric byte values. Nonbinary strings are sequences of characters, which might
be multibyte. Collations for nonbinary strings define an ordering of the character values for sorting
and comparison. For the _bin collation, this ordering is based solely on binary code values of the
characters (which is similar to ordering for binary strings except that a _bin collation must take into
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

account that a character might contain multiple bytes). For other collations, character ordering might
take additional factors such as lettercase into account.
Character set conversion. A nonbinary string has a character set and is converted to another
character set in many cases, even when the string has a _bin collation:
• When assigning column values from another column that has a different character set:
UPDATE t1 SET utf8_bin_column=latin1_column;
INSERT INTO t1 (latin1_column) SELECT utf8_bin_column FROM t2;

• When assigning column values for INSERT or UPDATE using a string literal:
SET NAMES latin1;
INSERT INTO t1 (utf8_bin_column) VALUES ('string-in-latin1');

• When sending results from the server to a client:
SET NAMES latin1;
SELECT utf8_bin_column FROM t2;

For binary string columns, no conversion occurs. For the preceding cases, the string value is copied
byte-wise.
Lettercase conversion. Collations provide information about lettercase of characters, so characters
in a nonbinary string can be converted from one lettercase to another, even for _bin collations that
ignore lettercase for ordering:
mysql> SET NAMES latin1 COLLATE latin1_bin;
Query OK, 0 rows affected (0.02 sec)
mysql> SELECT LOWER('aA'), UPPER('zZ');
+-------------+-------------+
| LOWER('aA') | UPPER('zZ') |
+-------------+-------------+
| aa
| ZZ
|
+-------------+-------------+
1 row in set (0.13 sec)

The concept of lettercase does not apply to bytes in a binary string. To perform lettercase conversion,
the string must be converted to a nonbinary string:
mysql> SET NAMES binary;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT LOWER('aA'), LOWER(CONVERT('aA' USING latin1));
+-------------+-----------------------------------+
| LOWER('aA') | LOWER(CONVERT('aA' USING latin1)) |
+-------------+-----------------------------------+
| aA
| aa
|
+-------------+-----------------------------------+
1 row in set (0.00 sec)

Trailing space handling in comparisons. Nonbinary strings have PADSPACE behavior for all
collations, including _bin collations. Trailing spaces are insignificant in comparisons:
mysql> SET NAMES utf8 COLLATE utf8_bin;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT 'a ' = 'a';
+------------+
| 'a ' = 'a' |
+------------+

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

|
1 |
+------------+
1 row in set (0.00 sec)

For binary strings, all characters are significant in comparisons, including trailing spaces:
mysql> SET NAMES binary;
Query OK, 0 rows affected (0.00 sec)
mysql> SELECT 'a ' = 'a';
+------------+
| 'a ' = 'a' |
+------------+
|
0 |
+------------+
1 row in set (0.00 sec)

Trailing space handling for inserts and retrievals. CHAR(N) columns store nonbinary strings.
Values shorter than N characters are extended with spaces on insertion. For retrieval, trailing spaces
are removed.
BINARY(N) columns store binary strings. Values shorter than N bytes are extended with 0x00 bytes
on insertion. For retrieval, nothing is removed; a value of the declared length is always returned.
mysql> CREATE TABLE t1 (
->
a CHAR(10) CHARACTER SET utf8 COLLATE utf8_bin,
->
b BINARY(10)
-> );
Query OK, 0 rows affected (0.09 sec)
mysql> INSERT INTO t1 VALUES ('a','a');
Query OK, 1 row affected (0.01 sec)
mysql> SELECT HEX(a), HEX(b) FROM t1;
+--------+----------------------+
| HEX(a) | HEX(b)
|
+--------+----------------------+
| 61
| 61000000000000000000 |
+--------+----------------------+
1 row in set (0.04 sec)

10.1.7.7 The BINARY Operator
The BINARY operator casts the string following it to a binary string. This is an easy way to force a
comparison to be done byte by byte rather than character by character. BINARY also causes trailing
spaces to be significant.
mysql> SELECT
-> 1
mysql> SELECT
-> 0
mysql> SELECT
-> 1
mysql> SELECT
-> 0

'a' = 'A';
BINARY 'a' = 'A';
'a' = 'a ';
BINARY 'a' = 'a ';

BINARY str is shorthand for CAST(str AS BINARY).
The BINARY attribute in character column definitions has a different effect. A character column
defined with the BINARY attribute is assigned the binary collation of the column character set. Every
character set has a binary collation. For example, the binary collation for the latin1 character set
is latin1_bin, so if the table default character set is latin1, these two column definitions are
equivalent:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Collation Issues

CHAR(10) BINARY
CHAR(10) CHARACTER SET latin1 COLLATE latin1_bin

The use of CHARACTER SET binary in the definition of a CHAR, VARCHAR, or TEXT column causes
the column to be treated as a binary data type. For example, the following pairs of definitions are
equivalent:
CHAR(10) CHARACTER SET binary
BINARY(10)
VARCHAR(10) CHARACTER SET binary
VARBINARY(10)
TEXT CHARACTER SET binary
BLOB

10.1.7.8 Examples of the Effect of Collation
Example 1: Sorting German Umlauts
Suppose that column X in table T has these latin1 column values:
Muffler
Müller
MX Systems
MySQL

Suppose also that the column values are retrieved using the following statement:
SELECT X FROM T ORDER BY X COLLATE collation_name;

The following table shows the resulting order of the values if we use ORDER BY with different collations.
latin1_swedish_ci

latin1_german1_ci

latin1_german2_ci

Muffler

Muffler

Müller

MX Systems

Müller

Muffler

Müller

MX Systems

MX Systems

MySQL

MySQL

MySQL

The character that causes the different sort orders in this example is the U with two dots over it (ü),
which the Germans call “U-umlaut.”
• The first column shows the result of the SELECT using the Swedish/Finnish collating rule, which says
that U-umlaut sorts with Y.
• The second column shows the result of the SELECT using the German DIN-1 rule, which says that Uumlaut sorts with U.
• The third column shows the result of the SELECT using the German DIN-2 rule, which says that Uumlaut sorts with UE.
Example 2: Searching for German Umlauts
Suppose that you have three tables that differ only by the character set and collation used:
mysql>
mysql>
->
->
mysql>

This
documentation
is for an
older version.
If you're

SET NAMES utf8;
CREATE TABLE german1 (
c CHAR(10)
) CHARACTER SET latin1 COLLATE latin1_german1_ci;
CREATE TABLE german2 (

This
documentation
is for an
older version.
If you're

String Repertoire

->
c CHAR(10)
-> ) CHARACTER SET latin1 COLLATE latin1_german2_ci;
mysql> CREATE TABLE germanutf8 (
->
c CHAR(10)
-> ) CHARACTER SET utf8 COLLATE utf8_unicode_ci;

Each table contains two records:
mysql> INSERT INTO german1 VALUES ('Bar'), ('Bär');
mysql> INSERT INTO german2 VALUES ('Bar'), ('Bär');
mysql> INSERT INTO germanutf8 VALUES ('Bar'), ('Bär');

Two of the above collations have an A = Ä equality, and one has no such equality
(latin1_german2_ci). For that reason, you'll get these results in comparisons:
mysql> SELECT * FROM german1 WHERE c = 'Bär';
+------+
| c
|
+------+
| Bar |
| Bär |
+------+
mysql> SELECT * FROM german2 WHERE c = 'Bär';
+------+
| c
|
+------+
| Bär |
+------+
mysql> SELECT * FROM germanutf8 WHERE c = 'Bär';
+------+
| c
|
+------+
| Bar |
| Bär |
+------+

This is not a bug but rather a consequence of the sorting properties of latin1_german1_ci and
utf8_unicode_ci (the sorting shown is done according to the German DIN 5007 standard).

10.1.8 String Repertoire
The repertoire of a character set is the collection of characters in the set.
As of MySQL 5.0.48, string expressions have a repertoire attribute, which can have two values:
• ASCII: The expression can contain only characters in the Unicode range U+0000 to U+007F.
• UNICODE: The expression can contain characters in the Unicode range U+0000 to U+FFFF.
The ASCII range is a subset of UNICODE range, so a string with ASCII repertoire can be converted
safely without loss of information to the character set of any string with UNICODE repertoire or to a
character set that is a superset of ASCII. (All MySQL character sets are supersets of ASCII with the
exception of swe7, which reuses some punctuation characters for Swedish accented characters.) The
use of repertoire enables character set conversion in expressions for many cases where MySQL would
otherwise return an “illegal mix of collations” error.
The following discussion provides examples of expressions and their repertoires, and describes how
the use of repertoire changes string expression evaluation:
• The repertoire for string constants depends on string content:
SET NAMES utf8; SELECT 'abc';
SELECT _utf8'def';
SELECT N'MySQL';

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

String Repertoire

Although the character set is utf8 in each of the preceding cases, the strings do not actually contain
any characters outside the ASCII range, so their repertoire is ASCII rather than UNICODE.
• Columns having the ascii character set have ASCII repertoire because of their character set. In
the following table, c1 has ASCII repertoire:
CREATE TABLE t1 (c1 CHAR(1) CHARACTER SET ascii);

The following example illustrates how repertoire enables a result to be determined in a case where
an error occurs without repertoire:
CREATE TABLE t1 (
c1 CHAR(1) CHARACTER SET latin1,
c2 CHAR(1) CHARACTER SET ascii
);
INSERT INTO t1 VALUES ('a','b');
SELECT CONCAT(c1,c2) FROM t1;

Without repertoire, this error occurs:
ERROR 1267 (HY000): Illegal mix of collations (latin1_swedish_ci,IMPLICIT)
and (ascii_general_ci,IMPLICIT) for operation 'concat'

Using repertoire, subset to superset (ascii to latin1) conversion can occur and a result is
returned:
+---------------+
| CONCAT(c1,c2) |
+---------------+
| ab
|
+---------------+

• Functions with one string argument inherit the repertoire of their argument. The result of
UPPER(_utf8'abc') has ASCII repertoire, because its argument has ASCII repertoire.
• For functions that return a string but do not have string arguments and use
character_set_connection as the result character set, the result repertoire is ASCII if
character_set_connection is ascii, and UNICODE otherwise:
FORMAT(numeric_column, 4);

Use of repertoire changes how MySQL evaluates the following example:
SET NAMES ascii;
CREATE TABLE t1 (a INT, b VARCHAR(10) CHARACTER SET latin1);
INSERT INTO t1 VALUES (1,'b');
SELECT CONCAT(FORMAT(a, 4), b) FROM t1;

Without repertoire, this error occurs:
ERROR 1267 (HY000): Illegal mix of collations (ascii_general_ci,COERCIBLE)
and (latin1_swedish_ci,IMPLICIT) for operation 'concat'

With repertoire, a result is returned:
+-------------------------+
| CONCAT(FORMAT(a, 4), b) |
+-------------------------+
| 1.0000b
|

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Operations Affected by Character Set Support

+-------------------------+

• Functions with two or more string arguments use the “widest” argument repertoire for the result
repertoire (UNICODE is wider than ASCII). Consider the following CONCAT() calls:
CONCAT(_ucs2 X'0041', _ucs2 X'0042')
CONCAT(_ucs2 X'0041', _ucs2 X'00C2')

For the first call, the repertoire is ASCII because both arguments are within the range of the ascii
character set. For the second call, the repertoire is UNICODE because the second argument is
outside the ascii character set range.
• The repertoire for function return values is determined based only on the repertoire of the arguments
that affect the result's character set and collation.
IF(column1 < column2, 'smaller', 'greater')

The result repertoire is ASCII because the two string arguments (the second argument and the third
argument) both have ASCII repertoire. The first argument does not matter for the result repertoire,
even if the expression uses string values.

10.1.9 Operations Affected by Character Set Support
This section describes operations that take character set information into account.

10.1.9.1 Result Strings
MySQL has many operators and functions that return a string. This section answers the question: What
is the character set and collation of such a string?
For simple functions that take string input and return a string result as output, the output's character
set and collation are the same as those of the principal input value. For example, UPPER(X) returns a
string whose character string and collation are the same as that of X. The same applies for INSTR(),
LCASE(), LOWER(), LTRIM(), MID(), REPEAT(), REPLACE(), REVERSE(), RIGHT(), RPAD(),
RTRIM(), SOUNDEX(), SUBSTRING(), TRIM(), UCASE(), and UPPER().
Note: The REPLACE() function, unlike all other functions, always ignores the collation of the string
input and performs a case-sensitive comparison.
If a string input or function result is a binary string, the string has no character set or collation. This can
be checked by using the CHARSET() and COLLATION() functions, both of which return binary to
indicate that their argument is a binary string:
mysql> SELECT CHARSET(BINARY 'a'), COLLATION(BINARY 'a');
+---------------------+-----------------------+
| CHARSET(BINARY 'a') | COLLATION(BINARY 'a') |
+---------------------+-----------------------+
| binary
| binary
|
+---------------------+-----------------------+

For operations that combine multiple string inputs and return a single string output, the “aggregation
rules” of standard SQL apply for determining the collation of the result:
• If an explicit COLLATE X occurs, use X.
• If explicit COLLATE X and COLLATE Y occur, raise an error.
• Otherwise, if all collations are X, use X.
• Otherwise, the result has no collation.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Operations Affected by Character Set Support

For example, with CASE ... WHEN a THEN b WHEN b THEN c COLLATE X END, the resulting
collation is X. The same applies for UNION, ||, CONCAT(), ELT(), GREATEST(), IF(), and
LEAST().
For operations that convert to character data, the character set and collation of the strings
that result from the operations are defined by the character_set_connection and
collation_connection system variables. This applies only to CAST(), CONV(), FORMAT(),
HEX(), SPACE(). Before MySQL 5.0.15, it also applies to CHAR().
If you are uncertain about the character set or collation of the result returned by a string function, you
can use the CHARSET() or COLLATION() function to find out:
mysql> SELECT USER(), CHARSET(USER()), COLLATION(USER());
+----------------+-----------------+-------------------+
| USER()
| CHARSET(USER()) | COLLATION(USER()) |
+----------------+-----------------+-------------------+
| test@localhost | utf8
| utf8_general_ci
|
+----------------+-----------------+-------------------+

10.1.9.2 CONVERT() and CAST()
CONVERT() provides a way to convert data between different character sets. The syntax is:
CONVERT(expr USING transcoding_name)

In MySQL, transcoding names are the same as the corresponding character set names.
Examples:
SELECT CONVERT(_latin1'Müller' USING utf8);
INSERT INTO utf8table (utf8column)
SELECT CONVERT(latin1field USING utf8) FROM latin1table;

CONVERT(... USING ...) is implemented according to the standard SQL specification.
You may also use CAST() to convert a string to a different character set. The syntax is:
CAST(character_string AS character_data_type CHARACTER SET charset_name)

Example:
SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8);

If you use CAST() without specifying CHARACTER SET, the resulting character set and collation are
defined by the character_set_connection and collation_connection system variables.
If you use CAST() with CHARACTER SET X, the resulting character set and collation are X and the
default collation of X.
You may not use a COLLATE clause inside a CONVERT() or CAST() call, but you may use it outside.
For example, CAST(... COLLATE ...) is illegal, but CAST(...) COLLATE ... is legal:
SELECT CAST(_latin1'test' AS CHAR CHARACTER SET utf8) COLLATE utf8_bin;

10.1.9.3 SHOW Statements and INFORMATION_SCHEMA
Several SHOW statements provide additional character set information. These include SHOW
CHARACTER SET, SHOW COLLATION, SHOW CREATE DATABASE, SHOW CREATE TABLE and SHOW
COLUMNS. These statements are described here briefly. For more information, see Section 13.7.5,
“SHOW Syntax”.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Operations Affected by Character Set Support

INFORMATION_SCHEMA has several tables that contain information similar to that displayed by
the SHOW statements. For example, the CHARACTER_SETS and COLLATIONS tables contain
the information displayed by SHOW CHARACTER SET and SHOW COLLATION. See Chapter 19,
INFORMATION_SCHEMA Tables.
The SHOW CHARACTER SET statement shows all available character sets. It takes an optional LIKE
clause that indicates which character set names to match. For example:
mysql> SHOW CHARACTER SET LIKE 'latin%';
+---------+-----------------------------+-------------------+--------+
| Charset | Description
| Default collation | Maxlen |
+---------+-----------------------------+-------------------+--------+
| latin1 | cp1252 West European
| latin1_swedish_ci |
1 |
| latin2 | ISO 8859-2 Central European | latin2_general_ci |
1 |
| latin5 | ISO 8859-9 Turkish
| latin5_turkish_ci |
1 |
| latin7 | ISO 8859-13 Baltic
| latin7_general_ci |
1 |
+---------+-----------------------------+-------------------+--------+

The output from SHOW COLLATION includes all available character sets. It takes an optional LIKE
clause that indicates which collation names to match. For example:
mysql> SHOW COLLATION LIKE 'latin1%';
+-------------------+---------+----+---------+----------+---------+
| Collation
| Charset | Id | Default | Compiled | Sortlen |
+-------------------+---------+----+---------+----------+---------+
| latin1_german1_ci | latin1 | 5 |
|
|
0 |
| latin1_swedish_ci | latin1 | 8 | Yes
| Yes
|
0 |
| latin1_danish_ci | latin1 | 15 |
|
|
0 |
| latin1_german2_ci | latin1 | 31 |
| Yes
|
2 |
| latin1_bin
| latin1 | 47 |
| Yes
|
0 |
| latin1_general_ci | latin1 | 48 |
|
|
0 |
| latin1_general_cs | latin1 | 49 |
|
|
0 |
| latin1_spanish_ci | latin1 | 94 |
|
|
0 |
+-------------------+---------+----+---------+----------+---------+

SHOW CREATE DATABASE displays the CREATE DATABASE statement that creates a given database:
mysql> SHOW CREATE DATABASE test;
+----------+-----------------------------------------------------------------+
| Database | Create Database
|
+----------+-----------------------------------------------------------------+
| test
| CREATE DATABASE `test` /*!40100 DEFAULT CHARACTER SET latin1 */ |
+----------+-----------------------------------------------------------------+

If no COLLATE clause is shown, the default collation for the character set applies.
SHOW CREATE TABLE is similar, but displays the CREATE TABLE statement to create a given table.
The column definitions indicate any character set specifications, and the table options include character
set information.
The SHOW COLUMNS statement displays the collations of a table's columns when invoked as SHOW
FULL COLUMNS. Columns with CHAR, VARCHAR, or TEXT data types have collations. Numeric and
other noncharacter types have no collation (indicated by NULL as the Collation value). For example:
mysql> SHOW FULL COLUMNS FROM person\G
*************************** 1. row ***************************
Field: id
Type: smallint(5) unsigned
Collation: NULL
Null: NO
Key: PRI
Default: NULL
Extra: auto_increment
Privileges: select,insert,update,references

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Unicode Support

Comment:
*************************** 2. row ***************************
Field: name
Type: char(60)
Collation: latin1_swedish_ci
Null: NO
Key:
Default:
Extra:
Privileges: select,insert,update,references
Comment:

The character set is not part of the display but is implied by the collation name.

10.1.10 Unicode Support
MySQL supports two character sets for storing Unicode data:
• ucs2, the UCS-2 encoding of the Unicode character set using 16 bits per character.
• utf8, a UTF-8 encoding of the Unicode character set using one to three bytes per character.
These two character sets support the characters from the Basic Multilingual Plane (BMP) of Unicode
Version 3.0. BMP characters have these characteristics:
• Their code values are between 0 and 65535 (or U+0000 .. U+FFFF).
• They can be encoded with a fixed 16-bit word, as in ucs2.
• They can be encoded with 8, 16, or 24 bits, as in utf8.
• They are sufficient for almost all characters in major languages.
The ucs2 and utf8 character sets do not support supplementary characters that lie outside the BMP.
Characters outside the BMP compare as REPLACEMENT CHARACTER and convert to '?' when
converted to a Unicode character set.
A similar set of collations is available for each Unicode character set. For example, each has a Danish
collation, the names of which are ucs2_danish_ci and utf8_danish_ci. All Unicode collations are
listed at Section 10.1.13.1, “Unicode Character Sets”.
The MySQL implementation of UCS-2 stores characters in big-endian byte order and does not use a
byte order mark (BOM) at the beginning of values. Other database systems might use little-endian byte
order or a BOM. In such cases, conversion of values will need to be performed when transferring data
between those systems and MySQL.
MySQL uses no BOM for UTF-8 values.
Client applications that need to communicate with the server using Unicode should set the client
character set accordingly; for example, by issuing a SET NAMES 'utf8' statement. ucs2 cannot be
used as a client character set, which means that it does not work for SET NAMES or SET CHARACTER
SET. (See Section 10.1.4, “Connection Character Sets and Collations”.)
The following sections provide additional detail on the Unicode character sets in MySQL.

10.1.10.1 The ucs2 Character Set (UCS-2 Unicode Encoding)
In UCS-2, every character is represented by a 2-byte Unicode code with the most significant byte
first. For example: LATIN CAPITAL LETTER A has the code 0x0041 and it is stored as a 2-byte
sequence: 0x00 0x41. CYRILLIC SMALL LETTER YERU (Unicode 0x044B) is stored as a 2-byte
sequence: 0x04 0x4B. For Unicode characters and their codes, please refer to the Unicode Home
Page.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

UTF-8 for Metadata

In MySQL, the ucs2 character set is a fixed-length 16-bit encoding for Unicode BMP characters.

10.1.10.2 The utf8 Character Set (3-Byte UTF-8 Unicode Encoding)
UTF-8 (Unicode Transformation Format with 8-bit units) is an alternative way to store Unicode data.
It is implemented according to RFC 3629, which describes encoding sequences that take from one to
four bytes. MySQL support for UTF-8 does not include 4-byte sequences. (An older standard for UTF-8
encoding, RFC 2279, describes UTF-8 sequences that take from one to six bytes. RFC 3629 renders
RFC 2279 obsolete; for this reason, sequences with five and six bytes are no longer used.)
The idea of UTF-8 is that various Unicode characters are encoded using byte sequences of different
lengths:
• Basic Latin letters, digits, and punctuation signs use one byte.
• Most European and Middle East script letters fit into a 2-byte sequence: extended Latin letters (with
tilde, macron, acute, grave and other accents), Cyrillic, Greek, Armenian, Hebrew, Arabic, Syriac,
and others.
• Korean, Chinese, and Japanese ideographs use 3-byte sequences.
Tip: To save space with UTF-8, use VARCHAR instead of CHAR. Otherwise, MySQL must reserve three
bytes for each character in a CHAR CHARACTER SET utf8 column because that is the maximum
possible length. For example, MySQL must reserve 30 bytes for a CHAR(10) CHARACTER SET utf8
column.
For additional information about data type storage, see Section 11.7, “Data Type Storage
Requirements”. For information about InnoDB physical row storage, including how InnoDB tables that
use COMPACT row format handle UTF-8 CHAR(N) columns internally, see Section 14.2.10.5, “Physical
Row Structure”.

10.1.11 UTF-8 for Metadata
Metadata is “the data about the data.” Anything that describes the database—as opposed to being
the contents of the database—is metadata. Thus column names, database names, user names,
version names, and most of the string results from SHOW are metadata. This is also true of the contents
of tables in INFORMATION_SCHEMA because those tables by definition contain information about
database objects.
Representation of metadata must satisfy these requirements:
• All metadata must be in the same character set. Otherwise, neither the SHOW statements nor SELECT
statements for tables in INFORMATION_SCHEMA would work properly because different rows in the
same column of the results of these operations would be in different character sets.
• Metadata must include all characters in all languages. Otherwise, users would not be able to name
columns and tables using their own languages.
To satisfy both requirements, MySQL stores metadata in a Unicode character set, namely UTF-8. This
does not cause any disruption if you never use accented or non-Latin characters. But if you do, you
should be aware that metadata is in UTF-8.
The metadata requirements mean that the return values of the USER(), CURRENT_USER(),
SESSION_USER(), SYSTEM_USER(), DATABASE(), and VERSION() functions have the UTF-8
character set by default.
The server sets the character_set_system system variable to the name of the metadata character
set:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Column Character Set Conversion

mysql> SHOW VARIABLES LIKE 'character_set_system';
+----------------------+-------+
| Variable_name
| Value |
+----------------------+-------+
| character_set_system | utf8 |
+----------------------+-------+

Storage of metadata using Unicode does not mean that the server returns headers of columns and
the results of DESCRIBE functions in the character_set_system character set by default. When
you use SELECT column1 FROM t, the name column1 itself is returned from the server to the
client in the character set determined by the value of the character_set_results system variable,
which has a default value of latin1. If you want the server to pass metadata results back in a
different character set, use the SET NAMES statement to force the server to perform character set
conversion. SET NAMES sets the character_set_results and other related system variables.
(See Section 10.1.4, “Connection Character Sets and Collations”.) Alternatively, a client program can
perform the conversion after receiving the result from the server. It is more efficient for the client to
perform the conversion, but this option is not always available for all clients.
If character_set_results is set to NULL, no conversion is performed and the server returns
metadata using its original character set (the set indicated by character_set_system).
Error messages returned from the server to the client are converted to the client character set
automatically, as with metadata.
If you are using (for example) the USER() function for comparison or assignment within a single
statement, don't worry. MySQL performs some automatic conversion for you.
SELECT * FROM t1 WHERE USER() = latin1_column;

This works because the contents of latin1_column are automatically converted to UTF-8 before the
comparison.
INSERT INTO t1 (latin1_column) SELECT USER();

This works because the contents of USER() are automatically converted to latin1 before the
assignment.
Although automatic conversion is not in the SQL standard, the SQL standard document does say that
every character set is (in terms of supported characters) a “subset” of Unicode. Because it is a wellknown principle that “what applies to a superset can apply to a subset,” we believe that a collation for
Unicode can apply for comparisons with non-Unicode strings. For more information about coercion of
strings, see Section 10.1.7.5, “Collation of Expressions”.

10.1.12 Column Character Set Conversion
To convert a binary or nonbinary string column to use a particular character set, use ALTER TABLE.
For successful conversion to occur, one of the following conditions must apply:
• If the column has a binary data type (BINARY, VARBINARY, BLOB), all the values that it contains
must be encoded using a single character set (the character set you're converting the column to). If
you use a binary column to store information in multiple character sets, MySQL has no way to know
which values use which character set and cannot convert the data properly.
• If the column has a nonbinary data type (CHAR, VARCHAR, TEXT), its contents should be encoded
in the column character set, not some other character set. If the contents are encoded in a different
character set, you can convert the column to use a binary data type first, and then to a nonbinary
column with the desired character set.
Suppose that a table t has a binary column named col1 defined as VARBINARY(50). Assuming that
the information in the column is encoded using a single character set, you can convert it to a nonbinary
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

column that has that character set. For example, if col1 contains binary data representing characters
in the greek character set, you can convert it as follows:
ALTER TABLE t MODIFY col1 VARCHAR(50) CHARACTER SET greek;

If your original column has a type of BINARY(50), you could convert it to CHAR(50), but the resulting
values will be padded with 0x00 bytes at the end, which may be undesirable. To remove these bytes,
use the TRIM() function:
UPDATE t SET col1 = TRIM(TRAILING 0x00 FROM col1);

Suppose that table t has a nonbinary column named col1 defined as CHAR(50) CHARACTER SET
latin1 but you want to convert it to use utf8 so that you can store values from many languages. The
following statement accomplishes this:
ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET utf8;

Conversion may be lossy if the column contains characters that are not in both character sets.
A special case occurs if you have old tables from before MySQL 4.1 where a nonbinary column
contains values that actually are encoded in a character set different from the server's default character
set. For example, an application might have stored sjis values in a column, even though MySQL's
default character set was latin1. It is possible to convert the column to use the proper character set
but an additional step is required. Suppose that the server's default character set was latin1 and
col1 is defined as CHAR(50) but its contents are sjis values. The first step is to convert the column
to a binary data type, which removes the existing character set information without performing any
character conversion:
ALTER TABLE t MODIFY col1 BLOB;

The next step is to convert the column to a nonbinary data type with the proper character set:
ALTER TABLE t MODIFY col1 CHAR(50) CHARACTER SET sjis;

This procedure requires that the table not have been modified already with statements such as INSERT
or UPDATE after an upgrade to MySQL 4.1 or later. In that case, MySQL would store new values in the
column using latin1, and the column will contain a mix of sjis and latin1 values and cannot be
converted properly.
If you specified attributes when creating a column initially, you should also specify them when altering
the table with ALTER TABLE. For example, if you specified NOT NULL and an explicit DEFAULT
value, you should also provide them in the ALTER TABLE statement. Otherwise, the resulting column
definition will not include those attributes.
To convert all character columns in a table, the ALTER TABLE ... CONVERT TO CHARACTER SET
charset statement may be useful. See Section 13.1.4, “ALTER TABLE Syntax”.

10.1.13 Character Sets and Collations That MySQL Supports
MySQL supports 70+ collations for 30+ character sets. This section indicates which character sets
MySQL supports. There is one subsection for each group of related character sets. For each character
set, the permissible collations are listed.
You can always list the available character sets and their default collations with the SHOW CHARACTER
SET statement:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

mysql> SHOW CHARACTER SET;
+----------+-----------------------------+---------------------+
| Charset | Description
| Default collation
|
+----------+-----------------------------+---------------------+
| big5
| Big5 Traditional Chinese
| big5_chinese_ci
|
| dec8
| DEC West European
| dec8_swedish_ci
|
| cp850
| DOS West European
| cp850_general_ci
|
| hp8
| HP West European
| hp8_english_ci
|
| koi8r
| KOI8-R Relcom Russian
| koi8r_general_ci
|
| latin1
| cp1252 West European
| latin1_swedish_ci
|
| latin2
| ISO 8859-2 Central European | latin2_general_ci
|
| swe7
| 7bit Swedish
| swe7_swedish_ci
|
| ascii
| US ASCII
| ascii_general_ci
|
| ujis
| EUC-JP Japanese
| ujis_japanese_ci
|
| sjis
| Shift-JIS Japanese
| sjis_japanese_ci
|
| hebrew
| ISO 8859-8 Hebrew
| hebrew_general_ci
|
| tis620
| TIS620 Thai
| tis620_thai_ci
|
| euckr
| EUC-KR Korean
| euckr_korean_ci
|
| koi8u
| KOI8-U Ukrainian
| koi8u_general_ci
|
| gb2312
| GB2312 Simplified Chinese
| gb2312_chinese_ci
|
| greek
| ISO 8859-7 Greek
| greek_general_ci
|
| cp1250
| Windows Central European
| cp1250_general_ci
|
| gbk
| GBK Simplified Chinese
| gbk_chinese_ci
|
| latin5
| ISO 8859-9 Turkish
| latin5_turkish_ci
|
| armscii8 | ARMSCII-8 Armenian
| armscii8_general_ci |
| utf8
| UTF-8 Unicode
| utf8_general_ci
|
| ucs2
| UCS-2 Unicode
| ucs2_general_ci
|
| cp866
| DOS Russian
| cp866_general_ci
|
| keybcs2 | DOS Kamenicky Czech-Slovak | keybcs2_general_ci |
| macce
| Mac Central European
| macce_general_ci
|
| macroman | Mac West European
| macroman_general_ci |
| cp852
| DOS Central European
| cp852_general_ci
|
| latin7
| ISO 8859-13 Baltic
| latin7_general_ci
|
| cp1251
| Windows Cyrillic
| cp1251_general_ci
|
| cp1256
| Windows Arabic
| cp1256_general_ci
|
| cp1257
| Windows Baltic
| cp1257_general_ci
|
| binary
| Binary pseudo charset
| binary
|
| geostd8 | GEOSTD8 Georgian
| geostd8_general_ci |
| cp932
| SJIS for Windows Japanese
| cp932_japanese_ci
|
| eucjpms | UJIS for Windows Japanese
| eucjpms_japanese_ci |
+----------+-----------------------------+---------------------+

In cases where a character set has multiple collations, it might not be clear which collation is most
suitable for a given application. To avoid choosing the wrong collation, it can be helpful to perform
some comparisons with representative data values to make sure that a given collation sorts values the
way you expect.
Collation-Charts.Org is a useful site for information that shows how one collation compares to another.

10.1.13.1 Unicode Character Sets
MySQL has two Unicode character sets:
• ucs2, the UCS-2 encoding of the Unicode character set using 16 bits per character.
• utf8, a UTF-8 encoding of the Unicode character set using one to three bytes per character.
You can store text in about 650 languages using these character sets. This section lists the collations
available for each Unicode character set and describes their differentiating properties. For general
information about the character sets, see Section 10.1.10, “Unicode Support”.
A similar set of collations is available for each Unicode character set. These are shown in the following
list, where xxx represents the character set name. For example, xxx_danish_ci represents the
Danish collations, the specific names of which are ucs2_danish_ci and utf8_danish_ci.
• xxx_bin
• xxx_czech_ci
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

• xxx_danish_ci
• xxx_esperanto_ci
• xxx_estonian_ci
• xxx_general_ci (default)
• xxx_hungarian_ci
• xxx_icelandic_ci
• xxx_latvian_ci
• xxx_lithuanian_ci
• xxx_persian_ci
• xxx_polish_ci
• xxx_roman_ci
• xxx_romanian_ci
• xxx_slovak_ci
• xxx_slovenian_ci
• xxx_spanish_ci
• xxx_spanish2_ci
• xxx_swedish_ci
• xxx_turkish_ci
• xxx_unicode_ci
The xxx_esperanto_ci collations were added in MySQL 5.0.13. The xxx_hungarian_ci
collations were added in MySQL 5.0.19.
MySQL implements the xxx_unicode_ci collations according to the Unicode Collation Algorithm
(UCA) described at http://www.unicode.org/reports/tr10/. The collation uses the version-4.0.0 UCA
weight keys: http://www.unicode.org/Public/UCA/4.0.0/allkeys-4.0.0.txt. The xxx_unicode_ci
collations have only partial support for the Unicode Collation Algorithm. Some characters are not
supported yet. Also, combining marks are not fully supported. This affects primarily Vietnamese,
Yoruba, and some smaller languages such as Navajo. A combined character will be considered
different from the same character written with a single unicode character in string comparisons,
and the two characters are considered to have a different length (for example, as returned by the
CHAR_LENGTH() function or in result set metadata).
MySQL implements language-specific Unicode collations only if the ordering with xxx_unicode_ci
does not work well for a language. Language-specific collations are UCA-based. They are derived from
xxx_unicode_ci with additional language tailoring rules.
For any Unicode character set, operations performed using the xxx_general_ci collation are faster
than those for the xxx_unicode_ci collation. For example, comparisons for the utf8_general_ci
collation are faster, but slightly less correct, than comparisons for utf8_unicode_ci. The reason
for this is that utf8_unicode_ci supports mappings such as expansions; that is, when one
character compares as equal to combinations of other characters. For example, in German and some
other languages “ß” is equal to “ss”. utf8_unicode_ci also supports contractions and ignorable
characters. utf8_general_ci is a legacy collation that does not support expansions, contractions, or
ignorable characters. It can make only one-to-one comparisons between characters.
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

To further illustrate, the following equalities hold in both utf8_general_ci and utf8_unicode_ci
(for the effect this has in comparisons or when doing searches, see Section 10.1.7.8, “Examples of the
Effect of Collation”):
Ä = A
Ö = O
Ü = U

A difference between the collations is that this is true for utf8_general_ci:
ß = s

Whereas this is true for utf8_unicode_ci, which supports the German DIN-1 ordering (also known
as dictionary order):
ß = ss

MySQL implements language-specific collations for the utf8 character set only if the ordering with
utf8_unicode_ci does not work well for a language. For example, utf8_unicode_ci works fine
for German dictionary order and French, so there is no need to create special utf8 collations.
utf8_general_ci also is satisfactory for both German and French, except that “ß” is equal to “s”,
and not to “ss”. If this is acceptable for your application, you should use utf8_general_ci because
it is faster. Otherwise, use utf8_unicode_ci because it is more accurate.
xxx_swedish_ci includes Swedish rules. For example, in Swedish, the following relationship holds,
which is not something expected by a German or French speaker:
Ü = Y < Ö

The xxx_spanish_ci and xxx_spanish2_ci collations correspond to modern Spanish and
traditional Spanish, respectively. In both collations, “ñ” (n-tilde) is a separate letter between “n” and “o”.
In addition, for traditional Spanish, “ch” is a separate letter between “c” and “d”, and “ll” is a separate
letter between “l” and “m”
The xxx_spanish2_ci collations may also be used for Asturian and Galician.
The xxx_danich_ci collations may also be used for Norwegian.
In the xxx_roman_ci collations, I and J compare as equal, and U and V compare as equal.
For additional information about Unicode collations in MySQL, see Collation-Charts.Org (utf8).

10.1.13.2 West European Character Sets
Western European character sets cover most West European languages, such as French, Spanish,
Catalan, Basque, Portuguese, Italian, Albanian, Dutch, German, Danish, Swedish, Norwegian, Finnish,
Faroese, Icelandic, Irish, Scottish, and English.
• ascii (US ASCII) collations:
• ascii_bin
• ascii_general_ci (default)
• cp850 (DOS West European) collations:
• cp850_bin
This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

• cp850_general_ci (default)
• dec8 (DEC Western European) collations:
• dec8_bin
• dec8_swedish_ci (default)
• hp8 (HP Western European) collations:
• hp8_bin
• hp8_english_ci (default)
• latin1 (cp1252 West European) collations:
• latin1_bin
• latin1_danish_ci
• latin1_general_ci
• latin1_general_cs
• latin1_german1_ci
• latin1_german2_ci
• latin1_spanish_ci
• latin1_swedish_ci (default)
latin1 is the default character set. MySQL's latin1 is the same as the Windows cp1252
character set. This means it is the same as the official ISO 8859-1 or IANA (Internet Assigned
Numbers Authority) latin1, except that IANA latin1 treats the code points between 0x80 and
0x9f as “undefined,” whereas cp1252, and therefore MySQL's latin1, assign characters for
those positions. For example, 0x80 is the Euro sign. For the “undefined” entries in cp1252, MySQL
translates 0x81 to Unicode 0x0081, 0x8d to 0x008d, 0x8f to 0x008f, 0x90 to 0x0090, and 0x9d
to 0x009d.
The latin1_swedish_ci collation is the default that probably is used by the majority of MySQL
customers. Although it is frequently said that it is based on the Swedish/Finnish collation rules, there
are Swedes and Finns who disagree with this statement.
The latin1_german1_ci and latin1_german2_ci collations are based on the DIN-1 and
DIN-2 standards, where DIN stands for Deutsches Institut für Normung (the German equivalent of
ANSI). DIN-1 is called the “dictionary collation” and DIN-2 is called the “phone book collation.” For
an example of the effect this has in comparisons or when doing searches, see Section 10.1.7.8,
“Examples of the Effect of Collation”.
• latin1_german1_ci (dictionary) rules:
Ä
Ö
Ü
ß

=
=
=
=

A
O
U
s

• latin1_german2_ci (phone-book) rules:
Ä = AE
Ö = OE

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

Ü = UE
ß = ss

In the latin1_spanish_ci collation, “ñ” (n-tilde) is a separate letter between “n” and “o”.
• macroman (Mac West European) collations:
• macroman_bin
• macroman_general_ci (default)
• swe7 (7bit Swedish) collations:
• swe7_bin
• swe7_swedish_ci (default)
For additional information about Western European collations in MySQL, see Collation-Charts.Org
(ascii, cp850, dec8, hp8, latin1, macroman, swe7).

10.1.13.3 Central European Character Sets
MySQL provides some support for character sets used in the Czech Republic, Slovakia, Hungary,
Romania, Slovenia, Croatia, Poland, and Serbia (Latin).
• cp1250 (Windows Central European) collations:
• cp1250_bin
• cp1250_croatian_ci
• cp1250_czech_cs
• cp1250_general_ci (default)
• cp852 (DOS Central European) collations:
• cp852_bin
• cp852_general_ci (default)
• keybcs2 (DOS Kamenicky Czech-Slovak) collations:
• keybcs2_bin
• keybcs2_general_ci (default)
• latin2 (ISO 8859-2 Central European) collations:
• latin2_bin
• latin2_croatian_ci
• latin2_czech_cs
• latin2_general_ci (default)
• latin2_hungarian_ci
• macce (Mac Central European) collations:
• macce_bin
• macce_general_ci (default)

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

For additional information about Central European collations in MySQL, see Collation-Charts.Org
(cp1250, cp852, keybcs2, latin2, macce).

10.1.13.4 South European and Middle East Character Sets
South European and Middle Eastern character sets supported by MySQL include Armenian, Arabic,
Georgian, Greek, Hebrew, and Turkish.
• armscii8 (ARMSCII-8 Armenian) collations:
• armscii8_bin
• armscii8_general_ci (default)
• cp1256 (Windows Arabic) collations:
• cp1256_bin
• cp1256_general_ci (default)
• geostd8 (GEOSTD8 Georgian) collations:
• geostd8_bin
• geostd8_general_ci (default)
• greek (ISO 8859-7 Greek) collations:
• greek_bin
• greek_general_ci (default)
• hebrew (ISO 8859-8 Hebrew) collations:
• hebrew_bin
• hebrew_general_ci (default)
• latin5 (ISO 8859-9 Turkish) collations:
• latin5_bin
• latin5_turkish_ci (default)
For additional information about South European and Middle Eastern collations in MySQL, see
Collation-Charts.Org (armscii8, cp1256, geostd8, greek, hebrew, latin5).

10.1.13.5 Baltic Character Sets
The Baltic character sets cover Estonian, Latvian, and Lithuanian languages.
• cp1257 (Windows Baltic) collations:
• cp1257_bin
• cp1257_general_ci (default)
• cp1257_lithuanian_ci
• latin7 (ISO 8859-13 Baltic) collations:
• latin7_bin
• latin7_estonian_cs

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

• latin7_general_ci (default)
• latin7_general_cs
For additional information about Baltic collations in MySQL, see Collation-Charts.Org (cp1257, latin7).

10.1.13.6 Cyrillic Character Sets
The Cyrillic character sets and collations are for use with Belarusian, Bulgarian, Russian, Ukrainian,
and Serbian (Cyrillic) languages.
• cp1251 (Windows Cyrillic) collations:
• cp1251_bin
• cp1251_bulgarian_ci
• cp1251_general_ci (default)
• cp1251_general_cs
• cp1251_ukrainian_ci
• cp866 (DOS Russian) collations:
• cp866_bin
• cp866_general_ci (default)
• koi8r (KOI8-R Relcom Russian) collations:
• koi8r_bin
• koi8r_general_ci (default)
• koi8u (KOI8-U Ukrainian) collations:
• koi8u_bin
• koi8u_general_ci (default)
For additional information about Cyrillic collations in MySQL, see Collation-Charts.Org (cp1251, cp866,
koi8r, koi8u). ).

10.1.13.7 Asian Character Sets
The Asian character sets that we support include Chinese, Japanese, Korean, and Thai. These can be
complicated. For example, the Chinese sets must allow for thousands of different characters. See The
cp932 Character Set, for additional information about the cp932 and sjis character sets.
For answers to some common questions and problems relating support for Asian character sets in
MySQL, see Section A.11, “MySQL 5.0 FAQ: MySQL Chinese, Japanese, and Korean Character Sets”.
• big5 (Big5 Traditional Chinese) collations:
• big5_bin
• big5_chinese_ci (default)
• cp932 (SJIS for Windows Japanese) collations:
• cp932_bin

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

• cp932_japanese_ci (default)
• eucjpms (UJIS for Windows Japanese) collations:
• eucjpms_bin
• eucjpms_japanese_ci (default)
• euckr (EUC-KR Korean) collations:
• euckr_bin
• euckr_korean_ci (default)
• gb2312 (GB2312 Simplified Chinese) collations:
• gb2312_bin
• gb2312_chinese_ci (default)
• gbk (GBK Simplified Chinese) collations:
• gbk_bin
• gbk_chinese_ci (default)
• sjis (Shift-JIS Japanese) collations:
• sjis_bin
• sjis_japanese_ci (default)
• tis620 (TIS620 Thai) collations:
• tis620_bin
• tis620_thai_ci (default)
• ujis (EUC-JP Japanese) collations:
• ujis_bin
• ujis_japanese_ci (default)
The big5_chinese_ci collation sorts on number of strokes.
For additional information about Asian collations in MySQL, see Collation-Charts.Org (big5, cp932,
eucjpms, euckr, gb2312, gbk, sjis, tis620, ujis).

The cp932 Character Set
Why is cp932 needed?
In MySQL, the sjis character set corresponds to the Shift_JIS character set defined by IANA,
which supports JIS X0201 and JIS X0208 characters. (See http://www.iana.org/assignments/charactersets.)
However, the meaning of “SHIFT JIS” as a descriptive term has become very vague and it often
includes the extensions to Shift_JIS that are defined by various vendors.
For example, “SHIFT JIS” used in Japanese Windows environments is a Microsoft extension of
Shift_JIS and its exact name is Microsoft Windows Codepage : 932 or cp932. In addition to

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

the characters supported by Shift_JIS, cp932 supports extension characters such as NEC special
characters, NEC selected—IBM extended characters, and IBM selected characters.
Many Japanese users have experienced problems using these extension characters. These problems
stem from the following factors:
• MySQL automatically converts character sets.
• Character sets are converted using Unicode (ucs2).
• The sjis character set does not support the conversion of these extension characters.
• There are several conversion rules from so-called “SHIFT JIS” to Unicode, and some characters
are converted to Unicode differently depending on the conversion rule. MySQL supports only one of
these rules (described later).
The MySQL cp932 character set is designed to solve these problems. It is available as of MySQL
5.0.3.
Because MySQL supports character set conversion, it is important to separate IANA Shift_JIS and
cp932 into two different character sets because they provide different conversion rules.
How does cp932 differ from sjis?
The cp932 character set differs from sjis in the following ways:
• cp932 supports NEC special characters, NEC selected—IBM extended characters, and IBM
selected characters.
• Some cp932 characters have two different code points, both of which convert to the same Unicode
code point. When converting from Unicode back to cp932, one of the code points must be
selected. For this “round trip conversion,” the rule recommended by Microsoft is used. (See http://
support.microsoft.com/kb/170559/EN-US/.)
The conversion rule works like this:
• If the character is in both JIS X 0208 and NEC special characters, use the code point of JIS X
0208.
• If the character is in both NEC special characters and IBM selected characters, use the code point
of NEC special characters.
• If the character is in both IBM selected characters and NEC selected—IBM extended characters,
use the code point of IBM extended characters.
The table shown at https://msdn.microsoft.com/en-us/goglobal/cc305152.aspx provides information
about the Unicode values of cp932 characters. For cp932 table entries with characters under which
a four-digit number appears, the number represents the corresponding Unicode (ucs2) encoding.
For table entries with an underlined two-digit value appears, there is a range of cp932 character
values that begin with those two digits. Clicking such a table entry takes you to a page that displays
the Unicode value for each of the cp932 characters that begin with those digits.
The following links are of special interest. They correspond to the encodings for the following sets of
characters:
• NEC special characters (lead byte 0x87):
https://msdn.microsoft.com/en-us/goglobal/gg674964

• NEC selected—IBM extended characters (lead byte 0xED and 0xEE):

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Character Sets and Collations That MySQL Supports

https://msdn.microsoft.com/en-us/goglobal/gg671837
https://msdn.microsoft.com/en-us/goglobal/gg671838

• IBM selected characters (lead byte 0xFA, 0xFB, 0xFC):
https://msdn.microsoft.com/en-us/goglobal/gg671839
https://msdn.microsoft.com/en-us/goglobal/gg671840
https://msdn.microsoft.com/en-us/goglobal/gg671841

• Starting from version 5.0.3, cp932 supports conversion of user-defined characters in combination
with eucjpms, and solves the problems with sjis/ujis conversion. For details, please refer to
http://www.opengroup.or.jp/jvc/cde/sjis-euc-e.html.
For some characters, conversion to and from ucs2 is different for sjis and cp932. The following
tables illustrate these differences.
Conversion to ucs2:
sjis/cp932 Value

sjis -> ucs2 Conversion

cp932 -> ucs2 Conversion

5C

005C

005C

7E

007E

007E

815C

2015

2015

815F

005C

FF3C

8160

301C

FF5E

8161

2016

2225

817C

2212

FF0D

8191

00A2

FFE0

8192

00A3

FFE1

81CA

00AC

FFE2

ucs2 value

ucs2 -> sjis Conversion

ucs2 -> cp932 Conversion

005C

815F

5C

007E

7E

7E

00A2

8191

3F

00A3

8192

3F

00AC

81CA

3F

2015

815C

815C

2016

8161

3F

2212

817C

3F

2225

3F

8161

301C

8160

3F

FF0D

3F

817C

FF3C

3F

815F

FF5E

3F

8160

FFE0

3F

8191

FFE1

3F

8192

FFE2

3F

81CA

Conversion from ucs2:

This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Setting the Error Message Language

Users of any Japanese character sets should be aware that using --character-set-clienthandshake (or --skip-character-set-client-handshake) has an important effect. See
Section 5.1.3, “Server Command Options”.

10.2 Setting the Error Message Language
By default, mysqld produces error messages in English, but they can also be displayed in any of
several other languages: Czech, Danish, Dutch, Estonian, French, German, Greek, Hungarian, Italian,
Japanese, Korean, Norwegian, Norwegian-ny, Polish, Portuguese, Romanian, Russian, Slovak,
Spanish, or Swedish.
You can select which language the server uses for error messages using the instructions in this
section.
To start mysqld with a particular language for error messages, use the --language or -L option. The
option value can be a language name or the full path to the error message file. For example:
shell> mysqld --language=swedish

Or:
shell> mysqld --language=/usr/local/share/swedish

The language name should be specified in lowercase.
By default, the language files are located in the share/mysql/LANGUAGE directory under the MySQL
base directory.
For information about changing the character set for error messages (rather than the language), see
Section 10.1.6, “Character Set for Error Messages”.
You can change the content of the error messages produced by the server using the instructions in
the MySQL Internals manual, available at MySQL Internals: Error Messages. If you do change the
content of error messages, remember to repeat your changes after each upgrade to a newer version of
MySQL.

10.3 Adding a Character Set
This section discusses the procedure for adding a character set to MySQL. The proper procedure
depends on whether the character set is simple or complex:
• If the character set does not need special string collating routines for sorting and does not need
multibyte character support, it is simple.
• If the character set needs either of those features, it is complex.
For example, greek and swe7 are simple character sets, whereas big5 and czech are complex
character sets.
To use the following instructions, you must have a MySQL source distribution. In the instructions,
MYSET represents the name of the character set that you want to add.
1. Add a  element for MYSET to the sql/share/charsets/Index.xml file. Use the
existing contents in the file as a guide to adding new contents. A partial listing for the latin1
 element follows:


This
documentation
is for an
older version.
If you're

This
documentation
is for an
older version.
If you're

Adding a Character Set

Western
cp1252 West European
...

primary
compiled


...

binary
compiled

...


The  element must list all the collations for the character set. These must include at
least a binary collation and a default (primary) collation. The default collation is often named using
a suffix of general_ci (general, case insensitive). It is possible for the binary collation to be the
default collation, but usually they are different. The default collation should have a primary flag.
The binary collation should have a binary flag.
You must assign a unique ID number to each collation, chosen from the range 1 to 254. To find the
maximum of the currently used collation IDs, use this query:
SELECT MAX(ID) FROM INFORMATION_SCHEMA.COLLATIONS;

2. This step depends on whether you are adding a simple or complex character set. A simple
character set requires only a configuration file, whereas a complex character set requires C source
file that defines collation functions, multibyte functions, or both.
For a simple character set, create a configuration file, MYSET.xml, that describes the character
set properties. Create this file in the sql/share/charsets directory. You can use a copy of
latin1.xml as the basis for this file. The syntax for the file is very simple:
• Comments are written as ordinary XML comments ().
• Words within