MySQL 5.0 Reference Manual

MySQL 5.0 Reference Manual
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/lifetime-support/
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 third-party
software that may be included in this Community release.
Document generated on: 2016-05-11 (revision: 47682)
Table of Contents
Preface and Legal Notices ............................................................................................................... xix
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 ............................................................................................... 12
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) .......................................... 15
1.6.4 MySQL Enterprise .................................................................................................... 15
1.7 How to Report Bugs or Problems ........................................................................................ 15
1.8 MySQL Standards Compliance ............................................................................................ 20
1.8.1 MySQL Extensions to Standard SQL ........................................................................ 21
1.8.2 MySQL Differences from Standard SQL .................................................................... 24
1.8.3 How MySQL Deals with Constraints ......................................................................... 29
1.9 Credits ............................................................................................................................... 33
1.9.1 Contributors to MySQL ............................................................................................. 33
1.9.2 Documenters and translators .................................................................................... 37
1.9.3 Packages that support MySQL ................................................................................. 39
1.9.4 Tools that were used to create MySQL ..................................................................... 39
1.9.5 Supporters of MySQL .............................................................................................. 40
2 Installing and Upgrading MySQL .................................................................................................... 41
2.1 MySQL Installation Overview ............................................................................................... 42
2.2 Determining Your Current MySQL Version ........................................................................... 42
2.3 Notes for MySQL Enterprise Server .................................................................................... 43
2.3.1 Enterprise Server Distribution Types ......................................................................... 44
2.3.2 Upgrading MySQL Enterprise Server ........................................................................ 44
2.4 Notes for MySQL Community Server ................................................................................... 44
2.4.1 Overview of MySQL Community Server Installation ................................................... 44
2.4.2 Choosing Which MySQL Distribution to Install ........................................................... 45
2.5 How to Get MySQL ............................................................................................................ 49
2.6 Verifying Package Integrity Using MD5 Checksums or GnuPG .............................................. 49
2.6.1 Verifying the MD5 Checksum ................................................................................... 49
2.6.2 Signature Checking Using GnuPG ............................................................................ 50
2.6.3 Signature Checking Using Gpg4win for Windows ...................................................... 53
2.6.4 Signature Checking Using RPM ............................................................................... 58
2.7 Installation Layouts ............................................................................................................. 59
2.8 Compiler-Specific Build Characteristics ................................................................................ 61
2.9 Standard MySQL Installation from a Binary Distribution ........................................................ 61
2.10 Installing MySQL on Microsoft Windows ............................................................................ 61
2.10.1 Choosing An Installation Package ........................................................................... 63
2.10.2 Installing MySQL on Microsoft Windows Using an MSI Package ............................... 63
2.10.3 MySQL Server Instance Configuration Wizard ......................................................... 70
2.10.4 Installing MySQL on Microsoft Windows Using a noinstall Zip Archive ....................... 81
2.10.5 Troubleshooting a MySQL Installation Under Windows ............................................. 90
2.10.6 Windows Postinstallation Procedures ...................................................................... 91
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.10.7 Upgrading MySQL on Windows .............................................................................. 93
2.10.8 Installing MySQL from Source on Windows ............................................................. 94
2.11 Installing MySQL on OS X ................................................................................................ 99
2.12 Installing MySQL on Linux Using RPM Packages ............................................................. 102
2.13 Installing MySQL on Solaris ............................................................................................ 106
2.14 Installing MySQL on i5/OS .............................................................................................. 106
2.15 Installing MySQL on NetWare ......................................................................................... 110
2.16 Installing MySQL on Unix/Linux Using Generic Binaries .................................................... 112
2.17 Installing MySQL from Source ......................................................................................... 115
2.17.1 Installing MySQL Using a Standard Source Distribution .......................................... 116
2.17.2 Installing MySQL Using a Development Source Tree ............................................. 119
2.17.3 MySQL Source-Configuration Options ................................................................... 122
2.17.4 Dealing with Problems Compiling MySQL .............................................................. 130
2.17.5 Compiling and Linking an Optimized mysqld Server ............................................... 133
2.18 Postinstallation Setup and Testing ................................................................................... 134
2.18.1 Initializing the Data Directory ................................................................................ 135
2.18.2 Starting the Server ............................................................................................... 138
2.18.3 Testing the Server ................................................................................................ 142
2.18.4 Securing the Initial MySQL Accounts .................................................................... 144
2.18.5 Starting and Stopping MySQL Automatically .......................................................... 148
2.19 Upgrading or Downgrading MySQL .................................................................................. 149
2.19.1 Upgrading MySQL ................................................................................................ 149
2.19.2 Downgrading MySQL ........................................................................................... 163
2.19.3 Checking Whether Tables or Indexes Must Be Rebuilt ........................................... 166
2.19.4 Rebuilding or Repairing Tables or Indexes ............................................................ 168
2.19.5 Copying MySQL Databases to Another Machine .................................................... 170
2.20 Operating System-Specific Notes ..................................................................................... 171
2.20.1 Linux Notes ......................................................................................................... 171
2.20.2 OS X Notes ......................................................................................................... 178
2.20.3 Solaris Notes ....................................................................................................... 178
2.20.4 BSD Notes ........................................................................................................... 182
2.20.5 Other Unix Notes ................................................................................................. 185
2.20.6 OS/2 Notes .......................................................................................................... 202
2.21 Environment Variables .................................................................................................... 203
2.22 Perl Installation Notes ..................................................................................................... 204
2.22.1 Installing Perl on Unix .......................................................................................... 205
2.22.2 Installing ActiveState Perl on Windows .................................................................. 206
2.22.3 Problems Using the Perl DBI/DBD Interface .......................................................... 206
3 Tutorial ........................................................................................................................................ 209
3.1 Connecting to and Disconnecting from the Server .............................................................. 209
3.2 Entering Queries ............................................................................................................... 210
3.3 Creating and Using a Database ........................................................................................ 213
3.3.1 Creating and Selecting a Database ......................................................................... 215
3.3.2 Creating a Table .................................................................................................... 215
3.3.3 Loading Data into a Table ...................................................................................... 217
3.3.4 Retrieving Information from a Table ........................................................................ 218
3.4 Getting Information About Databases and Tables ............................................................... 232
3.5 Using mysql in Batch Mode .............................................................................................. 233
3.6 Examples of Common Queries .......................................................................................... 235
3.6.1 The Maximum Value for a Column ......................................................................... 235
3.6.2 The Row Holding the Maximum of a Certain Column ............................................... 235
3.6.3 Maximum of Column per Group .............................................................................. 236
3.6.4 The Rows Holding the Group-wise Maximum of a Certain Column ............................ 236
3.6.5 Using User-Defined Variables ................................................................................. 237
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
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 ...................................................................................................
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 .....................
This
documentation
is for an
older version.
If you're
237
239
240
240
242
243
244
249
249
250
254
254
256
257
261
262
263
266
267
267
268
272
274
279
279
280
281
282
282
283
285
285
286
290
290
311
318
324
341
345
349
349
350
351
368
369
375
378
387
389
392
403
404
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 ..............................................
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 ..............................
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 .....................................................
This
documentation
is for an
older version.
If you're
404
405
405
406
408
409
409
410
410
411
412
413
413
414
414
417
417
418
439
439
466
556
566
586
594
594
595
596
597
598
598
600
600
604
605
606
607
608
611
613
615
616
616
617
625
627
628
629
630
631
632
636
641
643
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 ...............................................................................................
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 ...............................................................................
This
documentation
is for an
older version.
If you're
646
648
649
654
654
656
659
659
661
662
670
676
676
679
680
682
684
685
687
688
688
688
689
690
691
692
694
695
696
697
697
698
699
701
702
703
704
706
707
742
744
744
745
745
746
746
746
747
749
749
751
752
752
754
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 .........................................................................................
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 ..............................................................................
This
documentation
is for an
older version.
If you're
756
757
758
758
760
761
763
763
763
764
764
765
766
766
767
767
767
767
768
778
780
780
780
781
782
782
787
787
794
794
796
798
798
799
799
800
802
803
806
809
811
812
812
813
813
814
816
822
823
823
824
825
825
826
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 ...................................
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 ...............................................................................................................
This
documentation
is for an
older version.
If you're
829
829
829
832
832
834
835
835
836
836
838
838
840
843
849
852
854
857
857
858
859
860
868
870
872
872
880
882
885
886
887
889
899
900
902
903
904
904
905
906
907
908
912
913
915
917
918
921
922
922
926
927
931
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
11.2.1 Integer Types (Exact Value) - INTEGER, INT, SMALLINT, TINYINT, MEDIUMINT,
BIGINT ........................................................................................................................... 931
11.2.2 Fixed-Point Types (Exact Value) - DECIMAL, NUMERIC ........................................ 932
11.2.3 Floating-Point Types (Approximate Value) - FLOAT, DOUBLE ................................ 932
11.2.4 Bit-Value Type - BIT ............................................................................................ 933
11.2.5 Numeric Type Attributes ....................................................................................... 933
11.2.6 Out-of-Range and Overflow Handling .................................................................... 934
11.3 Date and Time Types ..................................................................................................... 935
11.3.1 The DATE, DATETIME, and TIMESTAMP Types ................................................... 937
11.3.2 The TIME Type .................................................................................................... 938
11.3.3 The YEAR Type ................................................................................................... 939
11.3.4 YEAR(2) Limitations and Migrating to YEAR(4) ...................................................... 939
11.3.5 Automatic Initialization and Updating for TIMESTAMP ............................................ 941
11.3.6 Fractional Seconds in Time Values ....................................................................... 944
11.3.7 Conversion Between Date and Time Types ........................................................... 944
11.3.8 Two-Digit Years in Dates ...................................................................................... 945
11.4 String Types ................................................................................................................... 946
11.4.1 The CHAR and VARCHAR Types ......................................................................... 946
11.4.2 The BINARY and VARBINARY Types ................................................................... 948
11.4.3 The BLOB and TEXT Types ................................................................................. 949
11.4.4 The ENUM Type .................................................................................................. 951
11.4.5 The SET Type ..................................................................................................... 953
11.5 Extensions for Spatial Data ............................................................................................. 955
11.5.1 Spatial Data Types ............................................................................................... 957
11.5.2 The OpenGIS Geometry Model ............................................................................. 958
11.5.3 Using Spatial Data ............................................................................................... 963
11.6 Data Type Default Values ............................................................................................... 971
11.7 Data Type Storage Requirements .................................................................................... 972
11.8 Choosing the Right Type for a Column ............................................................................ 976
11.9 Using Data Types from Other Database Engines .............................................................. 976
12 Functions and Operators ............................................................................................................ 979
12.1 Function and Operator Reference .................................................................................... 980
12.2 Type Conversion in Expression Evaluation ....................................................................... 989
12.3 Operators ....................................................................................................................... 991
12.3.1 Operator Precedence ........................................................................................... 992
12.3.2 Comparison Functions and Operators ................................................................... 993
12.3.3 Logical Operators ............................................................................................... 1000
12.3.4 Assignment Operators ........................................................................................ 1001
12.4 Control Flow Functions .................................................................................................. 1003
12.5 String Functions ............................................................................................................ 1005
12.5.1 String Comparison Functions .............................................................................. 1018
12.5.2 Regular Expressions ........................................................................................... 1021
12.6 Numeric Functions and Operators .................................................................................. 1027
12.6.1 Arithmetic Operators ........................................................................................... 1028
12.6.2 Mathematical Functions ...................................................................................... 1030
12.7 Date and Time Functions .............................................................................................. 1039
12.8 What Calendar Is Used By MySQL? .............................................................................. 1060
12.9 Full-Text Search Functions ............................................................................................ 1061
12.9.1 Natural Language Full-Text Searches .................................................................. 1062
12.9.2 Boolean Full-Text Searches ................................................................................ 1065
12.9.3 Full-Text Searches with Query Expansion ............................................................ 1067
12.9.4 Full-Text Stopwords ............................................................................................ 1068
12.9.5 Full-Text Restrictions .......................................................................................... 1071
12.9.6 Fine-Tuning MySQL Full-Text Search .................................................................. 1072
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
12.9.7 Adding a Collation for Full-Text Indexing .............................................................
12.10 Cast Functions and Operators .....................................................................................
12.11 Bit Functions and Operators ........................................................................................
12.12 Encryption and Compression Functions ........................................................................
12.13 Information Functions ..................................................................................................
12.14 Spatial Analysis Functions ...........................................................................................
12.14.1 Spatial Function Reference ...............................................................................
12.14.2 Argument Handling by Spatial Functions ............................................................
12.14.3 Functions That Create Geometry Values from WKT Values ................................
12.14.4 Functions That Create Geometry Values from WKB Values ................................
12.14.5 MySQL-Specific Functions That Create Geometry Values ...................................
12.14.6 Geometry Format Conversion Functions ............................................................
12.14.7 Geometry Property Functions ............................................................................
12.14.8 Spatial Operator Functions ................................................................................
12.14.9 Functions That Test Spatial Relations Between Geometry Objects ......................
12.15 Miscellaneous Functions ..............................................................................................
12.16 GROUP BY (Aggregate) Functions ..............................................................................
12.16.1 GROUP BY (Aggregate) Function Descriptions ..................................................
12.16.2 GROUP BY Modifiers .......................................................................................
12.16.3 MySQL Handling of GROUP BY .......................................................................
12.17 Precision Math ............................................................................................................
12.17.1 Types of Numeric Values ..................................................................................
12.17.2 DECIMAL Data Type Characteristics .................................................................
12.17.3 Expression Handling .........................................................................................
12.17.4 Rounding Behavior ...........................................................................................
12.17.5 Precision Math Examples ..................................................................................
13 SQL Statement Syntax .............................................................................................................
13.1 Data Definition Statements ............................................................................................
13.1.1 ALTER DATABASE Syntax ................................................................................
13.1.2 ALTER FUNCTION Syntax .................................................................................
13.1.3 ALTER PROCEDURE Syntax .............................................................................
13.1.4 ALTER TABLE Syntax ........................................................................................
13.1.5 ALTER VIEW Syntax ..........................................................................................
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 ..............................................................................
13.2 Data Manipulation Statements .......................................................................................
13.2.1 CALL Syntax ......................................................................................................
13.2.2 DELETE Syntax .................................................................................................
13.2.3 DO Syntax .........................................................................................................
13.2.4 HANDLER Syntax ..............................................................................................
This
documentation
is for an
older version.
If you're
1074
1075
1079
1081
1087
1095
1095
1097
1098
1098
1099
1100
1101
1106
1106
1109
1113
1113
1118
1121
1122
1123
1123
1125
1127
1127
1133
1134
1134
1134
1135
1135
1143
1144
1144
1144
1147
1153
1173
1175
1180
1181
1181
1181
1182
1182
1183
1183
1184
1185
1185
1187
1191
1191
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 ...............................................................................................
13.3 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 .................................................................................................
13.4 Replication Statements ..................................................................................................
13.4.1 SQL Statements for Controlling Master Servers ...................................................
13.4.2 SQL Statements for Controlling Slave Servers .....................................................
13.5 SQL Syntax for Prepared Statements ............................................................................
13.5.1 PREPARE Syntax ..............................................................................................
13.5.2 EXECUTE Syntax ..............................................................................................
13.5.3 DEALLOCATE PREPARE Syntax .......................................................................
13.6 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 .............................................................................................
13.7 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 .........................................................................
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 ............................................................
This
documentation
is for an
older version.
If you're
1193
1200
1210
1211
1228
1240
1242
1243
1245
1245
1246
1247
1252
1254
1258
1258
1260
1267
1270
1271
1271
1271
1271
1272
1273
1273
1275
1279
1281
1286
1286
1301
1309
1310
1313
1349
1354
1354
1355
1356
1358
1359
1362
1364
1366
1366
1369
1370
1371
1381
1405
1411
1411
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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 .................................................................
15.3.4 Getting memcached Statistics .............................................................................
15.3.5 memcached FAQ ...............................................................................................
16 Replication ...............................................................................................................................
16.1 Replication Configuration ...............................................................................................
16.1.1 How to Set Up Replication ..................................................................................
16.1.2 Replication and Binary Logging Options and Variables .........................................
16.1.3 Common Replication Administration Tasks ..........................................................
16.2 Replication Implementation ............................................................................................
16.2.1 Replication Implementation Details ......................................................................
16.2.2 Replication Relay and Status Logs ......................................................................
16.2.3 How Servers Evaluate Replication Filtering Rules ................................................
16.3 Replication Solutions .....................................................................................................
16.3.1 Using Replication for Backups ............................................................................
This
documentation
is for an
older version.
If you're
1412
1416
1417
1430
1431
1434
1436
1437
1449
1452
1455
1456
1458
1460
1461
1461
1462
1463
1465
1465
1466
1466
1467
1467
1469
1470
1471
1471
1475
1477
1478
1479
1480
1482
1484
1485
1485
1486
1487
1488
1508
1534
1543
1547
1548
1549
1558
1595
1598
1599
1600
1603
1609
1610
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
16.3.2 Using Replication with Different Master and Slave Storage Engines ......................
16.3.3 Using Replication for Scale-Out ..........................................................................
16.3.4 Replicating Different Databases to Different Slaves ..............................................
16.3.5 Improving Replication Performance .....................................................................
16.3.6 Switching Masters During Failover ......................................................................
16.3.7 Setting Up Replication to Use Secure Connections ..............................................
16.4 Replication Notes and Tips ............................................................................................
16.4.1 Replication Features and Issues .........................................................................
16.4.2 Replication Compatibility Between MySQL Versions .............................................
16.4.3 Upgrading a Replication Setup ............................................................................
16.4.4 Troubleshooting Replication ................................................................................
16.4.5 How to Report Replication Bugs or Problems ......................................................
17 MySQL Cluster ........................................................................................................................
17.1 MySQL Cluster Overview ..............................................................................................
17.1.1 MySQL Cluster Core Concepts ...........................................................................
17.1.2 MySQL Cluster Nodes, Node Groups, Replicas, and Partitions .............................
17.1.3 MySQL Cluster Hardware, Software, and Networking Requirements ......................
17.1.4 What is New in MySQL Cluster ...........................................................................
17.1.5 Known Limitations of MySQL Cluster ..................................................................
17.2 MySQL Cluster Installation and Upgrades ......................................................................
17.2.1 Installing MySQL Cluster on Linux ......................................................................
17.2.2 Initial Configuration of MySQL Cluster .................................................................
17.2.3 Initial Startup of MySQL Cluster ..........................................................................
17.2.4 MySQL Cluster Example with Tables and Data ....................................................
17.2.5 Safe Shutdown and Restart of MySQL Cluster .....................................................
17.2.6 Upgrading and Downgrading MySQL Cluster .......................................................
17.3 MySQL Cluster Configuration ........................................................................................
17.3.1 Quick Test Setup of MySQL Cluster ....................................................................
17.3.2 Overview of MySQL Cluster Configuration Parameters, Options, and Variables ......
17.3.3 MySQL Cluster Configuration Files ......................................................................
17.3.4 Using High-Speed Interconnects with MySQL Cluster ...........................................
17.4 MySQL Cluster Programs ..............................................................................................
17.4.1 ndbd — The MySQL Cluster Data Node Daemon ................................................
17.4.2 ndb_mgmd — The MySQL Cluster Management Server Daemon ..........................
17.4.3 ndb_mgm — The MySQL Cluster Management Client ...........................................
17.4.4 ndb_config — Extract MySQL Cluster Configuration Information ........................
17.4.5 ndb_cpcd — Automate Testing for NDB Development ........................................
17.4.6 ndb_delete_all — Delete All Rows from an NDB Table ...................................
17.4.7 ndb_desc — Describe NDB Tables ...................................................................
17.4.8 ndb_drop_index — Drop Index from an NDB Table ..........................................
17.4.9 ndb_drop_table — Drop an NDB Table ..........................................................
17.4.10 ndb_error_reporter — NDB Error-Reporting Utility ......................................
17.4.11 ndb_print_backup_file — Print NDB Backup File Contents .........................
17.4.12 ndb_print_schema_file — Print NDB Schema File Contents ........................
17.4.13 ndb_print_sys_file — Print NDB System File Contents ...............................
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 .....................................................................................
This
documentation
is for an
older version.
If you're
1612
1613
1614
1615
1616
1618
1620
1620
1632
1633
1634
1635
1637
1638
1640
1642
1644
1646
1647
1655
1658
1663
1665
1666
1669
1670
1672
1672
1675
1695
1749
1751
1751
1756
1759
1760
1765
1765
1766
1767
1769
1769
1770
1770
1771
1771
1777
1780
1781
1782
1783
1785
1789
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
17.5.1 Summary of MySQL Cluster Start Phases ........................................................... 1789
17.5.2 Commands in the MySQL Cluster Management Client ......................................... 1791
17.5.3 Online Backup of MySQL Cluster ........................................................................ 1791
17.5.4 MySQL Server Usage for MySQL Cluster ............................................................ 1795
17.5.5 Performing a Rolling Restart of a MySQL Cluster ................................................. 1797
17.5.6 Event Reports Generated in MySQL Cluster ........................................................ 1798
17.5.7 MySQL Cluster Log Messages ............................................................................ 1807
17.5.8 MySQL Cluster Single User Mode ....................................................................... 1822
17.5.9 Quick Reference: MySQL Cluster SQL Statements .............................................. 1823
17.5.10 MySQL Cluster Security Issues ......................................................................... 1825
18 Stored Programs and Views ..................................................................................................... 1833
18.1 Defining Stored Programs ............................................................................................. 1833
18.2 Using Stored Routines (Procedures and Functions) ........................................................ 1835
18.2.1 Stored Routine Syntax ........................................................................................ 1835
18.2.2 Stored Routines and MySQL Privileges ............................................................... 1836
18.2.3 Stored Routine Metadata .................................................................................... 1837
18.2.4 Stored Procedures, Functions, Triggers, and LAST_INSERT_ID() ......................... 1837
18.3 Using Triggers .............................................................................................................. 1837
18.3.1 Trigger Syntax and Examples ............................................................................. 1838
18.3.2 Trigger Metadata ................................................................................................ 1842
18.4 Using Views .................................................................................................................. 1842
18.4.1 View Syntax ....................................................................................................... 1842
18.4.2 View Processing Algorithms ................................................................................ 1843
18.4.3 Updatable and Insertable Views .......................................................................... 1844
18.4.4 The View WITH CHECK OPTION Clause ............................................................ 1846
18.4.5 View Metadata ................................................................................................... 1846
18.5 Access Control for Stored Programs and Views .............................................................. 1847
18.6 Binary Logging of Stored Programs ............................................................................... 1848
19 INFORMATION_SCHEMA Tables ............................................................................................ 1859
19.1 The INFORMATION_SCHEMA CHARACTER_SETS Table ............................................ 1861
19.2 The INFORMATION_SCHEMA COLLATIONS Table ....................................................... 1862
19.3 The INFORMATION_SCHEMA COLLATION_CHARACTER_SET_APPLICABILITY Table 1862
19.4 The INFORMATION_SCHEMA COLUMNS Table ........................................................... 1862
19.5 The INFORMATION_SCHEMA COLUMN_PRIVILEGES Table ........................................ 1863
19.6 The INFORMATION_SCHEMA KEY_COLUMN_USAGE Table ....................................... 1864
19.7 The INFORMATION_SCHEMA PROFILING Table .......................................................... 1865
19.8 The INFORMATION_SCHEMA ROUTINES Table .......................................................... 1866
19.9 The INFORMATION_SCHEMA SCHEMATA Table ......................................................... 1867
19.10 The INFORMATION_SCHEMA SCHEMA_PRIVILEGES Table ...................................... 1868
19.11 The INFORMATION_SCHEMA STATISTICS Table ....................................................... 1868
19.12 The INFORMATION_SCHEMA TABLES Table ............................................................. 1869
19.13 The INFORMATION_SCHEMA TABLE_CONSTRAINTS Table ...................................... 1870
19.14 The INFORMATION_SCHEMA TABLE_PRIVILEGES Table .......................................... 1870
19.15 The INFORMATION_SCHEMA TRIGGERS Table ........................................................ 1871
19.16 The INFORMATION_SCHEMA USER_PRIVILEGES Table ........................................... 1873
19.17 The INFORMATION_SCHEMA VIEWS Table ............................................................... 1873
19.18 Extensions to SHOW Statements ................................................................................. 1874
20 Connectors and APIs ............................................................................................................... 1877
20.1 MySQL Connector/ODBC .............................................................................................. 1880
20.2 MySQL Connector/Net .................................................................................................. 1881
20.3 MySQL Connector/J ...................................................................................................... 1881
20.4 MySQL Connector/C ..................................................................................................... 1881
20.5 libmysqld, the Embedded MySQL Server Library ............................................................ 1881
20.6 MySQL C API ............................................................................................................... 1882
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
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 .........................................................
A.5 MySQL 5.0 FAQ: Triggers ..............................................................................................
A.6 MySQL 5.0 FAQ: Views ..................................................................................................
This
documentation
is for an
older version.
If you're
1883
1884
1885
1885
1889
1894
1898
1950
1950
1957
1959
1983
1984
1985
1986
1987
1990
1990
1991
1991
1991
1992
1993
1993
1993
1993
1993
1995
1995
1995
1996
1997
1997
1998
2008
2010
2010
2017
2017
2021
2021
2022
2023
2023
2023
2024
2024
2025
2025
2027
2027
2028
2032
2034
This
documentation
is for an
older version.
If you're
MySQL 5.0 Reference Manual
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
2035
2035
2036
2037
2049
2062
2062
2067
2067
2067
2068
2106
2110
2110
2112
2125
2133
2142
2142
2143
2147
2147
2149
2150
2152
2154
2155
2155
2155
2155
2155
2157
2158
2159
2163
2239
2249
2275
2291
2293
2295
2299
2347
2353
2357
2389
2395
2411
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
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 error-free.
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 agencyspecific 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 International, Inc. AMD,
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Legal Notices
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 ....................................................................................................... 12
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) .................................................. 15
1.6.4 MySQL Enterprise ............................................................................................................ 15
1.7 How to Report Bugs or Problems ................................................................................................ 15
1.8 MySQL Standards Compliance .................................................................................................... 20
1.8.1 MySQL Extensions to Standard SQL ................................................................................ 21
1.8.2 MySQL Differences from Standard SQL ............................................................................ 24
1.8.3 How MySQL Deals with Constraints ................................................................................. 29
1.9 Credits ....................................................................................................................................... 33
1.9.1 Contributors to MySQL ..................................................................................................... 33
1.9.2 Documenters and translators ............................................................................................ 37
1.9.3 Packages that support MySQL ......................................................................................... 39
1.9.4 Tools that were used to create MySQL ............................................................................. 39
1.9.5 Supporters of MySQL ...................................................................................................... 40
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
<[email protected]>. 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Typographical and Syntax Conventions
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 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.
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
Database, table, and column names must often be substituted into statements. To indicate that such
substitution is necessary, this manual uses db_name, tbl_name, and col_name. For example, you might
see a statement like this:
mysql> SELECT col_name FROM db_name.tbl_name;
This means that if you were to enter a similar statement, you would supply your own database, table, and
column names, perhaps like this:
mysql> SELECT author_name FROM biblio_db.author_list;
SQL keywords are not case sensitive and may be written in 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?
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
What is MySQL?
MySQL, the most popular Open Source SQL database management system, is developed, distributed, and
supported by Oracle Corporation.
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-toone, 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.
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
Although under constant development, MySQL Server today offers a rich and useful set of functions.
Its connectivity, speed, and security make MySQL Server highly suited for accessing databases on the
Internet.
• MySQL Server works in client/server or embedded systems.
The MySQL Database Software is a client/server system that consists of a multi-threaded SQL server
that supports different backends, several different client programs and libraries, administrative tools, and
a wide range of application programming interfaces (APIs).
We also provide MySQL Server as an embedded multi-threaded library that you can link into your
application to get a smaller, faster, easier-to-manage 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.
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
• 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.
• 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.
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
• 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.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
History of MySQL
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 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:
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
• 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 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Development History
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
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Information Sources
Feature
MySQL Series
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.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Mailing Lists
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
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
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
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.
• <[email protected]>
A French mailing list.
• <[email protected]>
A Korean mailing list. To subscribe, email subscribe mysql [email protected] to this list.
• <[email protected]>
A German mailing list. To subscribe, email subscribe mysql-de [email protected] to this list.
You can find information about this mailing list at http://www.4t2.com/mysql/.
• <[email protected]>
A Portuguese mailing list. To subscribe, email subscribe mysql-br [email protected] to this
list.
• <[email protected]>
A Spanish mailing list. To subscribe, email subscribe mysql [email protected] to this list.
1.6.1.1 Guidelines for Using the Mailing Lists
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Community Support on Internet Relay Chat (IRC)
• 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
• 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:
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
• 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 <[email protected]>. 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 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.
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
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 platformdependent. In such cases, it is next to impossible for us to fix anything without knowing the operating
system and the version number of the platform.
If you compiled MySQL from source, remember also to provide information about your compiler if it is
related to the problem. Often people find bugs in compilers and think the problem is MySQL-related.
Most compilers are under development all the time and become better version by version. To determine
whether your problem depends on your compiler, we need to know what compiler you 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.
• 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.
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 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
<output from SHOW COLUMNS>
mysql> EXPLAIN SELECT ...\G
<output from EXPLAIN>
mysql> FLUSH STATUS;
mysql> SELECT ...;
<A short version of the output from SELECT,
including the time taken to run the query>
mysql> SHOW STATUS;
<output from SHOW STATUS>
• If a bug or problem occurs while running 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 README
file that describes your problem. Create a compressed archive of your files using tar and gzip or zip.
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
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Standards Compliance
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
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 nonSQL 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 terabyte-sized
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Selecting SQL Modes
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.
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 ...
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
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:
•
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.
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 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.
• 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
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
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;
• 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”.
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
• 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
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
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
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.
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.
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
• 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 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
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
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 selfreferential 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”.
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.
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
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.
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
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
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
> 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
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
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 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:
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
• 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.
• 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'.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Credits
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 <[email protected]> or <[email protected]>
The initial port to Win32/NT.
• Per Eric Olsson
For constructive criticism and real testing of the dynamic record format.
• Irena Pancirov <[email protected]>
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 <[email protected]>
mysqldump (previously msqldump, but ported and enhanced by Monty).
• Yuri Dario
For keeping up and extending the MySQL OS/2 port.
• Tim Bunce
Author of mysqlhotcopy.
• Zarko Mocnik <[email protected]>
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Contributors to MySQL
Sorting for Slovenian language.
• "TAMITO" <[email protected]>
The _MB character set macros and the ujis and sjis character sets.
• Joshua Chamas <[email protected]>
Base for concurrent insert, extended date syntax, debugging on NT, and answering on the MySQL
mailing list.
• Yves Carlier <[email protected]>
mysqlaccess, a program to show the access rights for a user.
• Rhys Jones <[email protected]> (And GWE Technologies Limited)
For one of the early JDBC drivers.
• Dr Xiaokun Kelvin ZHU <[email protected]>
Further development of one of the early JDBC drivers and other MySQL-related Java tools.
• James Cooper <[email protected]>
For setting up a searchable mailing list archive at his site.
• Rick Mehalick <[email protected]>
For xmysql, a graphical X client for MySQL Server.
• Doug Sisk <[email protected]>
For providing RPM packages of MySQL for Red Hat Linux.
• Diemand Alexander V. <[email protected]>
For providing RPM packages of MySQL for Red Hat Linux-Alpha.
• Antoni Pamies Olive <[email protected]>
For providing RPM versions of a lot of MySQL clients for Intel and SPARC.
• Jay Bloodworth <[email protected]>
For providing RPM versions for MySQL 3.21.
• David Sacerdote <[email protected]>
Ideas for secure checking of DNS host names.
• Wei-Jou Chen <[email protected]>
Some support for Chinese(BIG5) characters.
• Wei He <[email protected]>
A lot of functionality for the Chinese(GBK) character set.
• Jan Pazdziora <[email protected]>
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Contributors to MySQL
Czech sorting order.
• Zeev Suraski <[email protected]>
FROM_UNIXTIME() time formatting, ENCRYPT() functions, and bison advisor. Active mailing list
member.
• Luuk de Boer <[email protected]>
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 <[email protected]>
User-defined functions (UDFs); CREATE FUNCTION and DROP FUNCTION.
• Andreas F. Bobak <[email protected]>
The AGGREGATE extension to user-defined functions.
• Ross Wakelin <[email protected]>
Help to set up InstallShield for MySQL-Win32.
• Jethro Wright III <[email protected]>
The libmysql.dll library.
• James Pereria <[email protected]>
Mysqlmanager, a Win32 GUI tool for administering MySQL Servers.
• Curt Sampson <[email protected]>
Porting of MIT-pthreads to NetBSD/Alpha and NetBSD 1.3/i386.
• Martin Ramsch <[email protected]>
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Contributors to MySQL
• Jocelyn Fournier
Excellent spotting and reporting innumerable bugs (especially in the MySQL 4.1 subquery code).
• 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, <[email protected]>,
<[email protected]>, <[email protected]>, Ted Deppner <[email protected]>, 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 <[email protected]>
Irix setup.
• Luuk de Boer <[email protected]>
Benchmark questions.
• Tim Sailer <[email protected]>
DBD::mysql questions.
• Boyd Lynn Gerber <[email protected]>
SCO-related questions.
• Richard Mehalick <[email protected]>
xmysql-related questions and basic installation questions.
• Zeev Suraski <[email protected]>
Apache module configuration questions (log & auth), PHP-related questions, SQL syntax-related
questions and other general questions.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Documenters and translators
• Francesc Guasch <[email protected]>
General questions.
• Jonathan J Smith <[email protected]>
Questions pertaining to OS-specifics with Linux, SQL syntax, and other things that might need some
work.
• David Sklar <[email protected]>
Using MySQL from PHP and Perl.
• Alistair MacDonald <[email protected]>
Is flexible and can handle Linux and perhaps HP-UX.
• John Lyon <[email protected]>
Questions about installing MySQL on Linux systems, using either .rpm files or compiling from source.
• Lorvid Ltd. <[email protected]>
Simple billing/license/support/copyright issues.
• Patrick Sherrill <[email protected]>
ODBC and VisualC++ interface questions.
• Randy Harmon <[email protected]>
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. <[email protected]>
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 <[email protected]>
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Documenters and translators
Big parts of the Perl DBI/DBD section in the manual.
• Paul Southworth <[email protected]>, Ray Loyzaga <[email protected]>
Proof-reading of the Reference Manual.
• Therrien Gilbert <[email protected]>, Jean-Marc Pouyot <[email protected]>
French error messages.
• Petr Snajdr, <[email protected]>
Czech error messages.
• Jaroslaw Lewandowski <[email protected]>
Polish error messages.
• Miguel Angel Fernandez Roiz
Spanish error messages.
• Roy-Magne Mo <[email protected]>
Norwegian error messages and testing of MySQL 3.21.xx.
• Timur I. Bakeyev <[email protected]>
Russian error messages.
• <[email protected]> & Filippo Grassilli <[email protected]>
Italian error messages.
• Dirk Munzinger <[email protected]>
German error messages.
• Billik Stefan <[email protected]>
Slovak error messages.
• Stefan Saroiu <[email protected]>
Romanian error messages.
• Peter Feher
Hungarian error messages.
• Roberto M. Serqueira
Portuguese error messages.
• Carsten H. Pedersen
Danish error messages.
• Arjen Lentz
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Packages that support MySQL
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 <[email protected]>
For the Perl interface for MySQL Server.
• Jochen Wiedmann <[email protected]>
For maintaining the Perl DBD::mysql module.
• Eugene Chan <[email protected]>
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 <[email protected]>
For porting iODBC (Unix ODBC).
• Xavier Leroy <[email protected]>
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Supporters of 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.
• 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 ...................................................................................................... 42
2.2 Determining Your Current MySQL Version ................................................................................... 42
2.3 Notes for MySQL Enterprise Server ............................................................................................ 43
2.3.1 Enterprise Server Distribution Types ................................................................................. 44
2.3.2 Upgrading MySQL Enterprise Server ................................................................................ 44
2.4 Notes for MySQL Community Server ........................................................................................... 44
2.4.1 Overview of MySQL Community Server Installation ........................................................... 44
2.4.2 Choosing Which MySQL Distribution to Install ................................................................... 45
2.5 How to Get MySQL .................................................................................................................... 49
2.6 Verifying Package Integrity Using MD5 Checksums or GnuPG ...................................................... 49
2.6.1 Verifying the MD5 Checksum ........................................................................................... 49
2.6.2 Signature Checking Using GnuPG .................................................................................... 50
2.6.3 Signature Checking Using Gpg4win for Windows .............................................................. 53
2.6.4 Signature Checking Using RPM ....................................................................................... 58
2.7 Installation Layouts ..................................................................................................................... 59
2.8 Compiler-Specific Build Characteristics ........................................................................................ 61
2.9 Standard MySQL Installation from a Binary Distribution ................................................................ 61
2.10 Installing MySQL on Microsoft Windows .................................................................................... 61
2.10.1 Choosing An Installation Package ................................................................................... 63
2.10.2 Installing MySQL on Microsoft Windows Using an MSI Package ....................................... 63
2.10.3 MySQL Server Instance Configuration Wizard ................................................................. 70
2.10.4 Installing MySQL on Microsoft Windows Using a noinstall Zip Archive ............................... 81
2.10.5 Troubleshooting a MySQL Installation Under Windows ..................................................... 90
2.10.6 Windows Postinstallation Procedures .............................................................................. 91
2.10.7 Upgrading MySQL on Windows ...................................................................................... 93
2.10.8 Installing MySQL from Source on Windows ..................................................................... 94
2.11 Installing MySQL on OS X ........................................................................................................ 99
2.12 Installing MySQL on Linux Using RPM Packages ..................................................................... 102
2.13 Installing MySQL on Solaris .................................................................................................... 106
2.14 Installing MySQL on i5/OS ...................................................................................................... 106
2.15 Installing MySQL on NetWare ................................................................................................. 110
2.16 Installing MySQL on Unix/Linux Using Generic Binaries ............................................................ 112
2.17 Installing MySQL from Source ................................................................................................. 115
2.17.1 Installing MySQL Using a Standard Source Distribution .................................................. 116
2.17.2 Installing MySQL Using a Development Source Tree ..................................................... 119
2.17.3 MySQL Source-Configuration Options ........................................................................... 122
2.17.4 Dealing with Problems Compiling MySQL ...................................................................... 130
2.17.5 Compiling and Linking an Optimized mysqld Server ....................................................... 133
2.18 Postinstallation Setup and Testing ........................................................................................... 134
2.18.1 Initializing the Data Directory ........................................................................................ 135
2.18.2 Starting the Server ....................................................................................................... 138
2.18.3 Testing the Server ....................................................................................................... 142
2.18.4 Securing the Initial MySQL Accounts ............................................................................ 144
2.18.5 Starting and Stopping MySQL Automatically .................................................................. 148
2.19 Upgrading or Downgrading MySQL .......................................................................................... 149
2.19.1 Upgrading MySQL ........................................................................................................ 149
2.19.2 Downgrading MySQL ................................................................................................... 163
2.19.3 Checking Whether Tables or Indexes Must Be Rebuilt ................................................... 166
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Installation Overview
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 ..................................................................
168
170
171
171
178
178
182
185
202
203
204
205
206
206
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:
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 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:
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
[email protected]
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 secon
2.3 Notes for MySQL Enterprise Server
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Enterprise Server Distribution Types
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.
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.
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
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”.
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
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
• 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 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.
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
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.
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.
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
• 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
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!)
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
How to Get MySQL
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”.
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Signature Checking Using GnuPG
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. 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 [email protected] 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Signature Checking Using GnuPG
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
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Signature Checking Using GnuPG
shell> gpg --import mysql_pubkey.asc
gpg: key 5072E1F5: public key "MySQL Release Engineering
<[email protected]>" 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 <[email protected]>"
1 new user ID
gpg: key 5072E1F5: "MySQL Release Engineering <[email protected]>"
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 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 <[email protected]>"
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
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
gpg: Good signature from "MySQL Release Engineering <[email protected]>"
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:
Figure 2.1 Initial screen after loading Kleopatra
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
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 our
certificate, as otherwise you might not be able to verify our signature. Select I believe checks are very
accurate and then press OK.
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.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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installation Layouts
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 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installation Layouts
Directory
Contents of Directory
/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
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 SourceConfiguration 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Compiler-Specific Build Characteristics
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
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”.
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
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”.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Choosing An Installation Package
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 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.
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
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”.
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.
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
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:
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
\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. 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”.
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 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.
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.
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
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"
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.
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.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.
• 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
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
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
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.
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 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.
• 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.
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.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.
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 drop-down 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 dropdown 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.
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 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.
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.
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 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 mytemplate.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.
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:
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
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%
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”.
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
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 i386class 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.
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:
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
• 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: The first specified datafile c:\ibdata\ibdata1 did not exist:
InnoDB: a new database to be created!
InnoDB: Setting file c:\ibdata\ibdata1 size to 209715200
InnoDB: Database physically writes the file full: wait...
InnoDB: Log file c:\iblogs\ib_logfile0 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile0 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile1 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile1 size to 31457280
InnoDB: Log file c:\iblogs\ib_logfile2 did not exist: new to be created
InnoDB: Setting log file c:\iblogs\ib_logfile2 size to 31457280
InnoDB: Doublewrite buffer not found: creating new
InnoDB: Doublewrite buffer created
InnoDB: creating foreign key constraint system tables
InnoDB: foreign key constraint system tables created
011024 10:58:25 InnoDB: Started
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
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.
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.
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
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:
shell> "C:\Program Files\MySQL\MySQL Server 5.0\bin\mysqladmin"
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
-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.
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 use of a single option other than --defaults-file is possible but discouraged. --defaultsfile is more flexible because it enables you to specify multiple startup options for the server by placing
them in the named option file. Also, in MySQL 5.0, use of an option different from --defaults-file is
not supported until 5.0.3.
• 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 --localservice 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 --defaults-file
option had been given, this command would have the effect of causing the server to read the [mysqld]
group from the standard option files. However, because the --defaults-file option is present, the
server reads options from the [mysqld] option group, 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
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 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.
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”.
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
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”.
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]
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Windows Postinstallation Procedures
# 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:
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Windows Postinstallation Procedures
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
+--------------------+
|
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
|
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL on Windows
| 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 CommandLine Tool”, and Section 4.5.6, “mysqlshow — Display Database, Table, and Column Information”.
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:
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
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”.
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.
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
• 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”.
• 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.
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
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.
• 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.
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
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.
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:
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
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:
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,
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
“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 --vsconfig 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 toplevel directory of your source tree:
shell> ./scripts/make_win_src_distribution
This script creates a Windows source package to be used on your Windows system.
You can supply different options to the script based on your needs. 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.
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
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.
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.
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
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.
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
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
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”.
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.
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
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
The shared libraries for older releases, up to the current release. It contains single-threaded and threadsafe libraries. Install this package instead of MySQL-shared if you have applications installed that are
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
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 platform-independent
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installing MySQL on Solaris
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 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
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
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”.
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
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
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.
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.
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
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.
• 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-power6
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.
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. 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.
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installing MySQL on NetWare
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.
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
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
If you are running MySQL on NetWare 6.0, we strongly suggest that you use the --skip-externallocking 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:
*<NLM has terminated; Press any key to close the screen>*
If you want NetWare to close the screen automatically instead, use the --autoclose option to
mysqld_safe. For example:
#Starts the MySQL 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”.
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Create a mysql User and Group
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>
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
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Obtain and Unpack the Distribution
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.
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installing MySQL from Source
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 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:
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
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 &
# 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:
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
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.
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:
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
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
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.
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
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/.
• automake 1.8.1, available from http://www.gnu.org/software/automake/.
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
• 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-tcpThis
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
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”.
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
--disable-libtool-lock
Disable libtool lock
--disable-profiling
Build a version without query
profiling code
--enable-FEATURE
Enable FEATURE
This
documentation
is for an
older version.
If you're
IntroducedRemoved
PREFIX/share
5.0.82
5.0.34
5.0.37
5.0.45
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
Formats
Description
--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
yes
--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 ..
This
documentation
is for an
older version.
If you're
Default
IntroducedRemoved
/usr/include
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
Formats
Description
Default
--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
--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
--with-blackholestorage-engine
Enable the Blackhole Storage
Engine
--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)
--with-embedded-server
Build the embedded server
--with-examplestorage-engine
Enable the Example Storage
Engine
--with-extra-charsets
Use charsets in addition to
default
--with-gnu-ld
Assume the C compiler uses
GNU ld
--with-isam
Enable the ISAM table type
--with-lib-ccflags
Extra CC options for libraries
This
documentation
is for an
older version.
If you're
IntroducedRemoved
5.0.4
no
5.0.4
yes
5.0.6
no
no
5.0.2
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
Formats
Description
--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
indexes per table
--with-mit-threads
Always use included thread lib
--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 Build if server
is built
--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
handler
--with-openssl
Include the OpenSSL support
--with-opensslincludes
Find OpenSSL headers in DIR
This
documentation
is for an
older version.
If you're
Default
IntroducedRemoved
5.0.44
64
5.0.4
5.0.44
5.0.3
5.0.3
5.0.3
5.0.2
no
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
Formats
Description
--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
--with-server-suffix
Append value to the version
string
--with-system-type
Set the system type, like "sunsolaris10"
--with-tags
Include additional
configurations
automatic
--with-tcp-port
Which port to use for MySQL
services
3306
--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
This
documentation
is for an
older version.
If you're
Default
IntroducedRemoved
Use both
5.0.3
5.0.44
5.0.2
5.0.6
5.0.48
5.0.3
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
Formats
Description
--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
Default
IntroducedRemoved
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.
•
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
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
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Source-Configuration Options
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
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
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
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
32 2
rather than unsigned long. This enables tables to hold up to approximately 1.844E+19 ((2 ) ) rows
32
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.
• 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 rerunning configure:
shell> rm config.cache
shell> make clean
Alternatively, you can run make distclean.
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
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 --with-lowmemory 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.
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>
This
documentation
is for an
older version.
If you're
CC=gcc
CFLAGS=-O3
CXX=gcc
CXXFLAGS=-O3
export CC CFLAGS CXX CXXFLAGS
This
documentation
is for an
older version.
If you're
Dealing with Problems Compiling MySQL
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
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 recreate 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.
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
• 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.
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.)
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Postinstallation Setup and Testing
• 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 --with-debug
(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 --skipsafemalloc 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”.
• 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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Initializing the Data Directory
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.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Initializing the Data Directory
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 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Initializing the Data Directory
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:
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Starting the Server
•
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 can
use to test whether the server is accessible and working properly, see Section 2.18.3, “Testing the Server”.
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're
Starting 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Starting the Server
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 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Starting the Server
Change location into the data directory and check the ownership of the data directory and its contents to
make sure the server has access. For example, if the data directory is /usr/local/mysql/var, use this
command:
shell> ls -la /usr/local/mysql/var
If the data directory or its files or subdirectories are not owned by the 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-no-recover.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Testing the Server
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.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Testing the Server
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:
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
|
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
+------+-----------+
| 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
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.
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, 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.
• 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
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
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:
• 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:
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
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.
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)
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
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.
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading or Downgrading MySQL
• 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”.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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 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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
• 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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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:
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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 --print-defaults). 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 builtin 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.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
• 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 mysqldmax 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 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).
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
• 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
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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);
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
This
This
documentation
documentation
is for an
is for an
older version.
older version.
If you're
If you're
Upgrading MySQL
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 welldefined, 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”.
• 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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' |
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
+----------------------+
|
0 |
+----------------------+
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 |
+----------------------+
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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 versionspecific:
• 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Upgrading MySQL
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:
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Downgrading MySQL
• 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
• 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Downgrading MySQL
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, “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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Downgrading MySQL
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.
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.
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
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'
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.
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 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
• 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”.
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
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
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.
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
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;
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:
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
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:
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Operating System-Specific Notes
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 flush-privileges
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 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Linux Notes
-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 resource-unavailable 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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Linux Notes
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 </tmp/linuxthreads-2.2.2.patch. We
hope it is included in some form in future releases of glibc 2.2. In any case, if you link against glibc
2.2.2, you still need to correct STACK_SIZE and PTHREAD_THREADS_MAX. We hope that the defaults is
corrected to some more acceptable values for high-load MySQL setup in the future, so that the commands
needed to produce your own build can be reduced to ./configure; make; make install.
If you use these patches to build a special static version of libpthread.a, use it only for statically
linking against MySQL. We know that these patches are safe for MySQL and significantly improve its
performance, but we cannot say anything about their effects on other applications. If you link other
applications that require LinuxThreads against the patched static version of the library, or build a patched
shared version and install it on your system, you do so at your own risk.
If you experience any strange problems during the installation of MySQL, or with some common utilities
hanging, it is very likely that they are either library or compiler related. If this is the case, using our binary
resolves them.
If you link your own MySQL client programs, you may see the following error at runtime:
ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory
This problem can be avoided by one of the following methods:
• Link clients with the -Wl,r/full/path/to/libmysqlclient.so flag rather than with -Lpath).
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Linux Notes
• 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 are using the Fujitsu compiler (fcc/FCC), you may have some problems compiling MySQL because
the Linux header files are very gcc oriented. The following configure line should work with fcc/FCC:
CC=fcc CFLAGS="-O -K fast -K lib -K omitfp -Kpreex -D_GNU_SOURCE \
-DCONST=const -DNO_STRTOLL_PROTO" \
CXX=FCC CXXFLAGS="-O -K fast -K lib \
-K omitfp -K preex --no_exceptions --no_rtti -D_GNU_SOURCE \
-DCONST=const -Dalloca=__builtin_alloca -DNO_STRTOLL_PROTO \
'-D_EXTERN_INLINE=static __inline'" \
./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static --disable-shared \
--with-low-memory
2.20.1.4 Linux Postinstallation Notes
mysql.server can be found in the support-files directory under the MySQL installation directory
or in a MySQL source tree. You can install it as /etc/init.d/mysql for automatic MySQL startup and
shutdown. See Section 4.3.3, “mysql.server — MySQL Server Startup Script”.
If MySQL cannot open enough files or connections, it may be that you have not configured Linux to handle
enough files.
In Linux 2.2 and onward, you can check the number of allocated file handles as follows:
shell> cat /proc/sys/fs/file-max
shell> cat /proc/sys/fs/dquot-max
shell> cat /proc/sys/fs/super-max
If you have more than 16MB of memory, you should add something like the following to your init scripts (for
example, /etc/init.d/boot.local on SuSE Linux):
echo 65536 > /proc/sys/fs/file-max
echo 8192 > /proc/sys/fs/dquot-max
echo 1024 > /proc/sys/fs/super-max
You can also run the echo commands from the command line as root, but these settings are lost the next
time your computer restarts.
Alternatively, you can set these parameters on startup by using the sysctl tool, which is used by many
Linux distributions (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:
[mysqld_safe]
open-files-limit=8192
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Linux Notes
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/linux-fork.patch. We have done rather extensive
testing of this patch on both development and production systems. It has significantly improved MySQL
performance without causing any problems and 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.
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.7 Linux Alpha Notes
We have tested MySQL 5.0 on Alpha with our benchmarks and test suite, and it appears to work well.
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
OS X Notes
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.
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-thread-priority
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Solaris Notes
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:
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 --enableassembler from the configure line.
In the MySQL benchmarks, we obtained a 4% speed increase on UltraSPARC when using Forte 5.0 in 32bit 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Solaris Notes
For compilers older than WorkShop 5.3, you might have to edit the configure script. Change this line:
#if !defined(__STDC__) || __STDC__ != 1
To this:
#if !defined(__STDC__)
If you turn on __STDC__ with the -Xc option, the Sun compiler can't compile with the Solaris pthread.h
header file. This is a Sun bug (broken compiler or broken include file).
If mysqld issues the following error message when you run it, you have tried to compile MySQL with the
Sun compiler without enabling the -mt multi-thread option:
libc internal error: _rmutex_unlock: rmutex not held
Add -mt to CFLAGS and CXXFLAGS and recompile.
If you are using the SFW version of gcc (which comes with Solaris 8), you must add /opt/sfw/lib to
the environment variable LD_LIBRARY_PATH before running configure.
If you are using the gcc available from sunfreeware.com, you may have many problems. To avoid this,
you should recompile gcc and GNU binutils on the machine where you are running them.
If you get the following error when compiling MySQL with gcc, it means that your gcc is not configured for
your version of Solaris:
shell> gcc -O3 -g -O2 -DDBUG_OFF -o thr_alarm ...
./thr_alarm.c: In function `signal_hand':
./thr_alarm.c:556: too many arguments to function `sigwait'
The proper thing to do in this case is to get the newest version of gcc and compile it with your current gcc
compiler. At least for Solaris 2.5, almost all binary versions of gcc have old, unusable include files that
break all programs that use threads, and possibly other programs 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Solaris Notes
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.
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):
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
BSD Notes
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.
• 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
BSD Notes
• 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:
• 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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
BSD Notes
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.
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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.
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 HP-UX
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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:
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)());
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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
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/.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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 -fno-exceptions
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:
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
#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 ----
#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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
./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 \
-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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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 \
--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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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
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
32768
9
4096
524288
1024
This
documentation
is for an
older version.
If you're
Other Unix Notes
STRMAXBLK
524288
NSTRPAGES
500
STRSPLITFRAC
80
NLOG
3
NUMSP
64
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
4096
0
50
3
1
1
1
524288
8000
100
3
256
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.
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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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().
• 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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).
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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
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
This
documentation
is for an
older version.
If you're
SDATLIM
HDATLIM
SVMMLIM
HVMMLIM
SFNOLIM
HFNOLIM
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
0x7FFFFFFF
2048
2048
This
documentation
is for an
older version.
If you're
Other Unix Notes
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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Other Unix Notes
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.
#
#
#
#
#
#
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
OS/2 Notes
# /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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Environment Variables
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”.
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.
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
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
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Installing Perl on Unix
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
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
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
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:
• 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.
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
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
LDFLAGS = -belf -L/usr/local/lib
LD = gcc -G -fpic
LDDLFLAGS = -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.
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
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 .......................................................................................................
209
210
213
215
215
217
218
232
233
235
235
235
236
236
237
237
239
240
240
242
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Entering Queries
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:
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
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.
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();
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Entering Queries
+----------------+
| VERSION()
|
+----------------+
| 5.0.7-beta-Max |
+----------------+
1 row in set (0.00 sec)
+---------------------+
| NOW()
|
+---------------------+
| 2005-07-11 17:59:36 |
+---------------------+
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 |
+---------------+--------------+
| [email protected] | 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 /*
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
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 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()
|
+---------------+
| [email protected] |
+---------------+
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
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
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
• 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:
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
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 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
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 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;
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
+---------------------+
| 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
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):
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
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:
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:
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;
+----------+--------+---------+------+------------+------------+
| 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.
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.
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
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 |
+-------+--------+---------+------+------------+-------+
| 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 |
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
| 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
|
+--------+---------+------------+
| 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:
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 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 |
| 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
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 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 |
+----------+------------+------------+------+
| 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 |
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
| 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.
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:
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 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:
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 0 IS NULL, 0 IS NOT NULL, '' IS NULL, '' IS NOT NULL;
+-----------+---------------+------------+----------------+
| 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 case-insensitive 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 |
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
+-------+--------+---------+------+------------+-------+
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:
• “.” 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
|
+----------+-------+---------+------+------------+------------+
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
|
| Bowser
| Diane | dog
| m
| 1989-08-31 | 1995-07-29 |
| Whistler | Gwen | bird
| NULL | 1997-12-09 | NULL
|
+----------+-------+---------+------+------------+------------+
Because a regular expression pattern matches if it occurs anywhere in the value, it is not necessary in the
previous query to put a wildcard on either side of the pattern to get it to match the entire value like it would
be if you used an SQL pattern.
To find names containing exactly five characters, use “^” and “$” to match the beginning and end of the
name, and five instances of “.” in between:
mysql> SELECT * FROM pet WHERE name REGEXP '^.....$';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
You could also write the previous query using the {n} (“repeat-n-times”) operator:
mysql> SELECT * FROM pet WHERE name REGEXP '^.{5}$';
+-------+--------+---------+------+------------+-------+
| name | owner | species | sex | birth
| death |
+-------+--------+---------+------+------------+-------+
| Claws | Gwen
| cat
| m
| 1994-03-17 | NULL |
| Buffy | Harold | dog
| f
| 1989-05-13 | NULL |
+-------+--------+---------+------+------------+-------+
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 |
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
| 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 |
| 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 |
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
| 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 |
+---------+------+----------+
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.
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
• 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
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)<RIGHT(birth,5)) AS age,
-> 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.
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
• 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 |
+--------+------+--------+------+---------+
| 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
|
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
| 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.
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.
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
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:
+---------+
| 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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Examples of Common Queries
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 |
|
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:
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Maximum of Column per Group
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 |
+---------+-------+
|
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 |
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using User-Defined Variables
+---------+--------+-------+
|
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 [email protected]_price OR [email protected]_price;
+---------+--------+-------+
| article | dealer | price |
+---------+--------+-------+
|
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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using Foreign Keys
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,
(NULL,
INTO shirt VALUES
'dress', 'orange', @last),
'polo', 'red', @last),
'dress', 'blue', @last),
't-shirt', 'white', @last);
SELECT * FROM person;
+----+---------------------+
| id | name
|
+----+---------------------+
| 1 | Antonio Paz
|
| 2 | Lilliana Angelovska |
+----+---------------------+
SELECT * FROM shirt;
+----+---------+--------+-------+
| id | style
| color | owner |
+----+---------+--------+-------+
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Searching on Two Keys
| 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”.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Calculating Visits Per Day
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<<day)) AS days FROM t1
GROUP BY year,month;
Which returns:
+------+-------+------+
| year | month | days |
+------+-------+------+
| 2000 |
01 |
3 |
| 2000 |
02 |
2 |
+------+-------+------+
The query calculates how many different days appear in the table for each year/month combination, with
automatic removal of duplicate entries.
3.6.9 Using AUTO_INCREMENT
The AUTO_INCREMENT attribute can be used to generate a unique identity for new rows:
CREATE TABLE animals (
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (id)
) ENGINE=MyISAM;
INSERT INTO animals (name) VALUES
('dog'),('cat'),('penguin'),
('lax'),('whale'),('ostrich');
SELECT * FROM animals;
Which returns:
+----+---------+
| id | name
|
+----+---------+
| 1 | dog
|
| 2 | cat
|
| 3 | penguin |
| 4 | lax
|
| 5 | whale
|
| 6 | ostrich |
+----+---------+
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using AUTO_INCREMENT
No value was specified for the AUTO_INCREMENT column, so MySQL assigned sequence numbers
automatically. You can also explicitly assign 0 to the column to generate sequence numbers. If the column
is declared NOT NULL, it is also possible to assign NULL to the column to generate sequence numbers.
When you insert any other value into a AUTO_INCREMENT column, the column is set to that value and
the sequence is reset so that the next automatically generated value follows sequentially from the largest
column value.
You can retrieve the most recent automatically generated AUTO_INCREMENT value with the
LAST_INSERT_ID() SQL function or the mysql_insert_id() C API function. These functions are
connection-specific, so their return values are not affected by another connection which is also performing
inserts.
Use a large enough integer data type for the AUTO_INCREMENT column to hold the maximum sequence
value you will need. When the column reaches the upper limit of the data type, the next attempt to
generate a sequence number fails. For example, if you use TINYINT, the maximum permissible sequence
number is 127. For TINYINT UNSIGNED, the maximum is 255.
Note
For a multiple-row insert, LAST_INSERT_ID() and mysql_insert_id() actually
return the AUTO_INCREMENT key from the first of the inserted rows. This enables
multiple-row inserts to be reproduced correctly on other servers in a replication
setup.
For MyISAM and BDB tables you can specify AUTO_INCREMENT on a secondary column in a multiplecolumn index. In this case, the generated value for the AUTO_INCREMENT column is calculated as
MAX(auto_increment_column) + 1 WHERE prefix=given-prefix. This is useful when you want
to put data into ordered groups.
CREATE TABLE animals (
grp ENUM('fish','mammal','bird') NOT NULL,
id MEDIUMINT NOT NULL AUTO_INCREMENT,
name CHAR(30) NOT NULL,
PRIMARY KEY (grp,id)
) ENGINE=MyISAM;
INSERT INTO animals (grp,name) VALUES
('mammal','dog'),('mammal','cat'),
('bird','penguin'),('fish','lax'),('mammal','whale'),
('bird','ostrich');
SELECT * FROM animals ORDER BY grp,id;
Which returns:
+--------+----+---------+
| grp
| id | name
|
+--------+----+---------+
| fish
| 1 | lax
|
| mammal | 1 | dog
|
| mammal | 2 | cat
|
| mammal | 3 | whale
|
| bird
| 1 | penguin |
| bird
| 2 | ostrich |
+--------+----+---------+
In this case (when the AUTO_INCREMENT column is part of a multiple-column index), AUTO_INCREMENT
values are reused if you delete the row with the biggest AUTO_INCREMENT value in any group. This
happens even for MyISAM tables, for which AUTO_INCREMENT values normally are not reused.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using MySQL with Apache
If the AUTO_INCREMENT column is part of multiple indexes, MySQL will generate sequence values using
the index that begins with the AUTO_INCREMENT column, if there is one. For example, if the animals
table contained indexes PRIMARY KEY (grp, id) and INDEX (id), MySQL would ignore the
PRIMARY KEY for generating sequence values. As a result, the table would contain a single sequence, not
a sequence per grp value.
To start with an AUTO_INCREMENT value other than 1, you can set that value with CREATE TABLE or
ALTER TABLE, like this:
mysql> 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 ............................................
This
documentation
is for an
older version.
If you're
244
249
249
250
254
254
256
257
261
262
263
266
267
267
268
272
274
279
279
280
281
282
282
283
285
285
286
290
290
311
318
324
341
345
349
349
350
351
368
369
375
378
387
389
392
403
404
404
This
documentation
is for an
older version.
If you're
Overview of MySQL Programs
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 ......................................................
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 ......................................
405
405
406
408
409
409
410
410
411
412
413
413
414
414
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
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. 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
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
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Overview of MySQL Programs
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
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
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 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”.
• 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
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 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 case-sensitive 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”.
• 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using MySQL Programs
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
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”.
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
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.
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.
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
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.
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):
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
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
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.
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
--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:
• 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”.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Specifying Program Options
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.
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.)
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
• 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 uppercase
2
3
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
|
|
| 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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Program Option Modifiers
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
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using Option Files
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 Global options
%\my.cnf
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%
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).
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using Option Files
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 server-specific
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.
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using Option Files
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"
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.
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Using Option Files
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
There is no guarantee about the order in which the option files in the directory will be read.
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
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
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
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 -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 or lowercase)
2
3
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:
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 --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 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() |
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
+----------------+
| [email protected]%
|
+----------------+
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:
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 myerrors.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:
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> 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'.
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
Setting Environment Variables
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()
|
+---------------+
| [email protected] |
+---------------+
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
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
mysql> SELECT USER();
+---------------+
| USER()
|
+---------------+
| [email protected]
|
+---------------+
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:
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 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:
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.
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
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 mysqld-max server.
If you perform such an upgrade, you should manually remove the old mysqld-max server to ensure that
mysqld_safe runs the new mysqld server.
To override the default behavior and specify explicitly 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 --logerror 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
This
documentation
is for an
older version.
If you're
Introduced
This
documentation
is for an
older version.
If you're
mysqld_safe — MySQL Server Startup Script
Format
Description
--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
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:
*<NLM has terminated; Press any key to close the screen>*
If you want NetWare to close the screen automatically instead, use the --autoclose option to
mysqld_safe.
•
--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.
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
•
--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
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.
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
•
--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).
• 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
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
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.
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 support-files
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:
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
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:
[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.
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
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 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
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
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.
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
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
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
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
the process terminates due to a signal sent using kill -9 or for other reasons, such as a segmentation
fault. Please note that the mysqld_safe script might require that you start it from a certain place. This
means that you might have to change location to a certain directory before running mysqld_multi. If
you have problems starting, please see the mysqld_safe script. Check especially the lines:
---------------------------------------------------------------MY_PWD=`pwd`
# Check if we are starting this relative (for the binary release)
if test -d $MY_PWD/data/mysql -a -f ./share/mysql/english/errmsg.sys -a \
-x ./bin/mysqld
----------------------------------------------------------------
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Installation-Related Programs
[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
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.
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
•
--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
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.
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
•
--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).
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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
mysqlbug — Generate Bug Report
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).
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:
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
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.
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.
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
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 OptionFile 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.
• --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.
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
•
--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.
• 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”.
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_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.
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:
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
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 timeconsuming, 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.
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
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
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.
•
--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.
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
•
--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, “EndUser 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.
•
--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
This
documentation
is for an
older version.
If you're
This
documentation
is for an
older version.
If you're
MySQL Client Programs
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
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”.
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
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
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.52
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
Introduced
--i-am-a-dummy, --safe-updates 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
This
documentation
is for an
older version.
If you're
5.0.6
5.0.23
This
documentation
is for an
older version.
If you're
mysql — The MySQL Command-Line Tool
Format
Description
--table
Display output in tabular format
--tee
Append a copy of output to named file
--unbuffered
Flush the buffer after each query
--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
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 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 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.
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
•
--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
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
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 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:
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 --skippager. 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, “EndUser 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
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
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
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 --skip-reconnect.
•
--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
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 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
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.
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
•
--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.
•
--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
<field name="column_name">NULL</field>
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%'"
<?xml version="1.0"?>
<resultset statement="SHOW VARIABLES LIKE 'version%'" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instanc
<row>
<field name="Variable_name">version</field>
<field name="Value">5.0.40-debug</field>
</row>
<row>
<field name="Variable_name">version_comment</field>
<field name="Value">Source distribution</field>
</row>
<row>
<field name="Variable_name">version_compile_machine</field>
<field name="Value">i686</field>
</row>
<row>
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
<field name="Variable_name">version_compile_os</field>
<field name="Value">suse-linux-gnu</field>
</row>
</resultset>
(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
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.
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
system
tee
(\!) Execute a system shell command.
(\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 serverside 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 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.
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
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
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.
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
•
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
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:
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> 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 left-arrow and
right-arrow keys. You can also use -S interactively within less to switch the horizontal-browse mode on
and off. For more information, read the less manual page:
shell> man less
• 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 builtin tee command is that the built-in tee works even if you do not have the Unix tee available. The builtin 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
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
Option
Description
\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 [email protected]_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="(\[email protected]\h) [\d]> "
• Use a command-line option. You can set the --prompt option on the command line to mysql. For
example:
shell> mysql --prompt="(\[email protected]\h) [\d]> "
([email protected]) [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=(\\[email protected]\\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:
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]
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 (\[email protected]\h) [\d]>\_
PROMPT set to '(\[email protected]\h) [\d]>\_'
([email protected]) [database]>
([email protected]) [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:
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”.
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
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 server-side
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 <item>', where <item> 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 <item>',
where <item> 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:
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> 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 <item>',
where <item> 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 '<info_to_display>' AS ' ';
The statement shown outputs <info_to_display>.
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
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
*************************** 1. row ***************************
msg_nro: 3068
date: 2000-03-01 23:29:50
time_zone: +0200
mail_from: Monty
reply: [email protected]
mail_to: "Thimble Smith" <[email protected]>
sbj: UTF-8
txt: >>>>> "Thimble" == Thimble Smith writes:
Thimble> Hi. I think this is a good idea. Is anyone familiar
Thimble> with UTF-8 or Unicode? Otherwise, I'll put this on my
Thimble> TODO list and see what happens.
Yes, please do that.
Regards,
Monty
file: inbox-jani-1
hash: 190402944
1 row in set (0.09 sec)
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 --safeupdates, 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
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
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;
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
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
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).
• 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) password-hashing
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.
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
• 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
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
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 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
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
This
documentation
is for an
older version.
If you're
Introduced
This
documentation
is for an
older version.
If you're
mysqladmin — Client for Administering a MySQL Server
Format
Description
Introduced
--defaults-group-suffix
Option group suffix value
5.0.10
--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
--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
•
5.0.23
--help, -?
Display a help message and exit.
•
--character-sets-dir=dir_name
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 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.
•
--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.
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
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.
•
--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.
•
--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.
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
•
--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 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 --alldatabases 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:
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
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 --all-databases
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
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
This
documentation
is for an
older version.
If you're
Introduced
5.0.19
This
documentation
is for an
older version.
If you're
mysqlcheck — A Table Maintenance Program
Format
Description
--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
--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
This
documentation
is for an
older version.
If you're
Introduced
5.0.10
5.0.23
This
documentation
is for an
older version.
If you're
mysqlcheck — A Table Maintenance Program
Format
Description
--version
Display version information and exit
•
Introduced
--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
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
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
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
Optimize the tables.
•
--password[=password], -p[password]
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
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, “EndUser 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 --all-databases
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, --create-options,
--disable-keys, --extended-insert, --lock-tables, --quick, and --set-charset. 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 --skip-compact).
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-a-number)
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.
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
For additional information about mysqldump, see Section 7.4, “Using mysqldump for Backups”.
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
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
This
documentation
is for an
older version.
If you're
Introduced
5.0.32
5.0.10
5.0.52
This
documentation
is for an
older version.
If you're
mysqldump — A Database Backup Program
Format
Description
--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
--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 --create-options
--disable-keys --extended-insert --lock-tables --quick --setcharset.
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
--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
--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
This
documentation
is for an
older version.
If you're
Introduced
5.0.13
This
documentation
is for an
older version.
If you're
mysqldump — A Database Backup Program
Format
Description
Introduced
--ssl-verify-server-cert
Verify server certificate Common Name value against host
name used when connecting to server
5.0.23
--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
•
5.0.15
--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
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
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-drop-table 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 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
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 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
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 --master-data.
•
--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). --skip-dump-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.
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
•
--fields-terminated-by=..., --fields-enclosed-by=..., --fields-optionallyenclosed-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 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
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 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 --lock-tables.
•
--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 --lock-tables
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.
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.
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
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, --locktables, --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.
•
--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.
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
•
--opt
This option is shorthand. It is the same as specifying --add-drop-table --add-locks --createoptions --disable-keys --extended-insert --lock-tables --quick --set-charset.
It should give you a fast dump operation and produce a dump file that can be reloaded into a MySQL
server quickly.
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, “EndUser 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 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.
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
•
--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.
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.
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 --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 --linesterminated-by options.
Column values are dumped using the binary character set and the --default-character-set
option is ignored. In effect, there is no character set conversion. If a table contains columns 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
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
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)
<field name="column_name"
xsi:nil="true" />
'' (empty string)
<field name="column_name"></field>
'NULL' (string value)
<field name="column_name">NULL</
field>
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:
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 --xml -u root world City
<?xml version="1.0"?>
<mysqldump xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<database name="world">
<table_structure name="City">
<field Field="ID" Type="int(11)" Null="NO" Key="PRI" Extra="auto_increment" />
<field Field="Name" Type="char(35)" Null="NO" Key="" Default="" Extra="" />
<field Field="CountryCode" Type="char(3)" Null="NO" Key="" Default="" Extra="" />
<field Field="District" Type="char(20)" Null="NO" Key="" Default="" Extra="" />
<field Field="Population" Type="int(11)" Null="NO" Key="" Default="0" Extra="" />
<key Table="City" Non_unique="0" Key_name="PRIMARY" Seq_in_index="1" Column_name="ID"
Collation="A" Cardinality="4079" Null="" Index_type="BTREE" Comment="" />
<options Name="City" Engine="MyISAM" Version="10" Row_format="Fixed" Rows="4079"
Avg_row_length="67" Data_length="273293" Max_data_length="18858823439613951"
Index_length="43008" Data_free="0" Auto_increment="4080"
Create_time="2007-03-31 01:47:01" Update_time="2007-03-31 01:47:02"
Collation="latin1_swedish_ci" Create_options="" Comment="" />
</table_structure>
<table_data name="City">
<row>
<field name="ID">1</field>
<field name="Name">Kabul</field>
<field name="CountryCode">AFG</field>
<field name="District">Kabol</field>
<field name="Population">1780000</field>
</row>
...
<row>
<field name="ID">4079</field>
<field name="Name">Rafah</field>
<field name="CountryCode">PSE</field>
<field name="District">Rafah</field>
<field name="Population">92020</field>
</row>
</table_data>
</database>
</mysqldump>
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:
shell> mysqldump db_name > backup-file.sql
You can load the dump file back into the server like this:
This
documentation
is for an
old